Merge branch 'main' into feat/eval-dispatch

fix(chat): harden IM search, card updates, and message workflows

.github/eval-allowlist.txt

@@ -0,0 +1,61 @@
+# /eval 自助触发允许名单
+#
+# 名单内的 GitHub 登录名可对【自己创建的 PR】触发 /eval 评测；
+# 对任意 PR 触发仍需仓库 write/maintain/admin 权限（维护者背书）。
+# 授权读取的始终是默认分支上的本文件，PR 无法修改自身授权。
+#
+# 变更本文件必须走 PR 评审。每行一个 GitHub login，# 开头为注释。
+
+aftersss
+notable-open
+EdgarWang0925
+ayunya
+yutongshe
+qingyang1014
+caiTriumph
+xlb1130
+Anonymity-0
+FuShu-Yang
+guimingyue
+AlwaysLee
+TaoJikun
+zengyoulingzyl-stack
+liyuan333
+huangyoo
+lifeihong
+nitonitori
+cywan1998
+gangwn
+junlonghuo2
+aqruan
+Freda0909
+ShawnWhite777
+PeterGuy326
+abucraft
+pengzhihan47-star
+rainyak8
+gongrongyun
+huangyuanzhuo-coder
+ybcstudy
+bigqy
+liwang-ai
+meng93
+wxianfeng
+Patrick-Star-CN
+rossluo28-hz
+dxy704330469
+gtezg30062
+Neige-Premaire
+zhuoyu20
+avicii-chen
+typefield
+Haofeng0705
+Huwenjiao
+liuzeyang
+maoqxxmm
+FloralTide
+lingyun9833
+dxb121
+C0922
+xiaoji121
+H3java

.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/') ||
@@ -147,6 +148,7 @@ jobs:
                 filename === '.github/actionlint.yaml' ||
                 filename.startsWith('scripts/') ||
                 filename.startsWith('verify/') ||
+                filename.startsWith('internal/helpers/') ||
                 filename.startsWith('internal/generator/') ||
                 filename.startsWith('internal/cli/schema') ||
                 filename.startsWith('internal/interfacesnapshot/') ||
@@ -432,6 +434,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
@@ -1365,29 +1371,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/eval-dispatch.yml

@@ -0,0 +1,139 @@
+name: PR Eval Dispatch
+
+# `/eval <products> [sha=<full-head-sha>] [cases=<ref>]` PR 评论 → 触发内网评测流水线，报告由内网 bot 回贴。
+# 本 workflow 只在默认分支上下文运行，不 checkout、不执行 PR 代码。
+# 审核 SHA 规则：评测他人 PR 必须显式携带 sha=（审阅背书凭据，验证
+# 其恰为当前 open head）；评测自己创建的 PR 可省略，自动钉住派发时刻
+# 的当前 head（作者自背书，无第三方偷换窗口）；内网 CI 另以
+# FETCH_HEAD 校验兜底派发后的变更。
+# 授权两级：仓库 write/maintain/admin 可派发任意 PR；默认分支
+# .github/eval-allowlist.txt 名单内的用户仅可派发自己创建的 PR。
+# 触发通道与凭证全部经 secrets 注入，文件内不出现任何内网信息。
+
+on:
+  issue_comment:
+    types:
+      - created
+
+permissions: {}
+
+concurrency:
+  group: eval-dispatch-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  dispatch:
+    name: Dispatch internal evaluation
+    if: >-
+      github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/eval')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: read
+    steps:
+      - name: Check out default branch tooling
+        uses: actions/checkout@v4
+
+      - name: Verify commenter dispatch authorization
+        env:
+          GH_TOKEN: ${{ github.token }}
+          COMMENTER: ${{ github.event.comment.user.login }}
+          PR_AUTHOR: ${{ github.event.issue.user.login }}
+          EVAL_ALLOWLIST_PATH: .github/eval-allowlist.txt
+        run: |
+          # 不用 --fail：非协作者查权限返回 404 错误体，交由 guard 走名单分支；硬网络错误降级为空对象同样 fail-closed
+          permission_json="$(curl --silent --show-error \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/collaborators/${COMMENTER}/permission")" || permission_json='{}'
+          printf '%s' "$permission_json" | python3 scripts/ci/eval_dispatch_guard.py permission
+
+      - name: Parse /eval command
+        id: parse
+        continue-on-error: true
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: python3 scripts/ci/eval_comment_parse.py
+
+      - name: Reply usage on parse failure
+        if: steps.parse.outcome == 'failure'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          PARSE_ERROR: ${{ steps.parse.outputs.error }}
+        run: |
+          body="❌ /eval 命令解析失败：${PARSE_ERROR}"
+          jq -n --arg body "$body" '{body: $body}' | curl --fail --silent --show-error \
+            -X POST \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            --data @- \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null
+          exit 1
+
+      - name: Verify reviewed PR head
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          EXPECTED_PR_NUMBER: ${{ github.event.issue.number }}
+          REVIEWED_SHA: ${{ steps.parse.outputs.reviewed_sha }}
+          COMMENTER: ${{ github.event.comment.user.login }}
+        run: |
+          pr_json="$(curl --fail --silent --show-error \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}")"
+          printf '%s' "$pr_json" \
+            | python3 scripts/ci/eval_dispatch_guard.py head \
+            >> "$GITHUB_OUTPUT"
+
+      - name: Trigger internal evaluation pipeline
+        env:
+          EVAL_TRIGGER_TOKEN: ${{ secrets.EVAL_TRIGGER_TOKEN }}
+          EVAL_TRIGGER_URL: ${{ secrets.EVAL_TRIGGER_URL }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          PRODUCTS: ${{ steps.parse.outputs.products }}
+          CASES_REF: ${{ steps.parse.outputs.cases_ref }}
+        run: |
+          if [ -z "$EVAL_TRIGGER_TOKEN" ] || [ -z "$EVAL_TRIGGER_URL" ]; then
+            echo "EVAL_TRIGGER_URL / EVAL_TRIGGER_TOKEN not configured; cannot dispatch." >&2
+            exit 1
+          fi
+          jq -n \
+            --arg pr "$PR_NUMBER" \
+            --arg sha "$PR_HEAD_SHA" \
+            --arg products "$PRODUCTS" \
+            --arg cases "$CASES_REF" \
+            '{branch: "main", params: {pr_number: $pr, pr_head_sha: $sha, products: $products, cases_ref: $cases}}' \
+          | curl --fail --silent --show-error \
+            -X POST \
+            -H "private-token: ${EVAL_TRIGGER_TOKEN}" \
+            -H "Content-Type: application/json" \
+            --data @- \
+            "$EVAL_TRIGGER_URL"
+          echo "Internal evaluation dispatched."
+
+      - name: Acknowledge on PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.issue.number }}
+          PR_HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          PRODUCTS: ${{ steps.parse.outputs.products }}
+          CASES_REF: ${{ steps.parse.outputs.cases_ref }}
+        run: |
+          cases_note=""
+          if [ -n "$CASES_REF" ]; then
+            cases_note="，用例版本 \`${CASES_REF}\`"
+          fi
+          body="🛰️ /eval 已受理：产品集 \`${PRODUCTS}\`${cases_note}，评测对象 \`${PR_HEAD_SHA}\`。内网评测流水线运行结束后将由 bot 回贴报告（首行为基线对比头条）。"
+          jq -n --arg body "$body" '{body: $body}' | curl --fail --silent --show-error \
+            -X POST \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            --data @- \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${PR_NUMBER}/comments" > /dev/null

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

CHANGELOG.md

@@ -6,23 +6,156 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+### Added
+
+- **Aitable workflow execution and history** — adds `dws aitable workflow run` for confirmed asynchronous execution of scheduled or record-triggered workflows, plus `dws aitable workflow history` for status-, time-, and page-filtered execution records. The commands map directly to `aitable/run_workflow` and `aitable/get_flow_record_list`, validate trigger-specific arguments locally, and document the `executionId` / `instanceId` correlation.
+- **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.
+
+### Fixed
+
+- **Machine-readable export and download receipts** — `dws doc export`,
+  `dws drive download`, and `dws drive download --version` now keep progress
+  logs on stderr under `--format json` and emit one JSON result on stdout after
+  a successful local write. The result includes the saved path and byte size;
+  document exports additionally report the node, requested format, job/task
+  ID, and final status.
+### Changed
+
+- **Minutes `permission apply --policy` type** — `--policy` is now declared as
+  an `int` flag and its required check uses `Flags().Changed`, matching the
+  numeric-parameter convention. `--help` reports `int` instead of `string`;
+  accepted values (2/3/4) and gateway behavior are unchanged.
+- **Minutes skill references** — document `permission apply` in both Minutes
+  skill references: list it in the command trees, describe its policy values and
+  how it differs from `permission add`, and add its intent routing.
+
+## [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
 
-- **`dws recovery` CLI** — keeps a visible Deprecated compatibility stub for
-  plan/execute/finalize that returns an explicit “不再支持” notice. The
-  `internal/recovery` package is removed; Skills must not teach this path.
-  Transport errors keep generic retry/auth guidance without pointing callers
-  at recovery.
+- **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.3` baseline.
-It includes reviewed document shortcuts and chat reply mentions, together with
-the v1.0.57 beta-line command-contract, document, chat, OA, Wiki, compatibility,
-and CI reliability improvements validated through the prerelease channel.
+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.3** — publishes the validated prerelease baseline as
-  the stable `v1.0.57` release without adding post-beta product changes.
+- **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
 
@@ -100,6 +233,7 @@ and compatibility and CI reliability fixes.
 ### 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
 
@@ -112,6 +246,7 @@ and compatibility and CI reliability fixes.
 
 ### 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.

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.57-beta.3"
+  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.57-beta.3/dws-darwin-arm64.tar.gz"
-      sha256 "b1ea300a76654751ea33540d8a244b0c81b5df3947786980f95a5a19362a097a"
+      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.57-beta.3/dws-darwin-amd64.tar.gz"
-      sha256 "68b5f6e38bec994fa4db4bef5db1629c7bce799bb9837c447008c3325fc886e3"
+      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.57-beta.3/dws-linux-arm64.tar.gz"
-      sha256 "350e74f1a2611975e476e113e50264975a98185c11ee889a83d9480c0f10181b"
+      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.57-beta.3/dws-linux-amd64.tar.gz"
-      sha256 "2c27a9a884650a7a60545d9447f1b966667216e94c333ebf9d69f9b2ead96e04"
+      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.57-beta.3/dws-skills.zip"
-    sha256 "abaa8feaa3c61fff048cfd1139e1fc5b91c329eb666d2eb852797a3f5c4c0cac"
+    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.56"
+  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.56/dws-darwin-arm64.tar.gz"
-      sha256 "5c6003fe484aa36cc00820a574186652467b9d075f19c159cf807e57590256ba"
+      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.56/dws-darwin-amd64.tar.gz"
-      sha256 "969b005a10682c2a1a828fa112165b5b0cd8ceeed8d22110ef7f39402cc36804"
+      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.56/dws-linux-arm64.tar.gz"
-      sha256 "530c5ea7ddc7de320d9c2471fbd33752a723d00c9665f49321c7580e8392c756"
+      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.56/dws-linux-amd64.tar.gz"
-      sha256 "675fa42727ac9a549c6710b82e1980cd0f795363d71d5116a4e69771b7c5470e"
+      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.56/dws-skills.zip"
-    sha256 "3d57794e4660a089209ce3962571d16ca0d46141e973c9993257a301cce0e097"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.57/dws-skills.zip"
+    sha256 "0c9667209cf30761427a8f9348149cbbf1e397aa3c25587e99f205bc7525e101"
   end
 
   def install

Makefile

@@ -24,13 +24,13 @@ 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"
@@ -89,6 +89,7 @@ policy: test-auth-legacy-compat
 	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
 	@$(POLICY_ENV) ./scripts/policy/check-skill-context-budget.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
@@ -102,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
@@ -120,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
@@ -151,9 +169,13 @@ generate-schema:
 	@set -e; \
 	concepts_guard=$$(mktemp); \
 	concepts_schema_guard=$$(mktemp); \
-	trap 'rm -rf "$$concepts_guard" "$$concepts_schema_guard"' EXIT HUP INT TERM; \
+	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 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; \
 	rm -rf internal/cli/schema_agent_metadata internal/cli/schema_agent_metadata_audit.json; \
 	rm -f internal/cli/schema_meta_index.json; \
@@ -169,6 +191,14 @@ generate-schema:
 		printf '%s\n' 'generation modified reviewed input internal/cli/param_concepts.schema.json' >&2; \
 		exit 1; \
 	}; \
+	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/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; \
+	}; \
 	if [ -e internal/cli/schema_hints ]; then \
 		printf '%s\n' 'retired schema_hints/ must not reappear after generation' >&2; \
 		exit 1; \

README.md

@@ -471,7 +471,7 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
 <details>
 <summary><strong>Personal Event Subscription</strong> — real-time DingTalk messages for event-driven agents</summary>
 
-`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, and group title/disband lifecycle events.
+`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, and six OA approval task/instance events.
 
 The default `ndjson`, `json`, and `pretty` output preserves the transport envelope (`type`, `event_type`, string `data`, and `headers`) for existing scripts; `compact` retains its existing processor. Add `--flatten` to emit the stable top-level business fields used by Agent workflows. `--format` controls JSON serialization; `--flatten` controls the data structure and cannot be combined with `-f raw` or `--debug-raw-events`.
 
@@ -481,28 +481,33 @@ For an event-focused installation, use the official convenience installer:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh
+
+# Or install the standalone multi skill from an existing dws installation
+dws skill setup --mode multi -s event
 ```
 
 ```bash
 # Inspect the public personal event catalog and schema
 dws event list
 dws event schema user_im_message_receive_o2o --flatten
+dws event list --category oa
+dws event schema user_oa_approval_task_created --flatten
 
 # Listen for messages that mention the current user
-dws event consume user_im_message_receive_at --flatten -f ndjson
+dws event +listen-im --kind at-me -f ndjson
 
-# Listen for one-to-one messages with a specified user
-dws event consume user_im_message_receive_o2o --user <userId> --flatten -f ndjson
+# Listen for messages from a specified sender
+dws event +listen-im --kind sender --user <userId> -f ndjson
 
 # Listen by openDingtalkId (external contact, bot, or cross-organization identity)
-dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> --flatten -f ndjson
+dws event +listen-im --kind sender --open-dingtalk-id <openDingtalkId> -f ndjson
 
 # Listen for messages in a specified group
-dws event consume user_im_message_receive_group --group <openConversationId> --flatten -f ndjson
+dws event +listen-im --kind group --chat-id <openConversationId> -f ndjson
 
 # Listen for all one-to-one or all group messages
-dws event consume user_im_message_receive_o2o_all --flatten -f ndjson
-dws event consume user_im_message_receive_group_all --flatten -f ndjson
+dws event +listen-im --kind all-direct -f ndjson
+dws event +listen-im --kind all-group -f ndjson
 
 # Listen for a specified group's title changes, member changes, or disband event
 dws event consume user_im_group_updated --group <openConversationId> --flatten -f ndjson
@@ -510,14 +515,19 @@ dws event consume user_im_group_member_added --group <openConversationId> --flat
 dws event consume user_im_group_member_exited --group <openConversationId> --flatten -f ndjson
 dws event consume user_im_group_disbanded --group <openConversationId> --flatten -f ndjson
 
-# Listen for multiple events for the same user in one process
+# Listen for messages, reads, and recalls from the same sender in one process
+dws event +listen-im --kind sender --user <userId> \
+  --events message,read,recall -f ndjson
+
+# Listen for all six public OA approval events in one process
 dws event consume \
-  user_im_message_receive_o2o \
-  user_im_message_read_o2o \
-  user_im_message_recall_o2o \
-  --user <userId> \
-  --flatten \
-  -f ndjson
+  user_oa_approval_task_created \
+  user_oa_approval_task_finished \
+  user_oa_approval_task_redirected \
+  user_oa_approval_instance_started \
+  user_oa_approval_instance_terminated \
+  user_oa_approval_instance_finished \
+  --flatten -f ndjson
 
 # Inspect local consumers and cancel a subscription
 dws event status
@@ -536,7 +546,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-misc/references/event.md` for the Agent workflow and supported event parameters.
+See `skills/multi/dingtalk-event/SKILL.md` for the Agent workflow and supported event parameters.
 
 </details>
 

README_zh.md

@@ -465,7 +465,7 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 <details>
 <summary><strong>个人事件订阅</strong> — 实时接收钉钉消息，驱动事件触发的 Agent</summary>
 
-`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应，以及群标题变更和群解散事件。
+`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期，以及六个 OA 审批任务/实例事件。
 
 默认 `ndjson`、`json`、`pretty` 输出保留兼容 transport envelope（`type`、`event_type`、字符串 `data`、`headers`），`compact` 继续沿用原 processor。Agent 或新脚本显式加 `--flatten` 后，输出稳定的顶层业务字段。`--format` 控制 JSON 序列化，`--flatten` 控制数据结构，且不能与 `-f raw` 或 `--debug-raw-events` 同时使用。
 
@@ -475,28 +475,33 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh
+
+# 或在已有 dws 环境中安装独立的 multi skill
+dws skill setup --mode multi -s event
 ```
 
 ```bash
 # 查看公开个人事件目录和 schema
 dws event list
 dws event schema user_im_message_receive_o2o --flatten
+dws event list --category oa
+dws event schema user_oa_approval_task_created --flatten
 
 # 监听当前用户被 @ 的消息
-dws event consume user_im_message_receive_at --flatten -f ndjson
+dws event +listen-im --kind at-me -f ndjson
 
-# 监听与指定用户的单聊消息
-dws event consume user_im_message_receive_o2o --user <userId> --flatten -f ndjson
+# 监听指定发送人的消息
+dws event +listen-im --kind sender --user <userId> -f ndjson
 
 # 使用 openDingtalkId 监听外部联系人、机器人或跨组织身份
-dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> --flatten -f ndjson
+dws event +listen-im --kind sender --open-dingtalk-id <openDingtalkId> -f ndjson
 
 # 监听指定群的消息
-dws event consume user_im_message_receive_group --group <openConversationId> --flatten -f ndjson
+dws event +listen-im --kind group --chat-id <openConversationId> -f ndjson
 
 # 监听所有单聊或所有群消息
-dws event consume user_im_message_receive_o2o_all --flatten -f ndjson
-dws event consume user_im_message_receive_group_all --flatten -f ndjson
+dws event +listen-im --kind all-direct -f ndjson
+dws event +listen-im --kind all-group -f ndjson
 
 # 监听指定群标题变更、成员进退群或群解散
 dws event consume user_im_group_updated --group <openConversationId> --flatten -f ndjson
@@ -504,14 +509,19 @@ dws event consume user_im_group_member_added --group <openConversationId> --flat
 dws event consume user_im_group_member_exited --group <openConversationId> --flatten -f ndjson
 dws event consume user_im_group_disbanded --group <openConversationId> --flatten -f ndjson
 
-# 一个进程监听同一用户的多个事件
+# 一个进程监听同一发送人的消息、已读和撤回
+dws event +listen-im --kind sender --user <userId> \
+  --events message,read,recall -f ndjson
+
+# 一个进程监听全部六个公开 OA 审批事件
 dws event consume \
-  user_im_message_receive_o2o \
-  user_im_message_read_o2o \
-  user_im_message_recall_o2o \
-  --user <userId> \
-  --flatten \
-  -f ndjson
+  user_oa_approval_task_created \
+  user_oa_approval_task_finished \
+  user_oa_approval_task_redirected \
+  user_oa_approval_instance_started \
+  user_oa_approval_instance_terminated \
+  user_oa_approval_instance_finished \
+  --flatten -f ndjson
 
 # 查看本地 consume，并取消指定订阅
 dws event status
@@ -530,7 +540,7 @@ dws event stop <subscribe_id>
 | 状态可观测 | `status` 同时显示服务端订阅、personal bus 和本地 consumers |
 | 跨平台 | macOS/Linux 使用 Unix Socket，Windows 使用 Named Pipe |
 
-Agent 工作流和事件参数详见 `skills/multi/dingtalk-misc/references/event.md`。
+Agent 工作流和事件参数详见 `skills/multi/dingtalk-event/SKILL.md`。
 
 </details>
 

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/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/shortcut-lark-alignment.md

@@ -70,16 +70,17 @@
 
 > 已落地：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（5）
+### im → chat（7）
 
 | lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
 |---|---|---|
-| `+chat-list` ✅ | read | **已建 smart `chat +chat-list`**：`list_all_conversations` + 默认仅群聊 + `--types group/p2p` 当前页过滤 + `--exclude-muted` + page-size/page-token 别名 + openConversationId/name/conversationType 投影。剩余未做：sort/sort-type、bot 身份 p2p 剥离（DWS 无对应身份模型） |
-| `+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）
 

docs/shortcut-public-catalog.json

@@ -1,209 +1,926 @@
 {
-  "generated_at": "2026-08-05T22:43:52.497190",
-  "count": 294,
+  "generated_at": "2026-08-06T21:08:26.697858",
+  "count": 357,
   "results": [
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+advperm-disable",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "关闭高级权限会使自定义角色失效，显式发布高风险事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+advperm-enable",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "开启 Base 高级权限总开关的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+attachment-put",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "完整执行 prepare、HTTP PUT、attachment cell 覆盖和读回验证；空写回包只有最终附件可证明时成功。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+attachment-remove",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "清空或按文件名移除附件；若读回缺剩余 fileToken，会在写前明确停止而不破坏其他附件。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+attachment-upload",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "申请附件 OSS 直传地址和 fileToken；只负责上传准备，不伪造文件已上传。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-bootstrap",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "声明式创建 Base、表和字段，字段自动分片，逐层读回验证并报告部分副作用。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-copy",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一完整复制与仅结构复制意图，并把目标目录映射为可执行参数。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除整个 Base 的兼容入口，显式发布高风险确认事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+base-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "保留 Base 目录读取的 Shortcut 兼容入口；底层 leaf 已提供同等读取能力。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-get-primary-doc-id",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "已知 base/table/record 时读取主键文档 dentryUuid 的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+base-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "把最近访问 Base 响应稳定投影为 baseId/baseName 列表，作为未知 baseId 时的浏览入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-schema-snapshot",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "完整读取 Base、tables、fields、views，逐层区分合法空集合与缺失响应契约。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+base-search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按名称关键词定位 Base，并稳定投影可继续操作的 baseId/baseName。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+base-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "更新 Base 名称和备注的一对一写入，复用统一确认门。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+chart-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "删除图表及布局项，显式发布不可逆高风险事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+chart-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取指定图表完整配置的一对一入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+chart-share-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取图表分享配置的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+chart-share-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一开启、关闭和设置图表分享类型。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+chart-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一更新图表配置或布局，并要求显式 config 输入。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+chart-widgets-example",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "返回所有图表类型的 widget config 示例，供构造合法图表配置。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+dashboard-arrange",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "触发服务端智能布局重排并保留统一写入确认。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+dashboard-config-example",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "返回 dashboard config 的服务端结构示例，供后续写入构造合法参数。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+dashboard-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "级联删除仪表盘及图表，显式发布不可逆高风险事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+dashboard-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "读取仪表盘详情及 charts summary，作为图表操作导航入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+dashboard-share-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取仪表盘分享配置的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+dashboard-share-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一开启、关闭和设置仪表盘分享类型。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+dashboard-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "更新仪表盘配置的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+export-data",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "统一创建导出任务与按 taskId 续等，直到得到可下载的导出结果或明确失败。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+field-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除字段的一对一入口，显式发布数据丢失风险。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+field-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "批量获取字段完整类型配置，避免仅返回名称的损失投影。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+field-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一字段名称、类型配置和 AI 配置的增量更新输入。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+find-record",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "将关键词查询投影为稳定的 recordId/cells 结果，适合先定位再写入。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+form-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除表单视图的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+form-field-hide",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "用隐藏/显示布尔语义切换表单字段可见性。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+form-field-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "列出表单当前字段顺序、可见性、必填和描述配置。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+form-field-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一更新表单字段必填状态与描述。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+form-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "从表的视图中稳定筛出表单视图并返回表单目录。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+form-share-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取当前视图分享表单配置的一对一入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+form-share-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一开启或关闭指定视图的分享表单。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+form-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一更新表单标题和描述。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+import-data",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一将已上传文件导入新表或追加到已有表的目标语义。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+import-upload",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "申请导入 OSS 直传地址和 importId；只负责上传准备，不伪造导入完成。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+list-tables",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "把 Base 目录稳定投影为 tableId/tableName 列表，隐藏非表节点。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-bulk-patch",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先完整解析显式选择范围和 max-matches，再将同一 cells patch 自动分片写入并逐条读回验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "自动按 100 条分片删除；每批仅在所有目标 recordId 读回均不存在时成功，失败提供 nextOffset。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+record-history-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "按 recordId 查询变更历史的一对一只读入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-primary-doc-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "以幂等意图为 primaryDoc 字段创建关联文档。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-primary-doc-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取记录主键文档 nodeId 的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+record-query",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一 ID、筛选、关键词和分页查询，并投影稳定的 records/count/cursor 结果。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+record-query-empty",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "扫描记录并按用户字段为空的语义过滤空行，避免调用方手工判断 cells。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+record-share-links",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "对超过 20 条 recordId 去重分片调用并合并分享链接及逐批结果。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+record-share-url",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "将最多 20 个 recordId 统一映射为可分享链接列表。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "自动按 100 条分片更新并逐条读回验证；失败返回可续跑的 nextOffset。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-upsert",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按 recordId 拆分 create/update，自动按 100 条分片；创建必须返回新 recordId，全部结果读回验证。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+record-upsert-by-key",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "先按唯一 fieldId/value 完整查询，0 条创建、1 条更新、2 条以上停止，并读回验证最终 cells。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+resolve-base",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按名称搜索并要求唯一匹配，0 或多结果时显式失败而不猜 baseId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+resolve-table",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "在 Base 内按名称要求唯一匹配，0 或多结果时显式失败而不猜 tableId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+role-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一角色名称、成员与权限配置的创建输入。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+role-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除自定义角色的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+role-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取单个角色完整权限配置的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+role-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "列出 Base 全部自定义角色的一对一入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+role-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按 PATCH 语义增量更新角色配置，未提供字段保持不变。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+section-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "在 Base 目录树创建用于组织表和仪表盘的文件夹。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+section-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除目录文件夹的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+section-list-empty",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "扫描目录树并只返回没有子节点的空文件夹。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+section-list-nodes",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "列出当前版本全部 nsheet 节点，提供表、仪表盘和文件夹统一目录。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+section-move-node",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一移动任意 nsheet 节点到文件夹或 Base 根目录，并可指定位置。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+section-rename",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "重命名目录文件夹的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+section-reorder",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按当前父目录语义调整文件夹展示顺序。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+table-copy",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "在没有服务端 table-copy task 的情况下，本地重建安全字段、映射 fieldId，并可分片复制及读回验证全部记录。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+table-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除数据表的一对一入口，显式发布高风险确认事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+table-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "批量读取表级信息、字段和视图目录，为后续 Schema 与记录操作提供 ID。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+table-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "统一表名、备注和行命名规则的 PATCH 风格更新。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+template-search",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "按名称关键词搜索 AI 表格模板并返回可用于创建的 templateId。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+url-resolve",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "严格解析 alidocs AI 表格 URL 的 base/table/view/record ID，并可通过最深层只读接口验证目标存在。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-delete",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "不可逆删除视图的一对一入口，显式发布高风险确认事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-duplicate",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "复制现有视图配置并生成新视图的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "aitable",
       "command": "+view-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "读取视图完整列顺序、筛选、排序和分组配置。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+view-get-frozen-cols",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取 Grid 视图冻结列数的一对一入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+view-get-lock",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取视图锁定状态的一对一入口。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "aitable",
       "command": "+view-get-row-height",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取视图行高像素值的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-lock",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "用默认锁定与 --off 解锁统一表达视图锁状态切换。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-preset-apply",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "按精确名称幂等创建或更新视图预设，拒绝同名歧义和类型漂移，并读回校验 config。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-set-fill-color-rule",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "以全量覆盖语义设置条件填色规则，并用空数组明确清空。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-set-frozen-cols",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "设置冻结列数并以 0 明确表达取消冻结。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-set-row-height",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "把行高限制为服务支持的 32/56/88/128 像素档位后写入。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+view-update",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "统一视图名称、描述、可见列、筛选、排序和分组配置更新。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+workflow-deploy",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "primary_smart",
+      "semantic_delta": "创建或更新完整 workflow-dsl/v1，强制 valid=true/flowId，并可启用后从 list 验证 RUNNING。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+workflow-disable",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "禁用工作流会影响业务自动化，显式发布高风险确认事实。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+workflow-enable",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "启用指定自动化工作流的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+workflow-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "读取单个自动化工作流详情的一对一入口。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "aitable",
+      "command": "+workflow-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "schema_leaf",
+      "semantic_delta": "分页列出 Base 自动化工作流的一对一入口。",
+      "availability": "available"
     },
     {
       "suite": "read",
@@ -1964,7 +2681,7 @@
       "risk": "write",
       "status": "reviewed_available",
       "disposition": "primary_smart",
-      "semantic_delta": "一体化创建会话、上传、确认转换并轮询导入结果。",
+      "semantic_delta": "一体化创建会话、上传、确认转换并轮询导入结果；白名单外格式自动改走文件上传原样入库（fallback=upload、converted=false）。",
       "availability": "available"
     },
     {

docs/skill-content-framework.md

@@ -101,5 +101,5 @@ skills/mono/
 ## 7. 变更流程
 
 1. 改 / 增内容 → 更新 `skills/content-qa/mono-multi-coverage.yaml`（coverage 或 omit）  
-2. 跑 `make skill-mono-multi-content`（或 `make policy`）  
+2. 跑 `make skill-mono-multi-content`（该独立门禁不包含在默认 `make policy` 中）
 3. 失败则修内容或更新 reviewed omit（disposition + 原因），**禁止**用安装默认值绕过  

docs/skill-mono-multi-qa.md

@@ -2,7 +2,7 @@
 
 > 对照基准：`skills/mono`（单 skill）。被测主体：`skills/multi`。  
 > 机读合同：`skills/content-qa/mono-multi-coverage.yaml`。  
-> 执行：`make skill-mono-multi-content`（已挂入 `make policy`）。
+> 执行：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）。
 
 ## 1. 质检矩阵
 
@@ -11,7 +11,8 @@
 | **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` |
+| **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 成对测试。
 
@@ -37,6 +38,16 @@ 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；**不**改安装/升级默认。

docs/skill-wukong-align-plan.md

@@ -4,7 +4,7 @@
 > 合同短文：[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`）
+> 门禁：`make skill-mono-multi-content`（独立门禁；默认 `make policy` 按设计不包含该检查）
 >
 > 撰写 / 收窄 / 质检增补 / 执行：2026-08-05  
 > 工作树：`/Users/john/GolandProjects/open-source/dws-multi-skill-align`  

internal/app/chat_message_receipt_action_contract_test.go

@@ -0,0 +1,84 @@
+// 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 (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
+)
+
+func TestCrossPlatformCoverageChatMessageReceiptActionsBindToRunnableCommands(t *testing.T) {
+	testCases := []struct {
+		name    string
+		payload map[string]any
+	}{
+		{
+			name: "send receipt awaiting status",
+			payload: chatmsg.ProjectMessageSendReceipt(map[string]any{
+				"openTaskId": "task-pending",
+			}),
+		},
+		{
+			name: "send receipt ready for message actions",
+			payload: chatmsg.ProjectMessageSendReceipt(map[string]any{
+				"openTaskId":         "task-ready",
+				"openMessageId":      "message-ready",
+				"openConversationId": "conversation-ready",
+			}),
+		},
+		{
+			name: "send status awaiting message reference",
+			payload: chatmsg.ProjectMessageSendStatus(map[string]any{
+				"status": "PENDING",
+			}, "task-pending"),
+		},
+		{
+			name: "send status ready for message actions",
+			payload: chatmsg.ProjectMessageSendStatus(map[string]any{
+				"openTaskId":         "task-ready",
+				"openMessageId":      "message-ready",
+				"openConversationId": "conversation-ready",
+				"status":             "SUCCESS",
+			}, "task-ready"),
+		},
+	}
+
+	root := NewRootCommand()
+	for _, testCase := range testCases {
+		t.Run(testCase.name, func(t *testing.T) {
+			actions, ok := testCase.payload["nextActions"].([]map[string]any)
+			if !ok || len(actions) == 0 {
+				t.Fatalf("nextActions = %#v, want non-empty []map[string]any", testCase.payload["nextActions"])
+			}
+
+			for index, action := range actions {
+				cliPath, ok := action["cliPath"].(string)
+				if !ok || strings.TrimSpace(cliPath) == "" {
+					t.Fatalf("nextActions[%d].cliPath = %#v, want non-empty string", index, action["cliPath"])
+				}
+
+				command, remaining, err := root.Find(strings.Fields(cliPath))
+				if err != nil {
+					t.Fatalf("nextActions[%d].cliPath %q does not bind: %v", index, cliPath, err)
+				}
+				if command == nil || len(remaining) != 0 || !command.Runnable() {
+					t.Fatalf("nextActions[%d].cliPath %q resolved to command=%v remaining=%v runnable=%v", index, cliPath, command, remaining, command != nil && command.Runnable())
+				}
+
+				arguments, ok := action["arguments"].(map[string]any)
+				if !ok {
+					t.Fatalf("nextActions[%d].arguments = %#v, want map[string]any", index, action["arguments"])
+				}
+				for name := range arguments {
+					if command.Flags().Lookup(name) == nil && command.InheritedFlags().Lookup(name) == nil {
+						t.Errorf("nextActions[%d] argument %q is not a flag of runnable command %q", index, name, cliPath)
+					}
+				}
+			}
+		})
+	}
+}

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

@@ -80,12 +80,12 @@ func newEventCommand() *cobra.Command {
 	contract.RegisterProductDecl(contract.ProductDecl{
 		ID: "event",
 		Selection: contract.ProductSelectionDecl{
-			AgentSummary: "订阅/消费个人消息、动作与群生命周期事件，并管理订阅生命周期",
+			AgentSummary: "实时监听当前用户相关的个人 IM 与 OA 审批事件，并管理订阅生命周期",
 			UseWhen: []string{
-				"需要实时监听个人消息接收、全量消息、已读、撤回、表情回应或群生命周期事件，或管理个人事件订阅生命周期",
+				"需要实时监听未来发生的个人消息、消息动作、群生命周期或 OA 审批任务/实例事件，或管理个人事件订阅生命周期",
 			},
 			AvoidWhen: []string{
-				"查历史聊天或主动发消息分别用 chat 查询/发送命令",
+				"查历史聊天或主动发消息用 chat；查询或处理审批实例/任务用 oa；配置开放平台应用事件回调用 dev app event",
 			},
 		},
 	})
@@ -333,7 +333,7 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 	f.BoolVar(&force, "force", false,
 		"仅 --foreground 模式生效：跳过单实例锁 (慎用：会让云事件被随机切分)")
 	f.BoolVar(&dryRun, "dry-run", false,
-		"仅打印解析后的配置，不连接 bus / 云端")
+		"仅打印解析后的配置；不创建订阅、不连接 bus；复用 --subscribe-id 时会只读查询控制面")
 	f.BoolVar(&foreground, "foreground", false,
 		"当前进程直接跑 bus 服务、不 fork、不打印事件（给 systemd/k8s 托管用）；读事件不要用它")
 	f.StringVar(&personalOpts.SubscribeID, "subscribe-id", "",
@@ -398,22 +398,21 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 				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",
+				AgentSummary: "消费 OA、群生命周期或需要底层控制的个人事件流；Agent 通常使用 --flatten 输出 NDJSON",
 				UseWhen: []string{
-					"需要实时监听 @我、指定单聊、指定群或指定发送人的后续消息事件",
-					"用户明确要求监听当前身份的所有单聊或所有群消息",
-					"需要监听指定单聊或群聊中的消息已读、撤回或表情回应事件",
+					"需要监听六个公开 OA 审批任务/实例 EventKey 中的一个或多个事件",
 					"需要监听指定群的标题变更、成员进退群或群解散事件",
-					"监听机器人、外部联系人等以 openDingtalkId 标识的单聊目标",
-					"同一目标、同一过滤条件需要同时监听多个兼容事件",
+					"用户显式给出原始 EventKey、Filter DSL、subscribe_id，要求原始 transport envelope，或需要普通 IM facade 不提供的高级多事件控制",
 				},
 				AvoidWhen: []string{
+					"普通 @我、指定发送人/群、全部单聊/群聊及 message/reaction/read/recall 监听优先使用 event +listen-im",
 					"只查历史聊天记录时用 chat 查询命令",
+					"查询、同意、拒绝、转交、撤销或发起审批时用 oa；配置应用事件回调时用 dev app event",
 					"只看事件目录/字段时用 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",
+					"dws event consume user_oa_approval_task_created user_oa_approval_instance_finished --flatten --duration 10m --format ndjson",
+					"dws event consume user_im_group_member_added --group cid-example --flatten --max-events 1 --format ndjson",
 				},
 			},
 		},

internal/app/event_listen_im.go

@@ -71,7 +71,7 @@ func newEventListenIMCommand() *cobra.Command {
 		Use:   "+listen-im",
 		Short: "按 IM 意图解析目标并监听一个或多个个人消息事件",
 		Long: "把 @我、指定发送人、指定群、全部单聊或全部群聊等用户意图确定性编译为个人 EventKey，" +
-			"自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期。",
+			"自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期；本命令只处理 IM，不接收 OA 审批事件。",
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(c *cobra.Command, _ []string) error {
@@ -143,12 +143,12 @@ func newEventListenIMCommand() *cobra.Command {
 				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 消息事件",
+				AgentSummary: "按 @我、发送人、群或全量范围监听普通 IM message/reaction/read/recall 事件",
 				UseWhen: []string{
 					"已知要监听 @我、指定发送人、指定群、全部单聊或全部群聊的 message/reaction/read/recall 事件时使用；姓名用 --user-query、群名用 --chat-query，CLI 会唯一解析目标并把多个兼容事件合并到一个消费生命周期。",
 				},
 				AvoidWhen: []string{
-					"需要群标题/成员/解散等生命周期事件、显式 EventKey、复用 subscribe_id、Filter DSL、原始 transport envelope 或其它底层 consume 控制时使用 event consume；只查历史消息时使用 chat 查询入口",
+					"OA 审批事件、群标题/成员/解散等生命周期事件、显式 EventKey、复用 subscribe_id、Filter DSL、原始 transport envelope 或其它底层控制使用 event consume；只查历史消息使用 chat 查询入口",
 				},
 				Examples: []string{
 					"dws event +listen-im --kind at-me --max-events 1",

internal/app/event_personal_attempts_test.go

@@ -152,8 +152,8 @@ func TestCrossPlatformCoveragePersonalSubscriptionProtectionCoversAllPublicEvent
 		}
 	}
 
-	if publicCount != 16 {
-		t.Fatalf("public personal events = %d, want 16", publicCount)
+	if publicCount != 22 {
+		t.Fatalf("public personal events = %d, want 22 (16 IM + 6 OA)", publicCount)
 	}
 	for _, ruleType := range []string{"at", "all", "singleChat", "sender", "group"} {
 		if !ruleTypes[ruleType] {

internal/app/event_personal_command.go

@@ -26,6 +26,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"sync"
 	"text/tabwriter"
 	"time"
 
@@ -201,12 +202,15 @@ func newEventSchemaCommand() *cobra.Command {
 			},
 			Selection: contract.SelectionSpec{
 				AgentSummary: "查询指定个人事件码的输出字段结构；Agent 应查询 --flatten 模式",
-				UseWhen:      []string{"已知任一公开个人 IM event_key，消费前需要理解输出字段或保守 payload 契约"},
+				UseWhen:      []string{"已知任一公开个人 IM 或 OA event_key，消费前需要理解 --flatten 输出字段或 payload 契约"},
 				AvoidWhen: []string{
 					"查询 CLI 命令参数契约时用顶层 dws schema",
 					"要实际收事件时用 event consume",
 				},
-				Examples: []string{"dws event schema user_im_message_receive_at --flatten --format json"},
+				Examples: []string{
+					"dws event schema user_im_message_receive_at --flatten --format json",
+					"dws event schema user_oa_approval_task_created --flatten --format json",
+				},
 			},
 		},
 	})
@@ -262,6 +266,9 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
 		return personalSubscriptionValidationError(err)
 	}
+	if err := validatePersonalOAOptions(opts.EventKey, opts); err != nil {
+		return fmt.Errorf("event consume --as user: %w", personalSubscriptionValidationError(err))
+	}
 	rawFormat := ""
 	if f := c.Flags().Lookup("format"); f != nil && f.Changed {
 		rawFormat = opts.Common.FormatRaw
@@ -290,11 +297,18 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	if err != nil {
 		return fmt.Errorf("event consume --as user: %w", personalSubscriptionValidationError(err))
 	}
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
 	if opts.Common.DryRun {
 		if strings.TrimSpace(opts.SubscribeID) == "" {
 			if err := validatePersonalSubscriptionOptions(opts); err != nil {
 				return fmt.Errorf("event consume --as user: %w", personalSubscriptionValidationError(err))
 			}
+		} else {
+			_, eventKey, _, err := personalEnsureSubscription(ctx, client, identity, opts)
+			if err != nil {
+				return fmt.Errorf("event consume --as user: %w", err)
+			}
+			opts.EventKey = eventKey
 		}
 		cfg := consume.Config{
 			WorkDir:        workDir,
@@ -369,7 +383,6 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 		}
 	}
 
-	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
 	var attempt *personalSubscriptionAttemptReservation
 	if strings.TrimSpace(opts.SubscribeID) == "" {
 		attempt, err = reservePersonalSubscriptionAttempts(
@@ -408,9 +421,17 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 		)
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
-	cleanup := func(cleanupCtx context.Context) {
-		_ = personalDeleteSubscription(client, cleanupCtx, sub.SubscribeID)
-		_ = personalRemoveRunStates(workDir, []string{sub.SubscribeID})
+	selfCreated := strings.TrimSpace(opts.SubscribeID) == ""
+	ownsSubscription := selfCreated || opts.Ephemeral
+	var cleanupOnce sync.Once
+	cleanupOwnedSubscription := func(cleanupCtx context.Context) {
+		if !ownsSubscription {
+			return
+		}
+		cleanupOnce.Do(func() {
+			_ = personalDeleteSubscription(client, cleanupCtx, sub.SubscribeID)
+			_ = personalRemoveRunStates(workDir, []string{sub.SubscribeID})
+		})
 	}
 	if err := personalUpsertRunState(workDir, personal.RunState{
 		SubscribeID:  sub.SubscribeID,
@@ -421,19 +442,19 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 		IdentityHash: identityHash,
 	}); err != nil {
 		wrapped := fmt.Errorf("save run state: %w", err)
+		cleanupCtx := context.Background()
+		if personalSubscriptionCanceled(ctx, wrapped) {
+			cleanupCtx = ctx
+		}
 		if attempt != nil {
-			cleanupCtx := context.Background()
-			if personalSubscriptionCanceled(ctx, wrapped) {
-				cleanupCtx = ctx
-			}
 			classification := personalSubscriptionLocalFailure()
 			wrapped = attempt.completeFailure(ctx, 0, 0, wrapped, &classification)
-			cleanup(cleanupCtx)
 		}
+		cleanupOwnedSubscription(cleanupCtx)
 		return fmt.Errorf("event consume --as user: %w", wrapped)
 	}
 	if err := attempt.completeSuccess(); err != nil {
-		cleanup(context.Background())
+		cleanupOwnedSubscription(context.Background())
 		return fmt.Errorf("event consume --as user: %w", err)
 	}
 	// Ownership-based cleanup: a subscription this run CREATED is
@@ -442,9 +463,8 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 	// leaks server-side. A subscription REUSED via --subscribe-id is left
 	// intact — the caller owns its lifecycle. --ephemeral forces cleanup
 	// either way.
-	selfCreated := strings.TrimSpace(opts.SubscribeID) == ""
-	if opts.Ephemeral || selfCreated {
-		defer cleanup(context.Background())
+	if ownsSubscription {
+		defer cleanupOwnedSubscription(context.Background())
 	}
 
 	cfg.EventKey = eventKey
@@ -466,17 +486,9 @@ func runPersonalEventConsumeSingle(c *cobra.Command, opts personalConsumeOptions
 			Source:       foregroundSource,
 		}
 		bus.ApplyEnvTuning(&busCfg)
-		err = personalBusRun(ctx, busCfg)
-		if err != nil && !opts.Ephemeral {
-			cleanup(context.Background())
-		}
-		return err
+		return personalBusRun(ctx, busCfg)
 	}
-	err = personalConsumeRun(ctx, cfg)
-	if err != nil && !opts.Ephemeral {
-		cleanup(context.Background())
-	}
-	return err
+	return personalConsumeRun(ctx, cfg)
 }
 
 type personalMultiSubscription struct {
@@ -688,6 +700,9 @@ func preparePersonalMultiOptions(opts personalConsumeOptions) ([]personalConsume
 		if !def.Public {
 			return nil, personal.PublicAvailabilityError(eventKey)
 		}
+		if err := validatePersonalOAOptions(eventKey, opts); err != nil {
+			return nil, err
+		}
 		switch def.RuleType {
 		case "singleChat", "sender":
 			hasUserScope = true
@@ -814,6 +829,9 @@ func applyPersonalConsumeFilters(cfg *consume.Config, opts personalConsumeOption
 }
 
 func validatePersonalSubscriptionOptions(opts personalConsumeOptions) error {
+	if err := validatePersonalOAOptions(opts.EventKey, opts); err != nil {
+		return err
+	}
 	if _, _, err := personal.BuildRuleParam(opts.EventKey, personal.RuleOptions{
 		RuleType:       opts.Rule,
 		UserID:         opts.UserID,
@@ -826,6 +844,37 @@ func validatePersonalSubscriptionOptions(opts personalConsumeOptions) error {
 	return err
 }
 
+func validatePersonalOAOptions(eventKey string, opts personalConsumeOptions) error {
+	changed := personalOAOptionNames(opts)
+	if len(changed) == 0 {
+		return nil
+	}
+	def, ok := personalLookupDefinition(strings.TrimSpace(eventKey))
+	if !ok || def.Category != "oa" {
+		return nil
+	}
+	return fmt.Errorf("%s not supported for OA event %s", strings.Join(changed, ", "), eventKey)
+}
+
+func personalOAOptionNames(opts personalConsumeOptions) []string {
+	var changed []string
+	for _, item := range []struct {
+		name  string
+		value string
+	}{
+		{name: "--user", value: opts.UserID},
+		{name: "--open-dingtalk-id", value: opts.OpenDingTalkID},
+		{name: "--group", value: opts.GroupID},
+		{name: "--query", value: opts.QueryCSV},
+		{name: "--filter-json", value: opts.FilterJSON},
+	} {
+		if strings.TrimSpace(item.value) != "" {
+			changed = append(changed, item.name)
+		}
+	}
+	return changed
+}
+
 type personalPreparedSubscription struct {
 	EventKey string
 	RuleType string
@@ -839,6 +888,9 @@ func preparePersonalSubscription(identity personal.Identity, opts personalConsum
 	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
 		return personalPreparedSubscription{}, err
 	}
+	if err := validatePersonalOAOptions(opts.EventKey, opts); err != nil {
+		return personalPreparedSubscription{}, err
+	}
 	ruleType, ruleParam, err := personal.BuildRuleParam(opts.EventKey, personal.RuleOptions{
 		RuleType:       opts.Rule,
 		UserID:         opts.UserID,
@@ -885,13 +937,32 @@ func ensurePersonalSubscription(ctx context.Context, client *personal.Client, id
 		if err != nil {
 			return nil, "", "", err
 		}
-		eventKey := firstNonEmptyPersonalString(opts.EventKey, sub.EventKey)
+		if sub == nil {
+			return nil, "", "", errors.New("personal event: server returned an empty subscription")
+		}
+		requestedEventKey := strings.TrimSpace(opts.EventKey)
+		actualEventKey := strings.TrimSpace(sub.EventKey)
+		if requestedEventKey != "" && actualEventKey != "" && requestedEventKey != actualEventKey {
+			return nil, "", "", fmt.Errorf(
+				"event_key %q does not match reused subscription %q event_key %q",
+				requestedEventKey,
+				strings.TrimSpace(opts.SubscribeID),
+				actualEventKey,
+			)
+		}
+		eventKey := actualEventKey
+		if eventKey == "" {
+			eventKey = requestedEventKey
+		}
 		if eventKey == "" {
 			return nil, "", "", fmt.Errorf("event_key is required when --subscribe-id lookup returns no event_key")
 		}
 		if err := ensurePublicPersonalEvent(eventKey); err != nil {
 			return nil, "", "", err
 		}
+		if err := validatePersonalOAOptions(eventKey, opts); err != nil {
+			return nil, "", "", err
+		}
 		ruleType := firstNonEmptyPersonalString(sub.RuleType, opts.Rule)
 		if ruleType == "" {
 			if def, ok := personal.Lookup(eventKey); ok {

internal/app/event_personal_full_coverage_test.go

@@ -18,6 +18,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
 	eventtransport "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -36,18 +37,20 @@ func TestCrossPlatformCoveragePersonalEventRemainingSchemaAndSubscriptionCoverag
 		}
 	}
 
-	oldGet := personalGetSubscription
-	oldCreate := personalCreateSubscription
-	t.Cleanup(func() {
-		personalGetSubscription = oldGet
-		personalCreateSubscription = oldCreate
-	})
+	testseam.Protect(t, &personalGetSubscription)
+	testseam.Protect(t, &personalCreateSubscription)
 	client := personal.NewClient("https://example.test", personal.Identity{})
 	wantErr := errors.New("subscription")
 	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) { return nil, wantErr }
 	if _, _, _, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
 		t.Fatalf("get subscription error = %v", err)
 	}
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return nil, nil
+	}
+	if _, _, _, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); err == nil || !strings.Contains(err.Error(), "empty subscription") {
+		t.Fatalf("nil subscription = %v", err)
+	}
 	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
 		return &personal.Subscription{}, nil
 	}

internal/app/event_personal_oa_test.go

@@ -0,0 +1,627 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/spf13/cobra"
+)
+
+func TestPersonalOAEventListAndSchemaCommands(t *testing.T) {
+	list := newEventListCommand()
+	list.SilenceUsage = true
+	list.SilenceErrors = true
+	var listOut bytes.Buffer
+	list.SetOut(&listOut)
+	list.SetArgs([]string{"--category", "oa"})
+	if err := list.Execute(); err != nil {
+		t.Fatalf("event list --category oa error = %v", err)
+	}
+	tests := []struct {
+		eventKey   string
+		properties []string
+	}{
+		{
+			eventKey: personal.EventOAApprovalTaskCreated,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "create_time", "event_time",
+			},
+		},
+		{
+			eventKey: personal.EventOAApprovalTaskFinished,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "result", "create_time",
+				"finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: personal.EventOAApprovalTaskRedirected,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "result", "create_time",
+				"finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: personal.EventOAApprovalInstanceStarted,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "event_time",
+			},
+		},
+		{
+			eventKey: personal.EventOAApprovalInstanceTerminated,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: personal.EventOAApprovalInstanceFinished,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "result", "create_time", "finish_time",
+				"event_time",
+			},
+		},
+	}
+	for _, tt := range tests {
+		eventKey := tt.eventKey
+		if !strings.Contains(listOut.String(), eventKey) {
+			t.Fatalf("OA event list missing %s:\n%s", eventKey, listOut.String())
+		}
+
+		schema := newEventSchemaCommand()
+		schema.SilenceUsage = true
+		schema.SilenceErrors = true
+		var schemaOut bytes.Buffer
+		schema.SetOut(&schemaOut)
+		schema.SetArgs([]string{eventKey, "--flatten"})
+		if err := schema.Execute(); err != nil {
+			t.Fatalf("event schema %s --flatten error = %v", eventKey, err)
+		}
+		var doc map[string]any
+		if err := json.Unmarshal(schemaOut.Bytes(), &doc); err != nil {
+			t.Fatalf("decode schema for %s: %v\n%s", eventKey, err, schemaOut.String())
+		}
+		if doc["event_key"] != eventKey || doc["rule_type"] != "all" || doc["jq_root_path"] != "." {
+			t.Fatalf("schema document for %s = %#v", eventKey, doc)
+		}
+		schemaBody, ok := doc["schema"].(map[string]any)
+		if !ok {
+			t.Fatalf("schema body for %s = %#v", eventKey, doc["schema"])
+		}
+		properties, ok := schemaBody["properties"].(map[string]any)
+		if !ok || len(properties) != len(tt.properties) {
+			t.Fatalf("schema properties for %s = %#v, want %d fields", eventKey, schemaBody["properties"], len(tt.properties))
+		}
+		for _, name := range tt.properties {
+			if _, ok := properties[name].(map[string]any); !ok {
+				t.Fatalf("schema property %s for %s = %#v", name, eventKey, properties[name])
+			}
+		}
+		if _, ok := properties["payload"]; ok {
+			t.Fatalf("schema for %s exposed generic payload: %#v", eventKey, properties)
+		}
+	}
+	if strings.Contains(listOut.String(), personal.EventMention) {
+		t.Fatalf("OA category list leaked IM event:\n%s", listOut.String())
+	}
+}
+
+func TestPersonalOAEventConsumeDryRunAndValidation(t *testing.T) {
+	oldIdentity := personalResolveEventIdentity
+	oldGet := personalGetSubscription
+	t.Cleanup(func() {
+		personalResolveEventIdentity = oldIdentity
+		personalGetSubscription = oldGet
+	})
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+		return personal.Identity{
+			AccessToken:  "token",
+			LocalSubject: "subject",
+			ClientID:     "client",
+			SourceID:     "open",
+		}, nil
+	}
+	personalGetSubscription = func(_ *personal.Client, _ context.Context, subscribeID string) (*personal.Subscription, error) {
+		switch subscribeID {
+		case "oa-sub-task":
+			return &personal.Subscription{
+				SubscribeID: subscribeID,
+				EventKey:    personal.EventOAApprovalTaskCreated,
+				RuleType:    "all",
+			}, nil
+		case "im-sub-at":
+			return &personal.Subscription{
+				SubscribeID: subscribeID,
+				EventKey:    personal.EventMention,
+				RuleType:    "at",
+			}, nil
+		default:
+			t.Fatalf("unexpected subscription lookup %q", subscribeID)
+			return nil, nil
+		}
+	}
+
+	oaEvents := []string{
+		personal.EventOAApprovalTaskCreated,
+		personal.EventOAApprovalTaskFinished,
+		personal.EventOAApprovalTaskRedirected,
+		personal.EventOAApprovalInstanceStarted,
+		personal.EventOAApprovalInstanceTerminated,
+		personal.EventOAApprovalInstanceFinished,
+	}
+	for _, eventKey := range oaEvents {
+		t.Run(eventKey+"/dry-run", func(t *testing.T) {
+			cmd := newEventConsumeCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			var stderr bytes.Buffer
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(&stderr)
+			cmd.SetArgs([]string{eventKey, "--dry-run"})
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("OA dry-run error = %v", err)
+			}
+			if !strings.Contains(stderr.String(), "event_types      : "+eventKey) {
+				t.Fatalf("OA dry-run does not select %s:\n%s", eventKey, stderr.String())
+			}
+		})
+
+		for _, args := range [][]string{
+			{"--user", "user-1"},
+			{"--open-dingtalk-id", "open-user-1"},
+			{"--group", "cid-1"},
+			{"--query", "urgent"},
+			{"--filter-json", `{"field":"content","op":"eq","value":"urgent"}`},
+		} {
+			name := strings.TrimPrefix(args[0], "--")
+			t.Run(eventKey+"/reject-"+name, func(t *testing.T) {
+				cmd := newEventConsumeCommand()
+				cmd.SilenceUsage = true
+				cmd.SilenceErrors = true
+				cmd.SetOut(io.Discard)
+				cmd.SetErr(io.Discard)
+				cmd.SetArgs(append([]string{eventKey}, append(args, "--dry-run")...))
+				err := cmd.Execute()
+				if err == nil || !strings.Contains(err.Error(), "not supported") {
+					t.Fatalf("OA consume %s error = %v, want unsupported option", args[0], err)
+				}
+			})
+		}
+	}
+
+	t.Run("multi-dry-run", func(t *testing.T) {
+		cmd := newEventConsumeCommand()
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		var stderr bytes.Buffer
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(&stderr)
+		cmd.SetArgs(append(append([]string(nil), oaEvents...), "--dry-run"))
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("multi OA dry-run error = %v", err)
+		}
+		for _, eventKey := range oaEvents {
+			want := "event_key=" + eventKey + " rule_type=all rule_param={}"
+			if !strings.Contains(stderr.String(), want) {
+				t.Fatalf("multi OA dry-run missing %q:\n%s", want, stderr.String())
+			}
+		}
+	})
+
+	reuseOverrides := [][]string{
+		{"--user", "user-1"},
+		{"--open-dingtalk-id", "open-user-1"},
+		{"--group", "cid-1"},
+		{"--query", "urgent"},
+		{"--filter-json", `{"field":"content","op":"eq","value":"urgent"}`},
+	}
+	t.Run("reuse-dry-run/implicit-event-key/resolves-oa-event", func(t *testing.T) {
+		cmd := newEventConsumeCommand()
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		var stderr bytes.Buffer
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(&stderr)
+		cmd.SetArgs([]string{"--subscribe-id", "oa-sub-task", "--dry-run"})
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("implicit reused OA dry-run error = %v", err)
+		}
+		if !strings.Contains(stderr.String(), "event_types      : "+personal.EventOAApprovalTaskCreated) {
+			t.Fatalf("implicit reused OA dry-run did not resolve event key:\n%s", stderr.String())
+		}
+	})
+	for _, explicitEventKey := range []bool{true, false} {
+		mode := "implicit-event-key"
+		if explicitEventKey {
+			mode = "explicit-event-key"
+		}
+		for _, override := range reuseOverrides {
+			flag := override[0]
+			t.Run("reuse-dry-run/"+mode+"/"+strings.TrimPrefix(flag, "--"), func(t *testing.T) {
+				args := make([]string, 0, 6)
+				if explicitEventKey {
+					args = append(args, personal.EventOAApprovalTaskCreated)
+				}
+				args = append(args, "--subscribe-id", "oa-sub-task", flag, override[1], "--dry-run")
+				cmd := newEventConsumeCommand()
+				cmd.SilenceUsage = true
+				cmd.SilenceErrors = true
+				cmd.SetOut(io.Discard)
+				cmd.SetErr(io.Discard)
+				cmd.SetArgs(args)
+				err := cmd.Execute()
+				if err == nil || !strings.Contains(err.Error(), flag+" not supported for OA event") {
+					t.Fatalf("%s reused OA dry-run %s error = %v", mode, flag, err)
+				}
+			})
+		}
+	}
+
+	t.Run("reuse-dry-run/implicit-im-remains-supported", func(t *testing.T) {
+		cmd := newEventConsumeCommand()
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
+		cmd.SetArgs([]string{"--subscribe-id", "im-sub-at", "--query", "urgent", "--dry-run"})
+		if err := cmd.Execute(); err != nil {
+			t.Fatalf("implicit reused IM dry-run error = %v", err)
+		}
+	})
+
+	for _, override := range reuseOverrides {
+		flag, value := override[0], override[1]
+		t.Run("multi-reject-"+strings.TrimPrefix(flag, "--"), func(t *testing.T) {
+			cmd := newEventConsumeCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			args := append([]string(nil), oaEvents...)
+			args = append(args, flag, value, "--dry-run")
+			cmd.SetArgs(args)
+			err := cmd.Execute()
+			if err == nil || !strings.Contains(err.Error(), "not supported for OA event") {
+				t.Fatalf("multi OA consume %s error = %v", flag, err)
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "message query remains supported",
+			args: []string{personal.EventMention, "--query", "urgent", "--dry-run"},
+		},
+		{
+			name: "single group lifecycle filter remains supported",
+			args: []string{
+				personal.EventGroupUpdated,
+				"--group", "cid-1",
+				"--filter-json", `{"field":"future","op":"eq","value":"value"}`,
+				"--dry-run",
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			cmd := newEventConsumeCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			cmd.SetOut(io.Discard)
+			cmd.SetErr(io.Discard)
+			cmd.SetArgs(test.args)
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("existing IM consume behavior changed: %v", err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoveragePersonalOAValidationBranches(t *testing.T) {
+	invalid := personalConsumeOptions{
+		EventKey: personal.EventOAApprovalTaskCreated,
+		UserID:   "user-1",
+	}
+	if err := validatePersonalSubscriptionOptions(invalid); err == nil ||
+		!strings.Contains(err.Error(), "--user not supported for OA event") {
+		t.Fatalf("validatePersonalSubscriptionOptions() error = %v", err)
+	}
+	if _, err := preparePersonalSubscription(personal.Identity{}, invalid); err == nil ||
+		!strings.Contains(err.Error(), "--user not supported for OA event") {
+		t.Fatalf("preparePersonalSubscription() error = %v", err)
+	}
+
+	oldGet := personalGetSubscription
+	t.Cleanup(func() { personalGetSubscription = oldGet })
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return &personal.Subscription{
+			SubscribeID: "oa-sub-without-event-key",
+			RuleType:    "all",
+		}, nil
+	}
+	_, _, _, err := ensurePersonalSubscription(
+		context.Background(),
+		nil,
+		personal.Identity{},
+		personalConsumeOptions{
+			SubscribeID: "oa-sub-without-event-key",
+			EventKey:    personal.EventOAApprovalTaskCreated,
+			UserID:      "user-1",
+		},
+	)
+	if err == nil || !strings.Contains(err.Error(), "--user not supported for OA event") {
+		t.Fatalf("ensurePersonalSubscription() error = %v", err)
+	}
+}
+
+func TestPersonalOAMultiConsumeCreatesIndependentAllSubscriptionsOnSharedBus(t *testing.T) {
+	restoreMany := installPersonalManySeams(t)
+	defer restoreMany()
+	oldCreate := personalCreateSubscription
+	defer func() { personalCreateSubscription = oldCreate }()
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	identity := personal.Identity{
+		AccessToken:  "token",
+		LocalSubject: "subject",
+		ClientID:     "client",
+		SourceID:     "open",
+	}
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+		return identity, nil
+	}
+	var requests []personal.CreateSubscriptionRequest
+	personalCreateSubscription = func(_ *personal.Client, _ context.Context, req personal.CreateSubscriptionRequest) (*personal.Subscription, error) {
+		requests = append(requests, req)
+		return &personal.Subscription{SubscribeID: "sub-" + req.EventKey}, nil
+	}
+	personalEnsureSubscription = ensurePersonalSubscription
+	var states []personal.RunState
+	personalUpsertRunState = func(_ string, state personal.RunState) error {
+		states = append(states, state)
+		return nil
+	}
+	personalDeleteSubscription = func(*personal.Client, context.Context, string) error { return nil }
+	personalRemoveRunStates = func(string, []string) error { return nil }
+	personalValidateConsumeConfig = func(consume.Config) error { return nil }
+	runManyCalls := 0
+	var gotSpecs []consume.ConsumerSpec
+	personalConsumeRunMany = func(_ context.Context, _ consume.Config, specs []consume.ConsumerSpec) error {
+		runManyCalls++
+		gotSpecs = append([]consume.ConsumerSpec(nil), specs...)
+		return nil
+	}
+
+	eventKeys := []string{
+		personal.EventOAApprovalTaskCreated,
+		personal.EventOAApprovalTaskFinished,
+		personal.EventOAApprovalTaskRedirected,
+		personal.EventOAApprovalInstanceStarted,
+		personal.EventOAApprovalInstanceTerminated,
+		personal.EventOAApprovalInstanceFinished,
+	}
+	if err := runPersonalEventConsume(newPersonalCoverageCommand(), personalConsumeOptions{
+		EventKeys: eventKeys,
+		Flatten:   true,
+	}); err != nil {
+		t.Fatalf("multi OA consume error = %v", err)
+	}
+	if runManyCalls != 1 {
+		t.Fatalf("RunMany calls = %d, want one shared-bus consume call", runManyCalls)
+	}
+	if len(requests) != len(eventKeys) || len(states) != len(eventKeys) || len(gotSpecs) != len(eventKeys) {
+		t.Fatalf("requests=%d states=%d specs=%d, want %d each", len(requests), len(states), len(gotSpecs), len(eventKeys))
+	}
+	for i, eventKey := range eventKeys {
+		req := requests[i]
+		if req.EventKey != eventKey || req.RuleType != "all" || req.RuleParam == nil || len(req.RuleParam) != 0 || req.Filter != nil {
+			t.Fatalf("subscription request[%d] = %#v, want %s all/{}", i, req, eventKey)
+		}
+		if states[i].EventKey != eventKey || states[i].RuleType != "all" {
+			t.Fatalf("run state[%d] = %#v", i, states[i])
+		}
+		wantSpec := consume.ConsumerSpec{
+			EventKey:         eventKey,
+			EventTypes:       []string{eventKey},
+			SubscribeID:      "sub-" + eventKey,
+			ReadySubscribeID: "sub-" + eventKey,
+		}
+		if !reflect.DeepEqual(gotSpecs[i], wantSpec) {
+			t.Fatalf("consumer spec[%d] = %#v, want %#v", i, gotSpecs[i], wantSpec)
+		}
+	}
+}
+
+func TestPersonalOAReusedSubscriptionRejectsDefinitionOverridesAtRuntime(t *testing.T) {
+	oldGet := personalGetSubscription
+	t.Cleanup(func() { personalGetSubscription = oldGet })
+	getCalls := 0
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		getCalls++
+		return &personal.Subscription{
+			SubscribeID: "oa-sub-task",
+			EventKey:    personal.EventOAApprovalTaskCreated,
+			RuleType:    "all",
+		}, nil
+	}
+
+	tests := []struct {
+		name string
+		set  func(*personalConsumeOptions)
+	}{
+		{name: "user", set: func(opts *personalConsumeOptions) { opts.UserID = "user-1" }},
+		{name: "open-dingtalk-id", set: func(opts *personalConsumeOptions) { opts.OpenDingTalkID = "open-user-1" }},
+		{name: "group", set: func(opts *personalConsumeOptions) { opts.GroupID = "cid-1" }},
+		{name: "query", set: func(opts *personalConsumeOptions) { opts.QueryCSV = "urgent" }},
+		{name: "filter-json", set: func(opts *personalConsumeOptions) { opts.FilterJSON = `{"field":"content","op":"eq","value":"urgent"}` }},
+	}
+	for _, explicitEventKey := range []bool{true, false} {
+		mode := "implicit-event-key"
+		if explicitEventKey {
+			mode = "explicit-event-key"
+		}
+		for _, test := range tests {
+			t.Run(mode+"/"+test.name, func(t *testing.T) {
+				opts := personalConsumeOptions{SubscribeID: "oa-sub-task"}
+				if explicitEventKey {
+					opts.EventKey = personal.EventOAApprovalTaskCreated
+				}
+				test.set(&opts)
+				before := getCalls
+				_, _, _, err := ensurePersonalSubscription(
+					context.Background(),
+					nil,
+					personal.Identity{},
+					opts,
+				)
+				if err == nil || !strings.Contains(err.Error(), "--"+test.name+" not supported for OA event") {
+					t.Fatalf("reused OA subscription %s error = %v", test.name, err)
+				}
+				if getCalls != before+1 {
+					t.Fatalf("subscription lookup calls = %d, want %d", getCalls, before+1)
+				}
+			})
+		}
+	}
+}
+
+func TestPersonalOAImplicitReuseRuntimeLooksUpEventBeforeValidation(t *testing.T) {
+	oldIdentity := personalResolveEventIdentity
+	oldGet := personalGetSubscription
+	t.Cleanup(func() {
+		personalResolveEventIdentity = oldIdentity
+		personalGetSubscription = oldGet
+	})
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+		return personal.Identity{
+			AccessToken:  "token",
+			LocalSubject: "subject",
+			ClientID:     "client",
+			SourceID:     "open",
+		}, nil
+	}
+	getCalls := 0
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		getCalls++
+		return &personal.Subscription{
+			SubscribeID: "oa-sub-task",
+			EventKey:    personal.EventOAApprovalTaskCreated,
+			RuleType:    "all",
+		}, nil
+	}
+
+	cmd := newEventConsumeCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"--subscribe-id", "oa-sub-task", "--group", "cid-1"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "--group not supported for OA event "+personal.EventOAApprovalTaskCreated) {
+		t.Fatalf("implicit reused OA runtime error = %v", err)
+	}
+	if getCalls != 1 {
+		t.Fatalf("subscription lookup calls = %d, want 1", getCalls)
+	}
+}
+
+func TestPersonalIMReusedSubscriptionWithExistingOverridesRemainsSupported(t *testing.T) {
+	oldGet := personalGetSubscription
+	t.Cleanup(func() { personalGetSubscription = oldGet })
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return &personal.Subscription{
+			SubscribeID: "im-sub",
+			EventKey:    personal.EventSingleChat,
+			RuleType:    "singleChat",
+		}, nil
+	}
+
+	sub, eventKey, ruleType, err := ensurePersonalSubscription(
+		context.Background(),
+		nil,
+		personal.Identity{},
+		personalConsumeOptions{
+			SubscribeID: "im-sub",
+			EventKey:    personal.EventSingleChat,
+			UserID:      "user-1",
+			QueryCSV:    "urgent",
+			FilterJSON:  `{"field":"content","op":"eq","value":"urgent"}`,
+		},
+	)
+	if err != nil {
+		t.Fatalf("reused IM subscription error = %v", err)
+	}
+	if sub.SubscribeID != "im-sub" || eventKey != personal.EventSingleChat || ruleType != "singleChat" {
+		t.Fatalf("reused IM subscription = %#v, event=%q rule=%q", sub, eventKey, ruleType)
+	}
+}
+
+func TestPersonalOAStatusAndStopCommandWiring(t *testing.T) {
+	oldStatus := eventRunPersonalStatus
+	oldStop := eventRunPersonalStop
+	t.Cleanup(func() {
+		eventRunPersonalStatus = oldStatus
+		eventRunPersonalStop = oldStop
+	})
+
+	var statusOpts personalStatusOptions
+	eventRunPersonalStatus = func(_ *cobra.Command, opts personalStatusOptions) error {
+		statusOpts = opts
+		return nil
+	}
+	status := newEventStatusCommand()
+	status.SilenceUsage = true
+	status.SilenceErrors = true
+	status.SetOut(io.Discard)
+	status.SetErr(io.Discard)
+	status.SetArgs([]string{
+		"--event", personal.EventOAApprovalTaskCreated,
+		"--subscribe-id", "oa-sub-task",
+		"--status", "all",
+	})
+	if err := status.Execute(); err != nil {
+		t.Fatalf("OA event status error = %v", err)
+	}
+	if statusOpts.EventKey != personal.EventOAApprovalTaskCreated ||
+		statusOpts.SubscribeID != "oa-sub-task" ||
+		statusOpts.Status != "all" {
+		t.Fatalf("OA status options = %#v", statusOpts)
+	}
+
+	var stopOpts personalStopOptions
+	eventRunPersonalStop = func(_ *cobra.Command, opts personalStopOptions) error {
+		stopOpts = opts
+		return nil
+	}
+	root := &cobra.Command{Use: "dws", SilenceUsage: true, SilenceErrors: true}
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.PersistentFlags().Bool("yes", false, "")
+	event := &cobra.Command{Use: "event"}
+	event.AddCommand(newEventStopCommand())
+	root.AddCommand(event)
+	root.SetArgs([]string{"event", "stop", "oa-sub-task", "--yes"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("OA event stop error = %v", err)
+	}
+	if stopOpts.SubscribeID != "oa-sub-task" || stopOpts.All {
+		t.Fatalf("OA stop options = %#v", stopOpts)
+	}
+}

internal/app/event_personal_release_safety_test.go

@@ -0,0 +1,427 @@
+// 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"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"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/event/source"
+)
+
+func TestPersonalConsumeCleanupOwnershipRuntimeMatrix(t *testing.T) {
+	runErr := errors.New("runtime failed")
+	for _, foreground := range []bool{false, true} {
+		for _, selfCreated := range []bool{false, true} {
+			for _, ephemeral := range []bool{false, true} {
+				for _, failRuntime := range []bool{false, true} {
+					name := strings.Join([]string{
+						map[bool]string{false: "background", true: "foreground"}[foreground],
+						map[bool]string{false: "reused", true: "self-created"}[selfCreated],
+						map[bool]string{false: "persistent", true: "ephemeral"}[ephemeral],
+						map[bool]string{false: "success", true: "error"}[failRuntime],
+					}, "/")
+					t.Run(name, func(t *testing.T) {
+						restore := installPersonalManySeams(t)
+						t.Cleanup(restore)
+						t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+						oldNewSource := personalNewStreamSource
+						oldBusRun := personalBusRun
+						oldConsumeRun := personalConsumeRun
+						t.Cleanup(func() {
+							personalNewStreamSource = oldNewSource
+							personalBusRun = oldBusRun
+							personalConsumeRun = oldConsumeRun
+						})
+
+						personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+							return personal.Identity{
+								AccessToken:  "token",
+								ClientID:     "client",
+								SourceID:     "open",
+								LocalSubject: "subject",
+							}, nil
+						}
+						personalEnsureSubscription = func(
+							context.Context,
+							*personal.Client,
+							personal.Identity,
+							personalConsumeOptions,
+						) (*personal.Subscription, string, string, error) {
+							return &personal.Subscription{SubscribeID: "sub-one"}, personal.EventMention, "at", nil
+						}
+						personalValidateConsumeConfig = func(consume.Config) error { return nil }
+						personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+						personalUpsertRunState = func(string, personal.RunState) error { return nil }
+
+						deleteCalls := 0
+						removeCalls := 0
+						personalDeleteSubscription = func(*personal.Client, context.Context, string) error {
+							deleteCalls++
+							return nil
+						}
+						personalRemoveRunStates = func(string, []string) error {
+							removeCalls++
+							return nil
+						}
+
+						personalNewStreamSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) {
+							return nil, nil
+						}
+						personalBusRun = func(context.Context, bus.Config) error {
+							if failRuntime {
+								return runErr
+							}
+							return nil
+						}
+						personalConsumeRun = func(context.Context, consume.Config) error {
+							if failRuntime {
+								return runErr
+							}
+							return nil
+						}
+
+						opts := personalConsumeOptions{
+							EventKey:       personal.EventMention,
+							Ephemeral:      ephemeral,
+							ControlBaseURL: "https://mcp.example.test/dws",
+							Common: commonConsumeOptions{
+								Foreground: foreground,
+							},
+						}
+						if !selfCreated {
+							opts.SubscribeID = "sub-one"
+						}
+
+						err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), opts)
+						if failRuntime {
+							if !errors.Is(err, runErr) {
+								t.Fatalf("runtime error = %v, want %v", err, runErr)
+							}
+						} else if err != nil {
+							t.Fatalf("consume error = %v", err)
+						}
+
+						wantCleanup := 0
+						if selfCreated || ephemeral {
+							wantCleanup = 1
+						}
+						if deleteCalls != wantCleanup || removeCalls != wantCleanup {
+							t.Fatalf(
+								"cleanup delete/remove = %d/%d, want %d/%d",
+								deleteCalls,
+								removeCalls,
+								wantCleanup,
+								wantCleanup,
+							)
+						}
+					})
+				}
+			}
+		}
+	}
+}
+
+func TestPersonalConsumeCleanupOwnershipOnRunStateFailure(t *testing.T) {
+	stateErr := errors.New("save state failed")
+	for _, test := range []struct {
+		name        string
+		selfCreated bool
+		ephemeral   bool
+		wantCleanup int
+	}{
+		{name: "self-created", selfCreated: true, wantCleanup: 1},
+		{name: "reused persistent", wantCleanup: 0},
+		{name: "reused ephemeral", ephemeral: true, wantCleanup: 1},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			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", ClientID: "client", SourceID: "open"}, nil
+			}
+			personalEnsureSubscription = func(
+				context.Context,
+				*personal.Client,
+				personal.Identity,
+				personalConsumeOptions,
+			) (*personal.Subscription, string, string, error) {
+				return &personal.Subscription{SubscribeID: "sub-one"}, personal.EventMention, "at", nil
+			}
+			personalValidateConsumeConfig = func(consume.Config) error { return nil }
+			personalUpsertRunState = func(string, personal.RunState) error { return stateErr }
+			deleteCalls := 0
+			removeCalls := 0
+			personalDeleteSubscription = func(*personal.Client, context.Context, string) error {
+				deleteCalls++
+				return nil
+			}
+			personalRemoveRunStates = func(string, []string) error {
+				removeCalls++
+				return nil
+			}
+
+			opts := personalConsumeOptions{
+				EventKey:       personal.EventMention,
+				Ephemeral:      test.ephemeral,
+				ControlBaseURL: "https://mcp.example.test/dws",
+			}
+			if !test.selfCreated {
+				opts.SubscribeID = "sub-one"
+			}
+			if err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), opts); !errors.Is(err, stateErr) {
+				t.Fatalf("state error = %v, want %v", err, stateErr)
+			}
+			if deleteCalls != test.wantCleanup || removeCalls != test.wantCleanup {
+				t.Fatalf(
+					"cleanup delete/remove = %d/%d, want %d/%d",
+					deleteCalls,
+					removeCalls,
+					test.wantCleanup,
+					test.wantCleanup,
+				)
+			}
+		})
+	}
+}
+
+func TestPersonalReusedSubscriptionEventKeyResolution(t *testing.T) {
+	oldGet := personalGetSubscription
+	t.Cleanup(func() { personalGetSubscription = oldGet })
+
+	for _, test := range []struct {
+		name      string
+		requested string
+		actual    string
+		wantKey   string
+		wantErr   bool
+	}{
+		{
+			name:      "matching key uses actual",
+			requested: personal.EventMention,
+			actual:    personal.EventMention,
+			wantKey:   personal.EventMention,
+		},
+		{
+			name:    "implicit key uses actual",
+			actual:  personal.EventOAApprovalTaskCreated,
+			wantKey: personal.EventOAApprovalTaskCreated,
+		},
+		{
+			name:      "missing actual falls back to requested",
+			requested: personal.EventOAApprovalTaskCreated,
+			wantKey:   personal.EventOAApprovalTaskCreated,
+		},
+		{
+			name:      "requested IM mismatches actual OA",
+			requested: personal.EventMention,
+			actual:    personal.EventOAApprovalTaskCreated,
+			wantErr:   true,
+		},
+		{
+			name:      "requested OA mismatches actual IM",
+			requested: personal.EventOAApprovalTaskCreated,
+			actual:    personal.EventMention,
+			wantErr:   true,
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+				return &personal.Subscription{
+					SubscribeID: "sub-one",
+					EventKey:    test.actual,
+				}, nil
+			}
+			_, eventKey, _, err := ensurePersonalSubscription(
+				context.Background(),
+				nil,
+				personal.Identity{},
+				personalConsumeOptions{SubscribeID: "sub-one", EventKey: test.requested},
+			)
+			if test.wantErr {
+				if err == nil || !strings.Contains(err.Error(), "does not match reused subscription") {
+					t.Fatalf("mismatch error = %v", err)
+				}
+				if !strings.Contains(err.Error(), test.requested) || !strings.Contains(err.Error(), test.actual) {
+					t.Fatalf("mismatch error does not identify both keys: %v", err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("resolve reused subscription: %v", err)
+			}
+			if eventKey != test.wantKey {
+				t.Fatalf("resolved event key = %q, want %q", eventKey, test.wantKey)
+			}
+		})
+	}
+}
+
+func TestPersonalReusedSubscriptionMismatchStopsDryRunAndRuntime(t *testing.T) {
+	for _, mode := range []struct {
+		name       string
+		dryRun     bool
+		foreground bool
+	}{
+		{name: "dry-run", dryRun: true},
+		{name: "background"},
+		{name: "foreground", foreground: true},
+	} {
+		t.Run(mode.name, func(t *testing.T) {
+			restore := installPersonalManySeams(t)
+			t.Cleanup(restore)
+			t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+			oldGet := personalGetSubscription
+			oldNewSource := personalNewStreamSource
+			oldBusRun := personalBusRun
+			oldConsumeRun := personalConsumeRun
+			t.Cleanup(func() {
+				personalGetSubscription = oldGet
+				personalNewStreamSource = oldNewSource
+				personalBusRun = oldBusRun
+				personalConsumeRun = oldConsumeRun
+			})
+
+			personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+				return personal.Identity{AccessToken: "token", ClientID: "client", SourceID: "open"}, nil
+			}
+			personalEnsureSubscription = ensurePersonalSubscription
+			personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+				return &personal.Subscription{
+					SubscribeID: "sub-one",
+					EventKey:    personal.EventOAApprovalTaskCreated,
+					RuleType:    "all",
+				}, nil
+			}
+			personalValidateConsumeConfig = func(consume.Config) error { return nil }
+			personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+
+			upsertCalls := 0
+			consumeCalls := 0
+			busCalls := 0
+			personalUpsertRunState = func(string, personal.RunState) error {
+				upsertCalls++
+				return nil
+			}
+			personalNewStreamSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) {
+				return nil, nil
+			}
+			personalBusRun = func(context.Context, bus.Config) error {
+				busCalls++
+				return nil
+			}
+			personalConsumeRun = func(context.Context, consume.Config) error {
+				consumeCalls++
+				return nil
+			}
+
+			err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+				EventKey:       personal.EventMention,
+				SubscribeID:    "sub-one",
+				ControlBaseURL: "https://mcp.example.test/dws",
+				Common: commonConsumeOptions{
+					DryRun:     mode.dryRun,
+					Foreground: mode.foreground,
+				},
+			})
+			if err == nil || !strings.Contains(err.Error(), "does not match reused subscription") {
+				t.Fatalf("mismatch error = %v", err)
+			}
+			if upsertCalls != 0 || consumeCalls != 0 || busCalls != 0 {
+				t.Fatalf(
+					"mismatch reached upsert/consumer/bus = %d/%d/%d",
+					upsertCalls,
+					consumeCalls,
+					busCalls,
+				)
+			}
+		})
+	}
+}
+
+func TestPersonalReusedSubscriptionUsesActualKeyInDryRunAndRuntime(t *testing.T) {
+	for _, dryRun := range []bool{true, false} {
+		name := map[bool]string{false: "runtime", true: "dry-run"}[dryRun]
+		t.Run(name, func(t *testing.T) {
+			restore := installPersonalManySeams(t)
+			t.Cleanup(restore)
+			t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+			oldGet := personalGetSubscription
+			oldConsumeRun := personalConsumeRun
+			t.Cleanup(func() {
+				personalGetSubscription = oldGet
+				personalConsumeRun = oldConsumeRun
+			})
+
+			personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+				return personal.Identity{AccessToken: "token", ClientID: "client", SourceID: "open"}, nil
+			}
+			personalEnsureSubscription = ensurePersonalSubscription
+			personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+				return &personal.Subscription{
+					SubscribeID: "sub-oa",
+					EventKey:    personal.EventOAApprovalInstanceFinished,
+					RuleType:    "all",
+				}, nil
+			}
+			personalValidateConsumeConfig = func(consume.Config) error { return nil }
+			personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+			personalUpsertRunState = func(_ string, state personal.RunState) error {
+				if state.EventKey != personal.EventOAApprovalInstanceFinished {
+					t.Fatalf("run state event key = %q", state.EventKey)
+				}
+				return nil
+			}
+
+			var got consume.Config
+			personalConsumeRun = func(_ context.Context, cfg consume.Config) error {
+				got = cfg
+				return nil
+			}
+			if err := runPersonalEventConsumeSingle(newPersonalCoverageCommand(), personalConsumeOptions{
+				SubscribeID:    "sub-oa",
+				ControlBaseURL: "https://mcp.example.test/dws",
+				Common: commonConsumeOptions{
+					DryRun: dryRun,
+				},
+			}); err != nil {
+				t.Fatalf("reuse subscription: %v", err)
+			}
+			if got.EventKey != personal.EventOAApprovalInstanceFinished ||
+				len(got.EventTypes) != 1 || got.EventTypes[0] != personal.EventOAApprovalInstanceFinished ||
+				got.SubscribeID != "sub-oa" {
+				t.Fatalf("consume config = %#v", got)
+			}
+		})
+	}
+}
+
+func TestEventConsumeDryRunHelpDescribesReuseLookup(t *testing.T) {
+	usage := newEventConsumeCommand().Flags().Lookup("dry-run").Usage
+	for _, want := range []string{"不创建订阅", "不连接 bus", "复用 --subscribe-id", "只读查询控制面"} {
+		if !strings.Contains(usage, want) {
+			t.Fatalf("dry-run help %q missing %q", usage, want)
+		}
+	}
+}

internal/app/event_selection_routing_test.go

@@ -0,0 +1,74 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func TestCrossPlatformCoverageEventAgentSelectionBoundaries(t *testing.T) {
+	_ = NewRootCommand()
+
+	eventProduct, ok := contract.LookupProductDecl("event")
+	if !ok {
+		t.Fatal("event ProductDecl is not registered")
+	}
+	assertSelectionContains(t, "event product", eventProduct.Selection.AgentSummary,
+		[]string{"IM", "OA"})
+	assertSelectionContains(t, "event product use_when", strings.Join(eventProduct.Selection.UseWhen, "\n"),
+		[]string{"消息", "群生命周期", "OA"})
+	assertSelectionContains(t, "event product avoid_when", strings.Join(eventProduct.Selection.AvoidWhen, "\n"),
+		[]string{"chat", "oa", "dev app event"})
+
+	listenMeta, ok := cli.ResolveMeta("event +listen-im")
+	if !ok {
+		t.Fatal("event +listen-im metadata is not registered")
+	}
+	assertSelectionContains(t, "event.listen_im use_when", strings.Join(listenMeta.Selection.UseWhen, "\n"),
+		[]string{"@我", "message/reaction/read/recall"})
+	assertSelectionContains(t, "event.listen_im avoid_when", strings.Join(listenMeta.Selection.AvoidWhen, "\n"),
+		[]string{"OA 审批事件", "群标题", "Filter DSL", "event consume", "历史消息"})
+
+	consumeMeta, ok := cli.ResolveMeta("event consume")
+	if !ok {
+		t.Fatal("event consume metadata is not registered")
+	}
+	consumeUse := strings.Join(consumeMeta.Selection.UseWhen, "\n")
+	assertSelectionContains(t, "event.consume use_when", consumeUse,
+		[]string{"OA", "群", "EventKey", "Filter DSL", "subscribe_id", "transport envelope", "高级多事件"})
+	consumeAvoid := strings.Join(consumeMeta.Selection.AvoidWhen, "\n")
+	assertSelectionContains(t, "event.consume avoid_when", consumeAvoid,
+		[]string{"event +listen-im", "历史聊天", "oa", "dev app event"})
+
+	schemaMeta, ok := cli.ResolveMeta("event schema")
+	if !ok {
+		t.Fatal("event schema metadata is not registered")
+	}
+	assertSelectionContains(t, "event.schema use_when", strings.Join(schemaMeta.Selection.UseWhen, "\n"),
+		[]string{"IM", "OA", "--flatten"})
+
+	for productID, want := range map[string]string{
+		"chat": "event +listen-im",
+		"oa":   "event consume",
+	} {
+		decl, found := contract.LookupProductDecl(productID)
+		if !found {
+			t.Fatalf("%s ProductDecl is not registered", productID)
+		}
+		assertSelectionContains(t, productID+" avoid_when", strings.Join(decl.Selection.AvoidWhen, "\n"), []string{want})
+	}
+}
+
+func assertSelectionContains(t *testing.T, label, text string, fragments []string) {
+	t.Helper()
+	for _, fragment := range fragments {
+		if !strings.Contains(text, fragment) {
+			t.Errorf("%s = %q, want fragment %q", label, text, fragment)
+		}
+	}
+}

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 `{}`
 	}
@@ -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
@@ -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

@@ -30,13 +30,34 @@ var paramAliasCompleteCommands = map[string][]string{
 	"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"},
@@ -81,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"},
@@ -101,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"},
 	},
@@ -111,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
@@ -149,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
@@ -163,14 +253,33 @@ 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 TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
@@ -273,8 +382,9 @@ func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayl
 			}
 
 			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)
@@ -290,13 +400,16 @@ func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayl
 			}
 			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)
@@ -308,6 +421,16 @@ func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayl
 	}
 }
 
+// Resource download deliberately continues from the transport call into a
+// local HTTPS download. The generic capture caller returns an empty object, so
+// this command's stable post-transport validation error is the expected test
+// boundary; canonical and alias calls must still produce the same request and
+// the same error.
+func 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

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

@@ -135,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 {
@@ -1324,6 +1327,18 @@ func registerPluginAuthFromHeaders(srv mcptypes.ServerDescriptor) {
 //   - 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/schema_agent_examples_dry_run_test.go

@@ -296,7 +296,14 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles {
 			t.Fatalf("write dry-run fixture %s: %v", path, err)
 		}
 	}
-	return agentExampleFiles{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 materializeAgentExampleArgv(argv []string, files agentExampleFiles) []string {

internal/app/schema_interface_disposition_contract_test.go

@@ -34,7 +34,12 @@ func TestReviewedRoutedInterfacesReachFinalSchema(t *testing.T) {
 		{
 			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.",
+			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.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: "sheet.range_read",

internal/app/schema_safety_contract_test.go

@@ -26,6 +26,14 @@ func TestReviewedMutationSafetyReachesFinalSchema(t *testing.T) {
 	wants := []finalSchemaSafetyWant{
 		{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},
+		// Card update intentionally layers confirmation: the atomic typed command
+		// preserves its original contract, while the Agent-facing shortcut owns
+		// the outer confirmation boundary.
+		{canonical: "chat.update_streaming_card", effect: "write", risk: "medium", confirmation: "not_required", idempotency: "unknown", provenance: declared},
+		{canonical: "chat.shortcut_messages_send", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "chat.shortcut_messages_send_by_webhook", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "chat.shortcut_messages_send_card", effect: "write", risk: "medium", confirmation: "user_required", idempotency: "unknown", provenance: declared},
+		{canonical: "chat.shortcut_messages_update_card", effect: "write", risk: "medium", 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},

internal/app/schema_shortcut_contract_test.go

@@ -16,12 +16,12 @@ import (
 )
 
 const (
-	publicShortcutCount = 294
+	publicShortcutCount = 357
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including hidden leaves such as minutes.shortcut_minutes_search.
-	schemaPublishedShortcutCount = 295
+	schemaPublishedShortcutCount = 358
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 294
+	publiclyDeliveredShortcutCount = 357
 )
 
 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -114,7 +114,7 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 
 	product := executeShortcutSchemaQuery(t, "chat")
 	productPayload, _ := product["product"].(map[string]any)
-	if got, want := int(product["count"].(float64)), 180; 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"])
@@ -129,6 +129,75 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 	}
 }
 
+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)
+	}
+}
+
 func executeShortcutSchemaQuery(t testing.TB, args ...string) map[string]any {
 	t.Helper()
 	root := NewRootCommand()

internal/app/server_failure_classifier.go

@@ -81,6 +81,7 @@ func newServerFailureAPIError(
 		apperrors.WithReason(fallbackReason),
 		apperrors.WithServerKey(serverKey),
 		apperrors.WithHint(fallbackHint),
+		apperrors.WithActions("运行 dws doctor 检查登录态、网络和本地环境；持续失败时保留 Trace ID 和 Server Code"),
 		apperrors.WithServerDiag(diag),
 	}
 	if classified, ok := classifyServerFailure(message, diag); ok {

internal/app/server_failure_classifier_test.go

@@ -95,6 +95,9 @@ func TestCrossPlatformCoverageServerFailureClassifierUnknownFallsBack(t *testing
 	if typed.Reason != "business_error" || typed.Origin != "" || typed.FailureStage != "" || typed.ExecutionStarted != nil {
 		t.Fatalf("unexpected fallback classification: %#v", typed)
 	}
+	if len(typed.Actions) == 0 || !strings.Contains(typed.Actions[0], "dws doctor") {
+		t.Fatalf("fallback error has no stable troubleshooting entry: %#v", typed.Actions)
+	}
 }
 
 func TestCrossPlatformCoverageServerFailureReasonUsesTypedClassification(t *testing.T) {

internal/app/skill_setup.go

@@ -51,6 +51,8 @@ var (
 	skillSetupInstallMono    = installSkillToHomes
 	skillSetupInstallMulti   = installMultiSkillToHomes
 	skillSetupCopyDir        = copyDir
+	skillSetupMkdirTemp      = os.MkdirTemp
+	skillSetupRename         = os.Rename
 	skillSetupRunForm        = (*huh.Form).Run
 	skillSetupInteractive    = isInteractiveTerminal
 	skillSetupReadDir        = os.ReadDir
@@ -136,6 +138,9 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 
 	// multi 模式枚举 src 下的子 skill 名，供确认信息与安装步骤共用
 	var multiSkillNames []string
+	var foldedEventMiscTargets []string
+	var migrateEventMiscTargets []string
+	var installsEventMiscCompanion bool
 	if mode == skillSetupModeMulti {
 		allMultiSkillNames, listErr := skillSetupListMulti(skillSrc)
 		if listErr != nil {
@@ -151,6 +156,30 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 		// dingtalk-shared carries the global rules every product skill declares as a
 		// PREREQUISITE; it must ship even when --skill / --exclude narrows the set.
 		multiSkillNames = ensureMandatorySharedSkill(filtered, allMultiSkillNames)
+
+		foldedEventMiscTargets = findFoldedEventMiscTargets(dests)
+		if len(foldedEventMiscTargets) > 0 {
+			hasEvent := containsSkillName(multiSkillNames, multiEventSkill)
+			hasMisc := containsSkillName(multiSkillNames, multiMiscSkill)
+			switch {
+			case normalizedSkillListContains(excludeRaw, multiEventSkill):
+				return fmt.Errorf("检测到已有 dingtalk-misc 仍承载个人 Event 路由；不能显式 --exclude event，请先完成 dingtalk-event 迁移")
+			case hasMisc && !hasEvent:
+				return fmt.Errorf("检测到已有 dingtalk-misc 仍承载个人 Event 路由；不能只覆盖 dingtalk-misc，必须同时迁移 dingtalk-event")
+			case hasEvent:
+				if normalizedSkillListContains(excludeRaw, multiMiscSkill) {
+					return fmt.Errorf("检测到已有 dingtalk-misc 仍承载个人 Event 路由；本次安装 dingtalk-event 必须同时迁移 dingtalk-misc，不能显式 --exclude misc")
+				}
+				if !containsSkillName(allMultiSkillNames, multiMiscSkill) {
+					return fmt.Errorf("检测到已有 dingtalk-misc 仍承载个人 Event 路由，但当前 multi 源缺少迁移所需的 %s", multiMiscSkill)
+				}
+				if err := validateEventMiscMigrationSource(skillSrc); err != nil {
+					return err
+				}
+				migrateEventMiscTargets = append(migrateEventMiscTargets, foldedEventMiscTargets...)
+				installsEventMiscCompanion = !hasMisc
+			}
+		}
 	}
 
 	// --dry-run：仅预览将安装的内容与目标目录，不写入任何文件、不弹确认。
@@ -162,11 +191,15 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 		}
 		if mode == skillSetupModeMulti && len(multiSkillNames) > 0 {
 			fmt.Fprintf(out, "子 skill：%s\n", strings.Join(multiSkillNames, ", "))
+			printEventMiscMigrationPreview(out, migrateEventMiscTargets, installsEventMiscCompanion)
 		}
 		return nil
 	}
 
 	if !autoYes {
+		if mode == skillSetupModeMulti {
+			printEventMiscMigrationPreview(out, migrateEventMiscTargets, installsEventMiscCompanion)
+		}
 		ok, err := skillSetupConfirm(out, mode, skillSrc, dests, multiSkillNames)
 		if err != nil {
 			return err
@@ -182,7 +215,14 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 	case skillSetupModeMono:
 		installed, skipped, err = skillSetupInstallMono(skillSrc, dests, out, errOut)
 	case skillSetupModeMulti:
-		installed, skipped, err = skillSetupInstallMulti(skillSrc, multiSkillNames, dests, out, errOut)
+		installed, skipped, err = installMultiSkillsWithEventMigration(
+			skillSrc,
+			multiSkillNames,
+			dests,
+			migrateEventMiscTargets,
+			out,
+			errOut,
+		)
 	default:
 		return fmt.Errorf("内部错误：未知 mode %q", mode)
 	}
@@ -191,6 +231,7 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 	}
 
 	fmt.Fprintf(out, "\n✅ Skill 安装完成（mode=%s, installed=%d, skipped=%d）\n", mode, installed, skipped)
+	fmt.Fprintln(out, "ℹ️  若 Agent 会话已打开，请重启 Agent 或重新加载 Skills 后再验证路由。")
 	return nil
 }
 
@@ -204,6 +245,226 @@ const multiSkillPrefix = "dingtalk-"
 // dingtalk-shared that was never installed.
 const multiSharedSkill = "dingtalk-shared"
 
+// legacyMultiSharedSkill is the retired name shipped by older multi-skill
+// bundles. Once the replacement has been installed successfully, remove this
+// exact directory so Agent discovery cannot load both routing contracts.
+const legacyMultiSharedSkill = "dws-shared"
+
+const (
+	multiEventSkill = "dingtalk-event"
+	multiMiscSkill  = "dingtalk-misc"
+)
+
+var eventMigrationRequiredReferences = []string{
+	"event-im.md",
+	"event-im-keys.md",
+	"event-im-lifecycle.md",
+	"event-im-operations.md",
+	"event-im-output.md",
+	"event-oa.md",
+}
+
+func containsSkillName(names []string, want string) bool {
+	for _, name := range names {
+		if name == want {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizedSkillListContains(raw []string, want string) bool {
+	for _, name := range raw {
+		if normalizeMultiSkillName(name) == want {
+			return true
+		}
+	}
+	return false
+}
+
+// findFoldedEventMiscTargets identifies the short-lived multi-skill layout in
+// which personal Event routing lived inside dingtalk-misc. Both markers are
+// required so an unrelated misc install is never treated as a migration target.
+func findFoldedEventMiscTargets(dests []string) []string {
+	var targets []string
+	for _, dest := range dests {
+		miscRoot := filepath.Join(dest, multiMiscSkill)
+		skillBody, err := os.ReadFile(filepath.Join(miscRoot, "SKILL.md"))
+		if err != nil || !containsPersonalEventRoute(skillBody) {
+			continue
+		}
+		eventRef, err := skillSetupStat(filepath.Join(miscRoot, "references", "event.md"))
+		if err != nil || eventRef.IsDir() {
+			continue
+		}
+		targets = append(targets, dest)
+	}
+	sort.Strings(targets)
+	return targets
+}
+
+func containsPersonalEventRoute(skillBody []byte) bool {
+	body := strings.ToLower(string(skillBody))
+	for _, marker := range []string{
+		"dws event",
+		"个人 event",
+		"个人 im 事件",
+		"个人 im/oa",
+		"personal event",
+	} {
+		if strings.Contains(body, marker) {
+			return true
+		}
+	}
+	return false
+}
+
+func printEventMiscMigrationPreview(out io.Writer, targets []string, installsCompanion bool) {
+	if len(targets) == 0 {
+		return
+	}
+	action := "将原子切换 dingtalk-event 与本次已选择的干净 dingtalk-misc"
+	if installsCompanion {
+		action = "将原子切换 dingtalk-event，并额外安装干净的 dingtalk-misc 作为迁移伴侣（仅限以下目标）"
+	}
+	fmt.Fprintf(out, "Event Skill 迁移：%s：\n", action)
+	for _, target := range targets {
+		fmt.Fprintf(out, "  - %s\n", target)
+	}
+}
+
+func validateEventMiscMigrationSource(src string) error {
+	if err := validateEventMigrationSkillRoot(filepath.Join(src, multiEventSkill)); err != nil {
+		return fmt.Errorf("event Skill 迁移源无效: %w", err)
+	}
+	if err := validateMigrationSkillRoot(filepath.Join(src, multiMiscSkill), multiMiscSkill, nil); err != nil {
+		return fmt.Errorf("event Skill 迁移源无效: %w", err)
+	}
+
+	if err := validateCleanEventMiscRoot(filepath.Join(src, multiMiscSkill)); err != nil {
+		return fmt.Errorf("event Skill 迁移源无效: %w", err)
+	}
+	return nil
+}
+
+func validateEventMigrationSkillRoot(root string) error {
+	required := make([]string, 0, len(eventMigrationRequiredReferences))
+	for _, name := range eventMigrationRequiredReferences {
+		required = append(required, filepath.Join("references", name))
+	}
+	return validateMigrationSkillRoot(root, multiEventSkill, required)
+}
+
+func validateMigrationSkillRoot(root, expectedName string, requiredFiles []string) error {
+	skillPath := filepath.Join(root, "SKILL.md")
+	skillBody, err := os.ReadFile(skillPath)
+	if err != nil {
+		return fmt.Errorf("无法读取 %s: %w", skillPath, err)
+	}
+	name, err := parseMigrationSkillFrontmatter(skillBody)
+	if err != nil {
+		return fmt.Errorf("%s 无效: %w", skillPath, err)
+	}
+	if name != expectedName {
+		return fmt.Errorf("%s 的 name=%q，期望 %q", skillPath, name, expectedName)
+	}
+	for _, rel := range requiredFiles {
+		path := filepath.Join(root, rel)
+		info, statErr := skillSetupStat(path)
+		if statErr != nil || info.IsDir() {
+			if statErr == nil {
+				statErr = errors.New("is a directory")
+			}
+			return fmt.Errorf("缺少有效文件 %s: %w", path, statErr)
+		}
+		body, readErr := os.ReadFile(path)
+		if readErr != nil {
+			return fmt.Errorf("无法读取 %s: %w", path, readErr)
+		}
+		if strings.TrimSpace(string(body)) == "" {
+			return fmt.Errorf("文件为空 %s", path)
+		}
+	}
+	return nil
+}
+
+func parseMigrationSkillFrontmatter(body []byte) (string, error) {
+	normalized := strings.ReplaceAll(string(body), "\r\n", "\n")
+	lines := strings.Split(normalized, "\n")
+	if len(lines) == 0 || strings.TrimSpace(lines[0]) != "---" {
+		return "", errors.New("缺少 YAML frontmatter")
+	}
+	name := ""
+	description := ""
+	closingLine := -1
+	for i := 1; i < len(lines); i++ {
+		rawLine := lines[i]
+		line := strings.TrimSpace(rawLine)
+		if line == "---" {
+			closingLine = i
+			break
+		}
+		// Only inspect top-level frontmatter keys. Nested metadata may legally
+		// contain its own `name` without changing the Skill identity.
+		if strings.TrimLeft(rawLine, " \t") != rawLine {
+			continue
+		}
+		key, value, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		value = strings.Trim(strings.TrimSpace(value), "\"'")
+		switch strings.TrimSpace(key) {
+		case "name":
+			if name != "" {
+				return "", errors.New("frontmatter 含重复 name")
+			}
+			name = value
+		case "description":
+			description = value
+		}
+	}
+	if closingLine < 0 {
+		return "", errors.New("YAML frontmatter 未闭合")
+	}
+	if name == "" {
+		return "", errors.New("frontmatter 缺少 name")
+	}
+	if description == "" {
+		return "", errors.New("frontmatter 缺少 description")
+	}
+	if strings.TrimSpace(strings.Join(lines[closingLine+1:], "\n")) == "" {
+		return "", errors.New("SKILL.md 正文为空")
+	}
+	return name, nil
+}
+
+func validateCleanEventMiscRoot(miscRoot string) error {
+	miscSkillPath := filepath.Join(miscRoot, "SKILL.md")
+	miscBody, err := os.ReadFile(miscSkillPath)
+	if err != nil {
+		return fmt.Errorf("无法读取 %s: %w", miscSkillPath, err)
+	}
+	if containsPersonalEventRoute(miscBody) {
+		return fmt.Errorf("%s 仍包含个人 Event 路由", miscSkillPath)
+	}
+	refsRoot := filepath.Join(miscRoot, "references")
+	entries, err := skillSetupReadDir(refsRoot)
+	if errors.Is(err, os.ErrNotExist) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("无法检查 %s: %w", refsRoot, err)
+	}
+	for _, entry := range entries {
+		name := strings.ToLower(entry.Name())
+		if !entry.IsDir() && strings.HasPrefix(name, "event") && strings.HasSuffix(name, ".md") {
+			return fmt.Errorf("%s 仍存在折叠 Event 参考页", filepath.Join(refsRoot, entry.Name()))
+		}
+	}
+	return nil
+}
+
 // ensureMandatorySharedSkill guarantees the shared dependency skill is included
 // whenever it exists in the source, even if --skill / --exclude narrowed it out.
 func ensureMandatorySharedSkill(selected, all []string) []string {
@@ -607,6 +868,21 @@ func cleanupMutualExclusion(dest, mode string, out, errOut io.Writer) {
 	}
 }
 
+func cleanupLegacyMultiSharedSkill(dest string, out, errOut io.Writer) {
+	legacyPath := filepath.Join(dest, legacyMultiSharedSkill)
+	if _, err := skillSetupStat(legacyPath); err != nil {
+		if !errors.Is(err, os.ErrNotExist) {
+			fmt.Fprintf(errOut, "  ⚠️  无法检查已退役 Skill 残留 %s: %v\n", legacyPath, err)
+		}
+		return
+	}
+	if err := skillSetupRemoveAll(legacyPath); err != nil {
+		fmt.Fprintf(errOut, "  ⚠️  已退役 Skill 清理失败（已安装 %s） %s: %v\n", multiSharedSkill, legacyPath, err)
+		return
+	}
+	fmt.Fprintf(out, "  × 已清理已退役 Skill 残留 %s\n", legacyPath)
+}
+
 func installSkillToHomes(src string, dests []string, out, errOut io.Writer) (installed, skipped int, err error) {
 	sort.Strings(dests)
 	for _, dest := range dests {
@@ -634,6 +910,299 @@ func installSkillToHomes(src string, dests []string, out, errOut io.Writer) (ins
 	return installed, skipped, nil
 }
 
+func installMultiSkillsWithEventMigration(
+	src string,
+	skillNames []string,
+	dests []string,
+	migrationTargets []string,
+	out, errOut io.Writer,
+) (installed, skipped int, err error) {
+	if len(migrationTargets) == 0 {
+		return skillSetupInstallMulti(src, skillNames, dests, out, errOut)
+	}
+
+	migrationSet := make(map[string]struct{}, len(migrationTargets))
+	for _, dest := range migrationTargets {
+		migrationSet[dest] = struct{}{}
+	}
+	var ordinaryTargets []string
+	for _, dest := range dests {
+		if _, migrates := migrationSet[dest]; !migrates {
+			ordinaryTargets = append(ordinaryTargets, dest)
+		}
+	}
+
+	if len(ordinaryTargets) > 0 {
+		var n, nSkipped int
+		n, nSkipped, err = skillSetupInstallMulti(src, skillNames, ordinaryTargets, out, errOut)
+		installed += n
+		skipped += nSkipped
+		if err != nil {
+			return installed, skipped, err
+		}
+		if nSkipped > 0 {
+			return installed, skipped, fmt.Errorf("multi Skill 安装不完整（skipped=%d）；已保留折叠版 Event/misc，未执行迁移", nSkipped)
+		}
+	}
+
+	// The folded pair is excluded from the ordinary best-effort installer. All
+	// other selected skills (especially dingtalk-shared) must succeed before the
+	// old Event route is touched.
+	for _, dest := range migrationTargets {
+		cleanupMutualExclusion(dest, skillSetupModeMulti, out, errOut)
+	}
+	var prerequisiteNames []string
+	for _, name := range skillNames {
+		if name != multiEventSkill && name != multiMiscSkill {
+			prerequisiteNames = append(prerequisiteNames, name)
+		}
+	}
+	if len(prerequisiteNames) > 0 {
+		var n, nSkipped int
+		n, nSkipped, err = skillSetupInstallMulti(src, prerequisiteNames, migrationTargets, out, errOut)
+		installed += n
+		skipped += nSkipped
+		if err != nil {
+			return installed, skipped, err
+		}
+		if nSkipped > 0 {
+			return installed, skipped, fmt.Errorf("event Skill 迁移前置安装不完整（skipped=%d）；已保留折叠版 Event/misc", nSkipped)
+		}
+	}
+
+	migrated, migrationErr := migrateEventMiscAtomically(src, migrationTargets, out, errOut)
+	installed += migrated
+	if migrationErr != nil {
+		return installed, skipped, migrationErr
+	}
+	return installed, skipped, nil
+}
+
+type eventMiscMigration struct {
+	dest string
+
+	stageRoot   string
+	stagedEvent string
+	stagedMisc  string
+	backupEvent string
+	backupMisc  string
+
+	eventPath string
+	miscPath  string
+
+	eventBackedUp   bool
+	miscBackedUp    bool
+	newEventEnabled bool
+	newMiscEnabled  bool
+}
+
+func prepareEventMiscMigration(src, dest string) (*eventMiscMigration, error) {
+	stageRoot, err := skillSetupMkdirTemp(dest, ".dws-event-migration-")
+	if err != nil {
+		return nil, fmt.Errorf("无法在目标文件系统创建 Event Skill 迁移 staging %s: %w", dest, err)
+	}
+	migration := &eventMiscMigration{
+		dest:        dest,
+		stageRoot:   stageRoot,
+		stagedEvent: filepath.Join(stageRoot, "new-event"),
+		stagedMisc:  filepath.Join(stageRoot, "new-misc"),
+		backupEvent: filepath.Join(stageRoot, "old-event"),
+		backupMisc:  filepath.Join(stageRoot, "old-misc"),
+		eventPath:   filepath.Join(dest, multiEventSkill),
+		miscPath:    filepath.Join(dest, multiMiscSkill),
+	}
+	cleanupOnError := func(cause error) (*eventMiscMigration, error) {
+		if cleanupErr := skillSetupRemoveAll(stageRoot); cleanupErr != nil {
+			cause = errors.Join(cause, fmt.Errorf("清理 staging %s 失败: %w", stageRoot, cleanupErr))
+		}
+		return nil, cause
+	}
+
+	if err := skillSetupCopyDir(filepath.Join(src, multiEventSkill), migration.stagedEvent); err != nil {
+		return cleanupOnError(fmt.Errorf("预备 dingtalk-event 失败 %s: %w", dest, err))
+	}
+	if err := skillSetupCopyDir(filepath.Join(src, multiMiscSkill), migration.stagedMisc); err != nil {
+		return cleanupOnError(fmt.Errorf("预备 dingtalk-misc 失败 %s: %w", dest, err))
+	}
+	if err := validateEventMigrationSkillRoot(migration.stagedEvent); err != nil {
+		return cleanupOnError(fmt.Errorf("迁移 staging 验证失败 %s: %w", migration.stagedEvent, err))
+	}
+	if err := validateMigrationSkillRoot(migration.stagedMisc, multiMiscSkill, nil); err != nil {
+		return cleanupOnError(fmt.Errorf("迁移 staging 验证失败 %s: %w", migration.stagedMisc, err))
+	}
+	if err := validateCleanEventMiscRoot(migration.stagedMisc); err != nil {
+		return cleanupOnError(fmt.Errorf("迁移 staging 验证失败 %s: %w", migration.stagedMisc, err))
+	}
+	return migration, nil
+}
+
+func migrateEventMiscAtomically(src string, dests []string, out, errOut io.Writer) (int, error) {
+	sortedDests := append([]string(nil), dests...)
+	sort.Strings(sortedDests)
+	migrations := make([]*eventMiscMigration, 0, len(sortedDests))
+
+	// Stage every target before switching any target. This prevents a source or
+	// copy failure on a later Agent home from leaving earlier homes upgraded.
+	for _, dest := range sortedDests {
+		migration, err := prepareEventMiscMigration(src, dest)
+		if err != nil {
+			if cleanupErr := cleanupEventMiscStages(migrations, false, errOut); cleanupErr != nil {
+				err = errors.Join(err, cleanupErr)
+			}
+			return 0, err
+		}
+		migrations = append(migrations, migration)
+	}
+
+	committed := make([]*eventMiscMigration, 0, len(migrations))
+	for _, migration := range migrations {
+		if err := commitEventMiscMigration(migration); err != nil {
+			rollbackErr := rollbackEventMiscMigrations(committed)
+			if rollbackErr != nil {
+				err = errors.Join(err, fmt.Errorf("已切换目标回滚失败: %w", rollbackErr))
+			}
+			var recoveryRoots []string
+			for _, candidate := range migrations {
+				if eventMiscMigrationNeedsRecovery(candidate) {
+					recoveryRoots = append(recoveryRoots, candidate.stageRoot)
+				}
+			}
+			if len(recoveryRoots) > 0 {
+				err = errors.Join(err, fmt.Errorf("回滚不完整，已保留恢复目录（请勿删除）: %s", strings.Join(recoveryRoots, ", ")))
+			}
+			if cleanupErr := cleanupEventMiscStages(migrations, true, errOut); cleanupErr != nil {
+				err = errors.Join(err, cleanupErr)
+			}
+			return 0, err
+		}
+		committed = append(committed, migration)
+	}
+
+	for _, migration := range migrations {
+		fmt.Fprintf(out, "  ✓ %s\n", migration.eventPath)
+		fmt.Fprintf(out, "  ✓ %s（Event 原子迁移）\n", migration.miscPath)
+	}
+	if cleanupErr := cleanupEventMiscStages(migrations, false, errOut); cleanupErr != nil {
+		fmt.Fprintf(errOut, "  ⚠️  Event Skill 迁移已完成，但 staging 清理不完整: %v\n", cleanupErr)
+	}
+	return len(migrations) * 2, nil
+}
+
+func cleanupEventMiscStages(migrations []*eventMiscMigration, preserveRecovery bool, errOut io.Writer) error {
+	var cleanupErr error
+	for _, migration := range migrations {
+		if preserveRecovery && eventMiscMigrationNeedsRecovery(migration) {
+			fmt.Fprintf(errOut, "  ⚠️  已保留 Event Skill 恢复目录 %s\n", migration.stageRoot)
+			continue
+		}
+		if err := skillSetupRemoveAll(migration.stageRoot); err != nil {
+			cleanupErr = errors.Join(cleanupErr, fmt.Errorf("清理 Event Skill staging %s 失败: %w", migration.stageRoot, err))
+		}
+	}
+	return cleanupErr
+}
+
+func eventMiscMigrationNeedsRecovery(migration *eventMiscMigration) bool {
+	return migration.eventBackedUp || migration.miscBackedUp || migration.newEventEnabled || migration.newMiscEnabled
+}
+
+func commitEventMiscMigration(migration *eventMiscMigration) error {
+	eventExists, err := skillSetupPathExists(migration.eventPath)
+	if err != nil {
+		return fmt.Errorf("无法检查旧 dingtalk-event %s: %w", migration.dest, err)
+	}
+	miscExists, err := skillSetupPathExists(migration.miscPath)
+	if err != nil {
+		return fmt.Errorf("无法检查旧 dingtalk-misc %s: %w", migration.dest, err)
+	}
+	if !miscExists {
+		return fmt.Errorf("event Skill 迁移中止：折叠版 dingtalk-misc 已不存在 %s", migration.dest)
+	}
+
+	rollbackFailure := func(cause error) error {
+		if rollbackErr := rollbackEventMiscMigration(migration); rollbackErr != nil {
+			return errors.Join(cause, fmt.Errorf("回滚 Event/misc 失败 %s: %w", migration.dest, rollbackErr))
+		}
+		return cause
+	}
+	if eventExists {
+		if err := skillSetupRename(migration.eventPath, migration.backupEvent); err != nil {
+			return fmt.Errorf("备份旧 dingtalk-event 失败 %s: %w", migration.dest, err)
+		}
+		migration.eventBackedUp = true
+	}
+	if err := skillSetupRename(migration.stagedEvent, migration.eventPath); err != nil {
+		return rollbackFailure(fmt.Errorf("切换 dingtalk-event 失败 %s: %w", migration.dest, err))
+	}
+	migration.newEventEnabled = true
+	if err := skillSetupRename(migration.miscPath, migration.backupMisc); err != nil {
+		return rollbackFailure(fmt.Errorf("备份旧 dingtalk-misc 失败 %s: %w", migration.dest, err))
+	}
+	migration.miscBackedUp = true
+	if err := skillSetupRename(migration.stagedMisc, migration.miscPath); err != nil {
+		return rollbackFailure(fmt.Errorf("切换 dingtalk-misc 失败 %s: %w", migration.dest, err))
+	}
+	migration.newMiscEnabled = true
+	return nil
+}
+
+func rollbackEventMiscMigrations(migrations []*eventMiscMigration) error {
+	var rollbackErr error
+	for i := len(migrations) - 1; i >= 0; i-- {
+		if err := rollbackEventMiscMigration(migrations[i]); err != nil {
+			rollbackErr = errors.Join(rollbackErr, err)
+		}
+	}
+	return rollbackErr
+}
+
+func rollbackEventMiscMigration(migration *eventMiscMigration) error {
+	move := func(enabled *bool, from, to, label string) error {
+		if !*enabled {
+			return nil
+		}
+		if err := skillSetupRename(from, to); err != nil {
+			return fmt.Errorf("%s: %w", label, err)
+		}
+		*enabled = false
+		return nil
+	}
+
+	// Stop at the first rollback failure. In particular, do not remove the
+	// already-working standalone Event while the folded misc route has not been
+	// restored: even an incomplete rollback must leave at least one Event entry
+	// point live and preserve the remaining assets in staging for recovery.
+	steps := []struct {
+		enabled *bool
+		from    string
+		to      string
+		label   string
+	}{
+		{&migration.newMiscEnabled, migration.miscPath, migration.stagedMisc, "移出新 dingtalk-misc"},
+		{&migration.miscBackedUp, migration.backupMisc, migration.miscPath, "恢复旧 dingtalk-misc"},
+		{&migration.newEventEnabled, migration.eventPath, migration.stagedEvent, "移出新 dingtalk-event"},
+		{&migration.eventBackedUp, migration.backupEvent, migration.eventPath, "恢复旧 dingtalk-event"},
+	}
+	for _, step := range steps {
+		if err := move(step.enabled, step.from, step.to, step.label); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func skillSetupPathExists(path string) (bool, error) {
+	_, err := skillSetupStat(path)
+	switch {
+	case err == nil:
+		return true, nil
+	case errors.Is(err, os.ErrNotExist):
+		return false, nil
+	default:
+		return false, err
+	}
+}
+
 // installMultiSkillToHomes installs each subdir of src (dingtalk-*) into
 // dest as a sibling skill directory. installed/skipped is counted per
 // (agent-home × sub-skill) pair so the user sees granular progress.
@@ -649,6 +1218,7 @@ func installMultiSkillToHomes(src string, skillNames []string, dests []string, o
 			continue
 		}
 
+		sharedInstalled := false
 		for _, name := range skillNames {
 			subSrc := filepath.Join(src, name)
 			subDest := filepath.Join(dest, name)
@@ -664,6 +1234,12 @@ func installMultiSkillToHomes(src string, skillNames []string, dests []string, o
 			}
 			fmt.Fprintf(out, "  ✓ %s\n", subDest)
 			installed++
+			if name == multiSharedSkill {
+				sharedInstalled = true
+			}
+		}
+		if sharedInstalled {
+			cleanupLegacyMultiSharedSkill(dest, out, errOut)
 		}
 	}
 	return installed, skipped, nil

internal/app/skill_setup_embed_test.go

@@ -58,8 +58,9 @@ func TestMaterializeEmbeddedSkillSourceMono(t *testing.T) {
 }
 
 // TestMaterializeEmbeddedSkillSourceMulti verifies that the peer multi bundle
-// contains both the shared routing skill and misc (including folded PAT docs). Structured
-// Schema hints are build inputs and must not become a third installable mode.
+// contains the standalone Event skill, shared routing skill, and clean misc
+// (including PAT docs). Structured Schema hints are build inputs and must not
+// become a third installable mode.
 func TestMaterializeEmbeddedSkillSourceMulti(t *testing.T) {
 	dir, cleanup, err := materializeEmbeddedSkillSource(skillSetupModeMulti)
 	if err != nil {
@@ -71,6 +72,8 @@ func TestMaterializeEmbeddedSkillSourceMulti(t *testing.T) {
 		t.Fatalf("extracted dir %s is not a valid multi skill source root", dir)
 	}
 	for _, rel := range []string{
+		filepath.Join("dingtalk-event", "SKILL.md"),
+		filepath.Join("dingtalk-event", "references", "event-oa.md"),
 		filepath.Join("dingtalk-shared", "SKILL.md"),
 		filepath.Join("dingtalk-misc", "SKILL.md"),
 		filepath.Join("dingtalk-misc", "references", "pat.md"),
@@ -79,6 +82,11 @@ func TestMaterializeEmbeddedSkillSourceMulti(t *testing.T) {
 			t.Errorf("expected embedded multi skill to contain %s: %v", rel, err)
 		}
 	}
+	if _, err := os.Stat(filepath.Join(dir, "dingtalk-misc", "references", "event.md")); err == nil {
+		t.Fatal("embedded misc must not retain the folded personal Event reference")
+	} else if !os.IsNotExist(err) {
+		t.Fatalf("stat embedded misc event reference: %v", err)
+	}
 	if _, err := os.Stat(filepath.Join(dir, "schema-hints")); err == nil {
 		t.Fatal("embedded multi skill must not contain build-only schema-hints")
 	} else if !os.IsNotExist(err) {

internal/app/skill_setup_full_coverage_test.go

@@ -7,9 +7,11 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/charmbracelet/huh"
 	"github.com/spf13/cobra"
 )
@@ -120,12 +122,112 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 	}
 }
 
+func TestCrossPlatformCoverageSkillSetupMigratesLegacySharedAfterReplacement(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiSharedSkill, "dingtalk-chat"})
+	home := filepath.Join(t.TempDir(), "skills")
+	legacyPath := filepath.Join(home, legacyMultiSharedSkill)
+	customPath := filepath.Join(home, "custom-skill")
+	for _, path := range []string{legacyPath, customPath} {
+		if err := os.MkdirAll(path, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(path, "SKILL.md"), []byte("legacy or custom\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	var out, errOut bytes.Buffer
+	installed, skipped, err := installMultiSkillToHomes(
+		src,
+		[]string{multiSharedSkill, "dingtalk-chat"},
+		[]string{home},
+		&out,
+		&errOut,
+	)
+	if err != nil || installed != 2 || skipped != 0 {
+		t.Fatalf("install = %d/%d, err=%v, stderr=%s", installed, skipped, err, errOut.String())
+	}
+	if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+		t.Fatalf("legacy shared skill still exists: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(home, multiSharedSkill, "SKILL.md")); err != nil {
+		t.Fatalf("replacement shared skill missing: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(customPath, "SKILL.md")); err != nil {
+		t.Fatalf("unrelated custom skill changed: %v", err)
+	}
+	if !strings.Contains(out.String(), "已清理已退役 Skill 残留") {
+		t.Fatalf("legacy cleanup was not reported: %s", out.String())
+	}
+
+	t.Run("failed replacement preserves legacy", func(t *testing.T) {
+		missingSource := t.TempDir()
+		failureHome := filepath.Join(t.TempDir(), "skills")
+		failureLegacy := filepath.Join(failureHome, legacyMultiSharedSkill)
+		if err := os.MkdirAll(failureLegacy, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(failureLegacy, "SKILL.md"), []byte("legacy\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+
+		var failureOut, failureErr bytes.Buffer
+		installed, skipped, err := installMultiSkillToHomes(
+			missingSource,
+			[]string{multiSharedSkill},
+			[]string{failureHome},
+			&failureOut,
+			&failureErr,
+		)
+		if err != nil || installed != 0 || skipped != 1 {
+			t.Fatalf("failed replacement = %d/%d, err=%v", installed, skipped, err)
+		}
+		if _, err := os.Stat(filepath.Join(failureLegacy, "SKILL.md")); err != nil {
+			t.Fatalf("failed replacement removed legacy shared skill: %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillSetupLegacySharedCleanupFailures(t *testing.T) {
+	fail := errors.New("legacy cleanup failure")
+
+	t.Run("missing legacy is a no-op", func(t *testing.T) {
+		var out, errOut bytes.Buffer
+		cleanupLegacyMultiSharedSkill(t.TempDir(), &out, &errOut)
+		if out.Len() != 0 || errOut.Len() != 0 {
+			t.Fatalf("missing legacy emitted output: stdout=%q stderr=%q", out.String(), errOut.String())
+		}
+	})
+
+	t.Run("stat failure is reported", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, fail })
+		var out, errOut bytes.Buffer
+		cleanupLegacyMultiSharedSkill("dest", &out, &errOut)
+		if out.Len() != 0 || !strings.Contains(errOut.String(), "无法检查已退役 Skill 残留") {
+			t.Fatalf("stat failure output: stdout=%q stderr=%q", out.String(), errOut.String())
+		}
+	})
+
+	t.Run("remove failure is reported", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+			return skillSetupFileInfo{name: filepath.Base(path), mode: os.ModeDir}, nil
+		})
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return fail })
+		var out, errOut bytes.Buffer
+		cleanupLegacyMultiSharedSkill("dest", &out, &errOut)
+		if out.Len() != 0 || !strings.Contains(errOut.String(), "已退役 Skill 清理失败") {
+			t.Fatalf("remove failure output: stdout=%q stderr=%q", out.String(), errOut.String())
+		}
+	})
+}
+
 func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T) {
 	oldRunForm, oldInteractive := skillSetupRunForm, skillSetupInteractive
 	oldReadDir, oldStat := skillSetupReadDir, skillSetupStat
 	oldExecutable, oldGetwd, oldHome := skillSetupExecutable, skillSetupGetwd, skillSetupUserHomeDir
 	oldRemove, oldMkdir := skillSetupRemoveAll, skillSetupMkdirAll
 	oldCopyDir, oldWalk, oldRel := skillSetupCopyDir, skillSetupWalk, skillSetupRel
+	oldMkdirTemp, oldRename := skillSetupMkdirTemp, skillSetupRename
 	oldReadlink, oldOpen, oldOpenFile, oldCopy := skillSetupReadlink, skillSetupOpen, skillSetupOpenFile, skillSetupCopy
 	t.Cleanup(func() {
 		skillSetupRunForm, skillSetupInteractive = oldRunForm, oldInteractive
@@ -133,6 +235,7 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 		skillSetupExecutable, skillSetupGetwd, skillSetupUserHomeDir = oldExecutable, oldGetwd, oldHome
 		skillSetupRemoveAll, skillSetupMkdirAll = oldRemove, oldMkdir
 		skillSetupCopyDir, skillSetupWalk, skillSetupRel = oldCopyDir, oldWalk, oldRel
+		skillSetupMkdirTemp, skillSetupRename = oldMkdirTemp, oldRename
 		skillSetupReadlink, skillSetupOpen, skillSetupOpenFile, skillSetupCopy = oldReadlink, oldOpen, oldOpenFile, oldCopy
 	})
 	fail := errors.New("failure")
@@ -310,3 +413,236 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	}
 	_ = fs.ValidPath("path")
 }
+
+func TestCrossPlatformCoverageSkillSetupEventMigrationFailureBranches(t *testing.T) {
+	fail := errors.New("injected failure")
+	validSkill := func(name string) []byte {
+		return []byte("---\nname: " + name + "\ndescription: valid migration skill\n---\n\n# Skill\n")
+	}
+
+	t.Run("folded discovery rejects directory reference", func(t *testing.T) {
+		dest := t.TempDir()
+		miscRoot := filepath.Join(dest, multiMiscSkill)
+		if err := os.MkdirAll(miscRoot, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(miscRoot, "SKILL.md"), []byte("dws event\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+			if strings.HasSuffix(path, filepath.Join("references", "event.md")) {
+				return skillSetupFileInfo{name: "event.md", mode: os.ModeDir}, nil
+			}
+			return os.Stat(path)
+		})
+		if got := findFoldedEventMiscTargets([]string{dest}); len(got) != 0 {
+			t.Fatalf("directory event reference accepted: %#v", got)
+		}
+	})
+
+	t.Run("migration root validation failures", func(t *testing.T) {
+		if err := validateMigrationSkillRoot(filepath.Join(t.TempDir(), "missing"), multiEventSkill, nil); err == nil {
+			t.Fatal("missing SKILL.md succeeded")
+		}
+
+		root := t.TempDir()
+		if err := os.WriteFile(filepath.Join(root, "SKILL.md"), validSkill(multiEventSkill), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.MkdirAll(filepath.Join(root, "references", "directory.md"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := validateMigrationSkillRoot(root, multiEventSkill, []string{filepath.Join("references", "directory.md")}); err == nil || !strings.Contains(err.Error(), "is a directory") {
+			t.Fatalf("directory required file = %v", err)
+		}
+
+		missing := filepath.Join("references", "missing.md")
+		testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+			if path == filepath.Join(root, missing) {
+				return skillSetupFileInfo{name: "missing.md"}, nil
+			}
+			return os.Stat(path)
+		})
+		if err := validateMigrationSkillRoot(root, multiEventSkill, []string{missing}); err == nil || !strings.Contains(err.Error(), "无法读取") {
+			t.Fatalf("unreadable required file = %v", err)
+		}
+	})
+
+	t.Run("frontmatter validation branches", func(t *testing.T) {
+		validWithIgnoredLine := []byte("---\nignored line\nname: dingtalk-event\ndescription: valid\n---\n\nbody\n")
+		if name, err := parseMigrationSkillFrontmatter(validWithIgnoredLine); err != nil || name != multiEventSkill {
+			t.Fatalf("ignored frontmatter line = %q, %v", name, err)
+		}
+		for name, body := range map[string][]byte{
+			"duplicate name": []byte("---\nname: one\nname: two\ndescription: valid\n---\nbody\n"),
+			"unclosed":       []byte("---\nname: one\ndescription: valid\nbody\n"),
+			"missing name":   []byte("---\ndescription: valid\n---\nbody\n"),
+			"missing desc":   []byte("---\nname: one\n---\nbody\n"),
+			"empty body":     []byte("---\nname: one\ndescription: valid\n---\n  \n"),
+		} {
+			t.Run(name, func(t *testing.T) {
+				if _, err := parseMigrationSkillFrontmatter(body); err == nil {
+					t.Fatal("invalid frontmatter succeeded")
+				}
+			})
+		}
+	})
+
+	t.Run("clean misc validation branches", func(t *testing.T) {
+		if err := validateCleanEventMiscRoot(filepath.Join(t.TempDir(), "missing")); err == nil {
+			t.Fatal("missing misc root succeeded")
+		}
+
+		routed := t.TempDir()
+		if err := os.WriteFile(filepath.Join(routed, "SKILL.md"), append(validSkill(multiMiscSkill), []byte("dws event\n")...), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := validateCleanEventMiscRoot(routed); err == nil || !strings.Contains(err.Error(), "仍包含个人 Event 路由") {
+			t.Fatalf("routed misc = %v", err)
+		}
+
+		clean := t.TempDir()
+		if err := os.WriteFile(filepath.Join(clean, "SKILL.md"), validSkill(multiMiscSkill), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := validateCleanEventMiscRoot(clean); err != nil {
+			t.Fatalf("missing references should be clean: %v", err)
+		}
+
+		testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, fail })
+		if err := validateCleanEventMiscRoot(clean); !errors.Is(err, fail) {
+			t.Fatalf("read-dir failure = %v", err)
+		}
+	})
+
+	t.Run("ordinary and prerequisite install errors", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupInstallMulti, func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+			return 0, 0, fail
+		})
+		migration := filepath.Join(t.TempDir(), "migration")
+		ordinary := filepath.Join(t.TempDir(), "ordinary")
+		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill}, []string{migration, ordinary}, []string{migration}, io.Discard, io.Discard); !errors.Is(err, fail) {
+			t.Fatalf("ordinary install failure = %v", err)
+		}
+		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill, multiMiscSkill, multiSharedSkill}, []string{migration}, []string{migration}, io.Discard, io.Discard); !errors.Is(err, fail) {
+			t.Fatalf("prerequisite install failure = %v", err)
+		}
+	})
+
+	t.Run("preparation cleanup and staged misc validation", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		dest := t.TempDir()
+		testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { return fail })
+		cleanupFail := errors.New("cleanup failure")
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupFail })
+		if _, err := prepareEventMiscMigration(src, dest); err == nil || !errors.Is(err, fail) || !errors.Is(err, cleanupFail) {
+			t.Fatalf("joined preparation cleanup error = %v", err)
+		}
+	})
+
+	t.Run("invalid staged misc root", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		if err := os.WriteFile(filepath.Join(src, multiMiscSkill, "SKILL.md"), validSkill(multiEventSkill), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := prepareEventMiscMigration(src, t.TempDir()); err == nil || !strings.Contains(err.Error(), "staging 验证失败") {
+			t.Fatalf("invalid staged misc = %v", err)
+		}
+	})
+
+	t.Run("later staging failure joins cleanup error", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		first := filepath.Join(t.TempDir(), "a")
+		second := filepath.Join(t.TempDir(), "b")
+		if err := os.MkdirAll(first, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.MkdirAll(second, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		originalMkdirTemp := skillSetupMkdirTemp
+		calls := 0
+		testseam.Swap(t, &skillSetupMkdirTemp, func(dir, pattern string) (string, error) {
+			calls++
+			if calls == 2 {
+				return "", fail
+			}
+			return originalMkdirTemp(dir, pattern)
+		})
+		cleanupFail := errors.New("stage cleanup failure")
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupFail })
+		if _, err := migrateEventMiscAtomically(src, []string{second, first}, io.Discard, io.Discard); err == nil || !errors.Is(err, fail) || !errors.Is(err, cleanupFail) {
+			t.Fatalf("later preparation failure = %v", err)
+		}
+	})
+
+	t.Run("successful migration reports cleanup warning", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		home := filepath.Join(t.TempDir(), "skills")
+		writeFoldedEventMisc(t, home)
+		cleanupFail := errors.New("final cleanup failure")
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupFail })
+		var stderr bytes.Buffer
+		installed, err := migrateEventMiscAtomically(src, []string{home}, io.Discard, &stderr)
+		if err != nil || installed != 2 || !strings.Contains(stderr.String(), cleanupFail.Error()) {
+			t.Fatalf("successful migration cleanup warning: installed=%d err=%v stderr=%s", installed, err, stderr.String())
+		}
+	})
+
+	t.Run("commit rollback and cleanup failures are joined", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		root := t.TempDir()
+		first := filepath.Join(root, "a", "skills")
+		second := filepath.Join(root, "b", "skills")
+		for _, home := range []string{first, second} {
+			writeFoldedEventMisc(t, home)
+			writeOldStandaloneEvent(t, home)
+		}
+		commitFail := errors.New("second commit failure")
+		rollbackFail := errors.New("first rollback failure")
+		originalRename := skillSetupRename
+		testseam.Swap(t, &skillSetupRename, func(oldPath, newPath string) error {
+			if filepath.Base(oldPath) == "new-misc" && newPath == filepath.Join(second, multiMiscSkill) {
+				return commitFail
+			}
+			if filepath.Base(oldPath) == "old-misc" && newPath == filepath.Join(first, multiMiscSkill) {
+				return rollbackFail
+			}
+			return originalRename(oldPath, newPath)
+		})
+		cleanupFail := errors.New("post-rollback cleanup failure")
+		testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return cleanupFail })
+		if _, err := migrateEventMiscAtomically(src, []string{second, first}, io.Discard, io.Discard); err == nil || !errors.Is(err, commitFail) || !errors.Is(err, rollbackFail) || !errors.Is(err, cleanupFail) {
+			t.Fatalf("joined commit/rollback/cleanup error = %v", err)
+		}
+	})
+
+	t.Run("commit preflight and rollback aggregation", func(t *testing.T) {
+		migration := &eventMiscMigration{dest: "dest", eventPath: "event", miscPath: "misc"}
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, fail })
+		if err := commitEventMiscMigration(migration); !errors.Is(err, fail) {
+			t.Fatalf("event stat failure = %v", err)
+		}
+
+		testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+			if path == migration.eventPath {
+				return skillSetupFileInfo{name: "event", mode: os.ModeDir}, nil
+			}
+			return nil, fail
+		})
+		if err := commitEventMiscMigration(migration); !errors.Is(err, fail) {
+			t.Fatalf("misc stat failure = %v", err)
+		}
+
+		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+		if err := commitEventMiscMigration(migration); err == nil || !strings.Contains(err.Error(), "已不存在") {
+			t.Fatalf("missing misc = %v", err)
+		}
+
+		migration.newMiscEnabled = true
+		testseam.Swap(t, &skillSetupRename, func(string, string) error { return fail })
+		if err := rollbackEventMiscMigrations([]*eventMiscMigration{migration}); !errors.Is(err, fail) {
+			t.Fatalf("rollback aggregation = %v", err)
+		}
+	})
+}

internal/app/skill_setup_test.go

@@ -2,6 +2,9 @@ package app
 
 import (
 	"bytes"
+	"errors"
+	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -184,12 +187,20 @@ func writeMultiSkillSource(t *testing.T, names []string) string {
 		if err := os.MkdirAll(filepath.Join(sub, "references"), 0o755); err != nil {
 			t.Fatal(err)
 		}
-		if err := os.WriteFile(filepath.Join(sub, "SKILL.md"), []byte("# "+n), 0o644); err != nil {
+		skillBody := "---\nname: " + n + "\ndescription: test skill\n---\n\n# " + n + "\n"
+		if err := os.WriteFile(filepath.Join(sub, "SKILL.md"), []byte(skillBody), 0o644); err != nil {
 			t.Fatal(err)
 		}
 		if err := os.WriteFile(filepath.Join(sub, "references", n+".md"), []byte("ref "+n), 0o644); err != nil {
 			t.Fatal(err)
 		}
+		if n == multiEventSkill {
+			for _, ref := range eventMigrationRequiredReferences {
+				if err := os.WriteFile(filepath.Join(sub, "references", ref), []byte("ref "+ref+"\n"), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			}
+		}
 	}
 	return root
 }
@@ -549,3 +560,787 @@ func TestResolveSkillSetupSourceMultiFinds(t *testing.T) {
 		t.Fatalf("expected %s, got %s", multiDir, got)
 	}
 }
+
+func executeMultiSkillSetupTest(t *testing.T, src string, dests []string, args ...string) (string, string, error) {
+	t.Helper()
+	originalTargets := skillSetupResolveTargets
+	skillSetupResolveTargets = func(string, string) ([]string, error) {
+		return append([]string(nil), dests...), nil
+	}
+	t.Cleanup(func() { skillSetupResolveTargets = originalTargets })
+
+	cmd := newSkillSetupCommand()
+	cmd.Flags().Bool("dry-run", false, "")
+	var stdout, stderr bytes.Buffer
+	cmd.SetOut(&stdout)
+	cmd.SetErr(&stderr)
+	baseArgs := []string{"--mode", "multi", "--source", src}
+	cmd.SetArgs(append(baseArgs, args...))
+	err := cmd.Execute()
+	return stdout.String(), stderr.String(), err
+}
+
+func writeFoldedEventMisc(t *testing.T, agentHome string) {
+	t.Helper()
+	miscRoot := filepath.Join(agentHome, multiMiscSkill)
+	if err := os.MkdirAll(filepath.Join(miscRoot, "references"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(miscRoot, "SKILL.md"), []byte("personal IM route: dws event consume\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(miscRoot, "references", "event.md"), []byte("folded event docs\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func writeOldStandaloneEvent(t *testing.T, agentHome string) {
+	t.Helper()
+	eventRoot := filepath.Join(agentHome, multiEventSkill)
+	if err := os.MkdirAll(eventRoot, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(eventRoot, "SKILL.md"), []byte("old standalone event\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func assertOldEventMiscPair(t *testing.T, agentHome string) {
+	t.Helper()
+	eventBody, err := os.ReadFile(filepath.Join(agentHome, multiEventSkill, "SKILL.md"))
+	if err != nil || string(eventBody) != "old standalone event\n" {
+		t.Fatalf("old standalone event was not restored: body=%q err=%v", eventBody, err)
+	}
+	miscBody, err := os.ReadFile(filepath.Join(agentHome, multiMiscSkill, "SKILL.md"))
+	if err != nil || !strings.Contains(string(miscBody), "dws event") {
+		t.Fatalf("folded misc was not restored: body=%q err=%v", miscBody, err)
+	}
+	if _, err := os.Stat(filepath.Join(agentHome, multiMiscSkill, "references", "event.md")); err != nil {
+		t.Fatalf("folded Event reference was not restored: %v", err)
+	}
+}
+
+func assertNoEventMigrationStages(t *testing.T, agentHome string) {
+	t.Helper()
+	entries, err := os.ReadDir(agentHome)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), ".dws-event-migration-") {
+			t.Fatalf("unexpected leftover Event migration stage %s", filepath.Join(agentHome, entry.Name()))
+		}
+	}
+}
+
+func TestSkillSetupSelectiveEventMigratesOnlyFoldedTargets(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{
+		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
+	})
+	foldedHome := filepath.Join(t.TempDir(), "folded", "skills")
+	freshHome := filepath.Join(t.TempDir(), "fresh", "skills")
+	writeFoldedEventMisc(t, foldedHome)
+	if err := os.MkdirAll(filepath.Join(foldedHome, multiEventSkill), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(foldedHome, multiEventSkill, "SKILL.md"), []byte("old standalone event\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(foldedHome, "dingtalk-chat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(foldedHome, "dingtalk-chat", "SKILL.md"), []byte("keep sibling\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{freshHome, foldedHome}, "--skill", "event")
+	if err != nil {
+		t.Fatalf("selective event setup failed: %v\nstderr=%s\nstdout=%s", err, stderr, stdout)
+	}
+	if !strings.Contains(stdout, "迁移伴侣") || !strings.Contains(stdout, foldedHome) {
+		t.Fatalf("confirmation output should expose folded misc migration: %s", stdout)
+	}
+	if !strings.Contains(stdout, "重新加载 Skills") {
+		t.Fatalf("completion should tell the user to reload skills: %s", stdout)
+	}
+
+	for _, home := range []string{freshHome, foldedHome} {
+		for _, name := range []string{multiSharedSkill, multiEventSkill} {
+			if _, err := os.Stat(filepath.Join(home, name, "SKILL.md")); err != nil {
+				t.Errorf("%s missing from %s: %v", name, home, err)
+			}
+		}
+		if _, err := os.Stat(filepath.Join(home, "dingtalk-doc")); !os.IsNotExist(err) {
+			t.Errorf("unselected doc appeared in %s: %v", home, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(freshHome, multiMiscSkill)); !os.IsNotExist(err) {
+		t.Fatalf("fresh selective target must not receive misc, stat err=%v", err)
+	}
+	if _, err := os.Stat(filepath.Join(foldedHome, multiMiscSkill, "references", "event.md")); !os.IsNotExist(err) {
+		t.Fatalf("folded event reference survived clean misc replacement, stat err=%v", err)
+	}
+	eventBody, err := os.ReadFile(filepath.Join(foldedHome, multiEventSkill, "SKILL.md"))
+	if err != nil || strings.Contains(string(eventBody), "old standalone") {
+		t.Fatalf("old standalone event was not replaced: body=%q err=%v", eventBody, err)
+	}
+	siblingBody, err := os.ReadFile(filepath.Join(foldedHome, "dingtalk-chat", "SKILL.md"))
+	if err != nil || string(siblingBody) != "keep sibling\n" {
+		t.Fatalf("unrelated sibling changed: body=%q err=%v", siblingBody, err)
+	}
+
+	// A second selective run sees the already-clean misc, does not plan another
+	// migration, and leaves that unselected sibling in place.
+	stdout, stderr, err = executeMultiSkillSetupTest(t, src, []string{freshHome, foldedHome}, "--skill", "event", "--yes")
+	if err != nil {
+		t.Fatalf("idempotent event setup failed: %v\nstderr=%s", err, stderr)
+	}
+	if strings.Contains(stdout, "迁移伴侣") {
+		t.Fatalf("clean second run should not re-detect folded misc: %s", stdout)
+	}
+	if _, err := os.Stat(filepath.Join(foldedHome, multiMiscSkill, "SKILL.md")); err != nil {
+		t.Fatalf("second selective run removed clean misc: %v", err)
+	}
+}
+
+func TestSkillSetupEventMigrationDryRunAndExplicitExclude(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{
+		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
+	})
+
+	t.Run("dry run reports companion without writes", func(t *testing.T) {
+		home := filepath.Join(t.TempDir(), "skills")
+		writeFoldedEventMisc(t, home)
+		stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--dry-run", "--yes")
+		if err != nil {
+			t.Fatalf("dry run failed: %v\nstderr=%s", err, stderr)
+		}
+		if !strings.Contains(stdout, "DRY-RUN") || !strings.Contains(stdout, "迁移伴侣") {
+			t.Fatalf("dry run did not expose migration: %s", stdout)
+		}
+		body, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+		if readErr != nil || !strings.Contains(string(body), "dws event") {
+			t.Fatalf("dry run changed folded misc: body=%q err=%v", body, readErr)
+		}
+		if _, statErr := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(statErr) {
+			t.Fatalf("dry run installed event, stat err=%v", statErr)
+		}
+	})
+
+	t.Run("excluding required misc fails before writes", func(t *testing.T) {
+		home := filepath.Join(t.TempDir(), "skills")
+		writeFoldedEventMisc(t, home)
+		_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--exclude", "misc", "--yes")
+		if err == nil || !strings.Contains(err.Error(), "不能显式 --exclude misc") {
+			t.Fatalf("expected clear migration exclusion error, got %v", err)
+		}
+		if _, statErr := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(statErr) {
+			t.Fatalf("failed migration installed event, stat err=%v", statErr)
+		}
+		body, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+		if readErr != nil || !strings.Contains(string(body), "dws event") {
+			t.Fatalf("failed migration changed misc: body=%q err=%v", body, readErr)
+		}
+	})
+}
+
+func TestSkillSetupEventMigrationRequiresCleanMiscInSource(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+
+	_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "当前 multi 源缺少") {
+		t.Fatalf("expected missing migration companion error, got %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(statErr) {
+		t.Fatalf("failed preflight installed event, stat err=%v", statErr)
+	}
+}
+
+func TestSkillSetupEventMigrationAcceptsShippedMultiBundle(t *testing.T) {
+	wd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	src := filepath.Clean(filepath.Join(wd, "..", "..", "skills", "multi"))
+	if err := validateEventMiscMigrationSource(src); err != nil {
+		t.Fatalf("shipped multi bundle is not a valid Event migration source: %v", err)
+	}
+}
+
+func TestSkillSetupEventMigrationRejectsInvalidSkillBundlesBeforeWrites(t *testing.T) {
+	tests := []struct {
+		name   string
+		mutate func(t *testing.T, src string)
+	}{
+		{
+			name: "empty event root",
+			mutate: func(t *testing.T, src string) {
+				t.Helper()
+				if err := os.WriteFile(filepath.Join(src, multiEventSkill, "SKILL.md"), nil, 0o644); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "wrong event name",
+			mutate: func(t *testing.T, src string) {
+				t.Helper()
+				body := "---\nname: dingtalk-chat\ndescription: wrong skill\n---\n\n# Wrong\n"
+				if err := os.WriteFile(filepath.Join(src, multiEventSkill, "SKILL.md"), []byte(body), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "missing event reference",
+			mutate: func(t *testing.T, src string) {
+				t.Helper()
+				if err := os.Remove(filepath.Join(src, multiEventSkill, "references", "event-oa.md")); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "empty event reference",
+			mutate: func(t *testing.T, src string) {
+				t.Helper()
+				if err := os.WriteFile(filepath.Join(src, multiEventSkill, "references", "event-im.md"), nil, 0o644); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+		{
+			name: "wrong misc name",
+			mutate: func(t *testing.T, src string) {
+				t.Helper()
+				body := "---\nname: dingtalk-event\ndescription: wrong skill\n---\n\n# Wrong\n"
+				if err := os.WriteFile(filepath.Join(src, multiMiscSkill, "SKILL.md"), []byte(body), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+			test.mutate(t, src)
+			home := filepath.Join(t.TempDir(), "skills")
+			writeFoldedEventMisc(t, home)
+			writeOldStandaloneEvent(t, home)
+
+			stdout, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+			if err == nil || !strings.Contains(err.Error(), "迁移源无效") {
+				t.Fatalf("invalid migration source was accepted: %v", err)
+			}
+			if strings.Contains(stdout, "Skill 安装完成") {
+				t.Fatalf("invalid migration source reported success: %s", stdout)
+			}
+			assertOldEventMiscPair(t, home)
+			if _, statErr := os.Stat(filepath.Join(home, multiSharedSkill)); !os.IsNotExist(statErr) {
+				t.Fatalf("invalid source wrote shared skill: %v", statErr)
+			}
+		})
+	}
+}
+
+func TestSkillSetupSelectiveEventPreservesFoldedMiscAfterPrimarySkip(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+
+	originalInstallMulti := skillSetupInstallMulti
+	t.Cleanup(func() { skillSetupInstallMulti = originalInstallMulti })
+	calls := 0
+	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+		calls++
+		if calls > 1 {
+			t.Fatal("misc migration companion ran after a primary install skip")
+		}
+		return 1, 1, nil
+	}
+
+	stdout, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "已保留折叠版 Event/misc") {
+		t.Fatalf("expected preserved-fallback error, got %v", err)
+	}
+	if calls != 1 {
+		t.Fatalf("install calls = %d, want 1", calls)
+	}
+	if strings.Contains(stdout, "Skill 安装完成") {
+		t.Fatalf("partial migration reported success: %s", stdout)
+	}
+	body, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+	if readErr != nil || !strings.Contains(string(body), "dws event") {
+		t.Fatalf("primary skip changed folded misc: body=%q err=%v", body, readErr)
+	}
+	if _, statErr := os.Stat(filepath.Join(home, multiMiscSkill, "references", "event.md")); statErr != nil {
+		t.Fatalf("primary skip removed folded Event reference: %v", statErr)
+	}
+}
+
+func TestSkillSetupFreshTargetFailureDoesNotTouchFoldedPair(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	freshHome := filepath.Join(t.TempDir(), "fresh", "skills")
+	foldedHome := filepath.Join(t.TempDir(), "folded", "skills")
+	writeFoldedEventMisc(t, foldedHome)
+	writeOldStandaloneEvent(t, foldedHome)
+
+	originalInstallMulti := skillSetupInstallMulti
+	t.Cleanup(func() { skillSetupInstallMulti = originalInstallMulti })
+	calls := 0
+	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) {
+		calls++
+		if calls > 1 {
+			t.Fatal("folded target prerequisites ran after fresh target failure")
+		}
+		return 1, 1, nil
+	}
+
+	stdout, _, err := executeMultiSkillSetupTest(
+		t,
+		src,
+		[]string{foldedHome, freshHome},
+		"--skill", "event",
+		"--yes",
+	)
+	if err == nil || !strings.Contains(err.Error(), "已保留折叠版 Event/misc") {
+		t.Fatalf("fresh target failure did not block migration: %v", err)
+	}
+	if strings.Contains(stdout, "Skill 安装完成") {
+		t.Fatalf("partial mixed-target install reported success: %s", stdout)
+	}
+	assertOldEventMiscPair(t, foldedHome)
+	assertNoEventMigrationStages(t, foldedHome)
+}
+
+func TestSkillSetupUnrelatedSelectiveInstallLeavesFoldedPairUntouched(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{
+		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
+	})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+	writeOldStandaloneEvent(t, home)
+
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "doc", "--yes")
+	if err != nil {
+		t.Fatalf("unrelated selective install failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr)
+	}
+	if strings.Contains(stdout, "Event Skill 迁移") || strings.Contains(stdout, "Event 原子迁移") {
+		t.Fatalf("unrelated selective install planned Event migration: %s", stdout)
+	}
+	if _, err := os.Stat(filepath.Join(home, "dingtalk-doc", "SKILL.md")); err != nil {
+		t.Fatalf("selected doc was not installed: %v", err)
+	}
+	assertOldEventMiscPair(t, home)
+	assertNoEventMigrationStages(t, home)
+}
+
+func TestSkillSetupSelectiveEventAtomicStageFailurePreservesFoldedPair(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+
+	originalCopyDir := skillSetupCopyDir
+	t.Cleanup(func() { skillSetupCopyDir = originalCopyDir })
+	skillSetupCopyDir = func(src, dest string) error {
+		if strings.HasSuffix(dest, "new-misc") {
+			return errors.New("injected stage failure")
+		}
+		return originalCopyDir(src, dest)
+	}
+
+	stdout, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "预备 dingtalk-misc 失败") {
+		t.Fatalf("expected atomic staging error, got %v", err)
+	}
+	if strings.Contains(stdout, "Skill 安装完成") {
+		t.Fatalf("partial atomic migration reported success: %s", stdout)
+	}
+	body, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+	if readErr != nil || !strings.Contains(string(body), "dws event") {
+		t.Fatalf("stage failure changed folded misc: body=%q err=%v", body, readErr)
+	}
+	if _, statErr := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(statErr) {
+		t.Fatalf("stage failure installed standalone event, stat err=%v", statErr)
+	}
+}
+
+func TestSkillSetupEventMigrationPreparationFailuresPreserveFoldedPair(t *testing.T) {
+	t.Run("same-filesystem staging creation", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+		home := filepath.Join(t.TempDir(), "skills")
+		writeFoldedEventMisc(t, home)
+		writeOldStandaloneEvent(t, home)
+
+		originalMkdirTemp := skillSetupMkdirTemp
+		t.Cleanup(func() { skillSetupMkdirTemp = originalMkdirTemp })
+		skillSetupMkdirTemp = func(dir, pattern string) (string, error) {
+			if dir != home {
+				t.Fatalf("staging dir = %s, want target filesystem root %s", dir, home)
+			}
+			return "", errors.New("injected mkdir-temp failure")
+		}
+
+		_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+		if err == nil || !strings.Contains(err.Error(), "injected mkdir-temp failure") {
+			t.Fatalf("staging creation failure was not returned: %v", err)
+		}
+		assertOldEventMiscPair(t, home)
+		assertNoEventMigrationStages(t, home)
+	})
+
+	t.Run("event staging copy", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+		home := filepath.Join(t.TempDir(), "skills")
+		writeFoldedEventMisc(t, home)
+		writeOldStandaloneEvent(t, home)
+
+		originalCopyDir := skillSetupCopyDir
+		t.Cleanup(func() { skillSetupCopyDir = originalCopyDir })
+		skillSetupCopyDir = func(src, dest string) error {
+			if strings.HasSuffix(dest, "new-event") {
+				return errors.New("injected event copy failure")
+			}
+			return originalCopyDir(src, dest)
+		}
+
+		_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+		if err == nil || !strings.Contains(err.Error(), "injected event copy failure") {
+			t.Fatalf("event staging failure was not returned: %v", err)
+		}
+		assertOldEventMiscPair(t, home)
+		assertNoEventMigrationStages(t, home)
+	})
+}
+
+func TestSkillSetupSelectiveEventRejectsCorruptStagedMisc(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+
+	originalCopyDir := skillSetupCopyDir
+	t.Cleanup(func() { skillSetupCopyDir = originalCopyDir })
+	skillSetupCopyDir = func(src, dest string) error {
+		if err := originalCopyDir(src, dest); err != nil {
+			return err
+		}
+		if strings.HasSuffix(dest, "new-misc") {
+			return os.WriteFile(filepath.Join(dest, "references", "event-partial.md"), []byte("corrupt\n"), 0o644)
+		}
+		return nil
+	}
+
+	_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "staging 验证失败") {
+		t.Fatalf("corrupt staged misc was accepted: %v", err)
+	}
+	miscBody, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+	if readErr != nil || !strings.Contains(string(miscBody), "dws event") {
+		t.Fatalf("staging validation failure changed folded misc: body=%q err=%v", miscBody, readErr)
+	}
+	if _, err := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(err) {
+		t.Fatalf("staging validation failure installed event: %v", err)
+	}
+	assertNoEventMigrationStages(t, home)
+}
+
+func TestSkillSetupSelectiveEventRejectsIncompleteStagedEvent(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+	writeOldStandaloneEvent(t, home)
+
+	originalCopyDir := skillSetupCopyDir
+	t.Cleanup(func() { skillSetupCopyDir = originalCopyDir })
+	skillSetupCopyDir = func(src, dest string) error {
+		if err := originalCopyDir(src, dest); err != nil {
+			return err
+		}
+		if strings.HasSuffix(dest, "new-event") {
+			return os.Remove(filepath.Join(dest, "references", "event-oa.md"))
+		}
+		return nil
+	}
+
+	_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "staging 验证失败") {
+		t.Fatalf("incomplete staged Event was accepted: %v", err)
+	}
+	assertOldEventMiscPair(t, home)
+	assertNoEventMigrationStages(t, home)
+}
+
+func TestSkillSetupFullEventMigrationIsAtomicAndPreservesSiblings(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{
+		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
+	})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+	writeOldStandaloneEvent(t, home)
+	sibling := filepath.Join(home, "dingtalk-private-sibling")
+	if err := os.MkdirAll(sibling, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(sibling, "SKILL.md"), []byte("keep\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{home}, "--yes")
+	if err != nil {
+		t.Fatalf("full setup migration failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr)
+	}
+	if !strings.Contains(stdout, "Event 原子迁移") || !strings.Contains(stdout, "Skill 安装完成") {
+		t.Fatalf("full setup did not report atomic migration success: %s", stdout)
+	}
+	for _, name := range []string{multiEventSkill, multiMiscSkill, multiSharedSkill, "dingtalk-doc"} {
+		if _, err := os.Stat(filepath.Join(home, name, "SKILL.md")); err != nil {
+			t.Fatalf("full setup missing %s: %v", name, err)
+		}
+	}
+	if _, err := os.Stat(filepath.Join(home, multiMiscSkill, "references", "event.md")); !os.IsNotExist(err) {
+		t.Fatalf("full setup retained folded Event reference: %v", err)
+	}
+	body, err := os.ReadFile(filepath.Join(sibling, "SKILL.md"))
+	if err != nil || string(body) != "keep\n" {
+		t.Fatalf("full setup changed unrelated sibling: body=%q err=%v", body, err)
+	}
+	assertNoEventMigrationStages(t, home)
+}
+
+func TestSkillSetupEventMigrationWithoutSharedStillCleansMonoLeftover(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+	monoLeftover := filepath.Join(home, "dws")
+	if err := os.MkdirAll(monoLeftover, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(monoLeftover, "SKILL.md"), []byte("old mono\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err != nil {
+		t.Fatalf("migration without shared failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr)
+	}
+	if _, err := os.Stat(monoLeftover); !os.IsNotExist(err) {
+		t.Fatalf("migration without prerequisites retained mono leftover: %v", err)
+	}
+	for _, name := range []string{multiEventSkill, multiMiscSkill} {
+		if _, err := os.Stat(filepath.Join(home, name, "SKILL.md")); err != nil {
+			t.Fatalf("migration without shared missing %s: %v", name, err)
+		}
+	}
+	assertNoEventMigrationStages(t, home)
+}
+
+func TestSkillSetupFoldedEventMigrationSelectionPreflight(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{
+		multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc",
+	})
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "misc only", args: []string{"--skill", "misc", "--yes"}, want: "不能只覆盖 dingtalk-misc"},
+		{name: "explicitly excludes event", args: []string{"--exclude", "event", "--yes"}, want: "不能显式 --exclude event"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			home := filepath.Join(t.TempDir(), "skills")
+			writeFoldedEventMisc(t, home)
+			_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, tt.args...)
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("preflight error = %v, want %q", err, tt.want)
+			}
+			if _, err := os.Stat(filepath.Join(home, multiSharedSkill)); !os.IsNotExist(err) {
+				t.Fatalf("preflight failure wrote shared skill: %v", err)
+			}
+			if _, err := os.Stat(filepath.Join(home, multiEventSkill)); !os.IsNotExist(err) {
+				t.Fatalf("preflight failure wrote event skill: %v", err)
+			}
+			miscBody, readErr := os.ReadFile(filepath.Join(home, multiMiscSkill, "SKILL.md"))
+			if readErr != nil || !strings.Contains(string(miscBody), "dws event") {
+				t.Fatalf("preflight failure changed folded misc: body=%q err=%v", miscBody, readErr)
+			}
+		})
+	}
+}
+
+func TestSkillSetupEventMigrationRejectsEveryFoldedReferenceVariant(t *testing.T) {
+	for _, filename := range []string{"event.md", "event-im.md", "event-oa.md", "EVENT-legacy.MD"} {
+		t.Run(filename, func(t *testing.T) {
+			src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+			if err := os.WriteFile(filepath.Join(src, multiMiscSkill, "references", filename), []byte("stale\n"), 0o644); err != nil {
+				t.Fatal(err)
+			}
+			home := filepath.Join(t.TempDir(), "skills")
+			writeFoldedEventMisc(t, home)
+
+			_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+			if err == nil || !strings.Contains(err.Error(), "仍存在折叠 Event 参考页") {
+				t.Fatalf("source with %s was accepted: %v", filename, err)
+			}
+			if _, err := os.Stat(filepath.Join(home, multiSharedSkill)); !os.IsNotExist(err) {
+				t.Fatalf("invalid source wrote shared skill: %v", err)
+			}
+		})
+	}
+}
+
+func TestSkillSetupEventMigrationRenameFailuresRollbackPair(t *testing.T) {
+	for failAt := 1; failAt <= 4; failAt++ {
+		t.Run(fmt.Sprintf("rename_%d", failAt), func(t *testing.T) {
+			src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+			home := filepath.Join(t.TempDir(), "skills")
+			writeFoldedEventMisc(t, home)
+			writeOldStandaloneEvent(t, home)
+
+			originalRename := skillSetupRename
+			t.Cleanup(func() { skillSetupRename = originalRename })
+			renameCalls := 0
+			skillSetupRename = func(oldPath, newPath string) error {
+				renameCalls++
+				if renameCalls == failAt {
+					return errors.New("injected rename failure")
+				}
+				return originalRename(oldPath, newPath)
+			}
+
+			stdout, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+			if err == nil || !strings.Contains(err.Error(), "injected rename failure") {
+				t.Fatalf("rename failure %d was not returned: %v", failAt, err)
+			}
+			if strings.Contains(stdout, "Skill 安装完成") {
+				t.Fatalf("rename failure %d reported success: %s", failAt, stdout)
+			}
+			assertOldEventMiscPair(t, home)
+			assertNoEventMigrationStages(t, home)
+		})
+	}
+}
+
+func TestSkillSetupEventMigrationFailureRollsBackEarlierTargets(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	root := t.TempDir()
+	firstHome := filepath.Join(root, "a", "skills")
+	secondHome := filepath.Join(root, "b", "skills")
+	for _, home := range []string{firstHome, secondHome} {
+		writeFoldedEventMisc(t, home)
+		writeOldStandaloneEvent(t, home)
+	}
+
+	originalRename := skillSetupRename
+	t.Cleanup(func() { skillSetupRename = originalRename })
+	failed := false
+	skillSetupRename = func(oldPath, newPath string) error {
+		if !failed && oldPath == filepath.Join(secondHome, multiMiscSkill) {
+			failed = true
+			return errors.New("second target failure")
+		}
+		return originalRename(oldPath, newPath)
+	}
+
+	_, _, err := executeMultiSkillSetupTest(t, src, []string{secondHome, firstHome}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "second target failure") {
+		t.Fatalf("second target failure was not returned: %v", err)
+	}
+	for _, home := range []string{firstHome, secondHome} {
+		assertOldEventMiscPair(t, home)
+		assertNoEventMigrationStages(t, home)
+	}
+}
+
+func TestSkillSetupEventMigrationRollbackFailurePreservesRecoveryDirectory(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+	writeOldStandaloneEvent(t, home)
+
+	originalRename := skillSetupRename
+	t.Cleanup(func() { skillSetupRename = originalRename })
+	skillSetupRename = func(oldPath, newPath string) error {
+		if strings.HasSuffix(oldPath, filepath.Join("new-misc")) && newPath == filepath.Join(home, multiMiscSkill) {
+			return errors.New("commit failure")
+		}
+		if strings.HasSuffix(oldPath, filepath.Join("old-misc")) && newPath == filepath.Join(home, multiMiscSkill) {
+			return errors.New("rollback restore failure")
+		}
+		return originalRename(oldPath, newPath)
+	}
+
+	_, stderr, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "回滚不完整") || !strings.Contains(err.Error(), "恢复目录") {
+		t.Fatalf("rollback failure did not expose recovery directory: %v", err)
+	}
+	entries, readErr := os.ReadDir(home)
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	var recoveryRoot string
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), ".dws-event-migration-") {
+			recoveryRoot = filepath.Join(home, entry.Name())
+			break
+		}
+	}
+	if recoveryRoot == "" {
+		t.Fatal("rollback failure deleted the only recovery directory")
+	}
+	if !strings.Contains(err.Error(), recoveryRoot) || !strings.Contains(stderr, recoveryRoot) {
+		t.Fatalf("recovery directory was not reported: err=%v stderr=%s", err, stderr)
+	}
+	if _, err := os.Stat(filepath.Join(recoveryRoot, "old-misc", "SKILL.md")); err != nil {
+		t.Fatalf("old folded misc backup is missing from recovery directory: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(recoveryRoot, "old-event", "SKILL.md")); err != nil {
+		t.Fatalf("old standalone Event backup is missing from recovery directory: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(home, multiEventSkill, "SKILL.md")); err != nil {
+		t.Fatalf("rollback failure removed the live standalone Event entry: %v", err)
+	}
+}
+
+func TestSkillSetupEventMigrationRollbackFailureKeepsNewEventWithoutOldStandalone(t *testing.T) {
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+	home := filepath.Join(t.TempDir(), "skills")
+	writeFoldedEventMisc(t, home)
+
+	originalRename := skillSetupRename
+	t.Cleanup(func() { skillSetupRename = originalRename })
+	skillSetupRename = func(oldPath, newPath string) error {
+		if strings.HasSuffix(oldPath, filepath.Join("new-misc")) && newPath == filepath.Join(home, multiMiscSkill) {
+			return errors.New("commit failure")
+		}
+		if strings.HasSuffix(oldPath, filepath.Join("old-misc")) && newPath == filepath.Join(home, multiMiscSkill) {
+			return errors.New("rollback restore failure")
+		}
+		return originalRename(oldPath, newPath)
+	}
+
+	_, _, err := executeMultiSkillSetupTest(t, src, []string{home}, "--skill", "event", "--yes")
+	if err == nil || !strings.Contains(err.Error(), "回滚不完整") {
+		t.Fatalf("rollback failure was not returned: %v", err)
+	}
+	if _, statErr := os.Stat(filepath.Join(home, multiEventSkill, "SKILL.md")); statErr != nil {
+		t.Fatalf("rollback failure removed the only live Event entry: %v", statErr)
+	}
+	entries, readErr := os.ReadDir(home)
+	if readErr != nil {
+		t.Fatal(readErr)
+	}
+	for _, entry := range entries {
+		if !strings.HasPrefix(entry.Name(), ".dws-event-migration-") {
+			continue
+		}
+		if _, statErr := os.Stat(filepath.Join(home, entry.Name(), "old-misc", "SKILL.md")); statErr != nil {
+			t.Fatalf("rollback failure lost the folded misc recovery copy: %v", statErr)
+		}
+		return
+	}
+	t.Fatal("rollback failure did not preserve a recovery directory")
+}

internal/app/testdata/shortcut_hallucination_badcases_20260728.json

@@ -0,0 +1,633 @@
+{
+  "source_report": "param_hallucination_20260728_120943",
+  "source_file": "raw_dashscope_qwen3_7-max_20260728_120943.json",
+  "source_dws_commit": "a8e83e5",
+  "model": "dashscope/qwen3.7-max",
+  "expected_count": 52,
+  "badcases": [
+    {
+      "id": "dws_im_v3_0003-run10-command0",
+      "case_id": "dws_im_v3_0003",
+      "run": 10,
+      "command_index": 0,
+      "turn": 1,
+      "source_path": "chat +members",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +members --group \"dws测试群01\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0003-run10-command1",
+      "case_id": "dws_im_v3_0003",
+      "run": 10,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +members",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +members --group-name \"dws测试群01\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0003-run10-command2",
+      "case_id": "dws_im_v3_0003",
+      "run": 10,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +members",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +members \"dws测试群01\" --format json",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run1-command1",
+      "case_id": "dws_im_v3_0010",
+      "run": 1,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-dm",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-dm --open-dingtalk-id DCumk1qOOIgsjxMVAxenQsyiPzt5zTjyzS --content \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run1-command2",
+      "case_id": "dws_im_v3_0010",
+      "run": 1,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-dm",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-dm --dingtalk-id DCumk1qOOIgsjxMVAxenQsyiPzt5zTjyzS --content \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run8-command4",
+      "case_id": "dws_im_v3_0010",
+      "run": 8,
+      "command_index": 4,
+      "turn": 1,
+      "source_path": "chat +send-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-single --user-id \"DCumk1qOOIgsjxMVAxenQsyiPzt5zTjyzS\" --content \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run10-command0",
+      "case_id": "dws_im_v3_0010",
+      "run": 10,
+      "command_index": 0,
+      "turn": 1,
+      "source_path": "chat +send-by-bot",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-by-bot --open-dingtalk-id \"段旭彬\" --message \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run10-command1",
+      "case_id": "dws_im_v3_0010",
+      "run": 10,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-by-bot",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-by-bot --open-id \"段旭彬\" --msg \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0010-run10-command2",
+      "case_id": "dws_im_v3_0010",
+      "run": 10,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-by-bot",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-by-bot \"段旭彬\" \"评测任务更新了，稍后同步\" --format json",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0011-run1-command3",
+      "case_id": "dws_im_v3_0011",
+      "run": 1,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send-media",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-media --user-id \"489149\" --file-path \"建筑.jpeg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0011-run1-command4",
+      "case_id": "dws_im_v3_0011",
+      "run": 1,
+      "command_index": 4,
+      "turn": 1,
+      "source_path": "chat +send-media",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-media --receiver \"489149\" --file-path \"建筑.jpeg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0011-run9-command1",
+      "case_id": "dws_im_v3_0011",
+      "run": 9,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --user-id 489149 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case__ysfhvr3/建筑.jpeg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0011-run9-command2",
+      "case_id": "dws_im_v3_0011",
+      "run": 9,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --dry-run --format json 2>&1 | head -50",
+      "original_exit_code": 0,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run1-command2",
+      "case_id": "dws_im_v3_0012",
+      "run": 1,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_bc6azkyi/streamlit.docx\" --to \"符咏畅\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run1-command3",
+      "case_id": "dws_im_v3_0012",
+      "run": 1,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_bc6azkyi/streamlit.docx\" --user \"符咏畅\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run2-command3",
+      "case_id": "dws_im_v3_0012",
+      "run": 2,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --receiver 519483 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_3er98f5m/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run2-command8",
+      "case_id": "dws_im_v3_0012",
+      "run": 2,
+      "command_index": 8,
+      "turn": 1,
+      "source_path": "chat +send",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send --user 519483 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_3er98f5m/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run3-command1",
+      "case_id": "dws_im_v3_0012",
+      "run": 3,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --user-id 519483 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_cljycf8p/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run3-command2",
+      "case_id": "dws_im_v3_0012",
+      "run": 3,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --receiver 519483 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_cljycf8p/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run4-command3",
+      "case_id": "dws_im_v3_0012",
+      "run": 4,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --help",
+      "original_exit_code": 64,
+      "is_help": true
+    },
+    {
+      "id": "dws_im_v3_0012-run6-command4",
+      "case_id": "dws_im_v3_0012",
+      "run": 6,
+      "command_index": 4,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --user 519483 --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_8ef9dsey/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run6-command5",
+      "case_id": "dws_im_v3_0012",
+      "run": 6,
+      "command_index": 5,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --to \"519483\" --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_8ef9dsey/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run6-command6",
+      "case_id": "dws_im_v3_0012",
+      "run": 6,
+      "command_index": 6,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --name \"符咏畅\" --path \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_8ef9dsey/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run7-command1",
+      "case_id": "dws_im_v3_0012",
+      "run": 7,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --user-id \"519483\" --file-path \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_fjcfinmi/streamlit.docx\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0012-run7-command2",
+      "case_id": "dws_im_v3_0012",
+      "run": 7,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --format json --userid \"519483\" --file \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_fjcfinmi/streamlit.docx\"",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0016-run1-command7",
+      "case_id": "dws_im_v3_0016",
+      "run": 1,
+      "command_index": 7,
+      "turn": 3,
+      "source_path": "chat +rename-group",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +rename-group --id \"cideWy3UCPNZ4k8Mr4BL/8KRQ==\" --name \"测试废物群-20260713\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run2-command6",
+      "case_id": "dws_im_v3_0017",
+      "run": 2,
+      "command_index": 6,
+      "turn": 2,
+      "source_path": "chat +send-message",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-message --group \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --content \"@陈邦杰 请确认下评测环境\" --mention \"DCumk1qOOIgvuN6zOZeehqYdii06QhlcIl\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run2-command7",
+      "case_id": "dws_im_v3_0017",
+      "run": 2,
+      "command_index": 7,
+      "turn": 2,
+      "source_path": "chat +send-message",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-message --open-conversation-id \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --content \"@陈邦杰 请确认下评测环境\" --mention \"DCumk1qOOIgvuN6zOZeehqYdii06QhlcIl\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run2-command9",
+      "case_id": "dws_im_v3_0017",
+      "run": 2,
+      "command_index": 9,
+      "turn": 2,
+      "source_path": "chat +send-message",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-message --format json 2>&1",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run5-command0",
+      "case_id": "dws_im_v3_0017",
+      "run": 5,
+      "command_index": 0,
+      "turn": 1,
+      "source_path": "chat +group-member-list",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +group-member-list --group-name \"dws测试群01\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run6-command6",
+      "case_id": "dws_im_v3_0017",
+      "run": 6,
+      "command_index": 6,
+      "turn": 2,
+      "source_path": "chat +send-text",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-text --open-conversation-id \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --text \"@陈邦杰 请确认下评测环境\" --at-open-dingtalk-ids \"DCumk1qOOIgvuN6zOZeehqYdii06QhlcIl\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run6-command7",
+      "case_id": "dws_im_v3_0017",
+      "run": 6,
+      "command_index": 7,
+      "turn": 2,
+      "source_path": "chat +send-text",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-text --conversation-id \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --content \"@陈邦杰 请确认下评测环境\" --at-user-ids \"DCumk1qOOIgvuN6zOZeehqYdii06QhlcIl\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0017-run6-command8",
+      "case_id": "dws_im_v3_0017",
+      "run": 6,
+      "command_index": 8,
+      "turn": 2,
+      "source_path": "chat +group-send-text",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +group-send-text --group-id \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --text \"@陈邦杰 请确认下评测环境\" --at-open-dingtalk-ids \"DCumk1qOOIgvuN6zOZeehqYdii06QhlcIl\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0018-run10-command5",
+      "case_id": "dws_im_v3_0018",
+      "run": 10,
+      "command_index": 5,
+      "turn": 1,
+      "source_path": "chat +send-image",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-image --group \"cidyfbDkUpmy4ReyI7vfZy+zw==\" --file-path \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_z7y6p6_0/dog.png\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run4-command1",
+      "case_id": "dws_im_v3_0019",
+      "run": 4,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +send-image",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-image --user-id 489149 --image /private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_wsppmjwr/landscape.jpg --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run4-command2",
+      "case_id": "dws_im_v3_0019",
+      "run": 4,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-image",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-image --to 489149 --file /private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_wsppmjwr/landscape.jpg --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run6-command3",
+      "case_id": "dws_im_v3_0019",
+      "run": 6,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send --receiver-id 489149 --image \"/private/var/folders/wy/34yt54fd7fv1ccgg3jpcwd140000gn/T/dws_eval_case_09930iej/landscape.jpg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run8-command2",
+      "case_id": "dws_im_v3_0019",
+      "run": 8,
+      "command_index": 2,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --user-id 489149 --file \"landscape.jpg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run8-command3",
+      "case_id": "dws_im_v3_0019",
+      "run": 8,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +send-file",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-file --receiver-id 489149 --file \"landscape.jpg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run8-command6",
+      "case_id": "dws_im_v3_0019",
+      "run": 8,
+      "command_index": 6,
+      "turn": 1,
+      "source_path": "chat +send",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send --to 489149 --file \"landscape.jpg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run8-command9",
+      "case_id": "dws_im_v3_0019",
+      "run": 8,
+      "command_index": 9,
+      "turn": 1,
+      "source_path": "chat +send-to",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send-to --uid 489149 --file \"landscape.jpg\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0019-run9-command0",
+      "case_id": "dws_im_v3_0019",
+      "run": 9,
+      "command_index": 0,
+      "turn": 1,
+      "source_path": "chat +send",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +send --receiver 489149 --file-path \"./landscape.jpg\" --format json 2>&1",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command3",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 3,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single --user-id 550582 --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command4",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 4,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single --uid 550582 --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command5",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 5,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single --staff-id 550582 --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command6",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 6,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single --open-dingtalk-id \"DCumk1qOOIgsjxMVAxenQsyiPzt5zTjyzS\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command7",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 7,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single --target 550582 --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run4-command8",
+      "case_id": "dws_im_v3_0021",
+      "run": 4,
+      "command_index": 8,
+      "turn": 1,
+      "source_path": "chat +read-single",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +read-single 550582 --format json",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0021-run5-command1",
+      "case_id": "dws_im_v3_0021",
+      "run": 5,
+      "command_index": 1,
+      "turn": 1,
+      "source_path": "chat +message-list",
+      "expected_outcome": "ambiguous",
+      "raw": "dws chat +message-list --format json 2>&1",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0028-run4-command5",
+      "case_id": "dws_im_v3_0028",
+      "run": 4,
+      "command_index": 5,
+      "turn": 1,
+      "source_path": "chat +list-robot",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +list-robot \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --format json",
+      "original_exit_code": 5,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0028-run5-command15",
+      "case_id": "dws_im_v3_0028",
+      "run": 5,
+      "command_index": 15,
+      "turn": 1,
+      "source_path": "chat +list-group-bots",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +list-group-bots --id \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    },
+    {
+      "id": "dws_im_v3_0028-run9-command9",
+      "case_id": "dws_im_v3_0028",
+      "run": 9,
+      "command_index": 9,
+      "turn": 1,
+      "source_path": "chat +list-robots",
+      "expected_outcome": "rewrite",
+      "raw": "dws chat +list-robots --cid \"cidACeQ0fCtKfLsFGvA47gXaQ==\" --format json",
+      "original_exit_code": 3,
+      "is_help": false
+    }
+  ]
+}

internal/cli/command_path_fallbacks.go

@@ -0,0 +1,289 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package cli
+
+import (
+	"bytes"
+	_ "embed"
+	"encoding/json"
+	"fmt"
+	"io"
+	"regexp"
+	"sort"
+	"strings"
+	"sync"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+const commandPathFallbacksSchemaRef = "./command_path_fallbacks.schema.json"
+
+// command_path_fallbacks.json is a reviewed recovery policy for invalid paths
+// observed in evaluation. It is deliberately not a command identity source:
+// Help, Skill, Schema, and normal navigation continue to publish canonical
+// paths from the CommandRegistry and the real Cobra tree only.
+
+//go:embed command_path_fallbacks.json
+var embeddedCommandPathFallbacksJSON []byte
+
+//go:embed command_path_fallbacks.schema.json
+var embeddedCommandPathFallbacksSchemaJSON []byte
+
+var commandFallbackPathPattern = regexp.MustCompile(`^[A-Za-z0-9+][A-Za-z0-9._:+-]*(?: [A-Za-z0-9+][A-Za-z0-9._:+-]*)*$`)
+
+// CommandPathFallbackMode determines whether an invalid reviewed path can be
+// normalized exactly or must stop and surface reviewed candidates.
+type CommandPathFallbackMode string
+
+const (
+	CommandPathFallbackRewrite   CommandPathFallbackMode = "rewrite"
+	CommandPathFallbackAmbiguous CommandPathFallbackMode = "ambiguous"
+)
+
+// CommandPathFallback is one validated, generated runtime recovery record.
+// From is never advertised as a stable alias. To and Candidates are canonical
+// real Cobra paths validated at generation time.
+type CommandPathFallback struct {
+	From         string                  `json:"from"`
+	Mode         CommandPathFallbackMode `json:"mode"`
+	To           string                  `json:"to,omitempty"`
+	Candidates   []string                `json:"candidates,omitempty"`
+	Reviewed     bool                    `json:"reviewed"`
+	ReviewReason string                  `json:"review_reason"`
+}
+
+type commandPathFallbackSnapshot struct {
+	Schema  string                         `json:"$schema"`
+	Version int                            `json:"version"`
+	Entries []commandPathFallbackEntrySpec `json:"entries"`
+}
+
+type commandPathFallbackEntrySpec struct {
+	From         string                  `json:"from"`
+	Mode         CommandPathFallbackMode `json:"mode"`
+	To           string                  `json:"to,omitempty"`
+	Candidates   []string                `json:"candidates,omitempty"`
+	Reviewed     bool                    `json:"reviewed"`
+	ReviewReason string                  `json:"review_reason"`
+}
+
+var (
+	embeddedCommandPathFallbacksOnce sync.Once
+	embeddedCommandPathFallbacksData []CommandPathFallback
+	embeddedCommandPathFallbacksErr  error
+	loadReviewedCommandPathFallbacks = loadEmbeddedCommandPathFallbacks
+)
+
+// LoadCommandPathFallbacks decodes and validates the authored recovery table.
+// Callers receive a clone so generation and tests cannot mutate shared data.
+func LoadCommandPathFallbacks() ([]CommandPathFallback, error) {
+	return loadReviewedCommandPathFallbacks()
+}
+
+func loadEmbeddedCommandPathFallbacks() ([]CommandPathFallback, error) {
+	embeddedCommandPathFallbacksOnce.Do(func() {
+		embeddedCommandPathFallbacksData, embeddedCommandPathFallbacksErr = decodeCommandPathFallbacks(embeddedCommandPathFallbacksJSON)
+	})
+	return cloneCommandPathFallbacks(embeddedCommandPathFallbacksData), embeddedCommandPathFallbacksErr
+}
+
+func decodeCommandPathFallbacks(data []byte) ([]CommandPathFallback, error) {
+	var snapshot commandPathFallbackSnapshot
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&snapshot); err != nil {
+		return nil, fmt.Errorf("decode reviewed command path fallbacks: %w", err)
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		if err == nil {
+			err = fmt.Errorf("multiple JSON values")
+		}
+		return nil, fmt.Errorf("decode reviewed command path fallbacks: %w", err)
+	}
+	if snapshot.Version != 1 {
+		return nil, fmt.Errorf("unsupported command path fallbacks version %d", snapshot.Version)
+	}
+	if strings.TrimSpace(snapshot.Schema) != commandPathFallbacksSchemaRef {
+		return nil, fmt.Errorf("command path fallbacks must declare $schema=%q", commandPathFallbacksSchemaRef)
+	}
+	if len(snapshot.Entries) == 0 {
+		return nil, fmt.Errorf("command path fallbacks declares no entries")
+	}
+
+	entries := make([]CommandPathFallback, 0, len(snapshot.Entries))
+	seenFrom := make(map[string]bool, len(snapshot.Entries))
+	for index, spec := range snapshot.Entries {
+		from, err := validateAuthoredCommandFallbackPath(spec.From)
+		if err != nil {
+			return nil, fmt.Errorf("command path fallback entry %d from: %w", index, err)
+		}
+		if seenFrom[from] {
+			return nil, fmt.Errorf("command path fallbacks contains duplicate from path %q", from)
+		}
+		seenFrom[from] = true
+		reason := strings.TrimSpace(spec.ReviewReason)
+		if !spec.Reviewed || reason == "" {
+			return nil, fmt.Errorf("command path fallback %q requires reviewed=true and non-empty review_reason", from)
+		}
+
+		entry := CommandPathFallback{
+			From:         from,
+			Mode:         spec.Mode,
+			Reviewed:     true,
+			ReviewReason: reason,
+		}
+		switch spec.Mode {
+		case CommandPathFallbackRewrite:
+			if len(spec.Candidates) > 0 {
+				return nil, fmt.Errorf("rewrite command path fallback %q must not declare candidates", from)
+			}
+			to, pathErr := validateAuthoredCommandFallbackPath(spec.To)
+			if pathErr != nil {
+				return nil, fmt.Errorf("rewrite command path fallback %q to: %w", from, pathErr)
+			}
+			entry.To = to
+		case CommandPathFallbackAmbiguous:
+			if strings.TrimSpace(spec.To) != "" {
+				return nil, fmt.Errorf("ambiguous command path fallback %q must not declare to", from)
+			}
+			if len(spec.Candidates) < 2 {
+				return nil, fmt.Errorf("ambiguous command path fallback %q requires at least two candidates", from)
+			}
+			seenCandidates := make(map[string]bool, len(spec.Candidates))
+			for _, rawCandidate := range spec.Candidates {
+				candidate, pathErr := validateAuthoredCommandFallbackPath(rawCandidate)
+				if pathErr != nil {
+					return nil, fmt.Errorf("ambiguous command path fallback %q candidate: %w", from, pathErr)
+				}
+				if seenCandidates[candidate] {
+					return nil, fmt.Errorf("ambiguous command path fallback %q repeats candidate %q", from, candidate)
+				}
+				seenCandidates[candidate] = true
+				entry.Candidates = append(entry.Candidates, candidate)
+			}
+		default:
+			return nil, fmt.Errorf("command path fallback %q has invalid mode %q", from, spec.Mode)
+		}
+		entries = append(entries, entry)
+	}
+
+	sort.Slice(entries, func(i, j int) bool { return entries[i].From < entries[j].From })
+	return entries, nil
+}
+
+func validateAuthoredCommandFallbackPath(raw string) (string, error) {
+	path := strings.TrimSpace(raw)
+	if path == "" {
+		return "", fmt.Errorf("path is empty")
+	}
+	if path != raw || normalizeSchemaCLIPath(path) != path || !commandFallbackPathPattern.MatchString(path) {
+		return "", fmt.Errorf("path %q is not a normalized command path without leading dws or flags", raw)
+	}
+	return path, nil
+}
+
+// ReduceCommandPathFallbacks validates the reviewed recovery table against the
+// live distribution-owned Cobra tree. It refuses to turn an existing command
+// or stable alias into a hidden rewrite. The sole exception is an explicitly
+// annotated hint-only compatibility node, which contains no business action.
+func ReduceCommandPathFallbacks(root *cobra.Command) ([]CommandPathFallback, error) {
+	if root == nil {
+		return nil, fmt.Errorf("command path fallback source root is nil")
+	}
+	entries, err := LoadCommandPathFallbacks()
+	if err != nil {
+		return nil, err
+	}
+
+	byFrom := make(map[string]CommandPathFallback, len(entries))
+	for _, entry := range entries {
+		byFrom[entry.From] = entry
+	}
+	var problems []string
+	for _, entry := range entries {
+		match, resolveErr := resolveExactCobraPath(root, entry.From)
+		if resolveErr != nil {
+			problems = append(problems, fmt.Sprintf("from %q cannot be resolved safely: %v", entry.From, resolveErr))
+		} else if match.Command != nil && !cmdutil.IsHintOnlyCommand(match.Command) {
+			problems = append(problems, fmt.Sprintf("from %q collides with a real Cobra command or alias", entry.From))
+		}
+
+		switch entry.Mode {
+		case CommandPathFallbackRewrite:
+			if _, chained := byFrom[entry.To]; chained {
+				problems = append(problems, fmt.Sprintf("rewrite %q targets fallback source %q; chained fallbacks are forbidden", entry.From, entry.To))
+			}
+			problems = append(problems, validateCommandFallbackTarget(root, entry.From, entry.To, true)...)
+		case CommandPathFallbackAmbiguous:
+			for _, candidate := range entry.Candidates {
+				if _, chained := byFrom[candidate]; chained {
+					problems = append(problems, fmt.Sprintf("ambiguous fallback %q candidate %q is another fallback source", entry.From, candidate))
+				}
+				// Ambiguous recovery never dispatches. It may therefore point the
+				// caller at both canonical shortcuts and native leaves, while exact
+				// rewrites keep the stricter +shortcut identity boundary.
+				problems = append(problems, validateCommandFallbackTarget(root, entry.From, candidate, false)...)
+			}
+		default:
+			problems = append(problems, fmt.Sprintf("fallback %q has unsupported mode %q", entry.From, entry.Mode))
+		}
+	}
+
+	if len(problems) > 0 {
+		sort.Strings(problems)
+		return nil, fmt.Errorf("command path fallback reduction failed:\n  - %s", strings.Join(problems, "\n  - "))
+	}
+	return cloneCommandPathFallbacks(entries), nil
+}
+
+func validateCommandFallbackTarget(root *cobra.Command, from, target string, requireShortcutParity bool) []string {
+	var problems []string
+	if commandFallbackService(from) != commandFallbackService(target) {
+		problems = append(problems, fmt.Sprintf("fallback %q crosses service boundary to %q", from, target))
+	}
+	if requireShortcutParity && commandFallbackHasShortcut(from) != commandFallbackHasShortcut(target) {
+		problems = append(problems, fmt.Sprintf("fallback %q and target %q disagree on +shortcut identity", from, target))
+	}
+	match, err := resolveExactCobraPath(root, target)
+	if err != nil {
+		return append(problems, fmt.Sprintf("fallback %q target %q cannot be resolved safely: %v", from, target, err))
+	}
+	if match.Command == nil {
+		return append(problems, fmt.Sprintf("fallback %q target %q does not exist", from, target))
+	}
+	if match.UsedAlias {
+		problems = append(problems, fmt.Sprintf("fallback %q target %q must use canonical Cobra names, not an alias", from, target))
+	}
+	if !runnableSchemaLeaf(match.Command) || !match.Command.IsAvailableCommand() {
+		problems = append(problems, fmt.Sprintf("fallback %q target %q is not a public runnable Cobra leaf", from, target))
+	}
+	return problems
+}
+
+func commandFallbackService(path string) string {
+	parts := strings.Fields(path)
+	if len(parts) == 0 {
+		return ""
+	}
+	return parts[0]
+}
+
+func commandFallbackHasShortcut(path string) bool {
+	for _, part := range strings.Fields(path) {
+		if strings.HasPrefix(part, "+") {
+			return true
+		}
+	}
+	return false
+}
+
+func cloneCommandPathFallbacks(entries []CommandPathFallback) []CommandPathFallback {
+	cloned := make([]CommandPathFallback, len(entries))
+	for index, entry := range entries {
+		cloned[index] = entry
+		cloned[index].Candidates = append([]string(nil), entry.Candidates...)
+	}
+	return cloned
+}

internal/cli/command_path_fallbacks.json

@@ -0,0 +1,311 @@
+{
+  "$schema": "./command_path_fallbacks.schema.json",
+  "version": 1,
+  "entries": [
+    {
+      "from": "chat +group-search",
+      "mode": "rewrite",
+      "to": "chat +chat-search",
+      "reviewed": true,
+      "review_reason": "0803 evaluation badcase: the model emitted +group-search with --query; +chat-search provides the same group-name search operation."
+    },
+    {
+      "from": "chat +members",
+      "mode": "rewrite",
+      "to": "chat +group-members",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation badcases emitted +members three times for listing members of a group selected by name; +group-members is the unique reviewed read-only shortcut for that intent."
+    },
+    {
+      "from": "chat +group-member-list",
+      "mode": "rewrite",
+      "to": "chat +group-members",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +group-member-list for a group-name member lookup; +group-members is the unique reviewed read-only shortcut and canonical parameter validation remains authoritative."
+    },
+    {
+      "from": "chat +list-group-bots",
+      "mode": "rewrite",
+      "to": "chat +chat-bots",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +list-group-bots for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs."
+    },
+    {
+      "from": "chat +list-robot",
+      "mode": "rewrite",
+      "to": "chat +chat-bots",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted singular +list-robot for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs."
+    },
+    {
+      "from": "chat +list-robots",
+      "mode": "rewrite",
+      "to": "chat +chat-bots",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +list-robots for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs."
+    },
+    {
+      "from": "chat +message-list",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +chat-messages",
+        "chat +messages-list-direct",
+        "chat +search-msg",
+        "chat +unread-chats"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +message-list without identifying group versus direct history, conversation history versus cross-chat search, or ordinary versus unread conversations; no candidate may be selected automatically."
+    },
+    {
+      "from": "chat +read-single",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-list-direct",
+        "chat +chat-messages"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +read-single six times for direct-message history, but the invented name does not choose between the focused direct-history shortcut and the broader group/direct history workflow; command recovery must stop before parameter validation or dispatch."
+    },
+    {
+      "from": "chat +rename-group",
+      "mode": "rewrite",
+      "to": "chat +chat-update",
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +rename-group for the unique group-name update intent; +chat-update is the reviewed shortcut with that exact command-level operation. Parameter compatibility remains the canonical target's responsibility."
+    },
+    {
+      "from": "chat +send",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat +dm",
+        "chat +send-to-group"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send without a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow."
+    },
+    {
+      "from": "chat +send-message",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat +dm",
+        "chat +send-to-group"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-message without a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow."
+    },
+    {
+      "from": "chat +send-text",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat +dm",
+        "chat +send-to-group"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation identified text content but not a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow."
+    },
+    {
+      "from": "chat +send-to",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat +dm",
+        "chat +send-to-group"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-to without proving whether the recipient denotes a user, group, or low-level identifier; the write operation must not choose a target workflow automatically."
+    },
+    {
+      "from": "chat +send-dm",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +dm",
+        "chat +messages-send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-dm twice, but the invented name does not choose between the resolved-name text shortcut and the unified identifier-aware sending workflow; the write operation must not dispatch automatically."
+    },
+    {
+      "from": "chat +send-single",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +dm",
+        "chat +messages-send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-single for a direct message, but the invented name does not choose between the resolved-name text shortcut and the unified identifier-aware sending workflow; the write operation must not dispatch automatically."
+    },
+    {
+      "from": "chat +send-by-bot",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat message send-by-bot"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-by-bot three times without a complete sending-identity contract; stop and present the unified identity-aware shortcut and the exact native bot sender instead of selecting a write path."
+    },
+    {
+      "from": "chat +group-send-text",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +send-to-group",
+        "chat +messages-send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +group-send-text for a group text operation, but the invented name does not choose between name-resolved group text and the unified identifier-aware workflow; the write operation must not dispatch automatically."
+    },
+    {
+      "from": "chat +send-file",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat message send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-file fifteen times with incompatible target and file parameter spellings; stop before dispatch and let the caller choose the unified shortcut or native current-user file workflow."
+    },
+    {
+      "from": "chat +send-image",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat message send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-image without proving whether the input is an existing mediaId or a local file; stop before dispatch and let the caller choose the reviewed unified or native workflow."
+    },
+    {
+      "from": "chat +send-media",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +messages-send",
+        "chat message send"
+      ],
+      "reviewed": true,
+      "review_reason": "20260728 evaluation emitted +send-media without a concrete media type, sending identity, or compatible parameter contract; stop before dispatch and let the caller choose the reviewed unified or native workflow."
+    },
+    {
+      "from": "oa +list-processes",
+      "mode": "ambiguous",
+      "candidates": [
+        "oa +list-forms",
+        "oa +my-initiated",
+        "oa approval list-initiated"
+      ],
+      "reviewed": true,
+      "review_reason": "20260720 merged evaluation emitted +list-processes, but process can mean approval forms/templates or approval instances initiated by the current user; stop and present both shortcut workflows plus the exact native instance leaf."
+    },
+    {
+      "from": "chat +conversation-detail",
+      "mode": "rewrite",
+      "to": "chat +conversation-info",
+      "reviewed": true,
+      "review_reason": "20260804 multi-im badcase requested one conversation's details. +conversation-info is the unique current read-only shortcut for that operation. The rewrite changes only the command path and preserves every flag/value for target validation."
+    },
+    {
+      "from": "chat +bot-list",
+      "mode": "rewrite",
+      "to": "chat +chat-bots",
+      "reviewed": true,
+      "review_reason": "20260804 multi-im badcase requested the robot list for one group. +chat-bots is the unique current read-only shortcut. The fallback must not reinterpret the accompanying group flag."
+    },
+    {
+      "from": "chat +conversation-category-list",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +category-list",
+        "chat +category-list-conversations"
+      ],
+      "reviewed": true,
+      "review_reason": "The invented name can mean listing the user's categories or listing conversations inside one category. No candidate may execute before the caller chooses the intended object level."
+    },
+    {
+      "from": "chat +conversation-group-list",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +category-list-conversations",
+        "chat +conversation-list"
+      ],
+      "reviewed": true,
+      "review_reason": "The invented name can mean conversations in a custom category or the general conversation list. The command name alone does not identify the requested collection."
+    },
+    {
+      "from": "chat +list-my-groups",
+      "mode": "ambiguous",
+      "candidates": [
+        "chat +my-groups",
+        "chat +chat-list-mine",
+        "chat +chat-list"
+      ],
+      "reviewed": true,
+      "review_reason": "The invented name does not choose between the established resolver shortcut, the legacy personal-group list and the current Schema-complete chat list. Recovery must stop instead of silently changing pagination or output semantics."
+    },
+    {
+      "from": "doc +list-templates",
+      "mode": "rewrite",
+      "to": "doc +template-list",
+      "reviewed": true,
+      "review_reason": "202608 Doc experiments emitted +list-templates while discovering available templates. +template-list is the unique current public read-only shortcut for that operation; the rewrite changes only the command path and preserves flags for target validation."
+    },
+    {
+      "from": "doc +search-template",
+      "mode": "rewrite",
+      "to": "doc +template-search",
+      "reviewed": true,
+      "review_reason": "202608 Doc experiments emitted the verb/object inversion +search-template. +template-search is the unique current public read-only template-name search shortcut; the rewrite preserves every flag and value."
+    },
+    {
+      "from": "doc +template",
+      "mode": "ambiguous",
+      "candidates": [
+        "doc +template-list",
+        "doc +template-search",
+        "doc +create-from-template"
+      ],
+      "reviewed": true,
+      "review_reason": "202608 Doc experiments emitted the family-like +template without selecting browse, search, or create-from-template. Command recovery must stop before parameters or execution and present the three public workflows."
+    },
+    {
+      "from": "doc +version",
+      "mode": "ambiguous",
+      "candidates": [
+        "doc +history-list",
+        "doc +history-save",
+        "doc +history-revert"
+      ],
+      "reviewed": true,
+      "review_reason": "202608 Doc experiments emitted the family-like +version without choosing list, save, or revert. The write and high-risk revert operations cannot be selected from an umbrella name; present the canonical history shortcuts and stop."
+    },
+    {
+      "from": "doc +create-version",
+      "mode": "rewrite",
+      "to": "doc +history-save",
+      "reviewed": true,
+      "review_reason": "202608 supplemental Doc badcase emitted +create-version while explicitly trying to save the current document as a recoverable history snapshot. +history-save is the unique current canonical shortcut for that operation and accepts the same --node value without parameter transformation."
+    },
+    {
+      "from": "doc +save-version",
+      "mode": "rewrite",
+      "to": "doc +history-save",
+      "reviewed": true,
+      "review_reason": "202608 supplemental Doc badcase emitted the verb/object inversion +save-version for a current-version snapshot. +history-save is the unique current canonical shortcut with the same document-node contract; the legacy +version-save path is not selected as the fallback target."
+    },
+    {
+      "from": "doc +snapshot",
+      "mode": "rewrite",
+      "to": "doc +history-save",
+      "reviewed": true,
+      "review_reason": "202608 supplemental Doc badcase emitted +snapshot during an explicit save-current-version workflow. The current +history-save selection contract names this exact recoverable history-snapshot operation, so the reviewed rewrite preserves the --node value and does not infer an update or export workflow."
+    },
+    {
+      "from": "doc +version-create",
+      "mode": "rewrite",
+      "to": "doc +history-save",
+      "reviewed": true,
+      "review_reason": "202608 supplemental Doc badcase emitted +version-create while saving the current document version. +history-save is the unique current canonical snapshot shortcut and the path-only rewrite leaves its real execution and safety contract authoritative."
+    }
+  ]
+}

internal/cli/command_path_fallbacks.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/blob/main/internal/cli/command_path_fallbacks.schema.json",
+  "title": "DWS Reviewed Command Path Fallbacks",
+  "description": "Human-reviewed recovery-only normalization for invalid model-emitted command paths. These entries are not stable command identity, navigation, Help, Skill, or Schema aliases.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "version",
+    "entries"
+  ],
+  "properties": {
+    "$schema": {
+      "const": "./command_path_fallbacks.schema.json"
+    },
+    "version": {
+      "const": 1
+    },
+    "entries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/entry"
+      }
+    }
+  },
+  "$defs": {
+    "commandPath": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9+][A-Za-z0-9._:+-]*(?: [A-Za-z0-9+][A-Za-z0-9._:+-]*)*$",
+      "description": "Exact CLI path without a leading dws or flags."
+    },
+    "entry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "from",
+        "mode",
+        "reviewed",
+        "review_reason"
+      ],
+      "properties": {
+        "from": {
+          "$ref": "#/$defs/commandPath"
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "rewrite",
+            "ambiguous"
+          ]
+        },
+        "to": {
+          "$ref": "#/$defs/commandPath"
+        },
+        "candidates": {
+          "type": "array",
+          "minItems": 2,
+          "uniqueItems": true,
+          "description": "Canonical public runnable paths offered for an ambiguous source. Because ambiguous recovery never dispatches, candidates may mix reviewed shortcuts and native leaves within the same service.",
+          "items": {
+            "$ref": "#/$defs/commandPath"
+          }
+        },
+        "reviewed": {
+          "const": true
+        },
+        "review_reason": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "rewrite"
+              }
+            },
+            "required": [
+              "mode"
+            ]
+          },
+          "then": {
+            "required": [
+              "to"
+            ],
+            "not": {
+              "required": [
+                "candidates"
+              ]
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "ambiguous"
+              }
+            },
+            "required": [
+              "mode"
+            ]
+          },
+          "then": {
+            "required": [
+              "candidates"
+            ],
+            "not": {
+              "required": [
+                "to"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

internal/cli/command_path_fallbacks_generated.go

@@ -0,0 +1,253 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+// Code generated by cmd_command_path_fallbacks; DO NOT EDIT.
+// Source: internal/cli/command_path_fallbacks.json validated against the live Cobra tree.
+// Regenerate with `make generate-schema` (or `go generate ./internal/cli`).
+
+package cli
+
+var generatedCommandPathFallbacks = []CommandPathFallback{
+	{
+		From:         "chat +bot-list",
+		Mode:         "rewrite",
+		To:           "chat +chat-bots",
+		Reviewed:     true,
+		ReviewReason: "20260804 multi-im badcase requested the robot list for one group. +chat-bots is the unique current read-only shortcut. The fallback must not reinterpret the accompanying group flag.",
+	},
+	{
+		From:         "chat +conversation-category-list",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +category-list", "chat +category-list-conversations"},
+		Reviewed:     true,
+		ReviewReason: "The invented name can mean listing the user's categories or listing conversations inside one category. No candidate may execute before the caller chooses the intended object level.",
+	},
+	{
+		From:         "chat +conversation-detail",
+		Mode:         "rewrite",
+		To:           "chat +conversation-info",
+		Reviewed:     true,
+		ReviewReason: "20260804 multi-im badcase requested one conversation's details. +conversation-info is the unique current read-only shortcut for that operation. The rewrite changes only the command path and preserves every flag/value for target validation.",
+	},
+	{
+		From:         "chat +conversation-group-list",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +category-list-conversations", "chat +conversation-list"},
+		Reviewed:     true,
+		ReviewReason: "The invented name can mean conversations in a custom category or the general conversation list. The command name alone does not identify the requested collection.",
+	},
+	{
+		From:         "chat +group-member-list",
+		Mode:         "rewrite",
+		To:           "chat +group-members",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +group-member-list for a group-name member lookup; +group-members is the unique reviewed read-only shortcut and canonical parameter validation remains authoritative.",
+	},
+	{
+		From:         "chat +group-search",
+		Mode:         "rewrite",
+		To:           "chat +chat-search",
+		Reviewed:     true,
+		ReviewReason: "0803 evaluation badcase: the model emitted +group-search with --query; +chat-search provides the same group-name search operation.",
+	},
+	{
+		From:         "chat +group-send-text",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +send-to-group", "chat +messages-send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +group-send-text for a group text operation, but the invented name does not choose between name-resolved group text and the unified identifier-aware workflow; the write operation must not dispatch automatically.",
+	},
+	{
+		From:         "chat +list-group-bots",
+		Mode:         "rewrite",
+		To:           "chat +chat-bots",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +list-group-bots for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs.",
+	},
+	{
+		From:         "chat +list-my-groups",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +my-groups", "chat +chat-list-mine", "chat +chat-list"},
+		Reviewed:     true,
+		ReviewReason: "The invented name does not choose between the established resolver shortcut, the legacy personal-group list and the current Schema-complete chat list. Recovery must stop instead of silently changing pagination or output semantics.",
+	},
+	{
+		From:         "chat +list-robot",
+		Mode:         "rewrite",
+		To:           "chat +chat-bots",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted singular +list-robot for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs.",
+	},
+	{
+		From:         "chat +list-robots",
+		Mode:         "rewrite",
+		To:           "chat +chat-bots",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +list-robots for listing robots in one group; +chat-bots is the unique reviewed read-only shortcut. The fallback preserves flags and does not reinterpret generic IDs.",
+	},
+	{
+		From:         "chat +members",
+		Mode:         "rewrite",
+		To:           "chat +group-members",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation badcases emitted +members three times for listing members of a group selected by name; +group-members is the unique reviewed read-only shortcut for that intent.",
+	},
+	{
+		From:         "chat +message-list",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +chat-messages", "chat +messages-list-direct", "chat +search-msg", "chat +unread-chats"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +message-list without identifying group versus direct history, conversation history versus cross-chat search, or ordinary versus unread conversations; no candidate may be selected automatically.",
+	},
+	{
+		From:         "chat +read-single",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-list-direct", "chat +chat-messages"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +read-single six times for direct-message history, but the invented name does not choose between the focused direct-history shortcut and the broader group/direct history workflow; command recovery must stop before parameter validation or dispatch.",
+	},
+	{
+		From:         "chat +rename-group",
+		Mode:         "rewrite",
+		To:           "chat +chat-update",
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +rename-group for the unique group-name update intent; +chat-update is the reviewed shortcut with that exact command-level operation. Parameter compatibility remains the canonical target's responsibility.",
+	},
+	{
+		From:         "chat +send",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send without a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow.",
+	},
+	{
+		From:         "chat +send-by-bot",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat message send-by-bot"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-by-bot three times without a complete sending-identity contract; stop and present the unified identity-aware shortcut and the exact native bot sender instead of selecting a write path.",
+	},
+	{
+		From:         "chat +send-dm",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +dm", "chat +messages-send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-dm twice, but the invented name does not choose between the resolved-name text shortcut and the unified identifier-aware sending workflow; the write operation must not dispatch automatically.",
+	},
+	{
+		From:         "chat +send-file",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat message send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-file fifteen times with incompatible target and file parameter spellings; stop before dispatch and let the caller choose the unified shortcut or native current-user file workflow.",
+	},
+	{
+		From:         "chat +send-image",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat message send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-image without proving whether the input is an existing mediaId or a local file; stop before dispatch and let the caller choose the reviewed unified or native workflow.",
+	},
+	{
+		From:         "chat +send-media",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat message send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-media without a concrete media type, sending identity, or compatible parameter contract; stop before dispatch and let the caller choose the reviewed unified or native workflow.",
+	},
+	{
+		From:         "chat +send-message",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-message without a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow.",
+	},
+	{
+		From:         "chat +send-single",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +dm", "chat +messages-send"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-single for a direct message, but the invented name does not choose between the resolved-name text shortcut and the unified identifier-aware sending workflow; the write operation must not dispatch automatically.",
+	},
+	{
+		From:         "chat +send-text",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation identified text content but not a stable recipient type or sending identity; the write operation must stop until the caller chooses the unified, resolved-direct, or resolved-group workflow.",
+	},
+	{
+		From:         "chat +send-to",
+		Mode:         "ambiguous",
+		Candidates:   []string{"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		Reviewed:     true,
+		ReviewReason: "20260728 evaluation emitted +send-to without proving whether the recipient denotes a user, group, or low-level identifier; the write operation must not choose a target workflow automatically.",
+	},
+	{
+		From:         "doc +create-version",
+		Mode:         "rewrite",
+		To:           "doc +history-save",
+		Reviewed:     true,
+		ReviewReason: "202608 supplemental Doc badcase emitted +create-version while explicitly trying to save the current document as a recoverable history snapshot. +history-save is the unique current canonical shortcut for that operation and accepts the same --node value without parameter transformation.",
+	},
+	{
+		From:         "doc +list-templates",
+		Mode:         "rewrite",
+		To:           "doc +template-list",
+		Reviewed:     true,
+		ReviewReason: "202608 Doc experiments emitted +list-templates while discovering available templates. +template-list is the unique current public read-only shortcut for that operation; the rewrite changes only the command path and preserves flags for target validation.",
+	},
+	{
+		From:         "doc +save-version",
+		Mode:         "rewrite",
+		To:           "doc +history-save",
+		Reviewed:     true,
+		ReviewReason: "202608 supplemental Doc badcase emitted the verb/object inversion +save-version for a current-version snapshot. +history-save is the unique current canonical shortcut with the same document-node contract; the legacy +version-save path is not selected as the fallback target.",
+	},
+	{
+		From:         "doc +search-template",
+		Mode:         "rewrite",
+		To:           "doc +template-search",
+		Reviewed:     true,
+		ReviewReason: "202608 Doc experiments emitted the verb/object inversion +search-template. +template-search is the unique current public read-only template-name search shortcut; the rewrite preserves every flag and value.",
+	},
+	{
+		From:         "doc +snapshot",
+		Mode:         "rewrite",
+		To:           "doc +history-save",
+		Reviewed:     true,
+		ReviewReason: "202608 supplemental Doc badcase emitted +snapshot during an explicit save-current-version workflow. The current +history-save selection contract names this exact recoverable history-snapshot operation, so the reviewed rewrite preserves the --node value and does not infer an update or export workflow.",
+	},
+	{
+		From:         "doc +template",
+		Mode:         "ambiguous",
+		Candidates:   []string{"doc +template-list", "doc +template-search", "doc +create-from-template"},
+		Reviewed:     true,
+		ReviewReason: "202608 Doc experiments emitted the family-like +template without selecting browse, search, or create-from-template. Command recovery must stop before parameters or execution and present the three public workflows.",
+	},
+	{
+		From:         "doc +version",
+		Mode:         "ambiguous",
+		Candidates:   []string{"doc +history-list", "doc +history-save", "doc +history-revert"},
+		Reviewed:     true,
+		ReviewReason: "202608 Doc experiments emitted the family-like +version without choosing list, save, or revert. The write and high-risk revert operations cannot be selected from an umbrella name; present the canonical history shortcuts and stop.",
+	},
+	{
+		From:         "doc +version-create",
+		Mode:         "rewrite",
+		To:           "doc +history-save",
+		Reviewed:     true,
+		ReviewReason: "202608 supplemental Doc badcase emitted +version-create while saving the current document version. +history-save is the unique current canonical snapshot shortcut and the path-only rewrite leaves its real execution and safety contract authoritative.",
+	},
+	{
+		From:         "oa +list-processes",
+		Mode:         "ambiguous",
+		Candidates:   []string{"oa +list-forms", "oa +my-initiated", "oa approval list-initiated"},
+		Reviewed:     true,
+		ReviewReason: "20260720 merged evaluation emitted +list-processes, but process can mean approval forms/templates or approval instances initiated by the current user; stop and present both shortcut workflows plus the exact native instance leaf.",
+	},
+}
+
+func loadGeneratedCommandPathFallbacks() []CommandPathFallback {
+	return generatedCommandPathFallbacks
+}

internal/cli/command_path_fallbacks_lookup.go

@@ -0,0 +1,32 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package cli
+
+import "sync"
+
+var (
+	commandPathFallbackIndexOnce sync.Once
+	commandPathFallbackIndex     map[string]CommandPathFallback
+)
+
+func buildCommandPathFallbackIndex() {
+	entries := loadGeneratedCommandPathFallbacks()
+	commandPathFallbackIndex = make(map[string]CommandPathFallback, len(entries))
+	for _, entry := range entries {
+		commandPathFallbackIndex[entry.From] = entry
+	}
+}
+
+// LookupCommandPathFallback performs an exact O(1) lookup of a reviewed
+// recovery-only path. Normalization only removes a leading dws and folds
+// whitespace; it does not apply prefix, typo, or semantic matching.
+func LookupCommandPathFallback(rawPath string) (CommandPathFallback, bool) {
+	commandPathFallbackIndexOnce.Do(buildCommandPathFallbackIndex)
+	entry, ok := commandPathFallbackIndex[normalizeSchemaCLIPath(rawPath)]
+	if !ok {
+		return CommandPathFallback{}, false
+	}
+	entry.Candidates = append([]string(nil), entry.Candidates...)
+	return entry, true
+}

internal/cli/command_path_fallbacks_test.go

@@ -0,0 +1,372 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package cli
+
+import (
+	"encoding/json"
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+func commandFallbackJSON(entries string) []byte {
+	return []byte(`{"$schema":"./command_path_fallbacks.schema.json","version":1,"entries":` + entries + `}`)
+}
+
+func validCommandFallbackEntry(from, to string) string {
+	return `{"from":"` + from + `","mode":"rewrite","to":"` + to + `","reviewed":true,"review_reason":"reviewed fixture"}`
+}
+
+func TestCrossPlatformCoverageDecodeCommandPathFallbacksStrictContract(t *testing.T) {
+	valid := commandFallbackJSON(`[` + validCommandFallbackEntry(`chat +bad`, `chat +good`) + `]`)
+	entries, err := decodeCommandPathFallbacks(valid)
+	if err != nil || len(entries) != 1 || entries[0].From != "chat +bad" || entries[0].To != "chat +good" {
+		t.Fatalf("decode valid = %#v, %v", entries, err)
+	}
+	entries[0].Candidates = append(entries[0].Candidates, "mutated")
+	cloned := cloneCommandPathFallbacks(entries)
+	cloned[0].Candidates[0] = "clone"
+	if entries[0].Candidates[0] != "mutated" {
+		t.Fatal("cloneCommandPathFallbacks aliases candidate storage")
+	}
+
+	tests := map[string]struct {
+		data []byte
+		want string
+	}{
+		"unknown field": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"rewrite","to":"chat +good","reviewed":true,"review_reason":"x","extra":true}]`),
+			want: "unknown field",
+		},
+		"wrong schema": {
+			data: []byte(`{"$schema":"wrong","version":1,"entries":[` + validCommandFallbackEntry(`chat +bad`, `chat +good`) + `]}`),
+			want: "$schema",
+		},
+		"wrong version": {
+			data: []byte(`{"$schema":"./command_path_fallbacks.schema.json","version":2,"entries":[` + validCommandFallbackEntry(`chat +bad`, `chat +good`) + `]}`),
+			want: "unsupported",
+		},
+		"empty entries": {data: commandFallbackJSON(`[]`), want: "no entries"},
+		"unnormalized path": {
+			data: commandFallbackJSON(`[` + validCommandFallbackEntry(` chat  +bad `, `chat +good`) + `]`),
+			want: "not a normalized",
+		},
+		"unreviewed": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"rewrite","to":"chat +good","reviewed":false,"review_reason":"x"}]`),
+			want: "reviewed=true",
+		},
+		"empty reason": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"rewrite","to":"chat +good","reviewed":true,"review_reason":" "}]`),
+			want: "reviewed=true",
+		},
+		"invalid mode": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"guess","reviewed":true,"review_reason":"x"}]`),
+			want: "invalid mode",
+		},
+		"rewrite candidates": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"rewrite","to":"chat +good","candidates":["chat +one","chat +two"],"reviewed":true,"review_reason":"x"}]`),
+			want: "must not declare candidates",
+		},
+		"empty rewrite target": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"rewrite","reviewed":true,"review_reason":"x"}]`),
+			want: "path is empty",
+		},
+		"ambiguous target": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"ambiguous","to":"chat +good","candidates":["chat +one","chat +two"],"reviewed":true,"review_reason":"x"}]`),
+			want: "must not declare to",
+		},
+		"ambiguous too small": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"ambiguous","candidates":["chat +one"],"reviewed":true,"review_reason":"x"}]`),
+			want: "at least two",
+		},
+		"empty ambiguous candidate": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"ambiguous","candidates":["chat +one",""],"reviewed":true,"review_reason":"x"}]`),
+			want: "path is empty",
+		},
+		"duplicate candidate": {
+			data: commandFallbackJSON(`[{"from":"chat +bad","mode":"ambiguous","candidates":["chat +one","chat +one"],"reviewed":true,"review_reason":"x"}]`),
+			want: "repeats candidate",
+		},
+		"duplicate from": {
+			data: commandFallbackJSON(`[` + validCommandFallbackEntry(`chat +bad`, `chat +good`) + `,` + validCommandFallbackEntry(`chat +bad`, `chat +other`) + `]`),
+			want: "duplicate from",
+		},
+		"multiple documents": {
+			data: append(valid, []byte(` {}`)...),
+			want: "multiple JSON values",
+		},
+	}
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			if _, err := decodeCommandPathFallbacks(test.data); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("decode error = %v, want containing %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageCommandPathFallbackSchemaAndEmbeddedSource(t *testing.T) {
+	var schema map[string]any
+	if err := json.Unmarshal(embeddedCommandPathFallbacksSchemaJSON, &schema); err != nil {
+		t.Fatalf("decode embedded schema: %v", err)
+	}
+	if schema["$schema"] != "https://json-schema.org/draft/2020-12/schema" || schema["additionalProperties"] != false {
+		t.Fatalf("schema header = %#v", schema)
+	}
+	entries, err := LoadCommandPathFallbacks()
+	if err != nil || len(entries) != 34 {
+		t.Fatalf("LoadCommandPathFallbacks() = %#v, %v", entries, err)
+	}
+	if got, ok := LookupCommandPathFallback("dws chat +group-search"); !ok || got.To != "chat +chat-search" {
+		t.Fatalf("generated lookup = %#v, %v", got, ok)
+	}
+	if _, ok := LookupCommandPathFallback("chat +missing"); ok {
+		t.Fatal("generated lookup accepted unknown path")
+	}
+}
+
+func TestCrossPlatformCoverageCommandPathFallbackAuditCoverage(t *testing.T) {
+	rewrites := map[string]string{
+		"chat +bot-list":            "chat +chat-bots",
+		"chat +conversation-detail": "chat +conversation-info",
+		"chat +group-search":        "chat +chat-search",
+		"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",
+		"doc +create-version":       "doc +history-save",
+		"doc +list-templates":       "doc +template-list",
+		"doc +save-version":         "doc +history-save",
+		"doc +search-template":      "doc +template-search",
+		"doc +snapshot":             "doc +history-save",
+		"doc +version-create":       "doc +history-save",
+	}
+	for from, to := range rewrites {
+		entry, ok := LookupCommandPathFallback(from)
+		if !ok || entry.Mode != CommandPathFallbackRewrite || entry.To != to {
+			t.Errorf("rewrite %q = %#v, %v; want %q", from, entry, ok, to)
+		}
+	}
+
+	ambiguous := map[string][]string{
+		"chat +conversation-category-list": {"chat +category-list", "chat +category-list-conversations"},
+		"chat +conversation-group-list":    {"chat +category-list-conversations", "chat +conversation-list"},
+		"chat +group-send-text":            {"chat +send-to-group", "chat +messages-send"},
+		"chat +list-my-groups":             {"chat +my-groups", "chat +chat-list-mine", "chat +chat-list"},
+		"chat +message-list":               {"chat +chat-messages", "chat +messages-list-direct", "chat +search-msg", "chat +unread-chats"},
+		"chat +read-single":                {"chat +messages-list-direct", "chat +chat-messages"},
+		"chat +send":                       {"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		"chat +send-by-bot":                {"chat +messages-send", "chat message send-by-bot"},
+		"chat +send-dm":                    {"chat +dm", "chat +messages-send"},
+		"chat +send-message":               {"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		"chat +send-single":                {"chat +dm", "chat +messages-send"},
+		"chat +send-text":                  {"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		"chat +send-to":                    {"chat +messages-send", "chat +dm", "chat +send-to-group"},
+		"chat +send-file":                  {"chat +messages-send", "chat message send"},
+		"chat +send-image":                 {"chat +messages-send", "chat message send"},
+		"chat +send-media":                 {"chat +messages-send", "chat message send"},
+		"oa +list-processes":               {"oa +list-forms", "oa +my-initiated", "oa approval list-initiated"},
+		"doc +template":                    {"doc +template-list", "doc +template-search", "doc +create-from-template"},
+		"doc +version":                     {"doc +history-list", "doc +history-save", "doc +history-revert"},
+	}
+	for from, candidates := range ambiguous {
+		entry, ok := LookupCommandPathFallback(from)
+		if !ok || entry.Mode != CommandPathFallbackAmbiguous || !reflect.DeepEqual(entry.Candidates, candidates) {
+			t.Errorf("ambiguous %q = %#v, %v; want %v", from, entry, ok, candidates)
+		}
+	}
+
+	if entry, ok := LookupCommandPathFallback("chat +definitely-unknown"); ok {
+		t.Errorf("unreviewed path unexpectedly falls back: %#v", entry)
+	}
+}
+
+func TestCrossPlatformCoverageReduceCommandPathFallbacksValidatesLiveTree(t *testing.T) {
+	root := commandFallbackTestRoot()
+	entries := []CommandPathFallback{
+		{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +good", Reviewed: true, ReviewReason: "fixture"},
+		{From: "chat group search", Mode: CommandPathFallbackRewrite, To: "chat search", Reviewed: true, ReviewReason: "fixture"},
+		{From: "chat +choose", Mode: CommandPathFallbackAmbiguous, Candidates: []string{"chat +good", "chat +other"}, Reviewed: true, ReviewReason: "fixture"},
+		{From: "chat +mixed", Mode: CommandPathFallbackAmbiguous, Candidates: []string{"chat +good", "chat search"}, Reviewed: true, ReviewReason: "fixture"},
+	}
+	withCommandFallbackSource(t, entries)
+	got, err := ReduceCommandPathFallbacks(root)
+	if err != nil || len(got) != len(entries) {
+		t.Fatalf("ReduceCommandPathFallbacks() = %#v, %v", got, err)
+	}
+	got[2].Candidates[0] = "mutated"
+	again, err := ReduceCommandPathFallbacks(root)
+	if err != nil || again[2].Candidates[0] == "mutated" {
+		t.Fatalf("reduction did not clone candidates: %#v, %v", again, err)
+	}
+}
+
+func TestCrossPlatformCoverageReduceCommandPathFallbacksRejectsUnsafeMappings(t *testing.T) {
+	baseRoot := commandFallbackTestRoot
+	tests := map[string]struct {
+		entries []CommandPathFallback
+		mutate  func(*cobra.Command)
+		want    string
+	}{
+		"missing target": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +missing"}},
+			want:    "does not exist",
+		},
+		"real source collision": {
+			entries: []CommandPathFallback{{From: "chat +other", Mode: CommandPathFallbackRewrite, To: "chat +good"}},
+			want:    "collides with a real Cobra command or alias",
+		},
+		"cobra alias collision": {
+			entries: []CommandPathFallback{{From: "chat +official-alias", Mode: CommandPathFallbackRewrite, To: "chat +other"}},
+			want:    "collides with a real Cobra command or alias",
+		},
+		"cross service": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "mail +good"}},
+			want:    "crosses service boundary",
+		},
+		"shortcut mismatch": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat search"}},
+			want:    "disagree on +shortcut identity",
+		},
+		"chained rewrite": {
+			entries: []CommandPathFallback{
+				{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +next"},
+				{From: "chat +next", Mode: CommandPathFallbackRewrite, To: "chat +good"},
+			},
+			want: "chained fallbacks are forbidden",
+		},
+		"chained ambiguous candidate": {
+			entries: []CommandPathFallback{
+				{From: "chat +choose", Mode: CommandPathFallbackAmbiguous, Candidates: []string{"chat +good", "chat +next"}},
+				{From: "chat +next", Mode: CommandPathFallbackRewrite, To: "chat +other"},
+			},
+			want: "is another fallback source",
+		},
+		"missing ambiguous candidate": {
+			entries: []CommandPathFallback{{From: "chat +choose", Mode: CommandPathFallbackAmbiguous, Candidates: []string{"chat +good", "chat +missing"}}},
+			want:    "does not exist",
+		},
+		"hidden target": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +good"}},
+			mutate: func(root *cobra.Command) {
+				exactSchemaCommand(root, "chat +good").Hidden = true
+			},
+			want: "not a public runnable",
+		},
+		"target is alias": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +official-alias"}},
+			want:    "must use canonical Cobra names",
+		},
+		"ambiguous source command": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +good"}},
+			mutate: func(root *cobra.Command) {
+				chat := exactSchemaCommand(root, "chat")
+				chat.AddCommand(
+					&cobra.Command{Use: "+bad", Run: func(*cobra.Command, []string) {}},
+					&cobra.Command{Use: "+bad", Run: func(*cobra.Command, []string) {}},
+				)
+			},
+			want: "cannot be resolved safely",
+		},
+		"ambiguous target command": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackRewrite, To: "chat +duplicate"}},
+			mutate: func(root *cobra.Command) {
+				chat := exactSchemaCommand(root, "chat")
+				chat.AddCommand(
+					&cobra.Command{Use: "+duplicate", Run: func(*cobra.Command, []string) {}},
+					&cobra.Command{Use: "+duplicate", Run: func(*cobra.Command, []string) {}},
+				)
+			},
+			want: "target \"chat +duplicate\" cannot be resolved safely",
+		},
+		"unsupported reduced mode": {
+			entries: []CommandPathFallback{{From: "chat +bad", Mode: CommandPathFallbackMode("invalid")}},
+			want:    "unsupported mode",
+		},
+	}
+	for name, test := range tests {
+		t.Run(name, func(t *testing.T) {
+			root := baseRoot()
+			if test.mutate != nil {
+				test.mutate(root)
+			}
+			for index := range test.entries {
+				test.entries[index].Reviewed = true
+				test.entries[index].ReviewReason = "fixture"
+			}
+			withCommandFallbackSource(t, test.entries)
+			if _, err := ReduceCommandPathFallbacks(root); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("reduction error = %v, want containing %q", err, test.want)
+			}
+		})
+	}
+
+	withCommandFallbackLoadError(t, errors.New("fixture load"))
+	if _, err := ReduceCommandPathFallbacks(baseRoot()); err == nil || !strings.Contains(err.Error(), "fixture load") {
+		t.Fatalf("load error = %v", err)
+	}
+	if _, err := ReduceCommandPathFallbacks(nil); err == nil || !strings.Contains(err.Error(), "root is nil") {
+		t.Fatalf("nil root error = %v", err)
+	}
+	if got := commandFallbackService(""); got != "" {
+		t.Fatalf("commandFallbackService(empty) = %q", got)
+	}
+}
+
+func commandFallbackTestRoot() *cobra.Command {
+	root := &cobra.Command{Use: "dws"}
+	chat := &cobra.Command{Use: "chat"}
+	good := &cobra.Command{Use: "+good", Aliases: []string{"+official-alias"}, Run: func(*cobra.Command, []string) {}}
+	chat.AddCommand(
+		good,
+		&cobra.Command{Use: "+other", Run: func(*cobra.Command, []string) {}},
+		&cobra.Command{Use: "search", Run: func(*cobra.Command, []string) {}},
+	)
+	group := &cobra.Command{Use: "group"}
+	group.AddCommand(cmdutil.HintSubCmd("search", "use chat search"))
+	chat.AddCommand(group)
+	mail := &cobra.Command{Use: "mail"}
+	mail.AddCommand(&cobra.Command{Use: "+good", Run: func(*cobra.Command, []string) {}})
+	root.AddCommand(chat, mail)
+	return root
+}
+
+func withCommandFallbackSource(t *testing.T, entries []CommandPathFallback) {
+	t.Helper()
+	old := loadReviewedCommandPathFallbacks
+	loadReviewedCommandPathFallbacks = func() ([]CommandPathFallback, error) {
+		return cloneCommandPathFallbacks(entries), nil
+	}
+	t.Cleanup(func() { loadReviewedCommandPathFallbacks = old })
+}
+
+func withCommandFallbackLoadError(t *testing.T, want error) {
+	t.Helper()
+	old := loadReviewedCommandPathFallbacks
+	loadReviewedCommandPathFallbacks = func() ([]CommandPathFallback, error) { return nil, want }
+	t.Cleanup(func() { loadReviewedCommandPathFallbacks = old })
+}
+
+func TestCrossPlatformCoverageCommandPathFallbackGeneratedTableWellFormed(t *testing.T) {
+	entries := loadGeneratedCommandPathFallbacks()
+	if len(entries) == 0 {
+		t.Fatal("generated command path fallback table is empty")
+	}
+	seen := map[string]bool{}
+	for _, entry := range entries {
+		if seen[entry.From] || !entry.Reviewed || strings.TrimSpace(entry.ReviewReason) == "" {
+			t.Fatalf("invalid generated entry: %#v", entry)
+		}
+		seen[entry.From] = true
+	}
+	if !reflect.DeepEqual(entries, cloneCommandPathFallbacks(entries)) {
+		t.Fatal("generated table clone changed values")
+	}
+}

internal/cli/gen.go

@@ -27,7 +27,9 @@
 //   3. schema_parameter_mapping_ledger.go  mapping exclusions / removals (Go)
 //                                         (active bindings retired; ParamDecl.Property owns delivery)
 //   4. param_concepts.json + schema       reviewed parameter synonym policy
-//   5. cobra command tree (Go runtime)     flags/usage/required (reflected)
+//   5. command_path_fallbacks.json + schema
+//                                        reviewed recovery-only invalid paths
+//   6. cobra command tree (Go runtime)     flags/usage/required (reflected)
 //
 // schema_hints/, schema_agent_metadata/, schema_command_registry/,
 // schema_mcp_metadata.json, and schema_mcp_service_review(.json|/ledger) are
@@ -35,7 +37,9 @@
 //
 // Remaining generated output from this file:
 //   - param_aliases_generated.go           per-command parameter normalization
+//   - command_path_fallbacks_generated.go  invalid-path recovery normalization
 
 package cli
 
 //go:generate go run ../generator/cmd_param_aliases -root ../.. -output param_aliases_generated.go
+//go:generate go run ../generator/cmd_command_path_fallbacks -root ../.. -output command_path_fallbacks_generated.go

internal/cli/generate_entrypoint_contract_test.go

@@ -21,7 +21,7 @@ import (
 	"testing"
 )
 
-func TestGoGenerateDirectivesStayInUnifiedEntryPoint(t *testing.T) {
+func TestCrossPlatformCoverageGoGenerateDirectivesStayInUnifiedEntryPoint(t *testing.T) {
 	entries, err := os.ReadDir(".")
 	if err != nil {
 		t.Fatalf("read internal/cli: %v", err)
@@ -50,6 +50,7 @@ func TestGoGenerateDirectivesStayInUnifiedEntryPoint(t *testing.T) {
 	for _, generator := range []string{
 		"cmd_schema_catalog",
 		"cmd_param_aliases",
+		"cmd_command_path_fallbacks",
 	} {
 		if !bytes.Contains(content, []byte("//go:generate go run")) || !bytes.Contains(content, []byte(generator)) {
 			t.Errorf("gen.go does not register %s", generator)

internal/cli/param_concepts.json

@@ -10,35 +10,41 @@
   },
 
   "concepts": {
-    "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +template-search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"},
-    "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "mail thread list", "oa +list-executed"], "risk": "green"},
+    "search_query": {"denotes": "search keyword string", "canonical_hint": "query", "members": ["query", "keyword", "keywords", "q", "search-word"], "excludes": ["name", "subject", "text", "title"], "commands": ["aitable +base-search", "contact +dept-members", "contact +resolve-dept", "contact +search-user", "doc +create-from-template", "doc +find-doc", "doc +search", "doc +template-search", "doc template search", "mail +find-mail-user", "mail user search", "oa +search-forms", "oa approval search-forms"], "risk": "green"},
+    "pagination_size": {"denotes": "returned item count upper bound", "canonical_hint": "limit", "members": ["limit", "size", "page-size", "max-results", "max-result", "take", "top", "per-page"], "excludes": ["count", "page", "cursor"], "commands": ["aitable record query", "calendar event list", "chat message list", "devdoc article search", "doc +comment-list", "doc +find-doc", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list", "mail thread list", "oa +list-executed"], "risk": "green"},
     "page_number": {"denotes": "one-based page number", "canonical_hint": "page", "members": ["page", "page-no", "current-page", "page-num"], "excludes": ["cursor", "page-index", "page-size", "page-token"], "commands": ["devdoc article search"], "risk": "green"},
-    "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list"], "risk": "green"},
-    "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc block insert", "doc block update"], "risk": "green"},
+    "page_cursor": {"denotes": "pagination cursor/token", "canonical_hint": "cursor", "members": ["cursor", "next-cursor", "page-token", "next-token", "next-page-token"], "excludes": ["page", "offset"], "commands": ["calendar event list", "doc +comment-list", "doc +list", "doc +search", "doc +template-list", "doc +template-search", "doc +version-list", "doc comment list", "doc template list", "doc template search", "doc version list"], "risk": "green"},
+    "content_text": {"denotes": "text body content", "canonical_hint": "text", "members": ["text", "content", "body"], "excludes": ["title", "name"], "commands": ["doc +checkpoint-update", "doc +comment-create", "doc +comment-reply", "doc +comment-update", "doc +create", "doc +doc-append", "doc block insert", "doc block update", "doc comment create", "doc comment create-inline", "doc comment reply", "doc comment update", "doc create"], "risk": "green"},
     "time_start": {"denotes": "start time point with unchanged value format and unit", "canonical_hint": "start", "members": ["start", "start-time", "start-date", "from", "from-date", "begin", "since", "time-min", "min-time"], "excludes": ["date", "time", "end"], "commands": ["calendar event list", "chat message list-all", "report list"], "risk": "yellow"},
     "time_end": {"denotes": "end time point with unchanged value format and unit", "canonical_hint": "end", "members": ["end", "end-time", "end-date", "time-max", "max-time"], "excludes": ["date", "time", "start"], "commands": ["calendar event list"], "risk": "yellow"},
     "base_id": {"denotes": "multi-dimensional table Base id", "canonical_hint": "base-id", "members": ["base", "base-id", "base-token"], "excludes": [], "commands": ["aitable +field-get", "aitable +list-tables", "aitable +record-query", "aitable +record-share-url", "aitable +table-get"], "risk": "green"},
     "dept_id": {"denotes": "single department id", "canonical_hint": "dept", "members": ["dept", "dept-id", "department", "department-id", "parent", "parent-id"], "excludes": ["depts", "dept-ids", "department-ids", "name", "query"], "commands": ["contact +list-sub-depts", "contact dept list-children"], "risk": "yellow"},
     "dept_ids": {"denotes": "department id list", "canonical_hint": "dept-ids", "members": ["depts", "dept-ids", "department-ids"], "excludes": ["dept", "dept-id", "department-id", "name", "query"], "commands": ["contact +list-dept-members"], "risk": "yellow"},
-    "group_id": {"denotes": "single DingTalk numeric groupId", "canonical_hint": "group-id", "members": ["group-id"], "excludes": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id", "conversation-ids", "open-conversation-ids", "group-name", "name", "id"], "commands": ["chat group get-by-group-id"], "risk": "yellow"},
-    "open_conversation_id": {"denotes": "single DingTalk openConversationId with unchanged value", "canonical_hint": "conversation-id", "members": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id"], "excludes": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids", "group-name", "name", "id", "source", "target", "src-conversation-id", "dest-conversation-id"], "commands": ["chat +chat-bots", "chat +chat-dismiss", "chat +chat-invite-url", "chat +chat-mute", "chat +chat-role-add", "chat +chat-role-list", "chat +chat-role-query-user", "chat +chat-role-set-user", "chat +chat-role-update", "chat +chat-set-admin", "chat +chat-set-history", "chat +chat-update-alias", "chat +chat-update-nick", "chat +conversation-info", "chat +messages-list-pin", "chat +messages-read-status", "chat category add-conv", "chat category remove-conv", "chat chmod", "chat clear-messages", "chat clear-red-point", "chat conversation-info", "chat group audit-join-validation", "chat group bots", "chat group dismiss", "chat group invite-url", "chat group members", "chat group members add", "chat group members add-bot", "chat group members list-by-ids", "chat group members remove", "chat group members remove-bot", "chat group notice create", "chat group notice edit", "chat group notice get", "chat group notice list", "chat group quit", "chat group rename", "chat group set-admin", "chat group set-history", "chat group transfer-owner", "chat group update-alias", "chat group update-icon", "chat group update-nick", "chat group update-settings", "chat group-mute", "chat group-mute-member", "chat group-role add", "chat group-role list", "chat group-role query-user", "chat group-role remove", "chat group-role remove-user", "chat group-role set-user", "chat group-role update", "chat hide", "chat mark-read", "chat mark-unread", "chat message add-favorite", "chat message download-media", "chat message list", "chat message list-mentions", "chat message list-pin-msg", "chat message list-topic-replies", "chat message read-status", "chat message recall", "chat message recall-by-bot", "chat message remove-favorite", "chat message reply", "chat message search", "chat message send", "chat message send-by-bot", "chat message send-card", "chat message set-pin-msg", "chat message set-top-msg", "chat message unset-pin-msg", "chat message unset-top-msg", "chat mute-at-all", "chat mute-red-envelope", "chat set-top"], "risk": "yellow"},
+    "group_id": {"denotes": "single DingTalk numeric groupId", "canonical_hint": "group-id", "members": ["group-id"], "excludes": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id", "conversation-ids", "open-conversation-ids", "group-name", "name", "id"], "commands": ["chat +chat-get-by-id", "chat group get-by-group-id"], "risk": "yellow"},
+    "open_conversation_id": {"denotes": "single DingTalk openConversationId with unchanged value", "canonical_hint": "conversation-id", "members": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id"], "excludes": ["group-id", "group-ids", "conversation-ids", "open-conversation-ids", "group-name", "name", "id", "source", "target", "src-conversation-id", "dest-conversation-id"], "commands": ["chat +category-add-conversation", "chat +category-remove-conversation", "chat +chat-add-bot", "chat +chat-audit-join", "chat +chat-bots", "chat +chat-dismiss", "chat +chat-invite-url", "chat +chat-members-get", "chat +chat-mute", "chat +chat-mute-member", "chat +chat-quit", "chat +chat-remove-bot", "chat +chat-role-add", "chat +chat-role-list", "chat +chat-role-query-user", "chat +chat-role-remove", "chat +chat-role-remove-user", "chat +chat-role-set-user", "chat +chat-role-update", "chat +chat-set-admin", "chat +chat-set-history", "chat +chat-transfer-owner", "chat +chat-update-alias", "chat +chat-update-icon", "chat +chat-update-nick", "chat +chat-update-settings", "chat +conversation-clear-messages", "chat +conversation-clear-red-point", "chat +conversation-hide", "chat +conversation-info", "chat +conversation-mark-read", "chat +conversation-mark-unread", "chat +conversation-mute", "chat +flag-cancel", "chat +flag-create", "chat +messages-add-emoji", "chat +messages-add-text-emotion", "chat +messages-list-pin", "chat +messages-read-status", "chat +messages-recall-by-bot", "chat +messages-remove-emoji", "chat +messages-remove-text-emotion", "chat +messages-reply", "chat +messages-resource-download", "chat +messages-resource-url", "chat +messages-send-by-bot", "chat +messages-set-pin", "chat +messages-set-top", "chat +messages-unset-pin", "chat +messages-unset-top", "chat category add-conv", "chat category remove-conv", "chat chmod", "chat clear-messages", "chat clear-red-point", "chat conversation-info", "chat group audit-join-validation", "chat group bots", "chat group dismiss", "chat group invite-url", "chat group members", "chat group members add", "chat group members add-bot", "chat group members list-by-ids", "chat group members remove", "chat group members remove-bot", "chat group notice create", "chat group notice edit", "chat group notice get", "chat group notice list", "chat group quit", "chat group rename", "chat group set-admin", "chat group set-history", "chat group transfer-owner", "chat group update-alias", "chat group update-icon", "chat group update-nick", "chat group update-settings", "chat group-mute", "chat group-mute-member", "chat group-role add", "chat group-role list", "chat group-role query-user", "chat group-role remove", "chat group-role remove-user", "chat group-role set-user", "chat group-role update", "chat hide", "chat mark-read", "chat mark-unread", "chat message add-favorite", "chat message download-media", "chat message list", "chat message list-mentions", "chat message list-pin-msg", "chat message list-topic-replies", "chat message read-status", "chat message recall", "chat message recall-by-bot", "chat message remove-favorite", "chat message reply", "chat message search", "chat message send", "chat message send-by-bot", "chat message send-card", "chat message set-pin-msg", "chat message set-top-msg", "chat message unset-pin-msg", "chat message unset-top-msg", "chat mute-at-all", "chat mute-red-envelope", "chat set-top"], "risk": "yellow"},
     "open_conversation_ids": {"denotes": "DingTalk openConversationId list with unchanged element values", "canonical_hint": "conversation-ids", "members": ["conversation-ids", "open-conversation-ids", "groups"], "excludes": ["group-id", "group-ids", "conversation-id", "open-conversation-id", "chat-id"], "commands": ["chat message search-advanced"], "risk": "yellow"},
     "group_name": {"denotes": "group-name search keyword, not a group identifier", "canonical_hint": "group-name", "members": ["group-name"], "excludes": ["group-id", "conversation-id", "open-conversation-id", "chat-id", "id"], "commands": ["chat +group-members", "chat +send-to-group"], "risk": "yellow"},
-    "open_message_id": {"denotes": "single DingTalk openMessageId with unchanged value", "canonical_hint": "open-message-id", "members": ["msg-id", "message-id", "open-message-id"], "excludes": ["msg-ids", "message-ids", "open-message-ids", "ref-msg-id", "src-msg-id", "open-task-id", "topic-id", "resource-id"], "commands": ["chat +messages-read-status", "chat mark-read", "chat message add-emoji", "chat message add-favorite", "chat message add-text-emotion", "chat message download-media", "chat message forward", "chat message read-status", "chat message recall", "chat message remove-emoji", "chat message remove-favorite", "chat message remove-text-emotion", "chat message set-pin-msg", "chat message set-top-msg", "chat message unset-pin-msg", "chat message unset-top-msg"], "risk": "yellow"},
-    "open_message_ids": {"denotes": "DingTalk openMessageId list with unchanged element values", "canonical_hint": "msg-ids", "members": ["msg-ids", "message-ids", "open-message-ids"], "excludes": ["msg-id", "message-id", "open-message-id", "ref-msg-id", "src-msg-id"], "commands": ["chat +messages-mget", "chat message combine-forward", "chat message list-by-ids", "chat message list-emotion-replies"], "risk": "yellow"},
-    "referenced_open_message_id": {"denotes": "referenced DingTalk openMessageId in a reply", "canonical_hint": "ref-msg-id", "members": ["ref-msg-id", "ref-message-id"], "excludes": ["msg-id", "message-id", "open-message-id", "msg-ids", "src-msg-id"], "commands": ["chat message reply"], "risk": "yellow"},
+    "open_message_id": {"denotes": "single DingTalk openMessageId with unchanged value", "canonical_hint": "open-message-id", "members": ["msg-id", "message-id", "open-message-id"], "excludes": ["msg-ids", "message-ids", "open-message-ids", "ref-msg-id", "src-msg-id", "open-task-id", "topic-id", "resource-id"], "commands": ["chat +conversation-mark-read", "chat +flag-cancel", "chat +flag-create", "chat +messages-add-emoji", "chat +messages-add-text-emotion", "chat +messages-forward", "chat +messages-read-status", "chat +messages-remove-emoji", "chat +messages-remove-text-emotion", "chat +messages-resource-download", "chat +messages-set-pin", "chat +messages-set-top", "chat +messages-unset-pin", "chat +messages-unset-top", "chat mark-read", "chat message add-emoji", "chat message add-favorite", "chat message add-text-emotion", "chat message download-media", "chat message forward", "chat message read-status", "chat message recall", "chat message remove-emoji", "chat message remove-favorite", "chat message remove-text-emotion", "chat message set-pin-msg", "chat message set-top-msg", "chat message unset-pin-msg", "chat message unset-top-msg"], "risk": "yellow"},
+    "open_message_ids": {"denotes": "DingTalk openMessageId list with unchanged element values", "canonical_hint": "msg-ids", "members": ["msg-ids", "message-ids", "open-message-ids"], "excludes": ["msg-id", "message-id", "open-message-id", "ref-msg-id", "src-msg-id"], "commands": ["chat +flag-cancel", "chat +flag-create", "chat +messages-combine-forward", "chat +messages-mget", "chat message combine-forward", "chat message list-by-ids", "chat message list-emotion-replies"], "risk": "yellow"},
+    "referenced_open_message_id": {"denotes": "referenced DingTalk openMessageId in a reply", "canonical_hint": "ref-msg-id", "members": ["ref-msg-id", "ref-message-id"], "excludes": ["msg-id", "message-id", "open-message-id", "msg-ids", "src-msg-id"], "commands": ["chat +messages-reply", "chat message reply"], "risk": "yellow"},
     "user_id": {"denotes": "single user id", "canonical_hint": "user-id", "members": ["user", "user-id", "userid", "uid", "staff-id"], "excludes": ["at-user-ids", "to-user", "users", "user-ids", "name"], "commands": ["chat +chat-role-query-user", "chat +chat-role-set-user", "chat +messages-list-direct", "chat chmod", "chat conversation-info", "chat group transfer-owner", "chat group-role query-user", "chat group-role remove-user", "chat group-role set-user", "chat message list", "chat message send", "contact user profile get"], "risk": "yellow"},
-    "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot"], "risk": "yellow"},
-    "open_dingtalk_ids": {"denotes": "DingTalk openDingTalkId list with unchanged element values", "canonical_hint": "open-dingtalk-ids", "members": ["open-dingtalk-ids"], "excludes": ["user", "user-id", "user-ids", "staff-id", "users"], "commands": ["chat category create-smart", "chat group members list-by-ids", "chat message send-by-bot"], "risk": "yellow"},
+    "user_ids": {"denotes": "user id list", "canonical_hint": "user-ids", "members": ["users", "user-ids"], "excludes": ["user", "user-id", "userid", "uid", "staff-id", "at-user-ids"], "commands": ["attendance +check-result", "attendance check result", "chat +messages-batch-send-by-bot", "chat group members remove", "chat group set-admin", "chat group-mute-member", "chat message read-status", "chat message search-advanced", "chat message send-by-bot"], "risk": "yellow"},
+    "open_dingtalk_ids": {"denotes": "DingTalk openDingTalkId list with unchanged element values", "canonical_hint": "open-dingtalk-ids", "members": ["open-dingtalk-ids"], "excludes": ["user", "user-id", "user-ids", "staff-id", "users"], "commands": ["chat +chat-members-get", "chat category create-smart", "chat group members list-by-ids", "chat message send-by-bot"], "risk": "yellow"},
     "ding_id": {"denotes": "DING id", "canonical_hint": "ding-id", "members": ["ding-id", "open-ding-id"], "excludes": ["id"], "commands": ["ding message receiver-status"], "risk": "yellow"},
     "folder_id": {"denotes": "drive folder id", "canonical_hint": "folder", "members": ["folder", "folder-id"], "excludes": ["space-id"], "commands": ["drive list", "mail folder update"], "risk": "green"},
-    "space_id": {"denotes": "drive/wiki space id", "canonical_hint": "space-id", "members": ["space-id", "space", "workspace", "workspace-id"], "excludes": ["folder", "node"], "commands": ["drive info"], "risk": "yellow"},
+    "space_id": {"denotes": "drive/wiki/Doc workspace id with unchanged value", "canonical_hint": "space-id", "members": ["space-id", "space", "workspace", "workspace-id"], "excludes": ["folder", "node"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +copy", "doc +create", "doc +create-from-template", "doc +grant-and-share", "doc +import", "doc +list", "doc +move", "doc create", "doc file create", "doc import", "doc template apply", "drive info"], "risk": "yellow"},
     "app_id": {"denotes": "application id", "canonical_hint": "unified-app-id", "members": ["app-id", "unified-app-id", "application-id"], "excludes": ["app-key", "app-secret", "agent-id"], "commands": ["dev app get"], "risk": "yellow"},
-    "robot_code": {"denotes": "robot code", "canonical_hint": "robot-code", "members": ["robot-code", "robot"], "excludes": ["robot-id"], "commands": ["chat group members add-bot", "chat message recall-by-bot", "chat message send-by-bot", "ding message send"], "risk": "yellow"},
-    "open_bot_id": {"denotes": "single DingTalk openBotId with unchanged value", "canonical_hint": "bot-id", "members": ["bot-id", "open-bot-id"], "excludes": ["robot-code", "robot", "robot-id", "bot-code"], "commands": ["chat group members remove-bot"], "risk": "yellow"}
+    "robot_code": {"denotes": "robot code", "canonical_hint": "robot-code", "members": ["robot-code", "robot"], "excludes": ["robot-id", "bot-id", "open-bot-id", "bot-code"], "commands": ["chat +chat-add-bot", "chat +messages-batch-recall-by-bot", "chat +messages-batch-send-by-bot", "chat +messages-recall-by-bot", "chat +messages-send-by-bot", "chat group members add-bot", "chat message recall-by-bot", "chat message send-by-bot", "ding message send"], "risk": "yellow"},
+    "open_bot_id": {"denotes": "single DingTalk openBotId with unchanged value", "canonical_hint": "bot-id", "members": ["bot-id", "open-bot-id"], "excludes": ["robot-code", "robot", "robot-id", "bot-code"], "commands": ["chat +chat-remove-bot", "chat group members remove-bot"], "risk": "yellow"},
+    "doc_node_id": {"denotes": "single DingTalk document nodeId or accepted document URL/token with unchanged value", "canonical_hint": "node", "members": ["node", "node-id", "doc", "doc-id", "file-id", "document-id", "url"], "excludes": ["id", "folder", "folder-id", "parent-id", "workspace", "workspace-id", "block-id", "comment-id", "comment-key", "job-id", "task-id", "template-id", "version", "revision"], "commands": ["doc +access-change", "doc +access-grant", "doc +access-revoke", "doc +background-delete", "doc +background-update", "doc +checkpoint-update", "doc +comment-create", "doc +comment-delete", "doc +comment-list", "doc +comment-reply", "doc +comment-update", "doc +copy", "doc +doc-append", "doc +export", "doc +export-submit", "doc +fetch", "doc +history-list", "doc +history-revert", "doc +history-save", "doc +inspect", "doc +move", "doc +review", "doc +version-list", "doc +version-revert", "doc +version-save", "doc block delete", "doc block insert", "doc block list", "doc block update", "doc comment create", "doc comment create-inline", "doc comment delete", "doc comment list", "doc comment reply", "doc comment update", "doc export", "doc info", "doc media download", "doc media insert", "doc media upload", "doc read", "doc style background clear", "doc style background set", "doc style cover clear", "doc style cover set", "doc style get", "doc update", "doc version list", "doc version revert", "doc version save", "doc whiteboard insert"], "risk": "yellow"},
+    "doc_comment_key": {"denotes": "single DingTalk document commentKey with unchanged value", "canonical_hint": "comment-key", "members": ["comment-key", "comment-id"], "excludes": ["id", "node", "node-id", "doc-id", "block-id"], "commands": ["doc +comment-delete", "doc +comment-reply", "doc +comment-update", "doc comment delete", "doc comment reply", "doc comment update"], "risk": "yellow"},
+    "doc_version_number": {"denotes": "single DingTalk document historical version number with unchanged integer value", "canonical_hint": "version", "members": ["version", "version-number", "version-no"], "excludes": ["revision", "id", "node", "node-id", "doc-id"], "commands": ["doc +history-revert", "doc +version-revert", "doc version revert"], "risk": "yellow"},
+    "doc_content_format": {"denotes": "DingTalk document body format with unchanged markdown/jsonml value", "canonical_hint": "content-format", "members": ["content-format", "doc-format"], "excludes": ["format", "export-format", "mime-type"], "commands": ["doc +create", "doc +update", "doc create", "doc update"], "risk": "green"},
+    "doc_edit_revision": {"denotes": "single optimistic-concurrency revision for a document edit", "canonical_hint": "revision", "members": ["revision", "expected-revision"], "excludes": ["version", "version-number", "version-no"], "commands": ["doc +update", "doc update"], "risk": "yellow"}
   },
 
   "command_overrides": {
+	"doc +version-list": {"ambiguous": ["size", "max-results", "max-result", "take", "top", "per-page", "next-cursor", "next-token", "next-page-token"], "note": "--limit/--cursor and the shipped visible compatibility flags --page-size/--page-token remain native. Other pagination spellings cannot choose between two visible real flags and must stop before execution."},
     "chat group rename": {"bind": {"id": "open_conversation_id"}, "note": "This command's real --id carries one openConversationId; aliases reduce to --id without changing the value."},
     "chat group members": {"bind": {"id": "open_conversation_id"}},
     "chat group members add": {"bind": {"id": "open_conversation_id"}, "block": ["user-id", "open-dingtalk-id"], "note": "The real --users is a list and may contain mixed userId/openDingTalkId values; singular inputs are not promoted automatically."},
@@ -91,10 +97,24 @@
     "chat group-role set-user": {"block": ["role-id"], "note": "This command requires a role-id list; one id is not promoted into a batch input."},
     "chat +messages-send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact shortcut."},
     "chat message send-by-webhook": {"scoped_aliases": {"at-user-ids": "at-users"}, "scope_strict": true, "note": "Both names denote the same userId list used for @ mentions on this exact command."},
-    "doc block insert": {"block": ["before-block-id"], "note": "requires a two-parameter conversion to --ref-block plus --where before; name-only normalization would silently default to after"},
+    "doc block insert": {"block": ["before-block-id"], "note": "Parent and reference roles remain distinct. --before-block-id needs both --ref-block and --where before, while role-free --block-id cannot choose parent versus reference.", "scoped_aliases": {"parent-block-id": "parent-block", "ref-block-id": "ref-block", "reference-block-id": "ref-block"}, "ambiguous": ["block-id"], "scope_strict": true},
     "chat message send-by-bot": {"scoped_aliases": {"at-users": "at-user-ids"}, "block": ["user-id", "to-user-id"], "ambiguous": ["at-ids"], "note": "The reviewed @ userId-list alias is exact; singular recipients are not promoted, and bare --at-ids cannot choose an identifier domain."},
-    "doc +export-get": {"block": ["node"], "note": "node is a document node id, a different entity from job-id"},
+    "doc +export-get": {"block": ["doc-id", "document-id", "file-id", "node", "node-id", "task-id", "url"], "note": "This command queries one export jobId. Document node identifiers and import taskId spellings are different entities and are rejected.", "scoped_aliases": {"export-job-id": "job-id"}, "scope_strict": true},
     "doc block delete": {"block": ["index"], "note": "index (position) vs node (node id) are different"},
+    "doc +copy": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."},
+    "doc +list": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."},
+    "doc +move": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."},
+    "doc comment create": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
+    "doc comment reply": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
+    "doc comment update": {"scoped_aliases": {"mentioned-open-conversation-ids": "mentioned-open-conversation-id", "open-conversation-id": "mentioned-open-conversation-id", "open-conversation-ids": "mentioned-open-conversation-id"}, "block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids"], "scope_strict": true, "note": "The target is a list of mentioned openConversationIds. Explicit open-conversation spellings preserve the list value; numeric groupId and role-free conversation spellings are rejected."},
+    "doc +comment-create": {"block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "open-conversation-id", "open-conversation-ids"], "note": "This shortcut has no group-mention flag or payload field. Group-conversation spellings are blocked instead of inventing unsupported capability; route to the stable doc comment command when group mentions are required."},
+    "doc +comment-reply": {"block": ["chat-id", "chat-ids", "conversation-id", "conversation-ids", "group-id", "group-ids", "mentioned-open-conversation-id", "mentioned-open-conversation-ids", "open-conversation-id", "open-conversation-ids"], "note": "This shortcut has no group-mention flag or payload field. Group-conversation spellings are blocked instead of inventing unsupported capability; route to the stable doc comment command when group mentions are required."},
+    "doc media insert": {"scoped_aliases": {"ref-block-id": "ref-block", "reference-block-id": "ref-block"}, "block": ["before-block-id", "parent-block", "parent-block-id"], "ambiguous": ["block-id"], "scope_strict": true, "note": "Media insertion supports a reference block but no parent-block role. --before-block-id additionally needs --where before; role-free --block-id is left ambiguous."},
+    "doc read": {"block": ["before-block-id", "parent-block-id", "ref-block-id", "reference-block-id"], "ambiguous": ["block-id"], "note": "A section read requires --scope section plus a start/end boundary. A role-free --block-id cannot be reduced to one flag without inventing the missing scope/boundary role."},
+    "doc export get": {"scoped_aliases": {"export-job-id": "job-id"}, "block": ["doc-id", "document-id", "file-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one export jobId. Document node identifiers are rejected; native hidden --task-id remains the command's reviewed add-only compatibility alias for --job-id."},
+    "doc import get": {"scoped_aliases": {"import-task-id": "task-id"}, "block": ["doc-id", "document-id", "file-id", "job-id", "node", "node-id", "url"], "scope_strict": true, "note": "This command queries one import taskId. Document node identifiers and export jobId spellings are different entities and are rejected."},
+    "doc +share-doc": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a document nodeId into a URL, so identifier spellings are rejected with guidance to provide --url."},
+    "doc update": {"block": ["version", "version-no", "version-number"], "note": "--revision is an optimistic-concurrency revision, not a historical document version number. Version spellings must not reduce to --revision."},
     "report outbox list": {"block": ["template-type"], "note": "type vs name are different fields"},
     "chat group members add-bot": {"bind": {"id": "open_conversation_id"}},
     "chat group members list-by-ids": {"bind": {"id": "open_conversation_id", "users": "open_dingtalk_ids"}, "block": ["user-id", "user-ids"], "note": "This command's --id carries openConversationId, while --users carries an openDingTalkId list."},
@@ -111,7 +131,48 @@
     "chat category create-smart": {"bind": {"members": "open_dingtalk_ids"}, "scoped_aliases": {"title": "name"}, "note": "The real --members is an openDingTalkId list; the reviewed title/name alias is exact to the category display name."},
     "chat group audit-join-validation": {"ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "note": "A role-free user identifier cannot choose between the required --applicant and --inviter roles."},
     "chat message reply": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The required --ref-sender is a role-specific openDingTalkId and must not accept generic userId spellings."},
-    "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."}
+    "chat message send-card": {"block": ["user", "user-id", "userid", "uid", "staff-id"], "note": "The real --receiver is a role-specific openDingTalkId and must not accept generic userId spellings."},
+    "chat +category-add-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."},
+    "chat +category-list-conversations": {"block": ["category-ids"], "note": "The real --category-id is singular; list cardinality is not reduced automatically."},
+    "chat +category-remove-conversation": {"block": ["category-id"], "note": "The real --category-ids is a list; a singular category ID is not promoted automatically."},
+    "chat +chat-add-bot": {"bind": {"id": "open_conversation_id"}, "note": "The real --id is the group's openConversationId; robotCode and openBotId remain different domains."},
+    "chat +chat-audit-join": {"scoped_aliases": {"applicant-user-id": "applicant", "inviter-user-id": "inviter"}, "ambiguous": ["user", "user-id", "userid", "uid", "staff-id"], "scope_strict": true, "note": "A role-free user identifier cannot choose between applicant and inviter."},
+    "chat +chat-create": {"block": ["user-id", "open-dingtalk-id"], "note": "The real --users field is a list and may contain mixed identifier domains; a singular value is not promoted."},
+    "chat +chat-get-by-id": {"block": ["group", "conversation-id", "chat", "chat-id", "open-conversation-id", "conversation-ids", "open-conversation-ids", "group-name", "name", "id"], "note": "The real --group-id is numeric groupId; no CID or group-name spelling can be value-preservingly converted."},
+    "chat +chat-members-get": {"bind": {"id": "open_conversation_id", "users": "open_dingtalk_ids"}, "block": ["group", "group-name", "user-id", "user-ids"], "note": "The real --id is openConversationId and --users is an openDingTalkId list. The observed --group spelling carried a natural group name and is blocked; explicit CID spellings and --chat remain value-preserving aliases."},
+    "chat +chat-members-list": {"scoped_aliases": {"chat-id": "conversation-id", "id": "conversation-id"}, "block": ["query", "keyword", "group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "scope_strict": true, "note": "Native --chat/--open-conversation-id stay native; member filtering by query is unsupported and group-name resolution stays on --group/--chat-query."},
+    "chat +chat-mute-member": {"scoped_aliases": {"user-ids": "users", "open-dingtalk-ids": "users"}, "block": ["user", "user-id", "open-dingtalk-id"], "scope_strict": true, "note": "The target accepts a mixed identifier list; list spellings preserve values, but singular inputs are not promoted."},
+    "chat +chat-remove-bot": {"bind": {"id": "open_conversation_id"}, "note": "The real --id is openConversationId; --bot-id is separately governed by open_bot_id."},
+    "chat +chat-role-remove": {"block": ["role-ids"], "note": "The command removes one role ID; list cardinality is not reduced."},
+    "chat +chat-role-remove-user": {"scoped_aliases": {"user-id": "user", "open-dingtalk-id": "user"}, "block": ["role-id"], "scope_strict": true, "note": "The single --user accepts either identifier domain; --role-ids remains a list."},
+    "chat +chat-transfer-owner": {"scoped_aliases": {"user-id": "new-owner", "open-dingtalk-id": "new-owner"}, "scope_strict": true, "note": "The only user role is the new owner, and the target accepts either userId or openDingTalkId without changing the value."},
+    "chat +chat-update": {"scoped_aliases": {"conversation-id": "group", "open-conversation-id": "group", "chat-id": "group", "title": "name", "new-title": "name"}, "block": ["id", "group-id", "group-ids", "conversation-ids", "open-conversation-ids"], "scope_strict": true, "note": "--group accepts a name or CID, so only explicit CID spellings are mapped; generic --id is blocked."},
+    "chat +conversation-set-top": {"scoped_aliases": {"open-conversation-id": "conversation-id", "chat-id": "conversation-id", "open-conversation-ids": "conversation-ids", "chat-ids": "conversation-ids"}, "block": ["group", "groups", "group-id", "group-ids", "top", "set-top"], "scope_strict": true, "note": "Singular/list cardinality stays explicit; top/set-top cannot be rewritten to the inverse --off switch."},
+    "chat +feed-group-query-item": {"scoped_aliases": {"open-conversation-ids": "conversation-ids", "chat-ids": "conversation-ids"}, "block": ["group", "groups", "group-id", "group-ids", "conversation-id", "open-conversation-id"], "scope_strict": true, "note": "The real field is an openConversationId list; group names and singular IDs are not converted."},
+    "chat +flag-list": {"scoped_aliases": {"limit": "page-size"}, "block": ["max", "max-results", "max-size", "count", "page", "per-page"], "scope_strict": true, "note": "Native --page-size is the canonical page bound, native --size is its command-owned compatibility alias, and --limit is reviewed as value-preservingly equivalent to --page-size; total-count and page-number spellings are not equivalent."},
+    "chat +messages-batch-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values returned by bot sending; it is not an openMessageId field."},
+    "chat +messages-combine-forward": {"scoped_aliases": {"src-open-cid": "src-conversation-id", "src-open-conversation-id": "src-conversation-id", "source-conversation-id": "src-conversation-id", "dest-open-cid": "dest-conversation-id", "dest-open-conversation-id": "dest-conversation-id", "target-conversation-id": "dest-conversation-id", "destination-conversation-id": "dest-conversation-id"}, "block": ["group-id", "group-ids"], "ambiguous": ["conversation-id", "open-conversation-id", "group", "chat", "chat-id", "id"], "scope_strict": true, "note": "Source and destination conversation roles remain explicit; role-free CID spellings cannot choose a side."},
+    "chat +messages-forward": {"scoped_aliases": {"src-open-cid": "src-conversation-id", "src-open-conversation-id": "src-conversation-id", "source-conversation-id": "src-conversation-id", "dest-open-cid": "dest-conversation-id", "dest-open-conversation-id": "dest-conversation-id", "target-conversation-id": "dest-conversation-id", "destination-conversation-id": "dest-conversation-id", "src-open-message-id": "msg-id", "source-message-id": "msg-id"}, "block": ["group-id", "group-ids"], "ambiguous": ["conversation-id", "open-conversation-id", "group", "chat", "chat-id", "id"], "scope_strict": true, "note": "The message role is uniquely the source message, but source/destination conversation roles cannot be inferred from a generic CID."},
+    "chat +messages-forward-topic": {"scoped_aliases": {"src-open-conversation-id": "src-conversation-id", "source-conversation-id": "src-conversation-id", "dest-open-conversation-id": "dest-conversation-id", "target-conversation-id": "dest-conversation-id", "destination-conversation-id": "dest-conversation-id", "src-open-message-id": "src-msg-id", "source-message-id": "src-msg-id"}, "block": ["group-id", "group-ids", "msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "ambiguous": ["conversation-id", "open-conversation-id", "group", "chat", "chat-id", "id"], "scope_strict": true, "note": "Source and destination conversation roles and the source-message role remain explicit; role-free message IDs and list cardinality are not inferred."},
+    "chat +messages-list": {"scoped_aliases": {"start": "time"}, "block": ["before", "before-time", "end", "direction", "page-all", "count", "max", "max-results", "max-size", "page-size"], "scope_strict": true, "note": "start preserves the same boundary value; before/direction require multi-parameter or value transforms and page-all requires iteration. Native --conversation-id/--id/--size remain native."},
+    "chat +messages-recall-by-bot": {"block": ["msg-id", "message-id", "open-message-id", "msg-ids", "message-ids", "open-message-ids"], "note": "--keys carries processQueryKey values, not openMessageId values."},
+    "chat +messages-reply": {"scoped_aliases": {"msg-id": "ref-msg-id", "open-message-id": "ref-msg-id"}, "block": ["group", "msg-ids", "message-ids", "open-message-ids"], "scope_strict": true, "note": "The observed --group spelling carried a natural group name and is blocked. The only message role is the referenced message; plural IDs are not accepted, while --chat remains a CID alias and native --message-id stays native."},
+    "chat +messages-resource-download": {"block": ["download-dir"], "note": "--output may be a file or directory under workspace safety rules; a download directory cannot be assumed equivalent."},
+    "doc +create": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["content-file", "parent-id"], "scope_strict": true, "note": "--content-format is value-preservingly normalized to --doc-format. A raw --content-file path cannot become --content without adding the required @file transform, so it is blocked with guidance to use @relative-path or stable doc create."},
+    "doc +create-from-template": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."},
+    "doc +import": {"scoped_aliases": {"folder-id": "folder", "parent-folder": "folder", "parent-folder-id": "folder", "parent-node-id": "folder"}, "block": ["parent-id"], "scope_strict": true, "note": "This exact Doc command expects a Doc folder nodeId/dentryUuid/URL. Reviewed folder spellings preserve that value; generic --parent-id stays blocked because it may carry a numeric Drive dentryId."},
+    "doc +update": {"scoped_aliases": {"mode": "command", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node", "url": "node"}, "block": ["content-file"], "scope_strict": true, "note": "--mode append/overwrite is the same operation selector subset as --command and preserves its value. --content-file is blocked because +update requires @relative-path or stdin and central aliases cannot read/transform a file value."},
+    "doc +inspect": {"scoped_aliases": {"include-versions": "include-history"}, "block": ["include", "include-info"], "scope_strict": true, "note": "Historical versions and history are the same optional section on this exact shortcut. Generic --include needs value-dependent flag expansion, while base document info is always returned, so those spellings are rejected with precise guidance."},
+    "doc +fetch": {"scoped_aliases": {"start-block": "start-block-id", "end-block": "end-block-id"}, "ambiguous": ["block-id"], "scope_strict": true, "note": "Start/end block roles are preserved. A role-free --block-id cannot choose a range/section boundary and must stop before execution."},
+    "doc +media-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose between document and media identities."},
+    "doc +media-insert": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and local-media roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."},
+    "doc +media-list": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "The command lists media inside one document, so only strong document spellings map to --node. File and URL spellings remain role-ambiguous."},
+    "doc +media-preview": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has both document-node and attachment-resource roles. Strong document spellings map to --node; --file-id and --url cannot safely choose a role."},
+    "doc +resource-delete": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command removes a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."},
+    "doc +resource-download": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command downloads a document resource while targeting the document by --node. File and URL spellings do not uniquely identify that document role."},
+    "doc +resource-update": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "node-id": "node"}, "ambiguous": ["file-id", "url"], "scope_strict": true, "note": "This command has document-node, local-file, and HTTPS image URL roles. Only strong document spellings map to --node; --file-id and --url must stop as ambiguous."},
+    "doc +share": {"block": ["doc", "doc-id", "document-id", "file-id", "id", "node", "node-id"], "note": "The real --url requires a shareable document link. Name-only normalization cannot turn a node identifier into a URL, so identifier spellings are rejected with guidance to provide --url."},
+    "doc +grant-and-share": {"scoped_aliases": {"doc": "node", "doc-id": "node", "document-id": "node", "file-id": "node", "node-id": "node"}, "scope_strict": true, "note": "This workflow has two different real URL roles: --node selects the document for access control and --url is the shareable link sent to recipients. Explicit document-ID spellings map only to --node; --url remains native."}
   },
 
   "validation_fixture": {
@@ -258,8 +319,117 @@
       {"command": "chat +unread-chats", "emitted": "size", "expect": "count", "via": "override:scoped"},
       {"command": "chat category rename", "emitted": "name", "expect": "title", "via": "override:scoped"},
       {"command": "chat message list-unread-conversations", "emitted": "size", "expect": "count", "via": "override:scoped"},
+      {"command": "doc +comment-create", "emitted": "node-id", "expect": "node", "via": "concept:doc_node_id"},
+      {"command": "doc +doc-append", "emitted": "node", "expect": "doc", "via": "concept:doc_node_id"},
+      {"command": "doc +find-doc", "emitted": "keyword", "expect": "query", "via": "concept:search_query"},
+      {"command": "doc +search", "emitted": "q", "expect": "query", "via": "concept:search_query"},
+      {"command": "doc +comment-list", "emitted": "max-results", "expect": "limit", "via": "concept:pagination_size"},
+      {"command": "doc +list", "emitted": "page-token", "expect": "cursor", "via": "concept:page_cursor"},
+      {"command": "doc +copy", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"},
+      {"command": "doc +copy", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"},
+      {"command": "doc +copy", "emitted": "parent-id", "expect": "did-you-mean:blocked", "via": "guard:doc-folder-value-domain"},
+      {"command": "doc +comment-reply", "emitted": "comment-id", "expect": "comment-key", "via": "concept:doc_comment_key"},
+      {"command": "doc comment reply", "emitted": "mentioned-open-conversation-ids", "expect": "mentioned-open-conversation-id", "via": "override:scoped-role-list"},
+      {"command": "doc comment reply", "emitted": "group-id", "expect": "did-you-mean:blocked", "via": "guard:numeric-group-id-vs-open-conversation-id"},
+      {"command": "doc +comment-create", "emitted": "mentioned-open-conversation-id", "expect": "did-you-mean:blocked", "via": "guard:shortcut-missing-capability"},
+      {"command": "doc block insert", "emitted": "parent-block-id", "expect": "parent-block", "via": "override:scoped-block-role"},
+      {"command": "doc block insert", "emitted": "block-id", "expect": "did-you-mean:ambiguous", "via": "guard:parent-vs-reference-block-role"},
+      {"command": "doc media insert", "emitted": "before-block-id", "expect": "did-you-mean:blocked", "via": "guard:requires-ref-block-plus-where"},
+      {"command": "doc read", "emitted": "block-id", "expect": "did-you-mean:ambiguous", "via": "guard:requires-scope-and-boundary-role"},
+      {"command": "doc export get", "emitted": "node", "expect": "did-you-mean:blocked", "via": "guard:document-node-vs-export-job"},
+      {"command": "doc import get", "emitted": "job-id", "expect": "did-you-mean:blocked", "via": "guard:export-job-vs-import-task"},
+      {"command": "doc +version-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "doc +version-revert", "emitted": "revision", "expect": "did-you-mean:blocked", "via": "concept:doc_version_number+exclude"},
+      {"command": "doc update", "emitted": "version", "expect": "did-you-mean:blocked", "via": "guard:historical-version-vs-edit-revision"},
+      {"command": "doc +share-doc", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"},
+      {"command": "doc +comment-create", "emitted": "body", "expect": "content", "via": "concept:content_text"},
+      {"command": "doc +doc-append", "emitted": "content", "expect": "text", "via": "concept:content_text"},
+      {"command": "doc +export-submit", "emitted": "doc-id", "expect": "node", "via": "concept:doc_node_id"},
+      {"command": "doc +move", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"},
+      {"command": "doc +template-list", "emitted": "next-token", "expect": "cursor", "via": "concept:page_cursor"},
+      {"command": "doc +version-list", "emitted": "page-size", "expect": "limit", "via": "concept:pagination_size"},
+      {"command": "doc +version-save", "emitted": "file-id", "expect": "node", "via": "concept:doc_node_id"},
+      {"command": "doc comment create", "emitted": "text", "expect": "content", "via": "concept:content_text"},
+      {"command": "doc comment create-inline", "emitted": "body", "expect": "content", "via": "concept:content_text"},
+      {"command": "doc comment delete", "emitted": "comment-id", "expect": "comment-key", "via": "concept:doc_comment_key"},
+      {"command": "doc comment update", "emitted": "comment-id", "expect": "comment-key", "via": "concept:doc_comment_key"},
+      {"command": "doc version revert", "emitted": "version-no", "expect": "version", "via": "concept:doc_version_number"},
       {"command": "chat +chat-messages", "emitted": "chat", "expect": "group", "via": "override:scoped-eval"},
-      {"command": "chat +search-msg", "emitted": "chat", "expect": "group", "via": "override:scoped-eval"}
+      {"command": "chat +search-msg", "emitted": "chat", "expect": "group", "via": "override:scoped-eval"},
+      {"command": "chat +chat-update", "emitted": "chat-id", "expect": "group", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +chat-update", "emitted": "conversation-id", "expect": "group", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +chat-update", "emitted": "open-conversation-id", "expect": "group", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +chat-update", "emitted": "id", "expect": "did-you-mean:blocked", "via": "guard:generic-id-value-domain"},
+      {"command": "chat +chat-update", "emitted": "title", "expect": "name", "via": "override:scoped-group-title"},
+      {"command": "chat +chat-update", "emitted": "new-title", "expect": "name", "via": "override:scoped-group-title"},
+      {"command": "chat +flag-list", "emitted": "limit", "expect": "page-size", "via": "override:scoped-page-bound"},
+      {"command": "chat +flag-list", "emitted": "max", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"},
+      {"command": "chat +flag-list", "emitted": "max-results", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"},
+      {"command": "chat +flag-list", "emitted": "max-size", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"},
+      {"command": "chat +chat-members-list", "emitted": "chat-id", "expect": "conversation-id", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +chat-members-list", "emitted": "id", "expect": "conversation-id", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +chat-members-list", "emitted": "query", "expect": "did-you-mean:blocked", "via": "guard:unsupported-member-filter"},
+      {"command": "chat +conversation-set-top", "emitted": "open-conversation-id", "expect": "conversation-id", "via": "override:scoped-explicit-cid"},
+      {"command": "chat +conversation-set-top", "emitted": "chat-ids", "expect": "conversation-ids", "via": "override:scoped-explicit-cid-list"},
+      {"command": "chat +conversation-set-top", "emitted": "groups", "expect": "did-you-mean:blocked", "via": "guard:group-name-or-list-ambiguity"},
+      {"command": "chat +conversation-set-top", "emitted": "top", "expect": "did-you-mean:blocked", "via": "guard:inverse-boolean-semantics"},
+      {"command": "chat +chat-members-get", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"},
+      {"command": "chat +chat-members-get", "emitted": "open-dingtalk-ids", "expect": "users", "via": "concept:open_dingtalk_ids+bind"},
+      {"command": "chat +chat-members-get", "emitted": "group", "expect": "did-you-mean:blocked", "via": "guard:group-name-vs-open-conversation-id"},
+      {"command": "chat +chat-members-get", "emitted": "chat", "expect": "id", "via": "concept:open_conversation_id+bind"},
+      {"command": "chat +chat-get-by-id", "emitted": "group", "expect": "did-you-mean:blocked", "via": "guard:open-conversation-id-vs-numeric-group-id"},
+      {"command": "chat +messages-list", "emitted": "start", "expect": "time", "via": "override:scoped-time-boundary"},
+      {"command": "chat +messages-list", "emitted": "count", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"},
+      {"command": "chat +messages-list", "emitted": "max-results", "expect": "did-you-mean:blocked", "via": "guard:page-size-vs-total-count"},
+      {"command": "chat +messages-list", "emitted": "page-all", "expect": "did-you-mean:blocked", "via": "guard:requires-pagination-loop"},
+      {"command": "chat +messages-reply", "emitted": "msg-id", "expect": "ref-msg-id", "via": "override:scoped-reference-message"},
+      {"command": "chat +messages-reply", "emitted": "group", "expect": "did-you-mean:blocked", "via": "guard:group-name-vs-open-conversation-id"},
+      {"command": "chat +messages-reply", "emitted": "chat", "expect": "conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "chat +flag-cancel", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "chat +flag-cancel", "emitted": "chat", "expect": "conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "chat +flag-create", "emitted": "group", "expect": "conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "chat +chat-add-bot", "emitted": "conversation-id", "expect": "id", "via": "concept:open_conversation_id+bind"},
+      {"command": "chat +chat-add-bot", "emitted": "robot", "expect": "robot-code", "via": "concept:robot_code"},
+      {"command": "chat +chat-audit-join", "emitted": "applicant-user-id", "expect": "applicant", "via": "override:scoped-user-role"},
+      {"command": "chat +chat-audit-join", "emitted": "user-id", "expect": "did-you-mean:ambiguous", "via": "guard:applicant-vs-inviter-role"},
+      {"command": "chat +chat-create", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list"},
+      {"command": "chat +chat-mute-member", "emitted": "user-ids", "expect": "users", "via": "override:scoped-mixed-id-list"},
+      {"command": "chat +chat-mute-member", "emitted": "user-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list"},
+      {"command": "chat +chat-remove-bot", "emitted": "open-bot-id", "expect": "bot-id", "via": "concept:open_bot_id"},
+      {"command": "chat +chat-role-remove", "emitted": "role-ids", "expect": "did-you-mean:blocked", "via": "guard:list-vs-single"},
+      {"command": "chat +chat-role-remove-user", "emitted": "open-dingtalk-id", "expect": "user", "via": "override:scoped-mixed-id"},
+      {"command": "chat +chat-transfer-owner", "emitted": "user-id", "expect": "new-owner", "via": "override:scoped-owner-role"},
+      {"command": "chat +feed-group-query-item", "emitted": "chat-ids", "expect": "conversation-ids", "via": "override:scoped-explicit-cid-list"},
+      {"command": "chat +feed-group-query-item", "emitted": "conversation-id", "expect": "did-you-mean:blocked", "via": "guard:single-vs-list"},
+      {"command": "chat +messages-batch-recall-by-bot", "emitted": "message-id", "expect": "did-you-mean:blocked", "via": "guard:process-query-key-vs-open-message-id"},
+      {"command": "chat +messages-combine-forward", "emitted": "src-open-cid", "expect": "src-conversation-id", "via": "override:scoped-source-role"},
+      {"command": "chat +messages-combine-forward", "emitted": "conversation-id", "expect": "did-you-mean:ambiguous", "via": "guard:source-vs-destination-role"},
+      {"command": "chat +messages-forward", "emitted": "source-message-id", "expect": "msg-id", "via": "override:scoped-source-role"},
+      {"command": "chat +messages-forward", "emitted": "conversation-id", "expect": "did-you-mean:ambiguous", "via": "guard:source-vs-destination-role"},
+      {"command": "chat +messages-forward-topic", "emitted": "src-open-message-id", "expect": "src-msg-id", "via": "override:scoped-source-role"},
+      {"command": "chat +messages-forward-topic", "emitted": "message-id", "expect": "did-you-mean:blocked", "via": "guard:message-source-role"},
+      {"command": "chat +messages-recall-by-bot", "emitted": "message-id", "expect": "did-you-mean:blocked", "via": "guard:process-query-key-vs-open-message-id"},
+      {"command": "chat +messages-resource-download", "emitted": "conversation-id", "expect": "open-conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "chat +messages-resource-download", "emitted": "download-dir", "expect": "did-you-mean:blocked", "via": "guard:output-file-or-directory-contract"},
+      {"command": "chat +messages-set-pin", "emitted": "conversation-id", "expect": "open-conversation-id", "via": "concept:open_conversation_id"},
+      {"command": "doc +create", "emitted": "content-format", "expect": "doc-format", "via": "concept:doc_content_format"},
+      {"command": "doc +create", "emitted": "content-file", "expect": "did-you-mean:blocked", "via": "guard:requires-file-read-transform"},
+      {"command": "doc +inspect", "emitted": "include-versions", "expect": "include-history", "via": "override:scoped-section"},
+      {"command": "doc +inspect", "emitted": "include", "expect": "did-you-mean:blocked", "via": "guard:requires-value-dependent-flag-expansion"},
+      {"command": "doc +inspect", "emitted": "include-info", "expect": "did-you-mean:blocked", "via": "guard:base-info-always-returned"},
+      {"command": "doc +update", "emitted": "mode", "expect": "command", "via": "override:scoped-operation"},
+      {"command": "doc +update", "emitted": "revision", "expect": "expected-revision", "via": "concept:doc_edit_revision"},
+      {"command": "doc +update", "emitted": "version", "expect": "did-you-mean:blocked", "via": "guard:historical-version-vs-edit-revision"},
+      {"command": "doc +fetch", "emitted": "start-block", "expect": "start-block-id", "via": "override:scoped-boundary-role"},
+      {"command": "doc +fetch", "emitted": "block-id", "expect": "did-you-mean:ambiguous", "via": "guard:start-vs-end-boundary-role"},
+      {"command": "doc +access-grant", "emitted": "doc-id", "expect": "node", "via": "concept:doc_node_id"},
+      {"command": "doc +history-revert", "emitted": "version-number", "expect": "version", "via": "concept:doc_version_number"},
+      {"command": "doc +create-from-template", "emitted": "keyword", "expect": "query", "via": "concept:search_query"},
+      {"command": "doc +create-from-template", "emitted": "workspace-id", "expect": "workspace", "via": "concept:space_id"},
+      {"command": "doc +create-from-template", "emitted": "parent-folder-id", "expect": "folder", "via": "override:scoped-doc-folder"},
+      {"command": "doc +media-download", "emitted": "file-id", "expect": "did-you-mean:ambiguous", "via": "guard:document-node-vs-attachment-resource-role"},
+      {"command": "doc +resource-update", "emitted": "url", "expect": "did-you-mean:ambiguous", "via": "guard:document-url-vs-image-url-role"},
+      {"command": "doc +share", "emitted": "node-id", "expect": "did-you-mean:blocked", "via": "guard:node-id-needs-url-conversion"}
     ]
   }
 }

internal/cli/schema_parameter_mapping_ledger.go

@@ -256,6 +256,10 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"chat.list_conversation_message_v2 --open-dingtalk-id":               "selects the alternate list_individual_chat_message branch",
 	"chat.list_conversation_message_v2 --user":                           "selects the alternate list_individual_chat_message branch",
 	"chat.list_message_favorites --cursor":                               "Reviewed unpinned adapter: chat.list_message_favorites has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
+	"chat.list_message_favorites --max-items":                            "Reviewed helper-only pagination control: --max-items caps aggregated CLI output for chat.list_message_favorites and is not sent to the remote adapter.",
+	"chat.list_message_favorites --page-all":                             "Reviewed helper-only pagination control: --page-all enables CLI-side looping for chat.list_message_favorites and is not sent to the remote adapter.",
+	"chat.list_message_favorites --page-delay":                           "Reviewed helper-only pagination control: --page-delay controls local delay between chat.list_message_favorites pages and is not sent to the remote adapter.",
+	"chat.list_message_favorites --page-limit":                           "Reviewed helper-only pagination control: --page-limit caps CLI-side page fetches for chat.list_message_favorites and is not sent to the remote adapter.",
 	"chat.list_message_favorites --size":                                 "Reviewed unpinned adapter: chat.list_message_favorites has no singular pinned interface_ref; --size is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.query_msg_read_status --user":                                  "conditional wrapper: parseCSVValues + appendChatIDArgs routes each supplied identifier to targetUserIds or targetOpenDingTalkIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.query_msg_read_status --users":                                 "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to targetUserIds or targetOpenDingTalkIds according to its runtime ID shape; there is no single RPC property for this flag",
@@ -592,10 +596,26 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"sheet.range_batch_clear --node":                                     "Reviewed unpinned adapter: sheet.range_batch_clear has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
 	"sheet.range_batch_clear --ranges":                                   "Reviewed unpinned adapter: sheet.range_batch_clear has no singular pinned interface_ref; --ranges is a CLI wrapper input and does not publish a direct interface property.",
 	"sheet.range_batch_clear --type":                                     "Reviewed unpinned adapter: sheet.range_batch_clear has no singular pinned interface_ref; --type is a CLI wrapper input and does not publish a direct interface property.",
-	"sheet.range_batch_set_style --batch":                                "Composite wrapper reads this local JSON file and performs zero or more update_range calls; the filesystem path is not a direct RPC property.",
-	"sheet.range_batch_set_style --continue-on-error":                    "Composite wrapper consumes this flag in its local multi-call error loop and never sends it to update_range.",
+	"sheet.range_batch_set_style --batch":                                "Composite wrapper reads this local JSON file and assembles it into a single sheet/batch_update operations array; the filesystem path is not a direct RPC property.",
+	"sheet.range_batch_set_style --continue-on-error":                    "Reviewed unpinned adapter: sheet.range_batch_set_style has no singular pinned interface_ref; --continue-on-error is forwarded to sheet/batch_update as continueOnError and does not publish a direct interface property.",
 	"sheet.range_read --range":                                           "Reviewed unpinned adapter: sheet.range_read has no singular pinned interface_ref; --range is a CLI wrapper input and does not publish a direct interface property.",
 	"sheet.range_read --sheet-id":                                        "Reviewed unpinned adapter: sheet.range_read has no singular pinned interface_ref; --sheet-id is a CLI wrapper input and does not publish a direct interface property.",
+	"sheet.range_set_style --bg-color":                                   "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.backgroundColor across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --bg-colors-json":                             "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.backgroundColor across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --border-styles-json":                         "Composite stamp wrapper: set-style attaches this object as cells[][].borderStyles on every cell of the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-color":                                 "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.fontColor across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-colors-json":                           "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.fontColor across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-family":                                "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.fontFamily across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-line":                                  "Composite stamp wrapper: set-style expands this single-choice flag into the cells[][].cellStyles.textUnderline and textLineThrough booleans of the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-size":                                  "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.fontSize across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-sizes-json":                            "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.fontSize across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-style":                                 "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.fontStyle across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-weight":                                "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.fontWeight across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --font-weights-json":                          "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.fontWeight across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --h-align":                                    "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.horizontalAlignment across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --h-aligns-json":                              "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.horizontalAlignment across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --v-align":                                    "Composite stamp wrapper: set-style expands this flag into cells[][].cellStyles.verticalAlignment across the set_cell_range matrix; it has no top-level RPC property.",
+	"sheet.range_set_style --v-aligns-json":                              "Composite stamp wrapper: set-style expands this per-cell matrix into cells[][].cellStyles.verticalAlignment across the set_cell_range matrix; it has no top-level RPC property.",
 	"sheet.reply_sheet_comment --comment-key":                            "Reviewed unpinned adapter: sheet.reply_sheet_comment has no singular pinned interface_ref; --comment-key is a CLI wrapper input and does not publish a direct interface property.",
 	"sheet.reply_sheet_comment --content":                                "Reviewed unpinned adapter: sheet.reply_sheet_comment has no singular pinned interface_ref; --content is a CLI wrapper input and does not publish a direct interface property.",
 	"sheet.reply_sheet_comment --emoji":                                  "Reviewed unpinned adapter: sheet.reply_sheet_comment has no singular pinned interface_ref; --emoji is a CLI wrapper input and does not publish a direct interface property.",

internal/corecmd/corecmd.go

@@ -558,6 +558,18 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) {
 		for _, alias := range flag.Aliases {
 			RegisterFlag(cmd, flag.Kind, alias, "", flag.Usage+" (alias)")
 			_ = cmd.Flags().MarkHidden(alias)
+			if registered := cmd.Flags().Lookup(alias); registered != nil {
+				runtimeannotate.SetFlagAnnotation(
+					registered,
+					runtimeannotate.AnnotationFlagAliasOf,
+					flag.Name,
+				)
+				runtimeannotate.SetFlagAnnotation(
+					registered,
+					runtimeannotate.AnnotationFlagAliasOrigin,
+					runtimeannotate.FlagAliasOriginCorecmdV1,
+				)
+			}
 		}
 		if flag.MarkRequired {
 			_ = cmd.MarkFlagRequired(flag.Name)

internal/corecmd/corecmd_test.go

@@ -90,11 +90,17 @@ func TestCrossPlatformCoverageRegisterFlagsAllKinds(t *testing.T) {
 		}
 	}
 	// Aliases are registered with the main kind and hidden.
-	for _, alias := range []string{"i-alias", "sl-alias"} {
+	for alias, canonical := range map[string]string{"i-alias": "i", "sl-alias": "sl"} {
 		f := cmd.Flags().Lookup(alias)
 		if f == nil || !f.Hidden {
 			t.Fatalf("alias %q = %#v, want registered+hidden", alias, f)
 		}
+		if got := f.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != canonical {
+			t.Fatalf("alias %q annotation = %#v, want alias_of %q", alias, got, canonical)
+		}
+		if got := f.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
+			t.Fatalf("alias %q origin = %#v, want corecmd FlagSpec marker", alias, got)
+		}
 	}
 	if cmd.Flags().Lookup("i-alias").Value.Type() != "int" {
 		t.Fatal("int alias must be registered as int")

internal/corecmd/runtimeannotate/interface_alias.go

@@ -0,0 +1,25 @@
+// 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 runtimeannotate
+
+// CLI flag alias evidence is kept in this narrow file so the base-owned
+// Interface Snapshot helper can add the protocol constants to an older stable
+// worktree without replacing that revision's complete runtimeannotate package.
+// Only corecmd.FlagSpec.Aliases writes the exact origin; neither field is a
+// Schema synonym or final payload-equivalence proof.
+const (
+	AnnotationFlagAliasOf     = "dws.compat.alias_of"
+	AnnotationFlagAliasOrigin = "dws.compat.alias_origin"
+	FlagAliasOriginCorecmdV1  = "corecmd.flag_spec_aliases.v1"
+)

internal/errors/coverage_edges_test.go

@@ -41,7 +41,7 @@ func TestCrossPlatformCoverageDiagnosticsAndErrorRenderingEdges(t *testing.T) {
 		t.Fatalf("PrintJSON friendly diagnostics = %q, %v", out.String(), err)
 	}
 	out.Reset()
-	if err := PrintHumanAt(&out, err, VerbosityVerbose); err != nil || !strings.Contains(out.String(), "开启地址") {
+	if err := PrintHumanAt(&out, err, VerbosityVerbose); err != nil || !strings.Contains(out.String(), "处理入口") {
 		t.Fatalf("PrintHuman friendly diagnostics = %q, %v", out.String(), err)
 	}
 	out.Reset()

internal/errors/errors.go

@@ -19,6 +19,7 @@ import (
 	stderrors "errors"
 	"fmt"
 	"io"
+	"net/url"
 	"strings"
 	"time"
 
@@ -460,7 +461,7 @@ func PrintHumanAt(w io.Writer, err error, v Verbosity) error {
 			lines = append(lines, tui.Cyan("Hint: "+friendlyHint))
 		}
 		if actionURL != "" {
-			lines = append(lines, tui.White("Action: 开启地址: "+actionURL))
+			lines = append(lines, tui.White("Action: 处理入口: "+actionURL))
 		}
 	}
 
@@ -540,7 +541,7 @@ func PrintHumanAt(w io.Writer, err error, v Verbosity) error {
 
 func serverGuidance(diag ServerDiagnostics) (string, string) {
 	friendlyHint := strings.TrimSpace(diag.FriendlyHint)
-	actionURL := strings.TrimSpace(diag.ActionURL)
+	actionURL := safeServerActionURL(diag.ActionURL)
 	if friendlyHint == "" || actionURL == "" {
 		switch diag.ServerErrorCode {
 		case "TOKEN_VERIFIED_FAILED", "CLI_ORG_NOT_AUTHORIZED":
@@ -555,6 +556,19 @@ func serverGuidance(diag ServerDiagnostics) (string, string) {
 	return friendlyHint, actionURL
 }
 
+func safeServerActionURL(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+	parsed, err := url.Parse(raw)
+	if err != nil || !strings.EqualFold(parsed.Scheme, "https") ||
+		parsed.Hostname() == "" || parsed.User != nil {
+		return ""
+	}
+	return parsed.String()
+}
+
 func category(err error) string {
 	var typed *Error
 	if stderrors.As(err, &typed) {

internal/errors/errors_test.go

@@ -336,11 +336,40 @@ func TestCrossPlatformCoveragePrintHumanIncludesServerGuidance(t *testing.T) {
 	if !strings.Contains(got, "Hint: 请联系管理员开通消息搜索权益") {
 		t.Fatalf("expected server guidance in output, got %q", got)
 	}
-	if !strings.Contains(got, "Action: 开启地址: https://example.test/enable-search") {
+	if !strings.Contains(got, "Action: 处理入口: https://example.test/enable-search") {
 		t.Fatalf("expected server action URL in output, got %q", got)
 	}
 }
 
+func TestCrossPlatformCoverageServerGuidanceSuppressesUnsafeActionURL(t *testing.T) {
+	t.Parallel()
+	for _, actionURL := range []string{
+		"http://example.test/help",
+		"javascript:alert(1)",
+		"https://user:secret@example.test/help",
+		"not a url",
+	} {
+		var human strings.Builder
+		err := NewAPI("server error", WithServerDiag(ServerDiagnostics{
+			FriendlyHint: "保留 Trace ID 后排查",
+			ActionURL:    actionURL,
+		}))
+		if printErr := PrintHuman(&human, err); printErr != nil {
+			t.Fatal(printErr)
+		}
+		if strings.Contains(human.String(), actionURL) || strings.Contains(human.String(), "处理入口") {
+			t.Fatalf("unsafe action URL %q leaked to human output: %q", actionURL, human.String())
+		}
+		var jsonOutput strings.Builder
+		if printErr := PrintJSON(&jsonOutput, err); printErr != nil {
+			t.Fatal(printErr)
+		}
+		if strings.Contains(jsonOutput.String(), `"action_url"`) {
+			t.Fatalf("unsafe action URL %q leaked to JSON output: %q", actionURL, jsonOutput.String())
+		}
+	}
+}
+
 func TestCrossPlatformCoveragePrintJSONIncludesRPCCodeAndData(t *testing.T) {
 	t.Parallel()
 

internal/event/personal/client_test.go

@@ -128,6 +128,12 @@ func TestClientCreateRuleBasedSubscriptionsUsesDocumentedRuleParam(t *testing.T)
 		{"receive_user/openDingtalkId", EventFromUser, RuleOptions{OpenDingTalkID: "open-user-1"}, map[string]any{"targetUid": "open-user-1", "targetUidType": "openDingtalkId"}},
 		{"receive_o2o_all", EventAllSingleChat, RuleOptions{}, map[string]any{}},
 		{"receive_group_all", EventAllGroupChat, RuleOptions{}, map[string]any{}},
+		{"oa_approval_task_created", EventOAApprovalTaskCreated, RuleOptions{}, map[string]any{}},
+		{"oa_approval_task_finished", EventOAApprovalTaskFinished, RuleOptions{}, map[string]any{}},
+		{"oa_approval_task_redirected", EventOAApprovalTaskRedirected, RuleOptions{}, map[string]any{}},
+		{"oa_approval_instance_started", EventOAApprovalInstanceStarted, RuleOptions{}, map[string]any{}},
+		{"oa_approval_instance_terminated", EventOAApprovalInstanceTerminated, RuleOptions{}, map[string]any{}},
+		{"oa_approval_instance_finished", EventOAApprovalInstanceFinished, RuleOptions{}, map[string]any{}},
 		{"read_group", EventReadGroup, RuleOptions{GroupID: "cid-1"}, map[string]any{"openConversationId": "cid-1"}},
 		{"recall_group", EventRecallGroup, RuleOptions{GroupID: "cid-1"}, map[string]any{"openConversationId": "cid-1"}},
 		{"reaction_group", EventReactionGroup, RuleOptions{GroupID: "cid-1"}, map[string]any{"openConversationId": "cid-1"}},

internal/event/personal/output.go

@@ -121,6 +121,94 @@ type GroupLifecycleEventOutput struct {
 	Payload     map[string]any `json:"payload" description:"群生命周期事件业务数据，字段以服务端实际推送为准" additional_properties:"true"`
 }
 
+type OAApprovalTaskCreatedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	TaskID            string `json:"task_id" description:"审批任务 ID"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批任务状态"`
+	CreateTime        int64  `json:"create_time" description:"审批任务创建时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批任务事件业务时间" format:"timestamp_ms"`
+}
+
+type OAApprovalTaskFinishedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	TaskID            string `json:"task_id" description:"审批任务 ID"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批任务状态"`
+	Result            string `json:"result" description:"审批任务处理结果，值以服务端实际推送为准"`
+	CreateTime        int64  `json:"create_time" description:"审批任务创建时间" format:"timestamp_ms"`
+	FinishTime        int64  `json:"finish_time" description:"审批任务完成时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批任务事件业务时间" format:"timestamp_ms"`
+}
+
+type OAApprovalTaskRedirectedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	TaskID            string `json:"task_id" description:"原审批任务 ID"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"原审批任务状态"`
+	Result            string `json:"result" description:"审批任务转交结果，值以服务端实际推送为准"`
+	CreateTime        int64  `json:"create_time" description:"原审批任务创建时间" format:"timestamp_ms"`
+	FinishTime        int64  `json:"finish_time" description:"原审批任务转交完成时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批任务转交事件业务时间" format:"timestamp_ms"`
+}
+
+type OAApprovalInstanceStartedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批实例状态"`
+	CreateTime        int64  `json:"create_time" description:"审批实例创建时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批实例事件业务时间" format:"timestamp_ms"`
+}
+
+type OAApprovalInstanceTerminatedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批实例状态"`
+	CreateTime        int64  `json:"create_time" description:"审批实例创建时间" format:"timestamp_ms"`
+	FinishTime        int64  `json:"finish_time" description:"审批实例终止时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批实例终止事件业务时间" format:"timestamp_ms"`
+}
+
+type OAApprovalInstanceFinishedOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批实例状态"`
+	Result            string `json:"result" description:"审批实例处理结果，值以服务端实际推送为准"`
+	CreateTime        int64  `json:"create_time" description:"审批实例创建时间" format:"timestamp_ms"`
+	FinishTime        int64  `json:"finish_time" description:"审批实例完成时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批实例事件业务时间" format:"timestamp_ms"`
+}
+
 type GroupMemberEventOutput struct {
 	Type                   string                   `json:"type" description:"事件类型，固定为当前 event_key"`
 	EventID                string                   `json:"event_id" description:"事件 ID，可用于去重"`
@@ -230,6 +318,22 @@ type personalGroupMemberRecord struct {
 	OpenDingTalkID string `json:"openDingTalkId"`
 }
 
+type personalOAApprovalPayload struct {
+	EventTime int64                  `json:"event_time"`
+	Body      personalOAApprovalBody `json:"body"`
+}
+
+type personalOAApprovalBody struct {
+	ProcessInstanceID string `json:"processInstanceId"`
+	ProcessCode       string `json:"processCode"`
+	TaskID            string `json:"taskId"`
+	Title             string `json:"title"`
+	Status            string `json:"status"`
+	Result            string `json:"result"`
+	CreateTime        int64  `json:"createTime"`
+	FinishTime        int64  `json:"finishTime"`
+}
+
 func (b *personalReactionBody) UnmarshalJSON(data []byte) error {
 	// encoding/json otherwise falls back to case-insensitive field matching.
 	// Read this protocol field from a map so only operOpenDingtalkId is accepted.
@@ -343,7 +447,7 @@ func ProjectOutput(ev transport.Event) (any, error) {
 	case isGroupMemberEvent(eventType):
 		return projectGroupMemberEvent(ev, base, data.Payload)
 	case isGroupLifecycleEvent(eventType):
-		payload, err := decodeGroupLifecyclePayload(data.Payload)
+		payload, err := decodeConservativePayload(data.Payload)
 		if err != nil {
 			return ev, fmt.Errorf("decode personal group lifecycle payload: %w", err)
 		}
@@ -354,6 +458,8 @@ func ProjectOutput(ev transport.Event) (any, error) {
 			SubscribeID: base.SubscribeID,
 			Payload:     payload,
 		}, nil
+	case isOAEvent(eventType):
+		return projectOAApprovalEvent(ev, base, data.Payload)
 	default:
 		return ev, fmt.Errorf("unsupported personal event type %q", eventType)
 	}
@@ -370,7 +476,7 @@ func projectMessageEventContext(message personalMessageContext) MessageEventCont
 	}
 }
 
-func decodeGroupLifecyclePayload(raw json.RawMessage) (map[string]any, error) {
+func decodeConservativePayload(raw json.RawMessage) (map[string]any, error) {
 	trimmed := bytes.TrimSpace(raw)
 	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
 		return nil, fmt.Errorf("payload is missing")
@@ -489,6 +595,112 @@ func projectGroupMemberEvent(ev transport.Event, base baseEventOutput, raw json.
 	}, nil
 }
 
+func projectOAApprovalEvent(ev transport.Event, base baseEventOutput, raw json.RawMessage) (any, error) {
+	var payload personalOAApprovalPayload
+	if err := decodeRequiredPayload(raw, &payload); err != nil {
+		return ev, fmt.Errorf("decode personal OA payload: %w", err)
+	}
+	if strings.TrimSpace(payload.Body.ProcessInstanceID) == "" {
+		return ev, fmt.Errorf("decode personal OA payload: processInstanceId is required")
+	}
+	if isOAApprovalTaskEvent(base.Type) && strings.TrimSpace(payload.Body.TaskID) == "" {
+		return ev, fmt.Errorf("decode personal OA payload: taskId is required for %s", base.Type)
+	}
+
+	switch base.Type {
+	case EventOAApprovalTaskCreated:
+		return OAApprovalTaskCreatedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			TaskID:            payload.Body.TaskID,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			CreateTime:        payload.Body.CreateTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	case EventOAApprovalTaskFinished:
+		return OAApprovalTaskFinishedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			TaskID:            payload.Body.TaskID,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			Result:            payload.Body.Result,
+			CreateTime:        payload.Body.CreateTime,
+			FinishTime:        payload.Body.FinishTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	case EventOAApprovalTaskRedirected:
+		return OAApprovalTaskRedirectedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			TaskID:            payload.Body.TaskID,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			Result:            payload.Body.Result,
+			CreateTime:        payload.Body.CreateTime,
+			FinishTime:        payload.Body.FinishTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	case EventOAApprovalInstanceStarted:
+		return OAApprovalInstanceStartedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			CreateTime:        payload.Body.CreateTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	case EventOAApprovalInstanceTerminated:
+		return OAApprovalInstanceTerminatedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			CreateTime:        payload.Body.CreateTime,
+			FinishTime:        payload.Body.FinishTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	case EventOAApprovalInstanceFinished:
+		return OAApprovalInstanceFinishedOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			Result:            payload.Body.Result,
+			CreateTime:        payload.Body.CreateTime,
+			FinishTime:        payload.Body.FinishTime,
+			EventTime:         payload.EventTime,
+		}, nil
+	default:
+		return ev, fmt.Errorf("unsupported personal OA event type %q", base.Type)
+	}
+}
+
 func decodeRequiredPayload(raw json.RawMessage, target any) error {
 	trimmed := bytes.TrimSpace(raw)
 	if len(trimmed) == 0 || bytes.Equal(trimmed, []byte("null")) {
@@ -651,6 +863,18 @@ func outputTypeForEvent(eventKey string) reflect.Type {
 		return reflect.TypeOf(GroupMemberEventOutput{})
 	case isGroupLifecycleEvent(eventKey):
 		return reflect.TypeOf(GroupLifecycleEventOutput{})
+	case eventKey == EventOAApprovalTaskCreated:
+		return reflect.TypeOf(OAApprovalTaskCreatedOutput{})
+	case eventKey == EventOAApprovalTaskFinished:
+		return reflect.TypeOf(OAApprovalTaskFinishedOutput{})
+	case eventKey == EventOAApprovalTaskRedirected:
+		return reflect.TypeOf(OAApprovalTaskRedirectedOutput{})
+	case eventKey == EventOAApprovalInstanceStarted:
+		return reflect.TypeOf(OAApprovalInstanceStartedOutput{})
+	case eventKey == EventOAApprovalInstanceTerminated:
+		return reflect.TypeOf(OAApprovalInstanceTerminatedOutput{})
+	case eventKey == EventOAApprovalInstanceFinished:
+		return reflect.TypeOf(OAApprovalInstanceFinishedOutput{})
 	default:
 		return reflect.TypeOf(baseEventOutput{})
 	}
@@ -677,6 +901,21 @@ func isGroupLifecycleEvent(eventKey string) bool {
 		eventKey == EventGroupDisbanded
 }
 
+func isOAEvent(eventKey string) bool {
+	return eventKey == EventOAApprovalTaskCreated ||
+		eventKey == EventOAApprovalTaskFinished ||
+		eventKey == EventOAApprovalTaskRedirected ||
+		eventKey == EventOAApprovalInstanceStarted ||
+		eventKey == EventOAApprovalInstanceTerminated ||
+		eventKey == EventOAApprovalInstanceFinished
+}
+
+func isOAApprovalTaskEvent(eventKey string) bool {
+	return eventKey == EventOAApprovalTaskCreated ||
+		eventKey == EventOAApprovalTaskFinished ||
+		eventKey == EventOAApprovalTaskRedirected
+}
+
 func schemaType(t reflect.Type) string {
 	switch t.Kind() {
 	case reflect.String:

internal/event/personal/output_test.go

@@ -150,6 +150,59 @@ func personalGroupMemberData(eventKey string) string {
 	}`, eventKey)
 }
 
+func personalOAData(eventKey string) string {
+	body := map[string]any{
+		"processInstanceId": "process-instance-1",
+		"createTime":        int64(1785229100000),
+		"processCode":       "PROC-TEST-1",
+		"title":             "测试审批",
+	}
+	switch eventKey {
+	case EventOAApprovalTaskCreated:
+		body["taskId"] = "approval-task-1"
+		body["status"] = "RUNNING"
+	case EventOAApprovalTaskFinished:
+		body["taskId"] = "approval-task-1"
+		body["status"] = "FINISHED"
+		body["result"] = "agree"
+		body["finishTime"] = int64(1785229199000)
+	case EventOAApprovalTaskRedirected:
+		body["taskId"] = "approval-task-1"
+		body["status"] = "FINISHED"
+		body["result"] = "redirect"
+		body["finishTime"] = int64(1785229199000)
+	case EventOAApprovalInstanceStarted:
+		body["status"] = "RUNNING"
+	case EventOAApprovalInstanceTerminated:
+		body["status"] = "TERMINATED"
+		body["finishTime"] = int64(1785229199000)
+	case EventOAApprovalInstanceFinished:
+		body["status"] = "FINISHED"
+		body["result"] = "agree"
+		body["finishTime"] = int64(1785229199000)
+	}
+	data := map[string]any{
+		"eventId":      "oa-event",
+		"eventKey":     eventKey,
+		"occurredAtMs": int64(1785229200123),
+		"subId":        "oa-data-sub",
+		"payload": map[string]any{
+			"uid":         100001,
+			"CORPID":      "internal-corp",
+			"clientId":    "internal-client",
+			"filterSubId": "internal-filter",
+			"bizid":       "internal-biz",
+			"orgId":       100002,
+			"sourceId":    "open",
+			"body":        body,
+			"event_time":  int64(1785229199000),
+			"futureField": map[string]any{"nested": true},
+		},
+	}
+	encoded, _ := json.Marshal(data)
+	return string(encoded)
+}
+
 func TestCrossPlatformCoverageProjectOutputMessageEvents(t *testing.T) {
 	for _, eventKey := range []string{EventMention, EventSingleChat, EventInChat, EventFromUser, EventAllSingleChat, EventAllGroupChat} {
 		t.Run(eventKey, func(t *testing.T) {
@@ -396,6 +449,170 @@ func TestCrossPlatformCoverageProjectOutputGroupLifecycleEvents(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageProjectOutputOAEvents(t *testing.T) {
+	tests := []struct {
+		eventKey string
+		want     any
+	}{
+		{
+			eventKey: EventOAApprovalTaskCreated,
+			want: OAApprovalTaskCreatedOutput{
+				Type:              EventOAApprovalTaskCreated,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				TaskID:            "approval-task-1",
+				Title:             "测试审批",
+				Status:            "RUNNING",
+				CreateTime:        1785229100000,
+				EventTime:         1785229199000,
+			},
+		},
+		{
+			eventKey: EventOAApprovalTaskFinished,
+			want: OAApprovalTaskFinishedOutput{
+				Type:              EventOAApprovalTaskFinished,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				TaskID:            "approval-task-1",
+				Title:             "测试审批",
+				Status:            "FINISHED",
+				Result:            "agree",
+				CreateTime:        1785229100000,
+				FinishTime:        1785229199000,
+				EventTime:         1785229199000,
+			},
+		},
+		{
+			eventKey: EventOAApprovalTaskRedirected,
+			want: OAApprovalTaskRedirectedOutput{
+				Type:              EventOAApprovalTaskRedirected,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				TaskID:            "approval-task-1",
+				Title:             "测试审批",
+				Status:            "FINISHED",
+				Result:            "redirect",
+				CreateTime:        1785229100000,
+				FinishTime:        1785229199000,
+				EventTime:         1785229199000,
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceStarted,
+			want: OAApprovalInstanceStartedOutput{
+				Type:              EventOAApprovalInstanceStarted,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				Title:             "测试审批",
+				Status:            "RUNNING",
+				CreateTime:        1785229100000,
+				EventTime:         1785229199000,
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceTerminated,
+			want: OAApprovalInstanceTerminatedOutput{
+				Type:              EventOAApprovalInstanceTerminated,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				Title:             "测试审批",
+				Status:            "TERMINATED",
+				CreateTime:        1785229100000,
+				FinishTime:        1785229199000,
+				EventTime:         1785229199000,
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceFinished,
+			want: OAApprovalInstanceFinishedOutput{
+				Type:              EventOAApprovalInstanceFinished,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				Title:             "测试审批",
+				Status:            "FINISHED",
+				Result:            "agree",
+				CreateTime:        1785229100000,
+				FinishTime:        1785229199000,
+				EventTime:         1785229199000,
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.eventKey, func(t *testing.T) {
+			projected, err := ProjectOutput(transport.Event{
+				EventID:       "outer-event",
+				EventBornTime: 11,
+				EventType:     tt.eventKey,
+				SubscribeID:   "outer-sub",
+				Data:          personalOAData(tt.eventKey),
+			})
+			if err != nil {
+				t.Fatalf("ProjectOutput() error = %v", err)
+			}
+			if !reflect.DeepEqual(projected, tt.want) {
+				t.Fatalf("ProjectOutput() = %#v, want %#v", projected, tt.want)
+			}
+			assertNoInternalActionFields(t, projected)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageProjectOutputRejectsUnsupportedOAType(t *testing.T) {
+	ev := transport.Event{EventID: "outer-event", EventType: "user_oa_approval_unknown"}
+	projected, err := projectOAApprovalEvent(
+		ev,
+		baseEventOutput{Type: ev.EventType, EventID: ev.EventID},
+		json.RawMessage(`{"body":{"processInstanceId":"process-instance-1"},"event_time":1}`),
+	)
+	if err == nil || !strings.Contains(err.Error(), `unsupported personal OA event type "user_oa_approval_unknown"`) {
+		t.Fatalf("projectOAApprovalEvent() error = %v", err)
+	}
+	if got, ok := projected.(transport.Event); !ok || !reflect.DeepEqual(got, ev) {
+		t.Fatalf("projectOAApprovalEvent() fallback = %#v, want %#v", projected, ev)
+	}
+}
+
+func TestCrossPlatformCoverageProjectOutputOADecodesDoublyWrappedJSONString(t *testing.T) {
+	once, err := json.Marshal(personalOAData(EventOAApprovalTaskCreated))
+	if err != nil {
+		t.Fatal(err)
+	}
+	twice, err := json.Marshal(string(once))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	projected, err := ProjectOutput(transport.Event{Data: string(twice)})
+	if err != nil {
+		t.Fatalf("ProjectOutput() error = %v", err)
+	}
+	got, ok := projected.(OAApprovalTaskCreatedOutput)
+	if !ok {
+		t.Fatalf("ProjectOutput() type = %T, want OAApprovalTaskCreatedOutput", projected)
+	}
+	if got.Type != EventOAApprovalTaskCreated || got.EventID != "oa-event" || got.SubscribeID != "oa-data-sub" {
+		t.Fatalf("ProjectOutput() = %#v", got)
+	}
+}
+
 func TestCrossPlatformCoverageProjectOutputGroupMemberEvents(t *testing.T) {
 	for _, eventKey := range []string{EventGroupMemberAdded, EventGroupMemberExited} {
 		t.Run(eventKey, func(t *testing.T) {
@@ -549,6 +766,93 @@ func TestCrossPlatformCoverageProjectOutputRejectsInvalidGroupLifecyclePayloads(
 	}
 }
 
+func TestCrossPlatformCoverageProjectOutputRejectsInvalidOAPayloads(t *testing.T) {
+	tests := []struct {
+		name    string
+		payload string
+	}{
+		{name: "missing"},
+		{name: "null", payload: `,"payload":null`},
+		{name: "empty object", payload: `,"payload":{}`},
+		{name: "array", payload: `,"payload":[]`},
+		{name: "string", payload: `,"payload":"invalid"`},
+		{name: "missing body", payload: `,"payload":{"event_time":1}`},
+		{name: "null body", payload: `,"payload":{"body":null,"event_time":1}`},
+		{name: "empty body", payload: `,"payload":{"body":{},"event_time":1}`},
+	}
+	for _, eventKey := range []string{
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
+	} {
+		for _, tt := range tests {
+			t.Run(eventKey+"/"+tt.name, func(t *testing.T) {
+				ev := transport.Event{
+					EventID:   "outer-event",
+					EventType: eventKey,
+					Data:      fmt.Sprintf(`{"eventKey":%q%s}`, eventKey, tt.payload),
+				}
+				projected, err := ProjectOutput(ev)
+				if err == nil {
+					t.Fatal("ProjectOutput() error = nil, want OA payload validation error")
+				}
+				if !strings.Contains(err.Error(), "decode personal OA payload") {
+					t.Fatalf("ProjectOutput() error = %v, want OA payload context", err)
+				}
+				got, ok := projected.(transport.Event)
+				if !ok || !reflect.DeepEqual(got, ev) {
+					t.Fatalf("ProjectOutput() fallback = %#v, want %#v", projected, ev)
+				}
+			})
+		}
+	}
+}
+
+func TestCrossPlatformCoverageProjectOutputRejectsOAWithoutStableIDs(t *testing.T) {
+	tests := []struct {
+		name     string
+		eventKey string
+		body     string
+		want     string
+	}{
+		{
+			name:     "missing process instance",
+			eventKey: EventOAApprovalInstanceStarted,
+			body:     `{"status":"RUNNING"}`,
+			want:     "processInstanceId is required",
+		},
+		{
+			name:     "missing task",
+			eventKey: EventOAApprovalTaskCreated,
+			body:     `{"processInstanceId":"process-instance-1","status":"RUNNING"}`,
+			want:     "taskId is required",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ev := transport.Event{
+				EventID:   "outer-event",
+				EventType: tt.eventKey,
+				Data: fmt.Sprintf(
+					`{"eventKey":%q,"payload":{"body":%s,"event_time":1}}`,
+					tt.eventKey,
+					tt.body,
+				),
+			}
+			projected, err := ProjectOutput(ev)
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("ProjectOutput() error = %v, want %q", err, tt.want)
+			}
+			if got, ok := projected.(transport.Event); !ok || !reflect.DeepEqual(got, ev) {
+				t.Fatalf("ProjectOutput() fallback = %#v, want %#v", projected, ev)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageProjectOutputDecodesWrappedJSONString(t *testing.T) {
 	wrapped, err := json.Marshal(personalMessageData(EventSingleChat))
 	if err != nil {

internal/event/personal/registry.go

@@ -23,22 +23,28 @@ import (
 )
 
 const (
-	EventMention           = "user_im_message_receive_at"
-	EventSingleChat        = "user_im_message_receive_o2o"
-	EventInChat            = "user_im_message_receive_group"
-	EventFromUser          = "user_im_message_receive_user"
-	EventAllSingleChat     = "user_im_message_receive_o2o_all"
-	EventAllGroupChat      = "user_im_message_receive_group_all"
-	EventReadO2O           = "user_im_message_read_o2o"
-	EventReadGroup         = "user_im_message_read_group"
-	EventRecallO2O         = "user_im_message_recall_o2o"
-	EventRecallGroup       = "user_im_message_recall_group"
-	EventReactionO2O       = "user_im_message_reaction_o2o"
-	EventReactionGroup     = "user_im_message_reaction_group"
-	EventGroupUpdated      = "user_im_group_updated"
-	EventGroupMemberAdded  = "user_im_group_member_added"
-	EventGroupMemberExited = "user_im_group_member_exited"
-	EventGroupDisbanded    = "user_im_group_disbanded"
+	EventMention                      = "user_im_message_receive_at"
+	EventSingleChat                   = "user_im_message_receive_o2o"
+	EventInChat                       = "user_im_message_receive_group"
+	EventFromUser                     = "user_im_message_receive_user"
+	EventAllSingleChat                = "user_im_message_receive_o2o_all"
+	EventAllGroupChat                 = "user_im_message_receive_group_all"
+	EventReadO2O                      = "user_im_message_read_o2o"
+	EventReadGroup                    = "user_im_message_read_group"
+	EventRecallO2O                    = "user_im_message_recall_o2o"
+	EventRecallGroup                  = "user_im_message_recall_group"
+	EventReactionO2O                  = "user_im_message_reaction_o2o"
+	EventReactionGroup                = "user_im_message_reaction_group"
+	EventGroupUpdated                 = "user_im_group_updated"
+	EventGroupMemberAdded             = "user_im_group_member_added"
+	EventGroupMemberExited            = "user_im_group_member_exited"
+	EventGroupDisbanded               = "user_im_group_disbanded"
+	EventOAApprovalTaskCreated        = "user_oa_approval_task_created"
+	EventOAApprovalTaskFinished       = "user_oa_approval_task_finished"
+	EventOAApprovalTaskRedirected     = "user_oa_approval_task_redirected"
+	EventOAApprovalInstanceStarted    = "user_oa_approval_instance_started"
+	EventOAApprovalInstanceTerminated = "user_oa_approval_instance_terminated"
+	EventOAApprovalInstanceFinished   = "user_oa_approval_instance_finished"
 )
 
 const (
@@ -273,6 +279,72 @@ var definitions = []Definition{
 		Auth:           map[string]any{"identity": "user"},
 		Public:         true,
 	},
+	{
+		EventKey:       EventOAApprovalTaskCreated,
+		DisplayName:    "审批任务创建",
+		Description:    "审批任务创建，发送给审批人",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
+	{
+		EventKey:       EventOAApprovalTaskFinished,
+		DisplayName:    "审批任务完成",
+		Description:    "审批任务已完成",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
+	{
+		EventKey:       EventOAApprovalTaskRedirected,
+		DisplayName:    "审批人任务转交",
+		Description:    "审批任务已转交",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
+	{
+		EventKey:       EventOAApprovalInstanceStarted,
+		DisplayName:    "发起审批单",
+		Description:    "审批实例已发起",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
+	{
+		EventKey:       EventOAApprovalInstanceTerminated,
+		DisplayName:    "审批单终止",
+		Description:    "审批实例已终止",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
+	{
+		EventKey:       EventOAApprovalInstanceFinished,
+		DisplayName:    "审批单完成",
+		Description:    "审批实例完成，发送给审批单发起人",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
 }
 
 func targetUIDConstraints() *ParameterConstraints {

internal/event/personal/registry_test.go

@@ -46,12 +46,47 @@ func TestCatalogEnabledEvents(t *testing.T) {
 		EventGroupMemberAdded,
 		EventGroupMemberExited,
 		EventGroupDisbanded,
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
 	}
 	if !reflect.DeepEqual(keys, want) {
 		t.Fatalf("keys = %#v, want %#v", keys, want)
 	}
 }
 
+func TestOAEventCatalogDefinitions(t *testing.T) {
+	items := Catalog("oa", true, false)
+	wantKeys := []string{
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
+	}
+	if len(items) != len(wantKeys) {
+		t.Fatalf("Catalog(oa) = %#v, want %d events", items, len(wantKeys))
+	}
+	for i, item := range items {
+		if item.EventKey != wantKeys[i] {
+			t.Fatalf("Catalog(oa)[%d].event_key = %q, want %q", i, item.EventKey, wantKeys[i])
+		}
+		if item.Category != "oa" || item.RuleType != "all" || item.Status != StatusEnabled || !item.Public {
+			t.Fatalf("Catalog(oa)[%d] = %#v, want public enabled oa/all event", i, item)
+		}
+		if len(item.RequiredParams) != 0 || item.Constraints != nil {
+			t.Fatalf("Catalog(oa)[%d] parameters = %#v/%#v, want none", i, item.RequiredParams, item.Constraints)
+		}
+		if item.Auth["identity"] != "user" {
+			t.Fatalf("Catalog(oa)[%d].auth = %#v, want user identity", i, item.Auth)
+		}
+	}
+}
+
 func TestEventFromUserIsPublic(t *testing.T) {
 	if _, ok := Lookup(EventFromUser); !ok {
 		t.Fatalf("Lookup(%q) failed", EventFromUser)
@@ -119,6 +154,12 @@ func TestSchemaDocumentsDefaultToTransportEnvelope(t *testing.T) {
 		EventGroupMemberAdded,
 		EventGroupMemberExited,
 		EventGroupDisbanded,
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
 	} {
 		t.Run(eventKey, func(t *testing.T) {
 			def, ok := Lookup(eventKey)
@@ -433,6 +474,96 @@ func TestGroupLifecycleSchemaDocumentsUseConservativePayload(t *testing.T) {
 	}
 }
 
+func TestOAEventSchemaDocumentsMatchOutputDTO(t *testing.T) {
+	tests := []struct {
+		eventKey   string
+		properties []string
+	}{
+		{
+			eventKey: EventOAApprovalTaskCreated,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "create_time", "event_time",
+			},
+		},
+		{
+			eventKey: EventOAApprovalTaskFinished,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "result", "create_time",
+				"finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: EventOAApprovalTaskRedirected,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "task_id", "title", "status", "result", "create_time",
+				"finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceStarted,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "event_time",
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceTerminated,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "finish_time", "event_time",
+			},
+		},
+		{
+			eventKey: EventOAApprovalInstanceFinished,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "result", "create_time", "finish_time",
+				"event_time",
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.eventKey, func(t *testing.T) {
+			def, ok := Lookup(tt.eventKey)
+			if !ok {
+				t.Fatalf("Lookup(%q) failed", tt.eventKey)
+			}
+			doc := BuildSchemaDocumentForMode(def, true)
+			if doc.JQRootPath != "." {
+				t.Fatalf("jq_root_path = %q, want .", doc.JQRootPath)
+			}
+			props, ok := doc.Schema["properties"].(map[string]any)
+			if !ok || len(props) != len(tt.properties) {
+				t.Fatalf("schema.properties = %#v, want exactly %d fields", doc.Schema["properties"], len(tt.properties))
+			}
+			for _, name := range tt.properties {
+				if _, ok := props[name].(map[string]any); !ok {
+					t.Fatalf("schema.properties.%s = %#v, want object", name, props[name])
+				}
+			}
+			eventType := props["type"].(map[string]any)
+			if !reflect.DeepEqual(eventType["enum"], []string{tt.eventKey}) {
+				t.Fatalf("schema.properties.type.enum = %#v, want %q", eventType["enum"], tt.eventKey)
+			}
+			if _, ok := props["payload"]; ok {
+				t.Fatalf("schema.properties exposed generic payload: %#v", props)
+			}
+			for _, name := range []string{"timestamp", "create_time", "finish_time", "event_time"} {
+				property, exists := props[name].(map[string]any)
+				if !exists {
+					continue
+				}
+				if property["type"] != "integer" || property["format"] != "timestamp_ms" {
+					t.Fatalf("schema.properties.%s = %#v, want timestamp_ms integer", name, property)
+				}
+			}
+		})
+	}
+}
+
 func TestGroupMemberSchemaDocumentsMatchOutputDTO(t *testing.T) {
 	wantProperties := []string{
 		"type", "event_id", "timestamp", "subscribe_id", "conversation_id",
@@ -495,7 +626,16 @@ func TestBuildRuleParamMention(t *testing.T) {
 }
 
 func TestBuildRuleParamAllEvents(t *testing.T) {
-	for _, eventKey := range []string{EventAllSingleChat, EventAllGroupChat} {
+	for _, eventKey := range []string{
+		EventAllSingleChat,
+		EventAllGroupChat,
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
+	} {
 		t.Run(eventKey, func(t *testing.T) {
 			rule, param, err := BuildRuleParam(eventKey, RuleOptions{})
 			if err != nil {
@@ -701,6 +841,12 @@ func TestSupportsMessageFilter(t *testing.T) {
 		EventReadO2O,
 		EventReactionGroup,
 		EventGroupUpdated,
+		EventOAApprovalTaskCreated,
+		EventOAApprovalTaskFinished,
+		EventOAApprovalTaskRedirected,
+		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceTerminated,
+		EventOAApprovalInstanceFinished,
 		"unknown_event",
 	} {
 		if SupportsMessageFilter(eventKey) {

internal/generator/cmd_command_path_fallbacks/main.go

@@ -0,0 +1,122 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+// Command cmd_command_path_fallbacks validates the reviewed recovery-only
+// command path table against the live distribution Cobra tree and writes the
+// deterministic runtime lookup source. It does not add paths to Cobra, Help,
+// Skill, Schema, or the stable CommandRegistry identity surface.
+package main
+
+import (
+	"bytes"
+	"flag"
+	"fmt"
+	"go/format"
+	"os"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/generator/outputguard"
+)
+
+const defaultOutput = "internal/cli/command_path_fallbacks_generated.go"
+
+var (
+	newCommandFallbackRoot       = app.NewSchemaSourceRootCommand
+	reduceCommandFallbackEntries = cli.ReduceCommandPathFallbacks
+	formatCommandFallbackSource  = format.Source
+	writeCommandFallbackFile     = os.WriteFile
+	exitCommandFallbackProcess   = os.Exit
+)
+
+func main() {
+	var rootPath string
+	var outputPath string
+	flag.StringVar(&rootPath, "root", ".", "Repository root used to protect generator inputs")
+	flag.StringVar(&outputPath, "output", defaultOutput, "Output generated command-path fallback table")
+	flag.Parse()
+
+	if err := generateCommandPathFallbacks(rootPath, outputPath); err != nil {
+		fail(err)
+	}
+}
+
+func generateCommandPathFallbacks(rootPath, outputPath string) error {
+	if err := validateOutputIsolation(rootPath, outputPath); err != nil {
+		return err
+	}
+	entries, err := reduceCommandFallbackEntries(newCommandFallbackRoot())
+	if err != nil {
+		return err
+	}
+	source, err := renderCommandPathFallbacks(entries)
+	if err != nil {
+		return err
+	}
+	if err := writeCommandFallbackFile(outputPath, source, 0o644); err != nil {
+		return fmt.Errorf("write generated command path fallbacks: %w", err)
+	}
+	_, _ = fmt.Fprintf(os.Stderr, "generated command path fallbacks: output=%s entries=%d\n", outputPath, len(entries))
+	return nil
+}
+
+func validateOutputIsolation(rootPath, outputPath string) error {
+	inputs := []outputguard.Input{
+		{Name: "reviewed command path fallbacks", Path: "internal/cli/command_path_fallbacks.json"},
+		{Name: "reviewed command path fallback schema", Path: "internal/cli/command_path_fallbacks.schema.json"},
+	}
+	target := outputguard.Target{Name: "--output", Path: outputPath}
+	if err := outputguard.Validate(rootPath, inputs, []outputguard.Target{target}); err != nil {
+		return err
+	}
+	return outputguard.ValidateRepoTargetAllowlist(rootPath, target, defaultOutput)
+}
+
+func renderCommandPathFallbacks(entries []cli.CommandPathFallback) ([]byte, error) {
+	var b bytes.Buffer
+	b.WriteString("// Copyright 2026 Alibaba Group\n")
+	b.WriteString("// Licensed under the Apache License, Version 2.0\n\n")
+	b.WriteString("// Code generated by cmd_command_path_fallbacks; DO NOT EDIT.\n")
+	b.WriteString("// Source: internal/cli/command_path_fallbacks.json validated against the live Cobra tree.\n")
+	b.WriteString("// Regenerate with `make generate-schema` (or `go generate ./internal/cli`).\n\n")
+	b.WriteString("package cli\n\n")
+	b.WriteString("var generatedCommandPathFallbacks = []CommandPathFallback{\n")
+	for _, entry := range entries {
+		b.WriteString("\t{\n")
+		fmt.Fprintf(&b, "\t\tFrom: %q,\n", entry.From)
+		fmt.Fprintf(&b, "\t\tMode: %q,\n", entry.Mode)
+		if entry.To != "" {
+			fmt.Fprintf(&b, "\t\tTo: %q,\n", entry.To)
+		}
+		if len(entry.Candidates) > 0 {
+			fmt.Fprintf(&b, "\t\tCandidates: %s,\n", renderStringSlice(entry.Candidates))
+		}
+		b.WriteString("\t\tReviewed: true,\n")
+		fmt.Fprintf(&b, "\t\tReviewReason: %q,\n", entry.ReviewReason)
+		b.WriteString("\t},\n")
+	}
+	b.WriteString("}\n\n")
+	b.WriteString("func loadGeneratedCommandPathFallbacks() []CommandPathFallback {\n")
+	b.WriteString("\treturn generatedCommandPathFallbacks\n")
+	b.WriteString("}\n")
+
+	formatted, err := formatCommandFallbackSource(b.Bytes())
+	if err != nil {
+		return nil, fmt.Errorf("format generated command path fallbacks: %w", err)
+	}
+	return formatted, nil
+}
+
+func renderStringSlice(values []string) string {
+	quoted := make([]string, len(values))
+	for index, value := range values {
+		quoted[index] = fmt.Sprintf("%q", value)
+	}
+	return "[]string{" + strings.Join(quoted, ", ") + "}"
+}
+
+func fail(err error) {
+	_, _ = fmt.Fprintln(os.Stderr, "error:", err)
+	exitCommandFallbackProcess(1)
+}

internal/generator/cmd_command_path_fallbacks/main_test.go

@@ -0,0 +1,184 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"go/format"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageCommandFallbackGeneratorUsesDistributionOwnedCommandTree(t *testing.T) {
+	got := reflect.ValueOf(newCommandFallbackRoot).Pointer()
+	want := reflect.ValueOf(app.NewSchemaSourceRootCommand).Pointer()
+	if got != want {
+		t.Fatal("command fallback generator must use the distribution-owned Schema source command tree")
+	}
+}
+
+func preserveCommandFallbackGeneratorGlobals(t *testing.T) {
+	t.Helper()
+	oldArgs, oldFlags := os.Args, flag.CommandLine
+	oldRoot := newCommandFallbackRoot
+	oldReduce := reduceCommandFallbackEntries
+	oldFormat := formatCommandFallbackSource
+	oldWrite := writeCommandFallbackFile
+	oldExit := exitCommandFallbackProcess
+	t.Cleanup(func() {
+		os.Args, flag.CommandLine = oldArgs, oldFlags
+		newCommandFallbackRoot = oldRoot
+		reduceCommandFallbackEntries = oldReduce
+		formatCommandFallbackSource = oldFormat
+		writeCommandFallbackFile = oldWrite
+		exitCommandFallbackProcess = oldExit
+	})
+}
+
+func commandFallbackRepositoryRoot(t *testing.T) string {
+	t.Helper()
+	root, err := filepath.Abs(filepath.Join("..", "..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestCrossPlatformCoverageCommandFallbackMainWritesGeneratedFile(t *testing.T) {
+	preserveCommandFallbackGeneratorGlobals(t)
+	output := filepath.Join(t.TempDir(), "command_path_fallbacks_generated.go")
+	flag.CommandLine = flag.NewFlagSet("command-fallback-success", flag.ContinueOnError)
+	os.Args = []string{"cmd_command_path_fallbacks", "-root", commandFallbackRepositoryRoot(t), "-output", output}
+	newCommandFallbackRoot = func(...context.Context) *cobra.Command { return &cobra.Command{Use: "dws"} }
+	reduceCommandFallbackEntries = func(*cobra.Command) ([]cli.CommandPathFallback, error) {
+		return []cli.CommandPathFallback{{
+			From:         "demo +bad",
+			Mode:         cli.CommandPathFallbackRewrite,
+			To:           "demo +good",
+			Reviewed:     true,
+			ReviewReason: "fixture",
+		}}, nil
+	}
+
+	main()
+	data, err := os.ReadFile(output)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	for _, want := range []string{
+		"func loadGeneratedCommandPathFallbacks() []CommandPathFallback",
+		`From:         "demo +bad"`,
+		`To:           "demo +good"`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("generated source missing %q:\n%s", want, text)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageGenerateCommandPathFallbackFailurePaths(t *testing.T) {
+	preserveCommandFallbackGeneratorGlobals(t)
+	root := commandFallbackRepositoryRoot(t)
+	output := filepath.Join(t.TempDir(), "command_path_fallbacks_generated.go")
+	newCommandFallbackRoot = func(...context.Context) *cobra.Command { return &cobra.Command{Use: "dws"} }
+
+	if err := generateCommandPathFallbacks(root, filepath.Join(root, "internal", "cli", "command_path_fallbacks.json")); err == nil {
+		t.Fatal("generator accepted output overlapping reviewed input")
+	}
+	reduceCommandFallbackEntries = func(*cobra.Command) ([]cli.CommandPathFallback, error) {
+		return nil, errors.New("reduce")
+	}
+	if err := generateCommandPathFallbacks(root, output); err == nil || !strings.Contains(err.Error(), "reduce") {
+		t.Fatalf("reduction error = %v", err)
+	}
+	reduceCommandFallbackEntries = func(*cobra.Command) ([]cli.CommandPathFallback, error) { return nil, nil }
+	formatCommandFallbackSource = func([]byte) ([]byte, error) { return nil, errors.New("format") }
+	if err := generateCommandPathFallbacks(root, output); err == nil || !strings.Contains(err.Error(), "format generated") {
+		t.Fatalf("format error = %v", err)
+	}
+	formatCommandFallbackSource = format.Source
+	writeCommandFallbackFile = func(string, []byte, os.FileMode) error { return errors.New("write") }
+	if err := generateCommandPathFallbacks(root, output); err == nil || !strings.Contains(err.Error(), "write generated") {
+		t.Fatalf("write error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateCommandFallbackOutputIsolation(t *testing.T) {
+	root := commandFallbackRepositoryRoot(t)
+	if err := validateOutputIsolation(root, filepath.Join(t.TempDir(), "fallbacks.go")); err != nil {
+		t.Fatalf("temporary output rejected: %v", err)
+	}
+	if err := validateOutputIsolation(root, filepath.Join(root, "internal", "cli", "not_a_delivery_target.go")); err == nil ||
+		!strings.Contains(err.Error(), "not a canonical generated delivery target") {
+		t.Fatalf("non-canonical repository output error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageRenderCommandPathFallbacksShape(t *testing.T) {
+	preserveCommandFallbackGeneratorGlobals(t)
+	entries := []cli.CommandPathFallback{
+		{
+			From:         "demo +bad",
+			Mode:         cli.CommandPathFallbackRewrite,
+			To:           "demo +good",
+			Reviewed:     true,
+			ReviewReason: "rewrite fixture",
+		},
+		{
+			From:         "demo +choose",
+			Mode:         cli.CommandPathFallbackAmbiguous,
+			Candidates:   []string{"demo +one", "demo +two"},
+			Reviewed:     true,
+			ReviewReason: "ambiguous fixture",
+		},
+	}
+	data, err := renderCommandPathFallbacks(entries)
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(data)
+	for _, want := range []string{
+		`Mode:         "rewrite"`,
+		`Candidates:   []string{"demo +one", "demo +two"}`,
+		`ReviewReason: "ambiguous fixture"`,
+	} {
+		if !strings.Contains(text, want) {
+			t.Fatalf("render missing %q:\n%s", want, text)
+		}
+	}
+	if got := renderStringSlice(nil); got != "[]string{}" {
+		t.Fatalf("renderStringSlice(nil) = %q", got)
+	}
+	formatCommandFallbackSource = func([]byte) ([]byte, error) { return nil, errors.New("broken formatter") }
+	if _, err := renderCommandPathFallbacks(entries); err == nil || !strings.Contains(err.Error(), "broken formatter") {
+		t.Fatalf("formatter error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageCommandFallbackMainReportsFailure(t *testing.T) {
+	preserveCommandFallbackGeneratorGlobals(t)
+	flag.CommandLine = flag.NewFlagSet("command-fallback-failure", flag.ContinueOnError)
+	os.Args = []string{
+		"cmd_command_path_fallbacks",
+		"-root", commandFallbackRepositoryRoot(t),
+		"-output", filepath.Join(commandFallbackRepositoryRoot(t), "internal", "cli", "command_path_fallbacks.json"),
+	}
+	exitCommandFallbackProcess = func(code int) { panic(code) }
+	defer func() {
+		if recovered := recover(); recovered != 1 {
+			t.Fatalf("main exit = %#v, want 1", recovered)
+		}
+	}()
+	main()
+}

internal/helpers/aitable.go

@@ -5,14 +5,18 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
+	"math"
 	"os"
 	"strconv"
 	"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/pkg/paging"
 	"github.com/spf13/cobra"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )
 
@@ -122,114 +126,260 @@ func resolveWorkflowDSL(cmd *cobra.Command) (map[string]any, error) {
 	return dsl, nil
 }
 
+func validateWorkflowRunFlags(cmd *cobra.Command, _ []string) error {
+	tableID, _ := cmd.Flags().GetString("table-id")
+	tableID = strings.TrimSpace(tableID)
+	recordIDs, _ := cmd.Flags().GetStringSlice("record-ids")
+	cleaned := make([]string, 0, len(recordIDs))
+	seen := make(map[string]struct{}, len(recordIDs))
+	for _, recordID := range recordIDs {
+		recordID = strings.TrimSpace(recordID)
+		if recordID == "" {
+			continue
+		}
+		if _, ok := seen[recordID]; ok {
+			return apperrors.NewValidation(fmt.Sprintf("--record-ids 不能包含重复值 %q", recordID))
+		}
+		seen[recordID] = struct{}{}
+		cleaned = append(cleaned, recordID)
+	}
+	if cmd.Flags().Changed("table-id") && tableID == "" {
+		return apperrors.NewValidation("--table-id 不能为空")
+	}
+	if cmd.Flags().Changed("record-ids") && len(cleaned) == 0 {
+		return apperrors.NewValidation("--record-ids 必须包含 1 到 5 个非空记录 ID")
+	}
+	if len(cleaned) > 5 {
+		return apperrors.NewValidation(fmt.Sprintf("--record-ids 最多支持 5 个记录 ID，got %d", len(cleaned)))
+	}
+	if (tableID != "") != (len(cleaned) > 0) {
+		return apperrors.NewValidation("--table-id 与 --record-ids 必须同时提供；定时触发工作流则两者都不传")
+	}
+	return nil
+}
+
+func validateWorkflowHistoryFlags(cmd *cobra.Command, _ []string) error {
+	if cmd.Flags().Changed("page") {
+		page, _ := cmd.Flags().GetInt("page")
+		if page < 0 {
+			return apperrors.NewValidation(fmt.Sprintf("--page 必须 >= 0，got %d", page))
+		}
+	}
+	if cmd.Flags().Changed("size") {
+		size, _ := cmd.Flags().GetInt("size")
+		if size < 1 || size > 100 {
+			return apperrors.NewValidation(fmt.Sprintf("--size 必须在 [1, 100] 范围内，got %d", size))
+		}
+	}
+	for _, name := range []string{"after-time", "before-time"} {
+		if !cmd.Flags().Changed(name) {
+			continue
+		}
+		value, _ := cmd.Flags().GetInt(name)
+		if value < 0 {
+			return apperrors.NewValidation(fmt.Sprintf("--%s 必须是 >= 0 的 Unix 毫秒时间戳，got %d", name, value))
+		}
+	}
+	if cmd.Flags().Changed("after-time") && cmd.Flags().Changed("before-time") {
+		afterTime, _ := cmd.Flags().GetInt("after-time")
+		beforeTime, _ := cmd.Flags().GetInt("before-time")
+		if afterTime >= beforeTime {
+			return apperrors.NewValidation(fmt.Sprintf("--after-time 必须小于 --before-time，got %d >= %d", afterTime, beforeTime))
+		}
+	}
+	return nil
+}
+
 // recordQueryFetchAll implements --all auto-pagination for record query.
-//   - pageLimit controls max pages (default 50, 0 = unlimited)
-//   - Mid-loop errors break gracefully, outputting already-fetched data
-//   - Merged result preserves last page's cursor so caller can resume
+// It prints only a complete result. A page limit, empty/invalid response,
+// transport failure, or cursor cycle returns a non-zero structured error whose
+// details retain the incomplete records and retry cursor.
 func recordQueryFetchAll(toolArgs map[string]any, pageLimit int) error {
-	const pageDelayMs = 200
 	const serverID = "aitable"
 
 	ctx := context.Background()
-	var allRecords []any
-	page := 0
-	lastCursor := ""
-
-	for {
-		page++
-
-		if page > 1 {
-			helperSleep(time.Duration(pageDelayMs) * time.Millisecond)
-		}
-
-		fmt.Fprintf(os.Stderr, "[page %d] fetching...\n", page)
-
-		result, err := deps.Caller.CallTool(ctx, serverID, "query_records", toolArgs)
-		if err != nil {
-			if page == 1 {
-				return WrapError(err)
-			}
-			fmt.Fprintf(os.Stderr, "[page %d] error, stopping pagination: %v\n", page, err)
-			break
-		}
-
-		// Extract text content from tool result
-		var text string
-		for _, c := range result.Content {
-			if c.Type == "text" && c.Text != "" {
-				text = c.Text
-				break
-			}
-		}
-		if text == "" {
-			break
-		}
-
-		var resp map[string]any
-		if err := json.Unmarshal([]byte(text), &resp); err != nil {
-			if page == 1 {
-				deps.Out.PrintRaw(text)
-				return nil
-			}
-			break
-		}
-
-		// Extract records from response
-		var pageRecords []any
-		if data, ok := resp["data"].(map[string]any); ok {
-			if recs, ok := data["records"].([]any); ok {
-				pageRecords = recs
-			}
-		} else if recs, ok := resp["records"].([]any); ok {
-			pageRecords = recs
-		}
-		allRecords = append(allRecords, pageRecords...)
-
-		// Extract cursor for next page (MCP returns "nextCursor" or "cursor")
-		cursor := ""
-		if data, ok := resp["data"].(map[string]any); ok {
-			if c, ok := data["nextCursor"].(string); ok && c != "" {
-				cursor = c
-			} else if c, ok := data["cursor"].(string); ok && c != "" {
-				cursor = c
-			}
-		} else if c, ok := resp["nextCursor"].(string); ok && c != "" {
-			cursor = c
-		} else if c, ok := resp["cursor"].(string); ok && c != "" {
-			cursor = c
-		}
+	requestArgs := make(map[string]any, len(toolArgs))
+	for key, value := range toolArgs {
+		requestArgs[key] = value
+	}
+	initialCursor, _ := requestArgs["cursor"].(string)
 
+	effectivePageLimit := pageLimit
+	if pageLimit == 0 {
+		effectivePageLimit = paging.UnlimitedPageLimit
+	}
+	result := paging.FetchAll(ctx, func(ctx context.Context, cursor string) (paging.Page, error) {
 		if cursor == "" {
-			lastCursor = ""
-			break
+			delete(requestArgs, "cursor")
+		} else {
+			requestArgs["cursor"] = cursor
 		}
-
-		// Check page limit (0 = unlimited)
-		if pageLimit > 0 && page >= pageLimit {
-			lastCursor = cursor
-			fmt.Fprintf(os.Stderr, "[pagination] reached page limit (%d), stopping. Use --page-limit 0 to fetch all.\n", pageLimit)
-			break
+		toolResult, err := deps.Caller.CallTool(ctx, serverID, "query_records", requestArgs)
+		if err != nil {
+			return paging.Page{}, err
 		}
+		if toolResult == nil {
+			return paging.Page{}, fmt.Errorf("query_records returned a nil result")
+		}
+		for _, content := range toolResult.Content {
+			if content.Type == "text" && strings.TrimSpace(content.Text) != "" {
+				return parseRecordQueryPage(content.Text)
+			}
+		}
+		return paging.Page{}, fmt.Errorf("query_records returned no non-empty text content")
+	}, paging.Options{
+		PageLimit:      effectivePageLimit,
+		InterPageDelay: paging.DefaultInterPageDelay,
+		InitialCursor:  initialCursor,
+	})
 
-		lastCursor = ""
-		toolArgs["cursor"] = cursor
+	if !result.Complete {
+		return recordQueryIncompleteError(result, pageLimit)
 	}
 
-	fmt.Fprintf(os.Stderr, "[pagination] done: %d pages, %d total records\n", page, len(allRecords))
-
-	// Build merged output — preserve cursor & has_more for resume capability
+	fmt.Fprintf(os.Stderr, "[pagination] complete: %d pages, %d fetched records\n", result.Pages, len(result.Records))
 	mergedData := map[string]any{
-		"records":    allRecords,
-		"totalCount": len(allRecords),
+		"records":      result.Records,
+		"fetchedCount": len(result.Records),
+		"hasMore":      false,
+		"complete":     true,
+		"pages":        result.Pages,
 	}
-	if lastCursor != "" {
-		mergedData["cursor"] = lastCursor
-		mergedData["hasMore"] = true
-	} else {
-		mergedData["hasMore"] = false
+	if result.TotalCount != nil {
+		mergedData["totalCount"] = *result.TotalCount
+	}
+	return deps.Out.PrintJSON(map[string]any{"data": mergedData})
+}
+
+func parseRecordQueryPage(text string) (paging.Page, error) {
+	decoder := json.NewDecoder(strings.NewReader(text))
+	decoder.UseNumber()
+	var response map[string]any
+	if err := decoder.Decode(&response); err != nil {
+		return paging.Page{}, fmt.Errorf("query_records returned invalid JSON: %w", err)
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		if err == nil {
+			return paging.Page{}, fmt.Errorf("query_records returned more than one JSON value")
+		}
+		return paging.Page{}, fmt.Errorf("query_records returned trailing invalid JSON: %w", err)
+	}
+	if response == nil {
+		return paging.Page{}, fmt.Errorf("query_records returned null instead of an object")
 	}
 
-	return deps.Out.PrintJSON(map[string]any{"data": mergedData})
+	payload := response
+	if rawData, exists := response["data"]; exists {
+		data, ok := rawData.(map[string]any)
+		if !ok {
+			return paging.Page{}, fmt.Errorf("query_records data must be an object, got %T", rawData)
+		}
+		payload = data
+	}
+
+	rawRecords, exists := payload["records"]
+	if !exists {
+		return paging.Page{}, fmt.Errorf("query_records response is missing records")
+	}
+	records, ok := rawRecords.([]any)
+	if !ok {
+		return paging.Page{}, fmt.Errorf("query_records records must be an array, got %T", rawRecords)
+	}
+	for index, record := range records {
+		if _, ok := record.(map[string]any); !ok {
+			return paging.Page{}, fmt.Errorf("query_records records[%d] must be an object, got %T", index, record)
+		}
+	}
+
+	nextCursor := firstNonEmptyString(payload, "nextCursor", "cursor")
+	if hasMore, ok := payload["hasMore"].(bool); ok && hasMore && nextCursor == "" {
+		return paging.Page{}, fmt.Errorf("query_records reported hasMore=true without a next cursor")
+	}
+	totalCount, err := parseOptionalNonNegativeInt(payload["totalCount"])
+	if err != nil {
+		return paging.Page{}, fmt.Errorf("query_records totalCount: %w", err)
+	}
+	return paging.Page{Records: records, NextCursor: nextCursor, TotalCount: totalCount}, nil
+}
+
+func firstNonEmptyString(values map[string]any, keys ...string) string {
+	for _, key := range keys {
+		if value, ok := values[key].(string); ok && strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+	return ""
+}
+
+func parseOptionalNonNegativeInt(value any) (*int, error) {
+	if value == nil {
+		return nil, nil
+	}
+	var parsed int64
+	switch typed := value.(type) {
+	case json.Number:
+		integer, err := typed.Int64()
+		if err != nil {
+			return nil, fmt.Errorf("must be an integer, got %q", typed)
+		}
+		parsed = integer
+	case float64:
+		if math.Trunc(typed) != typed {
+			return nil, fmt.Errorf("must be an integer, got %v", typed)
+		}
+		parsed = int64(typed)
+	case int:
+		parsed = int64(typed)
+	case int64:
+		parsed = typed
+	default:
+		return nil, fmt.Errorf("must be a non-negative integer, got %T", value)
+	}
+	if parsed < 0 || int64(int(parsed)) != parsed {
+		return nil, fmt.Errorf("must fit a non-negative int, got %d", parsed)
+	}
+	result := int(parsed)
+	return &result, nil
+}
+
+func recordQueryIncompleteError(result paging.Result, pageLimit int) error {
+	incomplete := map[string]any{
+		"records":      result.Records,
+		"fetchedCount": len(result.Records),
+		"pages":        result.Pages,
+		"attempts":     result.Attempts,
+		"complete":     false,
+		"hasMore":      result.HasMore,
+		"stopReason":   result.StopReason,
+	}
+	if result.LastCursor != "" {
+		incomplete["cursor"] = result.LastCursor
+	}
+	if result.TotalCount != nil {
+		incomplete["totalCount"] = *result.TotalCount
+	}
+
+	hint := "retry the command; the structured error details preserve fetched records and the retry cursor"
+	if result.StopReason == paging.StopPageLimit {
+		hint = "rerun with --page-limit 0 to require a complete result, or resume from details.cursor"
+	}
+	message := fmt.Sprintf("record pagination incomplete after %d successful page(s) and %d fetched record(s)", result.Pages, len(result.Records))
+	return apperrors.NewAPI(message,
+		apperrors.WithOperation("aitable.query_records.all"),
+		apperrors.WithServerKey("aitable"),
+		apperrors.WithOrigin("mcp"),
+		apperrors.WithFailureStage("pagination"),
+		apperrors.WithExecutionStarted(true),
+		apperrors.WithRetryable(true),
+		apperrors.WithReason("pagination_"+string(result.StopReason)),
+		apperrors.WithHint(hint),
+		apperrors.WithDetails(map[string]any{
+			"page_limit":        pageLimit,
+			"incomplete_result": incomplete,
+		}),
+		apperrors.WithCause(result.Err),
+	)
 }
 
 // ─── filters 格式校验 ──────────────────────────────────────────────────────
@@ -953,7 +1103,7 @@ func newAitableCommand() *cobra.Command {
   dws aitable form       [list|delete|update]                                           表单管理
   dws aitable form field [list|update|hide]                                             表单字段管理
   dws aitable form share [get|update|notify]                                            表单分享管理
-  dws aitable workflow   [edit-example|create|update|enable|disable|get|list]           自动化工作流管理
+  dws aitable workflow   [edit-example|create|update|enable|disable|run|history|get|list] 自动化工作流管理
   dws aitable dashboard  [get|create|update|delete|config-example]                      仪表盘管理
   dws aitable chart      [get|create|update|delete|widgets-example]                     图表管理
   dws aitable export     data                                                           数据导出
@@ -4793,7 +4943,7 @@ locked 为 true 表示视图已锁定，false 表示未锁定。`,
 
 	workflowCmd := &cobra.Command{
 		Use:   "workflow",
-		Short: "自动化工作流管理（创建 / 更新 / 启停 / 查看 / 列表）",
+		Short: "自动化工作流管理（创建 / 更新 / 启停 / 执行 / 历史 / 查询）",
 		RunE:  groupRunE,
 	}
 
@@ -5138,6 +5288,116 @@ valid=false 仍表示 DSL 校验或发布未通过，必须读取 issues 修正
 		},
 	})
 
+	workflowRunCmd := NewLeafCommand(LeafSpec{
+		Use:   "run",
+		Short: "执行指定自动化工作流",
+		Long: `立即执行指定 Base 中的自动化工作流。此命令会启动真实的异步执行，并可能产生该工作流配置的消息发送、记录写入等副作用，因此执行前需要确认；CLI 不自动重试。
+
+记录类触发器必须同时提供 --table-id 与 --record-ids；--table-id 必须与触发器绑定的数据表一致，--record-ids 接受 1 到 5 个不重复记录 ID。定时触发器不传这两个参数。
+返回每条记录的提交状态；提交成功项包含 executionId，可用 workflow history 返回项的 instanceId 匹配执行记录。`,
+		Example: `  dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID --table-id TABLE_ID --record-ids RECORD_ID_1,RECORD_ID_2
+  dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID`,
+		Tool: "run_workflow",
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "user_required", Idempotency: "non_idempotent",
+		},
+		Validate: validateWorkflowRunFlags,
+		Flags: []LeafFlag{
+			{Name: "base-id", Usage: "目标 Base ID (必填)", Bind: "baseId", Trim: true, Required: true, Aliases: []string{"base"}},
+			{Name: "workflow-id", Usage: "目标工作流 ID (必填)", Bind: "workflowId", Trim: true, Required: true},
+			{Name: "table-id", Usage: "记录类触发器绑定的 Table ID；定时触发器不传", Bind: "tableId", Trim: true, OmitEmpty: true, RequiredWhen: "record-ids is provided or the workflow uses a record-based trigger"},
+			{Name: "record-ids", Usage: "触发工作流的记录 ID，逗号分隔；记录类触发器必填，1 到 5 个且不可重复", Kind: LeafStringSlice, Bind: "recordIds", RequiredWhen: "table-id is provided or the workflow uses a record-based trigger"},
+		},
+		Constraints: []LeafConstraint{{
+			Kind:        corecmd.Custom,
+			Flags:       []string{"table-id", "record-ids"},
+			Description: "记录类触发器必须同时提供 --table-id 与 --record-ids；定时触发器两者都不传",
+		}},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "aitable",
+				Name:           "workflow_run",
+				CanonicalPath:  "aitable.workflow_run",
+				CLIPath:        "aitable workflow run",
+				PrimaryCLIPath: "aitable workflow run",
+			},
+			Description: "立即执行 AI 表格自动化工作流，并返回异步执行提交结果。",
+			Interface:   aitableMCPInterface("run_workflow"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "立即执行已知 AI 表格自动化工作流，并获取 executionId。",
+				UseWhen:      []string{"用户明确要求立即执行已知工作流，已确认真实 base-id、workflow-id、触发类型及可能产生的业务副作用；记录类触发器还需确认绑定的 table-id 和 1 到 5 个真实 record-id"},
+				AvoidWhen:    []string{"仅开启后续自动触发用 workflow enable；查询工作流定义用 workflow get；查询既有执行结果用 workflow history；返回 executionId 后应以 history 的 instanceId 核对，不要在结果不确定时直接重复执行"},
+				Examples: []string{
+					"dws aitable workflow run --base-id <BASE_ID> --workflow-id <WORKFLOW_ID> --table-id <TABLE_ID> --record-ids <RECORD_ID>",
+					"dws aitable workflow run --base-id <BASE_ID> --workflow-id <WORKFLOW_ID>",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "base-id", Property: "baseId", Required: boolPtr(true), InterfaceType: "string"},
+				{Name: "workflow-id", Property: "workflowId", Required: boolPtr(true), InterfaceType: "string"},
+				{Name: "table-id", Property: "tableId", InterfaceType: "string", RequiredWhen: "record-ids is provided or the workflow uses a record-based trigger"},
+				{Name: "record-ids", Property: "recordIds", InterfaceType: "array", RequiredWhen: "table-id is provided or the workflow uses a record-based trigger"},
+			},
+		},
+	})
+
+	workflowHistoryCmd := NewLeafCommand(LeafSpec{
+		Use:   "history",
+		Short: "查询工作流执行历史",
+		Long: `分页查询指定 AI 表格工作流的执行历史。
+可按状态和 Unix 毫秒时间范围筛选；同时提供 --after-time 与 --before-time 时，前者必须小于后者。--page 从 0 开始，--size 默认 20、最大 100。
+返回 totalCount 与 list；run 返回的 executionId 可与历史项 instanceId 匹配。`,
+		Example: `  dws aitable workflow history --base-id BASE_ID --workflow-id WORKFLOW_ID
+  dws aitable workflow history --base-id BASE_ID --workflow-id WORKFLOW_ID --status failed --after-time 1786000000000 --before-time 1787000000000 --page 0 --size 50`,
+		Tool:     "get_flow_record_list",
+		Safety:   aitableSafetyRead(),
+		Validate: validateWorkflowHistoryFlags,
+		Flags: []LeafFlag{
+			{Name: "base-id", Usage: "目标 Base ID (必填)", Bind: "baseId", Trim: true, Required: true, Aliases: []string{"base"}},
+			{Name: "workflow-id", Usage: "目标工作流 ID (必填)", Bind: "flowId", Trim: true, Required: true},
+			{Name: "status", Usage: "执行状态筛选；不传表示全部", Bind: "status", Trim: true, OmitEmpty: true, Enum: []string{"success", "failed", "running", "break", "untrigger"}},
+			{Name: "after-time", Usage: "开始时间（Unix 毫秒）", Kind: LeafInt, Bind: "afterTime"},
+			{Name: "before-time", Usage: "结束时间（Unix 毫秒）", Kind: LeafInt, Bind: "beforeTime"},
+			{Name: "page", Usage: "页码，从 0 开始", Kind: LeafInt, Default: "0", Bind: "page"},
+			{Name: "size", Usage: "每页条数 [1, 100]", Kind: LeafInt, Default: "20", Bind: "size"},
+		},
+		Constraints: []LeafConstraint{{
+			Kind:        corecmd.Custom,
+			Flags:       []string{"after-time", "before-time"},
+			Description: "同时提供 --after-time 与 --before-time 时，--after-time 必须小于 --before-time",
+		}},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "aitable",
+				Name:           "workflow_history",
+				CanonicalPath:  "aitable.workflow_history",
+				CLIPath:        "aitable workflow history",
+				PrimaryCLIPath: "aitable workflow history",
+			},
+			Description: "分页查询 AI 表格自动化工作流执行历史。",
+			Interface:   aitableMCPInterface("get_flow_record_list"),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按状态、时间和分页条件查询工作流执行历史。",
+				UseWhen:      []string{"需要核对工作流是否执行、执行结果或定位 run 返回的 executionId 时；executionId 与历史项 instanceId 相同，running 为非终态"},
+				AvoidWhen:    []string{"查询工作流定义用 workflow get；列出工作流用 workflow list；立即发起执行用 workflow run"},
+				Examples: []string{
+					"dws aitable workflow history --base-id <BASE_ID> --workflow-id <WORKFLOW_ID>",
+					"dws aitable workflow history --base-id <BASE_ID> --workflow-id <WORKFLOW_ID> --status failed --page 0 --size 50",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "base-id", Property: "baseId", Required: boolPtr(true), InterfaceType: "string"},
+				{Name: "workflow-id", Property: "flowId", Required: boolPtr(true), InterfaceType: "string"},
+				{Name: "status", Property: "status", InterfaceType: "string", Enum: []string{"success", "failed", "running", "break", "untrigger"}},
+				{Name: "after-time", Property: "afterTime", InterfaceType: "number"},
+				{Name: "before-time", Property: "beforeTime", InterfaceType: "number"},
+				{Name: "page", Property: "page", InterfaceType: "number"},
+				{Name: "size", Property: "size", InterfaceType: "number"},
+			},
+		},
+	})
+
 	// ── dashboard: 仪表盘管理 ────────────────────────────────────
 
 	dashboardCmd := &cobra.Command{Use: "dashboard", Short: "仪表盘管理", RunE: groupRunE}
@@ -6966,8 +7226,8 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	recordQueryCmd.Flags().Int("page-size", 0, "--limit 的别名（兼容 LLM 常见误用）")
 	_ = recordQueryCmd.Flags().MarkHidden("page-size")
 	recordQueryCmd.Flags().String("cursor", "", "分页游标，首次查询不传；cursor 为空表示已取完全部记录")
-	recordQueryCmd.Flags().Bool("all", false, "自动翻页获取全部记录。传入时自动循环直到无更多数据或达到 --page-limit 上限")
-	recordQueryCmd.Flags().Int("page-limit", 50, "自动翻页最大页数（仅 --all 时生效）。默认 50 页（5000 条），设为 0 表示无限制")
+	recordQueryCmd.Flags().Bool("all", false, "自动翻页获取完整记录集；达到 --page-limit 且仍有更多页时返回非零结构化错误，不把不完整结果作为成功输出")
+	recordQueryCmd.Flags().Int("page-limit", 50, "自动翻页最大页数（仅 --all 时生效）。默认 50 页（约 5000 条）；设为 0 表示显式不限页数；超限时错误详情保留已取记录和续传 cursor")
 	recordQueryCmd.Flags().String("view-id", "", "视图 ID（record query 不支持按视图过滤，此参数会被忽略并给出提示）")
 	_ = recordQueryCmd.Flags().MarkHidden("view-id")
 	recordCreateCmd.Flags().String("base-id", "", "Base ID，可通过 base list 或 base search 获取 (必填)")
@@ -7339,6 +7599,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	workflowCmd.AddCommand(
 		workflowEditExampleCmd, workflowCreateCmd, workflowUpdateCmd,
 		workflowEnableCmd, workflowDisableCmd,
+		workflowRunCmd, workflowHistoryCmd,
 		workflowGetCmd, workflowListCmd,
 	)
 

internal/helpers/aitable_core_test.go

@@ -292,15 +292,15 @@ func TestCrossPlatformCoverageAitableToolResponseAndPaginationHelpers(t *testing
 		t.Fatalf("update view top-level: %v", err)
 	}
 
-	caller = &aitableTestCaller{responses: []string{`{"data":{"records":[{"id":1}],"nextCursor":"next"}}`}}
+	caller = &aitableTestCaller{responses: []string{`{"data":{"records":[{"id":1}],"totalCount":17}}`}}
 	out = installAitableDeps(t, caller)
-	if err := recordQueryFetchAll(map[string]any{}, 1); err != nil || !strings.Contains(out.String(), "totalCount") {
+	if err := recordQueryFetchAll(map[string]any{}, 1); err != nil || !strings.Contains(out.String(), `"totalCount": 17`) || !strings.Contains(out.String(), `"fetchedCount": 1`) {
 		t.Fatalf("paginated records = %q, %v", out.String(), err)
 	}
 	caller = &aitableTestCaller{responses: []string{"not-json"}}
 	out = installAitableDeps(t, caller)
-	if err := recordQueryFetchAll(map[string]any{}, 1); err != nil || !strings.Contains(out.String(), "not-json") {
-		t.Fatalf("raw first page = %q, %v", out.String(), err)
+	if err := recordQueryFetchAll(map[string]any{}, 1); err == nil || out.Len() != 0 {
+		t.Fatalf("invalid first page must fail without success output = %q, %v", out.String(), err)
 	}
 	caller = &aitableTestCaller{responses: []string{`{"records":[{"id":1}]}`}}
 	installAitableDeps(t, caller)

internal/helpers/aitable_coverage_gap_test.go

@@ -0,0 +1,93 @@
+// Copyright 2026 Alibaba Group
+// SPDX-License-Identifier: Apache-2.0
+
+package helpers
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/paging"
+)
+
+func TestCrossPlatformCoverageAITablePageParsingRemainingEdges(t *testing.T) {
+	for name, raw := range map[string]string{
+		"trailing invalid JSON": `{"records":[]} {`,
+		"data not object":       `{"data":[]}`,
+	} {
+		t.Run(name, func(t *testing.T) {
+			if _, err := parseRecordQueryPage(raw); err == nil {
+				t.Fatalf("parseRecordQueryPage(%q) succeeded", raw)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageAITableOptionalCountNumericTypes(t *testing.T) {
+	cases := []struct {
+		name    string
+		value   any
+		want    int
+		wantErr bool
+	}{
+		{name: "bad number", value: json.Number("1.5"), wantErr: true},
+		{name: "fractional float", value: float64(1.5), wantErr: true},
+		{name: "whole float", value: float64(2), want: 2},
+		{name: "int", value: int(3), want: 3},
+		{name: "int64", value: int64(4), want: 4},
+		{name: "wrong type", value: "5", wantErr: true},
+		{name: "negative", value: int64(-1), wantErr: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, err := parseOptionalNonNegativeInt(tc.value)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("value %#v succeeded: %#v", tc.value, got)
+				}
+				return
+			}
+			if err != nil || got == nil || *got != tc.want {
+				t.Fatalf("value %#v = %#v, %v", tc.value, got, err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageAITableIncompleteResultMetadata(t *testing.T) {
+	total := 9
+	err := recordQueryIncompleteError(paging.Result{
+		Records: []any{map[string]any{"id": "r"}}, Pages: 1, Attempts: 1,
+		HasMore: true, LastCursor: "next", StopReason: paging.StopPageLimit,
+		TotalCount: &total,
+	}, 1)
+	if err == nil || !strings.Contains(err.Error(), "pagination incomplete") {
+		t.Fatalf("incomplete result error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageAITableExplicitUnlimitedPaginationE2E(t *testing.T) {
+	responses := make([]string, paging.DefaultPageLimit+1)
+	for index := range responses {
+		next := ""
+		if index < len(responses)-1 {
+			next = fmt.Sprintf(`,"nextCursor":"cursor-%d"`, index+1)
+		}
+		responses[index] = fmt.Sprintf(`{"records":[{"recordId":"record-%d"}]%s}`, index, next)
+	}
+	caller := &aitableTestCaller{responses: responses}
+	out := installAitableDeps(t, caller)
+	if err := recordQueryFetchAll(map[string]any{}, 0); err != nil {
+		t.Fatalf("explicit unlimited pagination failed: %v", err)
+	}
+	if len(caller.calls) != len(responses) {
+		t.Fatalf("explicit unlimited pagination calls = %d, want %d", len(caller.calls), len(responses))
+	}
+	for _, want := range []string{`"pages": 51`, `"fetchedCount": 51`, `"complete": true`} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("explicit unlimited output missing %s: %s", want, out.String())
+		}
+	}
+}

internal/helpers/aitable_record_query_e2e_test.go

@@ -0,0 +1,192 @@
+// Copyright 2026 Alibaba Group
+// SPDX-License-Identifier: Apache-2.0
+
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"reflect"
+	"strings"
+	"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"
+)
+
+type recordQueryE2EStep struct {
+	result *edition.ToolResult
+	err    error
+}
+
+type recordQueryE2ECaller struct {
+	steps []recordQueryE2EStep
+	calls []aitableTestCall
+}
+
+func (c *recordQueryE2ECaller) CallTool(_ context.Context, server, tool string, args map[string]any) (*edition.ToolResult, error) {
+	cloned := make(map[string]any, len(args))
+	for key, value := range args {
+		cloned[key] = value
+	}
+	c.calls = append(c.calls, aitableTestCall{server: server, tool: tool, args: cloned})
+	index := len(c.calls) - 1
+	if index >= len(c.steps) {
+		return nil, fmt.Errorf("unexpected tool call %d", index+1)
+	}
+	return c.steps[index].result, c.steps[index].err
+}
+
+func (*recordQueryE2ECaller) Format() string { return "json" }
+func (*recordQueryE2ECaller) DryRun() bool   { return false }
+func (*recordQueryE2ECaller) Fields() string { return "" }
+func (*recordQueryE2ECaller) JQ() string     { return "" }
+
+func runRecordQueryCLI(t *testing.T, caller *recordQueryE2ECaller, extraArgs ...string) (string, error) {
+	t.Helper()
+	testseam.Protect(t, &deps)
+	oldArgs := os.Args
+	t.Cleanup(func() { os.Args = oldArgs })
+
+	InitDeps(caller)
+	out := &bytes.Buffer{}
+	deps.Out.w = out
+	deps.Out.errW = out
+	args := []string{"record", "query", "--base-id", "base-e2e", "--table-id", "table-e2e", "--all"}
+	args = append(args, extraArgs...)
+	os.Args = append([]string{"dws", "aitable"}, args...)
+
+	command := newAitableCommand()
+	command.SilenceErrors = true
+	command.SilenceUsage = true
+	command.SetArgs(args)
+	err := command.Execute()
+	return out.String(), err
+}
+
+func recordQueryTextStep(text string) recordQueryE2EStep {
+	return recordQueryE2EStep{result: textToolResult(text)}
+}
+
+func TestCrossPlatformCoverageRecordQueryCLICompleteE2E(t *testing.T) {
+	caller := &recordQueryE2ECaller{steps: []recordQueryE2EStep{
+		recordQueryTextStep(`{"data":{"records":[{"id":"r1"},{"id":"r2"}],"nextCursor":"cursor-2","totalCount":3}}`),
+		recordQueryTextStep(`{"data":{"records":[{"id":"r3"}],"nextCursor":"","totalCount":3}}`),
+	}}
+	out, err := runRecordQueryCLI(t, caller, "--page-limit", "0")
+	if err != nil {
+		t.Fatalf("record query CLI returned error: %v", err)
+	}
+	for _, want := range []string{`"complete": true`, `"fetchedCount": 3`, `"totalCount": 3`, `"id": "r3"`} {
+		if !bytes.Contains([]byte(out), []byte(want)) {
+			t.Fatalf("record query CLI output missing %s:\n%s", want, out)
+		}
+	}
+	if len(caller.calls) != 2 {
+		t.Fatalf("tool calls = %d, want 2", len(caller.calls))
+	}
+	if got := caller.calls[0].args["cursor"]; got != nil {
+		t.Fatalf("first-page cursor = %#v, want absent", got)
+	}
+	if got := caller.calls[1].args["cursor"]; got != "cursor-2" {
+		t.Fatalf("second-page cursor = %#v, want cursor-2", got)
+	}
+}
+
+func TestCrossPlatformCoverageRecordQueryCLIFailsClosedE2E(t *testing.T) {
+	tests := []struct {
+		name  string
+		steps []recordQueryE2EStep
+		args  []string
+	}{
+		{name: "nil result", steps: []recordQueryE2EStep{{result: nil}}},
+		{name: "empty content", steps: []recordQueryE2EStep{{result: &edition.ToolResult{}}}},
+		{name: "empty text", steps: []recordQueryE2EStep{recordQueryTextStep("")}},
+		{name: "invalid json", steps: []recordQueryE2EStep{recordQueryTextStep("{")}},
+		{name: "null payload", steps: []recordQueryE2EStep{recordQueryTextStep("null")}},
+		{name: "missing records", steps: []recordQueryE2EStep{recordQueryTextStep(`{"data":{"nextCursor":"c"}}`)}},
+		{name: "records wrong type", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":{}}`)}},
+		{name: "records null", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":null}`)}},
+		{name: "record item wrong type", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":["bad"]}`)}},
+		{name: "trailing json", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":[]} {}`)}},
+		{name: "has more without cursor", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":[],"hasMore":true}`)}},
+		{name: "invalid total", steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":[],"totalCount":"many"}`)}},
+		{name: "first transport error", steps: []recordQueryE2EStep{{err: errors.New("offline")}}},
+		{
+			name: "second page error",
+			steps: []recordQueryE2EStep{
+				recordQueryTextStep(`{"records":[{"id":"kept"}],"nextCursor":"retry-me"}`),
+				{err: errors.New("upstream reset")},
+			},
+			args: []string{"--page-limit", "0"},
+		},
+		{
+			name:  "page limit",
+			steps: []recordQueryE2EStep{recordQueryTextStep(`{"records":[{"id":"kept"}],"nextCursor":"resume-me"}`)},
+			args:  []string{"--page-limit", "1"},
+		},
+		{
+			name: "cursor cycle",
+			steps: []recordQueryE2EStep{
+				recordQueryTextStep(`{"records":[{"id":"r1"}],"nextCursor":"same"}`),
+				recordQueryTextStep(`{"records":[{"id":"r2"}],"nextCursor":"same"}`),
+			},
+			args: []string{"--page-limit", "0"},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &recordQueryE2ECaller{steps: test.steps}
+			out, err := runRecordQueryCLI(t, caller, test.args...)
+			if err == nil {
+				t.Fatalf("CLI treated %s as success; output=%s", test.name, out)
+			}
+			if out != "" {
+				t.Fatalf("CLI emitted success output for %s: %q", test.name, out)
+			}
+			var typed *apperrors.Error
+			if !errors.As(err, &typed) {
+				t.Fatalf("error type = %T, want *errors.Error", err)
+			}
+			if typed.Reason == "" || typed.Details["incomplete_result"] == nil {
+				t.Fatalf("error lacks recovery metadata: %#v", typed)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRecordQueryCLIInitialCursorE2E(t *testing.T) {
+	caller := &recordQueryE2ECaller{steps: []recordQueryE2EStep{
+		recordQueryTextStep(`{"records":[]}`),
+	}}
+	if out, err := runRecordQueryCLI(t, caller, "--cursor", "resume-from-here", "--page-limit", "0"); err != nil || out == "" {
+		t.Fatalf("resume query = %q, %v", out, err)
+	}
+	want := map[string]any{"baseId": "base-e2e", "tableId": "table-e2e", "cursor": "resume-from-here"}
+	if !reflect.DeepEqual(caller.calls[0].args, want) {
+		t.Fatalf("resume args = %#v, want %#v", caller.calls[0].args, want)
+	}
+}
+
+func TestCrossPlatformCoverageRecordQueryCLIPageLimitHelpE2E(t *testing.T) {
+	command := newAitableCommand()
+	command.SilenceErrors = true
+	command.SilenceUsage = true
+	out := &bytes.Buffer{}
+	command.SetOut(out)
+	command.SetErr(out)
+	command.SetArgs([]string{"record", "query", "--help"})
+	if err := command.Execute(); err != nil {
+		t.Fatalf("record query help failed: %v", err)
+	}
+	for _, want := range []string{"返回非零结构化错误", "不完整结果", "错误详情保留已取记录和续传 cursor"} {
+		if !strings.Contains(out.String(), want) {
+			t.Fatalf("record query help missing %q:\n%s", want, out.String())
+		}
+	}
+}

internal/helpers/aitable_workflow_write_test.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
@@ -40,26 +41,23 @@ func (*aitableWorkflowCaller) JQ() string     { return "" }
 
 func runAitableWorkflowCommand(t *testing.T, stdin io.Reader, args ...string) (*aitableWorkflowCaller, error) {
 	t.Helper()
-	previousDeps := deps
-	previousArgs := os.Args
-	t.Cleanup(func() {
-		deps = previousDeps
-		os.Args = previousArgs
-	})
+	testseam.Protect(t, &os.Args)
 
 	caller := &aitableWorkflowCaller{}
-	InitDeps(caller)
+	InitDepsForTest(t, caller)
 	deps.Out.w = io.Discard
 	os.Args = append([]string{"dws", "aitable", "workflow"}, args...)
 
 	cmd := newAitableCommand()
 	cmd.PersistentFlags().String("format", "json", "output format")
+	cmd.PersistentFlags().Bool("yes", false, "skip confirmation")
 	cmd.SilenceErrors = true
 	cmd.SilenceUsage = true
 	cmd.SetArgs(append([]string{"workflow"}, args...))
-	if stdin != nil {
-		cmd.SetIn(stdin)
+	if stdin == nil {
+		stdin = strings.NewReader("")
 	}
+	cmd.SetIn(stdin)
 	return caller, cmd.Execute()
 }
 
@@ -197,3 +195,158 @@ func TestAitableWorkflowWriteRejectsInvalidInput(t *testing.T) {
 		})
 	}
 }
+
+func TestCrossPlatformCoverageAitableWorkflowRunMapsRecordTrigger(t *testing.T) {
+	caller, err := runAitableWorkflowCommand(t, nil,
+		"run",
+		"--base-id", "base-run",
+		"--workflow-id", "workflow-run",
+		"--table-id", "table-run",
+		"--record-ids", "record-1,record-2",
+		"--yes",
+	)
+	if err != nil {
+		t.Fatalf("workflow run returned error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("tool call count = %d, want 1", len(caller.calls))
+	}
+	call := caller.calls[0]
+	if call.productID != "aitable" || call.toolName != "run_workflow" {
+		t.Fatalf("tool call = %s/%s, want aitable/run_workflow", call.productID, call.toolName)
+	}
+	wantArgs := map[string]any{
+		"baseId":     "base-run",
+		"workflowId": "workflow-run",
+		"tableId":    "table-run",
+		"recordIds":  []string{"record-1", "record-2"},
+	}
+	if !reflect.DeepEqual(call.args, wantArgs) {
+		t.Fatalf("tool args = %#v, want %#v", call.args, wantArgs)
+	}
+}
+
+func TestCrossPlatformCoverageAitableWorkflowRunMapsScheduledTrigger(t *testing.T) {
+	caller, err := runAitableWorkflowCommand(t, nil,
+		"run", "--base", "base-scheduled", "--workflow-id", "workflow-scheduled", "--yes",
+	)
+	if err != nil {
+		t.Fatalf("scheduled workflow run returned error: %v", err)
+	}
+	wantArgs := map[string]any{
+		"baseId":     "base-scheduled",
+		"workflowId": "workflow-scheduled",
+	}
+	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0].args, wantArgs) {
+		t.Fatalf("calls = %#v, want one scheduled invocation %#v", caller.calls, wantArgs)
+	}
+}
+
+func TestCrossPlatformCoverageAitableWorkflowRunRejectsUnsafeOrInvalidInput(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "confirmation", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow"}, want: "用户确认"},
+		{name: "blank table", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--table-id", "   ", "--yes"}, want: "--table-id 不能为空"},
+		{name: "blank records", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--record-ids", " , ", "--yes"}, want: "--record-ids 必须包含"},
+		{name: "table without records", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--table-id", "table", "--yes"}, want: "必须同时提供"},
+		{name: "records without table", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--record-ids", "record", "--yes"}, want: "必须同时提供"},
+		{name: "duplicate records", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--table-id", "table", "--record-ids", "record,record", "--yes"}, want: "不能包含重复值"},
+		{name: "too many records", args: []string{"run", "--base-id", "base", "--workflow-id", "workflow", "--table-id", "table", "--record-ids", "r1,r2,r3,r4,r5,r6", "--yes"}, want: "最多支持 5 个"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller, err := runAitableWorkflowCommand(t, nil, tc.args...)
+			if err == nil || !strings.Contains(strings.ToLower(err.Error()), strings.ToLower(tc.want)) {
+				t.Fatalf("error = %v, want substring %q", err, tc.want)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("invalid run reached MCP: %#v", caller.calls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageAitableWorkflowHistoryMapsFilters(t *testing.T) {
+	caller, err := runAitableWorkflowCommand(t, nil,
+		"history",
+		"--base-id", "base-history",
+		"--workflow-id", "workflow-history",
+		"--status", "failed",
+		"--after-time", "1786000000000",
+		"--before-time", "1787000000000",
+		"--page", "2",
+		"--size", "50",
+	)
+	if err != nil {
+		t.Fatalf("workflow history returned error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("tool call count = %d, want 1", len(caller.calls))
+	}
+	call := caller.calls[0]
+	if call.productID != "aitable" || call.toolName != "get_flow_record_list" {
+		t.Fatalf("tool call = %s/%s, want aitable/get_flow_record_list", call.productID, call.toolName)
+	}
+	wantArgs := map[string]any{
+		"baseId":     "base-history",
+		"flowId":     "workflow-history",
+		"status":     "failed",
+		"afterTime":  1786000000000,
+		"beforeTime": 1787000000000,
+		"page":       2,
+		"size":       50,
+	}
+	if !reflect.DeepEqual(call.args, wantArgs) {
+		t.Fatalf("tool args = %#v, want %#v", call.args, wantArgs)
+	}
+}
+
+func TestCrossPlatformCoverageAitableWorkflowHistoryMapsSingleTimeFilter(t *testing.T) {
+	caller, err := runAitableWorkflowCommand(t, nil,
+		"history",
+		"--base-id", "base-history",
+		"--workflow-id", "workflow-history",
+		"--after-time", "1786000000000",
+	)
+	if err != nil {
+		t.Fatalf("workflow history returned error: %v", err)
+	}
+	wantArgs := map[string]any{
+		"baseId":    "base-history",
+		"flowId":    "workflow-history",
+		"afterTime": 1786000000000,
+		"size":      20,
+	}
+	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0].args, wantArgs) {
+		t.Fatalf("calls = %#v, want one history invocation %#v", caller.calls, wantArgs)
+	}
+}
+
+func TestCrossPlatformCoverageAitableWorkflowHistoryRejectsInvalidFilters(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "status", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--status", "unknown"}, want: "允许值"},
+		{name: "negative page", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--page", "-1"}, want: "--page 必须 >= 0"},
+		{name: "zero size", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--size", "0"}, want: "--size 必须在"},
+		{name: "large size", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--size", "101"}, want: "--size 必须在"},
+		{name: "negative after", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--after-time", "-1"}, want: "Unix 毫秒时间戳"},
+		{name: "reversed range", args: []string{"history", "--base-id", "base", "--workflow-id", "workflow", "--after-time", "200", "--before-time", "100"}, want: "必须小于"},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller, err := runAitableWorkflowCommand(t, nil, tc.args...)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want substring %q", err, tc.want)
+			}
+			if len(caller.calls) != 0 {
+				t.Fatalf("invalid history query reached MCP: %#v", caller.calls)
+			}
+		})
+	}
+}

internal/helpers/chat/deps.go

@@ -0,0 +1,144 @@
+// 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 chat
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+type LeafContract = corecmd.ContractDecl
+
+type LeafSpec struct {
+	Safety   contract.SafetySpec
+	Contract LeafContract
+}
+
+type Deps struct {
+	GroupRunE            func(*cobra.Command, []string) error
+	CallMCPToolOnServer  func(string, string, map[string]any) error
+	DeclareLeafMetadata  func(*cobra.Command, LeafSpec) *cobra.Command
+	ValidateRequiredFlag func(*cobra.Command, ...string) error
+}
+
+var deps = Deps{
+	GroupRunE: func(cmd *cobra.Command, args []string) error {
+		return cmd.Help()
+	},
+	CallMCPToolOnServer: func(serverID, toolName string, args map[string]any) error {
+		return fmt.Errorf("im helpers dependency CallMCPToolOnServer is not initialized")
+	},
+	DeclareLeafMetadata: func(cmd *cobra.Command, spec LeafSpec) *cobra.Command {
+		return cmd
+	},
+	ValidateRequiredFlag: validateRequiredFlagsLocal,
+}
+
+func SetDeps(next Deps) {
+	if next.GroupRunE != nil {
+		deps.GroupRunE = next.GroupRunE
+	}
+	if next.CallMCPToolOnServer != nil {
+		deps.CallMCPToolOnServer = next.CallMCPToolOnServer
+	}
+	if next.DeclareLeafMetadata != nil {
+		deps.DeclareLeafMetadata = next.DeclareLeafMetadata
+	}
+	if next.ValidateRequiredFlag != nil {
+		deps.ValidateRequiredFlag = next.ValidateRequiredFlag
+	}
+}
+
+func NewChatToolbarCommand() *cobra.Command {
+	return newChatToolbarCommand()
+}
+
+func groupRunE(cmd *cobra.Command, args []string) error {
+	return deps.GroupRunE(cmd, args)
+}
+
+func callMCPToolOnServer(serverID, toolName string, args map[string]any) error {
+	return deps.CallMCPToolOnServer(serverID, toolName, args)
+}
+
+func DeclareLeafMetadata(cmd *cobra.Command, spec LeafSpec) *cobra.Command {
+	return deps.DeclareLeafMetadata(cmd, spec)
+}
+
+func validateRequiredFlags(cmd *cobra.Command, names ...string) error {
+	return deps.ValidateRequiredFlag(cmd, names...)
+}
+
+func mustGetFlag(cmd *cobra.Command, name string) string {
+	val, _ := cmd.Flags().GetString(name)
+	if val == "" {
+		val, _ = cmd.InheritedFlags().GetString(name)
+	}
+	return strings.TrimSpace(val)
+}
+
+func parseCSVInt64(raw string) ([]int64, error) {
+	parts := strings.Split(raw, ",")
+	result := make([]int64, 0, len(parts))
+	for _, p := range parts {
+		v := strings.TrimSpace(p)
+		if v == "" {
+			continue
+		}
+		n, err := strconv.ParseInt(v, 10, 64)
+		if err != nil {
+			return nil, fmt.Errorf("invalid integer %q", v)
+		}
+		result = append(result, n)
+	}
+	if len(result) == 0 {
+		return nil, fmt.Errorf("at least one ID is required")
+	}
+	return result, nil
+}
+
+func validateRequiredFlagsLocal(cmd *cobra.Command, names ...string) error {
+	for _, name := range names {
+		if strings.TrimSpace(mustGetFlag(cmd, name)) == "" {
+			return apperrors.NewValidation(
+				fmt.Sprintf("flag --%s is required", name),
+				apperrors.WithReason("missing_required_flag"),
+				apperrors.WithHint(fmt.Sprintf("使用 --%s 指定必填参数", name)),
+			)
+		}
+	}
+	return nil
+}
+
+func commandBoolFlag(cmd *cobra.Command, name string) bool {
+	if cmd == nil {
+		return false
+	}
+	value, _ := cmd.Flags().GetBool(name)
+	if !value {
+		value, _ = cmd.InheritedFlags().GetBool(name)
+	}
+	return value
+}
+
+func boolPtr(v bool) *bool {
+	return &v
+}

internal/helpers/chat/toolbar.go

@@ -0,0 +1,38 @@
+// 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 chat
+
+import "github.com/spf13/cobra"
+
+func newChatToolbarCommand() *cobra.Command {
+	toolbarCmd := &cobra.Command{
+		Use:   "toolbar",
+		Short: "快捷栏管理",
+		Long:  "管理会话快捷栏入口：查询、添加、隐藏、排序及自定义入口 CRUD。",
+		RunE:  groupRunE,
+	}
+	toolbarCmd.DisableAutoGenTag = true
+
+	toolbarCmd.AddCommand(
+		newToolbarListCommand(),
+		newToolbarAddCommand(),
+		newToolbarHideCommand(),
+		newToolbarSortCommand(),
+		newToolbarCreateCustomCommand(),
+		newToolbarRemoveCustomCommand(),
+		newToolbarUpdateCustomCommand(),
+	)
+
+	return toolbarCmd
+}

internal/helpers/chat/toolbar_add.go

@@ -0,0 +1,92 @@
+// 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 chat
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func newToolbarAddCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "add",
+		Short: "将入口添加到快捷栏可见区",
+		Long:  "将一个或多个快捷入口从隐藏区移至可见区。入口 ID 使用逗号分隔。",
+		Example: `  dws chat toolbar add --conversation-id <cid> --shortcut-ids 101,102
+  # 查询入口 ID: dws chat toolbar list --conversation-id <cid>`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "shortcut-ids"); err != nil {
+				return err
+			}
+			ids, err := parseCSVInt64(mustGetFlag(cmd, "shortcut-ids"))
+			if err != nil {
+				return fmt.Errorf("--shortcut-ids: %w", err)
+			}
+			err = callMCPToolOnServer("im", "add_shortcut_to_bar", map[string]any{
+				"openConversationId": cid,
+				"shortcutIds":        ids,
+			})
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().String("shortcut-ids", "", "入口 ID 列表（逗号分隔）")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("shortcut-ids")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "add_shortcut_to_bar",
+				CanonicalPath:  "chat.add_shortcut_to_bar",
+				CLIPath:        "chat toolbar add",
+				PrimaryCLIPath: "chat toolbar add",
+			},
+			Description: "将快捷入口添加到会话快捷栏可见区",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "add_shortcut_to_bar"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "将快捷入口添加到会话快捷栏可见区",
+				UseWhen:      []string{"需要将隐藏的快捷入口重新显示在快捷栏中"},
+				AvoidWhen:    []string{"创建新的自定义入口应使用 chat toolbar create-custom"},
+				Examples:     []string{"dws chat toolbar add --conversation-id <cid> --shortcut-ids 101,102"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "shortcut-ids", Property: "shortcutIds", Required: boolPtr(true)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_create_custom.go

@@ -0,0 +1,143 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package chat
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func newToolbarCreateCustomCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "create-custom",
+		Short: "创建自定义快捷栏入口",
+		Long: `创建一个新的自定义快捷栏入口。
+
+必填参数：
+  --conversation-id  会话 openConversationId
+  --title            入口标题
+  --url              入口跳转链接
+  --icon-url         入口图标 URL
+  --pc-url           PC 端跳转链接（可与 --url 相同）
+
+可选参数：
+  --extension        扩展信息，格式 key=value，可重复使用
+  --desc             入口描述（为空时使用 --title）
+  --tag              入口标签
+  --sort-index       排序权重`,
+		Example: `  dws chat toolbar create-custom --conversation-id <cid> --title "周报" --url "https://example.com" --icon-url "https://example.com/icon.png" --pc-url "https://example.com"
+  dws chat toolbar create-custom --conversation-id <cid> --title "工具" --url "https://example.com" --icon-url "https://example.com/icon.png" --pc-url "https://example.com" --extension color=blue --desc "常用工具"`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "title", "url", "icon-url", "pc-url"); err != nil {
+				return err
+			}
+
+			toolArgs := map[string]any{
+				"openConversationId": cid,
+				"name":               toolbarI18nJSONString(mustGetFlag(cmd, "title")),
+				"url":                mustGetFlag(cmd, "url"),
+				"icons":              toolbarIconsJSONString(mustGetFlag(cmd, "icon-url")),
+				"pcUrl":              mustGetFlag(cmd, "pc-url"),
+			}
+
+			descValue := mustGetFlag(cmd, "desc")
+			if descValue == "" {
+				descValue = mustGetFlag(cmd, "title")
+			}
+			toolArgs["desc"] = toolbarI18nJSONString(descValue)
+			if tag, _ := cmd.Flags().GetString("tag"); tag != "" {
+				toolArgs["tag"] = tag
+			}
+			if cmd.Flags().Changed("sort-index") {
+				sortIndex, _ := cmd.Flags().GetInt("sort-index")
+				toolArgs["sortIndex"] = sortIndex
+			}
+
+			ext, err := parseExtension(cmd)
+			if err != nil {
+				return err
+			}
+			if ext != nil {
+				toolArgs["extension"] = ext
+			}
+
+			err = callMCPToolOnServer("im", "create_custom_shortcut", toolArgs)
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().String("title", "", "入口标题")
+	cmd.Flags().String("url", "", "入口跳转链接")
+	cmd.Flags().String("icon-url", "", "入口图标 URL")
+	cmd.Flags().String("pc-url", "", "PC 端跳转链接")
+	cmd.Flags().StringArray("extension", nil, "扩展信息，格式 key=value，可重复使用")
+	cmd.Flags().String("desc", "", "入口描述（为空时使用 --title）")
+	cmd.Flags().String("tag", "", "入口标签")
+	cmd.Flags().Int("sort-index", 0, "排序权重")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("title")
+	_ = cmd.MarkFlagRequired("url")
+	_ = cmd.MarkFlagRequired("icon-url")
+	_ = cmd.MarkFlagRequired("pc-url")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "create_custom_shortcut",
+				CanonicalPath:  "chat.create_custom_shortcut",
+				CLIPath:        "chat toolbar create-custom",
+				PrimaryCLIPath: "chat toolbar create-custom",
+			},
+			Description: "创建自定义快捷栏入口",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "create_custom_shortcut"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "创建自定义快捷栏入口",
+				UseWhen:      []string{"需要在快捷栏中新增一个自定义入口（含标题、链接、图标等）"},
+				AvoidWhen:    []string{"移动已有入口使用 chat toolbar add / hide；更新已有自定义入口使用 chat toolbar update-custom"},
+				Examples:     []string{"dws chat toolbar create-custom --conversation-id <cid> --title \"周报\" --url \"https://example.com\" --icon-url \"https://example.com/icon.png\" --pc-url \"https://example.com\""},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "title", Property: "name", Required: boolPtr(true)},
+				{Name: "url", Property: "url", Required: boolPtr(true)},
+				{Name: "icon-url", Property: "icons", Required: boolPtr(true)},
+				{Name: "pc-url", Property: "pcUrl", Required: boolPtr(true)},
+				{Name: "extension", Property: "extension", Required: boolPtr(false)},
+				{Name: "desc", Property: "desc", Required: boolPtr(false)},
+				{Name: "tag", Property: "tag", Required: boolPtr(false)},
+				{Name: "sort-index", Property: "sortIndex", Required: boolPtr(false)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_custom_payload.go

@@ -0,0 +1,26 @@
+// 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 chat
+
+import "encoding/json"
+
+func toolbarI18nJSONString(value string) string {
+	payload, _ := json.Marshal(map[string]string{"zh_CN": value})
+	return string(payload)
+}
+
+func toolbarIconsJSONString(iconMobile string) string {
+	payload, _ := json.Marshal(map[string]string{"iconMobile": iconMobile})
+	return string(payload)
+}

internal/helpers/chat/toolbar_helpers.go

@@ -0,0 +1,93 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package chat
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+func hasIntersection(a, b []int64) bool {
+	if len(a) == 0 || len(b) == 0 {
+		return false
+	}
+	seen := make(map[int64]struct{}, len(a))
+	for _, v := range a {
+		seen[v] = struct{}{}
+	}
+	for _, v := range b {
+		if _, ok := seen[v]; ok {
+			return true
+		}
+	}
+	return false
+}
+
+func isSystemBusy(err error) bool {
+	if err == nil {
+		return false
+	}
+	return strings.Contains(err.Error(), "SYSTEM_BUSY")
+}
+
+func parseExtension(cmd *cobra.Command) (map[string]string, error) {
+	raw, _ := cmd.Flags().GetStringArray("extension")
+	if len(raw) == 0 {
+		return nil, nil
+	}
+	result := make(map[string]string, len(raw))
+	for _, pair := range raw {
+		idx := strings.Index(pair, "=")
+		if idx <= 0 {
+			return nil, fmt.Errorf("--extension 格式错误，期望 key=value，实际 %q", pair)
+		}
+		key := strings.TrimSpace(pair[:idx])
+		value := strings.TrimSpace(pair[idx+1:])
+		if key == "" {
+			return nil, fmt.Errorf("--extension key 不能为空: %q", pair)
+		}
+		if _, exists := result[key]; exists {
+			return nil, fmt.Errorf("--extension 重复 key %q，每个 key 只能指定一次", key)
+		}
+		result[key] = value
+	}
+	return result, nil
+}
+
+func toolbarConversationID(cmd *cobra.Command) (string, error) {
+	cid, _ := cmd.Flags().GetString("conversation-id")
+	cid = strings.TrimSpace(cid)
+	if cid == "" {
+		return "", apperrors.NewValidation(
+			"flag --conversation-id is required",
+			apperrors.WithReason("missing_required_flag"),
+			apperrors.WithHint("使用 --conversation-id 指定会话 openConversationId"),
+			apperrors.WithActions("通过 dws chat search 或 dws chat group list 获取会话 ID"),
+		)
+	}
+	return cid, nil
+}
+
+func toolbarNewSystemBusyError() error {
+	return apperrors.NewValidation(
+		"服务端繁忙（SYSTEM_BUSY），请稍后重试",
+		apperrors.WithReason("system_busy"),
+		apperrors.WithHint("服务端当前负载较高，建议等待几秒后重试"),
+		apperrors.WithActions("等待后使用相同参数重试"),
+	)
+}

internal/helpers/chat/toolbar_helpers_test.go

@@ -0,0 +1,733 @@
+// 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 chat
+
+import (
+	"context"
+	"errors"
+	"io"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+type toolbarCall struct {
+	product string
+	tool    string
+	args    map[string]any
+}
+
+type toolbarTestCaller struct {
+	product string
+	tool    string
+	args    map[string]any
+	err     error
+	calls   []toolbarCall
+}
+
+func (c *toolbarTestCaller) CallTool(_ context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	c.calls = append(c.calls, toolbarCall{product: productID, tool: toolName, args: args})
+	c.product = productID
+	c.tool = toolName
+	c.args = args
+	if c.err != nil {
+		return nil, c.err
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: "{}"}}}, nil
+}
+
+func (c *toolbarTestCaller) Format() string { return "json" }
+func (c *toolbarTestCaller) DryRun() bool   { return false }
+func (c *toolbarTestCaller) Fields() string { return "" }
+func (c *toolbarTestCaller) JQ() string     { return "" }
+
+func executeToolbarCommand(t *testing.T, cmd *cobra.Command, caller *toolbarTestCaller, args ...string) error {
+	t.Helper()
+	initToolbarDepsForTest(t, caller)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs(args)
+	return cmd.Execute()
+}
+
+func initToolbarDepsForTest(t *testing.T, caller *toolbarTestCaller) {
+	t.Helper()
+	previous := deps
+	SetDeps(Deps{
+		GroupRunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+		CallMCPToolOnServer: func(productID, toolName string, args map[string]any) error {
+			_, err := caller.CallTool(context.Background(), productID, toolName, args)
+			return err
+		},
+		DeclareLeafMetadata: func(cmd *cobra.Command, spec LeafSpec) *cobra.Command {
+			return cmd
+		},
+		ValidateRequiredFlag: validateRequiredFlagsLocal,
+	})
+	t.Cleanup(func() {
+		deps = previous
+	})
+}
+
+func requireTypedConfirmationError(t *testing.T, err error) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected confirmation error, got nil")
+	}
+	if !strings.Contains(err.Error(), "获得用户确认后加 --yes 执行") {
+		t.Fatalf("expected confirmation error, got %v", err)
+	}
+}
+
+func requireToolbarCall(
+	t *testing.T,
+	caller *toolbarTestCaller,
+	wantProduct, wantTool string,
+	wantArgs map[string]any,
+) {
+	t.Helper()
+	if caller.product != wantProduct || caller.tool != wantTool {
+		t.Fatalf("tool call = %s/%s, want %s/%s", caller.product, caller.tool, wantProduct, wantTool)
+	}
+	if !reflect.DeepEqual(caller.args, wantArgs) {
+		t.Fatalf("tool args = %#v, want %#v", caller.args, wantArgs)
+	}
+}
+
+func toolbarCustomArgs(extra ...string) []string {
+	args := []string{"--conversation-id", "cid", "--title", "Title", "--url", "https://example.com/mobile", "--icon-url", "https://example.com/icon.png", "--pc-url", "https://example.com/pc"}
+	return append(args, extra...)
+}
+
+func TestHasIntersection(t *testing.T) {
+	tests := []struct {
+		name string
+		a, b []int64
+		want bool
+	}{
+		{"both empty", nil, nil, false},
+		{"a empty", nil, []int64{1}, false},
+		{"b empty", []int64{1}, nil, false},
+		{"no overlap", []int64{1, 2, 3}, []int64{4, 5, 6}, false},
+		{"has overlap", []int64{1, 2, 3}, []int64{3, 4, 5}, true},
+		{"single match", []int64{1}, []int64{1}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := hasIntersection(tt.a, tt.b)
+			if got != tt.want {
+				t.Errorf("hasIntersection(%v, %v) = %v, want %v", tt.a, tt.b, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsSystemBusy(t *testing.T) {
+	if isSystemBusy(nil) {
+		t.Error("isSystemBusy(nil) should be false")
+	}
+	if !isSystemBusy(errors.New("error code: SYSTEM_BUSY")) {
+		t.Error("isSystemBusy should detect SYSTEM_BUSY in error message")
+	}
+	if isSystemBusy(errors.New("some other error")) {
+		t.Error("isSystemBusy should return false for non-SYSTEM_BUSY errors")
+	}
+}
+
+func TestParseExtension(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().StringArray("extension", nil, "")
+
+	ext, err := parseExtension(cmd)
+	if err != nil {
+		t.Fatalf("empty extension should not error: %v", err)
+	}
+	if ext != nil {
+		t.Fatalf("empty extension should return nil, got %v", ext)
+	}
+
+	_ = cmd.Flags().Set("extension", "key1=val1")
+	_ = cmd.Flags().Set("extension", "key2=val2")
+	ext, err = parseExtension(cmd)
+	if err != nil {
+		t.Fatalf("valid extension should not error: %v", err)
+	}
+	if ext["key1"] != "val1" || ext["key2"] != "val2" {
+		t.Fatalf("unexpected extension map: %v", ext)
+	}
+
+	cmd2 := &cobra.Command{Use: "test2"}
+	cmd2.Flags().StringArray("extension", nil, "")
+	_ = cmd2.Flags().Set("extension", "badformat")
+	_, err = parseExtension(cmd2)
+	if err == nil {
+		t.Fatal("invalid extension format should error")
+	}
+
+	cmd3 := &cobra.Command{Use: "test3"}
+	cmd3.Flags().StringArray("extension", nil, "")
+	_ = cmd3.Flags().Set("extension", "color=blue")
+	_ = cmd3.Flags().Set("extension", "color=red")
+	_, err = parseExtension(cmd3)
+	if err == nil {
+		t.Fatal("duplicate extension keys should error")
+	}
+
+	cmd4 := &cobra.Command{Use: "test4"}
+	cmd4.Flags().StringArray("extension", nil, "")
+	_ = cmd4.Flags().Set("extension", " =value")
+	_, err = parseExtension(cmd4)
+	if err == nil {
+		t.Fatal("blank extension key should error")
+	}
+}
+
+func TestToolbarConversationID(t *testing.T) {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("conversation-id", "", "")
+
+	_, err := toolbarConversationID(cmd)
+	if err == nil {
+		t.Fatal("missing conversation-id should error")
+	}
+
+	_ = cmd.Flags().Set("conversation-id", "cid123")
+	cid, err := toolbarConversationID(cmd)
+	if err != nil {
+		t.Fatalf("valid conversation-id should not error: %v", err)
+	}
+	if cid != "cid123" {
+		t.Fatalf("expected cid123, got %s", cid)
+	}
+}
+
+func TestToolbarDepsDefaultWrappersAndValidationEdges(t *testing.T) {
+	cmd := &cobra.Command{Use: "toolbar"}
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := groupRunE(cmd, nil); err != nil {
+		t.Fatalf("default groupRunE returned error: %v", err)
+	}
+	if err := callMCPToolOnServer("im", "tool", nil); err == nil ||
+		!strings.Contains(err.Error(), "CallMCPToolOnServer is not initialized") {
+		t.Fatalf("default callMCPToolOnServer error = %v", err)
+	}
+	if got := DeclareLeafMetadata(cmd, LeafSpec{}); got != cmd {
+		t.Fatal("default DeclareLeafMetadata should return the original command")
+	}
+
+	toolbar := NewChatToolbarCommand()
+	if toolbar.Name() != "toolbar" || len(toolbar.Commands()) != 7 {
+		t.Fatalf("toolbar command = %q with %d children, want toolbar with 7 children", toolbar.Name(), len(toolbar.Commands()))
+	}
+
+	parent := &cobra.Command{Use: "parent"}
+	parent.PersistentFlags().String("conversation-id", "", "")
+	child := &cobra.Command{Use: "child"}
+	parent.AddCommand(child)
+	_ = parent.PersistentFlags().Set("conversation-id", " inherited ")
+	if got := mustGetFlag(child, "conversation-id"); got != "inherited" {
+		t.Fatalf("mustGetFlag inherited value = %q, want inherited", got)
+	}
+
+	if _, err := parseCSVInt64(" , "); err == nil || !strings.Contains(err.Error(), "at least one ID") {
+		t.Fatalf("empty csv error = %v", err)
+	}
+	if _, err := parseCSVInt64("1,bad"); err == nil || !strings.Contains(err.Error(), `invalid integer "bad"`) {
+		t.Fatalf("invalid csv error = %v", err)
+	}
+	required := &cobra.Command{Use: "required"}
+	required.Flags().String("title", "", "")
+	if err := validateRequiredFlagsLocal(required, "title"); err == nil ||
+		!strings.Contains(err.Error(), "flag --title is required") {
+		t.Fatalf("validateRequiredFlagsLocal error = %v", err)
+	}
+	if commandBoolFlag(nil, "yes") {
+		t.Fatal("commandBoolFlag(nil) should be false")
+	}
+	boolParent := &cobra.Command{Use: "parent"}
+	boolParent.PersistentFlags().Bool("yes", false, "")
+	boolChild := &cobra.Command{Use: "child"}
+	boolParent.AddCommand(boolChild)
+	_ = boolParent.PersistentFlags().Set("yes", "true")
+	if !commandBoolFlag(boolChild, "yes") {
+		t.Fatal("commandBoolFlag should read inherited true value")
+	}
+}
+
+func TestToolbarCommandsValidationEdges(t *testing.T) {
+	tests := []struct {
+		name      string
+		cmd       func() *cobra.Command
+		args      []string
+		wantError string
+	}{
+		{
+			name:      "add blank conversation id",
+			cmd:       newToolbarAddCommand,
+			args:      []string{"--conversation-id", " ", "--shortcut-ids", "1"},
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "add blank shortcut ids",
+			cmd:       newToolbarAddCommand,
+			args:      []string{"--conversation-id", "cid", "--shortcut-ids", " "},
+			wantError: "flag --shortcut-ids is required",
+		},
+		{
+			name:      "add invalid shortcut ids",
+			cmd:       newToolbarAddCommand,
+			args:      []string{"--conversation-id", "cid", "--shortcut-ids", "1,bad"},
+			wantError: "--shortcut-ids",
+		},
+		{
+			name:      "hide blank conversation id",
+			cmd:       newToolbarHideCommand,
+			args:      []string{"--conversation-id", " ", "--shortcut-ids", "1"},
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "hide blank shortcut ids",
+			cmd:       newToolbarHideCommand,
+			args:      []string{"--conversation-id", "cid", "--shortcut-ids", " "},
+			wantError: "flag --shortcut-ids is required",
+		},
+		{
+			name:      "hide invalid shortcut ids",
+			cmd:       newToolbarHideCommand,
+			args:      []string{"--conversation-id", "cid", "--shortcut-ids", "1,bad"},
+			wantError: "--shortcut-ids",
+		},
+		{
+			name:      "list blank conversation id",
+			cmd:       newToolbarListCommand,
+			args:      []string{"--conversation-id", " "},
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "sort blank conversation id",
+			cmd:       newToolbarSortCommand,
+			args:      []string{"--conversation-id", " ", "--sorted-ids", "1"},
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "sort blank sorted ids",
+			cmd:       newToolbarSortCommand,
+			args:      []string{"--conversation-id", "cid", "--sorted-ids", " "},
+			wantError: "flag --sorted-ids is required",
+		},
+		{
+			name:      "sort invalid sorted ids",
+			cmd:       newToolbarSortCommand,
+			args:      []string{"--conversation-id", "cid", "--sorted-ids", "1,bad"},
+			wantError: "--sorted-ids",
+		},
+		{
+			name:      "sort invalid unsorted ids",
+			cmd:       newToolbarSortCommand,
+			args:      []string{"--conversation-id", "cid", "--sorted-ids", "1", "--unsorted-ids", "bad"},
+			wantError: "--unsorted-ids",
+		},
+		{
+			name:      "create blank conversation id",
+			cmd:       newToolbarCreateCustomCommand,
+			args:      toolbarCustomArgs("--conversation-id", " "),
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "create blank title",
+			cmd:       newToolbarCreateCustomCommand,
+			args:      toolbarCustomArgs("--title", " "),
+			wantError: "flag --title is required",
+		},
+		{
+			name:      "create invalid extension",
+			cmd:       newToolbarCreateCustomCommand,
+			args:      toolbarCustomArgs("--extension", "bad"),
+			wantError: "--extension",
+		},
+		{
+			name:      "remove blank conversation id",
+			cmd:       newToolbarRemoveCustomCommand,
+			args:      []string{"--conversation-id", " ", "--shortcut-id", "42", "--yes"},
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "update blank conversation id",
+			cmd:       newToolbarUpdateCustomCommand,
+			args:      toolbarCustomArgs("--shortcut-id", "42", "--conversation-id", " "),
+			wantError: "flag --conversation-id is required",
+		},
+		{
+			name:      "update blank title",
+			cmd:       newToolbarUpdateCustomCommand,
+			args:      toolbarCustomArgs("--shortcut-id", "42", "--title", " "),
+			wantError: "flag --title is required",
+		},
+		{
+			name:      "update invalid extension",
+			cmd:       newToolbarUpdateCustomCommand,
+			args:      toolbarCustomArgs("--shortcut-id", "42", "--extension", "bad"),
+			wantError: "--extension",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := executeToolbarCommand(t, tt.cmd(), &toolbarTestCaller{}, tt.args...)
+			if err == nil || !strings.Contains(err.Error(), tt.wantError) {
+				t.Fatalf("error = %v, want containing %q", err, tt.wantError)
+			}
+		})
+	}
+}
+
+func TestToolbarCommandsConvertSystemBusy(t *testing.T) {
+	tests := []struct {
+		name string
+		cmd  func() *cobra.Command
+		args []string
+	}{
+		{
+			name: "add",
+			cmd:  newToolbarAddCommand,
+			args: []string{"--conversation-id", "cid", "--shortcut-ids", "1,2"},
+		},
+		{
+			name: "hide",
+			cmd:  newToolbarHideCommand,
+			args: []string{"--conversation-id", "cid", "--shortcut-ids", "1,2"},
+		},
+		{
+			name: "sort",
+			cmd:  newToolbarSortCommand,
+			args: []string{"--conversation-id", "cid", "--sorted-ids", "1,2"},
+		},
+		{
+			name: "remove-custom",
+			cmd:  newToolbarRemoveCustomCommand,
+			args: []string{"--conversation-id", "cid", "--shortcut-id", "1", "--yes"},
+		},
+		{
+			name: "create-custom",
+			cmd:  newToolbarCreateCustomCommand,
+			args: toolbarCustomArgs(),
+		},
+		{
+			name: "update-custom",
+			cmd:  newToolbarUpdateCustomCommand,
+			args: toolbarCustomArgs("--shortcut-id", "99"),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := executeToolbarCommand(t, tt.cmd(), &toolbarTestCaller{
+				err: errors.New("remote SYSTEM_BUSY"),
+			}, tt.args...)
+			if err == nil || !strings.Contains(err.Error(), "SYSTEM_BUSY") {
+				t.Fatalf("expected system_busy validation error, got %v", err)
+			}
+		})
+	}
+}
+
+func TestToolbarCreateAndUpdateCustomIncludeOptionalFields(t *testing.T) {
+	createCaller := &toolbarTestCaller{}
+	err := executeToolbarCommand(t, newToolbarCreateCustomCommand(), createCaller, toolbarCustomArgs(
+		"--desc", "Description",
+		"--tag", "Tag",
+		"--sort-index", "7",
+		"--extension", "color=blue",
+	)...)
+	if err != nil {
+		t.Fatalf("create-custom returned error: %v", err)
+	}
+	requireToolbarCall(t, createCaller, "im", "create_custom_shortcut", map[string]any{
+		"openConversationId": "cid",
+		"name":               `{"zh_CN":"Title"}`,
+		"url":                "https://example.com/mobile",
+		"icons":              `{"iconMobile":"https://example.com/icon.png"}`,
+		"pcUrl":              "https://example.com/pc",
+		"desc":               `{"zh_CN":"Description"}`,
+		"tag":                "Tag",
+		"sortIndex":          7,
+		"extension":          map[string]string{"color": "blue"},
+	})
+
+	updateCaller := &toolbarTestCaller{}
+	err = executeToolbarCommand(t, newToolbarUpdateCustomCommand(), updateCaller, toolbarCustomArgs(
+		"--shortcut-id", "99",
+		"--desc", "Description",
+		"--tag", "Tag",
+		"--sort-index", "7",
+		"--extension", "color=blue",
+	)...)
+	if err != nil {
+		t.Fatalf("update-custom returned error: %v", err)
+	}
+	requireToolbarCall(t, updateCaller, "im", "update_custom_shortcut", map[string]any{
+		"openConversationId": "cid",
+		"shortcutId":         int64(99),
+		"name":               `{"zh_CN":"Title"}`,
+		"url":                "https://example.com/mobile",
+		"icons":              `{"iconMobile":"https://example.com/icon.png"}`,
+		"pcUrl":              "https://example.com/pc",
+		"desc":               `{"zh_CN":"Description"}`,
+		"tag":                "Tag",
+		"sortIndex":          7,
+		"extension":          map[string]string{"color": "blue"},
+	})
+}
+
+func TestToolbarCreateCustomDefaultsDescToTitle(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{name: "missing desc", args: toolbarCustomArgs()},
+		{name: "blank desc", args: toolbarCustomArgs("--desc", "   ")},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &toolbarTestCaller{}
+			if err := executeToolbarCommand(t, newToolbarCreateCustomCommand(), caller, tt.args...); err != nil {
+				t.Fatalf("create-custom returned error: %v", err)
+			}
+			requireToolbarCall(t, caller, "im", "create_custom_shortcut", map[string]any{
+				"openConversationId": "cid",
+				"name":               `{"zh_CN":"Title"}`,
+				"url":                "https://example.com/mobile",
+				"icons":              `{"iconMobile":"https://example.com/icon.png"}`,
+				"pcUrl":              "https://example.com/pc",
+				"desc":               `{"zh_CN":"Title"}`,
+			})
+		})
+	}
+}
+
+func TestToolbarUpdateCustomDefaultsDescToTitle(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{name: "missing desc", args: toolbarCustomArgs("--shortcut-id", "99")},
+		{name: "blank desc", args: toolbarCustomArgs("--shortcut-id", "99", "--desc", "   ")},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &toolbarTestCaller{}
+			if err := executeToolbarCommand(t, newToolbarUpdateCustomCommand(), caller, tt.args...); err != nil {
+				t.Fatalf("update-custom returned error: %v", err)
+			}
+			requireToolbarCall(t, caller, "im", "update_custom_shortcut", map[string]any{
+				"openConversationId": "cid",
+				"shortcutId":         int64(99),
+				"name":               `{"zh_CN":"Title"}`,
+				"url":                "https://example.com/mobile",
+				"icons":              `{"iconMobile":"https://example.com/icon.png"}`,
+				"pcUrl":              "https://example.com/pc",
+				"desc":               `{"zh_CN":"Title"}`,
+			})
+		})
+	}
+}
+
+func TestToolbarSortValidatesOptionalUnsortedIDs(t *testing.T) {
+	intersectionErr := executeToolbarCommand(t, newToolbarSortCommand(), &toolbarTestCaller{},
+		"--conversation-id", "cid",
+		"--sorted-ids", "1,2",
+		"--unsorted-ids", "2,3",
+	)
+	if intersectionErr == nil || !strings.Contains(intersectionErr.Error(), "不能有交集") {
+		t.Fatalf("expected id_intersection error, got %v", intersectionErr)
+	}
+
+	caller := &toolbarTestCaller{}
+	err := executeToolbarCommand(t, newToolbarSortCommand(), caller,
+		"--conversation-id", "cid",
+		"--sorted-ids", "1,2",
+		"--unsorted-ids", "3,4",
+	)
+	if err != nil {
+		t.Fatalf("sort returned error: %v", err)
+	}
+	requireToolbarCall(t, caller, "im", "sort_shortcut_bar", map[string]any{
+		"openConversationId":  "cid",
+		"sortedShortcutIds":   []int64{1, 2},
+		"unsortedShortcutIds": []int64{3, 4},
+	})
+}
+
+func TestCrossPlatformCoverageToolbarAddHideAndListCallMCPWithExactArgs(t *testing.T) {
+	tests := []struct {
+		name     string
+		cmd      func() *cobra.Command
+		args     []string
+		wantTool string
+		wantArgs map[string]any
+	}{
+		{
+			name:     "add",
+			cmd:      newToolbarAddCommand,
+			args:     []string{"--conversation-id", "cidX", "--shortcut-ids", "101,102"},
+			wantTool: "add_shortcut_to_bar",
+			wantArgs: map[string]any{
+				"openConversationId": "cidX",
+				"shortcutIds":        []int64{101, 102},
+			},
+		},
+		{
+			name:     "hide",
+			cmd:      newToolbarHideCommand,
+			args:     []string{"--conversation-id", "cidX", "--shortcut-ids", "201,202"},
+			wantTool: "hide_shortcut_from_bar",
+			wantArgs: map[string]any{
+				"openConversationId": "cidX",
+				"shortcutIds":        []int64{201, 202},
+			},
+		},
+		{
+			name:     "list",
+			cmd:      newToolbarListCommand,
+			args:     []string{"--conversation-id", "cidX"},
+			wantTool: "list_chat_toolbar_shortcuts",
+			wantArgs: map[string]any{
+				"openConversationId": "cidX",
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &toolbarTestCaller{}
+			if err := executeToolbarCommand(t, tt.cmd(), caller, tt.args...); err != nil {
+				t.Fatalf("%s returned error: %v", tt.name, err)
+			}
+			requireToolbarCall(t, caller, "im", tt.wantTool, tt.wantArgs)
+		})
+	}
+}
+
+func TestCrossPlatformCoverageToolbarRemoveCustomRejectsWithoutYes(t *testing.T) {
+	caller := &toolbarTestCaller{}
+	err := executeToolbarCommand(t, newToolbarRemoveCustomCommand(), caller,
+		"--conversation-id", "cidX", "--shortcut-id", "42")
+	requireTypedConfirmationError(t, err)
+	if len(caller.calls) != 0 {
+		t.Fatalf("expected 0 MCP calls before --yes, got %d: %+v", len(caller.calls), caller.calls)
+	}
+	if caller.product != "" || caller.tool != "" || caller.args != nil {
+		t.Fatalf("expected no MCP call recorded, got product=%q tool=%q args=%#v", caller.product, caller.tool, caller.args)
+	}
+}
+
+func TestCrossPlatformCoverageToolbarRemoveCustomCallsMCPWithExactArgsWhenYes(t *testing.T) {
+	caller := &toolbarTestCaller{}
+	err := executeToolbarCommand(t, newToolbarRemoveCustomCommand(), caller,
+		"--conversation-id", "cidX", "--shortcut-id", "42", "--yes")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(caller.calls) != 1 {
+		t.Fatalf("expected exactly 1 MCP call, got %d: %+v", len(caller.calls), caller.calls)
+	}
+	call := caller.calls[0]
+	if call.product != "im" {
+		t.Fatalf("product = %q, want im", call.product)
+	}
+	if call.tool != "remove_custom_shortcut" {
+		t.Fatalf("tool = %q, want remove_custom_shortcut", call.tool)
+	}
+	wantArgs := map[string]any{"openConversationId": "cidX", "shortcutId": int64(42)}
+	if !reflect.DeepEqual(call.args, wantArgs) {
+		t.Fatalf("tool args = %#v, want %#v", call.args, wantArgs)
+	}
+}
+
+type removeCustomSeamCall struct {
+	openConversationId string
+	shortcutId         int64
+}
+
+type removeCustomSeamStub struct {
+	calls []removeCustomSeamCall
+	err   error
+}
+
+// invoke records the seam call and forwards to deps.Caller.CallTool so the
+// command path still records the same remote invocation shape as production.
+func (s *removeCustomSeamStub) invoke(openConversationId string, shortcutId int64) error {
+	s.calls = append(s.calls, removeCustomSeamCall{openConversationId: openConversationId, shortcutId: shortcutId})
+	if err := callMCPToolOnServer("im", "remove_custom_shortcut", map[string]any{
+		"openConversationId": openConversationId,
+		"shortcutId":         shortcutId,
+	}); err != nil {
+		return err
+	}
+	return s.err
+}
+
+func TestCrossPlatformCoverageToolbarRemoveCustomSeamRejectsWithoutYes(t *testing.T) {
+	stub := &removeCustomSeamStub{}
+	testseam.Swap(t, &removeChatToolbarCustomShortcutFn, stub.invoke)
+
+	err := executeToolbarCommand(t, newToolbarRemoveCustomCommand(), &toolbarTestCaller{},
+		"--conversation-id", "cidX", "--shortcut-id", "42")
+	requireTypedConfirmationError(t, err)
+	if len(stub.calls) != 0 {
+		t.Fatalf("expected 0 seam calls before --yes, got %d: %+v", len(stub.calls), stub.calls)
+	}
+}
+
+func TestCrossPlatformCoverageToolbarRemoveCustomSeamCallsWithExactArgsWhenYes(t *testing.T) {
+	stub := &removeCustomSeamStub{}
+	testseam.Swap(t, &removeChatToolbarCustomShortcutFn, stub.invoke)
+
+	err := executeToolbarCommand(t, newToolbarRemoveCustomCommand(), &toolbarTestCaller{},
+		"--conversation-id", "cidX", "--shortcut-id", "42", "--yes")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if len(stub.calls) != 1 {
+		t.Fatalf("expected exactly 1 seam call, got %d: %+v", len(stub.calls), stub.calls)
+	}
+	call := stub.calls[0]
+	if call.openConversationId != "cidX" {
+		t.Fatalf("seam openConversationId = %q, want cidX", call.openConversationId)
+	}
+	if call.shortcutId != int64(42) {
+		t.Fatalf("seam shortcutId = %d, want 42", call.shortcutId)
+	}
+}
+
+func TestToolbarRemoveCustomDeclaresDestructiveHighRiskConfirmation(t *testing.T) {
+	var got LeafSpec
+	next := deps
+	next.DeclareLeafMetadata = func(cmd *cobra.Command, spec LeafSpec) *cobra.Command {
+		got = spec
+		return cmd
+	}
+	testseam.Swap(t, &deps, next)
+
+	_ = newToolbarRemoveCustomCommand()
+	if got.Safety.Effect != "destructive" || got.Safety.Risk != "high" ||
+		got.Safety.Confirmation != "user_required" {
+		t.Fatalf("remove-custom safety = %#v, want destructive/high/user_required", got.Safety)
+	}
+}

internal/helpers/chat/toolbar_hide.go

@@ -0,0 +1,92 @@
+// 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 chat
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func newToolbarHideCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "hide",
+		Short: "将入口从快捷栏可见区隐藏",
+		Long:  "将一个或多个快捷入口从可见区移至隐藏区。入口 ID 使用逗号分隔。",
+		Example: `  dws chat toolbar hide --conversation-id <cid> --shortcut-ids 101,102
+  # 查询入口 ID: dws chat toolbar list --conversation-id <cid>`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "shortcut-ids"); err != nil {
+				return err
+			}
+			ids, err := parseCSVInt64(mustGetFlag(cmd, "shortcut-ids"))
+			if err != nil {
+				return fmt.Errorf("--shortcut-ids: %w", err)
+			}
+			err = callMCPToolOnServer("im", "hide_shortcut_from_bar", map[string]any{
+				"openConversationId": cid,
+				"shortcutIds":        ids,
+			})
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().String("shortcut-ids", "", "入口 ID 列表（逗号分隔）")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("shortcut-ids")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "hide_shortcut_from_bar",
+				CanonicalPath:  "chat.hide_shortcut_from_bar",
+				CLIPath:        "chat toolbar hide",
+				PrimaryCLIPath: "chat toolbar hide",
+			},
+			Description: "将快捷入口从会话快捷栏可见区移至隐藏区",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "hide_shortcut_from_bar"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "将快捷入口从会话快捷栏可见区隐藏",
+				UseWhen:      []string{"需要将快捷栏中的入口隐藏到隐藏区"},
+				AvoidWhen:    []string{"永久删除自定义入口应使用 chat toolbar remove-custom"},
+				Examples:     []string{"dws chat toolbar hide --conversation-id <cid> --shortcut-ids 101,102"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "shortcut-ids", Property: "shortcutIds", Required: boolPtr(true)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_list.go

@@ -0,0 +1,75 @@
+// 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 chat
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func newToolbarListCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "查询会话快捷栏入口列表",
+		Long:  "查询指定会话的快捷栏入口列表，包括可见区和隐藏区的所有入口。",
+		Example: `  dws chat toolbar list --conversation-id <cid>
+  # 查询群 ID: dws chat search --query "群名"`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			return callMCPToolOnServer("im", "list_chat_toolbar_shortcuts", map[string]any{
+				"openConversationId": cid,
+			})
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "list_chat_toolbar_shortcuts",
+				CanonicalPath:  "chat.list_chat_toolbar_shortcuts",
+				CLIPath:        "chat toolbar list",
+				PrimaryCLIPath: "chat toolbar list",
+			},
+			Description: "查询会话快捷栏入口列表",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "list_chat_toolbar_shortcuts"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查询会话快捷栏入口列表",
+				UseWhen:      []string{"需要查看会话快捷栏中有哪些入口、获取入口 ID 时"},
+				AvoidWhen:    []string{"修改快捷栏排序使用 chat toolbar sort；创建自定义入口使用 chat toolbar create-custom"},
+				Examples:     []string{"dws chat toolbar list --conversation-id <cid>"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_remove_custom.go

@@ -0,0 +1,103 @@
+// 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 chat
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+// removeChatToolbarCustomShortcutFn is the package-level injection seam for
+// the remove-custom command's remote call. The default implementation routes
+// through callMCPToolOnServer against the im server, so production behavior is
+// unchanged. Tests swap it with testseam.Swap(t, &removeChatToolbarCustomShortcutFn, stub)
+// to capture the call without hitting a real remote. Like every package-var
+// seam in this repo it is not safe for t.Parallel tests.
+var removeChatToolbarCustomShortcutFn = func(openConversationId string, shortcutId int64) error {
+	return callMCPToolOnServer("im", "remove_custom_shortcut", map[string]any{
+		"openConversationId": openConversationId,
+		"shortcutId":         shortcutId,
+	})
+}
+
+func newToolbarRemoveCustomCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "remove-custom",
+		Short:   "删除自定义快捷栏入口",
+		Long:    "删除一个自定义快捷栏入口。该操作不可逆；必须先获得用户确认，再追加 --yes 执行。",
+		Example: `  dws chat toolbar remove-custom --conversation-id <cid> --shortcut-id 123`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			shortcutId, _ := cmd.Flags().GetInt64("shortcut-id")
+			if !commandBoolFlag(cmd, "yes") {
+				return apperrors.NewValidation(
+					"删除自定义快捷入口不可逆；获得用户确认后加 --yes 执行",
+					apperrors.WithReason("confirmation_required"),
+					apperrors.WithHint("先确认目标入口及影响范围；用户明确同意后以相同参数追加 --yes"),
+					apperrors.WithActions("确认目标自定义入口", "获得用户确认后使用 --yes 执行"),
+				)
+			}
+			err = removeChatToolbarCustomShortcutFn(cid, shortcutId)
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().Int64("shortcut-id", 0, "自定义入口 ID")
+	cmd.Flags().Bool("yes", false, "确认执行删除操作")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("shortcut-id")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "destructive", Risk: "high",
+			Confirmation: "user_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "remove_custom_shortcut",
+				CanonicalPath:  "chat.remove_custom_shortcut",
+				CLIPath:        "chat toolbar remove-custom",
+				PrimaryCLIPath: "chat toolbar remove-custom",
+			},
+			Description: "删除自定义快捷栏入口",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "remove_custom_shortcut"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "删除自定义快捷栏入口",
+				UseWhen:      []string{"需要永久删除某个自定义快捷栏入口"},
+				AvoidWhen:    []string{"仅隐藏入口使用 chat toolbar hide；更新入口使用 chat toolbar update-custom"},
+				Examples:     []string{"dws chat toolbar remove-custom --conversation-id <cid> --shortcut-id 123"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "shortcut-id", Property: "shortcutId", Required: boolPtr(true)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_sort.go

@@ -0,0 +1,115 @@
+// 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 chat
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+func newToolbarSortCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "sort",
+		Short: "排序快捷栏入口",
+		Long:  "对会话快捷栏入口进行排序。sorted-ids 指定排序后的可见区入口 ID 列表，unsorted-ids 指定不参与排序放在末尾的入口 ID 列表。两个列表不能有交集。",
+		Example: `  dws chat toolbar sort --conversation-id <cid> --sorted-ids 101,102,103
+  dws chat toolbar sort --conversation-id <cid> --sorted-ids 101,102 --unsorted-ids 103,104
+  # 查询入口 ID: dws chat toolbar list --conversation-id <cid>`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			if err := validateRequiredFlags(cmd, "sorted-ids"); err != nil {
+				return err
+			}
+			sortedIds, err := parseCSVInt64(mustGetFlag(cmd, "sorted-ids"))
+			if err != nil {
+				return fmt.Errorf("--sorted-ids: %w", err)
+			}
+
+			toolArgs := map[string]any{
+				"openConversationId": cid,
+				"sortedShortcutIds":  sortedIds,
+			}
+
+			if unsortedRaw, _ := cmd.Flags().GetString("unsorted-ids"); unsortedRaw != "" {
+				unsortedIds, err := parseCSVInt64(unsortedRaw)
+				if err != nil {
+					return fmt.Errorf("--unsorted-ids: %w", err)
+				}
+				if hasIntersection(sortedIds, unsortedIds) {
+					return apperrors.NewValidation(
+						"--sorted-ids 与 --unsorted-ids 不能有交集",
+						apperrors.WithReason("id_intersection"),
+						apperrors.WithHint("检查两个 ID 列表，确保同一个 ID 不同时出现在两个列表中"),
+						apperrors.WithActions("修正 ID 列表后重试"),
+					)
+				}
+				toolArgs["unsortedShortcutIds"] = unsortedIds
+			}
+
+			err = callMCPToolOnServer("im", "sort_shortcut_bar", toolArgs)
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().String("sorted-ids", "", "排序后的入口 ID 列表（逗号分隔）")
+	cmd.Flags().String("unsorted-ids", "", "不参与排序放在末尾的入口 ID 列表（逗号分隔）")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("sorted-ids")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "sort_shortcut_bar",
+				CanonicalPath:  "chat.sort_shortcut_bar",
+				CLIPath:        "chat toolbar sort",
+				PrimaryCLIPath: "chat toolbar sort",
+			},
+			Description: "对会话快捷栏入口进行排序",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "sort_shortcut_bar"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "对会话快捷栏入口进行排序",
+				UseWhen:      []string{"需要调整快捷栏入口的显示顺序"},
+				AvoidWhen:    []string{"仅添加或隐藏入口使用 chat toolbar add / hide"},
+				Examples:     []string{"dws chat toolbar sort --conversation-id <cid> --sorted-ids 101,102,103"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "sorted-ids", Property: "sortedShortcutIds", Required: boolPtr(true)},
+				{Name: "unsorted-ids", Property: "unsortedShortcutIds", Required: boolPtr(false)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat/toolbar_update_custom.go

@@ -0,0 +1,149 @@
+// 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 chat
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)
+
+func newToolbarUpdateCustomCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "update-custom",
+		Short: "更新自定义快捷栏入口",
+		Long: `更新一个已有的自定义快捷栏入口。
+
+必填参数：
+  --conversation-id  会话 openConversationId
+  --shortcut-id      自定义入口 ID
+  --title            入口标题
+  --url              入口跳转链接
+  --icon-url         入口图标 URL
+  --pc-url           PC 端跳转链接
+
+可选参数：
+  --extension        扩展信息，格式 key=value，可重复使用
+  --desc             入口描述
+  --tag              入口标签
+  --sort-index       排序权重`,
+		Example: `  dws chat toolbar update-custom --conversation-id <cid> --shortcut-id 123 --title "周报" --url "https://example.com" --icon-url "https://example.com/icon.png" --pc-url "https://example.com"
+  # 查询入口 ID: dws chat toolbar list --conversation-id <cid>`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cid, err := toolbarConversationID(cmd)
+			if err != nil {
+				return err
+			}
+			shortcutId, _ := cmd.Flags().GetInt64("shortcut-id")
+			if err := validateRequiredFlags(cmd, "title", "url", "icon-url", "pc-url"); err != nil {
+				return err
+			}
+
+			toolArgs := map[string]any{
+				"openConversationId": cid,
+				"shortcutId":         shortcutId,
+				"name":               toolbarI18nJSONString(mustGetFlag(cmd, "title")),
+				"url":                mustGetFlag(cmd, "url"),
+				"icons":              toolbarIconsJSONString(mustGetFlag(cmd, "icon-url")),
+				"pcUrl":              mustGetFlag(cmd, "pc-url"),
+			}
+
+			descValue := mustGetFlag(cmd, "desc")
+			if descValue == "" {
+				descValue = mustGetFlag(cmd, "title")
+			}
+			toolArgs["desc"] = toolbarI18nJSONString(descValue)
+			if tag, _ := cmd.Flags().GetString("tag"); tag != "" {
+				toolArgs["tag"] = tag
+			}
+			if cmd.Flags().Changed("sort-index") {
+				sortIndex, _ := cmd.Flags().GetInt("sort-index")
+				toolArgs["sortIndex"] = sortIndex
+			}
+
+			ext, err := parseExtension(cmd)
+			if err != nil {
+				return err
+			}
+			if ext != nil {
+				toolArgs["extension"] = ext
+			}
+
+			err = callMCPToolOnServer("im", "update_custom_shortcut", toolArgs)
+			if isSystemBusy(err) {
+				return toolbarNewSystemBusyError()
+			}
+			return err
+		},
+	}
+	cmd.Flags().String("conversation-id", "", "会话 openConversationId")
+	cmd.Flags().Int64("shortcut-id", 0, "自定义入口 ID")
+	cmd.Flags().String("title", "", "入口标题")
+	cmd.Flags().String("url", "", "入口跳转链接")
+	cmd.Flags().String("icon-url", "", "入口图标 URL")
+	cmd.Flags().String("pc-url", "", "PC 端跳转链接")
+	cmd.Flags().StringArray("extension", nil, "扩展信息，格式 key=value，可重复使用")
+	cmd.Flags().String("desc", "", "入口描述")
+	cmd.Flags().String("tag", "", "入口标签")
+	cmd.Flags().Int("sort-index", 0, "排序权重")
+	_ = cmd.MarkFlagRequired("conversation-id")
+	_ = cmd.MarkFlagRequired("shortcut-id")
+	_ = cmd.MarkFlagRequired("title")
+	_ = cmd.MarkFlagRequired("url")
+	_ = cmd.MarkFlagRequired("icon-url")
+	_ = cmd.MarkFlagRequired("pc-url")
+	cmd.DisableAutoGenTag = true
+
+	DeclareLeafMetadata(cmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "chat",
+				Name:           "update_custom_shortcut",
+				CanonicalPath:  "chat.update_custom_shortcut",
+				CLIPath:        "chat toolbar update-custom",
+				PrimaryCLIPath: "chat toolbar update-custom",
+			},
+			Description: "更新自定义快捷栏入口",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "im", RPCName: "update_custom_shortcut"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "更新自定义快捷栏入口",
+				UseWhen:      []string{"需要修改已有自定义快捷栏入口的标题、链接、图标等属性"},
+				AvoidWhen:    []string{"创建新入口使用 chat toolbar create-custom；删除入口使用 chat toolbar remove-custom"},
+				Examples:     []string{"dws chat toolbar update-custom --conversation-id <cid> --shortcut-id 123 --title \"周报\" --url \"https://example.com\" --icon-url \"https://example.com/icon.png\" --pc-url \"https://example.com\""},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "conversation-id", Property: "openConversationId", Required: boolPtr(true)},
+				{Name: "shortcut-id", Property: "shortcutId", Required: boolPtr(true)},
+				{Name: "title", Property: "name", Required: boolPtr(true)},
+				{Name: "url", Property: "url", Required: boolPtr(true)},
+				{Name: "icon-url", Property: "icons", Required: boolPtr(true)},
+				{Name: "pc-url", Property: "pcUrl", Required: boolPtr(true)},
+				{Name: "extension", Property: "extension", Required: boolPtr(false)},
+				{Name: "desc", Property: "desc", Required: boolPtr(false)},
+				{Name: "tag", Property: "tag", Required: boolPtr(false)},
+				{Name: "sort-index", Property: "sortIndex", Required: boolPtr(false)},
+			},
+		},
+	})
+
+	return cmd
+}

internal/helpers/chat_card_update_test.go

@@ -0,0 +1,163 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+func runNativeCardUpdate(t *testing.T, caller *scriptedToolCaller, args ...string) error {
+	t.Helper()
+	installScriptedCaller(t, caller)
+	root := newChatCommand()
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	if root.PersistentFlags().Lookup("dry-run") == nil {
+		root.PersistentFlags().Bool("dry-run", false, "preview without executing")
+	}
+	if root.PersistentFlags().Lookup("yes") == nil {
+		root.PersistentFlags().Bool("yes", false, "skip confirmation")
+	}
+	root.SetArgs(args)
+	return root.Execute()
+}
+
+func TestCrossPlatformCoverageNativeMessageUpdateCardVerifiesWrite(t *testing.T) {
+	t.Run("atomic command preserves no-extra-confirmation contract", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":{"bizId":"biz-confirm","updated":true}}`}}}
+		if err := runNativeCardUpdate(t, caller,
+			"message", "update-card",
+			"--biz-id", "biz-confirm",
+			"--content", "原子更新",
+			"--flow-status", "3",
+		); err != nil {
+			t.Fatal(err)
+		}
+		wantArgs := map[string]any{
+			"bizId":      "biz-confirm",
+			"msgContent": "原子更新",
+			"flowStatus": 3,
+		}
+		if caller.calls != 1 || caller.server != "im" || caller.tool != "update_streaming_card" || !reflect.DeepEqual(caller.args, wantArgs) {
+			t.Fatalf("atomic call = count:%d server:%q tool:%q args:%#v", caller.calls, caller.server, caller.tool, caller.args)
+		}
+	})
+
+	t.Run("explicit evidence succeeds", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":{"bizId":"biz-1","updated":true}}`}}}
+		err := runNativeCardUpdate(t, caller,
+			"message", "update-card",
+			"--biz-id", "biz-1",
+			"--content", "完成",
+			"--flow-status", "3",
+		)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 1 || caller.server != "im" || caller.tool != "update_streaming_card" {
+			t.Fatalf("call = count:%d server:%q tool:%q", caller.calls, caller.server, caller.tool)
+		}
+		if caller.args["bizId"] != "biz-1" {
+			t.Fatalf("args = %#v", caller.args)
+		}
+	})
+
+	t.Run("generic success is unverified", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"success":true,"errorCode":null}`}}}
+		err := runNativeCardUpdate(t, caller,
+			"message", "update-card",
+			"--biz-id", "not-a-real-card",
+			"--content", "完成",
+			"--flow-status", "3",
+		)
+		var typed *apperrors.Error
+		if !errors.As(err, &typed) || typed.Reason != "streaming_card_update_unverified" {
+			t.Fatalf("error = %#v, want streaming_card_update_unverified", err)
+		}
+	})
+
+	t.Run("lower write error is preserved", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{err: errors.New("write unavailable")}}}
+		err := runNativeCardUpdate(t, caller,
+			"message", "update-card",
+			"--biz-id", "biz-1",
+			"--content", "完成",
+			"--flow-status", "3",
+		)
+		if err == nil {
+			t.Fatal("lower write error was ignored")
+		}
+	})
+
+	for _, test := range []struct {
+		name       string
+		response   string
+		wantReason string
+	}{
+		{name: "empty response", response: "", wantReason: "streaming_card_update_unverified"},
+		{name: "invalid response", response: "{", wantReason: "streaming_card_update_response_invalid"},
+		{name: "not applied", response: `{"result":{"updated":false}}`, wantReason: "streaming_card_update_not_applied"},
+		{name: "biz id drift", response: `{"result":{"bizId":"biz-other","updated":true}}`, wantReason: "streaming_card_update_biz_id_mismatch"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: test.response}}}
+			err := runNativeCardUpdate(t, caller,
+				"message", "update-card",
+				"--biz-id", "biz-1",
+				"--content", "完成",
+				"--flow-status", "3",
+			)
+			var typed *apperrors.Error
+			if !errors.As(err, &typed) || typed.Reason != test.wantReason {
+				t.Fatalf("error = %#v, want reason %q", err, test.wantReason)
+			}
+		})
+	}
+
+	t.Run("invalid arguments make no call", func(t *testing.T) {
+		for _, args := range [][]string{
+			{"message", "update-card", "--biz-id", "<bizId>", "--content", "完成", "--flow-status", "3"},
+			{"message", "update-card", "--biz-id", "biz-1", "--content", "完成", "--flow-status", "6"},
+		} {
+			caller := &scriptedToolCaller{}
+			if err := runNativeCardUpdate(t, caller, args...); err == nil {
+				t.Fatalf("args %v unexpectedly succeeded", args)
+			}
+			if caller.calls != 0 {
+				t.Fatalf("args %v made %d calls", args, caller.calls)
+			}
+		}
+	})
+
+	t.Run("dry run publishes unverified plan without write", func(t *testing.T) {
+		caller := &scriptedToolCaller{}
+		err := runNativeCardUpdate(t, caller,
+			"message", "update-card",
+			"--biz-id", "biz-preview",
+			"--content", "完成",
+			"--flow-status", "3",
+			"--dry-run",
+		)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 0 {
+			t.Fatalf("dry-run made %d calls", caller.calls)
+		}
+	})
+}

internal/helpers/chat_command_edges_test.go

@@ -25,7 +25,7 @@ func runChatCoverageCommand(t *testing.T, caller edition.ToolCaller, args ...str
 	root.SilenceUsage = true
 	root.SetOut(io.Discard)
 	root.SetErr(io.Discard)
-	root.SetArgs(args)
+	root.SetArgs(append(append([]string(nil), args...), "--yes"))
 	return root.ExecuteContext(context.Background())
 }
 

internal/helpers/chat_coverage_more_test.go

@@ -370,6 +370,131 @@ func TestCrossPlatformCoverageUploadConversationLocalFileCoverage(t *testing.T)
 	}
 }
 
+func TestCrossPlatformCoverageChatBotRichMediaCoverage(t *testing.T) {
+	testseam.Protect(t, &deps)
+	testseam.Swap(t, &httpPutFile, func(context.Context, string, map[string]string, string, int64) error {
+		return nil
+	})
+
+	filePath := filepath.Join(t.TempDir(), "report.pdf")
+	if err := os.WriteFile(filePath, []byte("report"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	for _, response := range []string{`{`, `{"result":{}}`} {
+		if _, err := parseConversationFileDownloadURL(response); err == nil {
+			t.Fatalf("parseConversationFileDownloadURL(%q) returned nil", response)
+		}
+	}
+
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{name: "markdown requires title", args: []string{"--text", "message"}},
+		{name: "markdown requires text", args: []string{"--title", "title"}},
+		{name: "image requires URL", args: []string{"--msg-type", "image"}},
+		{name: "file requires path", args: []string{"--msg-type", "file"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			args := []string{"message", "send-by-bot", "--robot-code", "robot", "--group", "group"}
+			if err := runChatCoverageCommand(t, &scriptedToolCaller{}, append(args, tc.args...)...); err == nil {
+				t.Fatal("missing rich-media input returned nil")
+			}
+		})
+	}
+
+	t.Run("group and direct targets are mutually exclusive", func(t *testing.T) {
+		err := runChatCoverageCommand(t, &scriptedToolCaller{},
+			"message", "send-by-bot", "--robot-code", "robot",
+			"--group", "group", "--users", "user", "--title", "title", "--text", "message",
+		)
+		if err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
+			t.Fatalf("mutually exclusive target error = %v", err)
+		}
+	})
+
+	t.Run("direct markdown defaults to DX message type", func(t *testing.T) {
+		caller := &scriptedToolCaller{}
+		if err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--users", "user",
+			"--title", "title", "--text", "message",
+		); err != nil {
+			t.Fatal(err)
+		}
+		if caller.tool != "batch_send_robot_msg_to_users" || caller.args["msgType"] != "sampleMarkdownDX" {
+			t.Fatalf("direct markdown call = %s %#v", caller.tool, caller.args)
+		}
+	})
+
+	t.Run("direct image", func(t *testing.T) {
+		caller := &scriptedToolCaller{}
+		if err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--users", "user",
+			"--msg-type", "image", "--image-url", "https://example.test/image.png", "--at-all",
+		); err != nil {
+			t.Fatal(err)
+		}
+		if caller.tool != "batch_send_robot_msg_to_users" || caller.args["msgType"] != "sampleImageMsg" || caller.args["isAtAll"] != "true" {
+			t.Fatalf("direct image call = %s %#v", caller.tool, caller.args)
+		}
+	})
+
+	for _, tc := range []struct {
+		name   string
+		target []string
+	}{
+		{name: "user file", target: []string{"--users", "user"}},
+		{name: "open DingTalk ID file", target: []string{"--open-dingtalk-ids", "D-user"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{steps: []scriptedToolStep{
+				{text: `{"resourceUrl":"https://upload.example/file","uploadKey":"key"}`},
+				{text: `{"result":{"downloadUrl":"https://download.example/report.pdf"}}`},
+				{text: `{"success":true}`},
+			}}
+			args := []string{"message", "send-by-bot", "--robot-code", "robot", "--msg-type", "file", "--file-path", filePath}
+			if err := runChatCoverageCommand(t, caller, append(args, tc.target...)...); err != nil {
+				t.Fatal(err)
+			}
+			if caller.calls != 3 || caller.tool != "batch_send_robot_msg_to_users" || caller.args["msgType"] != "sampleDingtalkDriveFile" || caller.args["fileUrl"] != "https://download.example/report.pdf" {
+				t.Fatalf("direct file call = %d %s %#v", caller.calls, caller.tool, caller.args)
+			}
+		})
+	}
+
+	t.Run("file dry run", func(t *testing.T) {
+		caller := &scriptedToolCaller{dry: true}
+		if err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--group", "group",
+			"--msg-type", "file", "--file-path", filePath,
+		); err != nil || caller.calls != 0 {
+			t.Fatalf("dry run error = %v, calls = %d", err, caller.calls)
+		}
+	})
+
+	t.Run("file rejects multiple recipients", func(t *testing.T) {
+		err := runChatCoverageCommand(t, &scriptedToolCaller{},
+			"message", "send-by-bot", "--robot-code", "robot", "--users", "one,two",
+			"--msg-type", "file", "--file-path", filePath,
+		)
+		if err == nil || !strings.Contains(err.Error(), "requires exactly one") {
+			t.Fatalf("multiple-recipient error = %v", err)
+		}
+	})
+
+	t.Run("file upload failure", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{err: errors.New("upload failed")}}}
+		err := runChatCoverageCommand(t, caller,
+			"message", "send-by-bot", "--robot-code", "robot", "--group", "group",
+			"--msg-type", "file", "--file-path", filePath,
+		)
+		if err == nil || !strings.Contains(err.Error(), "upload failed") {
+			t.Fatalf("upload error = %v", err)
+		}
+	})
+}
+
 func TestCrossPlatformCoverageGuardGroupOwnerRemovalCoverage(t *testing.T) {
 	oldArgs := os.Args
 	os.Args = []string{"dws", "chat"}

internal/helpers/chat_favorites_test.go

@@ -190,23 +190,23 @@ func TestChatListFavoritesSuppliesOpenDefaults(t *testing.T) {
 func TestChatListFavoritesMapsExplicitPagination(t *testing.T) {
 	caller := &chatFavoritesCaller{}
 	err := executeChatFavoritesCommand(t, caller,
-		"message", "list-favorites", "--cursor", "42", "--size", "50")
+		"message", "list-favorites", "--cursor", "42", "--size", "30")
 	if err != nil {
 		t.Fatalf("list-favorites returned error: %v", err)
 	}
 
-	want := map[string]any{"cursor": int64(42), "size": "50"}
+	want := map[string]any{"cursor": int64(42), "size": "30"}
 	if len(caller.calls) != 1 || caller.calls[0].productID != "im" || caller.calls[0].toolName != "list_message_favorites" || !reflect.DeepEqual(caller.calls[0].args, want) {
 		t.Fatalf("calls = %#v, want im/list_message_favorites %#v", caller.calls, want)
 	}
 }
 
 func TestChatListFavoritesRejectsInvalidSize(t *testing.T) {
-	for _, size := range []string{"-1", "0", "101"} {
+	for _, size := range []string{"-1", "0", "31"} {
 		t.Run(size, func(t *testing.T) {
 			caller := &chatFavoritesCaller{}
 			err := executeChatFavoritesCommand(t, caller, "message", "list-favorites", "--size", size)
-			if err == nil || !strings.Contains(err.Error(), "--size must be between 1 and 100") {
+			if err == nil || !strings.Contains(err.Error(), "--size must be between 1 and 30") {
 				t.Fatalf("error = %v, want size validation error", err)
 			}
 			if got := apperrors.ExitCode(err); got != 3 {

internal/helpers/chat_message_help_test.go

@@ -0,0 +1,92 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package helpers
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+)
+
+func TestCrossPlatformCoverageChatMessageHelpDocumentsPostSendIDChain(t *testing.T) {
+	tests := []struct {
+		name       string
+		command    string
+		contains   []string
+		notContain string
+	}{
+		{
+			name:    "send returns task ID",
+			command: "send",
+			contains: []string{
+				"openTaskId",
+				"query-send-status --open-task-id <openTaskId>",
+			},
+		},
+		{
+			name:    "query returns message and conversation IDs",
+			command: "query-send-status",
+			contains: []string{
+				"openTaskId",
+				"openMessageId",
+				"openConversationId",
+				"chat message edit",
+				"chat message recall",
+			},
+		},
+		{
+			name:    "edit includes post-send workflow",
+			command: "edit",
+			contains: []string{
+				"send -> query-send-status -> edit",
+				"query-send-status --open-task-id <上一步返回的openTaskId>",
+				"edit --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>",
+			},
+			notContain: "chat message list",
+		},
+		{
+			name:    "recall includes post-send workflow",
+			command: "recall",
+			contains: []string{
+				"send -> query-send-status -> recall",
+				"query-send-status --open-task-id <上一步返回的openTaskId>",
+				"recall --conversation-id <上一步返回的openConversationId> --msg-id <上一步返回的openMessageId>",
+			},
+			notContain: "chat message list",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			cmd := newChatCommand()
+			var output bytes.Buffer
+			cmd.SetOut(&output)
+			cmd.SetErr(&output)
+			cmd.SetArgs([]string{"message", test.command, "--help"})
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("chat message %s --help: %v\n%s", test.command, err, output.String())
+			}
+
+			help := output.String()
+			for _, want := range test.contains {
+				if !strings.Contains(help, want) {
+					t.Errorf("chat message %s help missing %q:\n%s", test.command, want, help)
+				}
+			}
+			if test.notContain != "" && strings.Contains(help, test.notContain) {
+				t.Errorf("chat message %s help still contains %q:\n%s", test.command, test.notContain, help)
+			}
+		})
+	}
+}

internal/helpers/chat_message_pagination_test.go

@@ -0,0 +1,267 @@
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"reflect"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+type chatMessagePaginationCaller struct {
+	steps []scriptedToolStep
+	calls []pagedCommandCall
+}
+
+func (c *chatMessagePaginationCaller) CallTool(_ context.Context, serverID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	copied := map[string]any{}
+	for k, v := range args {
+		copied[k] = v
+	}
+	c.calls = append(c.calls, pagedCommandCall{server: serverID, tool: toolName, args: copied})
+	if len(c.steps) == 0 {
+		return textToolResult(`{"result":{"messages":[],"items":[],"hasMore":false,"nextCursor":"0"}}`), nil
+	}
+	step := c.steps[len(c.calls)-1]
+	if step.err != nil {
+		return nil, step.err
+	}
+	return textToolResult(step.text), nil
+}
+
+func (*chatMessagePaginationCaller) Format() string { return "json" }
+func (*chatMessagePaginationCaller) DryRun() bool   { return false }
+func (*chatMessagePaginationCaller) Fields() string { return "" }
+func (*chatMessagePaginationCaller) JQ() string     { return "" }
+
+func executeChatMessagePaginationCommand(t *testing.T, caller *chatMessagePaginationCaller, args ...string) (map[string]any, error) {
+	t.Helper()
+	oldDeps := deps
+	oldSleep := helperSleep
+	t.Cleanup(func() {
+		deps = oldDeps
+		helperSleep = oldSleep
+	})
+	InitDeps(caller)
+	out := &bytes.Buffer{}
+	deps.Out.w = out
+	deps.Out.errW = io.Discard
+	helperSleep = func(d time.Duration) {}
+
+	root := newChatCommand()
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.SetArgs(args)
+	err := root.ExecuteContext(context.Background())
+	if out.Len() == 0 {
+		return nil, err
+	}
+	var parsed map[string]any
+	if unmarshalErr := json.Unmarshal(out.Bytes(), &parsed); unmarshalErr != nil {
+		t.Fatalf("stdout JSON = %q, err = %v", out.String(), unmarshalErr)
+	}
+	return parsed, err
+}
+
+func TestChatMessagePaginationDefaultSinglePageUnchanged(t *testing.T) {
+	tests := []struct {
+		name   string
+		args   []string
+		server string
+		tool   string
+		want   map[string]any
+	}{
+		{
+			name:   "list-all",
+			args:   []string{"message", "list-all", "--start", "2026-08-01 00:00:00", "--end", "2026-08-02 00:00:00"},
+			server: "",
+			tool:   "search_messages_by_time_range",
+			want:   map[string]any{"startTime": "2026-08-01 00:00:00", "endTime": "2026-08-02 00:00:00", "limit": 50, "cursor": "0"},
+		},
+		{
+			name:   "list-by-sender",
+			args:   []string{"message", "list-by-sender", "--sender-user-id", "u1", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "",
+			tool:   "search_messages_by_sender",
+			want:   map[string]any{"senderUserId": "u1", "startTime": float64(1785513600000), "endTime": float64(1785600000000), "limit": 50, "cursor": "0"},
+		},
+		{
+			name:   "list-mentions",
+			args:   []string{"message", "list-mentions", "--group", "cid1", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "",
+			tool:   "search_at_me_message",
+			want:   map[string]any{"openConversationId": "cid1", "startTime": float64(1785513600000), "endTime": float64(1785600000000), "limit": 50, "cursor": "0"},
+		},
+		{
+			name:   "list-focused",
+			args:   []string{"message", "list-focused"},
+			server: "",
+			tool:   "list_special_focus_messages",
+			want:   map[string]any{"limit": 50},
+		},
+		{
+			name:   "search",
+			args:   []string{"message", "search", "--query", "发布", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "",
+			tool:   "search_messages_by_keyword",
+			want:   map[string]any{"keyword": "发布", "startTime": float64(1785513600000), "endTime": float64(1785600000000), "limit": 100, "cursor": "0"},
+		},
+		{
+			name:   "search-advanced",
+			args:   []string{"message", "search-advanced", "--query", "周报", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "im",
+			tool:   "search_messages",
+			want:   map[string]any{"keyword": "周报", "startTime": float64(1785513600000), "endTime": float64(1785600000000), "limit": 100, "cursor": "0"},
+		},
+		{
+			name:   "list-favorites",
+			args:   []string{"message", "list-favorites"},
+			server: "im",
+			tool:   "list_message_favorites",
+			want:   map[string]any{"cursor": int64(0), "size": "20"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{}
+			args := append([]string{}, tt.args...)
+			args = append(args, "--page-limit", "2", "--max-items", "1", "--page-delay", "0")
+			_, err := executeChatMessagePaginationCommand(t, caller, args...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(caller.calls) != 1 {
+				t.Fatalf("calls = %#v, want one fallback call", caller.calls)
+			}
+			got := caller.calls[0]
+			if got.server != tt.server || got.tool != tt.tool || !argsEqual(got.args, tt.want) {
+				t.Fatalf("call = %#v, want server=%s tool=%s args=%#v", got, tt.server, tt.tool, tt.want)
+			}
+		})
+	}
+}
+
+func TestChatMessagePaginationPageAllAggregatesSevenCommands(t *testing.T) {
+	tests := []struct {
+		name      string
+		args      []string
+		server    string
+		tool      string
+		itemPath  string
+		cursorOne any
+		cursorTwo any
+		pageOne   string
+		pageTwo   string
+	}{
+		{
+			name: "list-all", args: []string{"message", "list-all", "--start", "2026-08-01 00:00:00", "--end", "2026-08-02 00:00:00"},
+			server: "chat", tool: "search_messages_by_time_range", itemPath: "conversationMessagesList", cursorOne: "0", cursorTwo: "c2",
+			pageOne: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m1"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+			pageTwo: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m2"}]}],"hasMore":false,"nextCursor":""}}`,
+		},
+		{
+			name: "list-by-sender", args: []string{"message", "list-by-sender", "--sender-user-id", "u1", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "chat", tool: "search_messages_by_sender", itemPath: "conversationMessagesList", cursorOne: "0", cursorTwo: "c2",
+			pageOne: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"洄川","messages":[{"id":"m1"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+			pageTwo: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"洄川","messages":[{"id":"m2"}]}],"hasMore":false,"nextCursor":""}}`,
+		},
+		{
+			name: "list-mentions", args: []string{"message", "list-mentions", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "chat", tool: "search_at_me_message", itemPath: "conversationMessagesList", cursorOne: "0", cursorTwo: "c2",
+			pageOne: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m1"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+			pageTwo: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m2"}]}],"hasMore":false,"nextCursor":""}}`,
+		},
+		{
+			name: "list-focused", args: []string{"message", "list-focused"},
+			server: "chat", tool: "list_special_focus_messages", itemPath: "messages", cursorOne: nil, cursorTwo: int64(2),
+			pageOne: `{"result":{"messages":[{"id":"m1"}],"hasMore":true,"nextCursor":2}}`,
+			pageTwo: `{"result":{"messages":[{"id":"m2"}],"hasMore":false,"nextCursor":0}}`,
+		},
+		{
+			name: "search", args: []string{"message", "search", "--query", "发布", "--start", "2026-08-01T00:00:00+08:00", "--end", "2026-08-02T00:00:00+08:00"},
+			server: "chat", tool: "search_messages_by_keyword", itemPath: "conversationMessagesList", cursorOne: "0", cursorTwo: "c2",
+			pageOne: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m1"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+			pageTwo: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m2"}]}],"hasMore":false,"nextCursor":""}}`,
+		},
+		{
+			name: "search-advanced", args: []string{"message", "search-advanced", "--query", "周报"},
+			server: "im", tool: "search_messages", itemPath: "conversationMessagesList", cursorOne: "0", cursorTwo: "c2",
+			pageOne: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m1"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+			pageTwo: `{"result":{"conversationMessagesList":[{"openConversationId":"cid1","title":"群1","messages":[{"id":"m2"}]}],"hasMore":false,"nextCursor":""}}`,
+		},
+		{
+			name: "list-favorites", args: []string{"message", "list-favorites"},
+			server: "im", tool: "list_message_favorites", itemPath: "items", cursorOne: int64(0), cursorTwo: int64(20),
+			pageOne: `{"result":{"items":[{"id":"f1"}],"hasMore":true,"nextCursor":20}}`,
+			pageTwo: `{"result":{"items":[{"id":"f2"}],"hasMore":false,"nextCursor":0}}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessagePaginationCaller{steps: []scriptedToolStep{{text: tt.pageOne}, {text: tt.pageTwo}}}
+			args := append([]string{}, tt.args...)
+			args = append(args, "--page-all", "--page-delay", "0")
+			got, err := executeChatMessagePaginationCommand(t, caller, args...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			items := got["result"].(map[string]any)[tt.itemPath].([]any)
+			if tt.itemPath == "conversationMessagesList" {
+				messages := items[0].(map[string]any)["messages"].([]any)
+				if len(items) != 1 || len(messages) != 2 {
+					t.Fatalf("conversation items = %#v", items)
+				}
+			} else if len(items) != 2 {
+				t.Fatalf("items = %#v", items)
+			}
+			if len(caller.calls) != 2 {
+				t.Fatalf("calls = %#v, want two pages", caller.calls)
+			}
+			if caller.calls[0].server != tt.server || caller.calls[0].tool != tt.tool {
+				t.Fatalf("first call = %#v", caller.calls[0])
+			}
+			if !reflect.DeepEqual(caller.calls[0].args["cursor"], tt.cursorOne) {
+				t.Fatalf("first cursor = %#v, want %#v", caller.calls[0].args["cursor"], tt.cursorOne)
+			}
+			if !reflect.DeepEqual(caller.calls[1].args["cursor"], tt.cursorTwo) {
+				t.Fatalf("second cursor = %#v, want %#v", caller.calls[1].args["cursor"], tt.cursorTwo)
+			}
+			paging := got["paging"].(map[string]any)
+			if paging["pages"].(float64) != 2 || paging["total"].(float64) != 2 || paging["truncated"] != false {
+				t.Fatalf("paging = %#v", paging)
+			}
+		})
+	}
+}
+
+func argsEqual(got, want map[string]any) bool {
+	if len(got) != len(want) {
+		return false
+	}
+	for key, wantValue := range want {
+		gotValue, ok := got[key]
+		if !ok {
+			return false
+		}
+		switch w := wantValue.(type) {
+		case float64:
+			g, ok := gotValue.(int64)
+			if !ok || float64(g) != w {
+				return false
+			}
+		default:
+			if !reflect.DeepEqual(gotValue, wantValue) {
+				return false
+			}
+		}
+	}
+	return true
+}

internal/helpers/chat_message_search_test.go

@@ -16,6 +16,7 @@ package helpers
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"io"
 	"os"
 	"reflect"
@@ -23,8 +24,10 @@ import (
 	"testing"
 	"time"
 
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/agentproduct"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
 )
 
 type chatMessageSearchCall struct {
@@ -34,12 +37,41 @@ type chatMessageSearchCall struct {
 }
 
 type chatMessageSearchCaller struct {
-	calls []chatMessageSearchCall
+	calls           []chatMessageSearchCall
+	searchResponse  string
+	searchResponses []string
+	searchCalls     int
+	searchError     error
+	failPreflight   bool
+	preflightError  error
 }
 
 func (c *chatMessageSearchCaller) CallTool(_ context.Context, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
 	c.calls = append(c.calls, chatMessageSearchCall{productID: productID, toolName: toolName, args: args})
-	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{}`}}}, nil
+	text := `{}`
+	if toolName == "get_conversation_info" {
+		if c.preflightError != nil {
+			return nil, c.preflightError
+		}
+		if c.failPreflight {
+			return nil, errors.New("conversation not found")
+		}
+		text = `{"result":{"openConversationId":"` + args["openConversationId"].(string) + `"}}`
+	}
+	if toolName == "search_messages_by_keyword" || toolName == "search_messages" {
+		if c.searchError != nil {
+			c.searchCalls++
+			return nil, c.searchError
+		}
+		text = `{"result":{"messages":[],"hasMore":false}}`
+		if c.searchCalls < len(c.searchResponses) {
+			text = c.searchResponses[c.searchCalls]
+		} else if c.searchResponse != "" {
+			text = c.searchResponse
+		}
+		c.searchCalls++
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
 }
 
 func (*chatMessageSearchCaller) Format() string { return "json" }
@@ -72,6 +104,7 @@ func TestCrossPlatformCoverageChatMessageSearchUsesMCPContracts(t *testing.T) {
 		productID   string
 		toolName    string
 		wantToolArg map[string]any
+		preflight   []string
 	}{
 		{
 			name:      "keyword search",
@@ -79,13 +112,13 @@ func TestCrossPlatformCoverageChatMessageSearchUsesMCPContracts(t *testing.T) {
 			productID: "chat",
 			toolName:  "search_messages_by_keyword",
 			wantToolArg: map[string]any{
-				"keyword":            "categoryName",
-				"openConversationId": "cid-1",
-				"startTime":          startTime.UnixMilli(),
-				"endTime":            endTime.UnixMilli(),
-				"limit":              100,
-				"cursor":             "0",
+				"keyword":   "categoryName",
+				"startTime": startTime.UnixMilli(),
+				"endTime":   endTime.UnixMilli(),
+				"limit":     100,
+				"cursor":    "0",
 			},
+			preflight: []string{"cid-1"},
 		},
 		{
 			name:      "advanced search",
@@ -93,16 +126,16 @@ func TestCrossPlatformCoverageChatMessageSearchUsesMCPContracts(t *testing.T) {
 			productID: "im",
 			toolName:  "search_messages",
 			wantToolArg: map[string]any{
-				"keyword":             "categoryName",
-				"openConversationIds": []string{"cid-1", "cid-2"},
-				"messageType":         "text",
-				"onlyRobotMessages":   true,
-				"searchConvType":      "group",
-				"startTime":           startTime.UnixMilli(),
-				"endTime":             endTime.UnixMilli(),
-				"limit":               100,
-				"cursor":              "0",
+				"keyword":           "categoryName",
+				"messageType":       "text",
+				"onlyRobotMessages": true,
+				"searchConvType":    "group",
+				"startTime":         startTime.UnixMilli(),
+				"endTime":           endTime.UnixMilli(),
+				"limit":             100,
+				"cursor":            "0",
 			},
+			preflight: []string{"cid-1", "cid-2"},
 		},
 	}
 
@@ -116,14 +149,21 @@ func TestCrossPlatformCoverageChatMessageSearchUsesMCPContracts(t *testing.T) {
 			cmd := newChatCommand()
 			cmd.SilenceErrors = true
 			cmd.SilenceUsage = true
+			cmd.SetOut(io.Discard)
 			cmd.SetArgs(tt.args)
 			if err := cmd.Execute(); err != nil {
 				t.Fatalf("chat search returned error: %v", err)
 			}
-			if len(caller.calls) != 1 {
-				t.Fatalf("tool call count = %d, want 1", len(caller.calls))
+			if len(caller.calls) != len(tt.preflight)+1 {
+				t.Fatalf("tool calls = %#v", caller.calls)
 			}
-			call := caller.calls[0]
+			for index, conversationID := range tt.preflight {
+				call := caller.calls[index]
+				if call.productID != "chat" || call.toolName != "get_conversation_info" || call.args["openConversationId"] != conversationID {
+					t.Fatalf("preflight[%d] = %#v", index, call)
+				}
+			}
+			call := caller.calls[len(caller.calls)-1]
 			if call.productID != tt.productID || call.toolName != tt.toolName {
 				t.Fatalf("tool call = %s/%s, want %s/%s", call.productID, call.toolName, tt.productID, tt.toolName)
 			}
@@ -134,6 +174,507 @@ func TestCrossPlatformCoverageChatMessageSearchUsesMCPContracts(t *testing.T) {
 	}
 }
 
+func executeNativeScopedSearch(t *testing.T, caller *chatMessageSearchCaller, args ...string) (map[string]any, error) {
+	t.Helper()
+	previousDeps := deps
+	t.Cleanup(func() { deps = previousDeps })
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	cmd := newChatCommand()
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	var output strings.Builder
+	cmd.SetOut(&output)
+	cmd.SetArgs(args)
+	if err := cmd.Execute(); err != nil {
+		return nil, err
+	}
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(output.String()), &payload); err != nil {
+		return nil, err
+	}
+	return payload, nil
+}
+
+func TestNativeScopedSearchFiltersGlobalResultsForBothEntries(t *testing.T) {
+	start := "2026-07-09T00:00:00+08:00"
+	end := "2026-07-11T00:00:00+08:00"
+	for _, tt := range []struct {
+		name       string
+		args       []string
+		tool       string
+		scopeParam string
+	}{
+		{
+			name:       "keyword search",
+			args:       []string{"message", "search", "--query", "周报", "--group", "cid-target", "--start", start, "--end", end},
+			tool:       "search_messages_by_keyword",
+			scopeParam: "openConversationId",
+		},
+		{
+			name:       "advanced search",
+			args:       []string{"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target"},
+			tool:       "search_messages",
+			scopeParam: "openConversationIds",
+		},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			caller := &chatMessageSearchCaller{searchResponse: `{
+				"result": {
+					"conversationMessagesList": [
+						{"openConversationId":"cid-target","title":"目标群","messages":[{"openMessageId":"m-target","content":"目标"}]},
+						{"openConversationId":"cid-other","title":"其他群","messages":[{"openMessageId":"m-other","content":"越界"}]}
+					],
+					"hasMore": false
+				}
+			}`}
+			payload, err := executeNativeScopedSearch(t, caller, tt.args...)
+			if err != nil {
+				t.Fatal(err)
+			}
+			result, _ := payload["result"].(map[string]any)
+			groups, _ := result["conversationMessagesList"].([]any)
+			if len(groups) != 1 {
+				t.Fatalf("result = %#v", result)
+			}
+			group, _ := groups[0].(map[string]any)
+			if group["openConversationId"] != "cid-target" {
+				t.Fatalf("group = %#v", group)
+			}
+			scope, _ := payload["scope"].(map[string]any)
+			if scope["targetsValidated"] != true || scope["resultsWithinScope"] != true || scope["filterMode"] != "client" {
+				t.Fatalf("scope = %#v", scope)
+			}
+			searchCall := caller.calls[len(caller.calls)-1]
+			if searchCall.toolName != tt.tool {
+				t.Fatalf("search call = %#v", searchCall)
+			}
+			if _, exists := searchCall.args[tt.scopeParam]; exists {
+				t.Fatalf("global fallback unexpectedly forwarded %s: %#v", tt.scopeParam, searchCall.args)
+			}
+		})
+	}
+}
+
+func TestNativeScopedSearchInvalidCIDStopsBeforeSearch(t *testing.T) {
+	caller := &chatMessageSearchCaller{failPreflight: true}
+	_, err := executeNativeScopedSearch(t, caller,
+		"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-invalid")
+	if err == nil {
+		t.Fatal("invalid CID unexpectedly succeeded")
+	}
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Reason != "search_conversation_scope_invalid" {
+		t.Fatalf("error = %#v", err)
+	}
+	if len(caller.calls) != 1 || caller.calls[0].toolName != "get_conversation_info" {
+		t.Fatalf("calls = %#v", caller.calls)
+	}
+}
+
+func TestNativeScopedSearchPreservesPreflightAuthError(t *testing.T) {
+	want := &CLIError{Code: CodeAuthNotConfigured, Message: "当前未登录"}
+	caller := &chatMessageSearchCaller{preflightError: want}
+	_, err := executeNativeScopedSearch(t, caller,
+		"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+	if err == nil {
+		t.Fatal("auth failure unexpectedly succeeded")
+	}
+	var cliErr *CLIError
+	if !errors.As(err, &cliErr) || cliErr.Code != CodeAuthNotConfigured {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestCrossPlatformCoverageNativeScopedSearchPreservesAmbiguousMCPToolErrors(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		want *CLIError
+	}{
+		{
+			name: "rate limited",
+			want: &CLIError{
+				Code:    CodeMCPToolError,
+				Message: `{"success":false,"errorCode":"invalidRequest.rateLimited","errorMsg":"slow down"}`,
+			},
+		},
+		{
+			name: "permission denied",
+			want: &CLIError{
+				Code:    CodeMCPToolError,
+				Message: `{"success":false,"errorCode":"forbidden.noPermission","errorMsg":"permission denied"}`,
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			caller := &chatMessageSearchCaller{preflightError: test.want}
+			_, err := executeNativeScopedSearch(t, caller,
+				"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+			if err != test.want {
+				t.Fatalf("error = %#v, want original %#v", err, test.want)
+			}
+			if len(caller.calls) != 1 || caller.calls[0].toolName != "get_conversation_info" {
+				t.Fatalf("calls = %#v", caller.calls)
+			}
+		})
+	}
+}
+
+func TestNativeScopedSearchScansUntilTargetConversationAppears(t *testing.T) {
+	caller := &chatMessageSearchCaller{searchResponses: []string{
+		`{"result":{"conversationMessagesList":[{"openConversationId":"cid-other","messages":[{"openMessageId":"m-other"}]}],"hasMore":true,"nextCursor":"c2"}}`,
+		`{"result":{"conversationMessagesList":[{"openConversationId":"cid-target","messages":[{"openMessageId":"m-target"}]}],"hasMore":false}}`,
+	}}
+	payload, err := executeNativeScopedSearch(t, caller,
+		"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result, _ := payload["result"].(map[string]any)
+	if result["pagesFetched"] != float64(2) || result["complete"] != true {
+		t.Fatalf("result = %#v", result)
+	}
+	groups, _ := result["conversationMessagesList"].([]any)
+	if len(groups) != 1 {
+		t.Fatalf("groups = %#v", groups)
+	}
+	searchCalls := make([]chatMessageSearchCall, 0, 2)
+	for _, call := range caller.calls {
+		if call.toolName == "search_messages" {
+			searchCalls = append(searchCalls, call)
+		}
+	}
+	if len(searchCalls) != 2 || searchCalls[1].args["cursor"] != "c2" {
+		t.Fatalf("search calls = %#v", searchCalls)
+	}
+}
+
+func TestCrossPlatformCoverageNativeScopedSearchPageAllOptions(t *testing.T) {
+	t.Run("page limit preserves continuation", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponse: `{
+			"result": {
+				"conversationMessagesList": [
+					{"openConversationId":"cid-target","messages":[{"openMessageId":"m1"}]}
+				],
+				"hasMore": true,
+				"nextCursor": "c2"
+			}
+		}`}
+		payload, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target",
+			"--page-all", "--page-limit", "1", "--page-delay", "0")
+		if err != nil {
+			t.Fatal(err)
+		}
+		paging, _ := payload["paging"].(map[string]any)
+		if paging["pages"] != float64(1) || paging["total"] != float64(1) || paging["truncated"] != true {
+			t.Fatalf("paging = %#v", paging)
+		}
+		if caller.searchCalls != 1 {
+			t.Fatalf("search calls = %d, want 1", caller.searchCalls)
+		}
+	})
+
+	t.Run("max items truncates within filtered page", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponse: `{
+			"result": {
+				"conversationMessagesList": [
+					{"openConversationId":"cid-target","messages":[
+						{"openMessageId":"m1"},
+						{"openMessageId":"m2"}
+					]}
+				],
+				"hasMore": false
+			}
+		}`}
+		payload, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target",
+			"--page-all", "--max-items", "1", "--page-delay", "0")
+		if err != nil {
+			t.Fatal(err)
+		}
+		result, _ := payload["result"].(map[string]any)
+		groups, _ := result["conversationMessagesList"].([]any)
+		group, _ := groups[0].(map[string]any)
+		messages, _ := group["messages"].([]any)
+		if len(messages) != 1 {
+			t.Fatalf("messages = %#v", messages)
+		}
+		paging, _ := payload["paging"].(map[string]any)
+		if paging["total"] != float64(1) || paging["truncatedWithinPage"] != true || paging["resumeCursorReliable"] != false {
+			t.Fatalf("paging = %#v", paging)
+		}
+	})
+}
+
+func TestNativeScopedSearchMissingConversationIdentityFailsClosed(t *testing.T) {
+	caller := &chatMessageSearchCaller{searchResponse: `{"result":{"messages":[{"openMessageId":"m1"}],"hasMore":false}}`}
+	_, err := executeNativeScopedSearch(t, caller,
+		"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+	if err == nil {
+		t.Fatal("unverifiable scoped result unexpectedly succeeded")
+	}
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Reason != "search_conversation_scope_unverified" {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestNativeScopedSearchValidEmptyResultIsComplete(t *testing.T) {
+	caller := &chatMessageSearchCaller{searchResponse: `{"result":{"messages":[],"hasMore":false}}`}
+	payload, err := executeNativeScopedSearch(t, caller,
+		"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-empty")
+	if err != nil {
+		t.Fatal(err)
+	}
+	result, _ := payload["result"].(map[string]any)
+	if result["complete"] != true || result["hasMore"] != false {
+		t.Fatalf("result = %#v", result)
+	}
+	scope, _ := payload["scope"].(map[string]any)
+	if scope["targetsValidated"] != true || scope["sourceComplete"] != true {
+		t.Fatalf("scope = %#v", scope)
+	}
+}
+
+func TestCrossPlatformCoverageNativeScopedSearchFailureAndPaginationBranches(t *testing.T) {
+	t.Run("empty scope uses the native search call", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{}
+		previousDeps := deps
+		t.Cleanup(func() { deps = previousDeps })
+		InitDeps(caller)
+		deps.Out.w = io.Discard
+
+		cmd := &cobra.Command{Use: "search"}
+		err := runConversationScopedMessageSearch(
+			cmd,
+			"im",
+			"search_messages",
+			"openConversationIds",
+			map[string]any{"keyword": "周报"},
+			[]string{"", " "},
+		)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(caller.calls) != 1 || caller.calls[0].toolName != "search_messages" {
+			t.Fatalf("calls = %#v", caller.calls)
+		}
+	})
+
+	t.Run("invalid page options fail before preflight", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{}
+		previousDeps := deps
+		t.Cleanup(func() { deps = previousDeps })
+		InitDeps(caller)
+
+		cmd := &cobra.Command{Use: "search"}
+		AddPagedMCPFlags(cmd)
+		if err := cmd.Flags().Set("page-all", "true"); err != nil {
+			t.Fatal(err)
+		}
+		if err := cmd.Flags().Set("page-limit", "0"); err != nil {
+			t.Fatal(err)
+		}
+		err := runConversationScopedMessageSearch(
+			cmd,
+			"im",
+			"search_messages",
+			"openConversationIds",
+			map[string]any{"keyword": "周报"},
+			[]string{"cid-target"},
+		)
+		if err == nil || !strings.Contains(err.Error(), "--page-limit must be between 1 and 500") {
+			t.Fatalf("error = %v", err)
+		}
+		if len(caller.calls) != 0 {
+			t.Fatalf("invalid paging made calls: %#v", caller.calls)
+		}
+	})
+
+	t.Run("cancelled context interrupts page delay", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponse: `{
+			"result": {
+				"messages": [{"openMessageId":"m1","openConversationId":"cid-target"}],
+				"hasMore": true,
+				"nextCursor": "c2"
+			}
+		}`}
+		previousDeps := deps
+		t.Cleanup(func() { deps = previousDeps })
+		InitDeps(caller)
+		deps.Out.w = io.Discard
+
+		cmd := &cobra.Command{Use: "search"}
+		AddPagedMCPFlags(cmd)
+		if err := cmd.Flags().Set("page-all", "true"); err != nil {
+			t.Fatal(err)
+		}
+		if err := cmd.Flags().Set("page-delay", "60000"); err != nil {
+			t.Fatal(err)
+		}
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		cmd.SetContext(ctx)
+		err := runConversationScopedMessageSearch(
+			cmd,
+			"im",
+			"search_messages",
+			"openConversationIds",
+			map[string]any{"keyword": "周报", "limit": 100, "cursor": "0"},
+			[]string{"cid-target"},
+		)
+		if !errors.Is(err, context.Canceled) {
+			t.Fatalf("error = %v, want context canceled", err)
+		}
+		if caller.searchCalls != 1 {
+			t.Fatalf("search calls = %d, want 1", caller.searchCalls)
+		}
+	})
+
+	t.Run("lower search error", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchError: errors.New("search unavailable")}
+		_, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+		if err == nil {
+			t.Fatal("lower search error was ignored")
+		}
+	})
+
+	t.Run("stalled cursor fails closed", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponse: `{
+			"result": {
+				"messages": [{"openMessageId":"m1","openConversationId":"cid-target"}],
+				"hasMore": true
+			}
+		}`}
+		_, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+		var typed *apperrors.Error
+		if !errors.As(err, &typed) || typed.Reason != "search_conversation_scope_cursor_stalled" {
+			t.Fatalf("error = %#v", err)
+		}
+	})
+
+	t.Run("result limit preserves continuation", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponse: `{
+			"result": {
+				"messages": [{"openMessageId":"m1","openConversationId":"cid-target"}],
+				"hasMore": true,
+				"nextCursor": "c2"
+			}
+		}`}
+		payload, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target", "--limit", "1")
+		if err != nil {
+			t.Fatal(err)
+		}
+		result, _ := payload["result"].(map[string]any)
+		if result["complete"] != false || result["hasMore"] != true || result["nextCursor"] != "c2" {
+			t.Fatalf("result = %#v", result)
+		}
+	})
+
+	t.Run("duplicate message ids are removed across pages", func(t *testing.T) {
+		caller := &chatMessageSearchCaller{searchResponses: []string{
+			`{"result":{"messages":[{"openMessageId":"m1","openConversationId":"cid-target"}],"hasMore":true,"nextCursor":"c2"}}`,
+			`{"result":{"messages":[{"openMessageId":"m1","openConversationId":"cid-target"},{"openMessageId":"m2","openConversationId":"cid-target"}],"hasMore":false}}`,
+		}}
+		payload, err := executeNativeScopedSearch(t, caller,
+			"message", "search-advanced", "--query", "周报", "--conversation-ids", "cid-target")
+		if err != nil {
+			t.Fatal(err)
+		}
+		result, _ := payload["result"].(map[string]any)
+		groups, _ := result["conversationMessagesList"].([]any)
+		group, _ := groups[0].(map[string]any)
+		messages, _ := group["messages"].([]any)
+		if len(messages) != 2 {
+			t.Fatalf("deduplicated messages = %#v", messages)
+		}
+	})
+
+	if got := uniqueNonEmptyStrings([]string{" cid ", "", "cid"}); !reflect.DeepEqual(got, []string{"cid"}) {
+		t.Fatalf("uniqueNonEmptyStrings = %#v", got)
+	}
+	for _, test := range []struct {
+		value any
+		want  int
+	}{
+		{value: int64(7), want: 7},
+		{value: json.Number("8"), want: 8},
+		{value: float64(9), want: 9},
+		{value: int64(0), want: 11},
+	} {
+		if got := positiveSearchLimit(test.value, 11); got != test.want {
+			t.Errorf("positiveSearchLimit(%#v) = %d, want %d", test.value, got, test.want)
+		}
+	}
+	if cleanSearchCursor(nil) != "" || cleanSearchCursor(" null ") != "" || cleanSearchCursor(" c2 ") != "c2" {
+		t.Fatal("cleanSearchCursor did not normalize sentinel values")
+	}
+}
+
+func TestCrossPlatformCoverageNativeScopedSearchDryRunShowsCompositePlanWithoutCallingTools(t *testing.T) {
+	caller := &chatMessageSearchCaller{}
+	previousDeps := deps
+	t.Cleanup(func() { deps = previousDeps })
+	InitDeps(caller)
+	cmd := &cobra.Command{Use: "search"}
+	cmd.Flags().Bool("dry-run", true, "")
+	AddPagedMCPFlags(cmd)
+	for name, value := range map[string]string{
+		"page-all":   "true",
+		"page-limit": "7",
+		"max-items":  "9",
+		"page-delay": "11",
+	} {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	var output strings.Builder
+	cmd.SetOut(&output)
+	err := runConversationScopedMessageSearch(
+		cmd,
+		"im",
+		"search_messages",
+		"openConversationIds",
+		map[string]any{
+			"keyword":             "周报",
+			"openConversationIds": []string{"cid-target"},
+			"limit":               100,
+			"cursor":              "0",
+		},
+		[]string{"cid-target"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.calls) != 0 {
+		t.Fatalf("dry-run made calls: %#v", caller.calls)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal([]byte(output.String()), &payload); err != nil {
+		t.Fatal(err)
+	}
+	plan, _ := payload["plan"].([]any)
+	if payload["dry_run"] != true || payload["executed"] != false || len(plan) != 3 {
+		t.Fatalf("payload = %#v", payload)
+	}
+	searchStage, _ := plan[1].(map[string]any)
+	arguments, _ := searchStage["arguments"].(map[string]any)
+	if _, exists := arguments["openConversationIds"]; exists {
+		t.Fatalf("dry-run global search still carries scope: %#v", searchStage)
+	}
+	if searchStage["pageAll"] != true ||
+		searchStage["pageLimit"] != float64(7) ||
+		searchStage["maxItems"] != float64(9) ||
+		searchStage["pageDelay"] != float64(11) {
+		t.Fatalf("dry-run paging = %#v", searchStage)
+	}
+}
+
 type chatChangedContractCaller struct {
 	calls        []chatMessageSearchCall
 	resolveUsers bool
@@ -160,9 +701,12 @@ func executeChatChangedContract(t *testing.T, caller *chatChangedContractCaller,
 	InitDeps(caller)
 	deps.Out.w = io.Discard
 	cmd := newChatCommand()
+	if cmd.PersistentFlags().Lookup("yes") == nil {
+		cmd.PersistentFlags().Bool("yes", false, "skip confirmation")
+	}
 	cmd.SilenceErrors = true
 	cmd.SilenceUsage = true
-	cmd.SetArgs(args)
+	cmd.SetArgs(append(append([]string(nil), args...), "--yes"))
 	return cmd.Execute()
 }
 

internal/helpers/chat_safety_catalog_test.go

@@ -0,0 +1,62 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageChatCatalogSafetyMetadataIsExplicit(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	root.AddCommand(newChatCommand())
+
+	checked := 0
+	walkChatCatalogLeaves(root, func(cmd *cobra.Command) {
+		final, ok := contractfinal.RuntimeContractFinal(cmd)
+		if !ok || final.Identity == nil || final.Safety == nil {
+			return
+		}
+		if strings.TrimSpace(final.Identity.ProductID) != "chat" {
+			return
+		}
+		checked++
+		canonical := strings.TrimSpace(final.Identity.CanonicalPath)
+		safety := final.Safety
+		if safety.Effect == "" || safety.Risk == "" ||
+			safety.Confirmation == "" || safety.Idempotency == "" {
+			t.Fatalf("chat Catalog leaf %s has incomplete Safety: %+v", canonical, *safety)
+		}
+		if safety.Effect == "read" {
+			if safety.Risk != "low" ||
+				safety.Confirmation != "not_required" ||
+				safety.Idempotency != "idempotent" {
+				t.Fatalf("chat read Catalog leaf %s Safety = %+v, want read/low/not_required/idempotent",
+					canonical, *safety)
+			}
+		}
+	})
+	if checked == 0 {
+		t.Fatal("no chat Catalog leaves checked")
+	}
+}
+
+func walkChatCatalogLeaves(cmd *cobra.Command, fn func(*cobra.Command)) {
+	if cmd == nil {
+		return
+	}
+	if cmd.Runnable() && !cmd.HasSubCommands() {
+		fn(cmd)
+		return
+	}
+	for _, child := range cmd.Commands() {
+		if child.Name() == "help" {
+			continue
+		}
+		walkChatCatalogLeaves(child, fn)
+	}
+}