Merge pull request #1115

Merged by the dedicated Reviewer Router GitHub App for PR #1115.

.changes/command-typo-guidance.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Command typo guidance** — returns a validation error with up to three nearest command suggestions and the parent `--help` entry instead of printing the full command list.

.changes/download-host-allowlist-removal.md

@@ -0,0 +1,31 @@
+---
+category: Changed
+---
+
+- **Download host trust policy** — retires the static DingTalk/OSS download
+  host allowlist, the dial-time public-IP refusal, and the IP-literal
+  refusal from both the shared local download path (`drive +download`,
+  `drive +version-download`, doc/minutes artifact downloads) and the chat
+  message-resource path (`chat +messages-resource-download`,
+  `--download-resources`). Download URLs only require HTTPS without userinfo
+  and accept non-default HTTPS ports, because every dimension of a
+  dedicated-deployment storage endpoint — custom domain, port, and network
+  location — is decided by the customer deployment and cannot be enumerated
+  or configured client-side. Verified on a dedicated deployment whose
+  storage domain resolves to a customer-intranet address. Downloads align
+  with the official GUI client, which applies no client-side SSRF
+  interception: download URLs only ever come from authenticated service
+  responses (no command accepts a user-supplied URL), TLS hostname
+  verification pins the connection to the requested host, redirects are
+  re-validated per hop, and service credential headers are stripped once a
+  redirect leaves the original origin.
+- **Upload host trust unchanged** — upload target URLs (`drive +upload`,
+  minutes audio upload) keep the pre-existing public DingTalk/OSS trusted
+  host requirement through a dedicated upload validator, so removing the
+  download allowlist does not widen where local file bytes can be sent;
+  the validator also keeps the pre-existing default-port-only HTTPS rule
+  (DingTalk/OSS upload endpoints always serve on 443, so non-default ports
+  accepted for dedicated-deployment downloads stay anomalous for uploads).
+  Download credential headers are issued together with the download URL by
+  the same authenticated service response and follow it as-is on the first
+  request; redirects leaving the original host still strip them.

.changes/fork-pr-reviewer-router-identity.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Fork pull-request admission** — keeps the read-only Reviewer Router identity check fail-closed while allowing external contributors' CI to use the reviewed public App slug when GitHub withholds repository variables.

.changes/markdown-append-chunk-limit.md

@@ -0,0 +1,10 @@
+---
+category: Fixed
+---
+
+- **Markdown append chunking rewritten around safe split positions** — long markdown is now split so that every chunk is a complete, self-contained top-level block sequence, which is what `update_document mode=append` requires: the server inserts a brand new structure per call and cannot continue the previous one. Split points are chosen strictly by how much they change the rendered document — fully safe boundaries (blank lines, block starts that interrupt a paragraph) before boundaries that need repair (a table's rows now carry a re-emitted header and delimiter row; a fenced code block is closed and reopened with its original marker and info string) before boundaries that merely restructure (long paragraphs, list items) before a hard character cut. Within a tier the latest boundary in the window wins, since all chunks land in the same document. Every boundary that changes the rendered structure is reported in a new `degradations` field instead of being applied silently.
+- **Fixed markdown chunking dropping a newline** — the previous splitter rebuilt block text from lines and lost one `\n` whenever the content's last line began a heading, table or code fence, so `"para\n# Title"` was written as `"para# Title"` and the heading stopped being a heading. Roughly one in five randomly generated documents was affected. The new splitter slices by offset and never rebuilds text, making content preservation structural.
+- **Fixed oversized tables and code blocks being cut mid-cell and mid-fence** — the hard-split path never received the block type, so it cut at arbitrary character boundaries despite claiming to preserve table and code block integrity.
+- **Fixed readback verification comparing against content the server never receives** — `doc +create` / `doc +update` verified the readback against the raw input, so any repaired boundary (and, previously, any paragraph split) failed verification on large documents. Verification now compares against the document the chunk plan says the server should hold.
+- **Unified four markdown write paths onto one splitter** — `doc create` / `doc update`, `doc +create` / `doc +update` and `doc +checkpoint-update` now share `helpers.SplitMarkdownForAppend` and one limit constant (30000 runes), replacing two independent implementations plus one path that never chunked at all. `doc +checkpoint-update` accepts `@file` and stdin content, so oversized input was reachable there while the equivalent `doc +update` chunked. `doc +doc-append` takes `--text` from argv only and now rejects oversized input with a pointer to `doc +update` rather than sending one oversized call.
+- **`doc update --index` now fails closed when the content requires chunking** — each chunk creates an unpredictable number of blocks, so the insertion point for later chunks is unknowable; the flag was previously accepted and silently ignored.

.changes/remove-edu-college-vendor-extensions.md

@@ -0,0 +1,5 @@
+---
+category: Removed
+---
+
+- **Education and college vendor extensions removed** — removes `dws edu-contact`, `dws edu-group`, `dws edu-app`, `dws edu-familygroup`, and `dws college-contact` from the CLI, Schema, bundled Skills, and open-edition MCP endpoint registry. Future DWS packages no longer expose these five command surfaces.

.changes/report-entry-submit-require-recipient.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **report entry submit requires recipients** — `dws report entry submit`（及废弃别名 `dws report create`）的 `--to-user-ids` 从可选提升为必填：无接收人的日志提交在服务端仍返回成功，但日志对任何接收人都不可见。openAPI `create_report` 的 `toUserIds` 参数保持可选不动，规则仅在 dws CLI 侧收紧——Cobra required 拦截未传场景，RunE 内对空值/纯分隔符（如 `--to-user-ids ","`）同样 fail-closed 拒绝。修复 [#85724185](https://project.aone.alibaba-inc.com/v2/project/2170318/bug/85724185)。

.changes/reviewer-router-synchronous-merge.md

@@ -0,0 +1,5 @@
+---
+category: Fixed
+---
+
+- **Reviewer Router merge recovery** — retries exact App-owned merge intents through a SHA-bound synchronous merge after GitHub has enforced approval and nine GitHub Actions source-bound required checks.

.github/actionlint.yaml

@@ -4,3 +4,13 @@ paths:
       # GitHub Actions added concurrency.queue in 2026. actionlint v1.7.12's
       # bundled workflow schema has not caught up with the platform syntax.
       - 'unexpected key "queue" for "concurrency" section'
+  .github/workflows/coverage-baseline-promotion.yml:
+    ignore:
+      # Serialize every acknowledgement for one Formula target without
+      # allowing Actions' default single-pending replacement to orphan a run.
+      - 'unexpected key "queue" for "concurrency" section'
+  .github/workflows/coverage-baseline-repair.yml:
+    ignore:
+      # Keep the closed-event dispatcher and its exact-SHA producer queued for
+      # the same target instead of replacing either half of the repair chain.
+      - 'unexpected key "queue" for "concurrency" section'

.github/workflows/ci.yml

@@ -5,12 +5,17 @@ on:
     branches:
       - main
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, edited, auto_merge_enabled, auto_merge_disabled]
 
 permissions:
   contents: read
 
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  # Keep only the latest revision of a pull request: a stale run must not
+  # compete with its replacement for hosted runners. A replacement that sees
+  # a cold baseline cache recomputes it authoritatively. Protected-main pushes
+  # remain keyed by exact SHA so every potential merge base has a producer.
+  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || format('push-{0}', github.sha) }}
   cancel-in-progress: true
 
 jobs:
@@ -837,7 +842,9 @@ jobs:
     if: ${{ always() && needs.lint.result == 'success' }}
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    permissions: {}
+    permissions:
+      contents: read
+      pull-requests: read
     steps:
       - name: Verify test shards
         env:
@@ -916,6 +923,296 @@ jobs:
           done
           test "$failed" -eq 0
 
+      # Null and non-built-in merge identities emit either the protected-main
+      # push or the trusted pull_request_target closed repair. The built-in
+      # Actions identity is the exceptional unsafe path, so its own token must
+      # prove that main-merge-writers never lets it update main.
+      - name: Verify auto-merge identity
+        if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          REVIEWER_ROUTER_APP_SLUG: ${{ vars.REVIEWER_ROUTER_APP_SLUG }}
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const pullNumber = context.payload.pull_request.number;
+            const eventHeadSha = context.payload.pull_request.head.sha;
+            const eventBaseSha = context.payload.pull_request.base.sha;
+            const configuredAppSlug = process.env.REVIEWER_ROUTER_APP_SLUG?.trim();
+            const reviewedForkAppSlug = 'dingtalk-dws-reviewer-router';
+            const pullHeadRepository =
+              context.payload.pull_request.head.repo.full_name?.toLowerCase();
+            const baseRepository = `${owner}/${repo}`.toLowerCase();
+            const isForkPull =
+              Boolean(pullHeadRepository) && pullHeadRepository !== baseRepository;
+            const appSlug =
+              configuredAppSlug || (isForkPull ? reviewedForkAppSlug : '');
+            if (
+              !appSlug ||
+              appSlug !== appSlug.toLowerCase() ||
+              appSlug === 'github-actions'
+            ) {
+              core.setFailed(
+                'Reviewer Router App slug repository variable is missing or unsafe.',
+              );
+              return;
+            }
+            if (!configuredAppSlug) {
+              core.info(
+                `Fork pull request cannot read the repository App slug variable; using the reviewed public slug ${reviewedForkAppSlug}.`,
+              );
+            }
+            const expectedAppOwner = `${appSlug}[bot]`;
+            const writerRulesetName = 'main-merge-writers';
+            const skipWorkflowPattern =
+              /\[(?:skip ci|ci skip|no ci|skip actions|actions skip)\]|\bskip-checks\s*:\s*true\b/i;
+            const {data: repository} = await github.rest.repos.get({owner, repo});
+            function classifyMergeDefaults(repository) {
+              if (
+                repository === null ||
+                typeof repository !== 'object' ||
+                Array.isArray(repository)
+              ) {
+                return 'invalid';
+              }
+              const hasTitle = Object.prototype.hasOwnProperty.call(
+                repository,
+                'merge_commit_title',
+              );
+              const hasMessage = Object.prototype.hasOwnProperty.call(
+                repository,
+                'merge_commit_message',
+              );
+              if (!hasTitle && !hasMessage) {
+                return 'omitted';
+              }
+              if (!hasTitle || !hasMessage) {
+                return 'invalid';
+              }
+              if (
+                repository.merge_commit_title === 'MERGE_MESSAGE' &&
+                ['PR_TITLE', 'BLANK'].includes(repository.merge_commit_message)
+              ) {
+                return 'reviewed';
+              }
+              return 'invalid';
+            }
+            const mergeDefaultsProjection = classifyMergeDefaults(repository);
+            if (mergeDefaultsProjection === 'invalid') {
+              core.setFailed(
+                'Repository merge-message defaults are malformed or changed from their reviewed values.',
+              );
+              return;
+            }
+            if (mergeDefaultsProjection === 'omitted') {
+              core.info(
+                'Read-only CI cannot observe repository merge-message defaults; exact validation is delegated to the dedicated App.',
+              );
+            }
+
+            const appliedRules = await github.paginate(
+              'GET /repos/{owner}/{repo}/rules/branches/{branch}',
+              {owner, repo, branch: 'main', per_page: 100},
+            );
+            const repositorySource = `${owner}/${repo}`.toLowerCase();
+            const applicableRulesetIDs = [
+              ...new Set(
+                appliedRules
+                  .filter(rule =>
+                    rule.ruleset_source_type === 'Repository' &&
+                    rule.ruleset_source?.toLowerCase() === repositorySource &&
+                    Number.isSafeInteger(Number(rule.ruleset_id)) &&
+                    Number(rule.ruleset_id) > 0,
+                  )
+                  .map(rule => Number(rule.ruleset_id)),
+              ),
+            ];
+            const activeMainRulesets = [];
+            for (const rulesetID of applicableRulesetIDs) {
+              const {data: ruleset} = await github.request(
+                'GET /repos/{owner}/{repo}/rulesets/{ruleset_id}',
+                {owner, repo, ruleset_id: rulesetID},
+              );
+              if (
+                ruleset.enforcement !== 'active' ||
+                ruleset.target !== 'branch' ||
+                ruleset.source_type !== 'Repository' ||
+                ruleset.source?.toLowerCase() !== repositorySource
+              ) {
+                core.setFailed(
+                  `Applicable repository ruleset ${ruleset.name || rulesetID} is not an active branch ruleset owned by this repository.`,
+                );
+                return;
+              }
+              activeMainRulesets.push(ruleset);
+            }
+
+            const writerRulesets = activeMainRulesets.filter(
+              ruleset => ruleset.name === writerRulesetName,
+            );
+            if (writerRulesets.length !== 1) {
+              core.setFailed(
+                `Expected exactly one active ${writerRulesetName} ruleset on main; found ${writerRulesets.length}.`,
+              );
+              return;
+            }
+            const writerRuleset = writerRulesets[0];
+            const writerIncludes = writerRuleset.conditions?.ref_name?.include || [];
+            const writerExcludes = writerRuleset.conditions?.ref_name?.exclude || [];
+            // GitHub's read projection omits the entire parameters property
+            // when this exception is disabled. Accept only that exact omission
+            // or a one-field object containing exact false.
+            function isStrictUpdateRule(rule) {
+              if (rule?.type !== 'update') {
+                return false;
+              }
+              if (!Object.prototype.hasOwnProperty.call(rule, 'parameters')) {
+                return true;
+              }
+              const parameters = rule.parameters;
+              if (
+                parameters === null ||
+                typeof parameters !== 'object' ||
+                Array.isArray(parameters)
+              ) {
+                return false;
+              }
+              const parameterKeys = Object.keys(parameters);
+              return (
+                parameterKeys.length === 1 &&
+                parameterKeys[0] === 'update_allows_fetch_and_merge' &&
+                parameters.update_allows_fetch_and_merge === false
+              );
+            }
+            function isStrictGraphQLUpdateRule(restRuleset, graphRuleset) {
+              const restRulesetID = Number(restRuleset?.id);
+              const graphRulesetID = Number(graphRuleset?.databaseId);
+              const graphRules = graphRuleset?.rules;
+              const graphRule = graphRules?.nodes?.[0];
+              return (
+                Number.isSafeInteger(restRulesetID) &&
+                restRulesetID > 0 &&
+                graphRulesetID === restRulesetID &&
+                graphRuleset.name === restRuleset.name &&
+                graphRuleset.enforcement === 'ACTIVE' &&
+                graphRuleset.target === 'BRANCH' &&
+                graphRules?.totalCount === 1 &&
+                graphRules.nodes?.length === 1 &&
+                graphRule?.type === 'UPDATE' &&
+                graphRule.parameters?.__typename === 'UpdateParameters' &&
+                graphRule.parameters.updateAllowsFetchAndMerge === false
+              );
+            }
+            if (
+              writerIncludes.length !== 1 ||
+              writerIncludes[0] !== 'refs/heads/main' ||
+              writerExcludes.length !== 0 ||
+              typeof writerRuleset.node_id !== 'string' ||
+              !writerRuleset.node_id ||
+              writerRuleset.rules?.length !== 1 ||
+              !isStrictUpdateRule(writerRuleset.rules[0]) ||
+              writerRuleset.current_user_can_bypass !== 'never'
+            ) {
+              core.setFailed(
+                `${writerRulesetName} must target only refs/heads/main, contain only the strict update rule, and deny this built-in Actions identity any bypass.`,
+              );
+              return;
+            }
+            const {node: graphWriterRuleset} = await github.graphql(
+              `query ReviewerRouterWriterRule($rulesetID: ID!) {
+                node(id: $rulesetID) {
+                  ... on RepositoryRuleset {
+                    databaseId
+                    name
+                    enforcement
+                    target
+                    rules(first: 2) {
+                      totalCount
+                      nodes {
+                        type
+                        parameters {
+                          __typename
+                          ... on UpdateParameters {
+                            updateAllowsFetchAndMerge
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }`,
+              {rulesetID: writerRuleset.node_id},
+            );
+            if (!isStrictGraphQLUpdateRule(writerRuleset, graphWriterRuleset)) {
+              core.setFailed(
+                `${writerRulesetName} must expose one strict UPDATE rule with updateAllowsFetchAndMerge=false through GraphQL.`,
+              );
+              return;
+            }
+
+            const maxAttempts = 6;
+            for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+              const {data: currentPull} = await github.rest.pulls.get({
+                owner,
+                repo,
+                pull_number: pullNumber,
+              });
+              if (
+                currentPull.head.sha !== eventHeadSha ||
+                currentPull.base.sha !== eventBaseSha ||
+                currentPull.state !== 'open' ||
+                currentPull.draft ||
+                currentPull.base.ref !== 'main'
+              ) {
+                core.setFailed(
+                  `PR #${pullNumber} state or revision changed before the Test aggregate verified auto-merge identity.`,
+                );
+                return;
+              }
+              const mergeTexts = [
+                currentPull.title,
+                currentPull.auto_merge?.commit_title,
+                currentPull.auto_merge?.commit_message,
+              ].filter(value => typeof value === 'string');
+              if (mergeTexts.some(value => skipWorkflowPattern.test(value))) {
+                core.setFailed(
+                  `PR #${pullNumber} merge metadata contains a GitHub workflow-skip directive.`,
+                );
+                return;
+              }
+              if (!currentPull.auto_merge) {
+                core.info(
+                  `PR #${pullNumber} has no auto-merge request; protected-main push or closed-event repair remains authoritative.`,
+                );
+                return;
+              }
+              const enabledBy = currentPull.auto_merge.enabled_by?.login?.toLowerCase();
+              const safeCommitHeadline = `Merge pull request #${pullNumber}`;
+              const safeCommitBody =
+                `Merged by the dedicated Reviewer Router GitHub App for PR #${pullNumber}.`;
+              if (
+                enabledBy === expectedAppOwner &&
+                currentPull.auto_merge.commit_title === safeCommitHeadline &&
+                currentPull.auto_merge.commit_message === safeCommitBody
+              ) {
+                core.info(
+                  `PR #${pullNumber} auto-merge is owned by the reviewed ${expectedAppOwner} identity with fixed metadata.`,
+                );
+                return;
+              }
+              if (attempt < maxAttempts) {
+                core.info(
+                  `PR #${pullNumber} auto-merge owner or metadata is not the reviewed App value; waiting for Reviewer Router takeover (${attempt}/${maxAttempts}).`,
+                );
+                await new Promise(resolve => setTimeout(resolve, 5000));
+                continue;
+              }
+              core.setFailed(
+                `PR #${pullNumber} auto-merge must be null or owned by ${expectedAppOwner} with the reviewed fixed metadata.`,
+              );
+            }
+
   test-darwin:
     name: Test (macOS auth/keychain)
     needs: lint
@@ -1246,7 +1543,7 @@ jobs:
     needs: lint
     if: ${{ needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' }}
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
@@ -1381,6 +1678,143 @@ jobs:
           path: coverage-base.txt
           retention-days: 1
 
+  # Documentation and release-seal pushes do not change executable coverage,
+  # but their new main SHA is still a future PR merge base. Promote only an
+  # exact predecessor cache after independently proving the whole push changed
+  # metadata paths; fall back to a full authoritative profile on a cold chain.
+  coverage-main-metadata:
+    name: Coverage (main metadata cache)
+    needs: lint
+    if: ${{ github.event_name == 'push' && (needs.lint.outputs.changelog_only == 'true' || needs.lint.outputs.docs_only == 'true') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Check out exact metadata-only main revision
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.sha }}
+
+      - name: Set up Go
+        id: setup-go-metadata
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Verify metadata-only main successor
+        shell: bash
+        env:
+          PUSH_BEFORE_SHA: ${{ github.event.before }}
+          PUSH_AFTER_SHA: ${{ github.event.after }}
+        run: |
+          set -euo pipefail
+          full_commit='^[0-9a-f]{40}$'
+          [[ "$PUSH_BEFORE_SHA" =~ $full_commit ]]
+          [[ "$PUSH_AFTER_SHA" =~ $full_commit ]]
+          test "$PUSH_BEFORE_SHA" != 0000000000000000000000000000000000000000
+          test "$PUSH_AFTER_SHA" = "$GITHUB_SHA"
+          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
+          git rev-parse --verify "${PUSH_BEFORE_SHA}^{commit}" >/dev/null
+          git merge-base --is-ancestor "$PUSH_BEFORE_SHA" "$PUSH_AFTER_SHA"
+
+          changed_count=0
+          while IFS= read -r -d '' path; do
+            changed_count=$((changed_count + 1))
+            case "$path" in
+              CHANGELOG.md|README.md|README_zh.md|CONTRIBUTING.md|SECURITY.md|CODE_OF_CONDUCT.md|LICENSE|NOTICE|.github/PULL_REQUEST_TEMPLATE.md|.github/ISSUE_TEMPLATE/*|docs/*)
+                ;;
+              .changes/*)
+                if [[ "$path" =~ ^\.changes/[a-z0-9][a-z0-9._-]*\.md$ ]] ||
+                   [[ "$path" =~ ^\.changes/released/[0-9]+\.[0-9]+\.[0-9]+(-beta\.[1-9][0-9]*)?/[a-z0-9][a-z0-9._-]*\.md$ ]]; then
+                  continue
+                fi
+                echo "Refusing coverage-cache promotion for unreviewed change-fragment path: $path" >&2
+                exit 1
+                ;;
+              *)
+                echo "Refusing coverage-cache promotion for executable path: $path" >&2
+                exit 1
+                ;;
+            esac
+          done < <(git diff --name-only --no-renames -z "$PUSH_BEFORE_SHA" "$PUSH_AFTER_SHA")
+          test "$changed_count" -gt 0
+          echo "COVERAGE_SOURCE_REF=$PUSH_BEFORE_SHA" >> "$GITHUB_ENV"
+
+      - name: Restore existing current-SHA coverage profile
+        id: metadata-current-cache
+        uses: actions/cache/restore@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go-metadata.outputs.go-version }}
+
+      - name: Validate existing current-SHA coverage profile
+        if: steps.metadata-current-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Restore exact predecessor coverage profile
+        id: metadata-source-cache
+        if: steps.metadata-current-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ env.COVERAGE_SOURCE_REF }}-go${{ steps.setup-go-metadata.outputs.go-version }}
+
+      - name: Validate promoted predecessor coverage profile
+        if: steps.metadata-current-cache.outputs.cache-hit != 'true' && steps.metadata-source-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Install archive tooling for cold metadata baseline
+        if: steps.metadata-current-cache.outputs.cache-hit != 'true' && steps.metadata-source-cache.outputs.cache-hit != 'true'
+        run: |
+          if command -v zip >/dev/null && command -v unzip >/dev/null; then
+            echo "zip and unzip are already available"
+          else
+            sudo apt-get update
+            sudo apt-get install -y zip unzip
+          fi
+
+      - name: Recompute cold metadata baseline
+        if: steps.metadata-current-cache.outputs.cache-hit != 'true' && steps.metadata-source-cache.outputs.cache-hit != 'true'
+        env:
+          DWS_PACKAGE_VERSION: 0.0.0-test
+        run: |
+          set -euo pipefail
+          go test -count=1 -p 1 \
+            -coverprofile=coverage-cache.txt \
+            -covermode=atomic \
+            ./ ./cmd/... ./internal/... ./skills/...
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Save metadata main SHA coverage profile
+        if: steps.metadata-current-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go-metadata.outputs.go-version }}
+
+      # actions/cache/save reports upload failures as warnings. Convert an
+      # absent exact target key into a hard producer failure.
+      - name: Verify metadata main SHA coverage cache exists
+        id: metadata-target-cache-verification
+        uses: actions/cache/restore@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go-metadata.outputs.go-version }}
+          lookup-only: true
+          fail-on-cache-miss: true
+
+      - name: Require exact metadata main SHA coverage cache
+        env:
+          EXACT_CACHE_HIT: ${{ steps.metadata-target-cache-verification.outputs.cache-hit }}
+        run: test "$EXACT_CACHE_HIT" = true
+
   coverage:
     name: Coverage
     needs:
@@ -1389,6 +1823,7 @@ jobs:
       - coverage-current-full
       - coverage-supporting
       - coverage-baseline
+      - coverage-main-metadata
       - coverage-darwin
       - coverage-windows
     if: ${{ always() && needs.lint.result == 'success' }}
@@ -1405,6 +1840,7 @@ jobs:
           CURRENT_FULL_RESULT: ${{ needs.coverage-current-full.result }}
           SUPPORTING_RESULT: ${{ needs.coverage-supporting.result }}
           BASELINE_RESULT: ${{ needs.coverage-baseline.result }}
+          MAIN_METADATA_RESULT: ${{ needs.coverage-main-metadata.result }}
           DARWIN_RESULT: ${{ needs.coverage-darwin.result }}
           WINDOWS_RESULT: ${{ needs.coverage-windows.result }}
         run: |
@@ -1413,10 +1849,14 @@ jobs:
           current_full_expected=skipped
           supporting_expected=skipped
           baseline_expected=success
+          main_metadata_expected=skipped
           native_expected=skipped
           if [ "$CHANGELOG_ONLY" = true ] || [ "$DOCS_ONLY" = true ]; then
             current_expected=skipped
             baseline_expected=skipped
+            if [ "$GITHUB_EVENT_NAME" = push ]; then
+              main_metadata_expected=success
+            fi
           elif [ "$FULL_SUITE" = true ]; then
             current_expected=skipped
             current_full_expected=success
@@ -1432,7 +1872,8 @@ jobs:
             "current:$CURRENT_RESULT:$current_expected" \
             "current shards:$CURRENT_FULL_RESULT:$current_full_expected" \
             "supporting:$SUPPORTING_RESULT:$supporting_expected" \
-            "baseline:$BASELINE_RESULT:$baseline_expected"
+            "baseline:$BASELINE_RESULT:$baseline_expected" \
+            "main metadata cache:$MAIN_METADATA_RESULT:$main_metadata_expected"
           do
             name="${profile%%:*}"
             remainder="${profile#*:}"
@@ -1572,6 +2013,22 @@ jobs:
           path: coverage-cache.txt
           key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}
 
+      - name: Verify push coverage cache exists
+        id: push-cache-verification
+        if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true'
+        uses: actions/cache/restore@v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ github.sha }}-go${{ steps.setup-go.outputs.go-version }}
+          lookup-only: true
+          fail-on-cache-miss: true
+
+      - name: Require exact push coverage cache
+        if: github.event_name == 'push' && needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true' && needs.lint.outputs.full_suite == 'true'
+        env:
+          EXACT_CACHE_HIT: ${{ steps.push-cache-verification.outputs.cache-hit }}
+        run: test "$EXACT_CACHE_HIT" = true
+
       - name: Generate coverage report
         if: needs.lint.outputs.changelog_only != 'true' && needs.lint.outputs.docs_only != 'true'
         run: |

.github/workflows/coverage-baseline-promotion.yml

@@ -0,0 +1,322 @@
+name: Coverage Baseline Promotion
+
+run-name: Promote coverage baseline for ${{ github.event.client_payload.target_sha }}
+
+on:
+  repository_dispatch:
+    types: [coverage-baseline-promote]
+
+# repository_dispatch loads this workflow from the protected default branch.
+# The requested target is treated as untrusted input until the validation step
+# proves it is an exact Formula-only successor already contained in main.
+permissions:
+  checks: write
+  contents: read
+
+concurrency:
+  group: coverage-baseline-promotion-${{ github.event.client_payload.target_sha }}
+  cancel-in-progress: false
+  queue: max
+
+jobs:
+  promote:
+    if: github.repository == 'DingTalk-Real-AI/dingtalk-workspace-cli'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Validate Formula-only main target
+        id: validate-target
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const targetSha = context.payload.client_payload?.target_sha;
+            const sourceRunId = context.payload.client_payload?.source_run_id;
+            const checkRunId = Number(context.payload.client_payload?.check_run_id);
+            if (!/^[0-9a-f]{40}$/.test(targetSha || '')) {
+              throw new Error('coverage-baseline-promote requires one full target_sha');
+            }
+            if (!/^[1-9][0-9]*$/.test(sourceRunId || '')) {
+              throw new Error('coverage-baseline-promote requires one source_run_id');
+            }
+            if (!Number.isSafeInteger(checkRunId) || checkRunId <= 0) {
+              throw new Error('coverage-baseline-promote requires one safe check_run_id');
+            }
+
+            // Bind the finalizer before any target or cache validation. A
+            // later failure must complete the release-created acknowledgement
+            // instead of leaving Release to poll a permanently queued check.
+            const promotionExternalId = `release-${sourceRunId}-${targetSha}`;
+            const {data: promotionCheck} = await github.rest.checks.get({
+              owner,
+              repo,
+              check_run_id: checkRunId,
+            });
+            if (
+              promotionCheck.id !== checkRunId ||
+              promotionCheck.head_sha !== targetSha ||
+              promotionCheck.name !== 'Coverage Baseline Cache' ||
+              promotionCheck.external_id !== promotionExternalId ||
+              promotionCheck.app?.slug !== 'github-actions' ||
+              promotionCheck.status !== 'queued' ||
+              promotionCheck.conclusion !== null
+            ) {
+              throw new Error('coverage baseline acknowledgement has an invalid identity');
+            }
+            core.setOutput('target_sha', targetSha);
+            core.setOutput('check_run_id', String(checkRunId));
+            core.setOutput('check_external_id', promotionExternalId);
+
+            const {data: targetCommit} = await github.rest.repos.getCommit({
+              owner,
+              repo,
+              ref: targetSha,
+              per_page: 100,
+            });
+            const files = targetCommit.files || [];
+            const message = targetCommit.commit.message;
+            const formulaPath = files[0]?.filename;
+            const stableFormula =
+              formulaPath === 'Formula/dingtalk-workspace-cli.rb' &&
+              /^chore: update formula for v[0-9]+\.[0-9]+\.[0-9]+ \[skip ci\]$/.test(message);
+            const betaFormula =
+              formulaPath === 'Formula/dingtalk-workspace-cli-beta.rb' &&
+              /^chore: update beta formula for v[0-9]+\.[0-9]+\.[0-9]+-beta\.[1-9][0-9]* \[skip ci\]$/.test(message);
+            if (
+              targetCommit.sha !== targetSha ||
+              targetCommit.parents.length !== 1 ||
+              targetCommit.author?.login !== 'github-actions[bot]' ||
+              targetCommit.committer?.login !== 'github-actions[bot]' ||
+              files.length !== 1 ||
+              !['added', 'modified'].includes(files[0].status) ||
+              (!stableFormula && !betaFormula)
+            ) {
+              throw new Error(
+                `${targetSha} is not an exact release-produced Formula-only commit`,
+              );
+            }
+
+            const parentSha = targetCommit.parents[0].sha;
+            const requiredContexts = [
+              'Lint',
+              'Test',
+              'Coverage',
+              'Policy',
+              'Edition',
+              'Interface Integrity',
+              'AI Behavior',
+              'CLI Smoke',
+              'Mock MCP',
+            ];
+            async function requireSuccessfulAdmission(ref, label) {
+              for (let attempt = 1; attempt <= 6; attempt += 1) {
+                const runs = await github.paginate(github.rest.checks.listForRef, {
+                  owner,
+                  repo,
+                  ref,
+                  filter: 'latest',
+                  per_page: 100,
+                });
+                const latestByName = new Map();
+                for (const run of runs) {
+                  if (
+                    run.head_sha !== ref ||
+                    run.app?.slug !== 'github-actions' ||
+                    !requiredContexts.includes(run.name)
+                  ) {
+                    continue;
+                  }
+                  const current = latestByName.get(run.name);
+                  if (!current || run.id > current.id) {
+                    latestByName.set(run.name, run);
+                  }
+                }
+                const invalid = requiredContexts.filter((name) => {
+                  const run = latestByName.get(name);
+                  return !run || run.conclusion !== 'success';
+                });
+                if (invalid.length === 0) {
+                  return;
+                }
+                if (attempt < 6) {
+                  await new Promise(resolve => setTimeout(resolve, 5000));
+                  continue;
+                }
+                throw new Error(
+                  `${label} ${ref} lacks successful Code Admission contexts: ${invalid.join(', ')}`,
+                );
+              }
+            }
+            await requireSuccessfulAdmission(parentSha, 'Formula parent');
+            await requireSuccessfulAdmission(targetSha, 'Formula target');
+
+            const {data: branch} = await github.rest.repos.getBranch({
+              owner,
+              repo,
+              branch: context.payload.repository.default_branch,
+            });
+            const {data: containment} =
+              await github.rest.repos.compareCommitsWithBasehead({
+                owner,
+                repo,
+                basehead: `${targetSha}...${branch.commit.sha}`,
+              });
+            if (!['ahead', 'identical'].includes(containment.status)) {
+              throw new Error(`${targetSha} is not contained in the protected default branch`);
+            }
+
+            core.setOutput('parent_sha', parentSha);
+            core.setOutput('formula_path', formulaPath);
+
+      - name: Mark Formula cache promotion in progress
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            await github.rest.checks.update({
+              ...context.repo,
+              check_run_id: Number('${{ steps.validate-target.outputs.check_run_id }}'),
+              status: 'in_progress',
+              started_at: new Date().toISOString(),
+              output: {
+                title: 'Producing exact-SHA coverage baseline',
+                summary: 'The trusted default-branch workflow is validating or producing the main-scoped cache.',
+              },
+            });
+
+      - name: Check out validated Formula-only target
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ steps.validate-target.outputs.target_sha }}
+
+      - name: Verify checked-out Formula-only identity
+        shell: bash
+        env:
+          TARGET_SHA: ${{ steps.validate-target.outputs.target_sha }}
+          PARENT_SHA: ${{ steps.validate-target.outputs.parent_sha }}
+          FORMULA_PATH: ${{ steps.validate-target.outputs.formula_path }}
+        run: |
+          set -euo pipefail
+          test "$(git rev-parse HEAD)" = "$TARGET_SHA"
+          test "$(git rev-parse HEAD^)" = "$PARENT_SHA"
+          test "$(git diff --name-only --no-renames "$PARENT_SHA" "$TARGET_SHA")" = "$FORMULA_PATH"
+
+      - name: Set up Go
+        id: setup-go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go.mod
+
+      - name: Restore existing target coverage profile
+        id: target-cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.validate-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+
+      - name: Validate existing target coverage profile
+        if: steps.target-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Restore exact Formula parent coverage profile
+        id: parent-cache
+        if: steps.target-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.validate-target.outputs.parent_sha }}-go${{ steps.setup-go.outputs.go-version }}
+
+      - name: Validate promoted Formula parent profile
+        if: steps.target-cache.outputs.cache-hit != 'true' && steps.parent-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Install archive tooling for cold Formula baseline
+        if: steps.target-cache.outputs.cache-hit != 'true' && steps.parent-cache.outputs.cache-hit != 'true'
+        run: |
+          if command -v zip >/dev/null && command -v unzip >/dev/null; then
+            echo "zip and unzip are already available"
+          else
+            sudo apt-get update
+            sudo apt-get install -y zip unzip
+          fi
+
+      - name: Recompute cold Formula baseline
+        if: steps.target-cache.outputs.cache-hit != 'true' && steps.parent-cache.outputs.cache-hit != 'true'
+        env:
+          DWS_PACKAGE_VERSION: 0.0.0-test
+        run: |
+          set -euo pipefail
+          go test -count=1 -p 1 \
+            -coverprofile=coverage-cache.txt \
+            -covermode=atomic \
+            ./ ./cmd/... ./internal/... ./skills/...
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Save Formula main SHA coverage profile
+        if: steps.target-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.validate-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+
+      - name: Verify Formula main SHA coverage cache exists
+        id: formula-target-cache-verification
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.validate-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+          lookup-only: true
+          fail-on-cache-miss: true
+
+      - name: Require exact Formula main SHA coverage cache
+        env:
+          EXACT_CACHE_HIT: ${{ steps.formula-target-cache-verification.outputs.cache-hit }}
+        run: test "$EXACT_CACHE_HIT" = true
+
+      - name: Complete Formula cache promotion acknowledgement
+        if: ${{ always() && steps.validate-target.outputs.check_run_id != '' }}
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          PROMOTION_JOB_STATUS: ${{ job.status }}
+        with:
+          script: |
+            const checkRunId = Number('${{ steps.validate-target.outputs.check_run_id }}');
+            const targetSha = '${{ steps.validate-target.outputs.target_sha }}';
+            const expectedExternalId = '${{ steps.validate-target.outputs.check_external_id }}';
+            const {data: currentCheck} = await github.rest.checks.get({
+              ...context.repo,
+              check_run_id: checkRunId,
+            });
+            if (
+              currentCheck.head_sha !== targetSha ||
+              currentCheck.name !== 'Coverage Baseline Cache' ||
+              currentCheck.external_id !== expectedExternalId ||
+              currentCheck.app?.slug !== 'github-actions'
+            ) {
+              throw new Error('refusing to update a changed promotion acknowledgement');
+            }
+            const succeeded = process.env.PROMOTION_JOB_STATUS === 'success';
+            await github.rest.checks.update({
+              ...context.repo,
+              check_run_id: checkRunId,
+              status: 'completed',
+              conclusion: succeeded ? 'success' : 'failure',
+              completed_at: new Date().toISOString(),
+              output: {
+                title: succeeded
+                  ? 'Exact-SHA coverage baseline is available'
+                  : 'Exact-SHA coverage baseline promotion failed',
+                summary: succeeded
+                  ? `Verified the main-scoped exact cache for ${targetSha}.`
+                  : `Promotion failed for ${targetSha}; rerun the failed Release job after correcting the producer.`,
+              },
+            });

.github/workflows/coverage-baseline-repair.yml

@@ -0,0 +1,560 @@
+name: Coverage Baseline Repair
+
+run-name: Repair coverage baseline from ${{ github.event_name }}
+
+on:
+  pull_request_target:
+    branches: [main]
+    types: [closed]
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+    branches: [main]
+  repository_dispatch:
+    types: [coverage-baseline-repair]
+  schedule:
+    - cron: "23 * * * *"
+  workflow_dispatch:
+
+# pull_request_target and workflow_run are allowed to inspect only GitHub API
+# data and dispatch the trusted producer. GitHub deliberately makes both
+# triggers read-only for the default-branch cache, so all checkout and cache
+# writes live in repository_dispatch, schedule, or main-only workflow_dispatch.
+permissions:
+  contents: read
+
+concurrency:
+  group: coverage-baseline-repair-${{ github.event_name == 'pull_request_target' && github.event.pull_request.merge_commit_sha || github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.event_name == 'repository_dispatch' && github.event.client_payload.merge_commit_sha || github.sha }}
+  cancel-in-progress: false
+  # Retain every pending repair for one target. actionlint v1.7.12's bundled
+  # schema predates GitHub's concurrency.queue support.
+  queue: max
+
+jobs:
+  dispatch-merged-pr:
+    if: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.merged == true && github.repository == 'DingTalk-Real-AI/dingtalk-workspace-cli' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read
+      contents: write
+      pull-requests: read
+    steps:
+      # Never check out or execute pull-request content in this privileged
+      # base-owned event. Re-read the merged PR, bind every immutable identity,
+      # prove the result is in main, and send only those values to the producer.
+      - name: Dispatch trusted merged-PR repair
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const eventPull = context.payload.pull_request;
+            const fullCommit = /^[0-9a-f]{40}$/;
+            const pullNumber = Number(eventPull?.number);
+            const headSha = eventPull?.head?.sha;
+            const baseRef = eventPull?.base?.ref;
+            const mergeCommitSha = eventPull?.merge_commit_sha;
+            if (
+              context.payload.repository?.full_name !==
+                'DingTalk-Real-AI/dingtalk-workspace-cli' ||
+              context.payload.repository?.default_branch !== 'main' ||
+              !Number.isSafeInteger(pullNumber) ||
+              pullNumber <= 0 ||
+              !fullCommit.test(headSha || '') ||
+              baseRef !== 'main' ||
+              !fullCommit.test(mergeCommitSha || '')
+            ) {
+              throw new Error('closed PR event has an invalid repository or revision identity');
+            }
+
+            // REST base.sha follows the live base branch and can move after
+            // merge. Bind the closed event's stable PR head snapshot and merge
+            // facts, then authorize the target through main containment.
+            function isStableMergedPRIdentity(
+              currentPull,
+              pullNumber,
+              headSha,
+              mergeCommitSha,
+            ) {
+              return (
+                currentPull?.number === pullNumber &&
+                currentPull.state === 'closed' &&
+                currentPull.merged === true &&
+                typeof currentPull.merged_at === 'string' &&
+                currentPull.merged_at.length > 0 &&
+                currentPull.base?.ref === 'main' &&
+                currentPull.head?.sha === headSha &&
+                currentPull.merge_commit_sha === mergeCommitSha
+              );
+            }
+
+            const {data: currentPull} = await github.rest.pulls.get({
+              owner,
+              repo,
+              pull_number: pullNumber,
+            });
+            if (!isStableMergedPRIdentity(
+              currentPull,
+              pullNumber,
+              headSha,
+              mergeCommitSha,
+            )) {
+              throw new Error(`PR #${pullNumber} no longer matches the merged-main event`);
+            }
+
+            async function requireMainContainment(targetSha) {
+              let lastState = 'not checked';
+              for (let attempt = 1; attempt <= 6; attempt += 1) {
+                try {
+                  const {data: branch} = await github.rest.repos.getBranch({
+                    owner,
+                    repo,
+                    branch: 'main',
+                  });
+                  const {data: comparison} =
+                    await github.rest.repos.compareCommitsWithBasehead({
+                      owner,
+                      repo,
+                      basehead: `${targetSha}...${branch.commit.sha}`,
+                    });
+                  lastState = comparison.status;
+                  if (['ahead', 'identical'].includes(comparison.status)) {
+                    return;
+                  }
+                } catch (error) {
+                  lastState = error.message;
+                }
+                if (attempt < 6) {
+                  await new Promise(resolve => setTimeout(resolve, 5000));
+                }
+              }
+              throw new Error(
+                `${targetSha} is not contained in protected main after retries: ${lastState}`,
+              );
+            }
+            await requireMainContainment(mergeCommitSha);
+
+            // Normal App or human merges emit a protected-main push run whose
+            // CI producer owns this exact key. Give Actions event delivery a
+            // short visibility window and avoid a duplicate full-suite repair.
+            // A workflow-skip directive or suppressed built-in-token event has
+            // no such run, so only that missing-event path reaches dispatch.
+            const {data: ciWorkflow} = await github.rest.actions.getWorkflow({
+              owner,
+              repo,
+              workflow_id: '.github/workflows/ci.yml',
+            });
+            if (
+              ciWorkflow.name !== 'CI' ||
+              ciWorkflow.path !== '.github/workflows/ci.yml' ||
+              ciWorkflow.state !== 'active'
+            ) {
+              throw new Error('protected CI workflow identity is not active or exact');
+            }
+            for (let attempt = 1; attempt <= 12; attempt += 1) {
+              const {data: workflowRuns} =
+                await github.rest.actions.listWorkflowRunsForRepo({
+                  owner,
+                  repo,
+                  branch: 'main',
+                  event: 'push',
+                  per_page: 100,
+                });
+              const exactPushRun = workflowRuns.workflow_runs.find(run =>
+                run.name === 'CI' &&
+                run.workflow_id === ciWorkflow.id &&
+                run.path === ciWorkflow.path &&
+                run.event === 'push' &&
+                run.head_sha === mergeCommitSha &&
+                run.head_branch === 'main' &&
+                ['queued', 'in_progress', 'completed'].includes(run.status),
+              );
+              if (exactPushRun) {
+                core.info(
+                  `CI push run ${exactPushRun.id} already owns the exact-SHA producer for ${mergeCommitSha}; repair dispatch is unnecessary.`,
+                );
+                return;
+              }
+              if (attempt < 12) {
+                await new Promise(resolve => setTimeout(resolve, 5000));
+              }
+            }
+
+            // repository_dispatch is one of GitHub's explicit GITHUB_TOKEN
+            // recursion exceptions and receives default-branch cache-write scope.
+            await github.rest.repos.createDispatchEvent({
+              owner,
+              repo,
+              event_type: 'coverage-baseline-repair',
+              client_payload: {
+                source: 'merged_pr',
+                pull_number: String(pullNumber),
+                head_sha: headSha,
+                merge_commit_sha: mergeCommitSha,
+                source_run_id: String(context.runId),
+              },
+            });
+            core.info(
+              `Dispatched exact-SHA coverage repair for merged PR #${pullNumber} at ${mergeCommitSha}.`,
+            );
+
+  dispatch-failed-ci:
+    if: >-
+      ${{
+        github.event_name == 'workflow_run' &&
+        github.repository == 'DingTalk-Real-AI/dingtalk-workspace-cli' &&
+        github.event.workflow_run.name == 'CI' &&
+        github.event.workflow_run.event == 'push' &&
+        github.event.workflow_run.head_branch == 'main' &&
+        github.event.workflow_run.status == 'completed' &&
+        github.event.workflow_run.conclusion != 'success'
+      }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read
+      contents: write
+    steps:
+      # workflow_run cannot write the default-branch cache. Re-read the exact
+      # completed CI run from Actions, bind it to the protected CI workflow and
+      # main revision, then use the repository_dispatch recursion exception.
+      - name: Dispatch trusted failed-CI repair
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const upstream = 'DingTalk-Real-AI/dingtalk-workspace-cli';
+            const eventRun = context.payload.workflow_run;
+            const fullCommit = /^[0-9a-f]{40}$/;
+            const runID = Number(eventRun?.id);
+            const runAttempt = Number(eventRun?.run_attempt);
+            const headSha = eventRun?.head_sha;
+            const conclusion = eventRun?.conclusion;
+            if (
+              context.payload.repository?.full_name !== upstream ||
+              context.payload.repository?.default_branch !== 'main' ||
+              !Number.isSafeInteger(runID) ||
+              runID <= 0 ||
+              !Number.isSafeInteger(runAttempt) ||
+              runAttempt <= 0 ||
+              eventRun?.name !== 'CI' ||
+              eventRun?.event !== 'push' ||
+              eventRun?.head_branch !== 'main' ||
+              eventRun?.status !== 'completed' ||
+              typeof conclusion !== 'string' ||
+              conclusion.length === 0 ||
+              conclusion === 'success' ||
+              !fullCommit.test(headSha || '')
+            ) {
+              throw new Error('workflow_run event is not one completed non-success main CI push');
+            }
+
+            const {data: ciWorkflow} = await github.rest.actions.getWorkflow({
+              owner,
+              repo,
+              workflow_id: '.github/workflows/ci.yml',
+            });
+            const {data: currentRun} = await github.rest.actions.getWorkflowRun({
+              owner,
+              repo,
+              run_id: runID,
+            });
+            if (
+              ciWorkflow.name !== 'CI' ||
+              ciWorkflow.path !== '.github/workflows/ci.yml' ||
+              eventRun.workflow_id !== ciWorkflow.id ||
+              currentRun.id !== runID ||
+              currentRun.workflow_id !== ciWorkflow.id ||
+              currentRun.name !== 'CI' ||
+              currentRun.event !== 'push' ||
+              currentRun.head_branch !== 'main' ||
+              currentRun.head_sha !== headSha ||
+              currentRun.run_attempt !== runAttempt ||
+              currentRun.status !== 'completed' ||
+              currentRun.conclusion !== conclusion ||
+              currentRun.conclusion === 'success' ||
+              currentRun.repository?.full_name !== upstream ||
+              currentRun.head_repository?.full_name !== upstream
+            ) {
+              throw new Error(`CI workflow run ${runID} no longer matches the completed event`);
+            }
+
+            await github.rest.repos.createDispatchEvent({
+              owner,
+              repo,
+              event_type: 'coverage-baseline-repair',
+              client_payload: {
+                source: 'failed_ci',
+                workflow_run_id: String(runID),
+                workflow_run_attempt: String(runAttempt),
+                workflow_conclusion: conclusion,
+                merge_commit_sha: headSha,
+                source_run_id: String(context.runId),
+              },
+            });
+            core.info(
+              `Dispatched exact-SHA coverage repair for ${conclusion} CI run ${runID} at ${headSha}.`,
+            );
+
+  repair:
+    if: ${{ github.event_name == 'repository_dispatch' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 35
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    steps:
+      - name: Resolve trusted main repair target
+        id: resolve-target
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const fullCommit = /^[0-9a-f]{40}$/;
+            if (
+              context.payload.repository?.full_name !==
+                'DingTalk-Real-AI/dingtalk-workspace-cli' ||
+              context.payload.repository?.default_branch !== 'main'
+            ) {
+              throw new Error('coverage repair is restricted to the protected upstream repository');
+            }
+
+            async function requireMainContainment(targetSha) {
+              let lastState = 'not checked';
+              for (let attempt = 1; attempt <= 6; attempt += 1) {
+                try {
+                  const {data: branch} = await github.rest.repos.getBranch({
+                    owner,
+                    repo,
+                    branch: 'main',
+                  });
+                  const {data: comparison} =
+                    await github.rest.repos.compareCommitsWithBasehead({
+                      owner,
+                      repo,
+                      basehead: `${targetSha}...${branch.commit.sha}`,
+                    });
+                  lastState = comparison.status;
+                  if (['ahead', 'identical'].includes(comparison.status)) {
+                    return branch.commit.sha;
+                  }
+                } catch (error) {
+                  lastState = error.message;
+                }
+                if (attempt < 6) {
+                  await new Promise(resolve => setTimeout(resolve, 5000));
+                }
+              }
+              throw new Error(
+                `${targetSha} is not contained in protected main after retries: ${lastState}`,
+              );
+            }
+
+            // The dispatcher froze the stable PR head snapshot in this payload.
+            // Do not re-read mutable base.sha; bind the head and stable merge
+            // facts, then prove protected-main containment below.
+            function isStableMergedPRIdentity(
+              currentPull,
+              pullNumber,
+              headSha,
+              mergeCommitSha,
+            ) {
+              return (
+                currentPull?.number === pullNumber &&
+                currentPull.state === 'closed' &&
+                currentPull.merged === true &&
+                typeof currentPull.merged_at === 'string' &&
+                currentPull.merged_at.length > 0 &&
+                currentPull.base?.ref === 'main' &&
+                currentPull.head?.sha === headSha &&
+                currentPull.merge_commit_sha === mergeCommitSha
+              );
+            }
+
+            let targetSha;
+            if (context.eventName === 'repository_dispatch') {
+              const payload = context.payload.client_payload || {};
+              const sourceRunIDText = String(payload.source_run_id || '');
+              if (!/^[1-9][0-9]*$/.test(sourceRunIDText)) {
+                throw new Error('coverage-baseline-repair payload has an invalid source run');
+              }
+              if (payload.source === 'merged_pr') {
+                const rawPullNumber = String(payload.pull_number || '');
+                const pullNumber = Number(rawPullNumber);
+                const headSha = payload.head_sha;
+                targetSha = payload.merge_commit_sha;
+                if (
+                  !/^[1-9][0-9]*$/.test(rawPullNumber) ||
+                  !Number.isSafeInteger(pullNumber) ||
+                  !fullCommit.test(headSha || '') ||
+                  !fullCommit.test(targetSha || '')
+                ) {
+                  throw new Error('coverage-baseline-repair payload has an invalid PR identity');
+                }
+                const {data: currentPull} = await github.rest.pulls.get({
+                  owner,
+                  repo,
+                  pull_number: pullNumber,
+                });
+                if (!isStableMergedPRIdentity(
+                  currentPull,
+                  pullNumber,
+                  headSha,
+                  targetSha,
+                )) {
+                  throw new Error(
+                    `repair payload no longer matches merged PR #${pullNumber}`,
+                  );
+                }
+              } else if (payload.source === 'failed_ci') {
+                const rawWorkflowRunID = String(payload.workflow_run_id || '');
+                const workflowRunID = Number(rawWorkflowRunID);
+                const rawWorkflowRunAttempt = String(payload.workflow_run_attempt || '');
+                const workflowRunAttempt = Number(rawWorkflowRunAttempt);
+                const workflowConclusion = payload.workflow_conclusion;
+                targetSha = payload.merge_commit_sha;
+                if (
+                  !/^[1-9][0-9]*$/.test(rawWorkflowRunID) ||
+                  !Number.isSafeInteger(workflowRunID) ||
+                  !/^[1-9][0-9]*$/.test(rawWorkflowRunAttempt) ||
+                  !Number.isSafeInteger(workflowRunAttempt) ||
+                  typeof workflowConclusion !== 'string' ||
+                  workflowConclusion.length === 0 ||
+                  workflowConclusion === 'success' ||
+                  !fullCommit.test(targetSha || '')
+                ) {
+                  throw new Error('coverage-baseline-repair payload has an invalid CI identity');
+                }
+                const {data: ciWorkflow} = await github.rest.actions.getWorkflow({
+                  owner,
+                  repo,
+                  workflow_id: '.github/workflows/ci.yml',
+                });
+                const {data: currentRun} = await github.rest.actions.getWorkflowRun({
+                  owner,
+                  repo,
+                  run_id: workflowRunID,
+                });
+                if (
+                  ciWorkflow.name !== 'CI' ||
+                  ciWorkflow.path !== '.github/workflows/ci.yml' ||
+                  currentRun.id !== workflowRunID ||
+                  currentRun.workflow_id !== ciWorkflow.id ||
+                  currentRun.name !== 'CI' ||
+                  currentRun.event !== 'push' ||
+                  currentRun.head_branch !== 'main' ||
+                  currentRun.head_sha !== targetSha ||
+                  currentRun.run_attempt !== workflowRunAttempt ||
+                  currentRun.status !== 'completed' ||
+                  currentRun.conclusion !== workflowConclusion ||
+                  currentRun.conclusion === 'success' ||
+                  currentRun.repository?.full_name !==
+                    'DingTalk-Real-AI/dingtalk-workspace-cli' ||
+                  currentRun.head_repository?.full_name !==
+                    'DingTalk-Real-AI/dingtalk-workspace-cli'
+                ) {
+                  throw new Error(
+                    `repair payload no longer matches failed CI run ${workflowRunID}`,
+                  );
+                }
+              } else {
+                throw new Error('coverage-baseline-repair payload has an unknown source');
+              }
+              await requireMainContainment(targetSha);
+            } else {
+              if (context.ref !== 'refs/heads/main') {
+                throw new Error('scheduled and manual repair must run from refs/heads/main');
+              }
+              // github.sha is the default-branch tip that keyed this workflow's
+              // concurrency group. Keep the producer bound to that exact
+              // event-time target even if main advances while this run queues.
+              targetSha = context.sha;
+              if (!fullCommit.test(targetSha || '')) {
+                throw new Error('protected main did not resolve to one full commit SHA');
+              }
+              await requireMainContainment(targetSha);
+            }
+            core.setOutput('target_sha', targetSha);
+            core.info(`Resolved protected-main coverage repair target ${targetSha}.`);
+
+      - name: Check out exact protected-main target
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+          ref: ${{ steps.resolve-target.outputs.target_sha }}
+
+      - name: Verify checked-out repair target
+        env:
+          TARGET_SHA: ${{ steps.resolve-target.outputs.target_sha }}
+        run: test "$(git rev-parse HEAD)" = "$TARGET_SHA"
+
+      - name: Set up Go
+        id: setup-go
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version-file: go.mod
+
+      - name: Restore exact target coverage profile
+        id: target-cache
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.resolve-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+
+      - name: Validate existing exact target profile
+        if: steps.target-cache.outputs.cache-hit == 'true'
+        run: |
+          set -eu
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Install archive tooling for cold repair
+        if: steps.target-cache.outputs.cache-hit != 'true'
+        run: |
+          if command -v zip >/dev/null && command -v unzip >/dev/null; then
+            echo "zip and unzip are already available"
+          else
+            sudo apt-get update
+            sudo apt-get install -y zip unzip
+          fi
+
+      - name: Recompute complete target coverage profile
+        if: steps.target-cache.outputs.cache-hit != 'true'
+        env:
+          DWS_PACKAGE_VERSION: 0.0.0-test
+        run: |
+          set -euo pipefail
+          go test -count=1 -p 1 \
+            -coverprofile=coverage-cache.txt \
+            -covermode=atomic \
+            ./ ./cmd/... ./internal/... ./skills/...
+          test -s coverage-cache.txt
+          test "$(head -n 1 coverage-cache.txt)" = "mode: atomic"
+
+      - name: Save exact protected-main coverage profile
+        if: steps.target-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.resolve-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+
+      # Cache uploads are fail-open warnings. A lookup-only restore plus the
+      # explicit cache-hit assertion makes an absent or partial key fail hard.
+      - name: Verify exact protected-main coverage cache exists
+        id: target-cache-verification
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: coverage-cache.txt
+          key: dws-coverage-full-v2-${{ steps.resolve-target.outputs.target_sha }}-go${{ steps.setup-go.outputs.go-version }}
+          lookup-only: true
+          fail-on-cache-miss: true
+
+      - name: Require exact protected-main coverage cache
+        env:
+          EXACT_CACHE_HIT: ${{ steps.target-cache-verification.outputs.cache-hit }}
+        run: test "$EXACT_CACHE_HIT" = true

.github/workflows/release.yml

@@ -1112,6 +1112,9 @@ jobs:
     needs: [release-contract, release-validation, release, verify-darwin-signatures]
     runs-on: ubuntu-latest
     timeout-minutes: 30
+    outputs:
+      coverage_baseline_required: ${{ steps.seal-formula.outputs.coverage_baseline_required }}
+      coverage_baseline_commit: ${{ steps.seal-formula.outputs.coverage_baseline_commit }}
     permissions:
       checks: write
       contents: write
@@ -1495,6 +1498,7 @@ jobs:
           DWS_GIT_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Seal Formula-only Code Admission contexts
+        id: seal-formula
         if: ${{ github.repository_owner == 'DingTalk-Real-AI' }}
         uses: actions/github-script@v7
         env:
@@ -1515,6 +1519,8 @@ jobs:
             const sourcePath = channel === "stable"
               ? "dist/homebrew/dingtalk-workspace-cli.rb"
               : "dist/homebrew/dingtalk-workspace-cli-beta.rb";
+            core.setOutput("coverage_baseline_required", "false");
+            core.setOutput("coverage_baseline_commit", "");
             const expectedMessage = channel === "stable"
               ? `chore: update formula for ${version} [skip ci]`
               : `chore: update beta formula for ${version} [skip ci]`;
@@ -1650,6 +1656,11 @@ jobs:
                 },
               });
             }
+            core.setOutput("coverage_baseline_required", "true");
+            core.setOutput("coverage_baseline_commit", commit);
+            core.info(
+              `Formula-only Code Admission is sealed for ${commit}; the independent confirmation job will dispatch its exact-SHA cache producer.`,
+            );
 
       - name: Reverify exact immutable npm package
         run: ./scripts/release/verify-package-managers.sh --npm-only --expected-version "$RELEASE_VERSION"
@@ -2177,6 +2188,117 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+  coverage-baseline-confirmation:
+    name: Confirm Formula coverage baseline
+    # Once Formula sealing has exposed a target SHA, later publication
+    # verification failures must not orphan its exact-main cache producer.
+    if: ${{ !cancelled() && (needs.publish-release.result == 'success' || needs.publish-release.outputs.coverage_baseline_required == 'true') }}
+    needs: publish-release
+    runs-on: ubuntu-latest
+    timeout-minutes: 35
+    permissions:
+      checks: write
+      contents: write
+    steps:
+      - name: Require exact Formula cache acknowledgement
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          BASELINE_REQUIRED: ${{ needs.publish-release.outputs.coverage_baseline_required }}
+          FORMULA_COMMIT: ${{ needs.publish-release.outputs.coverage_baseline_commit }}
+        with:
+          script: |
+            const rawRequired = process.env.BASELINE_REQUIRED;
+            if (!['true', 'false'].includes(rawRequired)) {
+              throw new Error(`Formula baseline requirement is invalid: ${rawRequired || 'empty'}`);
+            }
+            const required = rawRequired === 'true';
+            const targetSha = process.env.FORMULA_COMMIT;
+            if (!required) {
+              if (targetSha) {
+                throw new Error('Formula baseline outputs are inconsistent for a no-op publication');
+              }
+              core.info('Formula was already current; no new exact-SHA cache acknowledgement is required.');
+              return;
+            }
+            if (!/^[0-9a-f]{40}$/.test(targetSha)) {
+              throw new Error('Formula baseline target output is malformed');
+            }
+            const expectedExternalId = `release-${context.runId}-${targetSha}`;
+            let promotionCheck;
+            try {
+              const created = await github.rest.checks.create({
+                ...context.repo,
+                name: 'Coverage Baseline Cache',
+                head_sha: targetSha,
+                status: 'queued',
+                external_id: expectedExternalId,
+                output: {
+                  title: 'Waiting for exact-SHA baseline promotion',
+                  summary:
+                    'The independent release governance job is waiting for the default-branch cache producer.',
+                },
+              });
+              promotionCheck = created.data;
+              await github.rest.repos.createDispatchEvent({
+                ...context.repo,
+                event_type: 'coverage-baseline-promote',
+                client_payload: {
+                  target_sha: targetSha,
+                  source_run_id: String(context.runId),
+                  check_run_id: String(promotionCheck.id),
+                },
+              });
+            } catch (error) {
+              if (promotionCheck) {
+                try {
+                  await github.rest.checks.update({
+                    ...context.repo,
+                    check_run_id: promotionCheck.id,
+                    status: 'completed',
+                    conclusion: 'failure',
+                    completed_at: new Date().toISOString(),
+                    output: {
+                      title: 'Coverage baseline dispatch failed',
+                      summary: `Release could not dispatch the exact-SHA producer: ${error.message}`,
+                    },
+                  });
+                } catch (cleanupError) {
+                  core.error(
+                    `Could not close failed cache acknowledgement ${promotionCheck.id}: ${cleanupError.message}`,
+                  );
+                }
+              }
+              throw error;
+            }
+            const checkRunId = promotionCheck.id;
+            for (let attempt = 1; attempt <= 180; attempt += 1) {
+              const {data: currentCheck} = await github.rest.checks.get({
+                ...context.repo,
+                check_run_id: checkRunId,
+              });
+              if (
+                currentCheck.head_sha !== targetSha ||
+                currentCheck.name !== 'Coverage Baseline Cache' ||
+                currentCheck.external_id !== expectedExternalId ||
+                currentCheck.app?.slug !== 'github-actions'
+              ) {
+                throw new Error('Formula baseline promotion acknowledgement changed identity');
+              }
+              if (currentCheck.status === 'completed') {
+                if (currentCheck.conclusion !== 'success') {
+                  throw new Error(
+                    `Formula baseline promotion failed with ${currentCheck.conclusion || 'unknown'}`,
+                  );
+                }
+                core.info(`Formula baseline promotion completed for ${targetSha}.`);
+                return;
+              }
+              if (attempt < 180) {
+                await new Promise(resolve => setTimeout(resolve, 10000));
+              }
+            }
+            throw new Error(`Formula baseline promotion timed out for ${targetSha}`);
+
   release-delivery-gate:
     name: Release delivery gate
     if: ${{ !cancelled() }}
@@ -2189,6 +2311,7 @@ jobs:
       - verify-darwin-signatures
       - publish-release
       - publish-channels
+      - coverage-baseline-confirmation
       - mirror-gitee-release
       - repair-npm
       - repair-channel
@@ -2211,6 +2334,7 @@ jobs:
           DARWIN_SIGNATURE_RESULT: ${{ needs.verify-darwin-signatures.result }}
           PUBLISH_RELEASE_RESULT: ${{ needs.publish-release.result }}
           PUBLISH_CHANNELS_RESULT: ${{ needs.publish-channels.result }}
+          COVERAGE_BASELINE_CONFIRMATION_RESULT: ${{ needs.coverage-baseline-confirmation.result }}
           MIRROR_GITEE_RESULT: ${{ needs.mirror-gitee-release.result }}
           REPAIR_NPM_RESULT: ${{ needs.repair-npm.result }}
           REPAIR_CHANNEL_RESULT: ${{ needs.repair-channel.result }}
@@ -2234,6 +2358,7 @@ jobs:
             require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" success
             require_result publish-release "$PUBLISH_RELEASE_RESULT" success
             require_result publish-channels "$PUBLISH_CHANNELS_RESULT" success
+            require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" success
             if test "$GITEE_FALLBACK_ENABLED" = true; then
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" success
             else
@@ -2273,6 +2398,7 @@ jobs:
               require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" skipped
               require_result publish-release "$PUBLISH_RELEASE_RESULT" skipped
               require_result publish-channels "$PUBLISH_CHANNELS_RESULT" skipped
+              require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" skipped
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" skipped
               require_result repair-npm "$REPAIR_NPM_RESULT" skipped
               require_result repair-channel "$REPAIR_CHANNEL_RESULT" skipped
@@ -2294,6 +2420,7 @@ jobs:
               require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" skipped
               require_result publish-release "$PUBLISH_RELEASE_RESULT" skipped
               require_result publish-channels "$PUBLISH_CHANNELS_RESULT" skipped
+              require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" skipped
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" skipped
               require_result repair-npm "$REPAIR_NPM_RESULT" skipped
               require_result repair-channel "$REPAIR_CHANNEL_RESULT" skipped
@@ -2309,6 +2436,7 @@ jobs:
               require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" skipped
               require_result publish-release "$PUBLISH_RELEASE_RESULT" skipped
               require_result publish-channels "$PUBLISH_CHANNELS_RESULT" skipped
+              require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" skipped
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" skipped
               require_result repair-channel "$REPAIR_CHANNEL_RESULT" skipped
               require_cloud_jobs_skipped
@@ -2323,6 +2451,7 @@ jobs:
               require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" skipped
               require_result publish-release "$PUBLISH_RELEASE_RESULT" skipped
               require_result publish-channels "$PUBLISH_CHANNELS_RESULT" skipped
+              require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" skipped
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" skipped
               require_result repair-npm "$REPAIR_NPM_RESULT" skipped
               require_cloud_jobs_skipped
@@ -2337,6 +2466,7 @@ jobs:
               require_result verify-darwin-signatures "$DARWIN_SIGNATURE_RESULT" skipped
               require_result publish-release "$PUBLISH_RELEASE_RESULT" skipped
               require_result publish-channels "$PUBLISH_CHANNELS_RESULT" skipped
+              require_result coverage-baseline-confirmation "$COVERAGE_BASELINE_CONFIRMATION_RESULT" skipped
               require_result mirror-gitee-release "$MIRROR_GITEE_RESULT" skipped
               require_result repair-npm "$REPAIR_NPM_RESULT" skipped
               require_cloud_jobs_skipped

.github/workflows/reviewer-router-approval-signal.yml

@@ -0,0 +1,19 @@
+name: Reviewer Router approval signal
+
+on:
+  pull_request_review:
+    types: [submitted, dismissed]
+
+# This workflow only converts an approval-state change into a trusted
+# workflow_run event. It must never read secrets, check out code, or mutate the
+# pull request; the default-branch Reviewer routing workflow owns reconciliation.
+permissions: {}
+
+jobs:
+  signal:
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    permissions: {}
+    steps:
+      - name: Signal approval-state change
+        run: echo "Review state changed; default-branch reconciliation will re-evaluate App-owned merge intents."

AGENTS.md

@@ -44,7 +44,8 @@ Schema contract) keep separate authorities — do not merge them with
 ## Command framework declaration
 
 - Framework definition: `docs/rfc-command-framework-convergence.md` **§5.0**
-- Today: `helpers.LeafSpec` / `shortcut.Shortcut` → `corecmd.Spec` (+ optional `Contract`) → `corecmd.New`
+- Today (leaf): `helpers.LeafSpec` / `shortcut.Shortcut` → `corecmd.Spec` (+ optional `Contract`) → `corecmd.New`
+- Today (non-leaf): owning Cobra command → complete `corecmd.GroupPolicy{Mode, Positionals, Recovery}` → `corecmd.ApplyGroupPolicy`; the final assembled-tree gate rejects undeclared groups and stale group declarations on leaves
 - **Declare = final Schema source**: `Flags` / `Constraints` / `Safety` / `ConstParams` / `Contract` (`corecmd.ContractDecl`; nested fields are `contract.*`)
 - Naming: `ContractDecl` is the authoring leaf declaration. "Schema" means Catalog / `ToolSpec` delivery — do not reintroduce `SchemaDecl`.
 - `Safety` uses `contract.SafetySpec` (`internal/corecmd/contract` only — no `cli.*` type alias). Its `confirmation` drives the runtime gate; `effect` / `risk` / `idempotency` are published unchanged. When `Contract` is set, convert once via `contractfinal.RegisterRuntimeContractFinal` (all callers — `corecmd.New` registers internally); assembly **pass-throughs** Final.
@@ -60,6 +61,7 @@ Schema contract) keep separate authorities — do not merge them with
   - **Tier2** — `DeclareLeafMetadata` (helpers migration; **Shortcut may also use this path — acceptable**)
   - **Tier3** — bare Cobra (should shrink over time; reviewed exclusions where needed)
   - Long-term outlook only: broader mcpbind / fewer hand-written `Execute` bodies. **Not** a current hard requirement to delete `Shortcut.Execute` or force mcpbind.
+- Group policy is separate from the leaf tiers: `corecmd.Spec` remains leaf-only. `ApplyGroupPolicy` must not infer or enable `TraverseChildren`; parent local-flag inheritance remains an explicit owning-command surface.
 - Description declare vs delivery: construction requires `ContractDecl.Description` (evidence). Catalog delivery prefers Cobra Long → provenance `cobra_help`; without Long, declared text → `contract_final`. Title: declared first, then Short, then MCP. Do **not** read this as "declare = wire final" or dual authority.
 - **Execute** = hooks (`Validate` / `Call` / `RunE` / `PostMount`) — not a second surface authority
 - Declaration path has **no reviewed parallel fields**; migration-only `runtime_gate` annotate until `Safety` is declared

docs/automation.md

@@ -62,9 +62,171 @@ make lint
 git diff --check
 ```
 
+## Reviewer Router GitHub App
+
+Reviewer requests and merge authority intentionally use different identities.
+The base-owned `pull_request_target` workflow may use its built-in
+`GITHUB_TOKEN` to request reviewers, but it must mint a dedicated GitHub App
+installation token before enabling auto-merge. GitHub suppresses most workflow
+events created by the built-in token; using it for auto-merge prevents the
+merge commit's `push` workflows from running and leaves the exact-SHA Coverage
+baseline without a trusted main-scoped producer.
+
+Configure the dedicated App before merging a workflow revision that requires
+it:
+
+- install it only on `DingTalk-Real-AI/dingtalk-workspace-cli`;
+- grant only `Contents: read and write` and `Pull requests: read and write`;
+- set repository variable `REVIEWER_ROUTER_APP_CLIENT_ID` to its client ID;
+- set `REVIEWER_ROUTER_APP_SLUG` to its exact lowercase slug;
+- set repository secret `REVIEWER_ROUTER_APP_PRIVATE_KEY` to its private key;
+- create one active repository branch ruleset named `main-merge-writers`,
+  targeting only `refs/heads/main`, with exactly one `Restrict updates` rule
+  (`update_allows_fetch_and_merge: false`). GitHub may project that strict
+  value through the read APIs as `{type: "update"}` with `parameters` omitted;
+  consumers accept only that exact omission or a one-field `parameters` object
+  containing explicit boolean `false`, and reject every other present shape or
+  value. They then bind the same ruleset node through GraphQL and require its
+  non-null `updateAllowsFetchAndMerge` value to be exactly `false`;
+- give that ruleset exactly three bypass actors: the Reviewer Router App as an
+  `Integration` in `pull_request` mode, plus `haofeng0705` (ID `30925823`) and
+  `PeterGuy326` (ID `47820304`) in `always` mode for Formula publication and
+  break-glass recovery;
+- never give the App bypass on `main-protection`, `main-quality`, or any other
+  ruleset, and never reuse `HOMEBREW_PR_TOKEN`,
+  `RELEASE_GOVERNANCE_TOKEN`, or a personal token for Reviewer Router.
+
+The workflow limits each minted token to the current repository, requests the
+two permissions explicitly, and lets the token action revoke it at job end.
+It also requires the minted App slug to equal the reviewed repository variable;
+there is no `GITHUB_TOKEN` fallback. Before reading App credentials, the
+base-owned workflow revalidates the event's exact base/head and uses its
+built-in token only to disable an existing request owned by
+`github-actions[bot]` or one whose title or merge metadata requests that GitHub
+skip workflows. A mint or permission failure therefore leaves that PR
+manual-merge only. The built-in token's `Contents: write` permission is
+isolated to this trusted cleanup job and is never used to enable auto-merge;
+review routing keeps `Contents: read`. Existing requests owned by a human or
+another non-built-in identity are replaced with the exact dedicated-App
+request after token minting. Only an already App-owned request with the fixed
+headline/body is preserved. The required `Test` context reads the live
+repository settings and applied rulesets, verifies the exact writer-rule
+shape, and requires its own built-in Actions identity to report
+`current_user_can_bypass: never`. Before enabling or reconciling auto-merge,
+the minted App independently requires `pull_requests_only` on that writer rule
+and `never` on every other active main ruleset. These identity-relative checks
+remain available to low-privilege tokens; GitHub deliberately hides the full
+`bypass_actors` list from callers without ruleset-write access. Operators must
+therefore inspect that list during rollout and keep it at the exact three actors
+above. The required `Test` context then briefly waits for the concurrent
+router takeover and accepts only a null request or the configured App owner
+with exact fixed metadata. A null request is safe for this failure mode because
+the built-in Actions identity cannot pass the writer rule; other permitted
+identities emit either a protected-main push or the trusted closed-PR repair.
+Draft PRs skip this identity check; the explicit `ready_for_review` trigger
+reruns admission when they become merge-eligible,
+while `edited` and `auto_merge_enabled` rerun both workflows when the PR title
+or merge request changes. A human `auto_merge_disabled` event reruns CI without
+silently re-enabling the request, leaving it available only to the designated
+break-glass identity. The required `Test` context rejects GitHub workflow-skip
+directives in the PR title or an existing auto-merge request and verifies the
+repository's reviewed `MERGE_MESSAGE` title plus `PR_TITLE` or `BLANK` body
+defaults. GitHub does not expose those merge-related settings to the read-only
+admission token: the classifier accepts only both exact reviewed values or the
+complete omission of both properties, and rejects partial omission, `null`, or
+any other value. Before any enable, reconcile, or merge mutation, the dedicated
+App's current-repository token (which has `Contents: write`) must observe both
+exact reviewed values. The dedicated App binds each mutation to the exact head
+OID and supplies a fixed safe headline and body, so GitHub cannot copy an unsafe
+PR title into its merge commit.
+After enabling, the workflow requires the owner to equal the token action's
+exact `<app-slug>[bot]` output. If the event base/head changes during the
+mutation window, it removes only that App-owned request and fails the run.
+The App-owned native auto-merge request is the reviewed automation intent, not
+the sole executor: GitHub's deferred auto-merge path does not reliably apply a
+GitHub App's pull-request-only ruleset bypass. A zero-permission approval-signal
+workflow converts submitted or dismissed reviews into `workflow_run`; completed
+admission workflows use the same trusted default-branch trigger. The serialized
+reconcile job treats `workflow_run` only as a wake-up signal: it never reads the
+triggering run's pull-request payload or artifacts and never checks out code
+from that run. It enumerates open `main` PRs again through the API, then
+revalidates the safe App owner, metadata, and ruleset boundary immediately
+before calling the synchronous PR merge endpoint with the exact current head
+SHA. The preflight requires exactly one repository-owned `main-protection`
+ruleset with one latest-head approval and exactly one repository-owned
+`main-quality` ruleset with the reviewed nine strict checks. The App must report
+`never` on both and on every other non-writer ruleset. Every required context
+must be bound to the GitHub Actions App (`integration_id=15368`); a missing,
+different, or duplicate context/source entry fails closed together with
+deletion or weakening of either gate. HTTP 405 means the PR is not ready,
+while 409 means its revision
+changed; either remains open for the next event. Other failures make
+reconciliation red. A concurrent native merge is accepted only after the final
+PR state proves the exact head, App identity, and non-empty merge SHA.
+A staggered twice-hourly schedule provides eventual recovery if a webhook or
+workflow completion is delayed, and `workflow_dispatch` remains the on-demand
+repair path.
+The break-glass publisher must preserve a safe final commit message;
+`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`,
+`[actions skip]`, and a `skip-checks: true` trailer are forbidden outside the
+release-controlled Formula-only path below.
+
+GitHub may suppress `pull_request_target` entirely for security-sensitive head
+branch names, including names that look like commit SHAs. Such a PR receives
+neither App takeover nor the closed-event repair. Rename the head branch for
+the normal path; if break-glass merge is unavoidable, preserve a safe final
+message so the protected-main push CI remains the authoritative producer.
+
+After installing the App, the protected-main push that deploys this workflow
+runs reconciliation automatically. Approval-signal and admission-workflow
+completions run the same serialized recovery path. The job enumerates open,
+ready `main` PRs
+with any non-App owner, unsafe App metadata, or workflow-skip metadata. It
+revalidates each base/head, converges a safe request to the exact dedicated-App
+owner and fixed message, and leaves a workflow-skipping request disabled for
+manual correction. It never enables auto-merge where the request was already
+null. Every exact safe App request is then attempted through the synchronous,
+SHA-bound merge endpoint; a server-declared not-ready result remains open for
+the next event. A mid-migration failure leaves the affected PR disabled for a
+fresh routing event or break-glass merge. One PR failure is recorded
+without preventing later legacy owners from being attempted; the batch ends
+red with a per-PR summary. Manually dispatch `Reviewer routing` from `main`
+until the failed count is zero.
+
+Disabling the App-owned auto-merge request before the reconcile job's final PR
+read leaves that PR manual-only. That final read is the cancellation
+linearization point: GitHub's merge API can condition atomically on the head SHA
+but not on the auto-merge request itself, so a disable racing after that read may
+lose to an already-issued merge request. To stop an in-flight attempt
+before the merge endpoint accepts it, close the PR or change its head; if the
+server observes that state first, it rejects the state/SHA-bound merge. No
+client-side action can revoke a merge that GitHub has already accepted.
+The endpoint has no equivalent expected-base parameter. The workflow therefore
+checks `base=main` and the repository before and after merge and fails any
+retargeted result, but a retarget racing after the final read cannot be made
+atomic client-side. Never retarget a PR while its App-owned intent is active:
+disable the request, wait until all running `Reviewer routing` reconciliation
+jobs finish, and only then change the base. Preventing a malicious same-instant
+retarget requires a GitHub-side branch/ruleset control rather than workflow
+code.
+
+A PR that introduces or rotates this identity still runs the old base-owned
+router. Install/configure the App and activate the exact writer ruleset first;
+this blocks its legacy `github-actions[bot]` request from writing `main`. After
+the governance PR's final push, disable that old request, confirm the live
+settings/ruleset contract and all required checks are green for the exact head,
+then have only `haofeng0705` or `PeterGuy326` merge that head with the
+repository-generated safe merge message. Verify the resulting merge SHA has a
+`CI` run with `event=push`,
+a successful `Coverage` context, and an exact-SHA baseline cache under
+`refs/heads/main`. Confirm automatic reconciliation reports zero failures and
+zero non-App owners. Finally use a normal canary PR to verify that the dedicated
+App is both `enabledBy` and `mergedBy`, and that the same post-merge chain
+repeats before declaring the rollout complete.
+
 ## Homebrew Formula Delivery
 
-Official releases use the Release workflow's built-in `GITHUB_TOKEN` to update
+Official releases use the designated `HOMEBREW_PR_TOKEN` identity to update
 exactly one tracked Formula after the immutable GitHub assets and their
 checksums have passed verification. The publisher validates the rendered Ruby,
 commits only the configured Formula path, never force-pushes `main`, and retries
@@ -72,11 +234,60 @@ from a fresh clone up to three times when `main` advances concurrently. Normal
 stable and beta releases do not create a Formula PR or run a permission
 canary. The workflow uses the existing repository-scoped
 `HOMEBREW_PR_TOKEN` release identity because GitHub does not allow its built-in
-Actions App to bypass this repository's rulesets. That identity is the sole
-user bypass actor on the two default-branch rulesets. The workflow creates the
+Actions App to bypass this repository's rulesets. Its owner is the designated
+always-bypass actor for controlled Formula publication and break-glass recovery,
+including on `main-merge-writers`. The workflow creates the
 nine Code Admission checks for the Formula-only commit only after proving its
 sole parent already has all nine successful checks and the committed Formula
-exactly matches this release's verified bytes.
+exactly matches this release's verified bytes. Formula commits retain
+`[skip ci]`, so the sealing step exposes only the reviewed commit identity to
+an independent confirmation job. That job creates the
+`Coverage Baseline Cache` acknowledgement and emits the reviewed
+`coverage-baseline-promote` repository dispatch. The default-branch
+`Coverage Baseline Promotion` workflow independently verifies the exact
+single-parent Formula commit, both parent and target admission contexts, and
+default-branch containment before checking out the target. It restores only
+the exact parent profile, recomputes the complete profile if that cache is
+absent, and saves the Formula SHA under the `main` cache scope. Because the
+cache save action treats upload errors as warnings, a second lookup must report
+`cache-hit=true` for the exact target key before the producer succeeds. The
+promotion completes the unique acknowledgement, and the confirmation job
+waits for that exact check-run ID. npm and mirror publication depend only on
+the immutable release job, so a transient
+cache-service failure cannot strand an otherwise valid release between
+channels; the final release-delivery gate still fails until the exact cache is
+confirmed. Once Formula sealing exposes the target SHA, the confirmation job
+also runs when a later immutable-package recheck fails, so a post-push failure
+cannot orphan the producer. Rerun the failed promotion/confirmation path after
+repairing the producer. Never add a prefix `restore-keys` fallback to this path.
+
+`Coverage Baseline Repair` is the independent safety net for every merged PR.
+Its base-owned `pull_request_target: closed` job never checks out or executes PR
+content: it binds the closed event's PR number and stable head SHA to the
+current merged-PR facts (`merged_at`, `base.ref`, and `merge_commit_sha`) and
+proves that merge commit is contained in `main`. It deliberately does not
+compare REST `base.sha`, because that field follows the live base branch and
+can move after the merge. Only then does it emit a
+`coverage-baseline-repair` repository dispatch. Workflow-skip directives alone
+do not suppress `pull_request_target`, subject to GitHub's separate
+security-sensitive branch-name restriction described above. The low-trust
+trigger is forbidden from writing the default-branch cache directly. Before
+dispatching, it gives Actions event delivery one minute to expose a run from
+the exact protected `.github/workflows/ci.yml` workflow and exits if that normal producer already
+owns the SHA, avoiding a duplicate full-suite run. A successful CI producer
+must hard-verify its exact cache key. If that run instead completes with any
+non-success conclusion, a separate base-owned `workflow_run` dispatcher binds
+the exact workflow ID/path, run ID/attempt, conclusion, repository, branch, and
+head SHA before requesting repair. `workflow_run` also has read-only
+default-branch cache access, so both dispatchers use the reviewed
+`repository_dispatch` exception. The dispatched default-branch producer
+revalidates the corresponding merged-PR or failed-CI identity before checkout,
+restores only the exact target key, recomputes the complete profile on a miss,
+and verifies `cache-hit=true` after saving. An hourly schedule refreshes the
+event-time `main` SHA after direct break-glass pushes or cache eviction;
+`workflow_dispatch` provides the same current-main repair on demand. The
+dedicated App identity remains mandatory because events created by the built-in
+`GITHUB_TOKEN` can suppress both the main push and the closed-PR event.
 
 Keep `HOMEBREW_PR_TOKEN` repository-scoped with `Contents: write` and
 `Pull requests: write` (the latter remains necessary for withdrawal rollback),

docs/ci-pr-gates.md

@@ -147,13 +147,112 @@ maintainer pool. A current-head approval or change request is preserved; after
 a new push, stale activity does not suppress a fresh request, and an
 outstanding change requester is preferred for continuity.
 
-The branch ruleset keeps one human approval and all nine strict required
-contexts, and requires someone other than the latest pusher to approve after
-the most recent head update. Repository auto-merge is enabled for ready PRs,
-so a PR merges after that approval and the current revision's nine checks are
-green. If `main` advances, strict checks rerun before merge. The reviewer
-router is orchestration, not a quality context, and must not be added to the
-ruleset.
+The branch rulesets keep one human approval and all nine strict required
+contexts, require someone other than the latest pusher to approve after the
+most recent head update, and restrict `main` updates to the dedicated Reviewer
+Router App in pull-request mode plus the designated Formula publishers and
+break-glass identities. Repository auto-merge is enabled for ready PRs, so the
+App-owned request records the automation intent while the App's synchronous
+merge path waits for that approval and the current revision's nine green
+checks. If `main` advances, strict checks rerun before merge. The
+reviewer routing job uses the built-in `GITHUB_TOKEN` to request reviewers with
+`Contents: read` and `Pull requests: write`. A separate base-owned cleanup job
+isolates the merge-authority permissions (`Contents: write` and `Pull
+requests: write`), revalidates the exact event base/head, and uses the built-in
+token only to disable an existing request owned by `github-actions[bot]` or one
+whose title or merge metadata requests that GitHub skip workflows; it never
+enables auto-merge. The job then mints a current-repository installation token
+for the dedicated Reviewer Router GitHub App, proves its emitted slug matches
+the reviewed `REVIEWER_ROUTER_APP_SLUG`, replaces every non-App request, and
+enables native auto-merge with fixed metadata. This
+identity boundary is required because GitHub suppresses
+most workflow events created by the built-in token; using it for auto-merge would
+silently skip the merge commit's protected-main CI and baseline-cache
+producer. Token minting or takeover fails closed without falling back to
+`GITHUB_TOKEN`: the unsafe request is cleared before credentials are read, and
+the required `Test` context live-verifies the exact `main-merge-writers` update
+rule. GitHub's read APIs may omit `parameters` for the strict
+`update_allows_fetch_and_merge: false` value, so the gate accepts only that
+exact omission or a one-field `parameters` object containing explicit boolean
+`false`; every other present shape or value fails closed. The gate then binds
+the same ruleset node through GraphQL and requires its non-null
+`updateAllowsFetchAndMerge` value to be exactly `false`. It also requires its
+own built-in token to report
+`current_user_can_bypass: never`. The minted App separately requires
+`pull_requests_only` on that writer rule and `never` on every other active main
+ruleset before it can enable, reconcile, or synchronously merge. The read-only
+`Test`
+token may receive a repository projection with both merge-default properties
+omitted; it accepts only that complete omission or exact `MERGE_MESSAGE` plus
+`PR_TITLE`/`BLANK`, while partial or malformed projections fail closed.
+The same unprivileged `pull_request` job may receive an empty repository-variable
+projection for an external fork. Only when the event head repository differs
+from the base repository does it substitute the exact reviewed public slug
+`dingtalk-dws-reviewer-router` for identity comparison. An empty variable on a
+same-repository PR and every malformed non-empty value still fail closed. This
+fallback neither mints a token nor grants merge authority; the base-owned
+Router continues to require its minted App slug to equal the repository
+variable before any mutation. The minted App's `Contents: write` token must
+observe the exact reviewed defaults
+before either mutation path proceeds. GitHub hides the complete
+`bypass_actors` list from low-privilege callers, so the rollout audit must still
+keep the writer list at exactly the Reviewer App, `haofeng0705` (ID
+`30925823`), and `PeterGuy326` (ID `47820304`). The required check finally
+accepts a null or exact App-owned
+request after a short takeover grace period. Null is safe from the suppressed
+event path because the built-in Actions identity cannot update `main`; other
+permitted identities produce either a main push or the trusted closed-PR
+repair. Drafts skip the identity step, while `ready_for_review`, `edited`,
+`auto_merge_enabled`, and `auto_merge_disabled` explicitly start fresh admission
+for readiness, title, and merge-request changes. Router does not react to
+`auto_merge_disabled`, so a
+human can deliberately leave the PR manual-only for break-glass handling.
+Reviewer routing remains available. The protected-main push that deploys the
+workflow automatically migrates every open, ready non-App request and repairs
+unsafe App metadata; it disables workflow-skipping requests for correction.
+Because GitHub's deferred native auto-merge path does not reliably apply an
+App's pull-request-only ruleset bypass, a zero-permission approval-signal
+workflow and completed `CI` / `Code Admission — AI Behavior` workflows wake the
+same trusted default-branch reconciliation through `workflow_run`. That event
+is only a wake-up signal: the privileged job does not consume its pull-request
+payload or artifacts and does not check out the triggering run's code. It
+re-enumerates open `main` PRs through the API and attempts only an exact
+App-owned request through the synchronous PR merge endpoint. Immediately before
+each attempt it revalidates the App's ruleset boundary and PR intent, supplies
+the current head SHA, and treats server-declared not-ready or
+concurrent-revision responses as retriable. The live preflight requires the
+exact repository-owned approval ruleset and exact nine-check strict quality
+ruleset, with every context bound to the GitHub Actions App
+(`integration_id=15368`) and the Reviewer Router App unable to bypass either;
+a missing, disabled, incorrectly sourced, or weakened gate fails closed before
+merge. GitHub—not the workflow—decides whether the
+merge is admissible. A staggered twice-hourly schedule provides eventual
+recovery, and a manual `workflow_dispatch` from `main` is the immediate
+idempotent retry path.
+Reconciliation never enables an originally null request. The reviewer router
+is orchestration, not a quality context, and
+must not be added to the ruleset.
+
+Disabling the App-owned request before the reconcile job's final PR read keeps
+the PR manual-only. GitHub can atomically bind the subsequent merge to the head
+SHA, but it cannot bind that call to the auto-merge intent; a disable racing
+after the final read may therefore lose to the in-flight merge. Closing the PR
+or changing its head blocks the attempt only if GitHub observes that state
+before accepting the merge endpoint call; no client-side action can revoke a
+merge that the server has already accepted.
+
+The merge endpoint has no expected-base precondition. Reconciliation checks
+that the base is this repository's `main` immediately before and after the call,
+but a retarget racing after the final read is not atomically preventable in the
+workflow. Operators must disable the App-owned intent and wait for all running
+`Reviewer routing` reconciliation jobs to finish before retargeting a PR; a
+stronger adversarial guarantee requires a GitHub-side branch/ruleset control.
+
+GitHub may omit `pull_request_target` for security-sensitive head branch names,
+including names that look like commit SHAs. Those PRs cannot use Router App
+takeover or the closed-event repair: rename the branch for the supported path,
+or use the designated break-glass identity with a safe final message so main
+push CI remains the exact-SHA producer.
 
 ## Running focused gates locally
 
@@ -213,7 +312,76 @@ the same dedicated cache profile path because GitHub includes that path in the
 cache version; the runtime-facing candidate and baseline filenames remain
 separate. Near-miss reuse is forbidden — the caches carry no prefix restore
 keys, because a neighbouring commit's profile would compare the candidate
-against the wrong baseline. Supporting and (when
+against the wrong baseline. PR concurrency is keyed by PR number, so a later
+revision cancels the stale run instead of letting obsolete test matrices
+compete with the replacement for hosted runners. If cancellation interrupts a
+cold-cache fallback, the latest run recomputes the same exact merge-base
+profile authoritatively. Main concurrency remains keyed by pushed SHA, so a
+newer main push cannot cancel a predecessor's producer.
+
+Every supported main advancement path has an exact-SHA producer. The required
+`Test` context rejects GitHub workflow-skip directives in PR and auto-merge
+metadata, reruns when that metadata is enabled, disabled, or edited, and
+verifies the live App/writer-ruleset identity contract. Reviewer Router
+additionally binds auto-merge to the exact head OID and writes a fixed safe
+merge headline/body. The sole break-glass publisher must retain a safe final
+message; the release-controlled Formula-only path
+is the sole supported use of `[skip ci]`. A full source push
+saves the assembled profile after the aggregate gate passes. A trusted
+documentation or release-seal push independently verifies that the complete
+`before...after` diff contains only the reviewed metadata allowlist, restores
+only the exact `before` cache, recomputes the full profile if the chain is
+cold, and makes that helper a dependency of the required `Coverage` context.
+Release-generated Formula commits intentionally retain `[skip ci]`; after
+their nine synthetic contexts are sealed, an independent release-governance
+job creates an acknowledgement and emits a `coverage-baseline-promote`
+repository dispatch. The default-branch promotion
+workflow revalidates the exact single-parent Formula identity, successful
+parent and target contexts, and main containment before it promotes the exact
+parent cache or performs the same full fallback. Every target-main producer
+follows its save with a lookup-only restore and requires
+`cache-hit=true` for the exact key; this turns the cache action's otherwise
+warning-only upload failure or prefix match into a hard failure. Formula
+promotion additionally updates one release-created `Coverage Baseline Cache`
+check. A separate confirmation job waits for that exact check-run ID while npm
+and mirrors remain dependent only on the immutable publication job; cache
+failure therefore makes the final delivery gate red without creating a
+partially published release. Once Formula sealing exposes its SHA, a later
+publication verification failure cannot suppress that confirmation job.
+
+A separate base-owned `pull_request_target: closed` safety net covers the final
+merged SHA even if a human or integration changes the merge message after PR
+checks finish. Skip directives alone do not suppress `pull_request_target`,
+subject to GitHub's separate security-sensitive branch-name restriction above.
+That job executes no PR code and only dispatches after binding the exact
+closed-event PR number and stable head SHA to merged-PR facts
+(`merged_at`, `base.ref`, and `merge_commit_sha`) and proving `main`
+containment. It does not compare the later REST `base.sha`, which follows the
+live base branch after merge. Because GitHub makes default-branch caches
+read-only to `pull_request_target`, the dispatcher first waits up to one minute
+for a run from the exact protected
+`.github/workflows/ci.yml` workflow and exits when that normal producer exists.
+A successful main CI hard-verifies the exact key itself. A completed
+non-success run starts a separate base-owned `workflow_run` dispatcher, which
+binds the exact CI workflow ID/path, run ID/attempt, conclusion, upstream
+repository, `main` branch, and head SHA. That trigger is also cache-read-only,
+so either trusted dispatcher uses `repository_dispatch`; its producer
+revalidates the merged-PR or failed-CI identity, checks out the contained SHA,
+and produces/verifies the exact full cache.
+An hourly schedule and a main-only manual dispatch repair the event-time main
+SHA after a direct break-glass push or cache eviction. The dispatch exception
+is intentional: unlike an ordinary event created by `GITHUB_TOKEN`, GitHub
+allows `repository_dispatch` to start another workflow. A legacy built-in-token
+merge can suppress the closed event too, which is why the required `Test`
+identity gate and dedicated Reviewer Router App are still mandatory.
+
+A cold miss can still occur during a producer race or after cache eviction,
+but it remains fail-safe: the PR recomputes the authoritative baseline with a
+30-minute job budget and saves a PR-scoped copy for same-PR reruns. It is no
+longer possible for a supported main-advance path to omit its producer
+silently. That PR-scoped fallback save remains a best-effort acceleration and
+does not replace the normal push, metadata, Formula, and merged-PR repair
+producers. Supporting and (when
 platform-selected) native profiles are generated before the aggregate
 `Coverage` context evaluates them. The
 aggregate and native gates require 100% coverage for changed executable Go
@@ -246,7 +414,9 @@ tool、parameter、mapping、positional execution、constraint 与 safety 语义
 
 The `main` quality ruleset must enable strict required-status-check policy
 (`strict_required_status_checks_policy=true`) so a PR is revalidated whenever
-`main` advances. It must require these exact contexts and no legacy aliases:
+`main` advances. Every entry must select the GitHub Actions App
+(`integration_id=15368`), not “any source”. It must require these exact
+context/source pairs and no legacy aliases:
 
 - `Lint`
 - `Test`
@@ -265,4 +435,11 @@ unproducible required context.
 
 The branch ruleset also requires one approval after the latest push. Enable
 repository auto-merge and automatic head-branch deletion; keep the base-owned
-reviewer router outside the required-context list.
+reviewer router outside the required-context list. Install its dedicated
+GitHub App only on this repository with `Contents: read and write` and `Pull
+requests: read and write`; do not grant Actions, Workflows, or Administration.
+Give it pull-request-only bypass on `main-merge-writers` and no bypass on any
+other ruleset. Store the App client ID and lowercase slug in repository
+variables `REVIEWER_ROUTER_APP_CLIENT_ID` and `REVIEWER_ROUTER_APP_SLUG`, and
+its private key in repository secret `REVIEWER_ROUTER_APP_PRIVATE_KEY`. Do not
+reuse release, Homebrew, or personal tokens for this boundary.

docs/rfc-command-framework-convergence.md

@@ -274,6 +274,7 @@ Definition（仅声明；不可编译）
 | 层 | 含义 | 今日落点 |
 |---|---|---|
 | **声明（declare）** | `corecmd.Spec` / `LeafSpec` / `ContractDecl` **数据字段**（声明证据；交付见下） | `Flags`/`Constraints`/`Risk`/`ConstParams`/`Contract`；类型真身在 `corecmd/contract`（DTO：`SafetySpec`/`ParamDecl`/`ProductDecl`/`ContractFinalPayload`；**无** Cobra store） |
+| **非叶声明（group declare）** | owning Cobra 命令上的完整 `corecmd.GroupPolicy`；不是 leaf `Spec` 字段 | `Mode` / `Positionals` / `Recovery` 经 `corecmd.ApplyGroupPolicy` 一次编译为 Cobra 行为与私有框架元数据 |
 | **框架转换** | 类型转换并注册（**禁止** JSON 注解桥） | `embedContractDecl` → `corecmd/contractfinal.RegisterRuntimeContractFinal`（annotate + store；全部调用方直调，`corecmd.New` 内部注册） |
 | **注解 seam** | Cobra `dws.schema.*` 写入 | `internal/corecmd/runtimeannotate.AnnotateRuntime*`（框架侧；`cli` 根经 `runtime_schema_seam.go` 包内别名访问；`cli/runtimeannotate` 垫片包已删，一律直引 corecmd） |
 | **Schema 透传** / 交付 | 组装读取注册表，原样投影为 `ToolSpec`；`RegisterSchemaSourceRoot` → `ResolveSchemaBuild`（`ResolveMeta` 自同一组装投影）；go:embed 仅限 reviewed 输入（MCP meta / `param_concepts` 等；reviewed `schema_command_registry/` 已退役，identity 由 collector 收集），映射排除走 Go ledger（`schema_parameter_mapping_ledger.go`），不得 embed Catalog | `internal/cli` 根（交付边界）；ContractFinal store 在 `corecmd/contractfinal`（`cli` 根经 `runtime_schema_seam.go` 包内别名访问；`cli/contractfinal` 垫片包已删） |
@@ -310,7 +311,25 @@ Definition（仅声明；不可编译）
 3. 写副作用：新 Leaf 声明完整 `SafetySpec`（框架 `ConfirmSafety` + Schema Final）；未迁移旧路径显式标注 `runtime_gate`；二者皆无则不合格；
 4. Schema `ToolSpec` 全字段组均落在 §5.0.4 表中某一权威格，禁止无主字段。
 
-#### 5.0.2a 三档声明路径（Tier1 / Tier2 / Tier3）
+#### 5.0.2a 非叶命令契约（`corecmd.GroupPolicy`）
+
+`corecmd.Spec` / `LeafSpec` 继续只定义叶命令。每个拥有子命令的 owning Cobra 命令必须在构造处通过 `corecmd.ApplyGroupPolicy` 声明一份完整 `GroupPolicy`：
+
+| 轴 | 允许值 | 语义 |
+|---|---|---|
+| `Mode` | `navigation_only` / `hybrid` | 仅导航并展示帮助，或同时保留本命令业务执行 |
+| `Positionals` | `reject` / `allow` | 未匹配 token 进入命令恢复，或由本命令业务位置参数消费 |
+| `Recovery` | `sibling` / `deep` / `disabled` | 只建议直接子命令、显式允许后代路径恢复，或完全关闭恢复 |
+
+硬规则：
+
+1. 三个字段必须同时声明；全零值只表示 leaf，不能应用到命令。`navigation_only` 必须 `Positionals=reject`；`Positionals=allow` 必须 `Recovery=disabled`，避免业务 argv 与命令恢复争抢同一 token。
+2. `ApplyGroupPolicy` 是唯一编译入口：navigation 安装统一 help/错误 handler；hybrid 保留 owning `RunE`，仅在声明拒绝 positionals 且开启恢复时包裹 unknown-command 分支。恢复统一投影为有界 `CommandResolution`（最多 3 个建议 + 当前 parent `--help`）；只有 `Recovery=deep` 才可建议完整后代路径。
+3. `GroupPolicy` **不推导** `TraverseChildren`。该 Cobra 字段会改变父级 local flag 是否向子命令传播，必须由原 owning command 显式保留，不能因迁移到 typo guidance 而扩大参数表面。
+4. 最终装配树门禁检查「有 children 必须有 GroupPolicy、leaf 不得残留 GroupPolicy、navigation/hybrid handler 与声明结构一致」。门禁不执行任意 `Args` 函数；`ApplyGroupPolicy` 对 `cobra.NoArgs` / `cobra.ArbitraryArgs` 的编译由 corecmd 单测覆盖。
+5. 命令树合并时，两侧非空 group 都必须先声明 policy；冲突声明、group 与 runnable/parse-bearing leaf 合并、或带 children 的未声明节点均 fail closed。纯 metadata 空壳可采用 typed source policy，不能借此吞掉 flags、hooks 或执行体。
+
+#### 5.0.2b 三档叶声明路径（Tier1 / Tier2 / Tier3）
 
 当前生产允许的三档路径（同一 `ContractFinal` 语义；不是互相否定）：
 

docs/shortcut-public-catalog.json

@@ -1,7 +1,57 @@
 {
-  "generated_at": "2026-08-24T12:22:05.108140",
-  "count": 426,
+  "generated_at": "2026-08-24T20:14:49.172788",
+  "count": 437,
   "results": [
+    {
+      "suite": "semantic",
+      "service": "agoal",
+      "command": "+contract-fields",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、字段数组和每项稳定 id；本地 keyword 覆盖字段标识、编码、标题、分类和类型，支持已知非空与保证零命中。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "agoal",
+      "command": "+obj-template-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、result 数组、稳定模板 ID 及 page/pageSize/totalCount；不虚构 cursor。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "agoal",
+      "command": "+report-statistics-list",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、content 数组和每项稳定 templateId；关键词同时支持已知非空与合法零命中。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "agoal",
+      "command": "+report-submit-detail",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、嵌套稳定用户身份及 page/pageSize/totalCount；下游忽略 keyword，因此做有界全量遍历、本地过滤、停滞/重复/总数变化失败与人员字段最小投影。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "agoal",
+      "command": "+user-rules",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、content 对象、rules 数组和稳定 ruleId；本地精确 ruleId 选择器支持已知非空与保证零命中。",
+      "availability": "available"
+    },
     {
       "suite": "semantic",
       "service": "aisearch",
@@ -2473,137 +2523,254 @@
       "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+create",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "创建后提取稳定 unifiedAppId，并以同一 ID 读回名称及请求字段；只有精确核验通过才返回成功。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+credentials-get",
+      "risk": "read",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格要求 success、稳定 unifiedAppId、非空客户端标识和非空 secret；Result 将密钥路径声明为敏感。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "devapp",
       "command": "+delete",
       "risk": "high-risk-write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "删除前读回稳定 appKey，删除后按该选择器有界遍历全部页并证明同一 unifiedAppId 不再存在。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+disable",
-      "risk": "write",
-      "status": "real-ok"
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "停用后按同一 unifiedAppId 读回并要求 appStatus=disabled。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+enable",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "启用后按同一 unifiedAppId 读回并要求 appStatus=normal。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+event-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、事件数组、每项稳定 eventCode 与游标终止证据；明确返回可用事件目录及订阅状态，并拒绝坏元素与伪空结果。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+event-subscribe",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空值与重复 eventCode，写后有界遍历订阅列表并逐项精确读回。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "devapp",
       "command": "+get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空响应、缺失 success 和空业务对象，并要求读回 unifiedAppId 与请求精确一致。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、应用数组、稳定 unifiedAppId 与游标终止证据；投影当前页并保留可续翻 meta.pagination。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+member-add",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空值和重复 userId，校验写终态后按稳定 userId 逐项精确读回，并要求 memberType 与请求角色一致。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+member-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、成员数组和每项稳定 userId；新增本地精确 userId 选择器以证明已知非空与保证零命中。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+member-remove",
-      "risk": "write",
-      "status": "real-ok"
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空值和重复 userId，校验写终态后读取完整成员数组，并逐项证明目标稳定 userId 已不存在。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+permission-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、权限数组、每项稳定 scopeValue 与游标终止证据，拒绝坏元素和伪空结果。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+robot-config",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空配置，写后按同一 unifiedAppId 读取机器人对象并精确比较全部请求标量字段。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+robot-disable",
+      "risk": "high-risk-write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "要求写终态成功并读回 robotStatus=UNCONFIGURED；不虚构保留配置或可直接恢复语义。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+robot-enable",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "要求写终态成功并按同一 unifiedAppId 读回 robotStatus=ONLINE。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "devapp",
       "command": "+robot-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证非空机器人配置对象，并要求读回 unifiedAppId 与请求精确一致。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+update",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "要求至少一个更新字段，写入后按同一 unifiedAppId 精确读回所有请求字段。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+version-check-approval",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "只执行 precheckOnly，严格绑定应用与版本身份，并保留可执行后续动作的 pending 结果。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
+      "service": "devapp",
+      "command": "+version-create",
+      "risk": "write",
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "创建回执必须含稳定 versionId，随后以 unifiedAppId/versionId 双身份读取详情并核验请求字段；live fixture 通过删除临时父应用清理。",
+      "availability": "available"
+    },
+    {
+      "suite": "semantic",
       "service": "devapp",
       "command": "+version-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证非空版本对象，并要求 unifiedAppId 和 versionId 同时与请求精确一致。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+version-list",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证 success、版本数组、每项稳定 versionId 与游标终止证据。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+version-status",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证非空发布状态对象，并要求 unifiedAppId 和 versionId 同时与请求精确一致。",
+      "availability": "available"
     },
     {
-      "suite": "write",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+webapp-config",
       "risk": "write",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "拒绝空更新，写入后按同一 unifiedAppId 读取网页配置并精确比较全部请求字段。",
+      "availability": "available"
     },
     {
-      "suite": "read",
+      "suite": "semantic",
       "service": "devapp",
       "command": "+webapp-get",
       "risk": "read",
-      "status": "real-ok"
+      "status": "reviewed_available",
+      "disposition": "semantic_adapter",
+      "semantic_delta": "严格验证非空网页配置对象，并要求读回 unifiedAppId 与请求精确一致。",
+      "availability": "available"
     },
     {
       "suite": "semantic",

internal/app/coverage_edges_test.go

@@ -380,7 +380,7 @@ func TestCrossPlatformCoverageDirectRuntimeCoverage(t *testing.T) {
 	if normalizeDirectRuntimeProductID("alias") != "one" || normalizeDirectRuntimeProductID("tb") != "teambition" || normalizeDirectRuntimeProductID("plain") != "plain" {
 		t.Fatal("direct runtime alias mismatch")
 	}
-	if ids := DirectRuntimeProductIDs(); !ids["one"] || !ids[defaultPATProductID] || !ids[devappProductID] {
+	if ids := DirectRuntimeProductIDs(); !ids["one"] || !ids[defaultPATProductID] || !ids[devappProductID] || !ids[recruitProductID] {
 		t.Fatalf("direct runtime IDs = %#v", ids)
 	}
 

internal/app/direct_runtime.go

@@ -46,6 +46,7 @@ const (
 	defaultPATServerID    = "abc3c880fb90f04b52d1426aaf093766e5fc9ec38411688cbb74df42a584d374"
 	devappProductID       = "devapp"
 	devappServerPath      = "/server/op-app"
+	recruitProductID      = "recruit"
 )
 
 // devappMCPEndpoint resolves the open-platform app-management MCP endpoint
@@ -400,9 +401,10 @@ func DirectRuntimeProductIDs() map[string]bool {
 	dynamicMu.RLock()
 	defer dynamicMu.RUnlock()
 
-	ids := make(map[string]bool, len(dynamicProducts)+2)
+	ids := make(map[string]bool, len(dynamicProducts)+3)
 	ids[defaultPATProductID] = true
 	ids[devappProductID] = true
+	ids[recruitProductID] = true
 	for key := range dynamicProducts {
 		ids[key] = true
 	}

internal/app/group_policy_tree_test.go

@@ -0,0 +1,55 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package app
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+// TestCrossPlatformCoverageFinalCommandTreesDeclareGroupPolicy replaces the
+// old helpers-only AST scan with an invariant over the two real assembly
+// products: the deterministic distribution tree and a runtime tree after a
+// nested plugin overlay has been merged.
+func TestCrossPlatformCoverageFinalCommandTreesDeclareGroupPolicy(t *testing.T) {
+	distribution := NewSchemaSourceRootCommand()
+	for _, path := range []string{
+		"sheet range read",
+		"pat chmod",
+		"plugin list",
+		"chat +chat-messages",
+	} {
+		requireFinalCommandPath(t, distribution, path)
+	}
+	if err := cobracmd.ValidateGroupTree(distribution); err != nil {
+		t.Fatalf("distribution command tree GroupPolicy invariant: %v", err)
+	}
+
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	testseam.Swap(t, &rootLoadPlugins, func(root *cobra.Command, _ *pipeline.Engine, runner executor.Runner) []*cobra.Command {
+		descriptor := conferencePluginDescriptor()
+		return buildPluginCommands([]mcptypes.ServerDescriptor{descriptor}, runner, root)
+	})
+	runtime := NewRootCommand()
+	requireFinalCommandPath(t, runtime, "conference camera open")
+	if err := cobracmd.ValidateGroupTree(runtime); err != nil {
+		t.Fatalf("runtime command tree GroupPolicy invariant: %v", err)
+	}
+}
+
+func requireFinalCommandPath(t *testing.T, root *cobra.Command, path string) *cobra.Command {
+	t.Helper()
+	command, remaining, err := root.Find(strings.Fields(path))
+	if err != nil || command == nil || len(remaining) != 0 || command == root {
+		t.Fatalf("final command path %q not assembled: command=%v remaining=%v err=%v", path, command, remaining, err)
+	}
+	return command
+}

internal/app/mcp_url_command.go

@@ -21,6 +21,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
@@ -43,6 +44,11 @@ func newMCPURLGroup(caller edition.ToolCaller) *cobra.Command {
 			return cmd.Help()
 		},
 	}
+	corecmd.ApplyGroupPolicy(group, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
 	group.AddCommand(newMCPURLGetCommand(caller))
 	return group
 }

internal/app/param_alias_payload_equivalence_test.go

@@ -237,11 +237,25 @@ var paramAliasCompleteCommands = map[string][]string{
 // param_concepts.json: inactive candidate templates are ignored, while every
 // command becomes mandatory as soon as one of its reviewed aliases is active.
 var paramAliasCandidateCompleteCommands = map[string][]string{
+	"agoal contract detail":                {"agoal", "contract", "detail", "--contract-id", "contract-1"},
+	"agoal contract update":                {"agoal", "contract", "update", "--contract-id", "contract-1", "--dimensions", `[{"id":"dimension-1","title":"Fixture Dimension","weight":100,"objectives":[]}]`},
+	"agoal obj-template create-or-update":  {"agoal", "obj-template", "create-or-update", "--template-id", "template-1", "--dimensions", `[{"title":"Fixture Dimension","weight":100}]`},
+	"agoal obj-template list":              {"agoal", "obj-template", "list", "--keyword", "fixture", "--page", "2", "--page-size", "7"},
+	"agoal report list-statistics":         {"agoal", "report", "list-statistics", "--keyword", "Fixture Rule"},
+	"agoal report submit-detail":           {"agoal", "report", "submit-detail", "--template-id", "template-1", "--submit-state", "ON_TIME", "--query-date", "2026-06-18T00:00:00+08:00"},
+	"agoal scorecard detail":               {"agoal", "scorecard", "detail", "--dept-id", "dept-1", "--selected-time", "2026-01-01T00:00:00+08:00"},
+	"agoal scorecard entity-detail":        {"agoal", "scorecard", "entity-detail", "--sc-id", "scorecard-1", "--entity-id", "entity-1"},
+	"agoal strategy detail":                {"agoal", "strategy", "detail", "--profile-id", "profile-1"},
+	"agoal user objectives":                {"agoal", "user", "objectives", "--user-id", "user-1", "--rule-id", "rule-1", "--period-ids", "period-1,period-2"},
+	"agoal user rules":                     {"agoal", "user", "rules", "--user-id", "user-1"},
 	"aisearch":                             {"aisearch", "--query", "Fixture User", "--dimension", "name"},
 	"aisearch +search-person":              {"aisearch", "+search-person", "--query", "Fixture User", "--dimensions", "name"},
 	"aisearch behavior":                    {"aisearch", "behavior", "--queries", "fixture", "--types", "im", "--behavior-type", "send", "--chat-scope", "Fixture Group", "--direction", "我->Fixture User", "--time-range", "本周"},
 	"aisearch enterprise":                  {"aisearch", "enterprise", "--queries", "fixture", "--types", "document", "--time-range", "本周"},
 	"aisearch person":                      {"aisearch", "person", "--query", "Fixture User", "--dimension", "name"},
+	"audit export":                         {"audit", "export", "--since", "2026-03-01", "--until", "2026-03-10", "--format", "jsonl", "--output", "/tmp/dws-audit-export-fixture.jsonl"},
+	"audit tail":                           {"audit", "tail", "--lines", "7", "--output", "/tmp/dws-audit-tail-fixture.jsonl"},
+	"audit verify":                         {"audit", "verify", "--file", "../../go.mod", "--output", "/tmp/dws-audit-verify-fixture.json"},
 	"contact +by-mobile":                   {"contact", "+by-mobile", "--mobile", "13800138000"},
 	"contact +list-dept-members":           {"contact", "+list-dept-members", "--depts", "1,2"},
 	"contact +list-followings":             {"contact", "+list-followings", "--open-id", "open-fixture-1"},
@@ -267,7 +281,66 @@ var paramAliasCandidateCompleteCommands = map[string][]string{
 	"contact user update":                  {"contact", "user", "update", "--user-id", "user-1", "--org-user-name", "Fixture User", "--depts", `[{"deptId":1}]`, "--yes"},
 	"contact user update-ownness":          {"contact", "user", "update-ownness", "--user-id", "user-1", "--ownness-text", "Fixture Status", "--yes"},
 	"contact user update-self":             {"contact", "user", "update-self", "--avatar-file-id", "file-1", "--nick", "Fixture Nick", "--yes"},
+	"dev app create":                       {"dev", "app", "create", "--name", "Fixture App", "--desc", "Fixture Description", "--yes"},
+	"dev app credentials get":              {"dev", "app", "credentials", "get", "--unified-app-id", "app-1"},
+	"dev app delete":                       {"dev", "app", "delete", "--unified-app-id", "app-1", "--confirm-name", "Fixture App", "--yes"},
+	"dev app disable":                      {"dev", "app", "disable", "--unified-app-id", "app-1", "--yes"},
+	"dev app enable":                       {"dev", "app", "enable", "--unified-app-id", "app-1", "--yes"},
+	"dev app event list":                   {"dev", "app", "event", "list", "--unified-app-id", "app-1", "--cursor", "cursor-1"},
+	"dev app event subscribe":              {"dev", "app", "event", "subscribe", "--unified-app-id", "app-1", "--event-codes", "chat_message_received", "--yes"},
+	"dev app event unsubscribe":            {"dev", "app", "event", "unsubscribe", "--unified-app-id", "app-1", "--event-codes", "chat_message_received", "--yes"},
+	"dev app list":                         {"dev", "app", "list", "--robot-name", "Fixture Robot"},
+	"dev app member add":                   {"dev", "app", "member", "add", "--unified-app-id", "app-1", "--member-type", "DEVELOPER", "--user-ids", "user-1,user-2", "--yes"},
+	"dev app member list":                  {"dev", "app", "member", "list", "--unified-app-id", "app-1"},
+	"dev app member remove":                {"dev", "app", "member", "remove", "--unified-app-id", "app-1", "--member-type", "DEVELOPER", "--user-ids", "user-1,user-2", "--yes"},
+	"dev app permission add":               {"dev", "app", "permission", "add", "--unified-app-id", "app-1", "--scope-values", "Contact.User.Read", "--yes"},
+	"dev app permission remove":            {"dev", "app", "permission", "remove", "--unified-app-id", "app-1", "--scope-values", "Contact.User.Read", "--yes"},
+	"dev app robot config":                 {"dev", "app", "robot", "config", "--unified-app-id", "app-1", "--i18n-description", `{"zh_CN":"Fixture Robot"}`, "--yes"},
+	"dev app robot disable":                {"dev", "app", "robot", "disable", "--unified-app-id", "app-1", "--yes"},
+	"dev app robot enable":                 {"dev", "app", "robot", "enable", "--unified-app-id", "app-1", "--yes"},
+	"dev app robot get":                    {"dev", "app", "robot", "get", "--unified-app-id", "app-1"},
+	"dev app robot result":                 {"dev", "app", "robot", "result", "--task-id", "task-1"},
+	"dev app robot submit":                 {"dev", "app", "robot", "submit", "--name", "Fixture Agent", "--desc", "Fixture robot description", "--robot-name", "Fixture Robot", "--yes"},
+	"dev app security config":              {"dev", "app", "security", "config", "--unified-app-id", "app-1", "--redirect-urls", "https://example.test/callback", "--yes"},
+	"dev app update":                       {"dev", "app", "update", "--unified-app-id", "app-1", "--name", "Fixture App", "--desc", "Fixture Description", "--yes"},
+	"dev app version check-approval":       {"dev", "app", "version", "check-approval", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"dev app version create":               {"dev", "app", "version", "create", "--unified-app-id", "app-1", "--version", "1.0.1", "--desc", "Fixture Version", "--yes"},
+	"dev app version get":                  {"dev", "app", "version", "get", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"dev app version list":                 {"dev", "app", "version", "list", "--unified-app-id", "app-1", "--cursor", "cursor-1"},
+	"dev app version publish":              {"dev", "app", "version", "publish", "--unified-app-id", "app-1", "--version-id", "version-1", "--yes"},
+	"dev app version status":               {"dev", "app", "version", "status", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"dev app webapp config":                {"dev", "app", "webapp", "config", "--unified-app-id", "app-1", "--pc-homepage-url", "https://example.test/app", "--yes"},
+	"dev app webapp get":                   {"dev", "app", "webapp", "get", "--unified-app-id", "app-1"},
+	"dev connect restart":                  {"dev", "connect", "restart", "--robot-client-id", "robot-client-1"},
+	"dev connect status":                   {"dev", "connect", "status", "--robot-client-id", "robot-client-1"},
+	"dev connect stop":                     {"dev", "connect", "stop", "--robot-client-id", "robot-client-1"},
+	"dev doc search":                       {"dev", "doc", "search", "--query", "fixture", "--page", "2"},
 	"devdoc +search-docs":                  {"devdoc", "+search-docs", "--query", "fixture", "--page", "2", "--size", "7"},
+	"devapp +create":                       {"devapp", "+create", "--name", "Fixture App", "--desc", "Fixture Description", "--yes"},
+	"devapp +delete":                       {"devapp", "+delete", "--unified-app-id", "app-1", "--yes"},
+	"devapp +disable":                      {"devapp", "+disable", "--unified-app-id", "app-1", "--yes"},
+	"devapp +enable":                       {"devapp", "+enable", "--unified-app-id", "app-1", "--yes"},
+	"devapp +event-list":                   {"devapp", "+event-list", "--unified-app-id", "app-1", "--cursor", "cursor-1"},
+	"devapp +get":                          {"devapp", "+get", "--unified-app-id", "app-1"},
+	"devapp +list":                         {"devapp", "+list", "--app-key", "app-key-1"},
+	"devapp +member-add":                   {"devapp", "+member-add", "--unified-app-id", "app-1", "--member-type", "DEVELOPER", "--user-ids", "user-1,user-2", "--yes"},
+	"devapp +member-list":                  {"devapp", "+member-list", "--unified-app-id", "app-1", "--user-id", "user-1"},
+	"devapp +member-remove":                {"devapp", "+member-remove", "--unified-app-id", "app-1", "--member-type", "DEVELOPER", "--user-ids", "user-1,user-2", "--yes"},
+	"devapp +permission-list":              {"devapp", "+permission-list", "--unified-app-id", "app-1", "--api-status", "PUBLISHED", "--scope-type", "APP"},
+	"devapp +robot-get":                    {"devapp", "+robot-get", "--unified-app-id", "app-1"},
+	"devapp +update":                       {"devapp", "+update", "--unified-app-id", "app-1", "--name", "Fixture App", "--desc", "Fixture Description", "--yes"},
+	"devapp +version-check-approval":       {"devapp", "+version-check-approval", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"devapp +version-get":                  {"devapp", "+version-get", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"devapp +version-list":                 {"devapp", "+version-list", "--unified-app-id", "app-1", "--cursor", "cursor-1"},
+	"devapp +version-status":               {"devapp", "+version-status", "--unified-app-id", "app-1", "--version-id", "version-1"},
+	"devapp +webapp-config":                {"devapp", "+webapp-config", "--unified-app-id", "app-1", "--pc-homepage-url", "https://example.test/app", "--yes"},
+	"devapp +webapp-get":                   {"devapp", "+webapp-get", "--unified-app-id", "app-1"},
+	"event +listen-im":                     {"event", "+listen-im", "--user", "user-1", "--events", "message,reaction", "--query", "fixture", "--duration", "1s", "--max-events", "1"},
+	"event consume":                        {"event", "consume", "--subscribe-id", "subscription-1", "--user", "user-1", "--group", "fixture-conversation", "--query", "fixture", "--output-dir", "/tmp/dws-event-fixture", "--filter-json", `{"rules":[]}`},
+	"event list":                           {"event", "list", "--category", "im", "--include-pending"},
+	"event schema":                         {"event", "schema", "--flatten"},
+	"event status":                         {"event", "status", "--event", "im_message_received", "--status", "active", "--subscribe-id", "subscription-1"},
+	"event stop":                           {"event", "stop", "--all", "--yes"},
 	"hrbrain +get-pool":                    {"hrbrain", "+get-pool", "--pool-code", "pool-1"},
 	"hrbrain +list-pool-employees":         {"hrbrain", "+list-pool-employees", "--pool-code", "pool-1", "--page", "2", "--page-size", "7"},
 	"hrbrain +list-pools":                  {"hrbrain", "+list-pools", "--keyword", "fixture", "--labels", "label-a,label-b", "--page", "2", "--page-size", "7"},
@@ -335,6 +408,9 @@ var paramAliasCandidateCompleteCommands = map[string][]string{
 	"report +outbox-list":                  {"report", "+outbox-list", "--size", "7"},
 	"report +report-latest":                {"report", "+report-latest", "--keyword", "Fixture", "--start", "2026-03-01T00:00:00+08:00", "--end", "2026-03-10T00:00:00+08:00"},
 	"report +template-search":              {"report", "+template-search", "--query", "fixture"},
+	"recruit job create":                   {"recruit", "job", "create", "--from", "testdata/recruit_job.json", "--yes"},
+	"recruit job get":                      {"recruit", "job", "get", "--job-id", "job-1"},
+	"recruit job list":                     {"recruit", "job", "list", "--job-ids", "job-1,job-2", "--creator-user-ids", "user-1,user-2", "--keyword", "fixture", "--cursor", "cursor-1", "--size", "7"},
 	"sheet +list-sheets":                   {"sheet", "+list-sheets", "--node", "node-1"},
 	"sheet +read":                          {"sheet", "+read", "--node", "node-1", "--sheet-id", "Sheet1"},
 
@@ -397,6 +473,18 @@ var paramAliasCandidateCompleteCommands = 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{
+	"dev app get": {
+		"app-key": {"dev", "app", "get", "--app-key", "app-key-1"},
+	},
+	"event +listen-im": {
+		"open-dingtalk-id": {"event", "+listen-im", "--open-dingtalk-id", appFixtureCurrentDOpenID, "--events", "message,reaction", "--query", "fixture", "--duration", "1s", "--max-events", "1"},
+		"user-query":       {"event", "+listen-im", "--user-query", "Fixture User", "--events", "message,reaction", "--query", "fixture", "--duration", "1s", "--max-events", "1"},
+		"chat-id":          {"event", "+listen-im", "--chat-id", "fixture-conversation", "--events", "message,reaction", "--query", "fixture", "--duration", "1s", "--max-events", "1"},
+		"chat-query":       {"event", "+listen-im", "--chat-query", "Fixture Group", "--events", "message,reaction", "--query", "fixture", "--duration", "1s", "--max-events", "1"},
+	},
+	"event consume": {
+		"open-dingtalk-id": {"event", "consume", "--subscribe-id", "subscription-1", "--open-dingtalk-id", appFixtureCurrentDOpenID, "--group", "fixture-conversation", "--query", "fixture", "--output-dir", "/tmp/dws-event-fixture", "--filter-json", `{"rules":[]}`},
+	},
 	"markdown create": {
 		"file": {"markdown", "create", "--file", "../../README.md", "--name", "fixture.md", "--space-id", "space-1"},
 	},
@@ -1106,7 +1194,8 @@ func TestCrossPlatformCoverageReviewedProductTemplatedParamAliasesCannotBypassCo
 		product, _, _ := strings.Cut(fixture.Command, " ")
 		switch product {
 		case "attendance", "mail", "oa", "ding", "report", "sheet", "whiteboard", "markdown",
-			"aisearch", "contact", "live", "devdoc", "hrbrain", "pat":
+			"aisearch", "contact", "live", "devdoc", "hrbrain", "pat",
+			"agoal", "audit", "dev", "devapp", "event", "mcp", "recruit":
 		default:
 			continue
 		}
@@ -1502,7 +1591,7 @@ func paramAliasExpectedCaptureBoundaryError(command string, err error) bool {
 	case "chat +messages-resource-download":
 		return strings.Contains(err.Error(), "资源下载接口未返回合法的 HTTPS 下载地址")
 	case "drive +download", "drive +version-download":
-		return strings.Contains(err.Error(), "下载地址必须是受信任域名上的 HTTPS URL")
+		return strings.Contains(err.Error(), "下载地址必须是合法的 HTTPS URL")
 	case "drive +upload":
 		return strings.Contains(err.Error(), "incomplete drive upload credentials")
 	default:

internal/app/plugin_commands.go

@@ -24,6 +24,7 @@ import (
 	"unicode"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
@@ -747,7 +748,11 @@ func pruneEmptyPluginGroups(parent *cobra.Command) {
 	}
 	for _, child := range append([]*cobra.Command(nil), parent.Commands()...) {
 		pruneEmptyPluginGroups(child)
-		if cmdutil.IsGroup(child) && len(child.Commands()) == 0 {
+		_, group, err := corecmd.GroupPolicyFor(child)
+		if err != nil {
+			panic(fmt.Sprintf("prune plugin group %q: %v", child.CommandPath(), err))
+		}
+		if group && len(child.Commands()) == 0 {
 			parent.RemoveCommand(child)
 		}
 	}

internal/app/plugin_commands_coverage_test.go

@@ -12,6 +12,7 @@ import (
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cobracmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
@@ -30,6 +31,42 @@ func (pluginWrongFlagValue) String() string   { return "" }
 func (pluginWrongFlagValue) Set(string) error { return nil }
 func (pluginWrongFlagValue) Type() string     { return "wrong" }
 
+func TestCrossPlatformCoveragePruneEmptyPluginGroupsRejectsMalformedPolicy(t *testing.T) {
+	emptyParent := &cobra.Command{Use: "plugin"}
+	emptyGroup := &cobra.Command{Use: "empty"}
+	corecmd.ApplyGroupPolicy(emptyGroup, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
+	emptyParent.AddCommand(emptyGroup)
+	pruneEmptyPluginGroups(emptyParent)
+	if len(emptyParent.Commands()) != 0 {
+		t.Fatalf("empty plugin group was not pruned: %#v", emptyParent.Commands())
+	}
+
+	parent := &cobra.Command{Use: "plugin"}
+	child := &cobra.Command{Use: "group"}
+	corecmd.ApplyGroupPolicy(child, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
+	for key := range child.Annotations {
+		child.Annotations[key] = "malformed"
+	}
+	parent.AddCommand(child)
+
+	defer func() {
+		got := recover()
+		message, ok := got.(string)
+		if !ok || !strings.Contains(message, "prune plugin group") {
+			t.Fatalf("pruneEmptyPluginGroups panic = %v", got)
+		}
+	}()
+	pruneEmptyPluginGroups(parent)
+}
+
 func TestPluginCompilerRejectsInvalidDuplicateAndEmptyDefinitions(t *testing.T) {
 	invalidRoot := conferencePluginDescriptor()
 	invalidRoot.CLI.Command = "Invalid Root"
@@ -507,7 +544,8 @@ func TestPluginConstraintGroupAndRootHelpers(t *testing.T) {
 	mergePluginRoot(nil, root)
 	mergePluginRoot(root, nil)
 	destination := &cobra.Command{Use: "plugin", Aliases: []string{"one"}}
-	source := &cobra.Command{Use: "plugin", Aliases: []string{"one", "two"}}
+	source := cobracmd.NewGroupCommand("plugin", "plugin")
+	source.Aliases = []string{"one", "two"}
 	source.AddCommand(&cobra.Command{Use: "leaf"})
 	mergePluginRoot(destination, source)
 	if !reflect.DeepEqual(destination.Aliases, []string{"one", "two"}) || requireOptionalPluginChild(destination, "leaf") == nil {

internal/app/preparse_presentation_test.go

@@ -17,6 +17,7 @@ import (
 	"bytes"
 	stderrors "errors"
 	"io"
+	"slices"
 	"strings"
 	"testing"
 
@@ -55,6 +56,44 @@ func TestCrossPlatformCoverageLeadingPersistentFlagVariantsReachTheRealCommand(t
 	}
 }
 
+func TestCrossPlatformCoverageFuzzyRootBooleanBetweenGroupAndLeafKeepsLeafPreParse(t *testing.T) {
+	root := NewSchemaSourceRootCommand()
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	args := []string{
+		"aisearch", "--query", "Alice", "--yess", "enterprise",
+		"--queries", "fixture", "--content-types", "document", "--time_range", "本周", "--help",
+	}
+	ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+	if err != nil {
+		t.Fatalf("RunPreParseArgs(%v) error = %v", args, err)
+	}
+	if ctx == nil || ctx.Command != "dws aisearch enterprise" ||
+		!slices.Contains(ctx.Args, "--yes") || !slices.Contains(ctx.Args, "--types") || !slices.Contains(ctx.Args, "--time-range") {
+		t.Fatalf("group-middle fuzzy flag skipped leaf PreParse: context=%#v", ctx)
+	}
+	if err := root.Execute(); err != nil {
+		t.Fatalf("corrected group-middle persistent flag failed: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageProtectedFlagChildNameValueStaysOnOwningCommand(t *testing.T) {
+	for _, args := range [][]string{
+		{"aisearch", "--types", "enterprise"},
+		{"aisearch", "--types", "false", "enterprise"},
+		{"aisearch", "--types=false", "enterprise"},
+	} {
+		root := NewSchemaSourceRootCommand()
+		ctx, err := pipeline.RunPreParseArgs(root, newPipelineEngine(), args)
+		if err != nil {
+			t.Fatalf("RunPreParseArgs(%v) error = %v", args, err)
+		}
+		if ctx == nil || ctx.Command != "dws aisearch" || !ctx.IsFlagProtected("types") || !slices.Equal(ctx.Args, args) {
+			t.Fatalf("protected child-name value selected wrong command: args=%v context=%#v", args, ctx)
+		}
+	}
+}
+
 func TestCrossPlatformCoveragePreParseConflictHonorsErrorPresentationFlags(t *testing.T) {
 	root := NewSchemaSourceRootCommand()
 	args := []string{
@@ -105,6 +144,7 @@ func TestCrossPlatformCoverageCommandResolutionPrecedesFlagErrorsOnProductionTre
 		args        []string
 		wantReason  string
 		wantCommand string
+		wantHint    string
 	}{
 		{
 			name:        "unknown shortcut",
@@ -118,6 +158,13 @@ func TestCrossPlatformCoverageCommandResolutionPrecedesFlagErrorsOnProductionTre
 			wantReason:  "unknown_subcommand",
 			wantCommand: "dws dev app",
 		},
+		{
+			name:        "unknown aisearch subcommand before protected flag",
+			args:        []string{"aisearch", "--query", "Alice", "enterprize", "--types", "enterprise", "--format", "json"},
+			wantReason:  "unknown_subcommand",
+			wantCommand: "dws aisearch",
+			wantHint:    "dws aisearch enterprise",
+		},
 	}
 
 	for _, test := range tests {
@@ -135,6 +182,9 @@ func TestCrossPlatformCoverageCommandResolutionPrecedesFlagErrorsOnProductionTre
 			if structured.Reason != test.wantReason || structured.ExitCode() != 3 {
 				t.Fatalf("structured error = %#v", structured)
 			}
+			if test.wantHint != "" && !strings.Contains(structured.Hint, test.wantHint) {
+				t.Fatalf("hint = %q, want %q", structured.Hint, test.wantHint)
+			}
 			if len(structured.AvailableFlags) != 0 || strings.Contains(structured.Message, "unknown flag") {
 				t.Fatalf("command error leaked flag classification: %#v", structured)
 			}

internal/app/profile_command_test.go

@@ -23,6 +23,7 @@ import (
 	"time"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	tea "github.com/charmbracelet/bubbletea"
 	"github.com/charmbracelet/lipgloss"
 	"github.com/spf13/cobra"
@@ -653,8 +654,11 @@ func TestAuthCommandDoesNotExposeSwitch(t *testing.T) {
 	if err == nil {
 		t.Fatalf("auth switch succeeded, want unknown command error\noutput:\n%s", out.String())
 	}
-	if !strings.Contains(err.Error(), `unknown command "switch" for "dws auth"`) {
-		t.Fatalf("error = %v, want auth switch unknown command", err)
+	var structured *apperrors.Error
+	if !errors.As(err, &structured) || structured.Reason != "unknown_subcommand" ||
+		structured.Message != `unknown subcommand "switch" for "dws auth"` ||
+		structured.Hint != "Run 'dws auth --help' for the full list" {
+		t.Fatalf("error = %#v, want bounded auth subcommand guidance", err)
 	}
 }
 

internal/app/retired_edu_vendor_extensions_test.go

@@ -0,0 +1,48 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRetiredEduVendorExtensionsAreAbsentFromRuntimeAndSchema(t *testing.T) {
+	products := []string{
+		"college-contact",
+		"edu-app",
+		"edu-contact",
+		"edu-familygroup",
+		"edu-group",
+	}
+
+	root := NewRootCommand()
+	for _, product := range products {
+		for _, command := range root.Commands() {
+			if command.Name() == product {
+				t.Fatalf("retired product command %q remains mounted", product)
+			}
+		}
+	}
+
+	retiredProducts := make(map[string]bool, len(products))
+	for _, product := range products {
+		retiredProducts[product] = true
+	}
+
+	snapshot := fullSchemaSnapshotForTest(t)
+	for _, product := range snapshot.Catalog["products"].([]map[string]any) {
+		productID, _ := product["id"].(string)
+		if retiredProducts[productID] {
+			t.Errorf("retired product %q remains in the Schema catalog", productID)
+		}
+	}
+	for canonicalPath := range snapshot.Tools {
+		for product := range retiredProducts {
+			if canonicalPath == product || strings.HasPrefix(canonicalPath, product+".") {
+				t.Errorf("retired Schema tool %q remains under product %q", canonicalPath, product)
+			}
+		}
+	}
+}

internal/app/root.go

@@ -30,6 +30,7 @@ import (
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
@@ -924,6 +925,11 @@ func newRootCommandWithMode(rootCtx context.Context, engine *pipeline.Engine, lo
 			return nil
 		},
 	}
+	corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
 
 	bindPersistentFlags(root, flags)
 
@@ -935,25 +941,42 @@ func newRootCommandWithMode(rootCtx context.Context, engine *pipeline.Engine, lo
 	patCaller := newRecordingToolCaller(newToolCallerAdapter(runner, flags))
 	mcpCmd.AddCommand(newMCPURLGroup(patCaller))
 
+	navigationGroup := func(command *cobra.Command) *cobra.Command {
+		corecmd.ApplyGroupPolicy(command, corecmd.GroupPolicy{
+			Mode:        corecmd.GroupNavigationOnly,
+			Positionals: corecmd.PositionalsReject,
+			Recovery:    corecmd.RecoverySibling,
+		})
+		return command
+	}
+	hybridGroup := func(command *cobra.Command) *cobra.Command {
+		corecmd.ApplyGroupPolicy(command, corecmd.GroupPolicy{
+			Mode:        corecmd.GroupHybrid,
+			Positionals: corecmd.PositionalsReject,
+			Recovery:    corecmd.RecoverySibling,
+		})
+		return command
+	}
+
 	utilityCommands := []*cobra.Command{
-		newAuthCommand(patCaller),
-		newProfileCommand(),
+		navigationGroup(newAuthCommand(patCaller)),
+		navigationGroup(newProfileCommand()),
 		newAPICommand(flags),
-		newSkillCommand(),
-		newCacheCommand(),
+		navigationGroup(newSkillCommand()),
+		hybridGroup(newCacheCommand()),
 		newCatalogCommand(),
-		newConfigCommand(),
+		navigationGroup(newConfigCommand()),
 		newDoctorCommand(),
-		newRecoveryCommand(),
-		newEventCommand(flags),
-		newAuditCommand(),
+		hybridGroup(newRecoveryCommand()),
+		navigationGroup(newEventCommand(flags)),
+		navigationGroup(newAuditCommand()),
 		newCompletionCommand(root),
 		newUpgradeCommand(),
 		newVersionCommand(),
 		newPluginCommand(),
-		usage.NewShortcutCommand(),
+		navigationGroup(usage.NewShortcutCommand()),
 		schemaCmd,
-		mcpCmd,
+		navigationGroup(mcpCmd),
 	}
 	root.AddCommand(utilityCommands...)
 

internal/app/root_help_test.go

@@ -145,8 +145,10 @@ func TestRootKeepsMainBranchChatCompatibilityCommands(t *testing.T) {
 		command.SilenceUsage = true
 		command.SetArgs(tc.args)
 		err := command.Execute()
-		if err == nil || !strings.Contains(err.Error(), "ambiguous command") || !strings.Contains(err.Error(), tc.hint) {
-			t.Fatalf("dws %s error = %v, want migration hint %q", strings.Join(tc.args, " "), err, tc.hint)
+		var structured *apperrors.Error
+		if !stderrors.As(err, &structured) || structured.Category != apperrors.CategoryValidation ||
+			structured.Reason != "unknown_subcommand" || !strings.Contains(structured.Hint, tc.hint) {
+			t.Fatalf("dws %s error = %#v, want migration hint %q", strings.Join(tc.args, " "), structured, tc.hint)
 		}
 	}
 

internal/app/schema_shortcut_contract_test.go

@@ -16,12 +16,12 @@ import (
 )
 
 const (
-	publicShortcutCount = 425
+	publicShortcutCount = 436
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including reviewed hidden compatibility and unavailable contracts.
-	schemaPublishedShortcutCount = 482
+	schemaPublishedShortcutCount = 493
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 425
+	publiclyDeliveredShortcutCount = 436
 )
 
 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {

internal/app/testdata/recruit_job.json

@@ -0,0 +1,21 @@
+{
+  "name": "Fixture Java Engineer",
+  "description": "Fixture backend development role",
+  "jobNature": "FULL-TIME",
+  "requiredEdu": 6,
+  "minSalary": 20000,
+  "maxSalary": 35000,
+  "creatorUserId": "creator-user-id",
+  "ownerUserIds": [
+    "owner-user-id-1",
+    "owner-user-id-2"
+  ],
+  "extData": {
+    "headCount": 1,
+    "fullTimeExtData": {
+      "salaryMonth": 12,
+      "minJobExperience": 1,
+      "maxJobExperience": 3
+    }
+  }
+}

internal/cobracmd/tree.go

@@ -16,9 +16,10 @@
 package cobracmd
 
 import (
+	"fmt"
 	"strings"
 
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
@@ -47,17 +48,14 @@ func NewGroupCommand(use, short string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               use,
 		Short:             short,
-		Args:              cobra.NoArgs,
 		TraverseChildren:  true,
 		DisableAutoGenTag: true,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return cmd.Help()
-		},
 	}
-	// Tag as a group container: its RunE only prints help, so cobra's
-	// Runnable() can't distinguish it from a real leaf — callers that need to
-	// collapse empty groups rely on this annotation.
-	cmdutil.MarkGroup(cmd)
+	corecmd.ApplyGroupPolicy(cmd, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
 	return cmd
 }
 
@@ -90,6 +88,7 @@ func MergeCommandTree(dst, src *cobra.Command) {
 	if dst == nil || src == nil {
 		return
 	}
+	mergeGroupPolicy(dst, src)
 	if dst.Short == "" || (IsGenericOverlayShort(dst.Short) && src.Short != "" && !IsGenericOverlayShort(src.Short)) {
 		dst.Short = src.Short
 	}
@@ -113,6 +112,137 @@ func MergeCommandTree(dst, src *cobra.Command) {
 	}
 }
 
+func mergeGroupPolicy(dst, src *cobra.Command) {
+	dstPolicy, dstOK, err := corecmd.GroupPolicyFor(dst)
+	if err != nil {
+		panic(fmt.Sprintf("destination command %q has invalid GroupPolicy: %v", dst.CommandPath(), err))
+	}
+	srcPolicy, srcOK, err := corecmd.GroupPolicyFor(src)
+	if err != nil {
+		panic(fmt.Sprintf("source command %q has invalid GroupPolicy: %v", src.CommandPath(), err))
+	}
+	if len(dst.Commands()) > 0 && !dstOK {
+		panic(fmt.Sprintf("destination command %q has children but no GroupPolicy", dst.CommandPath()))
+	}
+	if len(src.Commands()) > 0 && !srcOK {
+		panic(fmt.Sprintf("source command %q has children but no GroupPolicy", src.CommandPath()))
+	}
+	if dstOK && !srcOK {
+		if !isNeutralMergePlaceholder(src) {
+			panic(fmt.Sprintf("cannot merge runnable or behavior-bearing leaf command %q into typed group command %q",
+				src.CommandPath(), dst.CommandPath()))
+		}
+		return
+	}
+	if !dstOK && srcOK {
+		if !isNeutralMergePlaceholder(dst) {
+			panic(fmt.Sprintf("cannot merge typed group command %q into runnable or behavior-bearing leaf command %q",
+				src.CommandPath(), dst.CommandPath()))
+		}
+		corecmd.ApplyGroupPolicy(dst, srcPolicy)
+		return
+	}
+	if dstOK && srcOK && dstPolicy != srcPolicy {
+		// A NavigationOnly/Reject/Sibling source is the framework's neutral
+		// service scaffold (shortcuts and plugin overlays use it before being
+		// folded into an owning product root). The destination owns the merged
+		// command's default action and recovery scope, so preserve its policy.
+		// Any stronger source declaration would lose behavior during this
+		// destination-oriented merge and therefore fails closed.
+		if srcPolicy != (corecmd.GroupPolicy{
+			Mode:        corecmd.GroupNavigationOnly,
+			Positionals: corecmd.PositionalsReject,
+			Recovery:    corecmd.RecoverySibling,
+		}) {
+			panic(fmt.Sprintf("cannot merge command %q with conflicting GroupPolicy declarations: %+v != %+v",
+				dst.CommandPath(), dstPolicy, srcPolicy))
+		}
+		return
+	}
+}
+
+// isNeutralMergePlaceholder reports whether cmd contributes metadata only.
+// Such a shell may adopt (or be folded into) one typed group declaration.
+// Anything executable, parse-affecting, or child-bearing must declare its own
+// compatible GroupPolicy so tree assembly cannot silently discard behavior.
+func isNeutralMergePlaceholder(cmd *cobra.Command) bool {
+	if cmd == nil || len(cmd.Commands()) != 0 || cmd.Runnable() || cmd.Args != nil ||
+		cmd.PreRun != nil || cmd.PreRunE != nil || cmd.PostRun != nil || cmd.PostRunE != nil ||
+		cmd.PersistentPreRun != nil || cmd.PersistentPreRunE != nil ||
+		cmd.PersistentPostRun != nil || cmd.PersistentPostRunE != nil ||
+		cmd.TraverseChildren || cmd.DisableFlagParsing {
+		return false
+	}
+	hasFlags := false
+	cmd.LocalNonPersistentFlags().VisitAll(func(*pflag.Flag) { hasFlags = true })
+	cmd.PersistentFlags().VisitAll(func(*pflag.Flag) { hasFlags = true })
+	return !hasFlags
+}
+
+// ValidateGroupTree checks the final assembled Cobra tree rather than source
+// syntax. Every command with children must carry one valid typed GroupPolicy;
+// leaves must carry none. This catches dynamically assembled aliases, plugin
+// parents, and constructors outside any one source directory.
+func ValidateGroupTree(root *cobra.Command) error {
+	if root == nil {
+		return fmt.Errorf("cannot validate a nil command tree")
+	}
+	return validateGroupNode(root)
+}
+
+func validateGroupNode(cmd *cobra.Command) error {
+	policy, declared, err := corecmd.GroupPolicyFor(cmd)
+	if err != nil {
+		return fmt.Errorf("command %q has invalid GroupPolicy metadata: %w", cmd.CommandPath(), err)
+	}
+	children := cmd.Commands()
+	if len(children) == 0 {
+		if declared {
+			return fmt.Errorf("leaf command %q retains GroupPolicy %+v", cmd.CommandPath(), policy)
+		}
+		return nil
+	}
+	if !declared {
+		return fmt.Errorf("command %q has children but no GroupPolicy", cmd.CommandPath())
+	}
+	if !cmd.Runnable() {
+		return fmt.Errorf("group command %q with mode %q is not runnable", cmd.CommandPath(), policy.Mode)
+	}
+	if policy.Mode == corecmd.GroupNavigationOnly && (cmd.RunE == nil || cmd.Run != nil) {
+		return fmt.Errorf("navigation-only group %q does not retain framework help execution", cmd.CommandPath())
+	}
+	if policy.Mode == corecmd.GroupHybrid && cmd.RunE == nil {
+		return fmt.Errorf("hybrid group %q lost its business RunE", cmd.CommandPath())
+	}
+	if policy.Positionals == corecmd.PositionalsAllow && cmd.Args == nil {
+		return fmt.Errorf("group command %q allows positionals without an explicit Args contract", cmd.CommandPath())
+	}
+	if policy.Positionals == corecmd.PositionalsReject {
+		if cmd.Args == nil {
+			return fmt.Errorf("group command %q rejects positionals without compiled Args behavior", cmd.CommandPath())
+		}
+	}
+	if policy.Recovery == corecmd.RecoveryDeep && !hasAvailableDescendant(cmd) {
+		return fmt.Errorf("group command %q declares deep recovery without an available descendant", cmd.CommandPath())
+	}
+	for _, child := range children {
+		if err := validateGroupNode(child); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func hasAvailableDescendant(cmd *cobra.Command) bool {
+	for _, child := range cmd.Commands() {
+		if !child.IsAvailableCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
 // ShouldReplaceLeaf decides whether src should replace dst as a leaf command
 // based on override priority and local flag count.
 func ShouldReplaceLeaf(dst, src *cobra.Command) bool {

internal/cobracmd/tree_test.go

@@ -14,8 +14,10 @@
 package cobracmd
 
 import (
+	"strings"
 	"testing"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/spf13/cobra"
 )
 
@@ -143,20 +145,399 @@ func TestNewGroupCommand(t *testing.T) {
 		t.Fatalf("Short = %q, want %q", cmd.Short, "my group description")
 	}
 	if cmd.Args == nil {
-		t.Fatal("Args should be set (cobra.NoArgs)")
+		t.Fatal("Args should be set (cobra.ArbitraryArgs)")
 	}
-	// Verify Args rejects arguments.
-	if err := cmd.Args(cmd, []string{"extra"}); err == nil {
-		t.Fatal("expected Args to reject extra arguments")
+	// Args must reach the shared resolver instead of Cobra's generic arg error.
+	if err := cmd.Args(cmd, []string{"extra"}); err != nil {
+		t.Fatalf("Args intercepted command resolution: %v", err)
 	}
 	// Verify RunE is set and returns help (no error for valid invocation).
 	if cmd.RunE == nil {
 		t.Fatal("RunE should not be nil")
 	}
+	policy, ok, err := corecmd.GroupPolicyFor(cmd)
+	if err != nil || !ok || policy != (corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	}) {
+		t.Fatalf("GroupPolicyFor() = %+v, %v, %v", policy, ok, err)
+	}
 	// RunE calls cmd.Help() which should not error.
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatalf("RunE returned unexpected error: %v", err)
 	}
+	if err := cmd.RunE(cmd, []string{"extra"}); err == nil || !strings.Contains(err.Error(), "unknown subcommand") {
+		t.Fatalf("RunE typo error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageValidateGroupTree(t *testing.T) {
+	t.Run("valid final tree", func(t *testing.T) {
+		root := NewGroupCommand("dws", "root")
+		nested := NewGroupCommand("nested", "nested")
+		nested.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		root.AddCommand(nested)
+		if err := ValidateGroupTree(root); err != nil {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("nil tree", func(t *testing.T) {
+		if err := ValidateGroupTree(nil); err == nil || !strings.Contains(err.Error(), "nil") {
+			t.Fatalf("ValidateGroupTree(nil) = %v", err)
+		}
+	})
+
+	t.Run("children require declaration", func(t *testing.T) {
+		root := &cobra.Command{Use: "dws"}
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "no GroupPolicy") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("leaf rejects stale declaration", func(t *testing.T) {
+		leaf := NewGroupCommand("stale", "stale")
+		if err := ValidateGroupTree(leaf); err == nil || !strings.Contains(err.Error(), "retains GroupPolicy") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("deep policy on a leaf is still a stale group declaration", func(t *testing.T) {
+		leaf := &cobra.Command{Use: "stale-deep"}
+		corecmd.ApplyGroupPolicy(leaf, corecmd.GroupPolicy{
+			Mode: corecmd.GroupNavigationOnly, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		})
+		if err := ValidateGroupTree(leaf); err == nil || !strings.Contains(err.Error(), "retains GroupPolicy") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("declared group must stay runnable", func(t *testing.T) {
+		root := NewGroupCommand("dws", "root")
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		root.RunE = nil
+		root.Run = nil
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "not runnable") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("rejected positionals require compiled Args behavior", func(t *testing.T) {
+		root := NewGroupCommand("dws", "root")
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		root.Args = nil
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "compiled Args") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("allowed positionals require explicit Args contract", func(t *testing.T) {
+		root := &cobra.Command{Use: "dws", RunE: func(*cobra.Command, []string) error { return nil }}
+		corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+			Mode: corecmd.GroupHybrid, Positionals: corecmd.PositionalsAllow, Recovery: corecmd.RecoveryDisabled,
+		})
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "explicit Args") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("validation does not execute positional contracts", func(t *testing.T) {
+		calls := 0
+		root := &cobra.Command{
+			Use: "dws",
+			Args: func(*cobra.Command, []string) error {
+				calls++
+				return nil
+			},
+			RunE: func(*cobra.Command, []string) error { return nil },
+		}
+		corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+			Mode: corecmd.GroupHybrid, Positionals: corecmd.PositionalsAllow, Recovery: corecmd.RecoveryDisabled,
+		})
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		if err := ValidateGroupTree(root); err != nil {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+		if calls != 0 {
+			t.Fatalf("ValidateGroupTree executed Args %d times", calls)
+		}
+	})
+
+	t.Run("deep recovery requires available descendants", func(t *testing.T) {
+		root := &cobra.Command{Use: "dws"}
+		corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+			Mode: corecmd.GroupNavigationOnly, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		})
+		root.AddCommand(&cobra.Command{Use: "hidden", Hidden: true, RunE: func(*cobra.Command, []string) error { return nil }})
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "available descendant") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageValidateGroupTreeFailsClosedOnCorruption(t *testing.T) {
+	t.Run("malformed policy metadata", func(t *testing.T) {
+		root := &cobra.Command{
+			Use: "dws",
+			Annotations: map[string]string{
+				"dws.internal.corecmd.group_policy.v1": "malformed",
+			},
+		}
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "invalid GroupPolicy metadata") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("navigation-only execution hook changed", func(t *testing.T) {
+		root := NewGroupCommand("dws", "root")
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		root.RunE = nil
+		root.Run = func(*cobra.Command, []string) {}
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "does not retain framework help execution") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("hybrid business execution hook removed", func(t *testing.T) {
+		root := &cobra.Command{Use: "dws", RunE: func(*cobra.Command, []string) error { return nil }}
+		corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+			Mode: corecmd.GroupHybrid, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDisabled,
+		})
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		root.RunE = nil
+		root.Run = func(*cobra.Command, []string) {}
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), "lost its business RunE") {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("nested validation error is propagated", func(t *testing.T) {
+		root := NewGroupCommand("dws", "root")
+		root.AddCommand(NewGroupCommand("stale", "stale"))
+		if err := ValidateGroupTree(root); err == nil || !strings.Contains(err.Error(), `leaf command "dws stale" retains GroupPolicy`) {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+
+	t.Run("deep recovery accepts an available descendant", func(t *testing.T) {
+		root := &cobra.Command{Use: "dws"}
+		corecmd.ApplyGroupPolicy(root, corecmd.GroupPolicy{
+			Mode: corecmd.GroupNavigationOnly, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		})
+		root.AddCommand(&cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }})
+		if err := ValidateGroupTree(root); err != nil {
+			t.Fatalf("ValidateGroupTree() = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageMergeCommandTreeGroupPolicy(t *testing.T) {
+	t.Run("copies source declaration", func(t *testing.T) {
+		dst := &cobra.Command{Use: "root"}
+		src := NewGroupCommand("root", "source")
+		MergeCommandTree(dst, src)
+		policy, ok, err := corecmd.GroupPolicyFor(dst)
+		if err != nil || !ok || policy.Recovery != corecmd.RecoverySibling {
+			t.Fatalf("merged policy = %+v, %v, %v", policy, ok, err)
+		}
+	})
+
+	t.Run("typed destination accepts metadata-only source", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := &cobra.Command{Use: "root", Long: "source details"}
+		MergeCommandTree(dst, src)
+		if dst.Long != "source details" {
+			t.Fatalf("Long = %q", dst.Long)
+		}
+	})
+
+	t.Run("accepts identical declarations", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := NewGroupCommand("root", "source")
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("neutral scaffold preserves owning hybrid deep policy", func(t *testing.T) {
+		businessCalled := false
+		dst := &cobra.Command{
+			Use: "root",
+			RunE: func(*cobra.Command, []string) error {
+				businessCalled = true
+				return nil
+			},
+		}
+		want := corecmd.GroupPolicy{
+			Mode: corecmd.GroupHybrid, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		}
+		corecmd.ApplyGroupPolicy(dst, want)
+		dst.AddCommand(&cobra.Command{Use: "native", RunE: func(*cobra.Command, []string) error { return nil }})
+
+		src := NewGroupCommand("root", "neutral scaffold")
+		src.AddCommand(&cobra.Command{Use: "overlay", RunE: func(*cobra.Command, []string) error { return nil }})
+		MergeCommandTree(dst, src)
+
+		got, ok, err := corecmd.GroupPolicyFor(dst)
+		if err != nil || !ok || got != want {
+			t.Fatalf("merged owning policy = %+v, %v, %v; want %+v", got, ok, err, want)
+		}
+		if ChildByName(dst, "overlay") == nil {
+			t.Fatal("neutral scaffold child was not merged")
+		}
+		if err := dst.RunE(dst, nil); err != nil || !businessCalled {
+			t.Fatalf("owning Hybrid RunE was not preserved: called=%v err=%v", businessCalled, err)
+		}
+	})
+
+	t.Run("rejects conflicting declarations", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := &cobra.Command{Use: "root"}
+		corecmd.ApplyGroupPolicy(src, corecmd.GroupPolicy{
+			Mode: corecmd.GroupNavigationOnly, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDisabled,
+		})
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "conflicting GroupPolicy") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("hybrid deep target rejects non-neutral source", func(t *testing.T) {
+		dst := &cobra.Command{Use: "root", RunE: func(*cobra.Command, []string) error { return nil }}
+		corecmd.ApplyGroupPolicy(dst, corecmd.GroupPolicy{
+			Mode: corecmd.GroupHybrid, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		})
+		src := &cobra.Command{Use: "root"}
+		corecmd.ApplyGroupPolicy(src, corecmd.GroupPolicy{
+			Mode: corecmd.GroupNavigationOnly, Positionals: corecmd.PositionalsReject, Recovery: corecmd.RecoveryDeep,
+		})
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "conflicting GroupPolicy") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("does not overwrite undeclared runnable destination", func(t *testing.T) {
+		dst := &cobra.Command{Use: "root", RunE: func(*cobra.Command, []string) error { return nil }}
+		src := NewGroupCommand("root", "source")
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "behavior-bearing leaf") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("does not swallow runnable leaf source into group destination", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		dst.AddCommand(&cobra.Command{Use: "native", RunE: func(*cobra.Command, []string) error { return nil }})
+		src := &cobra.Command{Use: "root", RunE: func(*cobra.Command, []string) error { return nil }}
+		src.Flags().String("source-only", "", "must not be silently discarded")
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "behavior-bearing leaf") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("does not swallow parse behavior from source into group destination", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := &cobra.Command{Use: "root", Args: cobra.NoArgs}
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "behavior-bearing leaf") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, src)
+	})
+
+	t.Run("rejects undeclared destination group", func(t *testing.T) {
+		dst := &cobra.Command{Use: "root"}
+		dst.AddCommand(&cobra.Command{Use: "child"})
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "destination command") || !strings.Contains(got.(string), "no GroupPolicy") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(dst, &cobra.Command{Use: "root"})
+	})
+
+	t.Run("rejects undeclared source group", func(t *testing.T) {
+		src := &cobra.Command{Use: "root"}
+		src.AddCommand(&cobra.Command{Use: "child"})
+		defer func() {
+			got := recover()
+			if got == nil || !strings.Contains(got.(string), "source command") || !strings.Contains(got.(string), "no GroupPolicy") {
+				t.Fatalf("MergeCommandTree panic = %v", got)
+			}
+		}()
+		MergeCommandTree(&cobra.Command{Use: "root"}, src)
+	})
+}
+
+func TestCrossPlatformCoverageMergeCommandTreeFailsClosedOnCorruption(t *testing.T) {
+	mustPanic := func(t *testing.T, want string, fn func()) {
+		t.Helper()
+		defer func() {
+			got := recover()
+			message, ok := got.(string)
+			if !ok || !strings.Contains(message, want) {
+				t.Fatalf("panic = %v, want substring %q", got, want)
+			}
+		}()
+		fn()
+	}
+
+	malformed := func() *cobra.Command {
+		return &cobra.Command{
+			Use: "root",
+			Annotations: map[string]string{
+				"dws.internal.corecmd.group_policy.v1": "malformed",
+			},
+		}
+	}
+
+	t.Run("malformed destination policy", func(t *testing.T) {
+		mustPanic(t, "destination command", func() {
+			MergeCommandTree(malformed(), &cobra.Command{Use: "root"})
+		})
+	})
+
+	t.Run("malformed source policy", func(t *testing.T) {
+		mustPanic(t, "source command", func() {
+			MergeCommandTree(&cobra.Command{Use: "root"}, malformed())
+		})
+	})
+
+	t.Run("local flag prevents placeholder merge", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := &cobra.Command{Use: "root"}
+		src.Flags().String("local", "", "local parse behavior")
+		mustPanic(t, "behavior-bearing leaf", func() {
+			MergeCommandTree(dst, src)
+		})
+	})
+
+	t.Run("persistent flag prevents placeholder merge", func(t *testing.T) {
+		dst := NewGroupCommand("root", "destination")
+		src := &cobra.Command{Use: "root"}
+		src.PersistentFlags().String("persistent", "", "inherited parse behavior")
+		mustPanic(t, "behavior-bearing leaf", func() {
+			MergeCommandTree(dst, src)
+		})
+	})
 }
 
 func TestNewHiddenGroupCommand(t *testing.T) {
@@ -341,11 +722,11 @@ func TestMergeCommandTree(t *testing.T) {
 
 	t.Run("child merge recursive", func(t *testing.T) {
 		t.Parallel()
-		dst := &cobra.Command{Use: "root"}
+		dst := NewGroupCommand("root", "destination")
 		dstChild := &cobra.Command{Use: "sub", Short: ""}
 		dst.AddCommand(dstChild)
 
-		src := &cobra.Command{Use: "root"}
+		src := NewGroupCommand("root", "source")
 		srcChild := &cobra.Command{Use: "sub", Short: "Merged short"}
 		src.AddCommand(srcChild)
 
@@ -361,12 +742,12 @@ func TestMergeCommandTree(t *testing.T) {
 
 	t.Run("leaf replacement by higher priority", func(t *testing.T) {
 		t.Parallel()
-		dst := &cobra.Command{Use: "root"}
+		dst := NewGroupCommand("root", "destination")
 		dstLeaf := &cobra.Command{Use: "leaf", Short: "old"}
 		SetOverridePriority(dstLeaf, 1)
 		dst.AddCommand(dstLeaf)
 
-		src := &cobra.Command{Use: "root"}
+		src := NewGroupCommand("root", "source")
 		srcLeaf := &cobra.Command{Use: "leaf", Short: "new"}
 		SetOverridePriority(srcLeaf, 5)
 		src.AddCommand(srcLeaf)
@@ -383,10 +764,10 @@ func TestMergeCommandTree(t *testing.T) {
 
 	t.Run("new child addition", func(t *testing.T) {
 		t.Parallel()
-		dst := &cobra.Command{Use: "root"}
+		dst := NewGroupCommand("root", "destination")
 		dst.AddCommand(&cobra.Command{Use: "existing"})
 
-		src := &cobra.Command{Use: "root"}
+		src := NewGroupCommand("root", "source")
 		src.AddCommand(&cobra.Command{Use: "brand-new", Short: "added"})
 
 		MergeCommandTree(dst, src)

internal/corecmd/corecmd.go

@@ -11,11 +11,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-// Package corecmd is the shared, dispatch-agnostic base for building leaf
-// commands. It concentrates flag registration, the alias/env/default effective
-// value fallback chain, required validation, cross-flag constraint declaration
-// checks + runtime enforcement, SafetySpec-driven confirmation, toolArgs
-// assembly, and Agent Runtime Schema projection.
+// Package corecmd is the shared, dispatch-agnostic base for building commands.
+// It concentrates typed group policy, flag registration, the alias/env/default
+// effective value fallback chain, required validation, cross-flag constraint
+// declaration checks + runtime enforcement, SafetySpec-driven confirmation,
+// toolArgs assembly, and Agent Runtime Schema projection.
 //
 // Declaration vs execution (framework rule):
 //
@@ -231,7 +231,9 @@ const (
 //     or assemble business params that belong in Flags/ConstParams.
 //
 // Exactly one of RunE / Invoke / ResultInvoke / Orchestrate must be set; New
-// validates this at construction time. corecmd stays dispatch-agnostic and
+// validates this at construction time. Non-leaf commands are declared
+// separately through ApplyGroupPolicy so leaf execution fields can never be
+// configured and then silently ignored. corecmd stays dispatch-agnostic and
 // never calls a backend: the adapters (FromLeafSpec / FromShortcut) supply the
 // body.
 type Spec struct {

internal/corecmd/group_policy.go

@@ -0,0 +1,218 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package corecmd
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+// GroupMode declares whether a command with children is navigation-only or
+// also owns business execution. The zero value means the command is a leaf.
+type GroupMode string
+
+const (
+	// GroupNavigationOnly is a parent whose own invocation only renders help.
+	GroupNavigationOnly GroupMode = "navigation_only"
+	// GroupHybrid is a runnable business command that also owns children.
+	GroupHybrid GroupMode = "hybrid"
+)
+
+// PositionalsPolicy declares whether a group may consume positional values.
+type PositionalsPolicy string
+
+const (
+	// PositionalsReject makes every unmatched positional token eligible for
+	// command-resolution recovery rather than business execution.
+	PositionalsReject PositionalsPolicy = "reject"
+	// PositionalsAllow reserves positional values for the group's business
+	// execution. Recovery must therefore be disabled to avoid ambiguity.
+	PositionalsAllow PositionalsPolicy = "allow"
+)
+
+// RecoveryPolicy declares the search scope for unknown-command recovery.
+type RecoveryPolicy string
+
+const (
+	// RecoverySibling suggests only direct children of the current group.
+	RecoverySibling RecoveryPolicy = "sibling"
+	// RecoveryDeep may search all descendants of the current group.
+	RecoveryDeep RecoveryPolicy = "deep"
+	// RecoveryDisabled leaves positional handling entirely to Cobra or the
+	// command's business execution.
+	RecoveryDisabled RecoveryPolicy = "disabled"
+)
+
+// GroupPolicy is the typed declaration for every non-leaf command.
+//
+// Its zero value deliberately means "leaf": callers must declare all three
+// fields together for a group. ApplyGroupPolicy compiles the declaration to
+// Cobra behavior and private framework metadata; command authors must not
+// author parallel kind annotations themselves.
+type GroupPolicy struct {
+	Mode        GroupMode
+	Positionals PositionalsPolicy
+	Recovery    RecoveryPolicy
+}
+
+const groupPolicyAnnotation = "dws.internal.corecmd.group_policy.v1"
+
+// IsZero reports whether p is the leaf declaration.
+func (p GroupPolicy) IsZero() bool {
+	return p.Mode == "" && p.Positionals == "" && p.Recovery == ""
+}
+
+// ValidateGroupPolicy rejects partial declarations, unknown enum values, and
+// combinations whose parsing semantics would be ambiguous.
+func ValidateGroupPolicy(p GroupPolicy) error {
+	if p.IsZero() {
+		return nil
+	}
+	switch p.Mode {
+	case GroupNavigationOnly, GroupHybrid:
+	default:
+		return fmt.Errorf("invalid group mode %q", p.Mode)
+	}
+	switch p.Positionals {
+	case PositionalsReject, PositionalsAllow:
+	default:
+		return fmt.Errorf("invalid group positionals policy %q", p.Positionals)
+	}
+	switch p.Recovery {
+	case RecoverySibling, RecoveryDeep, RecoveryDisabled:
+	default:
+		return fmt.Errorf("invalid group recovery policy %q", p.Recovery)
+	}
+	if p.Mode == GroupNavigationOnly && p.Positionals != PositionalsReject {
+		return fmt.Errorf("navigation-only group requires positionals=%q", PositionalsReject)
+	}
+	if p.Positionals == PositionalsAllow && p.Recovery != RecoveryDisabled {
+		return fmt.Errorf("group with positionals=%q requires recovery=%q", PositionalsAllow, RecoveryDisabled)
+	}
+	return nil
+}
+
+// ApplyGroupPolicy is the sole declaration API for non-leaf command behavior.
+// Invalid declarations panic because they are framework construction bugs,
+// matching the fail-closed behavior of Spec flag/constraint declarations.
+//
+// Navigation-only groups receive the shared help/unknown-command RunE. Hybrid
+// groups retain their existing RunE; when they reject positionals, a wrapper
+// sends non-empty args to the same unknown-command resolver before invoking
+// business execution. When recovery is enabled, rejecting positionals
+// deliberately compiles to cobra.ArbitraryArgs: Cobra must not intercept the
+// token with a generic error before command resolution can produce bounded
+// guidance. RecoveryDisabled instead compiles rejection to cobra.NoArgs.
+func ApplyGroupPolicy(cmd *cobra.Command, policy GroupPolicy) {
+	if cmd == nil {
+		panic("cannot apply GroupPolicy to a nil command")
+	}
+	if policy.IsZero() {
+		panic(fmt.Sprintf("command %q cannot apply the zero GroupPolicy; zero means leaf", cmd.Name()))
+	}
+	if err := ValidateGroupPolicy(policy); err != nil {
+		panic(fmt.Sprintf("command %q declares invalid GroupPolicy: %v", cmd.Name(), err))
+	}
+	if existing, ok, err := GroupPolicyFor(cmd); err != nil {
+		panic(fmt.Sprintf("command %q carries invalid GroupPolicy metadata: %v", cmd.Name(), err))
+	} else if ok && existing != policy {
+		panic(fmt.Sprintf("command %q redeclares GroupPolicy from %+v to %+v", cmd.Name(), existing, policy))
+	} else if ok {
+		return
+	}
+
+	if policy.Mode == GroupNavigationOnly {
+		cmd.Run = nil
+		cmd.RunE = func(cmd *cobra.Command, args []string) error {
+			return runGroupPolicy(cmd, args, policy)
+		}
+	} else if cmd.RunE == nil {
+		panic(fmt.Sprintf("hybrid group %q must declare RunE before GroupPolicy is applied", cmd.Name()))
+	} else if policy.Positionals == PositionalsReject && policy.Recovery != RecoveryDisabled {
+		businessRunE := cmd.RunE
+		cmd.RunE = func(cmd *cobra.Command, args []string) error {
+			if len(args) > 0 {
+				return runGroupPolicy(cmd, args, policy)
+			}
+			return businessRunE(cmd, args)
+		}
+	}
+	if policy.Positionals == PositionalsReject && policy.Recovery != RecoveryDisabled {
+		cmd.Args = cobra.ArbitraryArgs
+	} else if policy.Positionals == PositionalsReject {
+		cmd.Args = cobra.NoArgs
+	}
+
+	if cmd.Annotations == nil {
+		cmd.Annotations = map[string]string{}
+	}
+	cmd.Annotations[groupPolicyAnnotation] = encodeGroupPolicy(policy)
+}
+
+// GroupPolicyFor reads the typed declaration compiled onto cmd. The boolean is
+// false only for a leaf. Malformed private metadata is returned as an error so
+// tree assembly can fail closed instead of silently treating a group as a leaf.
+func GroupPolicyFor(cmd *cobra.Command) (GroupPolicy, bool, error) {
+	if cmd == nil || cmd.Annotations == nil {
+		return GroupPolicy{}, false, nil
+	}
+	raw, ok := cmd.Annotations[groupPolicyAnnotation]
+	if !ok {
+		return GroupPolicy{}, false, nil
+	}
+	parts := strings.Split(raw, "|")
+	if len(parts) != 3 {
+		return GroupPolicy{}, false, fmt.Errorf("malformed encoded GroupPolicy %q", raw)
+	}
+	policy := GroupPolicy{
+		Mode:        GroupMode(parts[0]),
+		Positionals: PositionalsPolicy(parts[1]),
+		Recovery:    RecoveryPolicy(parts[2]),
+	}
+	if err := ValidateGroupPolicy(policy); err != nil {
+		return GroupPolicy{}, false, err
+	}
+	if policy.IsZero() {
+		return GroupPolicy{}, false, fmt.Errorf("encoded GroupPolicy must not be zero")
+	}
+	return policy, true, nil
+}
+
+func encodeGroupPolicy(policy GroupPolicy) string {
+	return string(policy.Mode) + "|" + string(policy.Positionals) + "|" + string(policy.Recovery)
+}
+
+func runGroupPolicy(cmd *cobra.Command, args []string, policy GroupPolicy) error {
+	if len(args) == 0 {
+		return cmd.Help()
+	}
+	input := strings.TrimSpace(args[0])
+	reason := cmdutil.ClassifyCommandResolution(cmd, input)
+	suggestions := cmdutil.SuggestSubcommands(cmd, input)
+	if reason == cmdutil.ResolutionUnknownSubcommand && policy.Recovery == RecoveryDeep {
+		if deep := cmdutil.SuggestDescendantSubcommands(cmd, input); len(deep) > 0 {
+			suggestions = deep
+		}
+	}
+	return cmdutil.NewCommandResolution(
+		cmd,
+		input,
+		reason,
+		suggestions,
+		"",
+	).Err()
+}

internal/corecmd/group_policy_test.go

@@ -0,0 +1,323 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package corecmd
+
+import (
+	"errors"
+	"runtime"
+	"slices"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageValidateGroupPolicy(t *testing.T) {
+	valid := []GroupPolicy{
+		{},
+		{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling},
+		{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoveryDeep},
+		{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoveryDisabled},
+		{Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: RecoverySibling},
+		{Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: RecoveryDeep},
+		{Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: RecoveryDisabled},
+		{Mode: GroupHybrid, Positionals: PositionalsAllow, Recovery: RecoveryDisabled},
+	}
+	for _, policy := range valid {
+		if err := ValidateGroupPolicy(policy); err != nil {
+			t.Fatalf("ValidateGroupPolicy(%+v) = %v", policy, err)
+		}
+	}
+
+	invalid := []struct {
+		name   string
+		policy GroupPolicy
+		needle string
+	}{
+		{name: "partial", policy: GroupPolicy{Mode: GroupHybrid}, needle: "positionals"},
+		{name: "unknown mode", policy: GroupPolicy{Mode: "leafish", Positionals: PositionalsReject, Recovery: RecoveryDisabled}, needle: "mode"},
+		{name: "unknown positionals", policy: GroupPolicy{Mode: GroupHybrid, Positionals: "maybe", Recovery: RecoveryDisabled}, needle: "positionals"},
+		{name: "unknown recovery", policy: GroupPolicy{Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: "global"}, needle: "recovery"},
+		{name: "navigation allows args", policy: GroupPolicy{Mode: GroupNavigationOnly, Positionals: PositionalsAllow, Recovery: RecoveryDisabled}, needle: "navigation-only"},
+		{name: "ambiguous recovery", policy: GroupPolicy{Mode: GroupHybrid, Positionals: PositionalsAllow, Recovery: RecoverySibling}, needle: "requires recovery"},
+	}
+	for _, tc := range invalid {
+		t.Run(tc.name, func(t *testing.T) {
+			if err := ValidateGroupPolicy(tc.policy); err == nil || !strings.Contains(err.Error(), tc.needle) {
+				t.Fatalf("ValidateGroupPolicy(%+v) = %v, want %q", tc.policy, err, tc.needle)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageApplyAndReadGroupPolicy(t *testing.T) {
+	policy := GroupPolicy{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling}
+	cmd := &cobra.Command{Use: "parent"}
+	ApplyGroupPolicy(cmd, policy)
+
+	got, ok, err := GroupPolicyFor(cmd)
+	if err != nil || !ok || got != policy {
+		t.Fatalf("GroupPolicyFor() = %+v, %v, %v; want %+v, true, nil", got, ok, err, policy)
+	}
+	if !cmd.Runnable() || cmd.TraverseChildren {
+		t.Fatalf("compiled navigation command Runnable=%v TraverseChildren=%v; policy must preserve the flag-traversal surface", cmd.Runnable(), cmd.TraverseChildren)
+	}
+	if cmd.Args == nil || cmd.Args(cmd, []string{"extra"}) != nil {
+		t.Fatal("PositionalsReject must let command resolution inspect unmatched args")
+	}
+	if err := cmd.RunE(cmd, []string{"extra"}); err == nil || !strings.Contains(err.Error(), "unknown subcommand") {
+		t.Fatalf("navigation recovery error = %v", err)
+	}
+	var help strings.Builder
+	cmd.SetOut(&help)
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatalf("navigation help error = %v", err)
+	}
+	if output := help.String(); !strings.Contains(output, "Usage:") {
+		t.Fatalf("navigation help output = %q", output)
+	}
+	// Re-applying the same declaration is idempotent.
+	ApplyGroupPolicy(cmd, policy)
+
+	traversing := &cobra.Command{Use: "traversing", TraverseChildren: true}
+	ApplyGroupPolicy(traversing, policy)
+	if !traversing.TraverseChildren {
+		t.Fatal("ApplyGroupPolicy changed an explicitly declared TraverseChildren surface")
+	}
+
+	leaf := &cobra.Command{Use: "leaf"}
+	if got, ok, err := GroupPolicyFor(leaf); err != nil || ok || !got.IsZero() {
+		t.Fatalf("leaf GroupPolicyFor() = %+v, %v, %v", got, ok, err)
+	}
+	annotatedLeaf := &cobra.Command{Use: "annotated-leaf", Annotations: map[string]string{"unrelated": "metadata"}}
+	if got, ok, err := GroupPolicyFor(annotatedLeaf); err != nil || ok || !got.IsZero() {
+		t.Fatalf("annotated leaf GroupPolicyFor() = %+v, %v, %v", got, ok, err)
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyDoesNotLeakParentLocalFlags(t *testing.T) {
+	root := &cobra.Command{Use: "dws", SilenceUsage: true, SilenceErrors: true}
+	ApplyGroupPolicy(root, GroupPolicy{
+		Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling,
+	})
+	parent := &cobra.Command{
+		Use:  "search",
+		RunE: func(*cobra.Command, []string) error { return nil },
+	}
+	parent.Flags().String("dimension", "", "parent-only search dimension")
+	ApplyGroupPolicy(parent, GroupPolicy{
+		Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: RecoverySibling,
+	})
+	childCalled := false
+	child := &cobra.Command{
+		Use: "enterprise",
+		RunE: func(*cobra.Command, []string) error {
+			childCalled = true
+			return nil
+		},
+	}
+	parent.AddCommand(child)
+	root.AddCommand(parent)
+	root.SetArgs([]string{"search", "--dimension", "name", "enterprise"})
+
+	err := root.Execute()
+	if err == nil || !strings.Contains(err.Error(), "unknown flag: --dimension") {
+		t.Fatalf("Execute() error = %v, want parent local flag rejected by child", err)
+	}
+	if childCalled {
+		t.Fatal("parent local flag leaked into child command execution")
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyHybridPreservesExecution(t *testing.T) {
+	called := false
+	cmd := &cobra.Command{
+		Use: "hybrid",
+		RunE: func(*cobra.Command, []string) error {
+			called = true
+			return nil
+		},
+	}
+	ApplyGroupPolicy(cmd, GroupPolicy{
+		Mode:        GroupHybrid,
+		Positionals: PositionalsAllow,
+		Recovery:    RecoveryDisabled,
+	})
+	if err := cmd.RunE(cmd, []string{"business-id"}); err != nil || !called {
+		t.Fatalf("hybrid RunE was not preserved: called=%v err=%v", called, err)
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyHybridRejectRoutesUnknownArgs(t *testing.T) {
+	called := false
+	wrapperFrames := 0
+	cmd := &cobra.Command{
+		Use: "hybrid",
+		RunE: func(*cobra.Command, []string) error {
+			called = true
+			pcs := make([]uintptr, 32)
+			frames := runtime.CallersFrames(pcs[:runtime.Callers(0, pcs)])
+			for {
+				frame, more := frames.Next()
+				if strings.Contains(frame.Function, "corecmd.ApplyGroupPolicy.func") {
+					wrapperFrames++
+				}
+				if !more {
+					break
+				}
+			}
+			return nil
+		},
+	}
+	policy := GroupPolicy{
+		Mode:        GroupHybrid,
+		Positionals: PositionalsReject,
+		Recovery:    RecoverySibling,
+	}
+	ApplyGroupPolicy(cmd, policy)
+	// Applying the identical declaration must be a no-op. In particular, it
+	// must not wrap the already wrapped Hybrid RunE a second time.
+	ApplyGroupPolicy(cmd, policy)
+	if err := cmd.RunE(cmd, []string{"typo"}); err == nil || !strings.Contains(err.Error(), "unknown subcommand") {
+		t.Fatalf("hybrid typo error = %v", err)
+	}
+	if called {
+		t.Fatal("unknown positional must not reach hybrid business RunE")
+	}
+	if err := cmd.RunE(cmd, nil); err != nil || !called {
+		t.Fatalf("hybrid empty-args execution called=%v err=%v", called, err)
+	}
+	if wrapperFrames != 1 {
+		t.Fatalf("Hybrid RunE wrapper depth = %d, want exactly 1 after idempotent re-apply", wrapperFrames)
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyDeepRecoveryUsesDescendantPath(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	sheet := &cobra.Command{Use: "sheet"}
+	rangeGroup := &cobra.Command{Use: "range"}
+	rangeGroup.AddCommand(&cobra.Command{Use: "read", Run: func(*cobra.Command, []string) {}})
+	ApplyGroupPolicy(rangeGroup, GroupPolicy{
+		Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling,
+	})
+	sheet.AddCommand(
+		rangeGroup,
+		&cobra.Command{Use: "+list-sheets", Run: func(*cobra.Command, []string) {}},
+	)
+	ApplyGroupPolicy(sheet, GroupPolicy{
+		Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoveryDeep,
+	})
+	root.AddCommand(sheet)
+
+	err := sheet.RunE(sheet, []string{"read"})
+	var structured *apperrors.Error
+	if !errors.As(err, &structured) {
+		t.Fatalf("deep recovery error = %T %v", err, err)
+	}
+	if structured.Reason != string(cmdutil.ResolutionUnknownSubcommand) ||
+		structured.Hint != `Did you mean "dws sheet range read"? (Run 'dws sheet --help' for the full list)` {
+		t.Fatalf("deep recovery = %#v", structured)
+	}
+	if got, ok := structured.Details["suggestions"].([]string); !ok || !slices.Equal(got, []string{"range read"}) {
+		t.Fatalf("deep suggestions = %#v", structured.Details["suggestions"])
+	}
+
+	err = sheet.RunE(sheet, []string{"+list-sheet"})
+	structured = nil
+	if !errors.As(err, &structured) || structured.Reason != string(cmdutil.ResolutionUnknownShortcut) {
+		t.Fatalf("direct shortcut recovery = %#v, err=%v", structured, err)
+	}
+	if !slices.Equal(structured.Actions, []string{
+		"Run 'dws sheet --help' for the full list",
+		"Run 'dws shortcut list --service sheet --format json'",
+	}) {
+		t.Fatalf("direct shortcut actions = %#v", structured.Actions)
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyRejectWithoutRecoveryUsesCobraArgs(t *testing.T) {
+	cmd := &cobra.Command{Use: "parent"}
+	ApplyGroupPolicy(cmd, GroupPolicy{
+		Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoveryDisabled,
+	})
+	if err := cmd.Args(cmd, []string{"extra"}); err == nil {
+		t.Fatal("RecoveryDisabled must leave rejected positionals to Cobra")
+	}
+}
+
+func TestCrossPlatformCoverageApplyGroupPolicyFailsClosed(t *testing.T) {
+	mustPanic := func(name, needle string, fn func()) {
+		t.Helper()
+		t.Run(name, func(t *testing.T) {
+			defer func() {
+				got := recover()
+				if got == nil || !strings.Contains(got.(string), needle) {
+					t.Fatalf("panic = %v, want %q", got, needle)
+				}
+			}()
+			fn()
+		})
+	}
+	mustPanic("nil command", "nil command", func() { ApplyGroupPolicy(nil, GroupPolicy{}) })
+	mustPanic("zero policy", "zero GroupPolicy", func() { ApplyGroupPolicy(&cobra.Command{Use: "leaf"}, GroupPolicy{}) })
+	mustPanic("invalid policy", "invalid GroupPolicy", func() {
+		ApplyGroupPolicy(&cobra.Command{Use: "broken"}, GroupPolicy{
+			Mode: GroupHybrid, Positionals: "unexpected", Recovery: RecoveryDisabled,
+		})
+	})
+	mustPanic("hybrid must run", "must declare RunE", func() {
+		ApplyGroupPolicy(&cobra.Command{Use: "hybrid"}, GroupPolicy{
+			Mode: GroupHybrid, Positionals: PositionalsReject, Recovery: RecoverySibling,
+		})
+	})
+	mustPanic("conflicting redeclaration", "redeclares GroupPolicy", func() {
+		cmd := &cobra.Command{Use: "parent"}
+		ApplyGroupPolicy(cmd, GroupPolicy{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling})
+		ApplyGroupPolicy(cmd, GroupPolicy{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoveryDisabled})
+	})
+	mustPanic("invalid existing metadata", "invalid GroupPolicy metadata", func() {
+		cmd := &cobra.Command{
+			Use: "broken",
+			Annotations: map[string]string{
+				groupPolicyAnnotation: "hybrid|reject|unexpected",
+			},
+		}
+		ApplyGroupPolicy(cmd, GroupPolicy{Mode: GroupNavigationOnly, Positionals: PositionalsReject, Recovery: RecoverySibling})
+	})
+}
+
+func TestCrossPlatformCoverageGroupPolicyForRejectsMalformedPrivateMetadata(t *testing.T) {
+	for name, test := range map[string]struct {
+		encoded string
+		needle  string
+	}{
+		"malformed":      {encoded: "hybrid|reject", needle: "malformed"},
+		"invalid policy": {encoded: "hybrid|reject|unexpected", needle: "recovery"},
+		"zero policy":    {encoded: "||", needle: "must not be zero"},
+	} {
+		t.Run(name, func(t *testing.T) {
+			cmd := &cobra.Command{
+				Use: "broken",
+				Annotations: map[string]string{
+					groupPolicyAnnotation: test.encoded,
+				},
+			}
+			if _, ok, err := GroupPolicyFor(cmd); err == nil || ok || !strings.Contains(err.Error(), test.needle) {
+				t.Fatalf("GroupPolicyFor(%q) = ok %v, err %v; want %q", test.encoded, ok, err, test.needle)
+			}
+		})
+	}
+}

internal/helpers/agoal.go

@@ -15,7 +15,7 @@ var agoalLoadLocation = time.LoadLocation
 // ──────────────────────────────────────────────────────────
 
 func newAgoalCommand() *cobra.Command {
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "agoal",
 		Short: "Agoal 管理",
 		Long: `管理钉钉 Agoal：战略解码、经营合约、计分卡、用户目标、周月报。
@@ -39,11 +39,11 @@ func newAgoalCommand() *cobra.Command {
   dws agoal obj-template list             获取目标模板列表
   dws agoal obj-template create-or-update 新增或更新目标模板`,
 		RunE: groupRunE,
-	}
+	})
 
 	// ── strategy: 战略解码管理 ──────────────────────────────────
 
-	strategyCmd := &cobra.Command{Use: "strategy", Short: "战略解码管理", RunE: groupRunE}
+	strategyCmd := newGroupCommand(&cobra.Command{Use: "strategy", Short: "战略解码管理", RunE: groupRunE})
 
 	strategyListCmd := &cobra.Command{
 		Use:   "list",
@@ -139,7 +139,7 @@ scopeType 支持:
 
 	// ── contract: 经营合约管理 ──────────────────────────────────
 
-	contractCmd := &cobra.Command{Use: "contract", Short: "经营合约管理", RunE: groupRunE}
+	contractCmd := newGroupCommand(&cobra.Command{Use: "contract", Short: "经营合约管理", RunE: groupRunE})
 
 	contractListCmd := &cobra.Command{
 		Use:   "list",
@@ -258,7 +258,7 @@ scopeType 支持:
 
 	// ── scorecard: 计分卡管理 ───────────────────────────────────
 
-	scorecardCmd := &cobra.Command{Use: "scorecard", Short: "计分卡管理", RunE: groupRunE}
+	scorecardCmd := newGroupCommand(&cobra.Command{Use: "scorecard", Short: "计分卡管理", RunE: groupRunE})
 
 	scorecardDetailCmd := &cobra.Command{
 		Use:   "detail",
@@ -394,7 +394,7 @@ scopeType 支持:
 
 	// ── user: 用户目标管理 ──────────────────────────────────────
 
-	userCmd := &cobra.Command{Use: "user", Short: "用户目标管理", RunE: groupRunE}
+	userCmd := newGroupCommand(&cobra.Command{Use: "user", Short: "用户目标管理", RunE: groupRunE})
 
 	userRulesCmd := &cobra.Command{
 		Use:   "rules",
@@ -445,7 +445,7 @@ scopeType 支持:
 
 	// ── report: 周月报管理 ──────────────────────────────────────
 
-	reportCmd := &cobra.Command{Use: "report", Short: "周月报管理", RunE: groupRunE}
+	reportCmd := newGroupCommand(&cobra.Command{Use: "report", Short: "周月报管理", RunE: groupRunE})
 
 	reportListStatisticsCmd := &cobra.Command{
 		Use:   "list-statistics",
@@ -520,7 +520,7 @@ scopeType 支持:
 
 	// ── template: 目标模板管理 ──────────────────────────────────
 
-	objTemplateCmd := &cobra.Command{Use: "obj-template", Short: "目标模板管理", RunE: groupRunE}
+	objTemplateCmd := newGroupCommand(&cobra.Command{Use: "obj-template", Short: "目标模板管理", RunE: groupRunE})
 
 	objTemplateListCmd := &cobra.Command{
 		Use:   "list",

internal/helpers/aisearch.go

@@ -210,6 +210,7 @@ func newAisearchCommand() *cobra.Command {
 			return groupRunE(cmd, args)
 		},
 	}
+	newHybridGroupCommand(root)
 
 	// root 和 person 各自定义同一组本地 flag，这样：
 	//   - dws aisearch --query xxx           ← root 自己能解析

internal/helpers/aitable.go

@@ -1562,7 +1562,7 @@ func newAitableCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "aitable",
 		Short: "AI 表格操作",
 		Long: `管理钉钉 AI 表格：Base 管理、数据表、字段、记录、视图、表单、仪表盘、图表、导入导出。
@@ -1586,11 +1586,11 @@ func newAitableCommand() *cobra.Command {
   dws aitable section    [create|rename|delete|reorder|list-empty|list-nodes|move-node]  文件夹与节点管理`,
 		RunE:                       groupRunE,
 		SuggestionsMinimumDistance: 2, // Enable "Did you mean ...?" for typos
-	}
+	})
 
 	// ── base: Base 管理 ─────────────────────────────────────────
 
-	baseCmd := &cobra.Command{Use: "base", Short: "Base 管理", RunE: groupRunE}
+	baseCmd := newGroupCommand(&cobra.Command{Use: "base", Short: "Base 管理", RunE: groupRunE})
 
 	baseGetPrimaryDocIdCmd := &cobra.Command{
 		Use:   "get-primary-doc-id",
@@ -1952,7 +1952,7 @@ MCP 层不会会自动解析 URL，必须直接传入 dentryUuid 以避免报错
 
 	// ── table: 数据表管理 ───────────────────────────────────────
 
-	tableCmd := &cobra.Command{Use: "table", Short: "数据表管理", RunE: groupRunE}
+	tableCmd := newGroupCommand(&cobra.Command{Use: "table", Short: "数据表管理", RunE: groupRunE})
 
 	tableGetCmd := &cobra.Command{
 		Use:   "get",
@@ -2223,7 +2223,7 @@ config 结构参考：
 
 	// ── field: 字段管理 ─────────────────────────────────────────
 
-	fieldCmd := &cobra.Command{Use: "field", Short: "字段管理", RunE: groupRunE}
+	fieldCmd := newGroupCommand(&cobra.Command{Use: "field", Short: "字段管理", RunE: groupRunE})
 
 	fieldGetCmd := &cobra.Command{
 		Use:   "get",
@@ -2582,7 +2582,7 @@ newFieldName、config、aiConfig 至少传入一项。
 
 	// ── record: 记录管理 ────────────────────────────────────────
 
-	recordCmd := &cobra.Command{Use: "record", Short: "记录管理", RunE: groupRunE}
+	recordCmd := newGroupCommand(&cobra.Command{Use: "record", Short: "记录管理", RunE: groupRunE})
 
 	recordQueryCmd := &cobra.Command{
 		Use:   "query",
@@ -3564,7 +3564,7 @@ fieldId 必须是 primaryDoc 类型的字段。`,
 
 	// ── template: 模板搜索 ──────────────────────────────────────
 
-	templateCmd := &cobra.Command{Use: "template", Short: "模板搜索", RunE: groupRunE}
+	templateCmd := newGroupCommand(&cobra.Command{Use: "template", Short: "模板搜索", RunE: groupRunE})
 
 	templateSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -3613,7 +3613,7 @@ fieldId 必须是 primaryDoc 类型的字段。`,
 
 	// ── attachment: 附件管理 ──────────────────────────────────────
 
-	attachmentCmd := &cobra.Command{Use: "attachment", Short: "附件管理", RunE: groupRunE}
+	attachmentCmd := newGroupCommand(&cobra.Command{Use: "attachment", Short: "附件管理", RunE: groupRunE})
 
 	attachmentUploadCmd := &cobra.Command{
 		Use:   "upload",
@@ -3690,7 +3690,7 @@ fieldId 必须是 primaryDoc 类型的字段。`,
 
 	// ── view: 视图管理 ───────────────────────────────────────────
 
-	viewCmd := &cobra.Command{Use: "view", Short: "视图管理", RunE: groupRunE}
+	viewCmd := newGroupCommand(&cobra.Command{Use: "view", Short: "视图管理", RunE: groupRunE})
 
 	viewGetCmd := &cobra.Command{
 		Use:   "get",
@@ -3721,6 +3721,7 @@ fieldId 必须是 primaryDoc 类型的字段。`,
 			return callAitableTool("get_views", toolArgs)
 		},
 	}
+	newHybridGroupCommand(viewGetCmd)
 
 	// ─── view get <attr> 子命令：按属性投影 view 响应 ──────────────
 	// card/timebar/aggregate 需要 viewType 校验；filter/sort/group/visible-fields/field-widths 不需要。
@@ -4114,6 +4115,7 @@ fieldWidths 仅支持 Grid 视图。
 			return callAitableTool("update_view", toolArgs)
 		},
 	}
+	newHybridGroupCommand(viewUpdateCmd)
 
 	// ─── view update <attr> 子命令：按属性局部更新 ────────────────────
 
@@ -5058,9 +5060,9 @@ locked 为 true 表示视图已锁定，false 表示未锁定。`,
 
 	// ── form: 表单管理 ──────────────────────────────────────────
 
-	formCmd := &cobra.Command{Use: "form", Short: "表单管理", RunE: groupRunE}
-	formFieldCmd := &cobra.Command{Use: "field", Short: "表单字段管理", RunE: groupRunE}
-	formShareCmd := &cobra.Command{Use: "share", Short: "表单分享管理", RunE: groupRunE}
+	formCmd := newGroupCommand(&cobra.Command{Use: "form", Short: "表单管理", RunE: groupRunE})
+	formFieldCmd := newGroupCommand(&cobra.Command{Use: "field", Short: "表单字段管理", RunE: groupRunE})
+	formShareCmd := newGroupCommand(&cobra.Command{Use: "share", Short: "表单分享管理", RunE: groupRunE})
 
 	formListCmd := &cobra.Command{
 		Use:     "list",
@@ -5312,7 +5314,7 @@ locked 为 true 表示视图已锁定，false 表示未锁定。`,
 
 	// ── form questions: 表单题目（form 视角的字段管理，等价于 field create / field delete） ──
 
-	formQuestionsCmd := &cobra.Command{Use: "questions", Short: "表单题目管理（等价于 field create / delete）", RunE: groupRunE}
+	formQuestionsCmd := newGroupCommand(&cobra.Command{Use: "questions", Short: "表单题目管理（等价于 field create / delete）", RunE: groupRunE})
 
 	formQuestionsCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -5607,11 +5609,11 @@ locked 为 true 表示视图已锁定，false 表示未锁定。`,
 
 	// ── workflow: 自动化工作流管理 ────────────────────────────────
 
-	workflowCmd := &cobra.Command{
+	workflowCmd := newGroupCommand(&cobra.Command{
 		Use:   "workflow",
 		Short: "自动化工作流管理（创建 / 更新 / 启停 / 执行 / 历史 / 查询）",
 		RunE:  groupRunE,
-	}
+	})
 
 	workflowCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -6066,7 +6068,7 @@ valid=false 仍表示 DSL 校验或发布未通过，必须读取 issues 修正
 
 	// ── dashboard: 仪表盘管理 ────────────────────────────────────
 
-	dashboardCmd := &cobra.Command{Use: "dashboard", Short: "仪表盘管理", RunE: groupRunE}
+	dashboardCmd := newGroupCommand(&cobra.Command{Use: "dashboard", Short: "仪表盘管理", RunE: groupRunE})
 
 	dashboardConfigExampleCmd := &cobra.Command{
 		Use:   "config-example",
@@ -6361,7 +6363,7 @@ layout 数组里每项含图表的新位置（row/col/width/height）。`,
 
 	// ── dashboard share: 仪表盘分享管理 ────────────────────────────
 
-	dashboardShareCmd := &cobra.Command{Use: "share", Short: "仪表盘分享管理", RunE: groupRunE}
+	dashboardShareCmd := newGroupCommand(&cobra.Command{Use: "share", Short: "仪表盘分享管理", RunE: groupRunE})
 
 	dashboardShareGetCmd := &cobra.Command{
 		Use:   "get",
@@ -6463,7 +6465,7 @@ layout 数组里每项含图表的新位置（row/col/width/height）。`,
 
 	// ── chart: 图表管理 ──────────────────────────────────────────
 
-	chartCmd := &cobra.Command{Use: "chart", Short: "图表管理", RunE: groupRunE}
+	chartCmd := newGroupCommand(&cobra.Command{Use: "chart", Short: "图表管理", RunE: groupRunE})
 
 	chartWidgetsExampleCmd := &cobra.Command{
 		Use:   "widgets-example",
@@ -6702,7 +6704,7 @@ layout 数组里每项含图表的新位置（row/col/width/height）。`,
 
 	// ── chart share: 图表分享管理 ────────────────────────────────
 
-	chartShareCmd := &cobra.Command{Use: "share", Short: "图表分享管理", RunE: groupRunE}
+	chartShareCmd := newGroupCommand(&cobra.Command{Use: "share", Short: "图表分享管理", RunE: groupRunE})
 
 	chartShareGetCmd := &cobra.Command{
 		Use:   "get",
@@ -6806,7 +6808,7 @@ layout 数组里每项含图表的新位置（row/col/width/height）。`,
 
 	// ── export / import: 数据导入导出 ────────────────────────────
 
-	exportCmd := &cobra.Command{Use: "export", Short: "数据导出", RunE: groupRunE}
+	exportCmd := newGroupCommand(&cobra.Command{Use: "export", Short: "数据导出", RunE: groupRunE})
 
 	exportDataCmd := &cobra.Command{
 		Use:   "data",
@@ -6911,11 +6913,11 @@ export-format 可选值：excel、attachment、excel_and_attachment、excel_with
 		},
 	})
 
-	importCmd := &cobra.Command{Use: "import", Short: "数据导入", RunE: groupRunE}
+	importCmd := newGroupCommand(&cobra.Command{Use: "import", Short: "数据导入", RunE: groupRunE})
 
 	// ── advperm: 高级权限 / 自定义角色 ────────────────────────────
 
-	advpermCmd := &cobra.Command{Use: "advperm", Short: "高级权限管理（开关 / 角色查看与删除）", RunE: groupRunE}
+	advpermCmd := newGroupCommand(&cobra.Command{Use: "advperm", Short: "高级权限管理（开关 / 角色查看与删除）", RunE: groupRunE})
 
 	advpermEnableCmd := &cobra.Command{
 		Use:   "enable",
@@ -7392,7 +7394,7 @@ role-get 自行 merge）。
 
 	// ── section: 文件夹与节点管理（导航树组织） ──────────────────────────────
 
-	sectionCmd := &cobra.Command{Use: "section", Short: "文件夹与节点管理", RunE: groupRunE}
+	sectionCmd := newGroupCommand(&cobra.Command{Use: "section", Short: "文件夹与节点管理", RunE: groupRunE})
 
 	sectionCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -8424,7 +8426,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 
 	// ── datasource: 数据源同步管理 ──────────────────────────────
 
-	datasourceCmd := &cobra.Command{Use: "datasource", Short: "数据源同步管理", RunE: groupRunE}
+	datasourceCmd := newGroupCommand(&cobra.Command{Use: "datasource", Short: "数据源同步管理", RunE: groupRunE})
 
 	datasourceGetConfigCmd := &cobra.Command{
 		Use:     "get-config",

internal/helpers/attendance.go

@@ -528,7 +528,7 @@ func newAttendanceCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "attendance",
 		Short: "考勤打卡 / 排班 / 统计",
 		Long: `管理钉钉考勤：查询个人考勤详情、班次查询、排班管理、获取考勤统计摘要、查询考勤组与规则。
@@ -546,11 +546,11 @@ func newAttendanceCommand() *cobra.Command {
   globalsetting  全局规则设置项（get 查询，save 更新，仅管理员可调用，包括打卡提醒、极速打卡、打卡结果通知、缺卡提醒、个人考勤统计通知、团队考勤统计通知）
   vacation       查询当前用户假期规则列表、查询员工假期余额、查询假期余额变更记录`,
 		RunE: groupRunE,
-	}
+	})
 
 	// ── record ───────────────────────────────────────────────
 
-	attendanceRecordCmd := &cobra.Command{Use: "record", Short: "考勤记录", RunE: groupRunE}
+	attendanceRecordCmd := newGroupCommand(&cobra.Command{Use: "record", Short: "考勤记录", RunE: groupRunE})
 
 	attendanceRecordGetCmd := &cobra.Command{
 		Use:     "get",
@@ -612,7 +612,7 @@ func newAttendanceCommand() *cobra.Command {
 
 	// ── check ────────────────────────────────────────────────
 
-	attendanceCheckCmd := &cobra.Command{Use: "check", Short: "打卡查询", RunE: groupRunE}
+	attendanceCheckCmd := newGroupCommand(&cobra.Command{Use: "check", Short: "打卡查询", RunE: groupRunE})
 
 	// MCP tool: query_check_result
 	attendanceCheckResultCmd := &cobra.Command{
@@ -783,7 +783,7 @@ func newAttendanceCommand() *cobra.Command {
 
 	// ── approve ────────────────────────────────────────────────
 
-	attendanceApproveCmd := &cobra.Command{Use: "approve", Short: "审批单查询", RunE: groupRunE}
+	attendanceApproveCmd := newGroupCommand(&cobra.Command{Use: "approve", Short: "审批单查询", RunE: groupRunE})
 
 	// 审批类型关键词到 bizType 数字映射
 	// 注意：服务端 bizType=2 同时覆盖 出差 与 外出（合并为同一类），
@@ -992,13 +992,13 @@ func newAttendanceCommand() *cobra.Command {
 
 	// ── shift ────────────────────────────────────────────────
 
-	attendanceShiftCmd := &cobra.Command{
+	attendanceShiftCmd := newGroupCommand(&cobra.Command{
 		Use:   "shift",
 		Short: "班次查询",
 		Long: `查询员工班次信息（班次 = 员工当天的打卡安排）。
 返回每条记录含：用户 ID、工作日期、打卡类型（OnDuty/OffDuty）、计划打卡时间、是否休息日。`,
 		RunE: groupRunE,
-	}
+	})
 
 	// MCP tool: batch_get_employee_shifts
 	attendanceShiftListCmd := &cobra.Command{
@@ -1068,7 +1068,7 @@ func newAttendanceCommand() *cobra.Command {
 
 	// ── class ────────────────────────────────────────────────
 
-	attendanceClassCmd := &cobra.Command{Use: "class", Short: "班次规则", RunE: groupRunE}
+	attendanceClassCmd := newGroupCommand(&cobra.Command{Use: "class", Short: "班次规则", RunE: groupRunE})
 
 	// MCP tool: get_class_list
 	attendanceClassSearchCmd := &cobra.Command{
@@ -1415,7 +1415,7 @@ checkTime 字段统一使用 "HH:mm" 格式（如 "09:00"），CLI 自动转换
 
 	// ── adjustment-rule ────────────────────────────────────
 
-	attendanceAdjustmentCmd := &cobra.Command{Use: "adjustment", Short: "补卡规则", RunE: groupRunE}
+	attendanceAdjustmentCmd := newGroupCommand(&cobra.Command{Use: "adjustment", Short: "补卡规则", RunE: groupRunE})
 
 	// MCP tool: get_adjustment_rule_detail
 	attendanceAdjustmentGetCmd := &cobra.Command{
@@ -1540,7 +1540,7 @@ checkTime 字段统一使用 "HH:mm" 格式（如 "09:00"），CLI 自动转换
 
 	// ── overtime-rule ──────────────────────────────────────
 
-	attendanceOvertimeCmd := &cobra.Command{Use: "overtime", Short: "加班规则", RunE: groupRunE}
+	attendanceOvertimeCmd := newGroupCommand(&cobra.Command{Use: "overtime", Short: "加班规则", RunE: groupRunE})
 
 	// MCP tool: get_overtime_rule_detail
 	attendanceOvertimeGetCmd := &cobra.Command{
@@ -1665,7 +1665,7 @@ checkTime 字段统一使用 "HH:mm" 格式（如 "09:00"），CLI 自动转换
 
 	// ── group ──────────────────────────────────────────────
 
-	attendanceGroupCmd := &cobra.Command{Use: "group", Short: "考勤组", RunE: groupRunE}
+	attendanceGroupCmd := newGroupCommand(&cobra.Command{Use: "group", Short: "考勤组", RunE: groupRunE})
 
 	// MCP tool: get_simple_groups
 	attendanceGroupSearchCmd := &cobra.Command{
@@ -2574,7 +2574,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 	})
 
 	// ── selfsetting ─────────────────────────────────────────────
-	attendanceSelfSettingCmd := &cobra.Command{
+	attendanceSelfSettingCmd := newGroupCommand(&cobra.Command{
 		Use:   "selfsetting",
 		Short: "个人规则设置",
 		Long: `个人规则设置相关命令。
@@ -2583,7 +2583,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
   get   查询个人规则设置，包括打卡提醒、极速打卡、打卡结果通知、缺卡提醒、个人考勤统计通知、团队考勤统计通知等设置项。
   save  更新保存个人规则设置；settingScene 必填，且对应场景至少传入一个设置字段。`,
 		RunE: groupRunE,
-	}
+	})
 
 	// MCP tool: query_self_setting
 	attendanceSelfSettingGetCmd := &cobra.Command{
@@ -2827,7 +2827,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 	})
 
 	// ── globalsetting ────────────────────────────────────────
-	attendanceGlobalSettingCmd := &cobra.Command{
+	attendanceGlobalSettingCmd := newGroupCommand(&cobra.Command{
 		Use:   "globalsetting",
 		Short: "全局规则设置（仅管理员）",
 		Long: `全局规则设置相关命令，仅管理员可以调用。
@@ -2836,7 +2836,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
   get   查询全局规则设置，包括打卡提醒、极速打卡、打卡结果通知、缺卡提醒、个人考勤统计通知、团队考勤统计通知等设置项。
   save  更新保存全局规则设置；settingScene 必填，且对应场景至少传入一个设置字段。`,
 		RunE: groupRunE,
-	}
+	})
 
 	// MCP tool: query_global_setting
 	attendanceGlobalSettingGetCmd := &cobra.Command{
@@ -2999,7 +2999,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 
 	// ── report ──────────────────────────────────────────────
 
-	attendanceReportCmd := &cobra.Command{
+	attendanceReportCmd := newGroupCommand(&cobra.Command{
 		Use:   "report",
 		Short: "查询考勤报表和结果",
 		Long: `考勤 MCP 报表接口，仅对管理员开放
@@ -3009,7 +3009,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
   query-data  根据字段查询考勤数据
   query-leave 查询用户假期数据`,
 		RunE: groupRunE,
-	}
+	})
 
 	// MCP tool: get_report_columns
 	reportColumnsCmd := &cobra.Command{
@@ -3218,7 +3218,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 
 	// ── 假期 vacation ───────────────────────────────────────────────
 
-	attendanceVacationCmd := &cobra.Command{
+	attendanceVacationCmd := newGroupCommand(&cobra.Command{
 		Use:   "vacation",
 		Short: "假期管理",
 		Long: `管理钉钉假期：查询假期规则列表、查询员工假期余额、查询假期余额变更记录。
@@ -3230,7 +3230,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
   save-balance 更新员工假期余额
   records      查询指定员工假期余额变更记录`,
 		RunE: groupRunE,
-	}
+	})
 
 	// ── 假期规则 types ─────────────────────────────────────────
 
@@ -3771,7 +3771,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 
 	// ── schedule ──────────────────────────────────────────────
 
-	attendanceScheduleCmd := &cobra.Command{
+	attendanceScheduleCmd := newGroupCommand(&cobra.Command{
 		Use:   "schedule",
 		Short: "排班管理",
 		Long: `排班制考勤组的排班记录导入与查询（排班 = 为员工安排具体工作日期和班次）。
@@ -3779,7 +3779,7 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
   import  导入排班记录到排班制考勤组
   get     获取指定用户的排班记录`,
 		RunE: groupRunE,
-	}
+	})
 
 	// schedule import (generateTurnSchedule)
 	scheduleImportCmd := &cobra.Command{
@@ -4219,14 +4219,14 @@ statsType 统计类型支持：week（周统计）、month（月统计）。`,
 
 	// ── checkin ──────────────────────────────────────────────
 
-	checkinCmd := &cobra.Command{
+	checkinCmd := newGroupCommand(&cobra.Command{
 		Use:   "checkin",
 		Short: "签到管理",
 		Long: `签到记录的查询。
 子命令:
   records  查询指定员工的签到记录`,
 		RunE: groupRunE,
-	}
+	})
 
 	// MCP tool: queryUserRecordByStaffIds
 	checkinRecordsCmd := &cobra.Command{

internal/helpers/calendar.go

@@ -2,14 +2,11 @@ package helpers
 
 import (
 	"encoding/json"
-	"fmt"
-	"os"
 	"sort"
 	"strconv"
 	"strings"
 	"time"
 
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/spf13/cobra"
 )
@@ -18,10 +15,9 @@ import (
 // dws calendar — 日历产品命令组
 // ──────────────────────────────────────────────────────────
 
-// calendarInfoHintSubCmd builds a hidden disambiguation subcommand that prints
-// a warning-level "Did you mean" hint to stderr (instead of returning an Error)
-// and exits 0. Scoped to calendar.go on purpose so the shared cmdutil.HintSubCmd
-// used by other products keeps returning errors as before.
+// calendarInfoHintSubCmd builds a hidden disambiguation subcommand that returns
+// the shared typed validation error while preserving Calendar's reviewed
+// replacement guidance.
 //
 // The `suggestion` argument should be the bare corrected command (no leading
 // "use:" / "hint:" prefix); the helper wraps it with the standard "Did you
@@ -29,186 +25,9 @@ import (
 func calendarInfoHintSubCmd(use, suggestion string) *cobra.Command {
 	c := hintSubCmd(use, suggestion)
 	c.DisableFlagParsing = true
-	c.RunE = func(cmd *cobra.Command, args []string) error {
-		fmt.Fprintf(os.Stderr, "warning: command %q does not exist\n  hint: %s\t %s\n more: %s \n",
-			cmd.Parent().CommandPath()+" "+use,
-			suggestion,
-			"[MUST] use --help to see command detail",
-			"'dws calendar --help' to see all available commands")
-		return nil
-	}
 	return c
 }
 
-// installUnknownVerbFallback makes `group` emit a consistent warning-style
-// "Did you mean" hint whenever the caller types an unknown subcommand under
-// that group, regardless of whether extra flags follow. This is a blanket
-// safety net that covers every verb we never thought to pre-register via
-// calendarInfoHintSubCmd (e.g. `dws calendar room query --min-duration 30`).
-//
-// Two Cobra knobs make this work together:
-//   - FParseErrWhitelist.UnknownFlags=true stops pflag from aborting with
-//     "unknown flag: --xxx" before RunE ever runs.
-//   - Args=cobra.ArbitraryArgs lets Cobra pass the bad verb through as the
-//     first positional arg instead of rejecting it.
-//
-// If the user types a *known* subcommand, Cobra still dispatches to that
-// child's RunE as usual; this fallback only fires when resolution stops at
-// `group` with leftover args.
-func installUnknownVerbFallback(group *cobra.Command) {
-	group.FParseErrWhitelist.UnknownFlags = true
-	group.Args = cobra.ArbitraryArgs
-
-	// Override HelpFunc so that `<group> <unknown-verb> --help` also shows
-	// the "unknown subcommand" error instead of silently printing help.
-	// Cobra intercepts --help before RunE, so without this the fallback
-	// would never fire when --help is present.
-	origHelp := group.HelpFunc()
-	group.SetHelpFunc(func(cmd *cobra.Command, args []string) {
-		if cmd == group {
-			// HelpFunc receives os.Args[1:] (full arg slice without binary).
-			// Strip tokens matching the resolved command path to get actual
-			// leftover args that should be checked for unknown verbs.
-			depth := len(strings.Fields(cmd.CommandPath())) - 1
-			leftover := stripCommandPrefix(args, depth)
-			if bad := findUnknownVerb(cmd, leftover); bad != "" {
-				printUnknownSubcmdError(cmd, bad)
-				return
-			}
-			origHelp(cmd, args)
-			return
-		}
-		// For non-group commands, render base help then apply the safety
-		// annotation. Recursion safety hinges on NOT calling
-		// cmd.Root().HelpFunc(): in test trees calendar IS the root, so that
-		// would re-enter this wrapper. origHelp was captured before any
-		// wrapping and is the plain cobra renderer.
-		origHelp(cmd, args)
-		cli.RenderSafetyAnnotation(cmd)
-	})
-
-	prev := group.RunE
-	group.RunE = func(cmd *cobra.Command, args []string) error {
-		// Unknown flags whitelisted by pflag may leak into args. Pick the first
-		// non-flag token as the offending verb.
-		if bad := findUnknownVerb(cmd, args); bad != "" {
-			printUnknownSubcmdError(cmd, bad)
-			return nil
-		}
-		// No unknown verb found. Since FParseErrWhitelist.UnknownFlags silently
-		// swallows bad flags, scan the original os.Args for flags unregistered
-		// on this command and report them explicitly.
-		if flag := findUnknownFlag(cmd); flag != "" {
-			fmt.Fprintf(os.Stderr, "Error: unknown flag: %s\n", flag)
-			fmt.Fprintf(os.Stderr, "  hint: Run '%s --help' to see available options\n", cmd.CommandPath())
-			return nil
-		}
-		if prev != nil {
-			return prev(cmd, args)
-		}
-		return cmd.Help()
-	}
-}
-
-// findUnknownVerb returns the first positional arg that is not a registered
-// subcommand (or alias) of cmd. Returns "" if all args are flags or known.
-func findUnknownVerb(cmd *cobra.Command, args []string) string {
-	for _, a := range args {
-		if strings.HasPrefix(a, "-") {
-			continue
-		}
-		isKnown := false
-		for _, c := range cmd.Commands() {
-			if c.Name() == a {
-				isKnown = true
-				break
-			}
-			for _, alias := range c.Aliases {
-				if alias == a {
-					isKnown = true
-					break
-				}
-			}
-			if isKnown {
-				break
-			}
-		}
-		if !isKnown {
-			return a
-		}
-	}
-	return ""
-}
-
-// printUnknownSubcmdError prints the standard "unknown subcommand" error to
-// stderr with available commands and a did-you-mean hint.
-func printUnknownSubcmdError(cmd *cobra.Command, bad string) {
-	var available []string
-	for _, c := range cmd.Commands() {
-		if !c.Hidden && c.Name() != "help" {
-			available = append(available, c.Name())
-		}
-	}
-	fmt.Fprintf(os.Stderr, "Error: unknown subcommand %q for %q\n", bad, cmd.CommandPath())
-	fmt.Fprintf(os.Stderr, "  available: %s\n", strings.Join(available, ", "))
-	if s := cmd.SuggestionsFor(bad); len(s) > 0 {
-		fmt.Fprintf(os.Stderr, "  hint: did you mean %q\n", cmd.CommandPath()+" "+s[0])
-	} else {
-		fmt.Fprintf(os.Stderr, "  hint: %s --help\n", cmd.CommandPath())
-	}
-}
-
-// stripCommandPrefix strips the first `depth` non-flag tokens from args.
-// This is needed because Cobra's HelpFunc receives os.Args[1:] (the full arg
-// slice without the binary name), including the resolved command path tokens.
-// depth should be len(strings.Fields(cmd.CommandPath())) - 1.
-func stripCommandPrefix(args []string, depth int) []string {
-	skipped := 0
-	for i, a := range args {
-		if skipped >= depth {
-			return args[i:]
-		}
-		if !strings.HasPrefix(a, "-") {
-			skipped++
-		}
-	}
-	return nil
-}
-
-// findUnknownFlag scans os.Args for flags that are not registered on cmd.
-// Returns the first offending flag token (e.g. "--today") or "".
-func findUnknownFlag(cmd *cobra.Command) string {
-	depth := len(strings.Fields(cmd.CommandPath())) - 1
-	leftover := stripCommandPrefix(os.Args[1:], depth)
-	for i := 0; i < len(leftover); i++ {
-		a := leftover[i]
-		if a == "--" {
-			break
-		}
-		if strings.HasPrefix(a, "--") {
-			name := a[2:]
-			if eqIdx := strings.Index(name, "="); eqIdx >= 0 {
-				name = name[:eqIdx]
-			}
-			if name == "help" {
-				continue
-			}
-			if cmd.Flags().Lookup(name) == nil {
-				return a
-			}
-		} else if strings.HasPrefix(a, "-") && a != "-" {
-			ch := a[1:2]
-			if ch == "h" {
-				continue
-			}
-			if cmd.Flags().ShorthandLookup(ch) == nil {
-				return a
-			}
-		}
-	}
-	return ""
-}
-
 func newCalendarCommand() *cobra.Command {
 	// Product-level Agent routing Decl (migrated from selection/calendar.json
 	// products.calendar). Catalog assembly stamps provenance contract_final.
@@ -224,7 +43,7 @@ func newCalendarCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "calendar",
 		Short: "日历日程 / 会议室 / 闲忙",
 		Long: `管理钉钉日历：日程、参会人、会议室、闲忙、附件、日历本、访问权限。调用前必须先使用 --help 查看参数结构。
@@ -238,11 +57,11 @@ func newCalendarCommand() *cobra.Command {
   dws calendar book        [list|get|search|update]          日历本管理
   dws calendar acl         [list|add|delete]                 日历访问权限管理`,
 		RunE: groupRunE,
-	}
+	})
 
 	// ── event: 日程 ─────────────────────────────────────────────
 
-	eventCmd := &cobra.Command{Use: "event", Short: "日程管理", RunE: groupRunE}
+	eventCmd := newGroupCommand(&cobra.Command{Use: "event", Short: "日程管理", RunE: groupRunE})
 
 	eventListCmd := &cobra.Command{
 		Use:   "list",
@@ -816,13 +635,13 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── attendee: 参会人 (曾用名: participant) ─────────────────
 
-	participantCmd := &cobra.Command{
+	participantCmd := newGroupCommand(&cobra.Command{
 		Use:     "attendee",
 		Aliases: []string{"participant"},
 		Short:   "日程参会人管理",
 		Long:    "管理日程的参会人。alias：`participant`，仍作为别名保留，历史调用无需改动。",
 		RunE:    groupRunE,
-	}
+	})
 
 	participantListCmd := &cobra.Command{
 		Use:     "list",
@@ -1008,7 +827,7 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── room: 会议室 ────────────────────────────────────────────
 
-	roomCmd := &cobra.Command{Use: "room", Short: "会议室管理", RunE: groupRunE}
+	roomCmd := newGroupCommand(&cobra.Command{Use: "room", Short: "会议室管理", RunE: groupRunE})
 
 	roomSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -1352,7 +1171,7 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── busy: 闲忙 ──────────────────────────────────────────────
 
-	busyCmd := &cobra.Command{Use: "busy", Short: "闲忙查询", RunE: groupRunE}
+	busyCmd := newGroupCommand(&cobra.Command{Use: "busy", Short: "闲忙查询", RunE: groupRunE})
 
 	busySearchCmd := &cobra.Command{
 		Use:   "search",
@@ -1444,7 +1263,7 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── attachment: 附件 ────────────────────────────────────────
 
-	attachmentCmd := &cobra.Command{Use: "attachment", Short: "日程附件管理", RunE: groupRunE}
+	attachmentCmd := newGroupCommand(&cobra.Command{Use: "attachment", Short: "日程附件管理", RunE: groupRunE})
 
 	attachmentAddCmd := &cobra.Command{
 		Use:   "add",
@@ -1529,7 +1348,7 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── acl: 日历访问权限 ─────────────────────────────────────────
 
-	aclCmd := &cobra.Command{Use: "acl", Short: "管理我的日历访问权限（共享给他人）", RunE: groupRunE}
+	aclCmd := newGroupCommand(&cobra.Command{Use: "acl", Short: "管理我的日历访问权限（共享给他人）", RunE: groupRunE})
 
 	aclListCmd := &cobra.Command{
 		Use:     "list",
@@ -1619,7 +1438,7 @@ func newCalendarCommand() *cobra.Command {
 
 	// ── book: 日历本 ────────────────────────────────────────────
 
-	bookCmd := &cobra.Command{Use: "book", Short: "日历本管理（我能看哪些日历）", RunE: groupRunE}
+	bookCmd := newGroupCommand(&cobra.Command{Use: "book", Short: "日历本管理（我能看哪些日历）", RunE: groupRunE})
 
 	bookListCmd := &cobra.Command{
 		Use:   "list",
@@ -2657,12 +2476,6 @@ func newCalendarCommand() *cobra.Command {
 
 	root.AddCommand(eventCmd, participantCmd, roomCmd, busyCmd, attachmentCmd, bookCmd, aclCmd)
 
-	// Install the unknown-verb fallback on every group command. This covers
-	// arbitrary typos like `dws calendar room query --min-duration 30` that
-	// the per-verb calendarInfoHintSubCmd registrations below can't anticipate.
-	for _, g := range []*cobra.Command{root, eventCmd, participantCmd, roomCmd, busyCmd, attachmentCmd, bookCmd, aclCmd} {
-		installUnknownVerbFallback(g)
-	}
 	// Hint subcommands must swallow any extra flags/args the caller passes,
 	// otherwise `dws calendar list` prints the nice "ambiguous command" hint
 	// but `dws calendar list --start ...` fails earlier with cobra's

internal/helpers/calendar_command_coverage_more_test.go

@@ -1,9 +1,10 @@
 package helpers
 
 import (
-	"os"
+	"errors"
 	"testing"
 
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
 )
 
@@ -46,16 +47,13 @@ func TestCrossPlatformCoverageCalendarOptionalFlagsRemainingCoverage(t *testing.
 
 func TestCrossPlatformCoverageCalendarUnknownFlagAndSuggestionRemainingCoverage(t *testing.T) {
 	root := &cobra.Command{Use: "calendar"}
-	group := &cobra.Command{Use: "room"}
+	group := newGroupCommand(&cobra.Command{Use: "room"})
 	group.SuggestionsMinimumDistance = 3
 	group.AddCommand(&cobra.Command{Use: "search", SuggestFor: []string{"serach"}, Run: func(*cobra.Command, []string) {}})
 	root.AddCommand(group)
-	installUnknownVerbFallback(group)
-	oldArgs := os.Args
-	os.Args = []string{"dws", "calendar", "room", "--unknown"}
-	t.Cleanup(func() { os.Args = oldArgs })
-	if err := group.RunE(group, nil); err != nil {
-		t.Fatalf("unknown flag fallback: %v", err)
+	err := group.RunE(group, []string{"serach"})
+	var structured *apperrors.Error
+	if !errors.As(err, &structured) || structured.Reason != "unknown_subcommand" {
+		t.Fatalf("typed suggestion fallback: %#v", err)
 	}
-	printUnknownSubcmdError(group, "serach")
 }

internal/helpers/calendar_coverage_more_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 	"time"
 
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
 )
 
@@ -175,42 +176,22 @@ func TestCrossPlatformCoverageBuildRecurrenceCoverage(t *testing.T) {
 
 func TestCrossPlatformCoverageCalendarUnknownFallbackCoverage(t *testing.T) {
 	root := &cobra.Command{Use: "calendar"}
-	group := &cobra.Command{Use: "room", RunE: func(*cobra.Command, []string) error { return errors.New("previous") }}
+	group := newGroupCommand(&cobra.Command{Use: "room"})
 	known := &cobra.Command{Use: "search", Aliases: []string{"find"}}
 	hidden := &cobra.Command{Use: "secret", Hidden: true}
 	group.AddCommand(known, hidden)
 	root.AddCommand(group)
-	installUnknownVerbFallback(group)
-	_ = group.RunE(group, []string{"unknown"})
-	_ = group.RunE(group, []string{"--ignored", "search"})
-	_ = group.RunE(group, nil)
-	group.HelpFunc()(group, []string{"calendar", "room", "unknown"})
-	group.HelpFunc()(known, nil)
-	printUnknownSubcmdError(group, "searhc")
-	printUnknownSubcmdError(group, "unrelated")
+	var structured *apperrors.Error
+	if err := group.RunE(group, []string{"searhc"}); !errors.As(err, &structured) || structured.Reason != "unknown_subcommand" {
+		t.Fatalf("typed group recovery = %#v", err)
+	}
+	if err := group.RunE(group, nil); err != nil {
+		t.Fatalf("group help = %v", err)
+	}
 
 	hint := calendarInfoHintSubCmd("query", "use search")
 	group.AddCommand(hint)
-	_ = hint.RunE(hint, nil)
-
-	oldArgs := os.Args
-	t.Cleanup(func() { os.Args = oldArgs })
-	group.Flags().StringP("known", "k", "", "")
-	for _, args := range [][]string{
-		{"dws", "calendar", "room", "--"},
-		{"dws", "calendar", "room", "--help"},
-		{"dws", "calendar", "room", "--known=value"},
-		{"dws", "calendar", "room", "--unknown=value"},
-		{"dws", "calendar", "room", "-h"},
-		{"dws", "calendar", "room", "-k", "value"},
-		{"dws", "calendar", "room", "-x"},
-	} {
-		os.Args = args
-		_ = findUnknownFlag(group)
+	if err := hint.RunE(hint, nil); err == nil {
+		t.Fatal("calendar compatibility hint succeeded")
 	}
-	nilPrev := &cobra.Command{Use: "empty"}
-	root.AddCommand(nilPrev)
-	installUnknownVerbFallback(nilPrev)
-	os.Args = []string{"dws", "calendar", "empty"}
-	_ = nilPrev.RunE(nilPrev, nil)
 }

internal/helpers/chat.go

@@ -2403,13 +2403,13 @@ func newChatCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:     "chat",
 		Aliases: []string{"im"},
 		Short:   "群聊 / 消息 / 机器人",
 		Long:    `管理钉钉会话与群聊：创建群、搜索群、查看群成员、添加机器人到群、修改群名称、拉取/发送/收藏会话消息、机器人消息与 Webhook。`,
 		RunE:    groupRunE,
-	}
+	})
 
 	chatChmodCmd := &cobra.Command{
 		Use:   "chmod <scope>",
@@ -2499,12 +2499,12 @@ func newChatCommand() *cobra.Command {
 		},
 	})
 
-	chatDataAuthCmd := &cobra.Command{
+	chatDataAuthCmd := newGroupCommand(&cobra.Command{
 		Use:   "data-auth",
 		Short: "授予 chat 数据读取权限",
 		Long:  `授予 chat 数据读取权限。该命令用于跨组织消息拉取等数据访问场景，不用于发送、撤回、群管理等命令操作。`,
 		RunE:  groupRunE,
-	}
+	})
 	chatDataAuthCrossOrgCmd := &cobra.Command{
 		Use:   "cross-org",
 		Short: "授予跨组织 chat 数据访问权限",
@@ -2576,7 +2576,7 @@ func newChatCommand() *cobra.Command {
 
 	// ── group 子命令 ──────────────────────────────────────────
 
-	chatGroupCmd := &cobra.Command{Use: "group", Short: "群组管理", RunE: groupRunE}
+	chatGroupCmd := newGroupCommand(&cobra.Command{Use: "group", Short: "群组管理", RunE: groupRunE})
 
 	chatGroupCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -2766,6 +2766,7 @@ func newChatCommand() *cobra.Command {
 			return callMCPTool("get_group_members", toolArgs)
 		},
 	}
+	newHybridGroupCommand(chatGroupMembersCmd)
 
 	chatGroupMembersAddBotCmd := &cobra.Command{
 		Use:   "add-bot",
@@ -2974,12 +2975,12 @@ func newChatCommand() *cobra.Command {
 
 	// ── message 子命令 ────────────────────────────────────────
 
-	chatMessageCmd := &cobra.Command{
+	chatMessageCmd := newGroupCommand(&cobra.Command{
 		Use:   "message",
 		Short: "会话消息管理",
 		Long:  `管理会话消息，包括拉取、发送、搜索、转发、钉住、收藏和撤回消息。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	chatMessageListCmd := &cobra.Command{
 		Use:   "list",
@@ -4674,7 +4675,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 
 	// ── bot 子命令 ────────────────────────────────────────────
 
-	chatBotCmd := &cobra.Command{Use: "bot", Short: "机器人管理", RunE: groupRunE}
+	chatBotCmd := newGroupCommand(&cobra.Command{Use: "bot", Short: "机器人管理", RunE: groupRunE})
 
 	chatBotSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -5210,12 +5211,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 
 	// ── file 子命令（会话文件上传，不暴露 spaceId）───────────────
 
-	chatFileCmd := &cobra.Command{
+	chatFileCmd := newGroupCommand(&cobra.Command{
 		Use:    "file",
 		Short:  "会话文件上传（已下线）",
 		Hidden: true,
 		RunE:   groupRunE,
-	}
+	})
 
 	chatFileUploadCmd := &cobra.Command{
 		Use:    "upload",
@@ -5250,7 +5251,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 
 	// ── category 子命令（会话分组，走 IM MCP）───────────────────
 
-	chatCategoryCmd := &cobra.Command{Use: "category", Short: "会话分组管理", RunE: groupRunE}
+	chatCategoryCmd := newGroupCommand(&cobra.Command{Use: "category", Short: "会话分组管理", RunE: groupRunE})
 
 	chatCategoryListCmd := &cobra.Command{
 		Use:   "list",
@@ -7580,7 +7581,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 
 	// ── group-role 子命令（群身份管理）────────────────────────
 
-	chatGroupRoleCmd := &cobra.Command{Use: "group-role", Short: "群身份管理", RunE: groupRunE}
+	chatGroupRoleCmd := newGroupCommand(&cobra.Command{Use: "group-role", Short: "群身份管理", RunE: groupRunE})
 
 	chatGroupRoleListCmd := &cobra.Command{
 		Use:   "list",
@@ -9864,7 +9865,7 @@ status 可选值:
 	})
 
 	// ── group notice: 群公告管理 ────────────────────────────────
-	chatGroupNoticeCmd := &cobra.Command{Use: "notice", Short: "群公告管理", RunE: groupRunE}
+	chatGroupNoticeCmd := newGroupCommand(&cobra.Command{Use: "notice", Short: "群公告管理", RunE: groupRunE})
 
 	chatGroupNoticeCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -10385,7 +10386,7 @@ status 可选值:
 		"fi_FI": true, "cs_CZ": true, "ar_SA": true, "tl_PH": true,
 		"he_IL": true, "nl_NL": true, "lo_LA": true, "it_IT": true,
 	}
-	chatTextCmd := &cobra.Command{Use: "text", Short: "文本内容处理", RunE: groupRunE}
+	chatTextCmd := newGroupCommand(&cobra.Command{Use: "text", Short: "文本内容处理", RunE: groupRunE})
 	chatTextTranslateCmd := &cobra.Command{
 		Use:   "translate",
 		Short: "翻译文本内容",
@@ -10450,11 +10451,11 @@ pl_PL, sv_SE, fi_FI, cs_CZ, ar_SA, tl_PH, he_IL, nl_NL, lo_LA, it_IT`,
 	chatGroupCmd.AddCommand(chatGroupBotsCmd, chatGroupDismissCmd, chatGroupSetHistoryCmd, chatGroupListMyGroupsCmd, chatGroupUpdateNickCmd, chatGroupUpdateAliasCmd, chatGroupListAllCmd, chatGroupListJoinValidationsCmd, chatGroupAuditJoinValidationCmd, chatGroupNoticeCmd, chatGroupShareInviteCmd, chatGroupUpgradeToExternalCmd)
 
 	// ── chat group user-settings ──
-	chatGroupUserSettingsCmd := &cobra.Command{
+	chatGroupUserSettingsCmd := newGroupCommand(&cobra.Command{
 		Use:   "user-settings",
 		Short: "批量查询或更新当前用户的群会话设置",
 		RunE:  groupRunE,
-	}
+	})
 	chatGroupUserSettingsQueryCmd := &cobra.Command{
 		Use:     "query",
 		Short:   "批量查询当前用户的群会话设置",

internal/helpers/chat/toolbar.go

@@ -13,7 +13,10 @@
 
 package chat
 
-import "github.com/spf13/cobra"
+import (
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/spf13/cobra"
+)
 
 func newChatToolbarCommand() *cobra.Command {
 	toolbarCmd := &cobra.Command{
@@ -22,6 +25,11 @@ func newChatToolbarCommand() *cobra.Command {
 		Long:  "管理会话快捷栏入口：查询、添加、隐藏、排序及自定义入口 CRUD。",
 		RunE:  groupRunE,
 	}
+	corecmd.ApplyGroupPolicy(toolbarCmd, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
 	toolbarCmd.DisableAutoGenTag = true
 
 	toolbarCmd.AddCommand(

internal/helpers/chat_command_edges_test.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"testing"
 
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
 )
@@ -121,8 +122,12 @@ func TestCrossPlatformCoverageChatStableCompatibilityHintsRemainAvailable(t *tes
 		}
 		root.SetArgs(tc.args)
 		err = root.ExecuteContext(context.Background())
-		if err == nil || !strings.Contains(err.Error(), "ambiguous command") || !strings.Contains(err.Error(), tc.hint) {
-			t.Fatalf("chat %s with legacy flags error = %v, want migration hint %q", tc.path, err, tc.hint)
+		var structured *apperrors.Error
+		if !errors.As(err, &structured) {
+			t.Fatalf("chat %s with legacy flags error = %T %v, want structured validation", tc.path, err, err)
+		}
+		if structured.Category != apperrors.CategoryValidation || structured.Reason != "unknown_subcommand" || !strings.Contains(structured.Hint, tc.hint) {
+			t.Fatalf("chat %s with legacy flags error = %#v, want migration hint %q", tc.path, structured, tc.hint)
 		}
 	}
 }

internal/helpers/chat_media_upload.go

@@ -33,6 +33,7 @@ func newChatMediaGroup() *cobra.Command {
 		},
 	}
 	media.AddCommand(newChatMediaUploadCommand())
+	newHybridGroupCommand(media)
 	return media
 }
 

internal/helpers/chat_personal_emotion.go

@@ -13,12 +13,12 @@ import (
 const personalEmotionUnpinnedReason = "Reviewed unpinned remote adapter: this executable CLI wrapper calls a remote helper that is absent from the pinned MCP metadata snapshot; no single pinned semantically equivalent interface_ref can represent the command."
 
 func newChatEmotionCommand() *cobra.Command {
-	cmd := &cobra.Command{
+	cmd := newGroupCommand(&cobra.Command{
 		Use:   "emotion",
 		Short: "个人收藏表情",
 		Long:  "查询、发送和新增当前用户的个人收藏表情。",
 		RunE:  groupRunE,
-	}
+	})
 	cmd.AddCommand(
 		newChatEmotionListCommand(),
 		newChatEmotionSendCommand(),

internal/helpers/college_contact_test.go

@@ -1,788 +0,0 @@
-package helpers
-
-import (
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-func TestCrossPlatformCoverageCollegeContactCommand_Structure(t *testing.T) {
-	cmd := newCollegeContactCommand()
-
-	if cmd.Name() != "college-contact" {
-		t.Errorf("expected name 'college-contact', got %q", cmd.Name())
-	}
-	if !cmd.Hidden {
-		t.Error("extension root command should be Hidden")
-	}
-
-	// 分组 → 叶子命令映射
-	groups := map[string][]string{
-		"dept": {
-			"get-standard-structure", "get-detail", "get-chain", "search",
-			"create", "update", "delete", "batch-update-type", "overview",
-		},
-		"employee": {
-			"get-detail", "add", "remove", "change-type", "change-dept",
-			"send-active-sms", "list-employees", "list-unaccepted",
-			"list-unactive", "upgrade-status", "start-upgrade",
-		},
-		"alumni": {
-			"get-dept-tree", "get-info", "list", "query", "search", "list-unaccepted", "get-group", "create-dept", "update-dept", "delete-dept", "update-managers", "add-alumnus", "update-alumnus", "remove-alumnus", "cancel-invite", "create-group", "disband-group", "get-alumni-org-from-graduate", "create-alumni-org", "add-alumni-org-main-admins",
-		},
-		"graduate": {
-			"query-graduate-years", "query-graduate-depts", "query-graduate-sub-depts", "query-page-graduate-users", "get-task-result", "get-alumni-org", "query-restore-sub-depts", "query-dept-deleted-emps", "search-graduate", "commit-graduate", "all-graduate", "batch-graduate", "delete-and-graduate", "batch-delete-pending", "batch-update-pending", "commit-restore",
-		},
-		"group": {
-			"query-group-rule", "get-group-rule-schedule", "query-preview-data", "create-group-rule", "delete-group-rule", "enable-group-rule", "disable-group-rule", "set-group-rule-schedule", "execute-group-rule",
-		},
-	}
-
-	for groupName, leaves := range groups {
-		var groupCmd *cobra.Command
-		for _, c := range cmd.Commands() {
-			if c.Name() == groupName {
-				groupCmd = c
-				break
-			}
-		}
-		if groupCmd == nil {
-			t.Fatalf("subcommand group %q not found", groupName)
-		}
-		for _, leaf := range leaves {
-			found := false
-			for _, c := range groupCmd.Commands() {
-				if c.Name() == leaf {
-					found = true
-					break
-				}
-			}
-			if !found {
-				t.Errorf("leaf command %q not found under %q", leaf, groupName)
-			}
-		}
-	}
-
-	// stats 分组已移除
-	for _, c := range cmd.Commands() {
-		if c.Name() == "stats" {
-			t.Error("subcommand group 'stats' should be removed")
-		}
-	}
-}
-
-func TestCrossPlatformCoverageCollegeContactCommand_FindPath(t *testing.T) {
-	root := &cobra.Command{Use: "dws"}
-	root.AddCommand(newCollegeContactCommand())
-
-	c, _, err := root.Find([]string{"college-contact", "dept", "get-standard-structure"})
-	if err != nil {
-		t.Fatalf("command path not found: %v", err)
-	}
-	if c.Name() != "get-standard-structure" {
-		t.Errorf("expected leaf 'get-standard-structure', got %q", c.Name())
-	}
-}
-
-// newCollegeContactTestRoot 模拟真实运行时的根命令：核心框架在 rootCmd 上
-// 注册全局 persistent --yes flag，叶子命令通过合并后的 Flags() 读取。
-func newCollegeContactTestRoot() *cobra.Command {
-	root := &cobra.Command{Use: "dws"}
-	root.PersistentFlags().BoolP("yes", "y", false, "跳过确认提示")
-	root.AddCommand(newCollegeContactCommand())
-	return root
-}
-
-// runDestructiveLeaf 执行不可逆叶子命令并捕获 panic。
-// 单测环境未初始化 products 运行时依赖，若门禁放行后进入
-// CallMCPToolOnServer 会因 deps 为 nil 而 panic，据此区分
-// “被门禁拦截（返回错误）”与“已越过门禁到达 MCP 调用层（panic）”。
-func runDestructiveLeaf(t *testing.T, args ...string) (err error, panicked bool) {
-	t.Helper()
-	root := newCollegeContactTestRoot()
-	root.SetArgs(args)
-	defer func() {
-		if r := recover(); r != nil {
-			panicked = true
-		}
-	}()
-	err = root.Execute()
-	return err, false
-}
-
-func TestCrossPlatformCoverageCollegeContactDestructive_RejectedWithoutYes(t *testing.T) {
-	cases := [][]string{
-		{"college-contact", "dept", "delete", "--dept-id", "12345"},
-		{"college-contact", "employee", "remove", "--staff-ids", "S12345,S12346"},
-	}
-	for _, args := range cases {
-		err, panicked := runDestructiveLeaf(t, args...)
-		if panicked {
-			t.Fatalf("%v: 未传 --yes 不应到达 MCP 调用层", args)
-		}
-		if err == nil {
-			t.Fatalf("%v: 未传 --yes 应拒绝执行", args)
-		}
-		if !strings.Contains(err.Error(), "--yes") {
-			t.Errorf("%v: 错误信息应提示 --yes，got: %v", args, err)
-		}
-	}
-}
-
-func TestCrossPlatformCoverageCollegeContactDestructive_ProceedsWithYes(t *testing.T) {
-	cases := [][]string{
-		{"college-contact", "dept", "delete", "--dept-id", "12345", "--yes"},
-		{"college-contact", "employee", "remove", "--staff-ids", "S12345", "--yes"},
-	}
-	for _, args := range cases {
-		err, panicked := runDestructiveLeaf(t, args...)
-		if !panicked {
-			// 未 panic 意味着未到达 MCP 调用层；若返回的仍是门禁错误则为拦截失败
-			if err != nil && strings.Contains(err.Error(), "需要用户确认") {
-				t.Fatalf("%v: 已传 --yes 仍被门禁拦截: %v", args, err)
-			}
-		}
-	}
-}
-
-// withCollegeContactCaller installs a dry-run capture caller so happy-path
-// command execution exercises each RunE up to the callMCPToolOnServer dispatch
-// without requiring a live MCP transport. In dry-run mode destructive
-// commands' confirm gate short-circuits to nil, so no --yes flag is needed.
-func withCollegeContactCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-// TestCollegeContactHappyPaths runs every leaf command with required flags only
-// and with all optional flags populated, expecting a nil error (dry-run preview).
-func TestCrossPlatformCoverageCollegeContactHappyPaths(t *testing.T) {
-	withCollegeContactCaller(t)
-
-	cases := [][]string{
-		// ── dept ─────────────────────────────────────────────
-		{"dept", "get-standard-structure"},
-		{"dept", "get-standard-structure", "--dept-id", "123", "--staff-id", "S1", "--keyword", "k", "--offset", "0", "--size", "20"},
-		{"dept", "get-detail", "--dept-id", "123"},
-		{"dept", "get-detail", "--dept-id", "123", "--staff-id", "S1", "--keyword", "k", "--offset", "0", "--size", "20"},
-		{"dept", "get-chain", "--dept-id", "123"},
-		{"dept", "get-chain", "--dept-id", "123", "--staff-id", "S1", "--keyword", "k", "--offset", "0", "--size", "20"},
-		{"dept", "search", "--dept-id", "123", "--keyword", "k"},
-		{"dept", "search", "--dept-id", "123", "--keyword", "k", "--staff-id", "S1", "--offset", "0", "--size", "20"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college", "--create-dept-group", "true"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college", "--create-dept-group", "false", "--dept-id", "5", "--dept-code", "C", "--brief", "b", "--phone", "p"},
-		{"dept", "update", "--dept-id", "123", "--dept-type", "college"},
-		{"dept", "update", "--dept-id", "123", "--dept-type", "college", "--stru-dept-id", "200", "--super-id", "100", "--create-dept-group", "true", "--name", "X", "--dept-code", "C", "--brief", "b", "--phone", "p"},
-		{"dept", "delete", "--dept-id", "123"},
-		{"dept", "batch-update-type", "--dept-ids", "100,200", "--target-dept-type", "college"},
-		{"dept", "overview"},
-		{"dept", "overview", "--dept-id", "123", "--staff-id", "S1", "--keyword", "k", "--offset", "0", "--size", "20"},
-
-		// ── employee ─────────────────────────────────────────
-		{"employee", "get-detail", "--staff-id", "S1"},
-		{"employee", "get-detail", "--staff-id", "S1", "--dept-id", "1", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--name", "n", "--mobile", "m", "--job-number", "j", "--emp-type", "college_student", "--login-id-type", "l", "--order-field", "job_number", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "add", "--emp-type", "college_student", "--main-dept-id", "100", "--exclusive-account", "true"},
-		{"employee", "add", "--emp-type", "college_student", "--main-dept-id", "100", "--exclusive-account", "true", "--dept-id", "1", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--send-active-sms", "false", "--staff-id", "S1", "--name", "n", "--mobile", "m", "--job-number", "j", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "remove", "--staff-ids", "S1"},
-		{"employee", "remove", "--staff-ids", "S1", "--dept-id", "1", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--staff-id", "x", "--name", "n", "--mobile", "m", "--job-number", "j", "--emp-type", "college_student", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc"},
-		{"employee", "change-type", "--staff-id", "S1", "--emp-type", "college_teacher"},
-		{"employee", "change-type", "--staff-id", "S1", "--emp-type", "college_teacher", "--dept-id", "1", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--name", "n", "--mobile", "m", "--job-number", "j", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "change-dept", "--staff-id", "S1", "--target-dept-id", "200"},
-		{"employee", "change-dept", "--staff-id", "S1", "--target-dept-id", "200", "--dept-id", "1", "--main-dept-id", "2", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--name", "n", "--mobile", "m", "--job-number", "j", "--emp-type", "college_student", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "send-active-sms", "--dept-id", "100"},
-		{"employee", "send-active-sms", "--dept-id", "100", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--staff-id", "x", "--name", "n", "--mobile", "m", "--job-number", "j", "--emp-type", "college_student", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "list-employees", "--dept-id", "123"},
-		{"employee", "list-employees", "--dept-id", "123", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--staff-id", "x", "--name", "n", "--mobile", "m", "--job-number", "j", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "list-unaccepted", "--dept-id", "123"},
-		{"employee", "list-unaccepted", "--dept-id", "123", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--staff-id", "x", "--name", "n", "--mobile", "m", "--job-number", "j", "--emp-type", "college_student", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "list-unactive", "--dept-id", "123"},
-		{"employee", "list-unactive", "--dept-id", "123", "--main-dept-id", "2", "--target-dept-id", "3", "--offset", "0", "--size", "20", "--exclusive-account", "true", "--send-active-sms", "true", "--staff-id", "x", "--name", "n", "--mobile", "m", "--job-number", "j", "--login-id-type", "l", "--order-field", "f", "--ordering", "asc", "--staff-ids", "s1,s2"},
-		{"employee", "upgrade-status"},
-		{"employee", "upgrade-status", "--dept-id", "123", "--staff-id", "S1", "--keyword", "k", "--offset", "0", "--size", "20"},
-		{"employee", "start-upgrade"},
-
-		// ── alumni ───────────────────────────────────────────
-		{"alumni", "get-dept-tree", "--alumni-dept-id", "123"},
-		{"alumni", "get-info", "--alumni-dept-id", "123"},
-		{"alumni", "list", "--alumni-dept-id", "1", "--order-field", "dept_entry", "--ordering", "asc"},
-		{"alumni", "list", "--alumni-dept-id", "1", "--order-field", "dept_entry", "--ordering", "asc", "--offset", "0", "--size", "20"},
-		{"alumni", "query", "--staff-id", "S1"},
-		{"alumni", "search", "--keyword", "x"},
-		{"alumni", "search", "--keyword", "x", "--offset", "0", "--size", "20"},
-		{"alumni", "list-unaccepted", "--alumni-dept-id", "1"},
-		{"alumni", "list-unaccepted", "--alumni-dept-id", "1", "--offset", "0", "--size", "20"},
-		{"alumni", "get-group", "--alumni-dept-id", "1"},
-		{"alumni", "create-dept", "--alumni-dept-id", "1", "--dept-name", "D"},
-		{"alumni", "update-dept", "--alumni-dept-id", "1", "--dept-name", "D"},
-		{"alumni", "delete-dept", "--alumni-dept-id", "1"},
-		{"alumni", "update-managers", "--alumni-dept-id", "1", "--admin-user-ids", "u1,u2"},
-		{"alumni", "add-alumnus", "--name", "X", "--mobile", "138", "--dept-ids", "1,2"},
-		{"alumni", "add-alumnus", "--name", "X", "--mobile", "138", "--dept-ids", "1,2", "--student-number", "2020", "--email", "e", "--intake", "2020", "--outtake", "2024"},
-		{"alumni", "update-alumnus", "--staff-id", "S1", "--name", "X", "--dept-ids", "1,2"},
-		{"alumni", "update-alumnus", "--staff-id", "S1", "--name", "X", "--dept-ids", "1,2", "--student-number", "2020", "--email", "e", "--intake", "2020", "--outtake", "2024"},
-		{"alumni", "remove-alumnus", "--staff-id", "S1", "--alumni-dept-id", "1"},
-		{"alumni", "cancel-invite", "--alumni-dept-id", "1", "--staff-ids", "s1,s2"},
-		{"alumni", "create-group", "--alumni-dept-id", "1"},
-		{"alumni", "disband-group", "--alumni-dept-id", "1"},
-		{"alumni", "get-alumni-org-from-graduate"},
-		{"alumni", "create-alumni-org", "--org-name", "O"},
-		{"alumni", "add-alumni-org-main-admins", "--admin-user-ids", "u1,u2"},
-
-		// ── graduate ─────────────────────────────────────────
-		{"graduate", "query-graduate-years"},
-		{"graduate", "query-graduate-depts", "--dept-id", "1"},
-		{"graduate", "query-graduate-depts", "--dept-id", "1", "--graduate-year", "2026"},
-		{"graduate", "query-graduate-sub-depts", "--dept-id", "1"},
-		{"graduate", "query-page-graduate-users", "--dept-id", "1"},
-		{"graduate", "query-page-graduate-users", "--dept-id", "1", "--graduate-year", "2026", "--offset", "0", "--size", "20"},
-		{"graduate", "get-task-result", "--request-no", "r1"},
-		{"graduate", "get-task-result", "--request-no", "r1", "--type", "GRADUATE"},
-		{"graduate", "get-alumni-org"},
-		{"graduate", "query-restore-sub-depts", "--dept-id", "1"},
-		{"graduate", "query-dept-deleted-emps", "--dept-id", "1"},
-		{"graduate", "query-dept-deleted-emps", "--dept-id", "1", "--offset", "0", "--size", "20"},
-		{"graduate", "search-graduate", "--keyword", "x"},
-		{"graduate", "search-graduate", "--keyword", "x", "--offset", "0", "--size", "20"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", "1,2", "--graduate-year", "2026"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", "1,2", "--graduate-year", "2026", "--request-no", "r1"},
-		{"graduate", "all-graduate", "--graduate-year", "2026"},
-		{"graduate", "all-graduate", "--graduate-year", "2026", "--request-no", "r1"},
-		{"graduate", "batch-graduate", "--dept-id", "1", "--staff-ids", "s1,s2"},
-		{"graduate", "delete-and-graduate", "--dept-id", "1", "--staff-ids", "s1,s2"},
-		{"graduate", "batch-delete-pending", "--dept-id", "1", "--staff-ids", "s1,s2"},
-		{"graduate", "batch-update-pending", "--dept-id", "1", "--staff-ids", "s1,s2", "--graduate-year", "2026"},
-		{"graduate", "commit-restore", "--graduate-dept-ids", "1,2"},
-		{"graduate", "commit-restore", "--graduate-dept-ids", "1,2", "--request-no", "r1"},
-
-		// ── group ────────────────────────────────────────────
-		{"group", "query-group-rule"},
-		{"group", "query-group-rule", "--name", "N", "--offset", "0", "--size", "20"},
-		{"group", "get-group-rule-schedule"},
-		{"group", "query-preview-data"},
-		{"group", "query-preview-data", "--offset", "0", "--size", "20"},
-		{"group", "create-group-rule", "--name", "X", "--tag-code", "T", "--dept-type", "college"},
-		{"group", "create-group-rule", "--name", "X", "--tag-code", "T", "--dept-type", "college", "--auto-admin", "true"},
-		{"group", "delete-group-rule", "--rule-id", "1"},
-		{"group", "enable-group-rule", "--rule-id", "1"},
-		{"group", "disable-group-rule", "--rule-id", "1"},
-		{"group", "set-group-rule-schedule"},
-		{"group", "set-group-rule-schedule", "--cron", "0 0 2 * * ?"},
-		{"group", "execute-group-rule"},
-	}
-
-	for _, args := range cases {
-		root := newCollegeContactCommand()
-		if err := executeCommand(root, args...); err != nil {
-			t.Errorf("%v: expected nil error, got: %v", args, err)
-		}
-	}
-}
-
-// TestCollegeContactValidationErrors exercises every validation-error branch:
-// missing required flags, non-integer int flags, invalid bool flags, and
-// empty-after-split CSV lists. Each case must return a non-nil error.
-func TestCrossPlatformCoverageCollegeContactValidationErrors(t *testing.T) {
-	withCollegeContactCaller(t)
-
-	cases := [][]string{
-		// ── dept ─────────────────────────────────────────────
-		{"dept", "get-standard-structure", "--dept-id", "abc"},
-		{"dept", "get-standard-structure", "--offset", "abc"},
-		{"dept", "get-standard-structure", "--size", "abc"},
-		{"dept", "get-detail"},
-		{"dept", "get-detail", "--dept-id", "abc"},
-		{"dept", "get-detail", "--dept-id", "1", "--offset", "abc"},
-		{"dept", "get-detail", "--dept-id", "1", "--size", "abc"},
-		{"dept", "get-chain"},
-		{"dept", "get-chain", "--dept-id", "abc"},
-		{"dept", "get-chain", "--dept-id", "1", "--offset", "abc"},
-		{"dept", "get-chain", "--dept-id", "1", "--size", "abc"},
-		{"dept", "search"},
-		{"dept", "search", "--dept-id", "abc", "--keyword", "k"},
-		{"dept", "search", "--dept-id", "1"},
-		{"dept", "search", "--dept-id", "1", "--keyword", "k", "--offset", "abc"},
-		{"dept", "search", "--dept-id", "1", "--keyword", "k", "--size", "abc"},
-		{"dept", "create"},
-		{"dept", "create", "--super-id", "abc"},
-		{"dept", "create", "--super-id", "100"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "abc"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college", "--create-dept-group", "maybe"},
-		{"dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college", "--create-dept-group", "true", "--dept-id", "abc"},
-		{"dept", "update"},
-		{"dept", "update", "--dept-id", "abc"},
-		{"dept", "update", "--dept-id", "1"},
-		{"dept", "update", "--dept-id", "1", "--dept-type", "college", "--stru-dept-id", "abc"},
-		{"dept", "update", "--dept-id", "1", "--dept-type", "college", "--super-id", "abc"},
-		{"dept", "update", "--dept-id", "1", "--dept-type", "college", "--create-dept-group", "maybe"},
-		{"dept", "delete"},
-		{"dept", "delete", "--dept-id", "abc"},
-		{"dept", "batch-update-type"},
-		{"dept", "batch-update-type", "--dept-ids", "abc", "--target-dept-type", "college"},
-		{"dept", "batch-update-type", "--dept-ids", ",,", "--target-dept-type", "college"},
-		{"dept", "batch-update-type", "--dept-ids", "1,2"},
-		{"dept", "overview", "--dept-id", "abc"},
-		{"dept", "overview", "--offset", "abc"},
-		{"dept", "overview", "--size", "abc"},
-
-		// ── employee ─────────────────────────────────────────
-		{"employee", "get-detail"},
-		{"employee", "get-detail", "--staff-id", "S1", "--dept-id", "abc"},
-		{"employee", "get-detail", "--staff-id", "S1", "--exclusive-account", "maybe"},
-		{"employee", "add"},
-		{"employee", "add", "--emp-type", "x"},
-		{"employee", "add", "--emp-type", "x", "--main-dept-id", "abc"},
-		{"employee", "add", "--emp-type", "x", "--main-dept-id", "100"},
-		{"employee", "add", "--emp-type", "x", "--main-dept-id", "100", "--exclusive-account", "maybe"},
-		{"employee", "add", "--emp-type", "x", "--main-dept-id", "100", "--exclusive-account", "true", "--dept-id", "abc"},
-		{"employee", "add", "--emp-type", "x", "--main-dept-id", "100", "--exclusive-account", "true", "--send-active-sms", "maybe"},
-		{"employee", "remove"},
-		{"employee", "remove", "--staff-ids", ",,"},
-		{"employee", "remove", "--staff-ids", "S1", "--dept-id", "abc"},
-		{"employee", "remove", "--staff-ids", "S1", "--exclusive-account", "maybe"},
-		{"employee", "change-type"},
-		{"employee", "change-type", "--staff-id", "S1"},
-		{"employee", "change-type", "--staff-id", "S1", "--emp-type", "t", "--dept-id", "abc"},
-		{"employee", "change-type", "--staff-id", "S1", "--emp-type", "t", "--exclusive-account", "maybe"},
-		{"employee", "change-dept"},
-		{"employee", "change-dept", "--staff-id", "S1"},
-		{"employee", "change-dept", "--staff-id", "S1", "--target-dept-id", "abc"},
-		{"employee", "change-dept", "--staff-id", "S1", "--target-dept-id", "200", "--dept-id", "abc"},
-		{"employee", "change-dept", "--staff-id", "S1", "--target-dept-id", "200", "--exclusive-account", "maybe"},
-		{"employee", "send-active-sms"},
-		{"employee", "send-active-sms", "--dept-id", "abc"},
-		{"employee", "send-active-sms", "--dept-id", "1", "--main-dept-id", "abc"},
-		{"employee", "send-active-sms", "--dept-id", "1", "--exclusive-account", "maybe"},
-		{"employee", "list-employees"},
-		{"employee", "list-employees", "--dept-id", "abc"},
-		{"employee", "list-employees", "--dept-id", "1", "--main-dept-id", "abc"},
-		{"employee", "list-employees", "--dept-id", "1", "--exclusive-account", "maybe"},
-		{"employee", "list-unaccepted"},
-		{"employee", "list-unaccepted", "--dept-id", "abc"},
-		{"employee", "list-unaccepted", "--dept-id", "1", "--main-dept-id", "abc"},
-		{"employee", "list-unaccepted", "--dept-id", "1", "--exclusive-account", "maybe"},
-		{"employee", "list-unactive"},
-		{"employee", "list-unactive", "--dept-id", "abc"},
-		{"employee", "list-unactive", "--dept-id", "1", "--main-dept-id", "abc"},
-		{"employee", "list-unactive", "--dept-id", "1", "--exclusive-account", "maybe"},
-		{"employee", "upgrade-status", "--dept-id", "abc"},
-		{"employee", "upgrade-status", "--offset", "abc"},
-		{"employee", "upgrade-status", "--size", "abc"},
-
-		// ── alumni ───────────────────────────────────────────
-		{"alumni", "get-dept-tree"},
-		{"alumni", "get-dept-tree", "--alumni-dept-id", "abc"},
-		{"alumni", "get-info"},
-		{"alumni", "get-info", "--alumni-dept-id", "abc"},
-		{"alumni", "list"},
-		{"alumni", "list", "--alumni-dept-id", "abc", "--order-field", "f", "--ordering", "asc"},
-		{"alumni", "list", "--alumni-dept-id", "1"},
-		{"alumni", "list", "--alumni-dept-id", "1", "--order-field", "f"},
-		{"alumni", "list", "--alumni-dept-id", "1", "--order-field", "f", "--ordering", "asc", "--offset", "abc"},
-		{"alumni", "query"},
-		{"alumni", "search"},
-		{"alumni", "search", "--keyword", "x", "--offset", "abc"},
-		{"alumni", "list-unaccepted"},
-		{"alumni", "list-unaccepted", "--alumni-dept-id", "abc"},
-		{"alumni", "list-unaccepted", "--alumni-dept-id", "1", "--offset", "abc"},
-		{"alumni", "get-group"},
-		{"alumni", "get-group", "--alumni-dept-id", "abc"},
-		{"alumni", "create-dept"},
-		{"alumni", "create-dept", "--alumni-dept-id", "abc", "--dept-name", "D"},
-		{"alumni", "create-dept", "--alumni-dept-id", "1"},
-		{"alumni", "update-dept"},
-		{"alumni", "update-dept", "--alumni-dept-id", "abc", "--dept-name", "D"},
-		{"alumni", "update-dept", "--alumni-dept-id", "1"},
-		{"alumni", "delete-dept"},
-		{"alumni", "delete-dept", "--alumni-dept-id", "abc"},
-		{"alumni", "update-managers"},
-		{"alumni", "update-managers", "--alumni-dept-id", "abc", "--admin-user-ids", "u"},
-		{"alumni", "update-managers", "--alumni-dept-id", "1"},
-		{"alumni", "update-managers", "--alumni-dept-id", "1", "--admin-user-ids", ",,"},
-		{"alumni", "add-alumnus"},
-		{"alumni", "add-alumnus", "--name", "X"},
-		{"alumni", "add-alumnus", "--name", "X", "--mobile", "m"},
-		{"alumni", "add-alumnus", "--name", "X", "--mobile", "m", "--dept-ids", "abc"},
-		{"alumni", "add-alumnus", "--name", "X", "--mobile", "m", "--dept-ids", ",,"},
-		{"alumni", "update-alumnus"},
-		{"alumni", "update-alumnus", "--staff-id", "S1"},
-		{"alumni", "update-alumnus", "--staff-id", "S1", "--name", "X"},
-		{"alumni", "update-alumnus", "--staff-id", "S1", "--name", "X", "--dept-ids", "abc"},
-		{"alumni", "update-alumnus", "--staff-id", "S1", "--name", "X", "--dept-ids", ",,"},
-		{"alumni", "remove-alumnus"},
-		{"alumni", "remove-alumnus", "--staff-id", "S1"},
-		{"alumni", "remove-alumnus", "--staff-id", "S1", "--alumni-dept-id", "abc"},
-		{"alumni", "cancel-invite"},
-		{"alumni", "cancel-invite", "--alumni-dept-id", "abc", "--staff-ids", "s"},
-		{"alumni", "cancel-invite", "--alumni-dept-id", "1"},
-		{"alumni", "cancel-invite", "--alumni-dept-id", "1", "--staff-ids", ",,"},
-		{"alumni", "create-group"},
-		{"alumni", "create-group", "--alumni-dept-id", "abc"},
-		{"alumni", "disband-group"},
-		{"alumni", "disband-group", "--alumni-dept-id", "abc"},
-		{"alumni", "create-alumni-org"},
-		{"alumni", "add-alumni-org-main-admins"},
-		{"alumni", "add-alumni-org-main-admins", "--admin-user-ids", ",,"},
-
-		// ── graduate ─────────────────────────────────────────
-		{"graduate", "query-graduate-depts"},
-		{"graduate", "query-graduate-depts", "--dept-id", "abc"},
-		{"graduate", "query-graduate-depts", "--dept-id", "1", "--graduate-year", "abc"},
-		{"graduate", "query-graduate-sub-depts"},
-		{"graduate", "query-graduate-sub-depts", "--dept-id", "abc"},
-		{"graduate", "query-page-graduate-users"},
-		{"graduate", "query-page-graduate-users", "--dept-id", "abc"},
-		{"graduate", "query-page-graduate-users", "--dept-id", "1", "--offset", "abc"},
-		{"graduate", "get-task-result"},
-		{"graduate", "query-restore-sub-depts"},
-		{"graduate", "query-restore-sub-depts", "--dept-id", "abc"},
-		{"graduate", "query-dept-deleted-emps"},
-		{"graduate", "query-dept-deleted-emps", "--dept-id", "abc"},
-		{"graduate", "query-dept-deleted-emps", "--dept-id", "1", "--offset", "abc"},
-		{"graduate", "search-graduate"},
-		{"graduate", "search-graduate", "--keyword", "x", "--offset", "abc"},
-		{"graduate", "commit-graduate"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", "abc"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", ",,"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", "1,2"},
-		{"graduate", "commit-graduate", "--graduate-dept-ids", "1,2", "--graduate-year", "abc"},
-		{"graduate", "all-graduate"},
-		{"graduate", "all-graduate", "--graduate-year", "abc"},
-		{"graduate", "batch-graduate"},
-		{"graduate", "batch-graduate", "--dept-id", "abc"},
-		{"graduate", "batch-graduate", "--dept-id", "1"},
-		{"graduate", "batch-graduate", "--dept-id", "1", "--staff-ids", ",,"},
-		{"graduate", "delete-and-graduate"},
-		{"graduate", "delete-and-graduate", "--dept-id", "abc"},
-		{"graduate", "delete-and-graduate", "--dept-id", "1"},
-		{"graduate", "delete-and-graduate", "--dept-id", "1", "--staff-ids", ",,"},
-		{"graduate", "batch-delete-pending"},
-		{"graduate", "batch-delete-pending", "--dept-id", "abc"},
-		{"graduate", "batch-delete-pending", "--dept-id", "1"},
-		{"graduate", "batch-delete-pending", "--dept-id", "1", "--staff-ids", ",,"},
-		{"graduate", "batch-update-pending"},
-		{"graduate", "batch-update-pending", "--dept-id", "abc"},
-		{"graduate", "batch-update-pending", "--dept-id", "1"},
-		{"graduate", "batch-update-pending", "--dept-id", "1", "--staff-ids", ",,"},
-		{"graduate", "batch-update-pending", "--dept-id", "1", "--staff-ids", "s1"},
-		{"graduate", "batch-update-pending", "--dept-id", "1", "--staff-ids", "s1", "--graduate-year", "abc"},
-		{"graduate", "commit-restore"},
-		{"graduate", "commit-restore", "--graduate-dept-ids", "abc"},
-		{"graduate", "commit-restore", "--graduate-dept-ids", ",,"},
-
-		// ── group ────────────────────────────────────────────
-		{"group", "query-group-rule", "--offset", "abc"},
-		{"group", "query-group-rule", "--size", "abc"},
-		{"group", "query-preview-data", "--offset", "abc"},
-		{"group", "query-preview-data", "--size", "abc"},
-		{"group", "create-group-rule"},
-		{"group", "create-group-rule", "--name", "X"},
-		{"group", "create-group-rule", "--name", "X", "--tag-code", "T"},
-		{"group", "create-group-rule", "--name", "X", "--tag-code", "T", "--dept-type", "college", "--auto-admin", "maybe"},
-		{"group", "delete-group-rule"},
-		{"group", "delete-group-rule", "--rule-id", "abc"},
-		{"group", "enable-group-rule"},
-		{"group", "enable-group-rule", "--rule-id", "abc"},
-		{"group", "disable-group-rule"},
-		{"group", "disable-group-rule", "--rule-id", "abc"},
-	}
-
-	for _, args := range cases {
-		root := newCollegeContactCommand()
-		if err := executeCommand(root, args...); err == nil {
-			t.Errorf("%v: expected non-nil error, got nil", args)
-		}
-	}
-}
-
-// TestCrossPlatformCoverageCollegeContactDestructiveConfirmGate verifies every
-// user_required destructive leaf in a paired manner:
-//   - Without --yes: returns confirmation_required error AND caller is never invoked (zero calls).
-//   - With --yes: proceeds to MCP dispatch with exactly one call AND the correct
-//     productID, tool name, and complete argument payload.
-func TestCrossPlatformCoverageCollegeContactDestructiveConfirmGate(t *testing.T) {
-	type destructiveCase struct {
-		name      string
-		args      []string
-		wantTool  string
-		wantInput map[string]any
-	}
-
-	cases := []destructiveCase{
-		{
-			"dept delete",
-			[]string{"college-contact", "dept", "delete", "--dept-id", "123"},
-			"delete_college_contact_dept",
-			map[string]any{"deptId": int64(123)},
-		},
-		{
-			"employee remove",
-			[]string{"college-contact", "employee", "remove", "--staff-ids", "S1,S2"},
-			"remove_employee",
-			map[string]any{"staffIds": []string{"S1", "S2"}},
-		},
-		{
-			"alumni delete-dept",
-			[]string{"college-contact", "alumni", "delete-dept", "--alumni-dept-id", "1"},
-			"delete_alumni_dept",
-			map[string]any{"alumniDeptId": int64(1)},
-		},
-		{
-			"alumni remove-alumnus",
-			[]string{"college-contact", "alumni", "remove-alumnus", "--staff-id", "S1", "--alumni-dept-id", "1"},
-			"delete_alumnus",
-			map[string]any{"staffId": "S1", "alumniDeptId": int64(1)},
-		},
-		{
-			"alumni cancel-invite",
-			[]string{"college-contact", "alumni", "cancel-invite", "--alumni-dept-id", "1", "--staff-ids", "s1,s2"},
-			"delete_alumni_invite_record",
-			map[string]any{"alumniDeptId": int64(1), "staffIds": []string{"s1", "s2"}},
-		},
-		{
-			"alumni disband-group",
-			[]string{"college-contact", "alumni", "disband-group", "--alumni-dept-id", "1"},
-			"disband_alumni_group",
-			map[string]any{"alumniDeptId": int64(1)},
-		},
-		{
-			"graduate commit-graduate",
-			[]string{"college-contact", "graduate", "commit-graduate", "--graduate-dept-ids", "1,2", "--graduate-year", "2026"},
-			"commit_graduate",
-			map[string]any{"graduateDeptIds": []int64{1, 2}, "graduateYear": int64(2026)},
-		},
-		{
-			"graduate all-graduate",
-			[]string{"college-contact", "graduate", "all-graduate", "--graduate-year", "2026"},
-			"all_graduate",
-			map[string]any{"graduateYear": int64(2026)},
-		},
-		{
-			"graduate batch-graduate",
-			[]string{"college-contact", "graduate", "batch-graduate", "--dept-id", "1", "--staff-ids", "s1,s2"},
-			"batch_graduate",
-			map[string]any{"deptId": int64(1), "staffIds": []string{"s1", "s2"}},
-		},
-		{
-			"graduate delete-and-graduate",
-			[]string{"college-contact", "graduate", "delete-and-graduate", "--dept-id", "1", "--staff-ids", "s1,s2"},
-			"delete_and_graduate",
-			map[string]any{"deptId": int64(1), "staffIds": []string{"s1", "s2"}},
-		},
-		{
-			"graduate batch-delete-pending",
-			[]string{"college-contact", "graduate", "batch-delete-pending", "--dept-id", "1", "--staff-ids", "s1,s2"},
-			"batch_delete_pending",
-			map[string]any{"deptId": int64(1), "staffIds": []string{"s1", "s2"}},
-		},
-		{
-			"graduate batch-update-pending",
-			[]string{"college-contact", "graduate", "batch-update-pending", "--dept-id", "1", "--staff-ids", "s1,s2", "--graduate-year", "2026"},
-			"batch_update_pending",
-			map[string]any{"deptId": int64(1), "staffIds": []string{"s1", "s2"}, "graduateYear": int64(2026)},
-		},
-		{
-			"graduate commit-restore",
-			[]string{"college-contact", "graduate", "commit-restore", "--graduate-dept-ids", "1,2"},
-			"commit_restore",
-			map[string]any{"graduateDeptIds": []int64{1, 2}},
-		},
-		{
-			"group delete-group-rule",
-			[]string{"college-contact", "group", "delete-group-rule", "--rule-id", "1"},
-			"delete_group_rule",
-			map[string]any{"ruleId": int64(1)},
-		},
-		{
-			"group execute-group-rule",
-			[]string{"college-contact", "group", "execute-group-rule"},
-			"execute_group_rule",
-			map[string]any{},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name+"/rejected_without_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newCollegeContactTestRoot()
-			root.SetArgs(tc.args)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("expected confirm-gate error without --yes, got nil")
-			}
-			if !strings.Contains(err.Error(), "需要用户确认") {
-				t.Fatalf("expected confirmation gate error, got: %v", err)
-			}
-			if len(caller.calls) != 0 {
-				t.Fatalf("caller should not be invoked without --yes, got %d calls", len(caller.calls))
-			}
-		})
-
-		t.Run(tc.name+"/dispatched_with_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newCollegeContactTestRoot()
-			argsWithYes := append(append([]string{}, tc.args...), "--yes")
-			root.SetArgs(argsWithYes)
-			err := root.Execute()
-			if err != nil {
-				t.Fatalf("Execute() with --yes error = %v", err)
-			}
-			if len(caller.calls) != 1 {
-				t.Fatalf("expected exactly 1 MCP call with --yes, got %d", len(caller.calls))
-			}
-			if caller.calls[0].productID != "college-contact" {
-				t.Errorf("productID = %q, want %q", caller.calls[0].productID, "college-contact")
-			}
-			if caller.calls[0].tool != tc.wantTool {
-				t.Errorf("tool = %q, want %q", caller.calls[0].tool, tc.wantTool)
-			}
-			gotArgs := caller.calls[0].args
-			if len(gotArgs) != 1 {
-				t.Fatalf("args should carry exactly the \"input\" key, got %v", gotArgs)
-			}
-			gotInput, ok := gotArgs["input"].(map[string]any)
-			if !ok {
-				t.Fatalf("args[\"input\"] should be map[string]any, got %T", gotArgs["input"])
-			}
-			if !reflect.DeepEqual(gotInput, tc.wantInput) {
-				t.Errorf("input = %#v, want %#v", gotInput, tc.wantInput)
-			}
-		})
-	}
-}
-
-// withCollegeContactDispatchCaller installs a non-dry-run capture caller so
-// commands go through the full dispatch path (deps.Caller.CallTool) and we can
-// verify the productID, tool name, and args passed to callMCPToolOnServer.
-func withCollegeContactDispatchCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-// TestCollegeContactDispatch verifies that representative commands from each
-// group dispatch to the correct MCP tool with the expected productID and args.
-func TestCrossPlatformCoverageCollegeContactDispatch(t *testing.T) {
-	type dispatchCase struct {
-		name      string
-		args      []string
-		wantTool  string
-		wantProd  string
-		checkArgs func(t *testing.T, args map[string]any)
-	}
-
-	cases := []dispatchCase{
-		{
-			name:     "dept get-standard-structure",
-			args:     []string{"college-contact", "dept", "get-standard-structure"},
-			wantTool: "get_college_standard_structure",
-			wantProd: "college-contact",
-		},
-		{
-			name:     "dept get-detail",
-			args:     []string{"college-contact", "dept", "get-detail", "--dept-id", "123"},
-			wantTool: "get_college_dept_detail",
-			wantProd: "college-contact",
-			checkArgs: func(t *testing.T, args map[string]any) {
-				input := args["input"].(map[string]any)
-				if input["deptId"] != int64(123) {
-					t.Errorf("deptId = %v (%T), want int64(123)", input["deptId"], input["deptId"])
-				}
-			},
-		},
-		{
-			name:     "dept create",
-			args:     []string{"college-contact", "dept", "create", "--super-id", "100", "--stru-dept-id", "200", "--name", "X", "--dept-type", "college", "--create-dept-group", "true"},
-			wantTool: "create_college_contact_dept",
-			wantProd: "college-contact",
-		},
-		{
-			name:     "employee get-detail",
-			args:     []string{"college-contact", "employee", "get-detail", "--staff-id", "S1"},
-			wantTool: "get_employee_detail",
-			wantProd: "college-contact",
-			checkArgs: func(t *testing.T, args map[string]any) {
-				input := args["input"].(map[string]any)
-				if input["staffId"] != "S1" {
-					t.Errorf("staffId = %v, want S1", input["staffId"])
-				}
-			},
-		},
-		{
-			name:     "alumni get-dept-tree",
-			args:     []string{"college-contact", "alumni", "get-dept-tree", "--alumni-dept-id", "123"},
-			wantTool: "get_alumni_dept_tree",
-			wantProd: "college-contact",
-			checkArgs: func(t *testing.T, args map[string]any) {
-				input := args["input"].(map[string]any)
-				if input["alumniDeptId"] != int64(123) {
-					t.Errorf("alumniDeptId = %v (%T), want int64(123)", input["alumniDeptId"], input["alumniDeptId"])
-				}
-			},
-		},
-		{
-			name:     "graduate query-graduate-years",
-			args:     []string{"college-contact", "graduate", "query-graduate-years"},
-			wantTool: "query_graduate_years",
-			wantProd: "college-contact",
-		},
-		{
-			name:     "group query-group-rule",
-			args:     []string{"college-contact", "group", "query-group-rule"},
-			wantTool: "query_group_rule",
-			wantProd: "college-contact",
-		},
-		{
-			name:     "dept delete with --yes",
-			args:     []string{"college-contact", "dept", "delete", "--dept-id", "123", "--yes"},
-			wantTool: "delete_college_contact_dept",
-			wantProd: "college-contact",
-			checkArgs: func(t *testing.T, args map[string]any) {
-				input := args["input"].(map[string]any)
-				if input["deptId"] != int64(123) {
-					t.Errorf("deptId = %v (%T), want int64(123)", input["deptId"], input["deptId"])
-				}
-			},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			caller := withCollegeContactDispatchCaller(t)
-
-			root := &cobra.Command{Use: "dws"}
-			root.PersistentFlags().BoolP("yes", "y", false, "跳过确认提示")
-			root.AddCommand(newCollegeContactCommand())
-			root.SetArgs(tc.args)
-
-			if err := root.Execute(); err != nil {
-				t.Fatalf("Execute() error = %v", err)
-			}
-			if caller.productID != tc.wantProd {
-				t.Errorf("productID = %q, want %q", caller.productID, tc.wantProd)
-			}
-			if caller.tool != tc.wantTool {
-				t.Errorf("tool = %q, want %q", caller.tool, tc.wantTool)
-			}
-			if tc.checkArgs != nil {
-				tc.checkArgs(t, caller.args)
-			}
-		})
-	}
-}

internal/helpers/conference.go

@@ -39,8 +39,9 @@ func newConferenceCommand() *cobra.Command {
 直接发起会议、邀请入会、会中控制请在钉钉客户端操作；如需预约日程，请改用 dws calendar event create。`,
 		RunE: runUnavailable,
 	}
+	newHybridGroupCommand(root)
 
-	meetingCmd := &cobra.Command{Use: "meeting", Short: "会议管理（已下线）", RunE: groupRunE}
+	meetingCmd := newGroupCommand(&cobra.Command{Use: "meeting", Short: "会议管理（已下线）", RunE: groupRunE})
 
 	meetingCreateCmd := &cobra.Command{
 		Use:     "reserve",
@@ -59,7 +60,7 @@ func newConferenceCommand() *cobra.Command {
 	root.AddCommand(meetingCmd)
 
 	// member 子命令组 — 成员管理
-	memberCmd := &cobra.Command{Use: "member", Short: "成员管理（已下线）", RunE: groupRunE}
+	memberCmd := newGroupCommand(&cobra.Command{Use: "member", Short: "成员管理（已下线）", RunE: groupRunE})
 
 	memberInviteCmd := &cobra.Command{
 		Use:   "invite",

internal/helpers/contact.go

@@ -422,7 +422,7 @@ func newContactCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "contact",
 		Short: "通讯录 / 用户 / 部门 / 角色 / 人员关系",
 		Long: `查询钉钉通讯录：用户搜索、手机号查找、部门搜索、子部门 / 成员列表、人员关系；用户花名册档案信息（学历、家庭、银行卡、合同等）与离职员工信息。
@@ -441,9 +441,9 @@ func newContactCommand() *cobra.Command {
   - contact user profile fields/get: 员工花名册档案查询（学历、家庭、银行卡等）
   - contact user dismission search: 离职员工列表查询`,
 		RunE: groupRunE,
-	}
+	})
 
-	userCmd := &cobra.Command{
+	userCmd := newGroupCommand(&cobra.Command{
 		Use:   "user",
 		Short: "人员管理",
 		Long: `人员管理：通讯录用户查询、修改员工信息、邀请员工加入企业、用户档案（花名册）查询、离职员工查询。
@@ -457,7 +457,7 @@ func newContactCommand() *cobra.Command {
   - 查询用户的学历、家庭、银行卡、合同等档案 → contact user profile get
   - 查询离职员工列表                         → contact user dismission search`,
 		RunE: groupRunE,
-	}
+	})
 
 	contactUserGetSelfCmd := &cobra.Command{
 		Use:     "get-self",
@@ -499,10 +499,10 @@ func newContactCommand() *cobra.Command {
 		},
 	})
 
-	relationCmd := &cobra.Command{Use: "relation",
+	relationCmd := newGroupCommand(&cobra.Command{Use: "relation",
 		Short: "人员关系查询",
 		Long:  `查询钉钉人员关系：特别关注人。`,
-		RunE:  groupRunE}
+		RunE:  groupRunE})
 
 	contactRelationListMyFollowingsCmd := &cobra.Command{
 		Use:     "list-my-followings",
@@ -704,7 +704,7 @@ func newContactCommand() *cobra.Command {
 
 	// ── label 角色 ──────────────────────────────────────────────────
 
-	contactLabelCmd := &cobra.Command{
+	contactLabelCmd := newGroupCommand(&cobra.Command{
 		Use:     "label",
 		Aliases: []string{"role"},
 		Short:   "角色查询",
@@ -720,7 +720,7 @@ func newContactCommand() *cobra.Command {
   2. 从返回结果中匹配目标角色名称及 labelId
   3. contact label list-members --id <labelId>  → 获取该角色下的成员`,
 		RunE: groupRunE,
-	}
+	})
 
 	runContactLabelList := func(cmd *cobra.Command, args []string) error {
 		if len(args) > 0 {
@@ -796,7 +796,7 @@ func newContactCommand() *cobra.Command {
 
 	contactLabelCmd.AddCommand(contactLabelListAllCmd, contactLabelGetCmd, contactLabelListMembersCmd)
 
-	contactDeptCmd := &cobra.Command{Use: "dept", Short: "部门查询", RunE: groupRunE}
+	contactDeptCmd := newGroupCommand(&cobra.Command{Use: "dept", Short: "部门查询", RunE: groupRunE})
 
 	contactDeptSearchCmd := &cobra.Command{
 		Use:     "search",
@@ -988,7 +988,7 @@ func newContactCommand() *cobra.Command {
 	})
 
 	// ── user profile 用户档案（花名册） ────────────────────────────────────
-	contactUserProfileCmd := &cobra.Command{
+	contactUserProfileCmd := newGroupCommand(&cobra.Command{
 		Use:   "profile",
 		Short: "用户档案（花名册）",
 		Long: `用户档案（花名册）：查询花名册字段列表、查询员工花名册字段信息。
@@ -1000,7 +1000,7 @@ func newContactCommand() *cobra.Command {
   - contact user get: 组织管理信息（部门、主管、管理员权限）
   - contact user profile get: 个人档案信息（学历、家庭、银行卡等）`,
 		RunE: groupRunE,
-	}
+	})
 
 	contactUserProfileFieldsCmd := &cobra.Command{
 		Use:   "fields",
@@ -1124,12 +1124,12 @@ contact user profile fields 获取可用字段列表。
 	contactUserProfileCmd.AddCommand(contactUserProfileFieldsCmd, contactUserProfileGetCmd)
 
 	// ── user dismission 离职员工 ───────────────────────────────────────────
-	contactUserDismissionCmd := &cobra.Command{
+	contactUserDismissionCmd := newGroupCommand(&cobra.Command{
 		Use:   "dismission",
 		Short: "离职员工查询",
 		Long:  `离职员工查询：分页获取离职员工列表，支持按员工姓名、离职时间范围、部门进行过滤。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	contactUserDismissionSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -1568,7 +1568,7 @@ contact user profile fields 获取可用字段列表。
 
 	// ── org 企业管理 ──────────────────────────────────────────────────
 
-	contactOrgCmd := &cobra.Command{
+	contactOrgCmd := newGroupCommand(&cobra.Command{
 		Use:   "org",
 		Short: "企业管理",
 		Long: `企业管理：创建企业。
@@ -1578,7 +1578,7 @@ contact user profile fields 获取可用字段列表。
   - 创建企业专属账号                   → contact account create
   - 邀请员工加入企业                   → contact user invite`,
 		RunE: groupRunE,
-	}
+	})
 
 	contactOrgCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -1639,12 +1639,12 @@ contact user profile fields 获取可用字段列表。
 
 	// ── account 企业账号管理 ──────────────────────────────────────────
 
-	contactAccountCmd := &cobra.Command{
+	contactAccountCmd := newGroupCommand(&cobra.Command{
 		Use:   "account",
 		Short: "企业账号管理",
 		Long:  "企业账号管理：创建或更新企业专属账号。",
 		RunE:  groupRunE,
-	}
+	})
 
 	contactAccountCreateCmd := &cobra.Command{
 		Use:   "create",

internal/helpers/contact_coverage_more_test.go

@@ -1,9 +1,11 @@
 package helpers
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
 )
 
@@ -37,8 +39,11 @@ func TestCrossPlatformCoverageContactRemainingCompatibilityBranches(t *testing.T
 	if err := hint.RunE(hint, []string{"--help"}); err != nil {
 		t.Fatalf("hint help: %v", err)
 	}
-	if err := hint.RunE(hint, []string{"unexpected"}); err == nil || !strings.Contains(err.Error(), "use: dws contact dept") {
-		t.Fatalf("hint guidance err=%v", err)
+	err := hint.RunE(hint, []string{"unexpected"})
+	var structured *apperrors.Error
+	if !errors.As(err, &structured) || structured.Category != apperrors.CategoryValidation ||
+		structured.Reason != "unknown_subcommand" || !strings.Contains(structured.Hint, "use: dws contact dept") {
+		t.Fatalf("hint guidance err=%#v", structured)
 	}
 
 	if err := executeFilterCoverage(t, newContactCommand(), "user", "get", "--unknown"); err == nil || !strings.Contains(err.Error(), "See '") {

internal/helpers/content_splitter.go

@@ -1,257 +0,0 @@
-package helpers
-
-import (
-	"strings"
-	"unicode/utf8"
-)
-
-// splitMarkdownSafe splits content into chunks of at most `limit` runes each,
-// respecting markdown structure boundaries.
-//
-// Split priority (high to low):
-//  1. H1 headings (# )
-//  2. H2 headings (## )
-//  3. H3 headings (### )
-//  4. Blank lines (paragraph boundaries)
-//  5. Hard split (preserving table/code block integrity)
-//
-// Invariant: strings.Join(result, "") == content (no content loss)
-func splitMarkdownSafe(content string, limit int) []string {
-	if utf8.RuneCountInString(content) <= limit {
-		return []string{content}
-	}
-
-	blocks := parseMarkdownBlocks(content)
-	return mergeBlocksIntoChunks(blocks, limit)
-}
-
-// markdownBlock represents an atomic block that should not be split.
-type markdownBlock struct {
-	text      string
-	blockType int
-}
-
-const (
-	blockNormal    = 0
-	blockH1        = 1
-	blockH2        = 2
-	blockH3        = 3
-	blockTable     = 4
-	blockCodeBlock = 5
-)
-
-// parseMarkdownBlocks splits content into atomic blocks that should be kept together.
-// The invariant is: strings.Join(all block texts, "") == original content.
-// Each block's text includes trailing newlines up to (but not including) the next block's start.
-func parseMarkdownBlocks(content string) []markdownBlock {
-	content = strings.ReplaceAll(content, "\r\n", "\n")
-	lines := strings.Split(content, "\n")
-
-	var blocks []markdownBlock
-	var currentLines []string
-	currentType := blockNormal
-	inCodeBlock := false
-
-	flushCurrent := func(includeTrailingNewline bool) {
-		if len(currentLines) > 0 {
-			text := strings.Join(currentLines, "\n")
-			if includeTrailingNewline {
-				text += "\n"
-			}
-			blocks = append(blocks, markdownBlock{text: text, blockType: currentType})
-			currentLines = nil
-			currentType = blockNormal
-		}
-	}
-
-	for i, line := range lines {
-		trimmed := strings.TrimSpace(line)
-		isLastLine := i == len(lines)-1
-
-		// Code block fence detection
-		if strings.HasPrefix(trimmed, "```") {
-			if !inCodeBlock {
-				flushCurrent(!isLastLine)
-				currentType = blockCodeBlock
-				inCodeBlock = true
-				currentLines = append(currentLines, line)
-				continue
-			}
-			// End of code block
-			currentLines = append(currentLines, line)
-			flushCurrent(!isLastLine)
-			inCodeBlock = false
-			continue
-		}
-
-		if inCodeBlock {
-			currentLines = append(currentLines, line)
-			continue
-		}
-
-		// Table line detection
-		if strings.HasPrefix(trimmed, "|") {
-			if currentType != blockTable {
-				flushCurrent(!isLastLine)
-				currentType = blockTable
-			}
-			currentLines = append(currentLines, line)
-			continue
-		}
-
-		// If we were in a table and hit a non-table line, flush
-		if currentType == blockTable {
-			flushCurrent(!isLastLine)
-		}
-
-		// Heading detection — only at line start (not inside other blocks)
-		// Order matters: check H3 before H2 before H1 to avoid ambiguity
-		if strings.HasPrefix(line, "### ") {
-			flushCurrent(!isLastLine)
-			currentType = blockH3
-			currentLines = append(currentLines, line)
-			flushCurrent(!isLastLine)
-			continue
-		} else if strings.HasPrefix(line, "## ") {
-			flushCurrent(!isLastLine)
-			currentType = blockH2
-			currentLines = append(currentLines, line)
-			flushCurrent(!isLastLine)
-			continue
-		}
-		if strings.HasPrefix(line, "# ") && !strings.HasPrefix(line, "## ") {
-			flushCurrent(!isLastLine)
-			currentType = blockH1
-			currentLines = append(currentLines, line)
-			flushCurrent(!isLastLine)
-			continue
-		}
-
-		currentLines = append(currentLines, line)
-	}
-	// Last block: no trailing newline
-	flushCurrent(false)
-
-	return blocks
-}
-
-// mergeBlocksIntoChunks greedily fills chunks up to the limit, then splits
-// backwards at the nearest heading boundary. This ensures chunks are as large
-// as possible while still breaking at meaningful markdown structure points.
-//
-// Strategy: fill forward until adding the next block would exceed the limit,
-// then look backwards for the last heading in the current chunk to split there.
-// If no heading is found, split at the overflow point (greedy).
-func mergeBlocksIntoChunks(blocks []markdownBlock, limit int) []string {
-	var chunks []string
-
-	i := 0
-	for i < len(blocks) {
-		// Accumulate blocks greedily until we'd exceed the limit
-		var chunkBlocks []markdownBlock
-		chunkRunes := 0
-
-		for i < len(blocks) {
-			blockRunes := utf8.RuneCountInString(blocks[i].text)
-
-			// Single oversized block: hard-split it
-			if blockRunes > limit && chunkRunes == 0 {
-				subChunks := hardSplitBlock(blocks[i].text, limit)
-				chunks = append(chunks, subChunks...)
-				i++
-				chunkBlocks = nil
-				chunkRunes = 0
-				continue
-			}
-
-			// Would exceed limit: stop accumulating
-			if chunkRunes+blockRunes > limit && chunkRunes > 0 {
-				break
-			}
-
-			chunkBlocks = append(chunkBlocks, blocks[i])
-			chunkRunes += blockRunes
-			i++
-		}
-
-		if len(chunkBlocks) == 0 {
-			continue
-		}
-
-		// If we stopped because of overflow AND there are multiple blocks,
-		// look backwards for the last heading to use as a split point
-		if i < len(blocks) && len(chunkBlocks) > 1 {
-			splitIdx := -1
-			for j := len(chunkBlocks) - 1; j > 0; j-- {
-				bt := chunkBlocks[j].blockType
-				if bt == blockH1 || bt == blockH2 || bt == blockH3 {
-					splitIdx = j
-					break
-				}
-			}
-			if splitIdx > 0 {
-				// Split: emit blocks before the heading, push heading+ back
-				var emitBuilder strings.Builder
-				for _, b := range chunkBlocks[:splitIdx] {
-					emitBuilder.WriteString(b.text)
-				}
-				chunks = append(chunks, emitBuilder.String())
-				// Rewind: put the heading and subsequent blocks back for next iteration
-				i -= len(chunkBlocks) - splitIdx
-				continue
-			}
-		}
-
-		// No heading split point found (or single block): emit all accumulated blocks
-		var emitBuilder strings.Builder
-		for _, b := range chunkBlocks {
-			emitBuilder.WriteString(b.text)
-		}
-		chunks = append(chunks, emitBuilder.String())
-	}
-
-	return chunks
-}
-
-// hardSplitBlock splits a single oversized block at paragraph boundaries,
-// falling back to rune-level splitting.
-func hardSplitBlock(text string, limit int) []string {
-	// SplitAfter keeps the paragraph separator attached to the preceding
-	// paragraph. The previous Split implementation rebuilt separators while
-	// merging, but dropped them whenever a chunk boundary fell between two
-	// paragraphs, violating the no-content-loss invariant.
-	paragraphs := strings.SplitAfter(text, "\n\n")
-	var chunks []string
-	var current strings.Builder
-	currentRunes := 0
-
-	for _, para := range paragraphs {
-		paraRunes := utf8.RuneCountInString(para)
-
-		if currentRunes+paraRunes > limit && currentRunes > 0 {
-			chunks = append(chunks, current.String())
-			current.Reset()
-			currentRunes = 0
-		}
-
-		// If single paragraph exceeds limit, split by runes
-		if paraRunes > limit {
-			runes := []rune(para)
-			for start := 0; start < len(runes); start += limit {
-				end := start + limit
-				if end > len(runes) {
-					end = len(runes)
-				}
-				chunks = append(chunks, string(runes[start:end]))
-			}
-			continue
-		}
-
-		current.WriteString(para)
-		currentRunes += paraRunes
-	}
-	if currentRunes > 0 {
-		chunks = append(chunks, current.String())
-	}
-	return chunks
-}

internal/helpers/content_splitter_test.go

@@ -1,125 +0,0 @@
-package helpers
-
-import (
-	"context"
-	"strings"
-	"testing"
-	"unicode/utf8"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
-)
-
-func TestCrossPlatformCoverageSplitMarkdownSafePreservesContentAndLimitsChunks(t *testing.T) {
-	short := "short 文本"
-	if got := splitMarkdownSafe(short, 100); len(got) != 1 || got[0] != short {
-		t.Fatalf("short split = %#v", got)
-	}
-
-	content := "# Heading\r\nparagraph one\r\n\r\n## Two\r\n| a | b |\r\n|---|---|\r\n| 1 | 2 |\r\nnormal\r\n### Three\r\n```go\r\nfmt.Println(\"hello\")\r\n```\r\ntail"
-	normalized := strings.ReplaceAll(content, "\r\n", "\n")
-	chunks := splitMarkdownSafe(content, 35)
-	if strings.Join(chunks, "") != normalized {
-		t.Fatalf("split content was not preserved:\nwant %q\n got %q", normalized, strings.Join(chunks, ""))
-	}
-	for _, chunk := range chunks {
-		if utf8.RuneCountInString(chunk) > 35 {
-			t.Errorf("chunk exceeds limit: %d %q", utf8.RuneCountInString(chunk), chunk)
-		}
-	}
-
-	blocks := parseMarkdownBlocks("before\n```\nunclosed")
-	if len(blocks) < 2 || blocks[len(blocks)-1].blockType != blockCodeBlock {
-		t.Fatalf("unclosed code blocks = %#v", blocks)
-	}
-}
-
-func TestCrossPlatformCoverageMergeBlocksUsesHeadingsAndHardSplits(t *testing.T) {
-	blocks := []markdownBlock{
-		{text: "aaaa", blockType: blockNormal},
-		{text: "# h\n", blockType: blockH1},
-		{text: "bbbb", blockType: blockNormal},
-		{text: "cccc", blockType: blockNormal},
-	}
-	chunks := mergeBlocksIntoChunks(blocks, 9)
-	if strings.Join(chunks, "") != "aaaa# h\nbbbbcccc" || len(chunks) < 2 {
-		t.Fatalf("heading merge = %#v", chunks)
-	}
-
-	chunks = mergeBlocksIntoChunks([]markdownBlock{{text: "aaaa"}, {text: "bbbb"}, {text: "cccc"}}, 8)
-	if strings.Join(chunks, "") != "aaaabbbbcccc" {
-		t.Fatalf("greedy merge = %#v", chunks)
-	}
-
-	oversized := "one\n\ntwo\n\n" + strings.Repeat("界", 11)
-	chunks = mergeBlocksIntoChunks([]markdownBlock{{text: oversized}}, 5)
-	if strings.Join(chunks, "") != oversized {
-		t.Fatalf("oversized merge = %#v", chunks)
-	}
-	for _, chunk := range chunks {
-		if utf8.RuneCountInString(chunk) > 5 {
-			t.Errorf("hard-split chunk exceeds limit: %q", chunk)
-		}
-	}
-
-	if got := mergeBlocksIntoChunks(nil, 5); len(got) != 0 {
-		t.Fatalf("empty merge = %#v", got)
-	}
-}
-
-func TestCrossPlatformCoverageHardSplitBlockCoversParagraphAndRuneBoundaries(t *testing.T) {
-	for _, text := range []string{
-		"aa\n\nbb\n\ncc",
-		"aa\n\n" + strings.Repeat("x", 12),
-		strings.Repeat("界", 13),
-		"",
-	} {
-		chunks := hardSplitBlock(text, 5)
-		if strings.Join(chunks, "") != text {
-			t.Errorf("hardSplitBlock(%q) = %#v", text, chunks)
-		}
-		for _, chunk := range chunks {
-			if utf8.RuneCountInString(chunk) > 5 {
-				t.Errorf("chunk exceeds limit: %q", chunk)
-			}
-		}
-	}
-}
-
-func TestCrossPlatformCoverageRuntimeDefaultsRegistryValidationAndSnapshot(t *testing.T) {
-	runtimeDefaultsMu.Lock()
-	previous := runtimeDefaults
-	runtimeDefaults = make(map[string]edition.RuntimeDefaultFn)
-	runtimeDefaultsMu.Unlock()
-	t.Cleanup(func() {
-		runtimeDefaultsMu.Lock()
-		runtimeDefaults = previous
-		runtimeDefaultsMu.Unlock()
-	})
-
-	resolver := func(context.Context) (string, bool) { return "value", true }
-	RegisterRuntimeDefault("$value", resolver)
-	snapshot := RuntimeDefaultsSnapshot()
-	if len(snapshot) != 1 || snapshot["$value"] == nil {
-		t.Fatalf("RuntimeDefaultsSnapshot() = %#v", snapshot)
-	}
-	delete(snapshot, "$value")
-	if len(RuntimeDefaultsSnapshot()) != 1 {
-		t.Fatal("snapshot mutated the runtime registry")
-	}
-
-	for _, tc := range []struct {
-		name string
-		fn   edition.RuntimeDefaultFn
-	}{
-		{"", resolver}, {"$nil", nil}, {"$value", resolver},
-	} {
-		func() {
-			defer func() {
-				if recover() == nil {
-					t.Errorf("RegisterRuntimeDefault(%q) did not panic", tc.name)
-				}
-			}()
-			RegisterRuntimeDefault(tc.name, tc.fn)
-		}()
-	}
-}

internal/helpers/coverage_pure_more_test.go

@@ -5,11 +5,11 @@ import (
 	"encoding/json"
 	"fmt"
 	"io"
-	"os"
 	"testing"
 	"time"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -30,30 +30,6 @@ func TestCrossPlatformCoveragePureScalarAndCommandHelpersCoverage(t *testing.T)
 		_ = isNumericUserID(value)
 	}
 
-	root := &cobra.Command{Use: "calendar"}
-	known := &cobra.Command{Use: "event", Aliases: []string{"e"}}
-	hidden := &cobra.Command{Use: "hidden", Hidden: true}
-	root.AddCommand(known, hidden)
-	for _, args := range [][]string{{"--x"}, {"event"}, {"e"}, {"missing"}} {
-		_ = findUnknownVerb(root, args)
-	}
-	printUnknownSubcmdError(root, "evnt")
-	for _, depth := range []int{0, 1, 3} {
-		_ = stripCommandPrefix([]string{"calendar", "event", "--x"}, depth)
-	}
-	oldArgs := os.Args
-	t.Cleanup(func() { os.Args = oldArgs })
-	root.Flags().StringP("known", "k", "", "")
-	for _, args := range [][]string{
-		{"dws", "calendar", "--known=x"},
-		{"dws", "calendar", "--unknown"},
-		{"dws", "calendar", "-z"},
-		{"dws", "calendar", "--", "--ignored"},
-	} {
-		os.Args = args
-		_ = findUnknownFlag(root)
-	}
-
 	for _, event := range []any{
 		nil,
 		map[string]any{"start": map[string]any{"dateTime": "2026-01-02T03:04:05Z"}},
@@ -284,7 +260,7 @@ func TestCrossPlatformCoverageSmallHandlerAndFormatterCoverage(t *testing.T) {
 	group := &cobra.Command{Use: "range"}
 	group.AddCommand(&cobra.Command{Use: "read"})
 	parent.AddCommand(group)
-	_ = deepSuggestSubcommand(parent, "read")
-	_ = deepSuggestSubcommand(parent, "missing")
+	_ = cmdutil.SuggestDescendantSubcommands(parent, "read")
+	_ = cmdutil.SuggestDescendantSubcommands(parent, "missing")
 	_ = time.Now()
 }

internal/helpers/dev.go

@@ -16,7 +16,6 @@ package helpers
 import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -71,7 +70,7 @@ func (devHandler) Command(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(root)
+	newGroupCommand(root)
 
 	doc := &cobra.Command{
 		Use:               "doc",
@@ -83,7 +82,7 @@ func (devHandler) Command(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(doc)
+	newGroupCommand(doc)
 	doc.AddCommand(newDevDocSearchCommand(runner))
 
 	root.AddCommand(

internal/helpers/devapp.go

@@ -23,7 +23,6 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/spf13/cobra"
 )
 
@@ -140,7 +139,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(root)
+	newGroupCommand(root)
 
 	webapp := &cobra.Command{
 		Use:               "webapp",
@@ -152,7 +151,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(webapp)
+	newGroupCommand(webapp)
 	webapp.AddCommand(
 		newDevAppWebappGetCommand(runner),
 		newDevAppWebappConfigCommand(runner),
@@ -168,7 +167,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(permission)
+	newGroupCommand(permission)
 	permission.AddCommand(
 		newDevAppPermissionListCommand(runner),
 		newDevAppPermissionAddCommand(runner),
@@ -185,7 +184,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(credentials)
+	newGroupCommand(credentials)
 	credentials.AddCommand(newDevAppCredentialsGetCommand(runner))
 
 	member := &cobra.Command{
@@ -198,7 +197,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(member)
+	newGroupCommand(member)
 	member.AddCommand(
 		newDevAppMemberListCommand(runner),
 		newDevAppMemberAddCommand(runner),
@@ -215,7 +214,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(security)
+	newGroupCommand(security)
 	security.AddCommand(newDevAppSecurityConfigCommand(runner))
 
 	robot := &cobra.Command{
@@ -228,7 +227,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(robot)
+	newGroupCommand(robot)
 	robot.AddCommand(
 		newDevAppRobotSubmitCommand(runner),
 		newDevAppRobotResultCommand(runner),
@@ -248,7 +247,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(version)
+	newGroupCommand(version)
 	version.AddCommand(
 		newDevAppVersionCreateCommand(runner),
 		newDevAppVersionListCommand(runner),
@@ -268,7 +267,7 @@ func newDevAppCommand(runner executor.Runner) *cobra.Command {
 			return cmd.Help()
 		},
 	}
-	cmdutil.MarkGroup(event)
+	newGroupCommand(event)
 	event.AddCommand(
 		newDevAppEventListCommand(runner),
 		newDevAppEventSubscribeCommand(runner),

internal/helpers/devapp_connect.go

@@ -587,6 +587,7 @@ func newDevAppRobotConnectCommand(runner executor.Runner) *cobra.Command {
 		newDevAppRobotConnectRestartCommand(),
 		newDevAppRobotConnectListCommand(runner),
 	)
+	newHybridGroupCommand(cmd)
 	cmd.Flags().String("channel", "auto", "渠道：auto(默认,自动探测)|openclaw|qoder|qoderwork|hermes|workbuddy|claudecode|codebuddy|codex|gemini|opencode|custom(自研/未支持的 AI，配 --agent-cmd)")
 	cmd.Flags().String("agent-cmd", "", "自研/未支持的 AI 工具命令（无头/一次性：问题作为最后一个参数追加，答案打到 stdout）；用来接入内置渠道之外的 AI（如网易有道龙虾 LobsterAI）；等价于 --channel custom + 设 DWS_AGENT_CMD；env: DWS_AGENT_CMD")
 	// 用 robot-client-* 而非 client-id/client-secret：后者是全局 OAuth 客户端覆盖

internal/helpers/devdoc.go

@@ -24,14 +24,14 @@ func newDevdocCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "devdoc",
 		Short: "开放平台文档搜索",
 		Long:  `搜索钉钉开放平台开发文档。默认以表格格式输出（标题、URL），使用 -f json 获取原始 JSON。`,
 		RunE:  groupRunE,
-	}
+	})
 
-	articleCmd := &cobra.Command{Use: "article", Short: "文档文章", RunE: groupRunE}
+	articleCmd := newGroupCommand(&cobra.Command{Use: "article", Short: "文档文章", RunE: groupRunE})
 	articleCmd.AddCommand(newDevdocArticleSearchCommand())
 	root.AddCommand(articleCmd)
 	root.AddCommand(hintSubCmd("search", "use: dws devdoc article search --query <关键词>"))

internal/helpers/ding.go

@@ -42,14 +42,14 @@ func newDingCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "ding",
 		Short: "DING 消息 / 发送 / 撤回",
 		Long:  `发送和撤回 DING 消息（应用内/短信/电话）。预发环境可用。`,
 		RunE:  groupRunE,
-	}
+	})
 
-	dingMessageCmd := &cobra.Command{Use: "message", Short: "DING 消息管理", RunE: groupRunE}
+	dingMessageCmd := newGroupCommand(&cobra.Command{Use: "message", Short: "DING 消息管理", RunE: groupRunE})
 
 	dingMessageSendCmd := &cobra.Command{
 		Use:   "send",

internal/helpers/doc.go

@@ -1166,7 +1166,7 @@ func newDocCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "doc",
 		Short: "钉钉文档管理",
 		Long: `管理钉钉文档：浏览、读写、块级编辑、导出、导入、模板管理。
@@ -1190,7 +1190,7 @@ func newDocCommand() *cobra.Command {
 
 文件管理（搜索/列表/上传/下载/复制/移动/重命名/删除/权限）已迁移到 dws drive。`,
 		RunE: groupRunE,
-	}
+	})
 
 	searchCmd := &cobra.Command{
 		Use:   "search",
@@ -1826,7 +1826,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		},
 	})
 
-	fileCmd := &cobra.Command{Use: "file", Short: "文件管理", RunE: groupRunE}
+	fileCmd := newGroupCommand(&cobra.Command{Use: "file", Short: "文件管理", RunE: groupRunE})
 
 	fileCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -1904,7 +1904,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		},
 	})
 
-	folderCmd := &cobra.Command{Use: "folder", Short: "文件夹管理", RunE: groupRunE}
+	folderCmd := newGroupCommand(&cobra.Command{Use: "folder", Short: "文件夹管理", RunE: groupRunE})
 
 	folderCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -2063,12 +2063,12 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		},
 	})
 
-	blockCmd := &cobra.Command{
+	blockCmd := newGroupCommand(&cobra.Command{
 		Use:   "block",
 		Short: "块级编辑",
 		Long:  `对文档进行块级别的精细编辑：查询、插入、更新、删除块元素。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	blockListCmd := &cobra.Command{
 		Use:   "list",
@@ -2844,12 +2844,12 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 	_ = renameCmd.Flags().MarkHidden("title")
 
 	// ── media (文档媒体/附件) ────────────────────────────────
-	mediaCmd := &cobra.Command{
+	mediaCmd := newGroupCommand(&cobra.Command{
 		Use:   "media",
 		Short: "文档媒体 / 附件管理",
 		Long:  `管理钉钉文档中的媒体资源和附件：上传附件并插入文档、下载文档内的附件等。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	mediaDownloadCmd := &cobra.Command{
 		Use:   "download",
@@ -3036,12 +3036,12 @@ resourceId 需通过 dws doc block list 获取：查询目标文档的块列表
 	mediaCmd.AddCommand(mediaDownloadCmd, mediaUploadCmd, mediaInsertCmd)
 
 	// ── comment (文档评论) ──────────────────────────────────
-	commentCmd := &cobra.Command{
+	commentCmd := newGroupCommand(&cobra.Command{
 		Use:   "comment",
 		Short: "文档评论 / 评论管理",
 		Long:  `管理钉钉文档的评论：查询评论列表、创建评论、回复评论。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	commentListCmd := &cobra.Command{
 		Use:   "list",
@@ -3545,13 +3545,13 @@ commentKey可从 dws doc comment create 或 dws doc comment list 返回结果中
 	commentCmd.AddCommand(newCommentBaseCommands("doc")...)
 
 	// ── permission (文档协作权限) ────────────────────────────
-	permissionCmd := &cobra.Command{
+	permissionCmd := newGroupCommand(&cobra.Command{
 		Use:     "permission",
 		Aliases: []string{"perm"},
 		Short:   "文档协作权限管理",
 		Long:    `管理钉钉文档的协作者权限：添加协作者、更新协作者权限、查询协作者列表。`,
 		RunE:    groupRunE,
-	}
+	})
 
 	permissionAddCmd := &cobra.Command{
 		Use:   "add",
@@ -4260,6 +4260,7 @@ CLI 内部自动完成全部流程：
 	_ = exportCmd.Flags().MarkHidden("file-id")
 
 	exportCmd.AddCommand(exportGetCmd)
+	newHybridGroupCommand(exportCmd)
 
 	// ── import: 文件导入为在线文档（一体化：上传→转换→轮询）──────────────
 	importCmd := &cobra.Command{
@@ -4356,14 +4357,15 @@ CLI 内部自动完成全部流程:
 	})
 	importGetCmd.Flags().String("task-id", "", "导入任务 ID (必填)")
 	importCmd.AddCommand(importGetCmd)
+	newHybridGroupCommand(importCmd)
 
 	// ── doc version 子命令组 ──
-	versionCmd := &cobra.Command{
+	versionCmd := newGroupCommand(&cobra.Command{
 		Use:   "version",
 		Short: "文档历史版本管理",
 		Long:  `管理钉钉在线文档（adoc）的历史版本：手动保存、查看版本列表、回滚到指定版本。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	versionSaveCmd := &cobra.Command{
 		Use:     "save",
@@ -4549,7 +4551,7 @@ CLI 内部自动完成全部流程:
 	versionCmd.AddCommand(versionSaveCmd, versionListCmd, versionRevertCmd)
 
 	// ── template 子命令组 ──────────────────────────────────────────────────────
-	templateCmd := &cobra.Command{Use: "template", Short: "文档模板管理", RunE: groupRunE}
+	templateCmd := newGroupCommand(&cobra.Command{Use: "template", Short: "文档模板管理", RunE: groupRunE})
 
 	templateListCmd := &cobra.Command{
 		Use:   "list",

internal/helpers/doc_style.go

@@ -20,7 +20,7 @@ const docStyleGetToolName = "get_document_style"
 
 // newDocStyleCommand 构建 `dws doc style` 命令组：cover set|clear、background set|clear、get。
 func newDocStyleCommand() *cobra.Command {
-	styleCmd := &cobra.Command{
+	styleCmd := newGroupCommand(&cobra.Command{
 		Use:   "style",
 		Short: "文档样式配置 (封面/背景)",
 		Long: `配置钉钉文档的封面与背景（单接口收口 update_document_style）。
@@ -34,13 +34,13 @@ func newDocStyleCommand() *cobra.Command {
 
 封面图片支持 --image 外链 (自动转存) 或 --file 本地文件上传，均会转存为公开读地址；背景仅支持 --color 纯色。`,
 		RunE: groupRunE,
-	}
+	})
 
-	coverCmd := &cobra.Command{
+	coverCmd := newGroupCommand(&cobra.Command{
 		Use:   "cover",
 		Short: "文档封面设置/移除",
 		RunE:  groupRunE,
-	}
+	})
 	coverSetCmd := &cobra.Command{
 		Use:   "set",
 		Short: "设置文档封面",
@@ -110,11 +110,11 @@ func newDocStyleCommand() *cobra.Command {
 		},
 	})
 
-	backgroundCmd := &cobra.Command{
+	backgroundCmd := newGroupCommand(&cobra.Command{
 		Use:   "background",
 		Short: "文档背景设置/清除",
 		RunE:  groupRunE,
-	}
+	})
 	backgroundSetCmd := &cobra.Command{
 		Use:     "set",
 		Short:   "设置文档背景纯色",

internal/helpers/doc_whiteboard.go

@@ -207,12 +207,12 @@ func runWhiteboardInsert(cmd *cobra.Command, _ []string) error {
 }
 
 func newDocWhiteboardCommand() *cobra.Command {
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "whiteboard",
 		Short: "白板卡片管理",
 		Long:  `管理钉钉文档中的白板卡片：插入空白板并获取白板资源 ID。删除白板卡片请使用 dws doc block delete。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	insertCmd := &cobra.Command{
 		Use:   "insert",

internal/helpers/doc_write_pipeline.go

@@ -14,9 +14,12 @@ import (
 )
 
 const (
-	// initialChunkSize is the first attempted chunk size (rune count).
-	// Server-side OSS delta resolution is now fixed, so large chunks are safe.
-	initialChunkSize = 10000
+	// DefaultMarkdownChunkRunes is the single source of truth for the markdown
+	// append-mode chunk limit (rune count), shared by every write path that
+	// chunks. The splitter budgets any injected repair (a re-emitted table
+	// header, a reopened fence) against this limit, so a repaired chunk is still
+	// guaranteed to be at most this many runes.
+	DefaultMarkdownChunkRunes = 30000
 
 	// longContentWarningThreshold triggers a hint to use --content-file.
 	longContentWarningThreshold = 2048
@@ -49,10 +52,22 @@ func detectContentSource(cmd *cobra.Command) contentInputSource {
 
 // DocWriteResult is the structured output of the write pipeline.
 type DocWriteResult struct {
-	Success        bool            `json:"success"`
-	NodeID         string          `json:"nodeId"`
-	ChunksWritten  int             `json:"chunksWritten"`
-	ServerResponse json.RawMessage `json:"serverResponse,omitempty"`
+	Success       bool   `json:"success"`
+	NodeID        string `json:"nodeId"`
+	ChunksWritten int    `json:"chunksWritten"`
+	// Degradations lists the chunk boundaries that changed the rendered
+	// structure. Empty means the document reads exactly as the input did.
+	Degradations   []MarkdownDegradation `json:"degradations,omitempty"`
+	ServerResponse json.RawMessage       `json:"serverResponse,omitempty"`
+}
+
+// chunkedWriteOutcome is what a chunked write reports back. It is a struct rather
+// than another return value because the tuple was already four wide.
+type chunkedWriteOutcome struct {
+	nodeID       string
+	written      int
+	lastResponse string
+	degradations []MarkdownDegradation
 }
 
 // docWritePipeline is the unified entry point for doc create/update with
@@ -61,7 +76,7 @@ type DocWriteResult struct {
 // Phases:
 //
 //  0. Pre-check: warn if --content literal is long
-//  1. Strategy: single write (≤initialChunkSize) or chunked
+//  1. Strategy: single write (≤DefaultMarkdownChunkRunes) or chunked
 //  2. Write: single call or adaptive chunked writes
 //  3. Output: JSON result
 func docWritePipeline(cmd *cobra.Command, toolName string, toolArgs map[string]any,
@@ -84,25 +99,37 @@ func docWritePipeline(cmd *cobra.Command, toolName string, toolArgs map[string]a
 	defer stop()
 
 	// Phase 1+2: strategy selection and write
-	var nodeID string
-	var chunksWritten int
-	var lastResponse string
+	var outcome chunkedWriteOutcome
 	var writeErr error
 
-	if markdown == "" || runeCount <= initialChunkSize {
+	if markdown == "" || runeCount <= DefaultMarkdownChunkRunes {
 		// Single write path
-		nodeID, lastResponse, writeErr = singleWrite(ctx, toolName, toolArgs)
-		chunksWritten = 1
+		outcome.nodeID, outcome.lastResponse, writeErr = singleWrite(ctx, toolName, toolArgs)
+		outcome.written = 1
 		if writeErr != nil && isTimeoutError(writeErr.Error()) {
 			// The server may have committed the write before the client observed the
 			// timeout. Replaying create/append here can duplicate a document or
 			// content, so fail closed and require inspection before any retry.
-			writeErr = docWriteUnknownStateError(operation, nodeID, "single_write", 0, 1, writeErr)
+			writeErr = docWriteUnknownStateError(operation, outcome.nodeID, "single_write", 0, 1, writeErr, nil)
 		}
 	} else {
-		// Chunked write path
+		// Chunked write path. --index cannot survive chunking: each chunk creates
+		// an unpredictable number of blocks, so the insertion point for chunk 2
+		// is unknowable. Fail closed rather than silently ignore the flag.
+		if _, hasIndex := toolArgs["index"]; hasIndex {
+			return apperrors.NewValidation(
+				fmt.Sprintf("内容长度 %d 字符超过单次写入上限 %d，需要自动分片，而 --index 在分片写入下无法保证插入位置", runeCount, DefaultMarkdownChunkRunes),
+				apperrors.WithOperation(operation),
+				apperrors.WithReason("doc_write_index_with_chunking"),
+				apperrors.WithRetryable(false),
+				apperrors.WithActions(
+					"去掉 --index 追加到文档末尾",
+					"或把内容拆成小于上限的多段，各自带 --index 分别写入",
+				),
+			)
+		}
 		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 内容较长 (%d 字符)，自动分片写入...", runeCount))
-		nodeID, chunksWritten, lastResponse, writeErr = chunkedWrite(ctx, toolName, toolArgs, markdown, operation, initialChunkSize)
+		outcome, writeErr = chunkedWrite(ctx, toolName, toolArgs, markdown, operation, DefaultMarkdownChunkRunes)
 	}
 
 	if writeErr != nil {
@@ -112,11 +139,12 @@ func docWritePipeline(cmd *cobra.Command, toolName string, toolArgs map[string]a
 	// Phase 3: output
 	result := DocWriteResult{
 		Success:       true,
-		NodeID:        nodeID,
-		ChunksWritten: chunksWritten,
+		NodeID:        outcome.nodeID,
+		ChunksWritten: outcome.written,
+		Degradations:  outcome.degradations,
 	}
-	if json.Valid([]byte(lastResponse)) {
-		result.ServerResponse = json.RawMessage(lastResponse)
+	if json.Valid([]byte(outcome.lastResponse)) {
+		result.ServerResponse = json.RawMessage(outcome.lastResponse)
 	}
 	return deps.Out.PrintJSON(result)
 }
@@ -131,18 +159,19 @@ func singleWrite(ctx context.Context, toolName string, toolArgs map[string]any)
 	return nodeID, resultText, nil
 }
 
-// chunkedWrite performs adaptive chunked writing.
-// For doc create: first chunk creates the document directly (with content), rest append.
-// For doc update with overwrite: first chunk uses overwrite, rest use append.
-// Returns nodeID, chunks written, last server response text, and error.
+// chunkedWrite writes markdown as a sequence of independently valid chunks.
+// For doc create: the first chunk creates the document directly (with content),
+// the rest append. For doc update with overwrite: the first chunk uses overwrite,
+// the rest use append.
 func chunkedWrite(ctx context.Context, toolName string, toolArgs map[string]any,
-	markdown string, operation string, startChunkSize int) (string, int, string, error) {
+	markdown string, operation string, chunkSize int) (chunkedWriteOutcome, error) {
 
-	var nodeID string
-	var lastResponse string
-	chunkSize := startChunkSize
-	chunks := splitMarkdownSafe(markdown, chunkSize)
-	writtenCount := 0
+	plan := SplitMarkdownForAppend(markdown, chunkSize)
+	chunks := plan.Chunks
+	out := chunkedWriteOutcome{degradations: plan.Degradations}
+	for _, warning := range plan.Warnings() {
+		deps.Out.PrintInfo("[WARN] " + warning)
+	}
 
 	// --- Write first chunk ---
 	if toolName == "create_document" {
@@ -154,81 +183,89 @@ func chunkedWrite(ctx context.Context, toolName string, toolArgs map[string]any,
 		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 写入分片 (1/%d)，%d 字符 (create)...",
 			len(chunks), utf8.RuneCountInString(chunks[0])))
 		resultText, err := callMCPToolReturnText(ctx, "create_document", createArgs)
+		out.lastResponse = resultText
 		if err != nil {
 			if isTimeoutError(err.Error()) {
-				return "", 0, resultText, docWriteUnknownStateError(operation, "", "chunk_1", 0, len(chunks), err)
+				return out, docWriteUnknownStateError(operation, "", "chunk_1", 0, len(chunks), err, plan.Degradations)
 			}
-			return "", 0, resultText, fmt.Errorf("创建文档失败: %w", err)
+			return out, fmt.Errorf("创建文档失败: %w", err)
 		}
-		nodeID = extractNodeIDFromResult(resultText)
-		if nodeID == "" {
-			return "", 0, resultText, fmt.Errorf("创建文档成功但无法提取 nodeId")
+		out.nodeID = extractNodeIDFromResult(resultText)
+		if out.nodeID == "" {
+			return out, fmt.Errorf("创建文档成功但无法提取 nodeId")
 		}
-		lastResponse = resultText
-		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 文档已创建 (nodeId=%s)", nodeID))
+		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 文档已创建 (nodeId=%s)", out.nodeID))
 	} else {
 		if id, ok := toolArgs["nodeId"].(string); ok {
-			nodeID = id
+			out.nodeID = id
 		}
 		firstMode := "append"
 		if m, ok := toolArgs["mode"].(string); ok {
 			firstMode = m
 		}
 		updateArgs := map[string]any{
-			"nodeId":   nodeID,
+			"nodeId":   out.nodeID,
 			"markdown": chunks[0],
 			"mode":     firstMode,
 		}
 		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 写入分片 (1/%d)，%d 字符 (%s)...",
 			len(chunks), utf8.RuneCountInString(chunks[0]), firstMode))
 		resultText, err := callMCPToolReturnText(ctx, "update_document", updateArgs)
+		out.lastResponse = resultText
 		if err != nil {
 			if isTimeoutError(err.Error()) {
-				return nodeID, 0, resultText, docWriteUnknownStateError(operation, nodeID, "chunk_1", 0, len(chunks), err)
+				return out, docWriteUnknownStateError(operation, out.nodeID, "chunk_1", 0, len(chunks), err, plan.Degradations)
 			}
-			return nodeID, 0, resultText, fmt.Errorf("第 1 片写入失败: %w", err)
+			return out, fmt.Errorf("第 1 片写入失败: %w", err)
 		}
-		lastResponse = resultText
 	}
-	writtenCount = 1
+	out.written = 1
 
 	// --- Write remaining chunks with append ---
 	for i := 1; i < len(chunks); i++ {
 		if ctx.Err() != nil {
-			return nodeID, writtenCount, lastResponse, fmt.Errorf("写入被中断，已完成 %d/%d 片", writtenCount, len(chunks))
+			return out, fmt.Errorf("写入被中断，已完成 %d/%d 片", out.written, len(chunks))
 		}
 
 		chunk := chunks[i]
-		preview := chunk
-		if len(preview) > 80 {
-			preview = preview[:80]
-		}
 		deps.Out.PrintInfo(fmt.Sprintf("[INFO] 写入分片 (%d/%d)，%d 字符, preview=[%s]...",
-			i+1, len(chunks), utf8.RuneCountInString(chunk), preview))
+			i+1, len(chunks), utf8.RuneCountInString(chunk), previewRunes(chunk, 80)))
 
 		updateArgs := map[string]any{
-			"nodeId":   nodeID,
+			"nodeId":   out.nodeID,
 			"markdown": chunk,
 			"mode":     "append",
 		}
 		resultText, err := callMCPToolReturnText(ctx, "update_document", updateArgs)
+		out.lastResponse = resultText
 		if err != nil {
 			if isTimeoutError(err.Error()) {
-				return nodeID, writtenCount, resultText, docWriteUnknownStateError(
-					operation, nodeID, fmt.Sprintf("chunk_%d", i+1), writtenCount, len(chunks), err,
+				return out, docWriteUnknownStateError(
+					operation, out.nodeID, fmt.Sprintf("chunk_%d", i+1), out.written, len(chunks), err, plan.Degradations,
 				)
 			}
-			return nodeID, writtenCount, resultText, fmt.Errorf("分片 %d 写入失败: %w", writtenCount+1, err)
+			return out, fmt.Errorf("分片 %d 写入失败: %w", out.written+1, err)
 		}
-		lastResponse = resultText
-		writtenCount++
+		out.written++
 	}
 
-	deps.Out.PrintInfo(fmt.Sprintf("[INFO] 全部 %d 个分片写入完成", writtenCount))
-	return nodeID, writtenCount, lastResponse, nil
+	deps.Out.PrintInfo(fmt.Sprintf("[INFO] 全部 %d 个分片写入完成", out.written))
+	return out, nil
 }
 
-func docWriteUnknownStateError(operation, nodeID, stage string, written, total int, cause error) error {
+// previewRunes truncates to at most n runes. Slicing by byte would cut a
+// multi-byte character in half and put invalid UTF-8 into the log line.
+func previewRunes(s string, n int) string {
+	runes := []rune(s)
+	if len(runes) <= n {
+		return s
+	}
+	return string(runes[:n])
+}
+
+func docWriteUnknownStateError(operation, nodeID, stage string, written, total int,
+	cause error, degradations []MarkdownDegradation) error {
+
 	details := map[string]any{
 		"status":        "unknown",
 		"nodeId":        nodeID,
@@ -236,6 +273,12 @@ func docWriteUnknownStateError(operation, nodeID, stage string, written, total i
 		"chunksTotal":   total,
 		"failedStage":   stage,
 	}
+	if len(degradations) > 0 {
+		// Resuming safely needs to know which boundaries carried injected repair
+		// text, because a chunk that begins with a repeated table header is not
+		// the same as the raw source at that offset.
+		details["degradations"] = degradations
+	}
 	return apperrors.NewAPI(
 		"文档写入响应超时，服务端提交状态未知；为避免重复创建或重复追加，已停止自动重试",
 		apperrors.WithOperation(operation),

internal/helpers/doc_write_pipeline_coverage_more_test.go

@@ -1,7 +1,9 @@
 package helpers
 
 import (
+	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
 	"os"
 	"strings"
@@ -49,13 +51,104 @@ func TestCrossPlatformCoverageDocWritePipelineStrategyRemainingCoverage(t *testi
 		t.Fatalf("single timeout must stop without replay: err=%v calls=%d", err, timeoutCaller.calls)
 	}
 
-	chunked := strings.Repeat("x", initialChunkSize+100)
+	chunked := strings.Repeat("x", DefaultMarkdownChunkRunes+100)
 	installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{}`}, {text: `{}`}}})
 	if err := docWritePipeline(docWriteCoverageCommand(), "update_document", map[string]any{"nodeId": "node", "markdown": chunked}, chunked, "update"); err != nil {
 		t.Fatalf("long content chunking: %v", err)
 	}
 }
 
+func TestCrossPlatformCoverageDocWriteRejectsIndexWhenChunking(t *testing.T) {
+	oldArgs := os.Args
+	os.Args = []string{"dws", "doc"}
+	t.Cleanup(func() { os.Args = oldArgs })
+
+	// --index cannot be propagated across chunks: each chunk creates an unknown
+	// number of blocks, so the insertion point for chunk 2 is unknowable. Before
+	// this guard, chunkedWrite rebuilt the tool args with only nodeId/markdown/mode
+	// and the flag was silently dropped.
+	long := strings.Repeat("x", DefaultMarkdownChunkRunes+10)
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{}`}, {text: `{}`}}}
+	installScriptedCaller(t, caller)
+	err := docWritePipeline(docWriteCoverageCommand(), "update_document",
+		map[string]any{"nodeId": "node", "mode": "append", "index": 3}, long, "update")
+	var typed *apperrors.Error
+	if err == nil || !errors.As(err, &typed) || typed.Reason != "doc_write_index_with_chunking" {
+		t.Fatalf("expected a fail-closed validation error, got %#v", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("must reject before writing anything, calls=%d", caller.calls)
+	}
+
+	// The same args below the limit stay allowed, so the guard is scoped to
+	// chunking rather than banning --index outright.
+	installScriptedCaller(t, &scriptedToolCaller{steps: []scriptedToolStep{{text: `{}`}}})
+	if err := docWritePipeline(docWriteCoverageCommand(), "update_document",
+		map[string]any{"nodeId": "node", "mode": "append", "index": 3}, "short", "update"); err != nil {
+		t.Fatalf("short content with --index must still write: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageDocWriteSurfacesDegradations(t *testing.T) {
+	oldArgs := os.Args
+	os.Args = []string{"dws", "doc"}
+	t.Cleanup(func() { os.Args = oldArgs })
+	// An oversized table must be split with its header repeated, and the caller
+	// must be told so — silently turning one table into three would otherwise
+	// look like a clean write.
+	rows := strings.Repeat("| 张三 | 技术部 | 10086 |\n", 4000)
+	content := "| 姓名 | 部门 | 工号 |\n|---|---|---|\n" + rows
+	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{}`}, {text: `{}`}, {text: `{}`}, {text: `{}`}}}
+	installScriptedCaller(t, caller)
+	// installScriptedCaller initializes deps and discards output; capture stdout
+	// afterwards so the result JSON can be inspected.
+	var stdout bytes.Buffer
+	deps.Out = NewFormatterWithWriters(&stdout, &bytes.Buffer{})
+	if err := docWritePipeline(docWriteCoverageCommand(), "update_document",
+		map[string]any{"nodeId": "node", "mode": "overwrite"}, content, "update"); err != nil {
+		t.Fatalf("chunked table write: %v", err)
+	}
+
+	// The result JSON follows the [INFO]/[WARN] progress lines on the same stream.
+	out := stdout.String()
+	if !strings.Contains(out, "[WARN] 内容过长已分片") {
+		t.Errorf("no warning line for the table split: %q", out)
+	}
+	var result DocWriteResult
+	if err := json.Unmarshal([]byte(out[strings.Index(out, "{"):]), &result); err != nil {
+		t.Fatalf("decode result: %v (stdout=%q)", err, out)
+	}
+	if result.ChunksWritten < 2 {
+		t.Fatalf("expected a chunked write, got %#v", result)
+	}
+	if len(result.Degradations) == 0 {
+		t.Fatalf("table split was not reported: %#v", result)
+	}
+	for _, d := range result.Degradations {
+		if d.Kind != "table_split" || !strings.HasPrefix(d.InjectedPrefix, "| 姓名 ") {
+			t.Errorf("degradation = %#v", d)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageDocWritePreviewTruncatesByRune(t *testing.T) {
+	// Slicing by byte would split a multi-byte character and put invalid UTF-8
+	// into the progress line.
+	for _, tc := range []struct {
+		in   string
+		n    int
+		want string
+	}{
+		{"abc", 5, "abc"},
+		{"abcdef", 3, "abc"},
+		{strings.Repeat("界", 5), 2, "界界"},
+	} {
+		if got := previewRunes(tc.in, tc.n); got != tc.want {
+			t.Errorf("previewRunes(%q,%d) = %q, want %q", tc.in, tc.n, got, tc.want)
+		}
+	}
+}
+
 func TestCrossPlatformCoverageChunkedWriteAdaptiveRetryRemainingCoverage(t *testing.T) {
 	oldArgs := os.Args
 	os.Args = []string{"dws", "doc"}
@@ -63,9 +156,9 @@ func TestCrossPlatformCoverageChunkedWriteAdaptiveRetryRemainingCoverage(t *test
 	markdown := strings.Repeat("x", 24000)
 	caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{}`}, {err: errors.New("HSFTimeoutException")}, {text: `{}`}}}
 	installScriptedCaller(t, caller)
-	_, written, _, err := chunkedWrite(context.Background(), "update_document", map[string]any{"nodeId": "node"}, markdown, "update", 10000)
-	if err == nil || written != 1 || caller.calls != 2 || !strings.Contains(err.Error(), "提交状态未知") {
-		t.Fatalf("timeout must stop without replay: written=%d calls=%d err=%v", written, caller.calls, err)
+	outcome, err := chunkedWrite(context.Background(), "update_document", map[string]any{"nodeId": "node"}, markdown, "update", 10000)
+	if err == nil || outcome.written != 1 || caller.calls != 2 || !strings.Contains(err.Error(), "提交状态未知") {
+		t.Fatalf("timeout must stop without replay: written=%d calls=%d err=%v", outcome.written, caller.calls, err)
 	}
 }
 
@@ -87,13 +180,13 @@ func TestCrossPlatformCoverageDocWriteFirstChunkTimeoutIsUnknown(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			caller := &scriptedToolCaller{steps: []scriptedToolStep{{err: errors.New("HSFTimeoutException")}, {text: `{}`}}}
 			installScriptedCaller(t, caller)
-			nodeID, written, _, err := chunkedWrite(context.Background(), tc.tool, tc.args, markdown, tc.name, 10000)
+			outcome, err := chunkedWrite(context.Background(), tc.tool, tc.args, markdown, tc.name, 10000)
 			var typed *apperrors.Error
 			if err == nil || !errors.As(err, &typed) {
 				t.Fatalf("error = %#v", err)
 			}
-			if nodeID != tc.wantNode || written != 0 || caller.calls != 1 {
-				t.Fatalf("node=%q written=%d calls=%d", nodeID, written, caller.calls)
+			if outcome.nodeID != tc.wantNode || outcome.written != 0 || caller.calls != 1 {
+				t.Fatalf("node=%q written=%d calls=%d", outcome.nodeID, outcome.written, caller.calls)
 			}
 			if typed.Reason != "doc_write_commit_unknown" || typed.FailureStage != "chunk_1" || typed.ExecutionStarted == nil || !*typed.ExecutionStarted || !typed.RetryableSet || typed.Retryable {
 				t.Fatalf("unknown commit metadata = %#v", typed)

internal/helpers/drive.go

@@ -375,12 +375,12 @@ func newDriveCommand() *cobra.Command {
 			},
 		},
 	})
-	driveCmd := &cobra.Command{
+	driveCmd := newGroupCommand(&cobra.Command{
 		Use:   "drive",
 		Short: "钉盘文件管理",
 		Long:  `钉盘：列出文件/文件夹、获取元数据和统计信息、创建快捷方式、下载、上传及管理文件。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	driveListCmd := &cobra.Command{
 		Use:   "list",
@@ -2030,14 +2030,14 @@ func newDriveCommand() *cobra.Command {
 	driveShortcutCmd.Flags().String("workspace", "", "目标知识库 ID (可选)")
 
 	// ── drive permission (文档节点权限管理) ──
-	drivePermissionCmd := &cobra.Command{
+	drivePermissionCmd := newGroupCommand(&cobra.Command{
 		Use:     "permission",
 		Aliases: []string{"perm"},
 		Short:   "文档节点权限管理",
 		Long: `管理文档空间节点的协作权限：添加、更新、查询、移除协作者。
 注意: 仅适用于文档空间节点，不适用于钉盘文件。`,
 		RunE: groupRunE,
-	}
+	})
 
 	drivePermAddCmd := &cobra.Command{
 		Use:   "add",
@@ -2806,12 +2806,12 @@ func newDriveCommand() *cobra.Command {
 	_ = driveRenameCmd.Flags().MarkHidden("title")
 
 	// ── drive recycle 子命令组 ──
-	recycleCmd := &cobra.Command{
+	recycleCmd := newGroupCommand(&cobra.Command{
 		Use:   "recycle",
 		Short: "钉盘回收站管理",
 		Long:  `管理钉盘回收站：查看回收站列表、还原回收项。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	recycleListCmd := &cobra.Command{
 		Use:     "list",
@@ -2921,7 +2921,7 @@ func newDriveCommand() *cobra.Command {
 	// ── deprecated 代理命令（Phase 2：从 doc 迁移，保留兼容，警告引导到新命令）──
 
 	// folder create → dws wiki node create --type folder
-	driveFolderCmd := &cobra.Command{Use: "folder", Short: "文件夹管理（deprecated）", RunE: groupRunE}
+	driveFolderCmd := newGroupCommand(&cobra.Command{Use: "folder", Short: "文件夹管理（deprecated）", RunE: groupRunE})
 	driveFolderCreateCmd := &cobra.Command{
 		Use:   "create",
 		Short: "创建文件夹（deprecated）",
@@ -2951,12 +2951,12 @@ func newDriveCommand() *cobra.Command {
 	driveFolderCmd.AddCommand(driveFolderCreateCmd)
 
 	// ── drive publish (文件互联网公开发布管理) ──
-	drivePublishCmd := &cobra.Command{
+	drivePublishCmd := newGroupCommand(&cobra.Command{
 		Use:   "publish",
 		Short: "文件互联网公开发布管理",
 		Long:  `管理文件的互联网公开发布状态：设置公开、关闭公开、查询公开状态。`,
 		RunE:  groupRunE,
-	}
+	})
 
 	drivePublishSetCmd := &cobra.Command{
 		Use:   "set",
@@ -3251,11 +3251,11 @@ func newDriveCommand() *cobra.Command {
 	_ = driveRecentCmd.Flags().MarkHidden("page-token")
 
 	// ── drive star (文档收藏管理) ──
-	driveStarCmd := &cobra.Command{
+	driveStarCmd := newGroupCommand(&cobra.Command{
 		Use:   "star",
 		Short: "文档收藏管理",
 		RunE:  groupRunE,
-	}
+	})
 	driveStarAddCmd := &cobra.Command{
 		Use:     "add",
 		Short:   "收藏文档",

internal/helpers/edu_app_test.go

@@ -1,503 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-func withEduAppCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func runEduApp(t *testing.T, args ...string) error {
-	t.Helper()
-	cmd := newEduAppCommand()
-	cmd.SetArgs(args)
-	return cmd.Execute()
-}
-
-// TestEduAppHappyPathsFullFlags exercises each leaf command with every flag
-// populated, so all optional-field branches and the dispatch line are covered.
-func TestCrossPlatformCoverageEduAppHappyPathsFullFlags(t *testing.T) {
-	cases := [][]string{
-		{"message", "summary-list", "--class-id", "1", "--cid", "c", "--target-role", "guardian", "--status", "0"},
-
-		{"task", "publish-list", "--cursor", "5", "--limit", "10", "--need-statistic", "--task-sources", "EDU_HOMEWORK,EDU_NOTICE"},
-		{"task", "all-list", "--biz-id", "1", "--cursor", "5", "--limit", "10", "--need-statistic", "--task-sources", "EDU_CARD"},
-		{"task", "student-list", "--students", `[{"userId":"u1","bizId":"1"}]`, "--query-all", "--cursor", "c", "--limit", "10", "--task-sources", "EDU_SR"},
-
-		{"report", "get", "--ids", "1001,1002"},
-		{"report", "by-teacher", "--page", "1", "--limit", "20", "--status", "1"},
-		{"report", "by-class", "--report-id", "1001", "--class-id", "12345", "--student-ids", "u1,u2"},
-		{"report", "by-student-list", "--class-id", "12345", "--student-id", "u1", "--page", "1", "--limit", "20"},
-		{"report", "by-student-detail", "--report-id", "1001", "--student-id", "u1", "--class-id", "12345"},
-
-		{"notice", "confirm", "--notice-id", "n1", "--student-id", "u1", "--device-id", "d1", "--parent-name", "张三", "--update-sign"},
-		{"notice", "create", "--identifer", "org1-staff1-uuid", "--content", "明天放假", "--title", "放假",
-			"--class-ids", "1,2", "--class-names", "一班,二班", "--class-selected-students", `{"1":["u1"]}`,
-			"--type", "SCHOOL", "--scope", "ALL", "--target-role", "guardian", "--is-signed", "true",
-			"--photo", "p", "--media", "m", "--audio", "a", "--send-ding", "--scheduled-release", "2026-07-29",
-			"--notice-deadline", "100", "--notice-deadline-open", "true", "--notice-deadline-setting", "s",
-			"--attributes", `{"k":"v"}`, "--user-name", "张三"},
-		{"notice", "delete", "--notice-id", "12345", "--user-name", "张三"},
-		{"notice", "list-by-teacher", "--class-id", "c", "--type", "SCHOOL", "--status", "FINISHED", "--user-name", "u", "--page", "1", "--page-size", "20"},
-		{"notice", "get", "--notice-id", "12345", "--user-name", "张三"},
-		{"notice", "confirm-status", "--notice-id", "12345", "--class-id", "c", "--status", "CONFIRMED", "--user-name", "u", "--page", "1", "--page-size", "20"},
-		{"notice", "list-by-student", "--student-id", "u1", "--class-id", "c", "--status", "FINISHED", "--user-name", "u", "--page", "1", "--page-size", "20"},
-
-		{"circle", "posts", "--class-id", "12345", "--student-id", "u1", "--target-role", "guardian"},
-
-		{"card", "update", "--card-id", "1", "--identifier", "org1-staff1-uuid", "--title", "新标题", "--content", "新内容", "--should-send-update-msg"},
-		{"card", "end", "--card-id", "1"},
-		{"card", "list", "--status", "UNFINISH", "--class-id", "5", "--page", "1", "--limit", "10"},
-		{"card", "user-statistic", "--card-id", "1", "--task-code", "code1", "--class-id", "cid1", "--finish", "--page", "1", "--limit", "20"},
-		{"card", "finish-info", "--card-id", "1", "--card-biz-id", "bid1", "--target-role", "guardian", "--student-id", "stu1"},
-
-		{"diploma", "create", "--identifier", "org1-staff1-uuid", "--content", "期末三好学生", "--user-name", "张三",
-			"--title", "三好学生", "--unit-name", "实验小学", "--tag", "三好", "--photo", "p", "--publish-time", "2026-07-29",
-			"--biz-code", "bc", "--biz-category", "cat", "--msg-type", "mt", "--template-url", "tpl",
-			"--class-ids", "1,2", "--select-class", `[{"classId":"1"}]`, "--attributes", `{"k":"v"}`},
-		{"diploma", "read", "--diploma-id", "1", "--class-id", "c", "--student-id", "u1", "--user-name", "张三"},
-		{"diploma", "list-by-teacher", "--page", "1", "--limit", "20", "--status", "PUBLISHED", "--tag", "三好", "--user-name", "u"},
-		{"diploma", "get", "--diploma-id", "1", "--user-name", "张三"},
-		{"diploma", "statistics", "--diploma-id", "1", "--user-name", "张三"},
-		{"diploma", "detail", "--diploma-id", "1", "--class-id", "c", "--user-name", "张三"},
-		{"diploma", "list-by-student", "--student-id", "u1", "--class-id", "c", "--page", "1", "--limit", "20", "--user-name", "张三"},
-		{"diploma", "student-detail", "--diploma-id", "1", "--student-id", "u1", "--class-id", "c", "--user-name", "张三"},
-		{"diploma", "delete", "--diploma-id", "1", "--user-name", "张三"},
-
-		{"homework", "create", "--identifier", "org1-staff1-uuid", "--hw-content", "完成练习",
-			"--hw-title", "数学作业", "--hw-photo", "p", "--hw-media", "m", "--hw-video", "v",
-			"--class-ids", "1,2", "--class-names", "一班,二班", "--class-selected-students", `{"1":["u1"]}`,
-			"--feedback", "fb", "--hw-deadline", "100", "--hw-deadline-open", "true", "--hw-deadline-setting", "s",
-			"--submit-types", "TEXT,PHOTO", "--hw-type", "HOMEWORK", "--target-role", "guardian", "--publish-type", "NOW",
-			"--biz-code", "bc", "--scheduled-release", "2026-07-29", "--task-plan-duration", "5", "--attributes", `{"k":"v"}`, "--user-name", "张三"},
-		{"homework", "delete", "--homework-id", "1", "--user-name", "张三"},
-		{"homework", "submit", "--hw-content-detail-id", "1", "--homework-id", "2", "--student-id", "u1", "--class-id", "c",
-			"--content", "已完成", "--photo", "p", "--media", "m", "--video", "v", "--user-name", "张三"},
-		{"homework", "get", "--homework-id", "1", "--user-name", "张三"},
-		{"homework", "class-by-homework", "--homework-id", "1", "--class-id", "c", "--user-name", "张三"},
-		{"homework", "class-detail", "--homework-id", "1", "--class-id", "c", "--user-name", "张三"},
-		{"homework", "submit-statistics", "--homework-id", "1", "--class-id", "c", "--user-name", "张三"},
-		{"homework", "list-by-student", "--student-id", "u1", "--class-id", "c", "--user-name", "张三", "--status", "FINISHED", "--page", "1", "--page-size", "20"},
-		{"homework", "student-detail", "--homework-id", "1", "--student-id", "u1", "--class-id", "c", "--user-name", "张三"},
-		{"homework", "list-by-teacher", "--class-id", "c", "--type", "HOMEWORK", "--status", "FINISHED", "--user-name", "u", "--page", "1", "--page-size", "20"},
-		{"homework", "create-comment", "--comment", "做得很好", "--hw-content-detail-id", "1", "--homework-id", "2",
-			"--student-id", "u1", "--photo", "p", "--video", "v", "--media", "m", "--user-name", "张三"},
-	}
-	for _, args := range cases {
-		t.Run(strings.Join(args, " "), func(t *testing.T) {
-			withEduAppCaller(t)
-			if err := runEduApp(t, args...); err != nil {
-				t.Fatalf("Execute(%v) = %v, want nil", args, err)
-			}
-		})
-	}
-}
-
-// TestEduAppZeroPagination drives the pagination defaulting branches (page<=0 /
-// page-size<=0 / the >0 else arms) that the positive-value happy paths skip.
-func TestCrossPlatformCoverageEduAppZeroPagination(t *testing.T) {
-	cases := [][]string{
-		{"report", "by-teacher", "--page", "0", "--limit", "0"},
-		{"report", "by-student-list", "--class-id", "c", "--student-id", "u1", "--page", "0", "--limit", "0"},
-		{"notice", "list-by-teacher", "--page", "0", "--page-size", "0"},
-		{"notice", "confirm-status", "--notice-id", "1", "--class-id", "c", "--page", "0", "--page-size", "0"},
-		{"notice", "list-by-student", "--student-id", "u1", "--class-id", "c", "--page", "0", "--page-size", "0"},
-		{"card", "list", "--status", "FINISH", "--page", "0", "--limit", "0"},
-		{"card", "user-statistic", "--card-id", "1", "--task-code", "code1", "--class-id", "cid1", "--page", "0", "--limit", "0"},
-		{"diploma", "list-by-teacher", "--page", "0", "--limit", "0"},
-		{"diploma", "list-by-student", "--student-id", "u1", "--class-id", "c", "--page", "0", "--limit", "0"},
-		{"homework", "list-by-student", "--student-id", "u1", "--class-id", "c", "--user-name", "张三", "--page", "0", "--page-size", "0"},
-		{"homework", "list-by-teacher", "--page", "0", "--page-size", "0"},
-	}
-	for _, args := range cases {
-		t.Run(strings.Join(args, " "), func(t *testing.T) {
-			withEduAppCaller(t)
-			if err := runEduApp(t, args...); err != nil {
-				t.Fatalf("Execute(%v) = %v, want nil", args, err)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduAppErrorPaths(t *testing.T) {
-	cases := []struct {
-		name string
-		args []string
-		want string
-	}{
-		{"summary-list missing class-id", []string{"message", "summary-list", "--cid", "c", "--target-role", "guardian", "--status", "0"}, "class-id"},
-		{"summary-list non-int class-id", []string{"message", "summary-list", "--class-id", "abc", "--cid", "c", "--target-role", "guardian", "--status", "0"}, "整数"},
-		{"summary-list missing cid", []string{"message", "summary-list", "--class-id", "1", "--target-role", "guardian", "--status", "0"}, "cid"},
-		{"summary-list missing target-role", []string{"message", "summary-list", "--class-id", "1", "--cid", "c", "--status", "0"}, "target-role"},
-		{"summary-list missing status", []string{"message", "summary-list", "--class-id", "1", "--cid", "c", "--target-role", "guardian"}, "status"},
-		{"summary-list non-int status", []string{"message", "summary-list", "--class-id", "1", "--cid", "c", "--target-role", "guardian", "--status", "x"}, "status"},
-
-		{"all-list missing biz-id", []string{"task", "all-list"}, "biz-id"},
-		{"student-list missing students", []string{"task", "student-list"}, "students"},
-		{"student-list bad json", []string{"task", "student-list", "--students", "{"}, "JSON"},
-
-		{"report get missing ids", []string{"report", "get"}, "ids"},
-		{"report get non-int ids", []string{"report", "get", "--ids", "abc"}, "整数"},
-		{"report by-class missing report-id", []string{"report", "by-class", "--class-id", "c"}, "report-id"},
-		{"report by-class non-int report-id", []string{"report", "by-class", "--report-id", "x", "--class-id", "c"}, "整数"},
-		{"report by-class missing class-id", []string{"report", "by-class", "--report-id", "1"}, "class-id"},
-		{"report by-student-list missing class-id", []string{"report", "by-student-list", "--student-id", "u1"}, "class-id"},
-		{"report by-student-list missing student-id", []string{"report", "by-student-list", "--class-id", "c"}, "student-id"},
-		{"report by-student-detail missing report-id", []string{"report", "by-student-detail", "--student-id", "u1", "--class-id", "c"}, "report-id"},
-		{"report by-student-detail non-int report-id", []string{"report", "by-student-detail", "--report-id", "x", "--student-id", "u1", "--class-id", "c"}, "整数"},
-		{"report by-student-detail missing student-id", []string{"report", "by-student-detail", "--report-id", "1", "--class-id", "c"}, "student-id"},
-		{"report by-student-detail missing class-id", []string{"report", "by-student-detail", "--report-id", "1", "--student-id", "u1"}, "class-id"},
-
-		{"notice confirm missing notice-id", []string{"notice", "confirm", "--student-id", "u1"}, "notice-id"},
-		{"notice confirm missing student-id", []string{"notice", "confirm", "--notice-id", "n1"}, "student-id"},
-		{"notice create missing identifer", []string{"notice", "create", "--content", "c"}, "identifer"},
-		{"notice create missing content", []string{"notice", "create", "--identifer", "x"}, "content"},
-		{"notice create bad selected-students", []string{"notice", "create", "--identifer", "x", "--content", "c", "--class-selected-students", "{"}, "class-selected-students"},
-		{"notice create bad attributes", []string{"notice", "create", "--identifer", "x", "--content", "c", "--attributes", "{"}, "attributes"},
-		{"notice delete missing notice-id", []string{"notice", "delete"}, "notice-id"},
-		{"notice delete non-int notice-id", []string{"notice", "delete", "--notice-id", "x"}, "整数"},
-		{"notice get missing notice-id", []string{"notice", "get"}, "notice-id"},
-		{"notice confirm-status missing notice-id", []string{"notice", "confirm-status", "--class-id", "c"}, "notice-id"},
-		{"notice confirm-status missing class-id", []string{"notice", "confirm-status", "--notice-id", "1"}, "class-id"},
-		{"notice list-by-student missing student-id", []string{"notice", "list-by-student", "--class-id", "c"}, "student-id"},
-		{"notice list-by-student missing class-id", []string{"notice", "list-by-student", "--student-id", "u1"}, "class-id"},
-
-		{"circle posts missing class-id", []string{"circle", "posts", "--student-id", "u1", "--target-role", "guardian"}, "class-id"},
-		{"circle posts missing student-id", []string{"circle", "posts", "--class-id", "c", "--target-role", "guardian"}, "student-id"},
-		{"circle posts missing target-role", []string{"circle", "posts", "--class-id", "c", "--student-id", "u1"}, "target-role"},
-
-		{"card update missing card-id", []string{"card", "update", "--identifier", "i", "--title", "t"}, "card-id"},
-		{"card update missing identifier", []string{"card", "update", "--card-id", "1", "--title", "t"}, "identifier"},
-		{"card update no title no content", []string{"card", "update", "--card-id", "1", "--identifier", "i"}, "至少传一个"},
-		{"card end missing card-id", []string{"card", "end"}, "card-id"},
-		{"card list missing status", []string{"card", "list"}, "status"},
-		{"card list invalid status", []string{"card", "list", "--status", "OTHER"}, "FINISH"},
-		{"card user-statistic missing card-id", []string{"card", "user-statistic", "--task-code", "c", "--class-id", "c"}, "card-id"},
-		{"card user-statistic missing task-code", []string{"card", "user-statistic", "--card-id", "1", "--class-id", "c"}, "task-code"},
-		{"card user-statistic missing class-id", []string{"card", "user-statistic", "--card-id", "1", "--task-code", "c"}, "class-id"},
-		{"card finish-info missing card-id", []string{"card", "finish-info", "--card-biz-id", "b"}, "card-id"},
-		{"card finish-info missing card-biz-id", []string{"card", "finish-info", "--card-id", "1"}, "card-biz-id"},
-		{"card finish-info invalid target-role", []string{"card", "finish-info", "--card-id", "1", "--card-biz-id", "b", "--target-role", "boss"}, "target-role"},
-
-		{"diploma create missing identifier", []string{"diploma", "create", "--content", "c", "--user-name", "u"}, "identifier"},
-		{"diploma create missing content", []string{"diploma", "create", "--identifier", "i", "--user-name", "u"}, "content"},
-		{"diploma create missing user-name", []string{"diploma", "create", "--identifier", "i", "--content", "c"}, "user-name"},
-		{"diploma create bad select-class", []string{"diploma", "create", "--identifier", "i", "--content", "c", "--user-name", "u", "--select-class", "{"}, "select-class"},
-		{"diploma create bad attributes", []string{"diploma", "create", "--identifier", "i", "--content", "c", "--user-name", "u", "--attributes", "{"}, "attributes"},
-		{"diploma read missing diploma-id", []string{"diploma", "read"}, "diploma-id"},
-		{"diploma get missing diploma-id", []string{"diploma", "get"}, "diploma-id"},
-		{"diploma statistics missing diploma-id", []string{"diploma", "statistics"}, "diploma-id"},
-		{"diploma detail missing diploma-id", []string{"diploma", "detail"}, "diploma-id"},
-		{"diploma list-by-student missing student-id", []string{"diploma", "list-by-student", "--class-id", "c"}, "student-id"},
-		{"diploma list-by-student missing class-id", []string{"diploma", "list-by-student", "--student-id", "u1"}, "class-id"},
-		{"diploma student-detail missing diploma-id", []string{"diploma", "student-detail", "--student-id", "u1", "--class-id", "c"}, "diploma-id"},
-		{"diploma student-detail missing student-id", []string{"diploma", "student-detail", "--diploma-id", "1", "--class-id", "c"}, "student-id"},
-		{"diploma student-detail missing class-id", []string{"diploma", "student-detail", "--diploma-id", "1", "--student-id", "u1"}, "class-id"},
-		{"diploma delete missing diploma-id", []string{"diploma", "delete"}, "diploma-id"},
-
-		{"homework create missing identifier", []string{"homework", "create", "--hw-content", "c"}, "identifier"},
-		{"homework create missing hw-content", []string{"homework", "create", "--identifier", "i"}, "hw-content"},
-		{"homework create bad hw-deadline", []string{"homework", "create", "--identifier", "i", "--hw-content", "c", "--hw-deadline", "x"}, "hw-deadline"},
-		{"homework create bad task-plan-duration", []string{"homework", "create", "--identifier", "i", "--hw-content", "c", "--task-plan-duration", "x"}, "task-plan-duration"},
-		{"homework create bad selected-students", []string{"homework", "create", "--identifier", "i", "--hw-content", "c", "--class-selected-students", "{"}, "class-selected-students"},
-		{"homework create bad attributes", []string{"homework", "create", "--identifier", "i", "--hw-content", "c", "--attributes", "{"}, "attributes"},
-		{"homework delete missing homework-id", []string{"homework", "delete"}, "homework-id"},
-		{"homework submit missing detail-id", []string{"homework", "submit"}, "hw-content-detail-id"},
-		{"homework submit bad homework-id", []string{"homework", "submit", "--hw-content-detail-id", "1", "--homework-id", "x"}, "homework-id"},
-		{"homework get missing homework-id", []string{"homework", "get"}, "homework-id"},
-		{"homework class-by-homework missing homework-id", []string{"homework", "class-by-homework"}, "homework-id"},
-		{"homework class-detail missing homework-id", []string{"homework", "class-detail", "--class-id", "c", "--user-name", "u"}, "homework-id"},
-		{"homework class-detail missing class-id", []string{"homework", "class-detail", "--homework-id", "1", "--user-name", "u"}, "class-id"},
-		{"homework class-detail missing user-name", []string{"homework", "class-detail", "--homework-id", "1", "--class-id", "c"}, "user-name"},
-		{"homework submit-statistics missing homework-id", []string{"homework", "submit-statistics", "--class-id", "c"}, "homework-id"},
-		{"homework submit-statistics missing class-id", []string{"homework", "submit-statistics", "--homework-id", "1"}, "class-id"},
-		{"homework list-by-student missing student-id", []string{"homework", "list-by-student", "--class-id", "c", "--user-name", "u"}, "student-id"},
-		{"homework list-by-student missing class-id", []string{"homework", "list-by-student", "--student-id", "u1", "--user-name", "u"}, "class-id"},
-		{"homework list-by-student missing user-name", []string{"homework", "list-by-student", "--student-id", "u1", "--class-id", "c"}, "user-name"},
-		{"homework student-detail missing homework-id", []string{"homework", "student-detail", "--student-id", "u1", "--class-id", "c"}, "homework-id"},
-		{"homework student-detail missing student-id", []string{"homework", "student-detail", "--homework-id", "1", "--class-id", "c"}, "student-id"},
-		{"homework student-detail missing class-id", []string{"homework", "student-detail", "--homework-id", "1", "--student-id", "u1"}, "class-id"},
-		{"homework create-comment missing comment", []string{"homework", "create-comment", "--hw-content-detail-id", "1"}, "comment"},
-		{"homework create-comment missing detail-id", []string{"homework", "create-comment", "--comment", "cm"}, "hw-content-detail-id"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			withEduAppCaller(t)
-			err := runEduApp(t, tc.args...)
-			if err == nil || !strings.Contains(err.Error(), tc.want) {
-				t.Fatalf("Execute(%v) error = %v, want contains %q", tc.args, err, tc.want)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduAppParseHelpers(t *testing.T) {
-	if got := eduAppParseCSV(" a , , b "); len(got) != 2 || got[0] != "a" || got[1] != "b" {
-		t.Fatalf("eduAppParseCSV = %#v", got)
-	}
-	ids, err := eduAppParseIntCSV(" 1 , , 2 ")
-	if err != nil || len(ids) != 2 || ids[0] != 1 || ids[1] != 2 {
-		t.Fatalf("eduAppParseIntCSV = %#v, err = %v", ids, err)
-	}
-	if _, err := eduAppParseIntCSV("1,bad"); err == nil {
-		t.Fatalf("eduAppParseIntCSV invalid = nil error")
-	}
-}
-
-func withEduAppDispatchCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduAppDispatch(t *testing.T) {
-	t.Run("message summary-list dispatches get_ai_message_summary_list", func(t *testing.T) {
-		caller := withEduAppDispatchCaller(t)
-		cmd := newEduAppCommand()
-		cmd.SetArgs([]string{"message", "summary-list", "--class-id", "100", "--cid", "cidxxx", "--target-role", "guardian", "--status", "1"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-app" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-app")
-		}
-		if caller.tool != "get_ai_message_summary_list" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "get_ai_message_summary_list")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] type = %T, want map[string]any", caller.args["input"])
-		}
-		if input["classId"] != int64(100) {
-			t.Fatalf("classId = %v, want 100", input["classId"])
-		}
-		if input["cid"] != "cidxxx" {
-			t.Fatalf("cid = %v, want %q", input["cid"], "cidxxx")
-		}
-		if input["targetRole"] != "guardian" {
-			t.Fatalf("targetRole = %v, want %q", input["targetRole"], "guardian")
-		}
-		if input["status"] != int64(1) {
-			t.Fatalf("status = %v, want 1", input["status"])
-		}
-	})
-
-	t.Run("report get dispatches get_report", func(t *testing.T) {
-		caller := withEduAppDispatchCaller(t)
-		cmd := newEduAppCommand()
-		cmd.SetArgs([]string{"report", "get", "--ids", "1001,1002"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-app" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-app")
-		}
-		if caller.tool != "get_report" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "get_report")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] type = %T, want map[string]any", caller.args["input"])
-		}
-		ids, ok := input["schoolReportIdList"].([]int64)
-		if !ok || len(ids) != 2 || ids[0] != 1001 || ids[1] != 1002 {
-			t.Fatalf("schoolReportIdList = %v, want [1001 1002]", input["schoolReportIdList"])
-		}
-	})
-
-	t.Run("circle posts dispatches query_student_circle_posts", func(t *testing.T) {
-		caller := withEduAppDispatchCaller(t)
-		cmd := newEduAppCommand()
-		cmd.SetArgs([]string{"circle", "posts", "--class-id", "12345", "--student-id", "stu1", "--target-role", "guardian"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-app" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-app")
-		}
-		if caller.tool != "query_student_circle_posts" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "query_student_circle_posts")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] type = %T, want map[string]any", caller.args["input"])
-		}
-		if input["classId"] != "12345" {
-			t.Fatalf("classId = %v, want %q", input["classId"], "12345")
-		}
-		if input["studentId"] != "stu1" {
-			t.Fatalf("studentId = %v, want %q", input["studentId"], "stu1")
-		}
-		if input["targetRole"] != "guardian" {
-			t.Fatalf("targetRole = %v, want %q", input["targetRole"], "guardian")
-		}
-	})
-
-	t.Run("card end dispatches end_card", func(t *testing.T) {
-		caller := withEduAppDispatchCaller(t)
-		cmd := newEduAppCommand()
-		cmd.SetArgs([]string{"card", "end", "--card-id", "999"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-app" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-app")
-		}
-		if caller.tool != "end_card" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "end_card")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] type = %T, want map[string]any", caller.args["input"])
-		}
-		if input["cardId"] != int64(999) {
-			t.Fatalf("cardId = %v, want 999", input["cardId"])
-		}
-	})
-
-	t.Run("card update dispatches update_card", func(t *testing.T) {
-		caller := withEduAppDispatchCaller(t)
-		cmd := newEduAppCommand()
-		cmd.SetArgs([]string{"card", "update", "--card-id", "77", "--identifier", "org1-staff1-uuid", "--title", "新标题", "--should-send-update-msg"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-app" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-app")
-		}
-		if caller.tool != "update_card" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "update_card")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] type = %T, want map[string]any", caller.args["input"])
-		}
-		if input["cardId"] != int64(77) {
-			t.Fatalf("cardId = %v, want 77", input["cardId"])
-		}
-		if input["identifier"] != "org1-staff1-uuid" {
-			t.Fatalf("identifier = %v, want %q", input["identifier"], "org1-staff1-uuid")
-		}
-		if input["title"] != "新标题" {
-			t.Fatalf("title = %v, want %q", input["title"], "新标题")
-		}
-		if input["shouldSendUpdateMsg"] != true {
-			t.Fatalf("shouldSendUpdateMsg = %v, want true", input["shouldSendUpdateMsg"])
-		}
-	})
-}
-
-// newEduAppConfirmRoot 模拟真实运行时的根命令：核心框架在 rootCmd 上注册
-// 全局 persistent --yes flag，叶子命令通过合并后的 Flags() 读取。
-func newEduAppConfirmRoot() *cobra.Command {
-	root := &cobra.Command{Use: "dws"}
-	root.PersistentFlags().BoolP("yes", "y", false, "跳过确认提示")
-	root.AddCommand(newEduAppCommand())
-	return root
-}
-
-// TestCrossPlatformCoverageEduAppDestructiveConfirmGate 对 edu-app 每个
-// user_required 破坏性叶子做成对验证：
-//   - 未显式确认：返回 confirmation_required 错误，且 caller 调用次数为零。
-//   - 显式确认后：恰好一次 MCP 调用，且 productID、tool、完整参数均准确。
-func TestCrossPlatformCoverageEduAppDestructiveConfirmGate(t *testing.T) {
-	cases := []struct {
-		name      string
-		args      []string
-		wantTool  string
-		wantInput map[string]any
-	}{
-		{
-			"notice delete",
-			[]string{"edu-app", "notice", "delete", "--notice-id", "12345"},
-			"delete_notice",
-			map[string]any{"noticeId": int64(12345)},
-		},
-		{
-			"notice delete with user-name",
-			[]string{"edu-app", "notice", "delete", "--notice-id", "12345", "--user-name", "张三"},
-			"delete_notice",
-			map[string]any{"noticeId": int64(12345), "userName": "张三"},
-		},
-		{
-			"homework delete",
-			[]string{"edu-app", "homework", "delete", "--homework-id", "12345"},
-			"delete_homework",
-			map[string]any{"homeworkId": int64(12345)},
-		},
-		{
-			"diploma delete",
-			[]string{"edu-app", "diploma", "delete", "--diploma-id", "12345"},
-			"delete_diploma",
-			map[string]any{"diplomaId": int64(12345)},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name+"/rejected_without_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduAppConfirmRoot()
-			root.SetArgs(tc.args)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("expected confirm-gate error without --yes, got nil")
-			}
-			if !strings.Contains(err.Error(), "需要用户确认") {
-				t.Fatalf("expected confirmation gate error, got: %v", err)
-			}
-			if len(caller.calls) != 0 {
-				t.Fatalf("caller should not be invoked without --yes, got %d calls", len(caller.calls))
-			}
-		})
-
-		t.Run(tc.name+"/dispatched_with_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduAppConfirmRoot()
-			root.SetArgs(append(append([]string{}, tc.args...), "--yes"))
-			if err := root.Execute(); err != nil {
-				t.Fatalf("Execute() with --yes error = %v", err)
-			}
-			if len(caller.calls) != 1 {
-				t.Fatalf("expected exactly 1 MCP call with --yes, got %d", len(caller.calls))
-			}
-			if caller.calls[0].productID != "edu-app" {
-				t.Errorf("productID = %q, want %q", caller.calls[0].productID, "edu-app")
-			}
-			if caller.calls[0].tool != tc.wantTool {
-				t.Errorf("tool = %q, want %q", caller.calls[0].tool, tc.wantTool)
-			}
-			gotArgs := caller.calls[0].args
-			if len(gotArgs) != 1 {
-				t.Fatalf("args should carry exactly the \"input\" key, got %v", gotArgs)
-			}
-			gotInput, ok := gotArgs["input"].(map[string]any)
-			if !ok {
-				t.Fatalf("args[\"input\"] should be map[string]any, got %T", gotArgs["input"])
-			}
-			if !reflect.DeepEqual(gotInput, tc.wantInput) {
-				t.Errorf("input = %#v, want %#v", gotInput, tc.wantInput)
-			}
-		})
-	}
-}

internal/helpers/edu_contact_test.go

@@ -1,672 +0,0 @@
-package helpers
-
-import (
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-func newTestEduContactRoot() *cobra.Command {
-	return newEduContactCommand()
-}
-
-// ──────────────────────────────────────────────────────────
-// 命令注册测试 — 验证所有子命令路径是否正确注册
-// ──────────────────────────────────────────────────────────
-
-func TestCrossPlatformCoverageEduContactCommandTree(t *testing.T) {
-	root := newTestEduContactRoot()
-
-	paths := [][]string{
-		// school
-		{"school", "roles"},
-		{"school", "structure"},
-		{"school", "periods"},
-		{"school", "type"},
-		{"school", "stats"},
-		{"school", "class-list"},
-		// class — 原有
-		{"class", "detail"},
-		{"class", "students"},
-		{"class", "teachers"},
-		{"class", "same-name"},
-		{"class", "user-role"},
-		{"class", "search-by-name"},
-		{"class", "headmaster"},
-		// class — 新增
-		{"class", "search-by-teacher"},
-		{"class", "add-student"},
-		{"class", "add-teachers"},
-		{"class", "add-unofficial-student"},
-		{"class", "delete-students"},
-		{"class", "delete-teacher"},
-		{"class", "modify-student-info"},
-		{"class", "move-student"},
-		{"class", "update-info"},
-		{"class", "update-student"},
-		{"class", "update-student-mobile"},
-		{"class", "update-student-number"},
-		// family
-		{"family", "children"},
-		{"family", "parents"},
-		// teacher
-		{"teacher", "classes"},
-		{"teacher", "update-course"},
-	}
-
-	for _, path := range paths {
-		if _, _, err := root.Find(path); err != nil {
-			t.Errorf("command path %v not found: %v", path, err)
-		}
-	}
-}
-
-// ──────────────────────────────────────────────────────────
-// 参数校验测试 — 验证必填参数缺失时返回错误
-// ──────────────────────────────────────────────────────────
-
-func executeCommand(root *cobra.Command, args ...string) error {
-	root.SetArgs(args)
-	return root.Execute()
-}
-
-func TestCrossPlatformCoverageClassSearchByTeacher_MissingName(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "search-by-teacher")
-	if err == nil {
-		t.Fatal("expected error for missing --name, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddTeachers_MissingDeptId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-teachers", "--teacher-user-ids", "uid1")
-	if err == nil {
-		t.Fatal("expected error for missing --dept-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddTeachers_MissingTeacherUserIds(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-teachers", "--dept-id", "12345")
-	if err == nil {
-		t.Fatal("expected error for missing --teacher-user-ids, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddTeachers_InvalidIsAdviser(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-teachers", "--dept-id", "12345", "--teacher-user-ids", "uid1", "--is-adviser", "3")
-	if err == nil {
-		t.Fatal("expected error for invalid --is-adviser, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassMoveStudent_MissingOriginClassId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "move-student", "--student-user-ids", "uid1", "--target-class-id", "67890")
-	if err == nil {
-		t.Fatal("expected error for missing --origin-class-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassMoveStudent_MissingStudentUserIds(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "move-student", "--origin-class-id", "12345", "--target-class-id", "67890")
-	if err == nil {
-		t.Fatal("expected error for missing --student-user-ids, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateStudentMobile_MissingMobile(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-student-mobile", "--dept-id", "12345", "--student-user-id", "uid1")
-	if err == nil {
-		t.Fatal("expected error for missing --mobile, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassDeleteStudents_MissingDeptId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "delete-students", "--student-user-ids", "uid1")
-	if err == nil {
-		t.Fatal("expected error for missing --dept-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassDeleteStudents_MissingStudentUserIds(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "delete-students", "--dept-id", "12345")
-	if err == nil {
-		t.Fatal("expected error for missing --student-user-ids, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddUnofficialStudent_MissingDeptId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-unofficial-student", "--student-staff-ids", "sid1")
-	if err == nil {
-		t.Fatal("expected error for missing --dept-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddUnofficialStudent_MissingStaffIds(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-unofficial-student", "--dept-id", "12345")
-	if err == nil {
-		t.Fatal("expected error for missing --student-staff-ids, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateStudent_MissingClassId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-student", "--student-user-id", "uid1", "--student-name", "张三", "--append-patriarch")
-	if err == nil {
-		t.Fatal("expected error for missing --class-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateStudent_MissingStudentUserId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-student", "--class-id", "12345", "--student-name", "张三", "--append-patriarch")
-	if err == nil {
-		t.Fatal("expected error for missing --student-user-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateStudent_InvalidPatriarchsJSON(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-student", "--class-id", "12345", "--student-user-id", "uid1", "--patriarchs", "invalid-json", "--append-patriarch")
-	if err == nil {
-		t.Fatal("expected error for invalid --patriarchs JSON, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateStudentNumber_MissingStudentNumber(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-student-number", "--class-id", "12345", "--student-user-id", "uid1")
-	if err == nil {
-		t.Fatal("expected error for missing --student-number, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateInfo_MissingClassId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-info", "--nick", "火箭班")
-	if err == nil {
-		t.Fatal("expected error for missing --class-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassUpdateInfo_GroupNameWithoutConversationId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "update-info", "--class-id", "12345", "--group-name", "测试群")
-	if err == nil {
-		t.Fatal("expected error for --group-name without --conversation-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassDeleteTeacher_MissingTeacherUserId(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "delete-teacher", "--class-id", "12345")
-	if err == nil {
-		t.Fatal("expected error for missing --teacher-user-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassModifyStudentInfo_MissingBothNickAndPatriarch(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "modify-student-info", "--dept-id", "12345", "--target-user-id", "uid1")
-	if err == nil {
-		t.Fatal("expected error for missing both --nick and --patriarch-user-id, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassModifyStudentInfo_PatriarchWithoutRelation(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "modify-student-info", "--dept-id", "12345", "--target-user-id", "uid1", "--patriarch-user-id", "pid1")
-	if err == nil {
-		t.Fatal("expected error for --patriarch-user-id without --relation, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddStudent_MissingStudentName(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-student", "--dept-id", "12345", "--student-mobile", "13800138000")
-	if err == nil {
-		t.Fatal("expected error for missing --student-name, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddStudent_MissingMobile(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-student", "--dept-id", "12345", "--student-name", "张三")
-	if err == nil {
-		t.Fatal("expected error for missing mobile (student or parent), got nil")
-	}
-}
-
-func TestCrossPlatformCoverageClassAddStudent_InvalidMotherJSON(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "class", "add-student", "--dept-id", "12345", "--student-name", "张三", "--mother", "bad-json")
-	if err == nil {
-		t.Fatal("expected error for invalid --mother JSON, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageTeacherUpdateCourse_MissingTeacherClassInfos(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "teacher", "update-course")
-	if err == nil {
-		t.Fatal("expected error for missing --teacher-class-infos, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageTeacherUpdateCourse_InvalidJSON(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "teacher", "update-course", "--teacher-class-infos", "not-json")
-	if err == nil {
-		t.Fatal("expected error for invalid --teacher-class-infos JSON, got nil")
-	}
-}
-
-func TestCrossPlatformCoverageTeacherUpdateCourse_EmptyArray(t *testing.T) {
-	root := newTestEduContactRoot()
-	err := executeCommand(root, "teacher", "update-course", "--teacher-class-infos", "[]")
-	if err == nil {
-		t.Fatal("expected error for empty --teacher-class-infos array, got nil")
-	}
-}
-
-// ──────────────────────────────────────────────────────────
-// Happy-path 测试 — 每个 leaf 命令的成功分支（经由 dry-run caller）
-// 以及所有可选字段分支，用于把 changed-code 覆盖率补到 100%。
-// ──────────────────────────────────────────────────────────
-
-// withEduContactCaller installs a dry-run capture caller so happy-path command
-// execution exercises each RunE up to the callMCPToolOnServer dispatch without
-// requiring a live MCP transport.
-func withEduContactCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduContactHappyPaths(t *testing.T) {
-	withEduContactCaller(t)
-	cases := [][]string{
-		// school
-		{"school", "roles"},
-		{"school", "structure"},
-		{"school", "periods"},
-		{"school", "type"},
-		{"school", "stats"},
-		{"school", "stats", "--statistics-type", "1"},
-		{"school", "class-list"},
-		// class — 读操作
-		{"class", "detail", "--dept-id", "123"},
-		{"class", "students", "--dept-id", "123"},
-		{"class", "teachers", "--dept-id", "123"},
-		{"class", "same-name", "--dept-id", "123"},
-		{"class", "user-role", "--dept-id", "123"},
-		{"class", "search-by-name", "--query-type", "student", "--name", "张三"},
-		{"class", "headmaster", "--class-name", "一年级1班"},
-		{"class", "search-by-teacher", "--name", "张老师"},
-		// class — update-student 各分支
-		{"class", "update-student", "--class-id", "123", "--student-user-id", "u1",
-			"--student-name", "张三", "--student-number", "S1", "--append-patriarch",
-			"--patriarchs", `[{"userId":"uid1","relation":"F"}]`},
-		{"class", "update-student", "--class-id", "123", "--student-user-id", "u1"},
-		// class — add-student 各手机号来源分支
-		{"class", "add-student", "--dept-id", "123", "--student-name", "张三",
-			"--student-mobile", "13800138000", "--student-user-id", "u1",
-			"--student-number", "S1", "--virtual-account-id", "v1"},
-		{"class", "add-student", "--dept-id", "123", "--student-name", "张三",
-			"--mother", `{"mobile":"13800138000","relation":"M"}`},
-		{"class", "add-student", "--dept-id", "123", "--student-name", "张三",
-			"--father", `{"mobile":"13900139000","relation":"F"}`},
-		{"class", "add-student", "--dept-id", "123", "--student-name", "张三",
-			"--other-patriarchs", `[{"mobile":"13700137000","relation":"O"}]`},
-		// class — modify-student-info 两个分支
-		{"class", "modify-student-info", "--dept-id", "123", "--target-user-id", "u1", "--nick", "张三"},
-		{"class", "modify-student-info", "--dept-id", "123", "--target-user-id", "u1",
-			"--patriarch-user-id", "p1", "--relation", "父亲"},
-		// class — delete-teacher
-		{"class", "delete-teacher", "--class-id", "123", "--teacher-user-id", "u1"},
-		// class — update-info 三个可选分支
-		{"class", "update-info", "--class-id", "123", "--nick", "火箭班"},
-		{"class", "update-info", "--class-id", "123", "--expected-student-num", "45"},
-		{"class", "update-info", "--class-id", "123", "--group-name", "家长群", "--conversation-id", "cid1"},
-		// class — update-student-number
-		{"class", "update-student-number", "--class-id", "123", "--student-user-id", "u1", "--student-number", "S1"},
-		// class — add-unofficial-student
-		{"class", "add-unofficial-student", "--dept-id", "123", "--student-staff-ids", "s1,s2"},
-		// class — delete-students
-		{"class", "delete-students", "--dept-id", "123", "--student-user-ids", "u1,u2"},
-		// class — update-student-mobile
-		{"class", "update-student-mobile", "--dept-id", "123", "--student-user-id", "u1", "--mobile", "13800138000"},
-		// class — move-student
-		{"class", "move-student", "--student-user-ids", "u1,u2", "--origin-class-id", "123", "--target-class-id", "456"},
-		// class — add-teachers 默认/班主任
-		{"class", "add-teachers", "--dept-id", "123", "--teacher-user-ids", "u1,u2"},
-		{"class", "add-teachers", "--dept-id", "123", "--teacher-user-ids", "u1", "--is-adviser", "1"},
-		// family
-		{"family", "children"},
-		{"family", "parents"},
-		// teacher
-		{"teacher", "classes"},
-		{"teacher", "update-course", "--teacher-class-infos", `[{"classId":123,"courseCode":"c1","courseName":"语文"}]`},
-	}
-	for _, args := range cases {
-		root := newTestEduContactRoot()
-		if err := executeCommand(root, args...); err != nil {
-			t.Errorf("happy path %v returned error: %v", args, err)
-		}
-	}
-}
-
-// TestEduContactErrorPathsRemaining covers validation branches not exercised by
-// the existing error tests, ensuring 100% changed-code coverage.
-func TestCrossPlatformCoverageEduContactErrorPathsRemaining(t *testing.T) {
-	cases := []struct {
-		name string
-		args []string
-	}{
-		// eduRequiredIntFlag：空值 + 非整数
-		{"stats-invalid-type", []string{"school", "stats", "--statistics-type", "abc"}},
-		{"detail-missing-dept", []string{"class", "detail"}},
-		{"detail-invalid-dept", []string{"class", "detail", "--dept-id", "abc"}},
-		{"students-missing-dept", []string{"class", "students"}},
-		{"teachers-missing-dept", []string{"class", "teachers"}},
-		{"samename-missing-dept", []string{"class", "same-name"}},
-		{"userrole-missing-dept", []string{"class", "user-role"}},
-		{"searchbyname-missing-querytype", []string{"class", "search-by-name", "--name", "张三"}},
-		{"searchbyname-missing-name", []string{"class", "search-by-name", "--query-type", "student"}},
-		{"headmaster-missing-classname", []string{"class", "headmaster"}},
-		// update-student
-		{"updatestudent-missing-classid", []string{"class", "update-student", "--student-user-id", "u1"}},
-		{"updatestudent-missing-userid", []string{"class", "update-student", "--class-id", "123"}},
-		{"updatestudent-invalid-patriarchs", []string{"class", "update-student", "--class-id", "123", "--student-user-id", "u1", "--patriarchs", "not-json"}},
-		// add-student
-		{"addstudent-missing-dept", []string{"class", "add-student", "--student-name", "张三"}},
-		{"addstudent-missing-name", []string{"class", "add-student", "--dept-id", "123"}},
-		{"addstudent-invalid-father", []string{"class", "add-student", "--dept-id", "123", "--student-name", "张三", "--father", "not-json"}},
-		{"addstudent-invalid-other", []string{"class", "add-student", "--dept-id", "123", "--student-name", "张三", "--other-patriarchs", "not-json"}},
-		{"addstudent-no-mobile", []string{"class", "add-student", "--dept-id", "123", "--student-name", "张三"}},
-		// modify-student-info
-		{"modify-missing-dept", []string{"class", "modify-student-info", "--target-user-id", "u1", "--nick", "张三"}},
-		{"modify-missing-target", []string{"class", "modify-student-info", "--dept-id", "123", "--nick", "张三"}},
-		// delete-teacher
-		{"deleteteacher-missing-classid", []string{"class", "delete-teacher", "--teacher-user-id", "u1"}},
-		// update-info
-		{"updateinfo-missing-classid", []string{"class", "update-info", "--nick", "火箭班"}},
-		{"updateinfo-invalid-expected", []string{"class", "update-info", "--class-id", "123", "--expected-student-num", "abc"}},
-		// update-student-number
-		{"usn-missing-classid", []string{"class", "update-student-number", "--student-user-id", "u1", "--student-number", "S1"}},
-		{"usn-missing-userid", []string{"class", "update-student-number", "--class-id", "123", "--student-number", "S1"}},
-		// add-unofficial-student
-		{"unofficial-missing-dept", []string{"class", "add-unofficial-student", "--student-staff-ids", "s1"}},
-		{"unofficial-empty-staffids", []string{"class", "add-unofficial-student", "--dept-id", "123", "--student-staff-ids", ",,"}},
-		// delete-students
-		{"deletestudents-missing-userids", []string{"class", "delete-students", "--dept-id", "123"}},
-		{"deletestudents-empty-userids", []string{"class", "delete-students", "--dept-id", "123", "--student-user-ids", ",,"}},
-		// update-student-mobile
-		{"usm-missing-dept", []string{"class", "update-student-mobile", "--student-user-id", "u1", "--mobile", "13800138000"}},
-		{"usm-missing-userid", []string{"class", "update-student-mobile", "--dept-id", "123", "--mobile", "13800138000"}},
-		// move-student
-		{"move-missing-target", []string{"class", "move-student", "--student-user-ids", "u1", "--origin-class-id", "123"}},
-		{"move-empty-userids", []string{"class", "move-student", "--origin-class-id", "123", "--target-class-id", "456", "--student-user-ids", ",,"}},
-		// add-teachers
-		{"addteachers-empty-userids", []string{"class", "add-teachers", "--dept-id", "123", "--teacher-user-ids", ",,"}},
-		{"addteachers-too-many", []string{"class", "add-teachers", "--dept-id", "123", "--teacher-user-ids", strings.Repeat("u,", 51) + "u"}},
-	}
-	for _, tc := range cases {
-		root := newTestEduContactRoot()
-		if err := executeCommand(root, tc.args...); err == nil {
-			t.Errorf("%s: expected error, got nil", tc.name)
-		}
-	}
-}
-
-// ──────────────────────────────────────────────────────────
-// Dispatch 验证测试 — 验证命令正确派发到 MCP Server
-// ──────────────────────────────────────────────────────────
-
-// withEduContactDispatchCaller installs a non-dry-run capture caller so that
-// callMCPToolOnServer goes through deps.Caller.CallTool and we can verify
-// the dispatched productID, tool name, and args.
-func withEduContactDispatchCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduContactDispatch(t *testing.T) {
-	t.Run("class detail dispatches get_class_detail with deptId", func(t *testing.T) {
-		caller := withEduContactDispatchCaller(t)
-		root := newEduContactCommand()
-		root.SetArgs([]string{"class", "detail", "--dept-id", "123"})
-		if err := root.Execute(); err != nil {
-			t.Fatal(err)
-		}
-		if caller.productID != "edu-contact" {
-			t.Errorf("productID = %q, want %q", caller.productID, "edu-contact")
-		}
-		if caller.tool != "get_class_detail" {
-			t.Errorf("tool = %q, want %q", caller.tool, "get_class_detail")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] is not map[string]any: %#v", caller.args)
-		}
-		if input["deptId"] != int64(123) {
-			t.Errorf("input[deptId] = %v (%T), want int64(123)", input["deptId"], input["deptId"])
-		}
-	})
-
-	t.Run("class search-by-name dispatches query_class_by_guardian_name", func(t *testing.T) {
-		caller := withEduContactDispatchCaller(t)
-		root := newEduContactCommand()
-		root.SetArgs([]string{"class", "search-by-name", "--query-type", "student", "--name", "张三"})
-		if err := root.Execute(); err != nil {
-			t.Fatal(err)
-		}
-		if caller.productID != "edu-contact" {
-			t.Errorf("productID = %q, want %q", caller.productID, "edu-contact")
-		}
-		if caller.tool != "query_class_by_guardian_name" {
-			t.Errorf("tool = %q, want %q", caller.tool, "query_class_by_guardian_name")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] is not map[string]any: %#v", caller.args)
-		}
-		if input["queryType"] != "student" {
-			t.Errorf("input[queryType] = %v, want %q", input["queryType"], "student")
-		}
-		if input["name"] != "张三" {
-			t.Errorf("input[name] = %v, want %q", input["name"], "张三")
-		}
-	})
-
-	t.Run("school stats dispatches statistics_school with statisticsType", func(t *testing.T) {
-		caller := withEduContactDispatchCaller(t)
-		root := newEduContactCommand()
-		root.SetArgs([]string{"school", "stats", "--statistics-type", "2"})
-		if err := root.Execute(); err != nil {
-			t.Fatal(err)
-		}
-		if caller.productID != "edu-contact" {
-			t.Errorf("productID = %q, want %q", caller.productID, "edu-contact")
-		}
-		if caller.tool != "statistics_school" {
-			t.Errorf("tool = %q, want %q", caller.tool, "statistics_school")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] is not map[string]any: %#v", caller.args)
-		}
-		if input["statisticsType"] != int64(2) {
-			t.Errorf("input[statisticsType] = %v (%T), want int64(2)", input["statisticsType"], input["statisticsType"])
-		}
-	})
-
-	t.Run("class add-teachers dispatches batch_add_class_teacher with list and isAdviser", func(t *testing.T) {
-		caller := withEduContactDispatchCaller(t)
-		root := newEduContactCommand()
-		root.SetArgs([]string{"class", "add-teachers", "--dept-id", "789", "--teacher-user-ids", "t1,t2", "--is-adviser", "1"})
-		if err := root.Execute(); err != nil {
-			t.Fatal(err)
-		}
-		if caller.productID != "edu-contact" {
-			t.Errorf("productID = %q, want %q", caller.productID, "edu-contact")
-		}
-		if caller.tool != "batch_add_class_teacher" {
-			t.Errorf("tool = %q, want %q", caller.tool, "batch_add_class_teacher")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] is not map[string]any: %#v", caller.args)
-		}
-		if input["deptId"] != int64(789) {
-			t.Errorf("input[deptId] = %v (%T), want int64(789)", input["deptId"], input["deptId"])
-		}
-		teacherUserIds, ok := input["teacherUserIds"].([]string)
-		if !ok {
-			t.Fatalf("input[teacherUserIds] is not []string: %#v", input["teacherUserIds"])
-		}
-		if len(teacherUserIds) != 2 || teacherUserIds[0] != "t1" || teacherUserIds[1] != "t2" {
-			t.Errorf("input[teacherUserIds] = %v, want [t1 t2]", teacherUserIds)
-		}
-		if input["isAdviser"] != int64(1) {
-			t.Errorf("input[isAdviser] = %v (%T), want int64(1)", input["isAdviser"], input["isAdviser"])
-		}
-	})
-
-	t.Run("class move-student dispatches move_student with list and two int flags", func(t *testing.T) {
-		caller := withEduContactDispatchCaller(t)
-		root := newEduContactCommand()
-		root.SetArgs([]string{"class", "move-student", "--student-user-ids", "u1,u2", "--origin-class-id", "100", "--target-class-id", "200"})
-		if err := root.Execute(); err != nil {
-			t.Fatal(err)
-		}
-		if caller.productID != "edu-contact" {
-			t.Errorf("productID = %q, want %q", caller.productID, "edu-contact")
-		}
-		if caller.tool != "move_student" {
-			t.Errorf("tool = %q, want %q", caller.tool, "move_student")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] is not map[string]any: %#v", caller.args)
-		}
-		studentUserIds, ok := input["studentUserIds"].([]string)
-		if !ok {
-			t.Fatalf("input[studentUserIds] is not []string: %#v", input["studentUserIds"])
-		}
-		if len(studentUserIds) != 2 || studentUserIds[0] != "u1" || studentUserIds[1] != "u2" {
-			t.Errorf("input[studentUserIds] = %v, want [u1 u2]", studentUserIds)
-		}
-		if input["originClassId"] != int64(100) {
-			t.Errorf("input[originClassId] = %v (%T), want int64(100)", input["originClassId"], input["originClassId"])
-		}
-		if input["targetClassId"] != int64(200) {
-			t.Errorf("input[targetClassId] = %v (%T), want int64(200)", input["targetClassId"], input["targetClassId"])
-		}
-	})
-}
-
-// newEduContactConfirmRoot 模拟真实运行时的根命令：核心框架在 rootCmd 上注册
-// 全局 persistent --yes flag，叶子命令通过合并后的 Flags() 读取。
-func newEduContactConfirmRoot() *cobra.Command {
-	root := &cobra.Command{Use: "dws"}
-	root.PersistentFlags().BoolP("yes", "y", false, "跳过确认提示")
-	root.AddCommand(newEduContactCommand())
-	return root
-}
-
-// TestCrossPlatformCoverageEduContactDestructiveConfirmGate 对 edu-contact 每个
-// user_required 破坏性叶子做成对验证：
-//   - 未显式确认：返回 confirmation_required 错误，且 caller 调用次数为零。
-//   - 显式确认后：恰好一次 MCP 调用，且 productID、tool、完整参数均准确。
-func TestCrossPlatformCoverageEduContactDestructiveConfirmGate(t *testing.T) {
-	cases := []struct {
-		name      string
-		args      []string
-		wantTool  string
-		wantInput map[string]any
-	}{
-		{
-			"class delete-teacher",
-			[]string{"edu-contact", "class", "delete-teacher", "--class-id", "12345", "--teacher-user-id", "userId1"},
-			"delete_teacher",
-			map[string]any{"classId": int64(12345), "teacherUserId": "userId1"},
-		},
-		{
-			"class delete-students",
-			[]string{"edu-contact", "class", "delete-students", "--dept-id", "12345", "--student-user-ids", "userId1,userId2"},
-			"delete_students",
-			map[string]any{"deptId": int64(12345), "studentUserIds": []string{"userId1", "userId2"}},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name+"/rejected_without_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduContactConfirmRoot()
-			root.SetArgs(tc.args)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("expected confirm-gate error without --yes, got nil")
-			}
-			if !strings.Contains(err.Error(), "需要用户确认") {
-				t.Fatalf("expected confirmation gate error, got: %v", err)
-			}
-			if len(caller.calls) != 0 {
-				t.Fatalf("caller should not be invoked without --yes, got %d calls", len(caller.calls))
-			}
-		})
-
-		t.Run(tc.name+"/dispatched_with_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduContactConfirmRoot()
-			root.SetArgs(append(append([]string{}, tc.args...), "--yes"))
-			if err := root.Execute(); err != nil {
-				t.Fatalf("Execute() with --yes error = %v", err)
-			}
-			if len(caller.calls) != 1 {
-				t.Fatalf("expected exactly 1 MCP call with --yes, got %d", len(caller.calls))
-			}
-			if caller.calls[0].productID != "edu-contact" {
-				t.Errorf("productID = %q, want %q", caller.calls[0].productID, "edu-contact")
-			}
-			if caller.calls[0].tool != tc.wantTool {
-				t.Errorf("tool = %q, want %q", caller.calls[0].tool, tc.wantTool)
-			}
-			gotArgs := caller.calls[0].args
-			if len(gotArgs) != 1 {
-				t.Fatalf("args should carry exactly the \"input\" key, got %v", gotArgs)
-			}
-			gotInput, ok := gotArgs["input"].(map[string]any)
-			if !ok {
-				t.Fatalf("args[\"input\"] should be map[string]any, got %T", gotArgs["input"])
-			}
-			if !reflect.DeepEqual(gotInput, tc.wantInput) {
-				t.Errorf("input = %#v, want %#v", gotInput, tc.wantInput)
-			}
-		})
-	}
-}

internal/helpers/edu_family_group.go

@@ -1,605 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"encoding/json"
-	"fmt"
-	"strconv"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
-)
-
-// ──────────────────────────────────────────────────────────
-// dws edu-familygroup — 家庭群管理
-// 共 6 个工具，按 group（读操作）/ manage（写操作）分组
-// 参考 wukong/extensions/vendors/dingtalk/eduFamilyGroup.go 迁移
-// ──────────────────────────────────────────────────────────
-
-func newEduFamilyGroupCommand() *cobra.Command {
-	contract.RegisterProductDecl(contract.ProductDecl{
-		ID: "edu-familygroup",
-		Selection: contract.ProductSelectionDecl{
-			AgentSummary: "家庭群查询/创建、孩子管理、家长邀请、学生应用权限控制",
-			UseWhen: []string{
-				"用户要查询或管理钉钉家庭群、添加孩子、邀请家长或控制学生应用权限。",
-			},
-			AvoidWhen: []string{
-				"家校通讯录用 edu-contact；班级师生群用 edu-group；家校应用/作业/打卡用 edu-app。",
-			},
-		},
-	})
-	root := &cobra.Command{
-		Use:    "edu-familygroup",
-		Short:  "家庭群",
-		Long:   `钉钉家庭群管理：家庭群查询/创建、孩子管理、家长邀请、学生应用权限控制等。`,
-		Hidden: true,
-		RunE:   groupRunE,
-	}
-
-	// ════════════════════════════════════════════════════════════
-	// group 子命令组 — 家庭群读操作
-	// ════════════════════════════════════════════════════════════
-
-	groupCmd := &cobra.Command{Use: "group", Short: "家庭群查询", RunE: groupRunE}
-
-	groupCheckExistsCmd := &cobra.Command{
-		Use:   "check-exists",
-		Short: "检查家庭群是否存在",
-		Long: `根据传入的 uid 拉取该用户所有家庭组织，按家庭群名称匹配判断家庭群是否存在。
-仅当存在同名家庭且其群会话 cid 非空时，才认为家庭群存在，返回 true，否则返回 false。
-面向家长（GUARDIAN）角色。`,
-		Example: `  dws edu-familygroup group check-exists --uid 12345 --group-name "小明一家"
-  dws edu-familygroup group check-exists --uid 12345 --group-name "小明一家" -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			groupName, err := eduFamilyGroupRequiredStringFlag(cmd, "group-name")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-familygroup", "check_family_group_exists", map[string]any{
-				"input": map[string]any{"uid": uid, "groupName": groupName},
-			})
-		},
-	}
-	DeclareLeafMetadata(groupCheckExistsCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "check_family_group_exists",
-				CanonicalPath:  "edu-familygroup.check_family_group_exists",
-				CLIPath:        "edu-familygroup group check-exists",
-				PrimaryCLIPath: "edu-familygroup group check-exists",
-			},
-			Description: "检查家庭群是否存在",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "check_family_group_exists"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "检查家庭群是否存在",
-				UseWhen:      []string{"需要判断指定用户名下是否存在同名家庭群时"},
-				AvoidWhen:    []string{"查询家庭成员信息用 list-children"},
-				Examples: []string{
-					"dws edu-familygroup group check-exists --uid 12345 --group-name \"小明一家\" --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-				{Name: "group-name", Property: "input.groupName", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	groupListChildrenCmd := &cobra.Command{
-		Use:   "list-children",
-		Short: "查询家长绑定的孩子列表",
-		Long: `查询当前用户（uid）作为家长身份所在家庭中的所有孩子信息（不限家庭组织），
-包含孩子基本信息及关联的学生号列表。底层按 uid 读扩散并完成家长身份校验，无孩子时返回空列表。
-面向家长（GUARDIAN）角色。`,
-		Example: `  dws edu-familygroup group list-children --uid 12345
-  dws edu-familygroup group list-children --uid 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-familygroup", "listBoundChildren", map[string]any{
-				"input": map[string]any{"uid": uid},
-			})
-		},
-	}
-	DeclareLeafMetadata(groupListChildrenCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "listBoundChildren",
-				CanonicalPath:  "edu-familygroup.listBoundChildren",
-				CLIPath:        "edu-familygroup group list-children",
-				PrimaryCLIPath: "edu-familygroup group list-children",
-			},
-			Description: "查询家长绑定的孩子列表",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "listBoundChildren"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "查询家长绑定的孩子列表",
-				UseWhen:      []string{"需要查询指定家长 uid 绑定的所有孩子及关联学生号信息时"},
-				AvoidWhen:    []string{"查看家庭群是否存在用 check-exists"},
-				Examples: []string{
-					"dws edu-familygroup group list-children --uid 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	// ════════════════════════════════════════════════════════════
-	// manage 子命令组 — 家庭群写操作
-	// ════════════════════════════════════════════════════════════
-
-	manageCmd := &cobra.Command{Use: "manage", Short: "家庭群管理", RunE: groupRunE}
-
-	manageCreateCmd := &cobra.Command{
-		Use:   "create",
-		Short: "创建家庭群",
-		Long: `以 uid 作为创建人创建一个新的家庭，创建家庭时会同时创建家庭群，返回结果中携带群会话 cid。
-children 为 JSON 数组，每个元素包含 name（必填）、students（必填，含 corpId + staffId）、
-birthday / gender / nick / avatar / period / grade / mobile（均可选）。
-addGroup 为 JSON 对象，含 schoolCorpId / schoolStaffId / inviteDingtalkId / inviteId（均可选）。
-新建家庭场景下无需前置家长身份校验，创建人合法性由底层校验单元完成。`,
-		Example: `  dws edu-familygroup manage create --uid 12345 --children '[{"name":"小明","students":[{"corpId":"dingxxx","staffId":"stu001"}]}]'
-  dws edu-familygroup manage create --uid 12345 --children '[{"name":"小明","students":[{"corpId":"dingxxx","staffId":"stu001"}]}]' --source 1`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			childrenRaw, _ := cmd.Flags().GetString("children")
-			if strings.TrimSpace(childrenRaw) == "" {
-				return fmt.Errorf("--children 为必填参数")
-			}
-			var children []any
-			if err := json.Unmarshal([]byte(childrenRaw), &children); err != nil {
-				return fmt.Errorf("--children 须为合法 JSON 数组: %w", err)
-			}
-			if err := eduFamilyGroupValidateChildren(children); err != nil {
-				return err
-			}
-			input := map[string]any{"uid": uid, "children": children}
-			if v, _ := cmd.Flags().GetString("add-group"); strings.TrimSpace(v) != "" {
-				var addGroup map[string]any
-				if err := json.Unmarshal([]byte(v), &addGroup); err != nil {
-					return fmt.Errorf("--add-group 须为合法 JSON 对象: %w", err)
-				}
-				if addGroup == nil {
-					return fmt.Errorf("--add-group 须为 JSON 对象，不能为 null")
-				}
-				input["addGroup"] = addGroup
-			}
-			if v, _ := cmd.Flags().GetInt("source"); cmd.Flags().Changed("source") {
-				input["source"] = v
-			}
-			return callMCPToolOnServer("edu-familygroup", "create_family_group", map[string]any{
-				"input": input,
-			})
-		},
-	}
-	DeclareLeafMetadata(manageCreateCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "medium",
-			Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "create_family_group",
-				CanonicalPath:  "edu-familygroup.create_family_group",
-				CLIPath:        "edu-familygroup manage create",
-				PrimaryCLIPath: "edu-familygroup manage create",
-			},
-			Description: "创建家庭群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "create_family_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "创建家庭群并同步创建家庭组织",
-				UseWhen:      []string{"需要以指定 uid 创建新的家庭群，同时注册孩子信息并生成群会话时"},
-				AvoidWhen:    []string{"已有家庭群要加孩子用 add-child"},
-				Examples: []string{
-					"dws edu-familygroup manage create --uid 12345 --children '[{\"name\":\"小明\",\"students\":[{\"corpId\":\"dingxxx\",\"staffId\":\"stu001\"}]}]' --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-				{Name: "children", Property: "input.children", Required: boolPtr(true)},
-				{Name: "add-group", Property: "input.addGroup"},
-				{Name: "source", Property: "input.source"},
-			},
-		},
-	})
-
-	manageInviteParentCmd := &cobra.Command{
-		Use:   "invite-parent",
-		Short: "短信邀请家长加入家庭群",
-		Long: `通过短信向指定手机号的家长发送家庭群邀请链接，家长点击链接后加入当前家庭组织及家庭群。
-返回 true 表示邀请短信已成功发送。仅家长（GUARDIAN）角色可调用。`,
-		Example: `  dws edu-familygroup manage invite-parent --org-id 12345 --uid 67890 --mobile 13800138000
-  dws edu-familygroup manage invite-parent --org-id 12345 --uid 67890 --mobile 13800138000 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			orgID, err := eduFamilyGroupRequiredIntFlag(cmd, "org-id")
-			if err != nil {
-				return err
-			}
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			mobile, err := eduFamilyGroupRequiredStringFlag(cmd, "mobile")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-familygroup", "invite_parent_to_familygroup", map[string]any{
-				"input": map[string]any{"orgId": orgID, "uid": uid, "mobile": mobile},
-			})
-		},
-	}
-	DeclareLeafMetadata(manageInviteParentCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "medium",
-			Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "invite_parent_to_familygroup",
-				CanonicalPath:  "edu-familygroup.invite_parent_to_familygroup",
-				CLIPath:        "edu-familygroup manage invite-parent",
-				PrimaryCLIPath: "edu-familygroup manage invite-parent",
-			},
-			Description: "短信邀请家长加入家庭群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "invite_parent_to_familygroup"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "通过短信邀请家长加入家庭群",
-				UseWhen:      []string{"需要向指定手机号发送家庭群邀请短信时"},
-				AvoidWhen:    []string{"添加孩子到家庭群用 add-child"},
-				Examples: []string{
-					"dws edu-familygroup manage invite-parent --org-id 12345 --uid 67890 --mobile 13800138000 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "org-id", Property: "input.orgId", Required: boolPtr(true)},
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-				{Name: "mobile", Property: "input.mobile", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	manageAddChildCmd := &cobra.Command{
-		Use:   "add-child",
-		Short: "为家庭群添加孩子",
-		Long: `为指定家庭群添加孩子，支持三种方式（由底层自动路由）：
-  - 仅传 --mobile：手机号邀请链路，该手机号对应的钉钉账号被邀请加入家庭群
-  - 仅传 --students：直接生成学生号链路，选中学生后创建孩子并绑定关系
-  - 同时传 --mobile + --students：mobile 优先，走手机号邀请链路
-mobile 与 students 至少传一个。
-students 为 JSON 数组，每个元素含 schoolOrgId（整数）和 studentStaffId（字符串），均必填。
-仅家长（GUARDIAN）角色可调用。`,
-		Example: `  dws edu-familygroup manage add-child --org-id 12345 --uid 67890 --name 小明 --mobile 13900139000
-  dws edu-familygroup manage add-child --org-id 12345 --uid 67890 --name 小明 --students '[{"schoolOrgId":111,"studentStaffId":"stu001"}]'`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			orgID, err := eduFamilyGroupRequiredIntFlag(cmd, "org-id")
-			if err != nil {
-				return err
-			}
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			name, err := eduFamilyGroupRequiredStringFlag(cmd, "name")
-			if err != nil {
-				return err
-			}
-			mobile, _ := cmd.Flags().GetString("mobile")
-			mobile = strings.TrimSpace(mobile)
-			studentsRaw, _ := cmd.Flags().GetString("students")
-			studentsRaw = strings.TrimSpace(studentsRaw)
-			if mobile == "" && studentsRaw == "" {
-				return fmt.Errorf("--mobile 与 --students 至少传一个")
-			}
-			input := map[string]any{"orgId": orgID, "uid": uid, "name": name}
-			if mobile != "" {
-				input["mobile"] = mobile
-			}
-			if studentsRaw != "" {
-				var students []any
-				if err := json.Unmarshal([]byte(studentsRaw), &students); err != nil {
-					return fmt.Errorf("--students 须为合法 JSON 数组: %w", err)
-				}
-				if err := eduFamilyGroupValidateStudents(students); err != nil {
-					return err
-				}
-				input["students"] = students
-			}
-			return callMCPToolOnServer("edu-familygroup", "add_child_to_family_group", map[string]any{
-				"input": input,
-			})
-		},
-	}
-	DeclareLeafMetadata(manageAddChildCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "medium",
-			Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "add_child_to_family_group",
-				CanonicalPath:  "edu-familygroup.add_child_to_family_group",
-				CLIPath:        "edu-familygroup manage add-child",
-				PrimaryCLIPath: "edu-familygroup manage add-child",
-			},
-			Description: "为家庭群添加孩子",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "add_child_to_family_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "为已有家庭群添加孩子",
-				UseWhen:      []string{"需要向已有家庭群添加新孩子（通过手机号邀请或直接绑定学生号）时"},
-				AvoidWhen:    []string{"创建全新家庭群用 create"},
-				Examples: []string{
-					"dws edu-familygroup manage add-child --org-id 12345 --uid 67890 --name 小明 --mobile 13900139000 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "org-id", Property: "input.orgId", Required: boolPtr(true)},
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-				{Name: "name", Property: "input.name", Required: boolPtr(true)},
-				{Name: "mobile", Property: "input.mobile"},
-				{Name: "students", Property: "input.students"},
-			},
-		},
-	})
-
-	manageToggleAppCmd := &cobra.Command{
-		Use:   "toggle-app",
-		Short: "开启或关闭学生应用权限",
-		Long: `为指定学生号开启或关闭应用权限。
-支持的应用类型（--app-type）：
-  - XIAOTIANDI：小天地（学生圈）
-  - LEARNING_VIDEO：学习视频
-直接覆写权限状态，天然幂等。仅家长（GUARDIAN）角色可调用。`,
-		Example: `  dws edu-familygroup manage toggle-app --org-id 12345 --uid 67890 --child-staff-id staff001 --app-type XIAOTIANDI --open true
-  dws edu-familygroup manage toggle-app --org-id 12345 --uid 67890 --child-staff-id staff001 --app-type LEARNING_VIDEO --open false`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			orgID, err := eduFamilyGroupRequiredIntFlag(cmd, "org-id")
-			if err != nil {
-				return err
-			}
-			uid, err := eduFamilyGroupRequiredIntFlag(cmd, "uid")
-			if err != nil {
-				return err
-			}
-			childStaffID, err := eduFamilyGroupRequiredStringFlag(cmd, "child-staff-id")
-			if err != nil {
-				return err
-			}
-			appType, err := eduFamilyGroupRequiredStringFlag(cmd, "app-type")
-			if err != nil {
-				return err
-			}
-			if appType != "XIAOTIANDI" && appType != "LEARNING_VIDEO" {
-				return fmt.Errorf("--app-type 须为 XIAOTIANDI 或 LEARNING_VIDEO")
-			}
-			openStr, err := eduFamilyGroupRequiredStringFlag(cmd, "open")
-			if err != nil {
-				return err
-			}
-			var open bool
-			switch strings.ToLower(openStr) {
-			case "true":
-				open = true
-			case "false":
-				open = false
-			default:
-				return fmt.Errorf("--open 须为 true 或 false")
-			}
-			return callMCPToolOnServer("edu-familygroup", "toggle_student_app", map[string]any{
-				"input": map[string]any{
-					"orgId": orgID, "uid": uid, "childStaffId": childStaffID,
-					"appType": appType, "open": open,
-				},
-			})
-		},
-	}
-	DeclareLeafMetadata(manageToggleAppCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-familygroup",
-				Name:           "toggle_student_app",
-				CanonicalPath:  "edu-familygroup.toggle_student_app",
-				CLIPath:        "edu-familygroup manage toggle-app",
-				PrimaryCLIPath: "edu-familygroup manage toggle-app",
-			},
-			Description: "开启或关闭学生应用权限",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-familygroup", RPCName: "toggle_student_app"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "开启或关闭学生应用权限",
-				UseWhen:      []string{"需要为指定学生号开启或关闭小天地/学习视频应用权限时"},
-				AvoidWhen:    []string{"管理家庭群成员用 add-child / invite-parent"},
-				Examples: []string{
-					"dws edu-familygroup manage toggle-app --org-id 12345 --uid 67890 --child-staff-id staff001 --app-type XIAOTIANDI --open true --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "org-id", Property: "input.orgId", Required: boolPtr(true)},
-				{Name: "uid", Property: "input.uid", Required: boolPtr(true)},
-				{Name: "child-staff-id", Property: "input.childStaffId", Required: boolPtr(true)},
-				{Name: "app-type", Property: "input.appType", Required: boolPtr(true)},
-				{Name: "open", Property: "input.open", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	// ════════════════════════════════════════════════════════════
-	// flags + 构建命令树
-	// ════════════════════════════════════════════════════════════
-
-	// group（读操作）flags
-	groupCheckExistsCmd.Flags().String("uid", "", "用户 uid（必填）")
-	groupCheckExistsCmd.Flags().String("group-name", "", "家庭群名称（必填）")
-	groupListChildrenCmd.Flags().String("uid", "", "家长 uid（必填）")
-
-	// manage（写操作）flags
-	manageCreateCmd.Flags().String("uid", "", "创建人 uid（必填）")
-	manageCreateCmd.Flags().String("children", "", "孩子信息 JSON 数组（必填）")
-	manageCreateCmd.Flags().String("add-group", "", "同学群信息 JSON 对象（可选）")
-	manageCreateCmd.Flags().Int("source", 0, "渠道来源（可选）")
-
-	manageInviteParentCmd.Flags().String("org-id", "", "家庭组织 ID（必填）")
-	manageInviteParentCmd.Flags().String("uid", "", "操作人 uid（必填）")
-	manageInviteParentCmd.Flags().String("mobile", "", "被邀请家长手机号（必填）")
-
-	manageAddChildCmd.Flags().String("org-id", "", "家庭组织 ID（必填）")
-	manageAddChildCmd.Flags().String("uid", "", "操作人 uid（必填）")
-	manageAddChildCmd.Flags().String("name", "", "孩子姓名（必填）")
-	manageAddChildCmd.Flags().String("mobile", "", "孩子手机号（可选，与 --students 至少传一个）")
-	manageAddChildCmd.Flags().String("students", "", "待关联学生号 JSON 数组（可选，每项含 schoolOrgId + studentStaffId）")
-
-	manageToggleAppCmd.Flags().String("org-id", "", "家庭组织 ID（必填）")
-	manageToggleAppCmd.Flags().String("uid", "", "家长 uid（必填）")
-	manageToggleAppCmd.Flags().String("child-staff-id", "", "孩子在家庭组织中的 staffId（必填）")
-	manageToggleAppCmd.Flags().String("app-type", "", "应用类型：XIAOTIANDI / LEARNING_VIDEO（必填）")
-	manageToggleAppCmd.Flags().String("open", "", "true=开启 / false=关闭（必填）")
-
-	groupCmd.AddCommand(groupCheckExistsCmd, groupListChildrenCmd)
-	manageCmd.AddCommand(manageCreateCmd, manageInviteParentCmd, manageAddChildCmd, manageToggleAppCmd)
-
-	root.AddCommand(groupCmd, manageCmd)
-
-	return root
-}
-
-// eduFamilyGroupValidateChildren validates the --children payload: the array
-// must be non-empty, each child must carry a non-empty name and a non-empty
-// students array, and each student must carry corpId + staffId.
-func eduFamilyGroupValidateChildren(children []any) error {
-	if len(children) == 0 {
-		return fmt.Errorf("--children 不能为空数组，至少需包含一个孩子")
-	}
-	for i, c := range children {
-		child, ok := c.(map[string]any)
-		if !ok {
-			return fmt.Errorf("--children[%d] 须为 JSON 对象", i)
-		}
-		name, _ := child["name"].(string)
-		if strings.TrimSpace(name) == "" {
-			return fmt.Errorf("--children[%d].name 为必填字段", i)
-		}
-		students, ok := child["students"].([]any)
-		if !ok || len(students) == 0 {
-			return fmt.Errorf("--children[%d].students 为必填字段且不能为空数组", i)
-		}
-		for j, s := range students {
-			student, ok := s.(map[string]any)
-			if !ok {
-				return fmt.Errorf("--children[%d].students[%d] 须为 JSON 对象", i, j)
-			}
-			corpID, _ := student["corpId"].(string)
-			if strings.TrimSpace(corpID) == "" {
-				return fmt.Errorf("--children[%d].students[%d].corpId 为必填字段", i, j)
-			}
-			staffID, _ := student["staffId"].(string)
-			if strings.TrimSpace(staffID) == "" {
-				return fmt.Errorf("--children[%d].students[%d].staffId 为必填字段", i, j)
-			}
-		}
-	}
-	return nil
-}
-
-// eduFamilyGroupValidateStudents validates the --students payload: the array
-// must be non-empty and each element must carry a numeric schoolOrgId and a
-// non-empty studentStaffId.
-func eduFamilyGroupValidateStudents(students []any) error {
-	if len(students) == 0 {
-		return fmt.Errorf("--students 不能为空数组，至少需包含一个学生号")
-	}
-	for i, s := range students {
-		student, ok := s.(map[string]any)
-		if !ok {
-			return fmt.Errorf("--students[%d] 须为 JSON 对象", i)
-		}
-		switch student["schoolOrgId"].(type) {
-		case float64, int, int64, json.Number:
-		default:
-			return fmt.Errorf("--students[%d].schoolOrgId 为必填字段且须为整数", i)
-		}
-		staffID, _ := student["studentStaffId"].(string)
-		if strings.TrimSpace(staffID) == "" {
-			return fmt.Errorf("--students[%d].studentStaffId 为必填字段", i)
-		}
-	}
-	return nil
-}
-
-// eduFamilyGroupRequiredIntFlag extracts a required integer flag, returning an
-// error if the flag is empty or not a valid integer.
-func eduFamilyGroupRequiredIntFlag(cmd *cobra.Command, name string) (int64, error) {
-	v, _ := cmd.Flags().GetString(name)
-	v = strings.TrimSpace(v)
-	if v == "" {
-		return 0, fmt.Errorf("--%s 为必填参数", name)
-	}
-	n, err := strconv.ParseInt(v, 10, 64)
-	if err != nil {
-		return 0, fmt.Errorf("--%s 须为整数: %w", name, err)
-	}
-	return n, nil
-}
-
-// eduFamilyGroupRequiredStringFlag extracts a required string flag.
-func eduFamilyGroupRequiredStringFlag(cmd *cobra.Command, name string) (string, error) {
-	v, _ := cmd.Flags().GetString(name)
-	v = strings.TrimSpace(v)
-	if v == "" {
-		return "", fmt.Errorf("--%s 为必填参数", name)
-	}
-	return v, nil
-}

internal/helpers/edu_family_group_test.go

@@ -1,318 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-)
-
-func withEduFamilyGroupCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduFamilyGroupHappyPaths(t *testing.T) {
-	cases := [][]string{
-		{"group", "check-exists", "--uid", "1", "--group-name", "小明一家"},
-		{"group", "list-children", "--uid", "1"},
-		{"manage", "create", "--uid", "1",
-			"--children", `[{"name":"小明","students":[{"corpId":"c","staffId":"s"}]}]`,
-			"--add-group", `{"schoolCorpId":"x"}`, "--source", "1"},
-		{"manage", "invite-parent", "--org-id", "1", "--uid", "2", "--mobile", "13800138000"},
-		{"manage", "add-child", "--org-id", "1", "--uid", "2", "--name", "小明", "--mobile", "13900139000"},
-		{"manage", "add-child", "--org-id", "1", "--uid", "2", "--name", "小明",
-			"--students", `[{"schoolOrgId":111,"studentStaffId":"stu001"}]`},
-		{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s",
-			"--app-type", "XIAOTIANDI", "--open", "true"},
-		{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s",
-			"--app-type", "LEARNING_VIDEO", "--open", "false"},
-	}
-	for _, args := range cases {
-		t.Run(strings.Join(args, " "), func(t *testing.T) {
-			withEduFamilyGroupCaller(t)
-			cmd := newEduFamilyGroupCommand()
-			cmd.SetArgs(args)
-			if err := cmd.Execute(); err != nil {
-				t.Fatalf("Execute(%v) = %v, want nil", args, err)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduFamilyGroupErrorPaths(t *testing.T) {
-	cases := []struct {
-		name string
-		args []string
-		want string
-	}{
-		{"check-exists missing uid", []string{"group", "check-exists", "--group-name", "x"}, "uid"},
-		{"check-exists non-int uid", []string{"group", "check-exists", "--uid", "abc", "--group-name", "x"}, "整数"},
-		{"check-exists missing group-name", []string{"group", "check-exists", "--uid", "1"}, "group-name"},
-		{"list-children missing uid", []string{"group", "list-children"}, "uid"},
-		{"create missing uid", []string{"manage", "create", "--children", "[]"}, "uid"},
-		{"create missing children", []string{"manage", "create", "--uid", "1"}, "children"},
-		{"create children bad json", []string{"manage", "create", "--uid", "1", "--children", "{"}, "JSON"},
-		{"create children empty array", []string{"manage", "create", "--uid", "1", "--children", "[]"}, "不能为空数组"},
-		{"create add-group bad json", []string{"manage", "create", "--uid", "1",
-			"--children", `[{"name":"小明","students":[{"corpId":"c","staffId":"s"}]}]`,
-			"--add-group", "{"}, "add-group"},
-		{"create add-group null", []string{"manage", "create", "--uid", "1",
-			"--children", `[{"name":"小明","students":[{"corpId":"c","staffId":"s"}]}]`,
-			"--add-group", "null"}, "null"},
-		{"invite-parent missing org-id", []string{"manage", "invite-parent", "--uid", "2", "--mobile", "138"}, "org-id"},
-		{"invite-parent missing uid", []string{"manage", "invite-parent", "--org-id", "1", "--mobile", "138"}, "uid"},
-		{"invite-parent missing mobile", []string{"manage", "invite-parent", "--org-id", "1", "--uid", "2"}, "mobile"},
-		{"add-child missing org-id", []string{"manage", "add-child", "--uid", "2", "--name", "x", "--mobile", "138"}, "org-id"},
-		{"add-child missing uid", []string{"manage", "add-child", "--org-id", "1", "--name", "x", "--mobile", "138"}, "uid"},
-		{"add-child missing name", []string{"manage", "add-child", "--org-id", "1", "--uid", "2", "--mobile", "138"}, "name"},
-		{"add-child no mobile no students", []string{"manage", "add-child", "--org-id", "1", "--uid", "2", "--name", "x"}, "至少传一个"},
-		{"add-child students bad json", []string{"manage", "add-child", "--org-id", "1", "--uid", "2", "--name", "x", "--students", "{"}, "students"},
-		{"add-child students empty", []string{"manage", "add-child", "--org-id", "1", "--uid", "2", "--name", "x", "--students", "[]"}, "不能为空数组"},
-		{"toggle-app missing org-id", []string{"manage", "toggle-app", "--uid", "2", "--child-staff-id", "s", "--app-type", "XIAOTIANDI", "--open", "true"}, "org-id"},
-		{"toggle-app missing uid", []string{"manage", "toggle-app", "--org-id", "1", "--child-staff-id", "s", "--app-type", "XIAOTIANDI", "--open", "true"}, "uid"},
-		{"toggle-app missing child-staff-id", []string{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--app-type", "XIAOTIANDI", "--open", "true"}, "child-staff-id"},
-		{"toggle-app missing app-type", []string{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s", "--open", "true"}, "app-type"},
-		{"toggle-app invalid app-type", []string{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s", "--app-type", "OTHER", "--open", "true"}, "XIAOTIANDI"},
-		{"toggle-app missing open", []string{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s", "--app-type", "XIAOTIANDI"}, "open"},
-		{"toggle-app invalid open", []string{"manage", "toggle-app", "--org-id", "1", "--uid", "2", "--child-staff-id", "s", "--app-type", "XIAOTIANDI", "--open", "maybe"}, "true 或 false"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			withEduFamilyGroupCaller(t)
-			cmd := newEduFamilyGroupCommand()
-			cmd.SetArgs(tc.args)
-			if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), tc.want) {
-				t.Fatalf("Execute(%v) error = %v, want contains %q", tc.args, err, tc.want)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduFamilyGroupValidateChildren(t *testing.T) {
-	valid := []any{map[string]any{
-		"name":     "小明",
-		"students": []any{map[string]any{"corpId": "c", "staffId": "s"}},
-	}}
-	if err := eduFamilyGroupValidateChildren(valid); err != nil {
-		t.Fatalf("valid children error = %v", err)
-	}
-	cases := []struct {
-		name     string
-		children []any
-		want     string
-	}{
-		{"empty", []any{}, "不能为空数组"},
-		{"non-object", []any{1}, "须为 JSON 对象"},
-		{"missing name", []any{map[string]any{"students": []any{map[string]any{"corpId": "c", "staffId": "s"}}}}, "name 为必填"},
-		{"missing students", []any{map[string]any{"name": "x"}}, "students 为必填"},
-		{"student non-object", []any{map[string]any{"name": "x", "students": []any{1}}}, "须为 JSON 对象"},
-		{"missing corpId", []any{map[string]any{"name": "x", "students": []any{map[string]any{"staffId": "s"}}}}, "corpId 为必填"},
-		{"missing staffId", []any{map[string]any{"name": "x", "students": []any{map[string]any{"corpId": "c"}}}}, "staffId 为必填"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if err := eduFamilyGroupValidateChildren(tc.children); err == nil || !strings.Contains(err.Error(), tc.want) {
-				t.Fatalf("error = %v, want contains %q", err, tc.want)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduFamilyGroupValidateStudents(t *testing.T) {
-	valid := []any{map[string]any{"schoolOrgId": float64(111), "studentStaffId": "stu001"}}
-	if err := eduFamilyGroupValidateStudents(valid); err != nil {
-		t.Fatalf("valid students error = %v", err)
-	}
-	cases := []struct {
-		name     string
-		students []any
-		want     string
-	}{
-		{"empty", []any{}, "不能为空数组"},
-		{"non-object", []any{1}, "须为 JSON 对象"},
-		{"missing schoolOrgId", []any{map[string]any{"studentStaffId": "s"}}, "schoolOrgId 为必填"},
-		{"missing studentStaffId", []any{map[string]any{"schoolOrgId": float64(1)}}, "studentStaffId 为必填"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if err := eduFamilyGroupValidateStudents(tc.students); err == nil || !strings.Contains(err.Error(), tc.want) {
-				t.Fatalf("error = %v, want contains %q", err, tc.want)
-			}
-		})
-	}
-}
-
-func withEduFamilyGroupDispatchCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: false}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduFamilyGroupDispatch(t *testing.T) {
-	t.Run("check-exists", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"group", "check-exists", "--uid", "123", "--group-name", "测试家庭"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "check_family_group_exists" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "check_family_group_exists")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map[string]any", caller.args["input"])
-		}
-		if input["uid"] != int64(123) {
-			t.Fatalf("input[\"uid\"] = %#v, want int64(123)", input["uid"])
-		}
-		if input["groupName"] != "测试家庭" {
-			t.Fatalf("input[\"groupName\"] = %#v, want %q", input["groupName"], "测试家庭")
-		}
-	})
-
-	t.Run("list-children", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"group", "list-children", "--uid", "456"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "listBoundChildren" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "listBoundChildren")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map[string]any", caller.args["input"])
-		}
-		if input["uid"] != int64(456) {
-			t.Fatalf("input[\"uid\"] = %#v, want int64(456)", input["uid"])
-		}
-	})
-
-	t.Run("create", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"manage", "create", "--uid", "789",
-			"--children", `[{"name":"小明","students":[{"corpId":"c","staffId":"s"}]}]`})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "create_family_group" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "create_family_group")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map[string]any", caller.args["input"])
-		}
-		if input["uid"] != int64(789) {
-			t.Fatalf("input[\"uid\"] = %#v, want int64(789)", input["uid"])
-		}
-		if input["children"] == nil {
-			t.Fatalf("input[\"children\"] is nil, want non-nil")
-		}
-	})
-
-	t.Run("invite-parent", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"manage", "invite-parent", "--org-id", "1", "--uid", "2", "--mobile", "13800138000"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "invite_parent_to_familygroup" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "invite_parent_to_familygroup")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map[string]any", caller.args["input"])
-		}
-		if input["orgId"] != int64(1) {
-			t.Fatalf("input[\"orgId\"] = %#v, want int64(1)", input["orgId"])
-		}
-		if input["uid"] != int64(2) {
-			t.Fatalf("input[\"uid\"] = %#v, want int64(2)", input["uid"])
-		}
-		if input["mobile"] != "13800138000" {
-			t.Fatalf("input[\"mobile\"] = %#v, want %q", input["mobile"], "13800138000")
-		}
-	})
-
-	t.Run("toggle-app", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"manage", "toggle-app", "--org-id", "1", "--uid", "2",
-			"--child-staff-id", "s", "--app-type", "XIAOTIANDI", "--open", "true"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "toggle_student_app" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "toggle_student_app")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map[string]any", caller.args["input"])
-		}
-		if input["appType"] != "XIAOTIANDI" {
-			t.Fatalf("input[\"appType\"] = %#v, want %q", input["appType"], "XIAOTIANDI")
-		}
-		if input["open"] != true {
-			t.Fatalf("input[\"open\"] = %#v, want true", input["open"])
-		}
-	})
-
-	t.Run("add-child", func(t *testing.T) {
-		caller := withEduFamilyGroupDispatchCaller(t)
-		cmd := newEduFamilyGroupCommand()
-		cmd.SetArgs([]string{"manage", "add-child", "--org-id", "12345", "--uid", "67890",
-			"--name", "小明", "--mobile", "13900139000",
-			"--students", `[{"schoolOrgId":111,"studentStaffId":"stu001"}]`})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute() = %v", err)
-		}
-		if caller.productID != "edu-familygroup" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-familygroup")
-		}
-		if caller.tool != "add_child_to_family_group" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "add_child_to_family_group")
-		}
-		want := map[string]any{
-			"input": map[string]any{
-				"orgId":  int64(12345),
-				"uid":    int64(67890),
-				"name":   "小明",
-				"mobile": "13900139000",
-				"students": []any{
-					map[string]any{"schoolOrgId": float64(111), "studentStaffId": "stu001"},
-				},
-			},
-		}
-		if !reflect.DeepEqual(caller.args, want) {
-			t.Fatalf("args = %#v, want %#v", caller.args, want)
-		}
-	})
-}

internal/helpers/edu_group.go

@@ -1,846 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"fmt"
-	"strconv"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
-)
-
-// ──────────────────────────────────────────────────────────
-// dws edu-group — 家校群管理
-// 共 14 个工具，按 student-group / class-group / batch 分组
-// ──────────────────────────────────────────────────────────
-
-func newEduGroupCommand() *cobra.Command {
-	contract.RegisterProductDecl(contract.ProductDecl{
-		ID: "edu-group",
-		Selection: contract.ProductSelectionDecl{
-			AgentSummary: "师生群查询/创建/解散、班级群会话信息查询、批量操作",
-			UseWhen: []string{
-				"用户要查询或管理钉钉师生群、班级群会话信息，或批量检查/创建师生群。",
-			},
-			AvoidWhen: []string{
-				"家庭群用 edu-familygroup；家校通讯录用 edu-contact；家校应用/作业/打卡用 edu-app。",
-			},
-		},
-	})
-	root := &cobra.Command{
-		Use:    "edu-group",
-		Short:  "家校群",
-		Long:   `钉钉家校群管理：师生群查询/创建/解散、班级群会话信息查询、批量操作等。`,
-		Hidden: true,
-		RunE:   groupRunE,
-	}
-
-	// ════════════════════════════════════════════════════════════
-	// student-group 子命令组 — 师生群管理
-	// ════════════════════════════════════════════════════════════
-
-	studentGroupCmd := &cobra.Command{Use: "student-group", Short: "师生群管理", RunE: groupRunE}
-
-	studentGroupInfoCmd := &cobra.Command{
-		Use:   "info",
-		Short: "查询班级师生群信息",
-		Long:  `查询指定班级的师生群信息。返回师生群的群会话ID（cid）。管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group student-group info --dept-id 12345
-  dws edu-group student-group info --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "get_class_group_info", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupInfoCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "get_class_group_info",
-				CanonicalPath:  "edu-group.get_class_group_info",
-				CLIPath:        "edu-group student-group info",
-				PrimaryCLIPath: "edu-group student-group info",
-			},
-			Description: "查询班级师生群信息",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "get_class_group_info"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "查询班级师生群信息",
-				UseWhen:      []string{"需要查询指定班级的师生群会话ID时"},
-				AvoidWhen:    []string{"查询班级群会话详情用 student-group conversation"},
-				Examples: []string{
-					"dws edu-group student-group info --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupExistsCmd := &cobra.Command{
-		Use:   "exists",
-		Short: "检查组织是否已创建师生群",
-		Long:  `检查指定组织下是否已创建师生群。返回是否存在师生群（true/false）。仅限管理员角色调用。`,
-		Example: `  dws edu-group student-group exists --dept-id 12345
-  dws edu-group student-group exists --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "check_class_group_exists", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupExistsCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "check_class_group_exists",
-				CanonicalPath:  "edu-group.check_class_group_exists",
-				CLIPath:        "edu-group student-group exists",
-				PrimaryCLIPath: "edu-group student-group exists",
-			},
-			Description: "检查组织是否已创建师生群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "check_class_group_exists"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "检查组织是否已创建师生群",
-				UseWhen:      []string{"需要判断指定班级是否已创建师生群时"},
-				AvoidWhen:    []string{"查询师生群成员用 student-group members"},
-				Examples: []string{
-					"dws edu-group student-group exists --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupMembersCmd := &cobra.Command{
-		Use:   "members",
-		Short: "查询师生群成员列表",
-		Long:  `查询指定班级师生群的所有成员userId列表。管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group student-group members --dept-id 12345
-  dws edu-group student-group members --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "get_group_members", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupMembersCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "get_group_members",
-				CanonicalPath:  "edu-group.get_group_members",
-				CLIPath:        "edu-group student-group members",
-				PrimaryCLIPath: "edu-group student-group members",
-			},
-			Description: "查询师生群成员列表",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "get_group_members"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "查询师生群成员列表",
-				UseWhen:      []string{"需要查询指定班级师生群的所有成员userId列表时"},
-				AvoidWhen:    []string{"判断用户是否在群中用 student-group is-in"},
-				Examples: []string{
-					"dws edu-group student-group members --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupIsInCmd := &cobra.Command{
-		Use:   "is-in",
-		Short: "判断用户是否在师生群中",
-		Long:  `判断当前用户是否在指定班级的师生群中。返回是否在群中（true/false）。管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group student-group is-in --dept-id 12345
-  dws edu-group student-group is-in --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "is_in_class_group", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupIsInCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "is_in_class_group",
-				CanonicalPath:  "edu-group.is_in_class_group",
-				CLIPath:        "edu-group student-group is-in",
-				PrimaryCLIPath: "edu-group student-group is-in",
-			},
-			Description: "判断用户是否在师生群中",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "is_in_class_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "判断用户是否在师生群中",
-				UseWhen:      []string{"需要判断当前用户是否在指定班级师生群中时"},
-				AvoidWhen:    []string{"查询群成员列表用 student-group members"},
-				Examples: []string{
-					"dws edu-group student-group is-in --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupConversationCmd := &cobra.Command{
-		Use:   "conversation",
-		Short: "查询班级群会话详情",
-		Long: `查询指定班级师生群的会话详情。
-返回群会话ID（cid）、群标题（title）、群成员数量（memberCount）和群图标URL（icon）。
-管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group student-group conversation --dept-id 12345
-  dws edu-group student-group conversation --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "get_group_conversation_info", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupConversationCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "get_group_conversation_info",
-				CanonicalPath:  "edu-group.get_group_conversation_info",
-				CLIPath:        "edu-group student-group conversation",
-				PrimaryCLIPath: "edu-group student-group conversation",
-			},
-			Description: "查询班级群会话详情",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "get_group_conversation_info"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "查询班级师生群会话详情",
-				UseWhen:      []string{"需要查询指定班级师生群的会话ID、标题、成员数、图标时"},
-				AvoidWhen:    []string{"仅需群会话ID用 student-group info"},
-				Examples: []string{
-					"dws edu-group student-group conversation --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupCreateCmd := &cobra.Command{
-		Use:   "create",
-		Short: "创建班级师生群",
-		Long: `为指定班级创建师生群。自动将班级的班主任设为群主，并拉入所有老师和学生。
-前提是班级必须已设置班主任。返回创建成功的群会话ID（cid）。仅限管理员或班主任角色调用。`,
-		Example: `  dws edu-group student-group create --dept-id 12345
-  dws edu-group student-group create --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "create_class_group", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupCreateCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "medium",
-			Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "create_class_group",
-				CanonicalPath:  "edu-group.create_class_group",
-				CLIPath:        "edu-group student-group create",
-				PrimaryCLIPath: "edu-group student-group create",
-			},
-			Description: "创建班级师生群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "create_class_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "为指定班级创建师生群",
-				UseWhen:      []string{"需要为指定班级创建师生群，自动拉入班主任、老师和学生时"},
-				AvoidWhen:    []string{"批量创建师生群用 batch create-student-groups"},
-				Examples: []string{
-					"dws edu-group student-group create --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	studentGroupDisbandCmd := &cobra.Command{
-		Use:   "disband",
-		Short: "解散班级师生群",
-		Long:  `解散指定班级的师生群，同时删除班级与群的关联关系。仅限管理员或班主任角色调用。`,
-		Example: `  dws edu-group student-group disband --dept-id 12345
-  dws edu-group student-group disband --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "disband_class_group", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(studentGroupDisbandCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "destructive", Risk: "high",
-			Confirmation: "user_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "disband_class_group",
-				CanonicalPath:  "edu-group.disband_class_group",
-				CLIPath:        "edu-group student-group disband",
-				PrimaryCLIPath: "edu-group student-group disband",
-			},
-			Description: "解散班级师生群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "disband_class_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "解散班级师生群并删除关联关系",
-				UseWhen:      []string{"需要解散指定班级的师生群并删除班级与群的关联关系时"},
-				AvoidWhen:    []string{"查询师生群信息用 student-group info"},
-				Examples: []string{
-					"dws edu-group student-group disband --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	// ════════════════════════════════════════════════════════════
-	// class-group 子命令组 — 班级群（家校群）会话管理
-	// ════════════════════════════════════════════════════════════
-
-	classGroupCmd := &cobra.Command{Use: "class-group", Short: "班级群会话管理", RunE: groupRunE}
-
-	classGroupConversationIDCmd := &cobra.Command{
-		Use:   "conversation-id",
-		Short: "获取班级群会话ID",
-		Long:  `获取指定班级的班级群会话ID，可用于后续发送群消息等操作。管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group class-group conversation-id --dept-id 12345
-  dws edu-group class-group conversation-id --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "get_class_conversation_id", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(classGroupConversationIDCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "get_class_conversation_id",
-				CanonicalPath:  "edu-group.get_class_conversation_id",
-				CLIPath:        "edu-group class-group conversation-id",
-				PrimaryCLIPath: "edu-group class-group conversation-id",
-			},
-			Description: "获取班级群会话ID",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "get_class_conversation_id"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "获取班级群会话ID",
-				UseWhen:      []string{"需要获取指定班级的班级群会话ID以便后续发送群消息时"},
-				AvoidWhen:    []string{"需要完整群信息用 class-group conversation"},
-				Examples: []string{
-					"dws edu-group class-group conversation-id --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	classGroupConversationCmd := &cobra.Command{
-		Use:   "conversation",
-		Short: "获取班级群完整会话信息",
-		Long: `获取指定班级的班级群完整会话信息。
-返回班级群的会话ID（cid）、群标题（title）、群成员数量（memberCount）和群图标URL（icon）。
-管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group class-group conversation --dept-id 12345
-  dws edu-group class-group conversation --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "get_class_conversation", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(classGroupConversationCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "get_class_conversation",
-				CanonicalPath:  "edu-group.get_class_conversation",
-				CLIPath:        "edu-group class-group conversation",
-				PrimaryCLIPath: "edu-group class-group conversation",
-			},
-			Description: "获取班级群完整会话信息",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "get_class_conversation"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "获取班级群完整会话信息",
-				UseWhen:      []string{"需要查询指定班级的班级群会话ID、标题、成员数、图标时"},
-				AvoidWhen:    []string{"仅需会话ID用 class-group conversation-id"},
-				Examples: []string{
-					"dws edu-group class-group conversation --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	classGroupExistsCmd := &cobra.Command{
-		Use:   "exists",
-		Short: "检查班级群是否存在",
-		Long:  `检查指定班级是否已创建班级群。返回班级群是否存在（true/false）。管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group class-group exists --dept-id 12345
-  dws edu-group class-group exists --dept-id 12345 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			deptID, err := eduGroupRequiredIntFlag(cmd, "dept-id")
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer("edu-group", "check_class_conversation_exists", map[string]any{
-				"input": map[string]any{"deptId": deptID},
-			})
-		},
-	}
-	DeclareLeafMetadata(classGroupExistsCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "check_class_conversation_exists",
-				CanonicalPath:  "edu-group.check_class_conversation_exists",
-				CLIPath:        "edu-group class-group exists",
-				PrimaryCLIPath: "edu-group class-group exists",
-			},
-			Description: "检查班级群是否存在",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "check_class_conversation_exists"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "检查班级群是否存在",
-				UseWhen:      []string{"需要判断指定班级是否已创建班级群时"},
-				AvoidWhen:    []string{"查询班级群会话信息用 class-group conversation"},
-				Examples: []string{
-					"dws edu-group class-group exists --dept-id 12345 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "dept-id", Property: "input.deptId", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	classGroupListByConversationIDsCmd := &cobra.Command{
-		Use:   "list-by-cids",
-		Short: "根据会话ID列表批量查询群信息",
-		Long: `根据群会话ID列表批量查询群的详细信息。
-返回群会话详情列表，每项包含会话ID（cid）、群标题（title）、群成员数量（memberCount）和群图标URL（icon）。
-管理员、班主任、老师角色可调用。`,
-		Example: `  dws edu-group class-group list-by-cids --conversation-ids cid1,cid2,cid3
-  dws edu-group class-group list-by-cids --conversation-ids cid1,cid2 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			raw, _ := cmd.Flags().GetString("conversation-ids")
-			raw = strings.TrimSpace(raw)
-			if raw == "" {
-				return fmt.Errorf("--conversation-ids 为必填参数")
-			}
-			conversationIDs := eduGroupParseCSV(raw)
-			if len(conversationIDs) == 0 {
-				return fmt.Errorf("--conversation-ids 不能为空")
-			}
-			return callMCPToolOnServer("edu-group", "list_groups_by_conversation_ids", map[string]any{
-				"input": map[string]any{"conversationIds": conversationIDs},
-			})
-		},
-	}
-	DeclareLeafMetadata(classGroupListByConversationIDsCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "list_groups_by_conversation_ids",
-				CanonicalPath:  "edu-group.list_groups_by_conversation_ids",
-				CLIPath:        "edu-group class-group list-by-cids",
-				PrimaryCLIPath: "edu-group class-group list-by-cids",
-			},
-			Description: "根据会话ID列表批量查询群信息",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "list_groups_by_conversation_ids"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "根据会话ID列表批量查询群信息",
-				UseWhen:      []string{"需要根据一组群会话ID批量查询群的详细信息时"},
-				AvoidWhen:    []string{"按班级ID批量查询用 batch get-class-groups"},
-				Examples: []string{
-					"dws edu-group class-group list-by-cids --conversation-ids cid1,cid2,cid3 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "conversation-ids", Property: "input.conversationIds", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	// ════════════════════════════════════════════════════════════
-	// batch 子命令组 — 批量操作
-	// ════════════════════════════════════════════════════════════
-
-	batchCmd := &cobra.Command{Use: "batch", Short: "批量操作", RunE: groupRunE}
-
-	batchCheckClassGroupCmd := &cobra.Command{
-		Use:   "check-student-group",
-		Short: "批量检查班级是否已创建师生群",
-		Long:  `批量检查多个班级是否已创建师生群。返回班级ID与群会话ID（cid）的映射关系。仅限管理员角色调用。`,
-		Example: `  dws edu-group batch check-student-group --class-ids 12345,67890
-  dws edu-group batch check-student-group --class-ids 12345,67890 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			raw, _ := cmd.Flags().GetString("class-ids")
-			raw = strings.TrimSpace(raw)
-			if raw == "" {
-				return fmt.Errorf("--class-ids 为必填参数")
-			}
-			classIDs, err := eduGroupParseIntCSV(raw)
-			if err != nil {
-				return fmt.Errorf("--class-ids 须为逗号分隔的整数列表: %w", err)
-			}
-			return callMCPToolOnServer("edu-group", "batch_check_class_group", map[string]any{
-				"input": map[string]any{"classIds": classIDs},
-			})
-		},
-	}
-	DeclareLeafMetadata(batchCheckClassGroupCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "batch_check_class_group",
-				CanonicalPath:  "edu-group.batch_check_class_group",
-				CLIPath:        "edu-group batch check-student-group",
-				PrimaryCLIPath: "edu-group batch check-student-group",
-			},
-			Description: "批量检查班级是否已创建师生群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "batch_check_class_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "批量检查班级是否已创建师生群",
-				UseWhen:      []string{"需要批量检查多个班级是否已创建师生群时"},
-				AvoidWhen:    []string{"单个班级检查用 student-group exists"},
-				Examples: []string{
-					"dws edu-group batch check-student-group --class-ids 12345,67890 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "class-ids", Property: "input.classIds", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	batchGetClassConversationsCmd := &cobra.Command{
-		Use:   "get-class-groups",
-		Short: "批量获取班级群信息",
-		Long:  `批量获取多个班级的班级群会话信息。返回班级ID与群会话信息的映射关系。仅限管理员角色调用。`,
-		Example: `  dws edu-group batch get-class-groups --class-ids 12345,67890
-  dws edu-group batch get-class-groups --class-ids 12345,67890 -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			raw, _ := cmd.Flags().GetString("class-ids")
-			raw = strings.TrimSpace(raw)
-			if raw == "" {
-				return fmt.Errorf("--class-ids 为必填参数")
-			}
-			classIDs := eduGroupParseCSV(raw)
-			if len(classIDs) == 0 {
-				return fmt.Errorf("--class-ids 不能为空")
-			}
-			return callMCPToolOnServer("edu-group", "batch_get_class_conversations", map[string]any{
-				"input": map[string]any{"classIds": classIDs},
-			})
-		},
-	}
-	DeclareLeafMetadata(batchGetClassConversationsCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "batch_get_class_conversations",
-				CanonicalPath:  "edu-group.batch_get_class_conversations",
-				CLIPath:        "edu-group batch get-class-groups",
-				PrimaryCLIPath: "edu-group batch get-class-groups",
-			},
-			Description: "批量获取班级群信息",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "batch_get_class_conversations"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "批量获取班级群会话信息",
-				UseWhen:      []string{"需要批量获取多个班级的班级群会话信息时"},
-				AvoidWhen:    []string{"按会话ID批量查询用 class-group list-by-cids"},
-				Examples: []string{
-					"dws edu-group batch get-class-groups --class-ids 12345,67890 --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "class-ids", Property: "input.classIds", Required: boolPtr(true)},
-			},
-		},
-	})
-
-	batchCreateClassGroupCmd := &cobra.Command{
-		Use:   "create-student-groups",
-		Short: "批量创建师生群",
-		Long: `为组织下所有已设置班主任但尚未创建师生群的班级批量创建师生群。
-小学和幼儿园学段的班级不会创建师生群。仅限管理员角色调用。`,
-		Example: `  dws edu-group batch create-student-groups
-  dws edu-group batch create-student-groups -f json`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			return callMCPToolOnServer("edu-group", "batch_create_class_group", map[string]any{
-				"input": map[string]any{},
-			})
-		},
-	}
-	DeclareLeafMetadata(batchCreateClassGroupCmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "medium",
-			Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "edu-group",
-				Name:           "batch_create_class_group",
-				CanonicalPath:  "edu-group.batch_create_class_group",
-				CLIPath:        "edu-group batch create-student-groups",
-				PrimaryCLIPath: "edu-group batch create-student-groups",
-			},
-			Description: "批量创建师生群",
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "edu-group", RPCName: "batch_create_class_group"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "为组织下符合条件的班级批量创建师生群",
-				UseWhen:      []string{"需要为组织下所有已设置班主任但尚未创建师生群的班级批量创建师生群时"},
-				AvoidWhen:    []string{"单个班级创建用 student-group create"},
-				Examples: []string{
-					"dws edu-group batch create-student-groups --format json",
-				},
-			},
-			Parameters: []contract.ParamDecl{},
-		},
-	})
-
-	// ════════════════════════════════════════════════════════════
-	// flags + 构建命令树
-	// ════════════════════════════════════════════════════════════
-
-	// student-group flags
-	studentGroupInfoCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupExistsCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupMembersCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupIsInCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupConversationCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupCreateCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	studentGroupDisbandCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-
-	// class-group flags
-	classGroupConversationIDCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	classGroupConversationCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	classGroupExistsCmd.Flags().String("dept-id", "", "班级 ID（必填）")
-	classGroupListByConversationIDsCmd.Flags().String("conversation-ids", "", "群会话 ID 列表，逗号分隔（必填）")
-
-	// batch flags
-	batchCheckClassGroupCmd.Flags().String("class-ids", "", "班级 ID 列表，逗号分隔（必填）")
-	batchGetClassConversationsCmd.Flags().String("class-ids", "", "班级 ID 列表，逗号分隔（必填）")
-
-	studentGroupCmd.AddCommand(
-		studentGroupInfoCmd, studentGroupExistsCmd, studentGroupMembersCmd,
-		studentGroupIsInCmd, studentGroupConversationCmd,
-		studentGroupCreateCmd, studentGroupDisbandCmd,
-	)
-	classGroupCmd.AddCommand(
-		classGroupConversationIDCmd, classGroupConversationCmd,
-		classGroupExistsCmd, classGroupListByConversationIDsCmd,
-	)
-	batchCmd.AddCommand(batchCheckClassGroupCmd, batchGetClassConversationsCmd, batchCreateClassGroupCmd)
-
-	root.AddCommand(studentGroupCmd, classGroupCmd, batchCmd)
-
-	return root
-}
-
-// eduGroupRequiredIntFlag extracts a required integer flag, returning an error
-// if the flag is empty or not a valid integer.
-func eduGroupRequiredIntFlag(cmd *cobra.Command, name string) (int64, error) {
-	v, _ := cmd.Flags().GetString(name)
-	v = strings.TrimSpace(v)
-	if v == "" {
-		return 0, fmt.Errorf("--%s 为必填参数", name)
-	}
-	n, err := strconv.ParseInt(v, 10, 64)
-	if err != nil {
-		return 0, fmt.Errorf("--%s 须为整数: %w", name, err)
-	}
-	return n, nil
-}
-
-// eduGroupParseCSV splits a comma-separated string into trimmed non-empty values.
-func eduGroupParseCSV(raw string) []string {
-	parts := strings.Split(raw, ",")
-	result := make([]string, 0, len(parts))
-	for _, p := range parts {
-		v := strings.TrimSpace(p)
-		if v != "" {
-			result = append(result, v)
-		}
-	}
-	return result
-}
-
-// eduGroupParseIntCSV splits a comma-separated string into int64 values.
-func eduGroupParseIntCSV(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)
-	}
-	return result, nil
-}

internal/helpers/edu_group_test.go

@@ -1,366 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"io"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-// withEduGroupCaller installs a dry-run capture caller so happy-path command
-// execution exercises each RunE up to the callMCPToolOnServer dispatch without
-// requiring a live MCP transport.
-func withEduGroupCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduGroupHappyPaths(t *testing.T) {
-	cases := [][]string{
-		{"student-group", "info", "--dept-id", "123"},
-		{"student-group", "exists", "--dept-id", "123"},
-		{"student-group", "members", "--dept-id", "123"},
-		{"student-group", "is-in", "--dept-id", "123"},
-		{"student-group", "conversation", "--dept-id", "123"},
-		{"student-group", "create", "--dept-id", "123"},
-		{"student-group", "disband", "--dept-id", "123"},
-		{"class-group", "conversation-id", "--dept-id", "123"},
-		{"class-group", "conversation", "--dept-id", "123"},
-		{"class-group", "exists", "--dept-id", "123"},
-		{"class-group", "list-by-cids", "--conversation-ids", "cid1,cid2"},
-		{"batch", "check-student-group", "--class-ids", "1,2"},
-		{"batch", "get-class-groups", "--class-ids", "1,2"},
-		{"batch", "create-student-groups"},
-	}
-	for _, args := range cases {
-		t.Run(strings.Join(args, " "), func(t *testing.T) {
-			withEduGroupCaller(t)
-			cmd := newEduGroupCommand()
-			cmd.SetArgs(args)
-			if err := cmd.Execute(); err != nil {
-				t.Fatalf("Execute(%v) = %v, want nil", args, err)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduGroupMissingRequiredFlags(t *testing.T) {
-	// Each dept-id command must reject an absent --dept-id, covering its own
-	// error branch as well as the shared eduGroupRequiredIntFlag empty case.
-	deptIDCommands := [][]string{
-		{"student-group", "info"},
-		{"student-group", "exists"},
-		{"student-group", "members"},
-		{"student-group", "is-in"},
-		{"student-group", "conversation"},
-		{"student-group", "create"},
-		{"student-group", "disband"},
-		{"class-group", "conversation-id"},
-		{"class-group", "conversation"},
-		{"class-group", "exists"},
-	}
-	for _, args := range deptIDCommands {
-		t.Run(strings.Join(args, " "), func(t *testing.T) {
-			withEduGroupCaller(t)
-			cmd := newEduGroupCommand()
-			cmd.SetArgs(args)
-			if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "dept-id") {
-				t.Fatalf("Execute(%v) error = %v, want dept-id required", args, err)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageEduGroupFlagValidation(t *testing.T) {
-	t.Run("non-integer dept-id", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"student-group", "info", "--dept-id", "abc"})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "整数") {
-			t.Fatalf("non-integer dept-id error = %v", err)
-		}
-	})
-
-	t.Run("list-by-cids missing conversation-ids", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"class-group", "list-by-cids"})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "conversation-ids") {
-			t.Fatalf("missing conversation-ids error = %v", err)
-		}
-	})
-
-	t.Run("list-by-cids only separators", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"class-group", "list-by-cids", "--conversation-ids", " , , "})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "conversation-ids") {
-			t.Fatalf("empty conversation-ids error = %v", err)
-		}
-	})
-
-	t.Run("batch check missing class-ids", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"batch", "check-student-group"})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "class-ids") {
-			t.Fatalf("missing class-ids error = %v", err)
-		}
-	})
-
-	t.Run("batch check invalid integer class-ids", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"batch", "check-student-group", "--class-ids", "x"})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "整数") {
-			t.Fatalf("invalid integer class-ids error = %v", err)
-		}
-	})
-
-	t.Run("batch get missing class-ids", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"batch", "get-class-groups"})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "class-ids") {
-			t.Fatalf("missing class-ids error = %v", err)
-		}
-	})
-
-	t.Run("batch get only separators", func(t *testing.T) {
-		withEduGroupCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"batch", "get-class-groups", "--class-ids", " , , "})
-		if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "class-ids") {
-			t.Fatalf("empty class-ids error = %v", err)
-		}
-	})
-}
-
-func TestCrossPlatformCoverageEduGroupParseHelpers(t *testing.T) {
-	if got := eduGroupParseCSV(" a , , b "); len(got) != 2 || got[0] != "a" || got[1] != "b" {
-		t.Fatalf("eduGroupParseCSV = %#v", got)
-	}
-	ids, err := eduGroupParseIntCSV(" 1 , , 2 ")
-	if err != nil || len(ids) != 2 || ids[0] != 1 || ids[1] != 2 {
-		t.Fatalf("eduGroupParseIntCSV = %#v, err = %v", ids, err)
-	}
-	if _, err := eduGroupParseIntCSV("1,bad"); err == nil {
-		t.Fatalf("eduGroupParseIntCSV invalid = nil error")
-	}
-}
-
-// withEduGroupDispatchCaller installs a non-dry-run capture caller so commands
-// exercise the full dispatch path through deps.Caller.CallTool.
-func withEduGroupDispatchCaller(t *testing.T) *recruitCaptureCaller {
-	t.Helper()
-	caller := &recruitCaptureCaller{}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-	return caller
-}
-
-func TestCrossPlatformCoverageEduGroupDispatch(t *testing.T) {
-	t.Run("student-group info dispatches get_class_group_info", func(t *testing.T) {
-		caller := withEduGroupDispatchCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"student-group", "info", "--dept-id", "123"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute error = %v", err)
-		}
-		if caller.productID != "edu-group" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-group")
-		}
-		if caller.tool != "get_class_group_info" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "get_class_group_info")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map", caller.args["input"])
-		}
-		if input["deptId"] != int64(123) {
-			t.Fatalf("input[\"deptId\"] = %#v, want int64(123)", input["deptId"])
-		}
-	})
-
-	t.Run("student-group create dispatches create_class_group", func(t *testing.T) {
-		caller := withEduGroupDispatchCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"student-group", "create", "--dept-id", "456"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute error = %v", err)
-		}
-		if caller.productID != "edu-group" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-group")
-		}
-		if caller.tool != "create_class_group" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "create_class_group")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map", caller.args["input"])
-		}
-		if input["deptId"] != int64(456) {
-			t.Fatalf("input[\"deptId\"] = %#v, want int64(456)", input["deptId"])
-		}
-	})
-
-	t.Run("student-group disband dispatches disband_class_group", func(t *testing.T) {
-		caller := withEduGroupDispatchCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.PersistentFlags().Bool("yes", false, "")
-		cmd.PersistentFlags().Bool("dry-run", false, "")
-		cmd.SetArgs([]string{"student-group", "disband", "--dept-id", "789", "--yes"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute error = %v", err)
-		}
-		if caller.productID != "edu-group" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-group")
-		}
-		if caller.tool != "disband_class_group" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "disband_class_group")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map", caller.args["input"])
-		}
-		if input["deptId"] != int64(789) {
-			t.Fatalf("input[\"deptId\"] = %#v, want int64(789)", input["deptId"])
-		}
-	})
-
-	t.Run("class-group list-by-cids dispatches list_groups_by_conversation_ids", func(t *testing.T) {
-		caller := withEduGroupDispatchCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"class-group", "list-by-cids", "--conversation-ids", "cid1,cid2,cid3"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute error = %v", err)
-		}
-		if caller.productID != "edu-group" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-group")
-		}
-		if caller.tool != "list_groups_by_conversation_ids" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "list_groups_by_conversation_ids")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map", caller.args["input"])
-		}
-		cids, ok := input["conversationIds"].([]string)
-		if !ok || len(cids) != 3 || cids[0] != "cid1" || cids[1] != "cid2" || cids[2] != "cid3" {
-			t.Fatalf("input[\"conversationIds\"] = %#v, want [cid1 cid2 cid3]", input["conversationIds"])
-		}
-	})
-
-	t.Run("batch check-student-group dispatches batch_check_class_group", func(t *testing.T) {
-		caller := withEduGroupDispatchCaller(t)
-		cmd := newEduGroupCommand()
-		cmd.SetArgs([]string{"batch", "check-student-group", "--class-ids", "100,200"})
-		if err := cmd.Execute(); err != nil {
-			t.Fatalf("Execute error = %v", err)
-		}
-		if caller.productID != "edu-group" {
-			t.Fatalf("productID = %q, want %q", caller.productID, "edu-group")
-		}
-		if caller.tool != "batch_check_class_group" {
-			t.Fatalf("tool = %q, want %q", caller.tool, "batch_check_class_group")
-		}
-		input, ok := caller.args["input"].(map[string]any)
-		if !ok {
-			t.Fatalf("args[\"input\"] = %#v, want map", caller.args["input"])
-		}
-		classIDs, ok := input["classIds"].([]int64)
-		if !ok || len(classIDs) != 2 || classIDs[0] != 100 || classIDs[1] != 200 {
-			t.Fatalf("input[\"classIds\"] = %#v, want [100 200]", input["classIds"])
-		}
-	})
-}
-
-// newEduGroupConfirmRoot 模拟真实运行时的根命令：核心框架在 rootCmd 上注册
-// 全局 persistent --yes flag，叶子命令通过合并后的 Flags() 读取。
-func newEduGroupConfirmRoot() *cobra.Command {
-	root := &cobra.Command{Use: "dws"}
-	root.PersistentFlags().BoolP("yes", "y", false, "跳过确认提示")
-	root.AddCommand(newEduGroupCommand())
-	return root
-}
-
-// TestCrossPlatformCoverageEduGroupDestructiveConfirmGate 对 edu-group 每个
-// user_required 破坏性叶子做成对验证：
-//   - 未显式确认：返回 confirmation_required 错误，且 caller 调用次数为零。
-//   - 显式确认后：恰好一次 MCP 调用，且 productID、tool、完整参数均准确。
-func TestCrossPlatformCoverageEduGroupDestructiveConfirmGate(t *testing.T) {
-	cases := []struct {
-		name      string
-		args      []string
-		wantTool  string
-		wantInput map[string]any
-	}{
-		{
-			"student-group disband",
-			[]string{"edu-group", "student-group", "disband", "--dept-id", "12345"},
-			"disband_class_group",
-			map[string]any{"deptId": int64(12345)},
-		},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name+"/rejected_without_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduGroupConfirmRoot()
-			root.SetArgs(tc.args)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("expected confirm-gate error without --yes, got nil")
-			}
-			if !strings.Contains(err.Error(), "需要用户确认") {
-				t.Fatalf("expected confirmation gate error, got: %v", err)
-			}
-			if len(caller.calls) != 0 {
-				t.Fatalf("caller should not be invoked without --yes, got %d calls", len(caller.calls))
-			}
-		})
-
-		t.Run(tc.name+"/dispatched_with_yes", func(t *testing.T) {
-			caller := &recruitCaptureCaller{dryRun: false}
-			InitDepsForTest(t, caller)
-			deps.Out.w = io.Discard
-
-			root := newEduGroupConfirmRoot()
-			root.SetArgs(append(append([]string{}, tc.args...), "--yes"))
-			if err := root.Execute(); err != nil {
-				t.Fatalf("Execute() with --yes error = %v", err)
-			}
-			if len(caller.calls) != 1 {
-				t.Fatalf("expected exactly 1 MCP call with --yes, got %d", len(caller.calls))
-			}
-			if caller.calls[0].productID != "edu-group" {
-				t.Errorf("productID = %q, want %q", caller.calls[0].productID, "edu-group")
-			}
-			if caller.calls[0].tool != tc.wantTool {
-				t.Errorf("tool = %q, want %q", caller.calls[0].tool, tc.wantTool)
-			}
-			gotArgs := caller.calls[0].args
-			if len(gotArgs) != 1 {
-				t.Fatalf("args should carry exactly the \"input\" key, got %v", gotArgs)
-			}
-			gotInput, ok := gotArgs["input"].(map[string]any)
-			if !ok {
-				t.Fatalf("args[\"input\"] should be map[string]any, got %T", gotArgs["input"])
-			}
-			if !reflect.DeepEqual(gotInput, tc.wantInput) {
-				t.Errorf("input = %#v, want %#v", gotInput, tc.wantInput)
-			}
-		})
-	}
-}

internal/helpers/file_comment.go

@@ -55,12 +55,12 @@ func fileCommentSpaceIDFlag() LeafFlag {
 // doc comment, sheet comment, and drive comment. The public command belongs to
 // Drive, while the implementation routes to the shared doc-comment MCP server.
 func newDriveFileCommentCmd() *cobra.Command {
-	commentCmd := &cobra.Command{
+	commentCmd := newGroupCommand(&cobra.Command{
 		Use:   "comment",
 		Short: "普通文件评论管理",
 		Long:  "管理钉盘普通预览文件的评论：查询评论列表或创建全文纯文本评论。",
 		RunE:  groupRunE,
-	}
+	})
 
 	listCmd := NewLeafCommand(LeafSpec{
 		Use:   "list",

internal/helpers/helpers.go

@@ -15,15 +15,16 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/cmdutil"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
-// Re-export cmdutil functions as package-level aliases so that existing product
-// files continue to compile with their current (unexported) call sites.
-// This avoids a mass-rename in 22 product files while still consolidating the
-// implementations in pkg/cmdutil.
+// Re-export shared command helpers as package-level aliases so existing product
+// files continue to compile with their current (unexported) call sites. This
+// avoids a mass-rename while keeping reusable command-resolution and flag
+// utilities in cmdutil.
 var (
 	groupRunE                       = cmdutil.GroupRunE
 	hintSubCmd                      = cmdutil.HintSubCmd
@@ -38,6 +39,40 @@ var (
 	helperAfter                     = time.After
 )
 
+// newGroupCommand declares the ordinary navigation policy used by helper
+// command containers. The unified framework compiles this declaration into
+// Cobra behavior and command-resolution metadata.
+func newGroupCommand(command *cobra.Command) *cobra.Command {
+	corecmd.ApplyGroupPolicy(command, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
+	return command
+}
+
+// newDeepGroupCommand declares a navigation container whose typo recovery may
+// teach exact descendant paths (for example sheet read -> sheet range read).
+func newDeepGroupCommand(command *cobra.Command) *cobra.Command {
+	corecmd.ApplyGroupPolicy(command, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupNavigationOnly,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoveryDeep,
+	})
+	return command
+}
+
+// newHybridGroupCommand declares a business command that also owns children.
+// Its existing RunE remains the command's default action.
+func newHybridGroupCommand(command *cobra.Command) *cobra.Command {
+	corecmd.ApplyGroupPolicy(command, corecmd.GroupPolicy{
+		Mode:        corecmd.GroupHybrid,
+		Positionals: corecmd.PositionalsReject,
+		Recovery:    corecmd.RecoverySibling,
+	})
+	return command
+}
+
 // Deps holds shared dependencies injected from the host application.
 type Deps struct {
 	Caller edition.ToolCaller

internal/helpers/hrbrain.go

@@ -29,7 +29,7 @@ func newHrbrainCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "hrbrain",
 		Short: "组织大脑：人才池、员工档案与人才搜索",
 		Long: `钉钉组织大脑（hrbrain）能力：人才池管理、员工档案查询、人才搜索与标签管理。
@@ -47,11 +47,11 @@ func newHrbrainCommand() *cobra.Command {
   dws hrbrain search employees-structured   使用高级条件搜索人员
   dws hrbrain search fields                 获取高级搜索字段列表`,
 		RunE: groupRunE,
-	}
+	})
 
 	// ── talent-pool: 人才池管理 ────────────────────────────────
 
-	talentPoolCmd := &cobra.Command{Use: "talent-pool", Short: "人才池管理", RunE: groupRunE}
+	talentPoolCmd := newGroupCommand(&cobra.Command{Use: "talent-pool", Short: "人才池管理", RunE: groupRunE})
 
 	talentPoolListCmd := &cobra.Command{
 		Use:   "list",
@@ -236,7 +236,7 @@ func newHrbrainCommand() *cobra.Command {
 
 	// ── profile: 员工档案管理 ──────────────────────────────────
 
-	profileCmd := &cobra.Command{Use: "profile", Short: "员工档案管理", RunE: groupRunE}
+	profileCmd := newGroupCommand(&cobra.Command{Use: "profile", Short: "员工档案管理", RunE: groupRunE})
 
 	profileMetadataCmd := &cobra.Command{
 		Use:     "metadata",
@@ -493,7 +493,7 @@ func newHrbrainCommand() *cobra.Command {
 
 	// ── search: 人才搜索 ─────────────────────────────────────
 
-	searchCmd := &cobra.Command{Use: "search", Short: "人才搜索", RunE: groupRunE}
+	searchCmd := newGroupCommand(&cobra.Command{Use: "search", Short: "人才搜索", RunE: groupRunE})
 
 	employeeSearchCmd := &cobra.Command{
 		Use:   "employees",

internal/helpers/interfaces.go

@@ -72,7 +72,8 @@ func buildCommands(factories []Factory, runner executor.Runner) []*cobra.Command
 	out := make([]*cobra.Command, 0, len(factories))
 	for _, factory := range factories {
 		handler := factory()
-		out = append(out, handler.Command(runner))
+		command := handler.Command(runner)
+		out = append(out, command)
 	}
 	sort.Slice(out, func(i, j int) bool {
 		return out[i].Use < out[j].Use

internal/helpers/live.go

@@ -20,14 +20,14 @@ func newLiveCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "live",
 		Short: "直播列表 / 信息",
 		Long:  `查看钉钉直播：列出我的直播记录。`,
 		RunE:  groupRunE,
-	}
+	})
 
-	streamCmd := &cobra.Command{Use: "stream", Short: "直播流管理", RunE: groupRunE}
+	streamCmd := newGroupCommand(&cobra.Command{Use: "stream", Short: "直播流管理", RunE: groupRunE})
 
 	streamListCmd := &cobra.Command{
 		Use:     "list",

internal/helpers/mail.go

@@ -113,14 +113,14 @@ func newMailCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "mail",
 		Short: "邮箱 / 邮件收发",
 		Long:  `管理钉钉企业邮箱：查询邮箱地址、搜索邮件、查看邮件、发送邮件、获取会话（thread）、列举文件夹、列举标签。`,
 		RunE:  groupRunE,
-	}
+	})
 
-	mailboxCmd := &cobra.Command{Use: "mailbox", Short: "邮箱地址管理", RunE: groupRunE}
+	mailboxCmd := newGroupCommand(&cobra.Command{Use: "mailbox", Short: "邮箱地址管理", RunE: groupRunE})
 
 	mailboxListCmd := &cobra.Command{
 		Use:   "list",
@@ -263,7 +263,7 @@ func newMailCommand() *cobra.Command {
 
 	mailboxCmd.AddCommand(mailboxListCmd, mailboxProfileCmd, mailboxSharedWithMeCmd)
 
-	messageCmd := &cobra.Command{Use: "message", Short: "邮件管理", RunE: groupRunE}
+	messageCmd := newGroupCommand(&cobra.Command{Use: "message", Short: "邮件管理", RunE: groupRunE})
 
 	messageSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -588,7 +588,7 @@ func newMailCommand() *cobra.Command {
 		},
 	})
 
-	folderCmd := &cobra.Command{Use: "folder", Short: "邮件文件夹管理", RunE: groupRunE}
+	folderCmd := newGroupCommand(&cobra.Command{Use: "folder", Short: "邮件文件夹管理", RunE: groupRunE})
 
 	folderListCmd := &cobra.Command{
 		Use:   "list",
@@ -842,7 +842,7 @@ func newMailCommand() *cobra.Command {
 
 	folderCmd.AddCommand(folderListCmd, folderCreateCmd, folderDeleteCmd, folderUpdateCmd)
 
-	tagCmd := &cobra.Command{Use: "tag", Short: "邮件标签管理", RunE: groupRunE}
+	tagCmd := newGroupCommand(&cobra.Command{Use: "tag", Short: "邮件标签管理", RunE: groupRunE})
 
 	tagListCmd := &cobra.Command{
 		Use:   "list",
@@ -995,7 +995,7 @@ func newMailCommand() *cobra.Command {
 
 	tagCmd.AddCommand(tagListCmd, tagCreateCmd, tagDeleteCmd, tagUpdateCmd)
 
-	threadCmd := &cobra.Command{Use: "thread", Short: "邮件会话管理", RunE: groupRunE}
+	threadCmd := newGroupCommand(&cobra.Command{Use: "thread", Short: "邮件会话管理", RunE: groupRunE})
 
 	threadListCmd := &cobra.Command{
 		Use:   "list",
@@ -1975,7 +1975,7 @@ internetMessageId 来源：message send / draft send / message reply / message r
 		},
 	})
 
-	attachmentCmd := &cobra.Command{Use: "attachment", Short: "邮件附件管理", RunE: groupRunE}
+	attachmentCmd := newGroupCommand(&cobra.Command{Use: "attachment", Short: "邮件附件管理", RunE: groupRunE})
 
 	attachmentListCmd := &cobra.Command{
 		Use:   "list",
@@ -2443,7 +2443,7 @@ internetMessageId 来源：message send / draft send / message reply / message r
 		messageReplyCmd, messageReplyAllCmd, messageForwardCmd,
 		messageBatchMoveCmd, messageBatchDeleteCmd, messageBatchModifyCmd, messageBatchGetCmd, messageVerifyCmd, messageExportCmd, messageShareToChatCmd)
 
-	sentMessageCmd := &cobra.Command{Use: "sent-message", Short: "已发送邮件管理", RunE: groupRunE}
+	sentMessageCmd := newGroupCommand(&cobra.Command{Use: "sent-message", Short: "已发送邮件管理", RunE: groupRunE})
 
 	sentMessageRecallCmd := &cobra.Command{
 		Use:   "recall",
@@ -2600,10 +2600,10 @@ internetMessageId 来源：message send / draft send / message reply / message r
 	_ = draftSendCmd.Flags().MarkHidden("sender")
 	draftSendCmd.Flags().String("id", "", "草稿邮件 ID (必填)")
 
-	draftCmd := &cobra.Command{Use: "draft", Short: "草稿管理", RunE: groupRunE}
+	draftCmd := newGroupCommand(&cobra.Command{Use: "draft", Short: "草稿管理", RunE: groupRunE})
 	draftCmd.AddCommand(draftCreateCmd, draftUpdateCmd, draftSendCmd)
 
-	userCmd := &cobra.Command{Use: "user", Short: "邮箱用户管理", RunE: groupRunE}
+	userCmd := newGroupCommand(&cobra.Command{Use: "user", Short: "邮箱用户管理", RunE: groupRunE})
 
 	userSearchCmd := &cobra.Command{
 		Use:   "search",
@@ -2707,7 +2707,7 @@ user 对象字段：
 
 	// ── template 子命令组 ──────────────────────────────────
 
-	templateCmd := &cobra.Command{Use: "template", Short: "邮件模板管理", RunE: groupRunE}
+	templateCmd := newGroupCommand(&cobra.Command{Use: "template", Short: "邮件模板管理", RunE: groupRunE})
 
 	templateCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -3057,7 +3057,7 @@ user 对象字段：
 
 	// ── contact 子命令组 ──────────────────────────────────
 
-	contactCmd := &cobra.Command{Use: "contact", Short: "邮件联系人管理", RunE: groupRunE}
+	contactCmd := newGroupCommand(&cobra.Command{Use: "contact", Short: "邮件联系人管理", RunE: groupRunE})
 
 	contactCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -3315,7 +3315,7 @@ user 对象字段：
 	contactCmd.AddCommand(contactCreateCmd, contactListCmd, contactUpdateCmd, contactBatchDeleteCmd)
 
 	// ── auto-reply 自动回复 ──────────────────────────────
-	autoReplyCmd := &cobra.Command{Use: "auto-reply", Short: "邮件自动回复管理", RunE: groupRunE}
+	autoReplyCmd := newGroupCommand(&cobra.Command{Use: "auto-reply", Short: "邮件自动回复管理", RunE: groupRunE})
 
 	autoReplyGetCmd := &cobra.Command{
 		Use:   "get",
@@ -3393,7 +3393,7 @@ user 对象字段：
 	autoReplyCmd.AddCommand(autoReplyGetCmd, autoReplyUpdateCmd)
 
 	// ── rule 收信规则 ────────────────────────────────────
-	ruleCmd := &cobra.Command{Use: "rule", Short: "收信规则管理", RunE: groupRunE}
+	ruleCmd := newGroupCommand(&cobra.Command{Use: "rule", Short: "收信规则管理", RunE: groupRunE})
 
 	ruleListCmd := &cobra.Command{
 		Use:   "list",
@@ -3578,7 +3578,7 @@ object 与 operation 合法组合：
 	ruleCmd.AddCommand(ruleListCmd, ruleCreateCmd, ruleUpdateCmd, ruleDeleteCmd, ruleAdjustCmd)
 
 	// ── allow-list 个人收信白名单 ────────────────────────────────
-	allowListCmd := &cobra.Command{Use: "allow-list", Short: "个人收信白名单管理", RunE: groupRunE}
+	allowListCmd := newGroupCommand(&cobra.Command{Use: "allow-list", Short: "个人收信白名单管理", RunE: groupRunE})
 
 	allowListListCmd := &cobra.Command{
 		Use:   "list",
@@ -3646,7 +3646,7 @@ object 与 operation 合法组合：
 	allowListCmd.AddCommand(allowListListCmd, allowListAddCmd, allowListRemoveCmd)
 
 	// ── block-list 个人收信黑名单 ────────────────────────────────
-	blockListCmd := &cobra.Command{Use: "block-list", Short: "个人收信黑名单管理", RunE: groupRunE}
+	blockListCmd := newGroupCommand(&cobra.Command{Use: "block-list", Short: "个人收信黑名单管理", RunE: groupRunE})
 
 	blockListListCmd := &cobra.Command{
 		Use:   "list",
@@ -3713,7 +3713,7 @@ object 与 operation 合法组合：
 	blockListRemoveCmd.Flags().String("entries", "", "逗号分隔的地址列表，支持邮件地址(如123@domain.com)或域名(如@domain.com)")
 	blockListCmd.AddCommand(blockListListCmd, blockListAddCmd, blockListRemoveCmd)
 
-	calendarCmd := &cobra.Command{Use: "calendar", Short: "邮箱日历管理", RunE: groupRunE}
+	calendarCmd := newGroupCommand(&cobra.Command{Use: "calendar", Short: "邮箱日历管理", RunE: groupRunE})
 	calendarListCmd := &cobra.Command{
 		Use:   "list",
 		Short: "列出用户可访问的日历列表",
@@ -3762,7 +3762,7 @@ object 与 operation 合法组合：
 	calendarListCmd.Flags().String("email", "", "用户的邮箱地址 (必填)")
 	calendarCmd.AddCommand(calendarListCmd)
 
-	calendarEventCmd := &cobra.Command{Use: "calendar-event", Short: "邮箱日历日程管理", RunE: groupRunE}
+	calendarEventCmd := newGroupCommand(&cobra.Command{Use: "calendar-event", Short: "邮箱日历日程管理", RunE: groupRunE})
 	calendarEventListCmd := &cobra.Command{
 		Use:   "list",
 		Short: "查询指定日历时间范围内的日程",

internal/helpers/markdown.go

@@ -46,12 +46,12 @@ func newMarkdownCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "markdown",
 		Short: "Markdown 文件处理",
 		Long:  "创建、覆盖、修补、对比和获取钉盘或文档空间中的原生 Markdown 文件。",
 		RunE:  groupRunE,
-	}
+	})
 	root.AddCommand(
 		newMarkdownFetchCmd(),
 		newMarkdownCreateCmd(),

internal/helpers/markdown_chunk.go

@@ -0,0 +1,349 @@
+package helpers
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"unicode/utf8"
+)
+
+// DefaultMarkdownChunkRunes lives in doc_write_pipeline.go and is the shared
+// limit for every chunked markdown write path.
+
+// MarkdownChunkPlan is the result of splitting markdown for append-mode writes.
+//
+// The contract is deliberately NOT strings.Join(Chunks, "") == content: the
+// server's mode=append inserts a brand new structure per call, so keeping a
+// table or a fenced code block intact across a boundary requires re-emitting its
+// header or its fence. Instead:
+//
+//   - len(Chunks) >= 1 always, so Chunks[0] is safe to index.
+//   - every chunk is at most Limit runes when Limit > 0.
+//   - every chunk is a complete, self-contained top-level block sequence: no
+//     half table, no unclosed fence, and no partial line unless a hard-split
+//     degradation is recorded for that boundary.
+//   - every boundary that changes the rendered structure appears in
+//     Degradations. An empty Degradations means ExpectedDocument() renders
+//     identically to the input.
+type MarkdownChunkPlan struct {
+	Chunks       []string              `json:"-"`
+	Limit        int                   `json:"limit"`
+	Degradations []MarkdownDegradation `json:"degradations,omitempty"`
+}
+
+// MarkdownDegradation records one boundary that could not be made invisible.
+type MarkdownDegradation struct {
+	Kind string `json:"kind"`
+	Tier string `json:"tier"`
+	// ChunkIndex is the chunk *before* the boundary this describes.
+	ChunkIndex int    `json:"chunkIndex"`
+	Line       int    `json:"line"`
+	Detail     string `json:"detail"`
+	// InjectedSuffix was appended to Chunks[ChunkIndex] and InjectedPrefix was
+	// prepended to Chunks[ChunkIndex+1] — the two halves of one repair, which
+	// live in different chunks and are therefore reported separately. They exist
+	// so a caller can strip them and recover the original content exactly.
+	InjectedSuffix string `json:"injectedSuffix,omitempty"`
+	InjectedPrefix string `json:"injectedPrefix,omitempty"`
+}
+
+// Degraded reports whether any boundary changed the rendered structure.
+func (p MarkdownChunkPlan) Degraded() bool { return len(p.Degradations) > 0 }
+
+// ExpectedDocument is the document the server is expected to hold once every
+// chunk has been appended. Readback verification must compare against this
+// rather than the original content, because repaired boundaries legitimately
+// differ from the input.
+//
+// It is a method rather than a field so a large document is not duplicated in
+// memory unless a caller actually verifies.
+func (p MarkdownChunkPlan) ExpectedDocument() string {
+	if len(p.Chunks) == 1 {
+		return p.Chunks[0]
+	}
+	return strings.Join(p.Chunks, "\n\n")
+}
+
+// Warnings renders one human-readable line per distinct degradation kind,
+// aggregated with a count and the affected line numbers.
+func (p MarkdownChunkPlan) Warnings() []string {
+	if len(p.Degradations) == 0 {
+		return nil
+	}
+	order := make([]string, 0, len(p.Degradations))
+	detail := map[string]string{}
+	lines := map[string][]int{}
+	for _, d := range p.Degradations {
+		if _, seen := detail[d.Kind]; !seen {
+			order = append(order, d.Kind)
+			detail[d.Kind] = d.Detail
+		}
+		lines[d.Kind] = append(lines[d.Kind], d.Line)
+	}
+	out := make([]string, 0, len(order))
+	for _, kind := range order {
+		at := lines[kind]
+		if len(at) == 1 {
+			out = append(out, fmt.Sprintf("内容过长已分片：%s（第 %d 行）", detail[kind], at[0]))
+			continue
+		}
+		out = append(out, fmt.Sprintf("内容过长已分片：%s（%d 处，首次在第 %d 行）",
+			detail[kind], len(at), at[0]))
+	}
+	return out
+}
+
+// Summary is the structured projection for command envelopes.
+func (p MarkdownChunkPlan) Summary() map[string]any {
+	return map[string]any{
+		"chunks":       len(p.Chunks),
+		"limit":        p.Limit,
+		"degraded":     p.Degraded(),
+		"degradations": p.Degradations,
+	}
+}
+
+// SplitMarkdownForAppend splits content into chunks that are each safe to send
+// as an independent update_document mode=append call. See MarkdownChunkPlan for
+// the exact contract.
+//
+// limitRunes <= 0 disables splitting and returns the content as a single chunk,
+// which callers use as an explicit "send it in one call whatever the size"
+// escape hatch.
+func SplitMarkdownForAppend(content string, limitRunes int) MarkdownChunkPlan {
+	normalized := normalizeMarkdownNewlines(content)
+	plan := MarkdownChunkPlan{Limit: limitRunes}
+	if limitRunes <= 0 || utf8.RuneCountInString(normalized) <= limitRunes {
+		plan.Chunks = []string{normalized}
+		return plan
+	}
+	scan := scanMarkdownStructure(normalized)
+	plan = scan.emit(plan)
+	if len(plan.Chunks) > 1 && scan.linkRefs > 0 {
+		plan.Degradations = append(plan.Degradations, MarkdownDegradation{
+			Kind: "link_reference_split", Tier: "soft", ChunkIndex: 0, Line: 0,
+			Detail: "文档含链接引用定义，分片后引用与定义可能不在同一片，链接会失效",
+		})
+	}
+	return plan
+}
+
+// normalizeMarkdownNewlines converts CRLF and lone CR to LF. Normalizing rather
+// than deleting matters: deleting a lone CR silently joins two lines.
+//
+// This runs unconditionally, including on the single-chunk path, so short and
+// long content never disagree about line endings.
+func normalizeMarkdownNewlines(content string) string {
+	if !strings.ContainsRune(content, '\r') {
+		return content
+	}
+	return strings.ReplaceAll(strings.ReplaceAll(content, "\r\n", "\n"), "\r", "\n")
+}
+
+// emit walks the content, choosing the best available boundary for each window.
+//
+// A chunk covering [a, b) is rendered as injection(a).prefix + content[a:b] +
+// injection(b).suffix, so both halves of a repair are decided by position and a
+// hard split can never leave a fence hanging open.
+func (s *markdownScan) emit(plan MarkdownChunkPlan) MarkdownChunkPlan {
+	limit := plan.Limit
+	start, startRune := 0, 0
+	skipReported := false
+	for {
+		prefix, owed, dropped := s.effectiveInjection(start, limit)
+		if dropped && !skipReported {
+			skipReported = true
+			plan.recordKind(s.lineOf(start), "repair_skipped", "soft",
+				"该结构的修复文本本身就超过分片上限，已放弃保留其结构")
+		}
+		prefixRunes := utf8.RuneCountInString(prefix)
+		if s.runesFrom(startRune) <= limit-prefixRunes {
+			// The tail carries the region's own terminator, so nothing is owed.
+			plan.Chunks = append(plan.Chunks, prefix+s.content[start:])
+			return plan
+		}
+
+		cand, ok := s.pick(start, startRune, limit-prefixRunes, limit)
+		if !ok {
+			reserve := 0
+			if owed != "" {
+				reserve = utf8.RuneCountInString(owed) + 1
+			}
+			cand = s.hardCandidate(start, startRune, limit-prefixRunes-reserve)
+		}
+
+		body := s.content[start:cand.offset]
+		if !cand.keepTrailing {
+			body = strings.TrimRight(body, " \t\n")
+		}
+		_, suffix, _ := s.effectiveInjection(cand.offset, limit)
+		sep := ""
+		if suffix != "" && body != "" && !strings.HasSuffix(body, "\n") {
+			sep = "\n" // the closing marker must start its own line
+		}
+		chunk := prefix + body + sep + suffix
+		if strings.TrimSpace(chunk) != "" {
+			plan.Chunks = append(plan.Chunks, chunk)
+			plan.record(s, cand, len(plan.Chunks)-1, suffix, limit)
+		}
+		start, startRune = cand.offset, cand.runeIdx
+	}
+}
+
+// effectiveInjection is injectionAt with the repair dropped when it cannot fit,
+// which is the only way to keep the per-window budget positive for a structure
+// whose own header or fence line is longer than the limit.
+func (s *markdownScan) effectiveInjection(offset, limit int) (prefix, suffix string, dropped bool) {
+	p, sfx := s.injectionAt(offset)
+	if p == "" && sfx == "" {
+		return "", "", false
+	}
+	prefixCost, suffixCost := s.injectionCostAt(offset)
+	if prefixCost+suffixCost >= limit {
+		return "", "", true
+	}
+	return p, sfx, false
+}
+
+// pick returns the best boundary in [start, start+budget]: the highest tier with
+// any candidate, and within that tier the latest one.
+//
+// Taking the latest candidate within a tier is not just an optimization. Every
+// chunk is appended to the same document, so within tierSafe the choice has no
+// effect on the final document at all — cutting early only costs extra chunks
+// and extra round trips.
+func (s *markdownScan) pick(start, startRune, budget, limit int) (splitCandidate, bool) {
+	maxRune := startRune + budget
+	for tier := splitTier(0); tier < splitTierCount; tier++ {
+		list := s.byTier[tier]
+		// Candidates are stored in ascending offset, so the binary search finds
+		// the first one past the window; everything before it is a candidate to
+		// walk back through.
+		hi := sort.Search(len(list), func(k int) bool { return s.cands[list[k]].trimRuneIdx > maxRune })
+		for j := hi - 1; j >= 0; j-- {
+			c := s.cands[list[j]]
+			if c.offset <= start {
+				break // this tier is exhausted within the window
+			}
+			prefix, suffix := s.injectionCostAt(c.offset)
+			if c.trimRuneIdx+suffix > maxRune {
+				continue // the closing injection does not fit
+			}
+			if prefix+suffix >= limit {
+				// The repair would consume the whole next window, so this
+				// candidate can never make progress. Rejecting it here is what
+				// removes the "repair does not fit" livelock: every accepted
+				// candidate leaves the next window at least one rune.
+				continue
+			}
+			return c, true
+		}
+	}
+	return splitCandidate{}, false
+}
+
+// hardCandidate is the last resort, used only when the window holds no
+// structural boundary at all — in practice, a single line longer than the limit.
+// It prefers the last whitespace within a bounded lookback so words survive,
+// and falls back to an exact rune cut.
+func (s *markdownScan) hardCandidate(start, startRune, budget int) splitCandidate {
+	// budget is always at least 1: effectiveInjection drops any repair whose
+	// prefix plus suffix would reach the limit, so the caller's
+	// limit-prefix-reserve arithmetic cannot go non-positive.
+	const lookback = 64
+	off, n := start, 0
+	spaceOff, spaceRune := -1, 0
+	for off < len(s.content) && n < budget {
+		r, size := utf8.DecodeRuneInString(s.content[off:])
+		off += size
+		n++
+		// Deliberately not '\n': a line boundary is a structural decision, and
+		// the tiers above already rejected every one in this window. Cutting at
+		// a newline here would resurrect exactly the boundaries they refused —
+		// a setext underline, for instance.
+		if r == ' ' || r == '\t' {
+			spaceOff, spaceRune = off, n
+		}
+	}
+	kind := candHardRune
+	if spaceOff > start && n-spaceRune <= lookback {
+		kind, off, n = candHardWhitespace, spaceOff, spaceRune
+	}
+	if s.offsetInHTML(start) {
+		// A hard cut inside HTML breaks a tag (this is a single oversized HTML
+		// line with no safe boundary). Flag it so the caller can point the user
+		// at uploading the block as a file instead.
+		kind = candHardHTML
+	}
+	return splitCandidate{
+		offset: off, runeIdx: startRune + n, line: int32(s.lineOf(off)),
+		region: -1, tier: tierRepair, kind: kind, keepTrailing: true,
+	}
+}
+
+// offsetInHTML reports whether the byte offset sits inside an HTML region.
+func (s *markdownScan) offsetInHTML(offset int) bool {
+	r := s.lines[s.lineIndexOf(offset)].region
+	return r >= 0 && s.regions[r].kind == regionHTML
+}
+
+// lineOf returns the 1-based line number containing the given byte offset. The
+// first line always starts at 0, so the search never returns 0.
+func (s *markdownScan) lineOf(offset int) int {
+	return sort.Search(len(s.lines), func(k int) bool { return s.lines[k].start > offset })
+}
+
+// record appends a degradation for the boundary, if it changed anything.
+func (p *MarkdownChunkPlan) record(s *markdownScan, c splitCandidate, chunkIndex int, suffix string, limit int) {
+	kind, tier, detail := degradationFor(c.kind)
+	if kind == "" {
+		return
+	}
+	// Report the injection that was actually used, not the one injectionAt would
+	// like to use: when the repair is dropped for not fitting, nothing is added.
+	prefix, _, _ := s.effectiveInjection(c.offset, limit)
+	p.Degradations = append(p.Degradations, MarkdownDegradation{
+		Kind: kind, Tier: tier, ChunkIndex: chunkIndex, Line: int(c.line),
+		Detail: detail, InjectedSuffix: suffix, InjectedPrefix: prefix,
+	})
+}
+
+// recordKind appends a degradation that no candidate describes.
+func (p *MarkdownChunkPlan) recordKind(line int, kind, tier, detail string) {
+	p.Degradations = append(p.Degradations, MarkdownDegradation{
+		Kind: kind, Tier: tier, ChunkIndex: len(p.Chunks), Line: line, Detail: detail,
+	})
+}
+
+func degradationFor(kind candidateKind) (string, string, string) {
+	switch kind {
+	case candParagraphLine:
+		return "paragraph_split", "soft", "长段落被拆成多个段落"
+	case candListItem:
+		return "list_split", "soft", "列表被拆成多个列表"
+	case candQuoteLine:
+		return "blockquote_split", "soft", "引用块被拆成多个引用块"
+	case candRegionBoundary:
+		return "block_boundary_split", "soft", "在块边界处切分，前后两块的解析结果可能与整体不同"
+	case candIndentedCodeLine:
+		return "indented_code_split", "soft", "缩进代码块被拆成多个代码块"
+	case candHTMLLine:
+		return "html_block_split", "soft", "HTML 块被拆开，标签可能不再配对；内容很大时建议存成文件后用 dws doc import 导入"
+	case candHTMLRepair:
+		return "html_block_split", "repair", "<pre>/<style>/<textarea> 块被拆成多个，每片各自重开并闭合标签；内容很大时可存成文件后用 dws doc import 导入"
+	case candOrderedListItem:
+		return "ordered_list_split", "repair", "有序列表被拆开，后续分片的编号可能从 1 重新开始"
+	case candTableRow:
+		return "table_split", "repair", "表格被拆成多个表格，后续分片重复表头行与分隔行"
+	case candFenceBody:
+		return "code_block_split", "repair", "代码块被拆成多个代码块，每片各自闭合围栏"
+	case candHardWhitespace:
+		return "hard_split_at_whitespace", "rune", "无结构切分点，已在空白处硬切"
+	case candHardRune:
+		return "hard_rune_split", "rune", "单行长度超过上限，已按字符硬切"
+	case candHardHTML:
+		return "html_tag_hard_split", "rune", "HTML 内容无法在不破坏标签的前提下切分，已硬切；建议将内容存成文件后用 dws doc import 导入"
+	default:
+		return "", "", "" // tierSafe boundaries change nothing
+	}
+}

internal/helpers/markdown_chunk_test.go

@@ -0,0 +1,764 @@
+package helpers
+
+import (
+	"fmt"
+	"math/rand"
+	"strings"
+	"testing"
+	"unicode/utf8"
+)
+
+// stripInjections undoes every repair the plan recorded, so what remains must be
+// the original content. Stripping is anchored (TrimSuffix on the chunk before the
+// boundary, TrimPrefix on the chunk after it) rather than a substring search,
+// which is why MarkdownDegradation reports the two halves separately.
+func stripInjections(p MarkdownChunkPlan) []string {
+	out := append([]string(nil), p.Chunks...)
+	for _, d := range p.Degradations {
+		if d.InjectedSuffix != "" && d.ChunkIndex < len(out) {
+			out[d.ChunkIndex] = strings.TrimSuffix(out[d.ChunkIndex], d.InjectedSuffix)
+		}
+		if d.InjectedPrefix != "" && d.ChunkIndex+1 < len(out) {
+			out[d.ChunkIndex+1] = strings.TrimPrefix(out[d.ChunkIndex+1], d.InjectedPrefix)
+		}
+	}
+	return out
+}
+
+// dropWhitespace removes every space, tab and newline. Comparing content with
+// whitespace removed is the strongest no-loss statement compatible with repairs:
+// boundary whitespace legitimately moves, but no other character may appear or
+// disappear.
+func dropWhitespace(s string) string {
+	return strings.Map(func(r rune) rune {
+		if r == ' ' || r == '\t' || r == '\n' {
+			return -1
+		}
+		return r
+	}, s)
+}
+
+// hasUnclosedFence replays the production fence rule over a single chunk. A
+// naive count of "```" cannot do this: a four-backtick fence legitimately
+// contains three-backtick lines, so only the state machine knows whether the
+// chunk ends inside a code block.
+func hasUnclosedFence(chunk string) bool {
+	scan := scanMarkdownStructure(normalizeMarkdownNewlines(chunk))
+	for _, r := range scan.regions {
+		if r.kind == regionFence && scan.lines[r.lastLine].kind != lineFenceClose {
+			return true
+		}
+	}
+	return false
+}
+
+func degradationKinds(p MarkdownChunkPlan) []string {
+	kinds := make([]string, 0, len(p.Degradations))
+	for _, d := range p.Degradations {
+		kinds = append(kinds, d.Kind)
+	}
+	return kinds
+}
+
+func TestCrossPlatformCoverageMarkdownChunkTierSelection(t *testing.T) {
+	for _, tc := range []struct {
+		name     string
+		content  string
+		limit    int
+		want     []string
+		wantKind []string
+	}{{
+		name:    "blank line boundary is invisible",
+		content: "alpha\n\nbravo\n\ncharlie",
+		limit:   12,
+		want:    []string{"alpha\n\nbravo", "charlie"},
+	}, {
+		// The heading interrupts the paragraph, so cutting right before it is
+		// safe even without a blank line. This is the boundary the previous
+		// implementation corrupted into "para# Title".
+		name:    "heading interrupts a paragraph",
+		content: "para\n# Title",
+		limit:   8,
+		want:    []string{"para", "# Title"},
+	}, {
+		// Greedy-latest within a tier: every chunk lands in the same document,
+		// so an earlier safe boundary would only cost an extra round trip.
+		// Aligning to the heading here would emit 3 chunks (10/84/30).
+		name:    "greedy within the safe tier",
+		content: strings.Repeat("a", 10) + "\n\n# h\n\n" + strings.Repeat("b", 80) + "\n\n" + strings.Repeat("c", 30),
+		limit:   100,
+		want: []string{
+			strings.Repeat("a", 10) + "\n\n# h\n\n" + strings.Repeat("b", 80),
+			strings.Repeat("c", 30),
+		},
+	}, {
+		name:     "paragraph soft break becomes two paragraphs",
+		content:  "first line\nsecond line",
+		limit:    12,
+		want:     []string{"first line", "second line"},
+		wantKind: []string{"paragraph_split"},
+	}, {
+		name:     "unordered list splits between items",
+		content:  "- alpha\n- bravo\n- charlie",
+		limit:    10,
+		want:     []string{"- alpha", "- bravo", "- charlie"},
+		wantKind: []string{"list_split", "list_split"},
+	}, {
+		// Ordered lists are repair tier, not soft: the server renumbers from 1,
+		// which is a visible change an unordered split does not cause.
+		name:     "ordered list split is heavier than unordered",
+		content:  "1. alpha\n2. bravo",
+		limit:    10,
+		want:     []string{"1. alpha", "2. bravo"},
+		wantKind: []string{"ordered_list_split"},
+	}, {
+		name:     "blockquote splits between lines",
+		content:  "> one\n> two\n> three",
+		limit:    8,
+		want:     []string{"> one", "> two", "> three"},
+		wantKind: []string{"blockquote_split", "blockquote_split"},
+	}, {
+		// Each half is still an indented code block, so no injection is needed —
+		// but one block becomes two.
+		name:     "indented code splits at a line boundary",
+		content:  "    code a\n    code b",
+		limit:    12,
+		want:     []string{"    code a", "    code b"},
+		wantKind: []string{"indented_code_split"},
+	}, {
+		name:     "single long line falls back to whitespace",
+		content:  "aaa bbb ccc ddd",
+		limit:    8,
+		want:     []string{"aaa bbb ", "ccc ddd"},
+		wantKind: []string{"hard_split_at_whitespace"},
+	}, {
+		name:     "single long word falls back to runes",
+		content:  strings.Repeat("界", 7),
+		limit:    3,
+		want:     []string{"界界界", "界界界", "界"},
+		wantKind: []string{"hard_rune_split", "hard_rune_split"},
+	}, {
+		name:    "leading blank lines never emit an empty chunk",
+		content: "\n\n\nalpha\n\nbravo",
+		limit:   6,
+		want:    []string{"alpha", "bravo"},
+	}} {
+		t.Run(tc.name, func(t *testing.T) {
+			plan := SplitMarkdownForAppend(tc.content, tc.limit)
+			if len(plan.Chunks) != len(tc.want) {
+				t.Fatalf("chunks = %#v, want %#v", plan.Chunks, tc.want)
+			}
+			for i, want := range tc.want {
+				if plan.Chunks[i] != want {
+					t.Errorf("chunk %d = %q, want %q", i, plan.Chunks[i], want)
+				}
+			}
+			if got := degradationKinds(plan); strings.Join(got, ",") != strings.Join(tc.wantKind, ",") {
+				t.Errorf("degradations = %v, want %v", got, tc.wantKind)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMarkdownChunkRepairsTablesAndFences(t *testing.T) {
+	t.Run("table repeats header and delimiter", func(t *testing.T) {
+		content := "| 姓名 | 部门 |\n|---|---|\n" + strings.Repeat("| 张三 | 技术部 |\n", 5)
+		plan := SplitMarkdownForAppend(content, 60)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("expected a split, got %#v", plan.Chunks)
+		}
+		header := "| 姓名 | 部门 |\n|---|---|\n"
+		for i, chunk := range plan.Chunks {
+			if !strings.HasPrefix(chunk, header) {
+				t.Errorf("chunk %d lost the header: %q", i, chunk)
+			}
+		}
+		for _, d := range plan.Degradations {
+			if d.Kind != "table_split" || d.InjectedPrefix != header {
+				t.Errorf("degradation = %#v", d)
+			}
+		}
+		// The repeated header is charged to the chunk that carries it.
+		for i, chunk := range plan.Chunks {
+			if n := utf8.RuneCountInString(chunk); n > 60 {
+				t.Errorf("chunk %d is %d runes, over the limit", i, n)
+			}
+		}
+	})
+
+	t.Run("fence closes and reopens with the original marker", func(t *testing.T) {
+		for _, open := range []string{"```go", "````", "~~~~", "~~~ yaml"} {
+			marker := open[:strings.LastIndexAny(open, "`~")+1]
+			content := open + "\n" + strings.Repeat("body\n", 6) + marker
+			plan := SplitMarkdownForAppend(content, 30)
+			if len(plan.Chunks) < 2 {
+				t.Fatalf("%q: expected a split, got %#v", open, plan.Chunks)
+			}
+			for i, chunk := range plan.Chunks {
+				if !strings.HasPrefix(chunk, open) {
+					t.Errorf("%q chunk %d lost the opening fence: %q", open, i, chunk)
+				}
+				if !strings.HasSuffix(chunk, marker) {
+					t.Errorf("%q chunk %d is not closed: %q", open, i, chunk)
+				}
+				if hasUnclosedFence(chunk) {
+					t.Errorf("%q chunk %d leaves a fence open: %q", open, i, chunk)
+				}
+			}
+		}
+	})
+
+	t.Run("fence interior keeps trailing blank lines", func(t *testing.T) {
+		content := "```\nalpha\n\n\nbravo\ncharlie\ndelta\n```"
+		plan := SplitMarkdownForAppend(content, 22)
+		joined := strings.Join(stripInjections(plan), "")
+		if dropWhitespace(joined) != dropWhitespace(content) {
+			t.Fatalf("content changed: %q", joined)
+		}
+		if !strings.Contains(strings.Join(plan.Chunks, "|"), "alpha\n\n\n") {
+			t.Errorf("blank lines inside the fence were trimmed: %#v", plan.Chunks)
+		}
+	})
+
+	t.Run("repair wider than the limit is dropped and reported", func(t *testing.T) {
+		// The reopening fence alone is longer than the limit, so preserving the
+		// structure is impossible; the splitter must say so rather than emit
+		// chunks over the limit or loop forever.
+		content := "```" + strings.Repeat("x", 40) + "\n" + strings.Repeat("body\n", 4) + "```"
+		plan := SplitMarkdownForAppend(content, 20)
+		for i, chunk := range plan.Chunks {
+			if n := utf8.RuneCountInString(chunk); n > 20 {
+				t.Errorf("chunk %d is %d runes, over the limit", i, n)
+			}
+		}
+		if !strings.Contains(strings.Join(degradationKinds(plan), ","), "repair_skipped") {
+			t.Errorf("expected repair_skipped, got %v", degradationKinds(plan))
+		}
+	})
+}
+
+func TestCrossPlatformCoverageMarkdownChunkHazards(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		content string
+		limit   int
+		// forbidden is a boundary that must never be chosen, expressed as the
+		// exact text a chunk would end with if it were.
+		forbidden string
+		wantKinds string
+	}{{
+		// `para\n---` is a setext H2, not a paragraph followed by a rule.
+		// Splitting there turns one heading into a paragraph plus a horizontal
+		// rule, so the dash line must not be treated as a block start.
+		name:      "setext underline with dashes",
+		content:   "para\n---\n\ntail text here",
+		limit:     10,
+		forbidden: "para",
+	}, {
+		name:      "setext underline with equals",
+		content:   "para\n===\n\ntail text here",
+		limit:     10,
+		forbidden: "para",
+	}, {
+		// A dash rule *is* safe when no paragraph is open above it.
+		name:    "dash rule after a blank line is safe",
+		content: "alpha\n\n---\n\nbravo",
+		limit:   9,
+	}, {
+		// `***` cannot be read as a setext underline, so it always interrupts.
+		name:    "asterisk rule interrupts a paragraph",
+		content: "para\n***\nmore text",
+		limit:   9,
+	}, {
+		// The blank line belongs to the code block, so it is not a safe boundary.
+		// Cutting is still allowed at the code block's own line boundaries, but
+		// it must be reported rather than treated as invisible.
+		name:      "indented code with an interior blank line",
+		content:   "    alpha\n\n    bravo",
+		limit:     11,
+		wantKinds: "indented_code_split",
+	}, {
+		// A loose list's interior blank line is inside the list.
+		name:      "loose list interior blank line",
+		content:   "- alpha\n\n  more\n- bravo",
+		limit:     16,
+		forbidden: "- alpha",
+	}, {
+		// Whether a table interrupts a paragraph is parser-dependent, so this
+		// boundary is allowed but must be reported, never treated as safe.
+		name:      "table header after a paragraph line is not safe",
+		content:   "para\n| a | b |\n|---|---|\n| 1 | 2 |",
+		limit:     24,
+		wantKinds: "block_boundary_split",
+	}, {
+		name:      "html block split is reported",
+		content:   "<div>\nalpha\nbravo\n</div>",
+		limit:     12,
+		wantKinds: "html_block_split",
+	}, {
+		name:      "link reference definitions are reported",
+		content:   "[ref]: https://example.com/one\n\nalpha text\n\nbravo text",
+		limit:     16,
+		wantKinds: "link_reference_split",
+	}} {
+		t.Run(tc.name, func(t *testing.T) {
+			plan := SplitMarkdownForAppend(tc.content, tc.limit)
+			for i, chunk := range plan.Chunks {
+				if n := utf8.RuneCountInString(chunk); n > tc.limit {
+					t.Errorf("chunk %d is %d runes, over the limit: %q", i, n, chunk)
+				}
+			}
+			if tc.forbidden != "" {
+				for i, chunk := range plan.Chunks {
+					if chunk == tc.forbidden {
+						t.Errorf("chunk %d cut at a forbidden boundary: %#v", i, plan.Chunks)
+					}
+				}
+			}
+			if tc.wantKinds != "" {
+				got := strings.Join(degradationKinds(plan), ",")
+				if !strings.Contains(got, tc.wantKinds) {
+					t.Errorf("degradations = %q, want to contain %q", got, tc.wantKinds)
+				}
+			}
+			joined := strings.Join(stripInjections(plan), "")
+			if dropWhitespace(joined) != dropWhitespace(normalizeMarkdownNewlines(tc.content)) {
+				t.Errorf("content changed:\n got %q\nwant %q", joined, tc.content)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMarkdownChunkEdgeContracts(t *testing.T) {
+	t.Run("limit disables splitting", func(t *testing.T) {
+		// Callers rely on this as an explicit "send it in one call whatever the
+		// size" escape hatch.
+		for _, limit := range []int{0, -1} {
+			plan := SplitMarkdownForAppend("alpha\nbravo\ncharlie", limit)
+			if len(plan.Chunks) != 1 || plan.Chunks[0] != "alpha\nbravo\ncharlie" {
+				t.Fatalf("limit=%d chunks = %#v", limit, plan.Chunks)
+			}
+			if plan.Degraded() {
+				t.Errorf("limit=%d must not degrade: %#v", limit, plan.Degradations)
+			}
+		}
+	})
+
+	t.Run("empty content yields one empty chunk", func(t *testing.T) {
+		// chunkedWrite and the doc shortcuts both index Chunks[0] unguarded.
+		plan := SplitMarkdownForAppend("", DefaultMarkdownChunkRunes)
+		if len(plan.Chunks) != 1 || plan.Chunks[0] != "" {
+			t.Fatalf("chunks = %#v", plan.Chunks)
+		}
+	})
+
+	t.Run("newlines are normalized on the single-chunk path too", func(t *testing.T) {
+		// Normalizing rather than deleting matters: deleting a lone CR silently
+		// joins two lines. Doing it unconditionally matters so short and long
+		// content never disagree.
+		for _, limit := range []int{5, DefaultMarkdownChunkRunes} {
+			plan := SplitMarkdownForAppend("a\r\nb\rc", limit)
+			if got := strings.Join(plan.Chunks, ""); !strings.Contains(got, "a\nb\nc") {
+				t.Errorf("limit=%d joined = %q, want CRLF and lone CR normalized", limit, got)
+			}
+		}
+	})
+
+	t.Run("whitespace-only content", func(t *testing.T) {
+		plan := SplitMarkdownForAppend("\n\n\n\n\n\n\n\n", 3)
+		if len(plan.Chunks) == 0 {
+			t.Fatal("plan must always hold at least one chunk")
+		}
+	})
+
+	t.Run("projections", func(t *testing.T) {
+		plan := SplitMarkdownForAppend("first line\nsecond line", 12)
+		if !plan.Degraded() {
+			t.Fatalf("expected a degraded plan: %#v", plan)
+		}
+		if got := plan.ExpectedDocument(); got != "first line\n\nsecond line" {
+			t.Errorf("ExpectedDocument = %q", got)
+		}
+		warnings := plan.Warnings()
+		if len(warnings) != 1 || !strings.Contains(warnings[0], "段落") {
+			t.Errorf("Warnings = %#v", warnings)
+		}
+		summary := plan.Summary()
+		if summary["chunks"] != 2 || summary["degraded"] != true || summary["limit"] != 12 {
+			t.Errorf("Summary = %#v", summary)
+		}
+
+		single := SplitMarkdownForAppend("short", DefaultMarkdownChunkRunes)
+		if single.Degraded() || single.Warnings() != nil {
+			t.Errorf("single chunk must not degrade: %#v", single)
+		}
+		if got := single.ExpectedDocument(); got != "short" {
+			t.Errorf("single ExpectedDocument = %q", got)
+		}
+	})
+
+	t.Run("warnings aggregate repeated kinds", func(t *testing.T) {
+		plan := SplitMarkdownForAppend("- a\n- b\n- c\n- d", 4)
+		warnings := plan.Warnings()
+		if len(warnings) != 1 || !strings.Contains(warnings[0], "处") {
+			t.Errorf("Warnings = %#v", warnings)
+		}
+	})
+}
+
+// TestCrossPlatformCoverageMarkdownChunkInvariantsOnSeededCorpus is the
+// regression net for the whole algorithm. The seed is fixed so a failure is
+// reproducible, and the corpus crosses every block type against limits small
+// enough to force each tier.
+//
+// The old block-rebuilding splitter failed the content invariant on roughly one
+// input in five, because it reassembled text instead of slicing it.
+func TestCrossPlatformCoverageMarkdownChunkInvariantsOnSeededCorpus(t *testing.T) {
+	generators := []func(n int) string{
+		func(n int) string { return fmt.Sprintf("# Heading %d", n) },
+		func(n int) string { return fmt.Sprintf("### Heading %d", n) },
+		func(n int) string { return strings.Repeat("文字", 1+n%9) },
+		func(n int) string { return "first line\nsecond line\nthird line" },
+		func(n int) string { return "| a | b |\n|---|---|\n" + strings.Repeat("| 1 | 2 |\n", 1+n%5) },
+		func(n int) string { return "```go\n" + strings.Repeat("code\n", 1+n%4) + "```" },
+		func(n int) string { return "~~~~\n" + strings.Repeat("t\n", 1+n%3) + "~~~~" },
+		func(n int) string { return "````\n``` nested\n````" },
+		func(n int) string { return "- alpha\n- bravo\n- charlie" },
+		func(n int) string { return "1. alpha\n2. bravo\n3. charlie" },
+		func(n int) string { return "- alpha\n\n  continued\n- bravo" },
+		func(n int) string { return "> quoted one\n> quoted two" },
+		func(n int) string { return "    indented\n\n    code" },
+		func(n int) string { return "setext heading\n---" },
+		func(n int) string { return "setext heading\n===" },
+		func(n int) string { return "***" },
+		func(n int) string { return strings.Repeat("x", 30+n%40) },
+		func(n int) string { return "word " + strings.Repeat("wordy ", 6+n%5) },
+		func(n int) string { return "a\r\nb\rc" },
+		func(n int) string { return "<div>\nhtml body\n</div>" },
+		func(n int) string { return "<script>\n\nstill script\n</script>" },
+		func(n int) string { return "<pre>\n" + strings.Repeat("pre line\n", 1+n%4) + "</pre>" },
+		func(n int) string { return "<pre>\nfirst\n\nafter blank\n</pre>" },
+		func(n int) string { return "<pre\n  class=\"c\">\n" + strings.Repeat("x\n", 1+n%3) + "</pre>" },
+		func(n int) string { return "<style>\n" + strings.Repeat(".a{b:1}\n", 1+n%3) + "</style>" },
+		func(n int) string { return "<textarea>\n" + strings.Repeat("row\n", 1+n%3) + "</textarea>" },
+		func(n int) string { return "[ref]: https://example.com/x" },
+	}
+	limits := []int{1, 2, 3, 7, 17, 64, 200}
+	rng := rand.New(rand.NewSource(20260817))
+
+	for iter := 0; iter < 4000; iter++ {
+		var parts []string
+		for k := 0; k < 1+rng.Intn(6); k++ {
+			parts = append(parts, generators[rng.Intn(len(generators))](rng.Intn(10)))
+		}
+		content := strings.Join(parts, "\n\n")
+		limit := limits[rng.Intn(len(limits))]
+		plan := SplitMarkdownForAppend(content, limit)
+		normalized := normalizeMarkdownNewlines(content)
+
+		fail := func(format string, args ...any) {
+			t.Fatalf("seed=20260817 iter=%d limit=%d content=%q\n"+format,
+				append([]any{iter, limit, normalized}, args...)...)
+		}
+
+		// I1: a plan always has an indexable first chunk.
+		if len(plan.Chunks) == 0 {
+			fail("empty plan")
+		}
+		// I2: no chunk exceeds the limit, injections included.
+		for i, chunk := range plan.Chunks {
+			if n := utf8.RuneCountInString(chunk); n > limit {
+				fail("chunk %d is %d runes: %q", i, n, chunk)
+			}
+		}
+		// I3: stripping the recorded repairs recovers the content exactly.
+		if got := dropWhitespace(strings.Join(stripInjections(plan), "")); got != dropWhitespace(normalized) {
+			fail("content changed:\n got %q\nwant %q", got, dropWhitespace(normalized))
+		}
+		// I4 and I5 assume the structure could be preserved. When the limit is
+		// smaller than a fence line or a table header, the plan says so via
+		// repair_skipped and no self-containedness claim is being made.
+		if strings.Contains(strings.Join(degradationKinds(plan), ","), "repair_skipped") {
+			continue
+		}
+		// I4: no chunk ends inside a code block.
+		for i, chunk := range plan.Chunks {
+			if hasUnclosedFence(chunk) {
+				fail("chunk %d leaves a fence open: %q", i, chunk)
+			}
+		}
+		// I5: a table body row is never orphaned from its header, so no chunk
+		// may open with a delimiter row.
+		for i, chunk := range plan.Chunks {
+			if first := strings.SplitN(chunk, "\n", 2)[0]; isTableDelimiterRow(strings.TrimSpace(first)) {
+				fail("chunk %d starts with a delimiter row: %q", i, chunk)
+			}
+		}
+	}
+}
+
+// TestCrossPlatformCoverageMarkdownChunkDegradationBookkeeping pins the contracts
+// that decide the ExpectedDocument / degradations story every caller depends on.
+// The seeded corpus exercises these paths but asserts only aggregate invariants;
+// these cases assert the exact field values, so an off-by-one in ChunkIndex or a
+// wrong ExpectedDocument join can never pass silently.
+func TestCrossPlatformCoverageMarkdownChunkDegradationBookkeeping(t *testing.T) {
+	t.Run("ChunkIndex points at the chunk before each boundary", func(t *testing.T) {
+		// Four list items, each within the limit, split into four chunks with a
+		// degradation at each of the three boundaries, indexed 0,1,2.
+		plan := SplitMarkdownForAppend("- aa\n- bb\n- cc\n- dd", 5)
+		if len(plan.Chunks) != 4 || len(plan.Degradations) != 3 {
+			t.Fatalf("chunks=%#v degradations=%#v", plan.Chunks, plan.Degradations)
+		}
+		for i, d := range plan.Degradations {
+			if d.ChunkIndex != i {
+				t.Errorf("degradation %d has ChunkIndex %d, want %d", i, d.ChunkIndex, i)
+			}
+		}
+	})
+
+	t.Run("ExpectedDocument carries the repeated table header", func(t *testing.T) {
+		// This is the case ExpectedDocument exists for: after a table repair the
+		// server holds N tables, so verification must expect the repeated header,
+		// not the single-table input.
+		header := "| a | b |\n|---|---|\n"
+		content := header + strings.Repeat("| 1 | 2 |\n", 6)
+		plan := SplitMarkdownForAppend(content, 40)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("fixture must split, got %d chunk(s)", len(plan.Chunks))
+		}
+		expected := plan.ExpectedDocument()
+		// The header appears once per chunk, i.e. more often than in the input.
+		if got, want := strings.Count(expected, "| a | b |"), len(plan.Chunks); got != want {
+			t.Errorf("header appears %d times in ExpectedDocument, want %d", got, want)
+		}
+		// ExpectedDocument is exactly the chunks joined with a blank line, and it
+		// re-parses without any orphaned delimiter row.
+		if expected != strings.Join(plan.Chunks, "\n\n") {
+			t.Errorf("ExpectedDocument is not the chunks joined by a blank line")
+		}
+		rescan := SplitMarkdownForAppend(expected, len(expected)*4)
+		if len(rescan.Chunks) != 1 || rescan.Degraded() {
+			t.Errorf("ExpectedDocument does not round-trip as one clean document: %#v", rescan)
+		}
+	})
+
+	t.Run("one document reports every distinct degradation kind", func(t *testing.T) {
+		// A realistic mixed document: an oversized table, an oversized fenced
+		// code block, and a long paragraph, each forced to split by the limit.
+		content := strings.Join([]string{
+			"| a | b |\n|---|---|\n" + strings.Repeat("| 1 | 2 |\n", 6),
+			"```go\n" + strings.Repeat("fmt.Println(1)\n", 6) + "```",
+			strings.Repeat("word ", 40),
+		}, "\n\n")
+		plan := SplitMarkdownForAppend(content, 45)
+
+		kinds := map[string]bool{}
+		lastLineByKind := map[string]int{}
+		for _, d := range plan.Degradations {
+			kinds[d.Kind] = true
+			// Lines within a kind are reported in ascending order.
+			if prev, seen := lastLineByKind[d.Kind]; seen && d.Line < prev {
+				t.Errorf("%s degradation lines out of order: %d after %d", d.Kind, d.Line, prev)
+			}
+			lastLineByKind[d.Kind] = d.Line
+		}
+		for _, want := range []string{"table_split", "code_block_split"} {
+			if !kinds[want] {
+				t.Errorf("missing %s in %v", want, degradationKinds(plan))
+			}
+		}
+		// Stripping every recorded repair still recovers the whole document.
+		if got := dropWhitespace(strings.Join(stripInjections(plan), "")); got != dropWhitespace(content) {
+			t.Errorf("mixed document not recoverable after stripping injections")
+		}
+	})
+
+	t.Run("regression: large document ending in a heading keeps the newline", func(t *testing.T) {
+		// The bug that started this rewrite: the old splitter rebuilt block text
+		// and dropped the newline before a trailing heading/table/fence, so a
+		// heading at the very end stopped being a heading. Reproduce it at
+		// production scale.
+		body := strings.Repeat("这是一段正文内容。\n\n", 6000) // ~60k runes, no trailing newline
+		content := body + "## 附录"
+		plan := SplitMarkdownForAppend(content, DefaultMarkdownChunkRunes)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("fixture must exceed the limit, got %d chunk(s)", len(plan.Chunks))
+		}
+		// The heading must survive as its own line, never glued to preceding text.
+		last := plan.Chunks[len(plan.Chunks)-1]
+		if !strings.Contains(last, "\n## 附录") {
+			r := []rune(last)
+			t.Fatalf("trailing heading is not on its own line: %q", string(r[max(0, len(r)-30):]))
+		}
+		// The original bug produced a single line like "正文内容。## 附录". Assert no
+		// chunk has body text and the heading marker on the same line.
+		for i, chunk := range plan.Chunks {
+			for _, line := range strings.Split(chunk, "\n") {
+				if strings.Contains(line, "。##") {
+					t.Errorf("chunk %d glued the heading onto a text line: %q", i, line)
+				}
+			}
+		}
+		// And nothing was lost.
+		if got := dropWhitespace(strings.Join(plan.Chunks, "")); got != dropWhitespace(normalizeMarkdownNewlines(content)) {
+			t.Error("content changed at production scale")
+		}
+	})
+
+	t.Run("repaired chunks stay within the limit at the production limit", func(t *testing.T) {
+		// The concern: a continuation chunk carries a re-emitted table header, so
+		// could header + rows push it over the limit? No — the header is charged
+		// against the window budget before rows are packed. The seeded corpus
+		// proves this at tiny limits where the header dwarfs the limit; this pins
+		// it at the real DefaultMarkdownChunkRunes with a wide header, which is the
+		// value that actually ships.
+		limit := DefaultMarkdownChunkRunes
+		const cols = 40
+		header := "|" + strings.Repeat(" 列名称占位 |", cols) + "\n"
+		delim := "|" + strings.Repeat("---|", cols) + "\n"
+		row := "|" + strings.Repeat(" 单元格数据 |", cols) + "\n"
+		content := header + delim + strings.Repeat(row, limit/utf8.RuneCountInString(row)+50)
+
+		plan := SplitMarkdownForAppend(content, limit)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("fixture must split, got %d chunk(s)", len(plan.Chunks))
+		}
+		sawInjectedContinuation := false
+		for i, chunk := range plan.Chunks {
+			if n := utf8.RuneCountInString(chunk); n > limit {
+				t.Errorf("chunk %d is %d runes, over the limit %d", i, n, limit)
+			}
+			if i > 0 && strings.HasPrefix(chunk, header) {
+				sawInjectedContinuation = true
+			}
+		}
+		if !sawInjectedContinuation {
+			t.Error("expected at least one continuation chunk carrying the re-emitted header")
+		}
+	})
+
+	t.Run("closed pre block does not swallow a following oversized table", func(t *testing.T) {
+		// Regression for the type-1 HTML closer bug: <pre>/<style>/<textarea> were
+		// all classified as type 1 but the terminator search only looked for
+		// </script>, so a closed <pre> block swallowed the rest of the document.
+		// A following oversized table would then be cut as HTML lines with no
+		// header re-emitted, leaving invalid tables downstream.
+		header := "| a | b |\n|---|---|\n"
+		table := header + strings.Repeat("| 1 | 2 |\n", 12)
+		for _, open := range []string{"<pre>", "<style>", "<textarea>"} {
+			closer := strings.Replace(open, "<", "</", 1)
+			content := open + "\ninner\n" + closer + "\n\n" + table
+			plan := SplitMarkdownForAppend(content, 40)
+
+			kinds := strings.Join(degradationKinds(plan), ",")
+			if !strings.Contains(kinds, "table_split") {
+				t.Errorf("%s: table was not split as a table (degradations=%q)", open, kinds)
+			}
+			if strings.Contains(kinds, "html_block_split") {
+				t.Errorf("%s: table was cut as HTML lines (degradations=%q)", open, kinds)
+			}
+			// Every continuation chunk of the table carries the re-emitted header.
+			for i, chunk := range plan.Chunks {
+				if i > 0 && strings.Contains(chunk, "| 1 | 2 |") && !strings.HasPrefix(chunk, header) {
+					t.Errorf("%s: chunk %d has table rows without the header: %q", open, i, chunk)
+				}
+			}
+		}
+	})
+}
+
+func TestCrossPlatformCoverageMarkdownChunkHTMLRepair(t *testing.T) {
+	t.Run("pre style textarea reopen and close on every chunk", func(t *testing.T) {
+		for _, tc := range []struct{ open, close string }{
+			{"<pre>", "</pre>"}, {"<style>", "</style>"}, {"<textarea>", "</textarea>"},
+		} {
+			content := tc.open + "\n" + strings.Repeat("row\n", 8) + tc.close
+			// Limit large enough for the injected tags plus one content line.
+			plan := SplitMarkdownForAppend(content, len(tc.open)+len(tc.close)+8)
+			if len(plan.Chunks) < 2 {
+				t.Fatalf("%s: expected a split, got %d", tc.open, len(plan.Chunks))
+			}
+			for i, chunk := range plan.Chunks {
+				if !strings.HasPrefix(chunk, tc.open) {
+					t.Errorf("%s: chunk %d not reopened: %q", tc.open, i, chunk)
+				}
+				if !strings.HasSuffix(chunk, tc.close) {
+					t.Errorf("%s: chunk %d not closed: %q", tc.open, i, chunk)
+				}
+			}
+			for _, d := range plan.Degradations {
+				if d.Kind != "html_block_split" || d.Tier != "repair" || d.InjectedPrefix == "" {
+					t.Errorf("%s: degradation = %#v", tc.open, d)
+				}
+			}
+			// Content recoverable after stripping the injected tags.
+			if got := dropWhitespace(strings.Join(stripInjections(plan), "")); got != dropWhitespace(content) {
+				t.Errorf("%s: content changed after strip: %q", tc.open, got)
+			}
+		}
+	})
+
+	t.Run("multi-line opening tag is reopened in full", func(t *testing.T) {
+		open := "<pre\n  class=\"code\"\n  id=\"x\">"
+		content := open + "\n" + strings.Repeat("content line\n", 6) + "</pre>"
+		plan := SplitMarkdownForAppend(content, 60)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("expected a split, got %d", len(plan.Chunks))
+		}
+		for i, chunk := range plan.Chunks {
+			if i > 0 && !strings.HasPrefix(chunk, open) {
+				t.Errorf("chunk %d did not reopen the full multi-line tag: %q", i, chunk)
+			}
+			if n := utf8.RuneCountInString(chunk); n > 60 {
+				t.Errorf("chunk %d is %d runes, over the limit", i, n)
+			}
+		}
+	})
+
+	t.Run("interior blank line is preserved, never a silent safe split", func(t *testing.T) {
+		content := "<pre>\nbefore\n\nafter\n</pre>"
+		plan := SplitMarkdownForAppend(content, 16)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("expected a split, got %d", len(plan.Chunks))
+		}
+		// The blank inside the pre must not be treated as a boundary-free safe
+		// cut: splitting inside a <pre> must be reported, and content survives.
+		if len(plan.Degradations) == 0 {
+			t.Error("splitting inside a <pre> must be reported, not silent")
+		}
+		if got := dropWhitespace(strings.Join(stripInjections(plan), "")); got != dropWhitespace(content) {
+			t.Errorf("blank line lost: %q", got)
+		}
+	})
+
+	t.Run("script is never repaired", func(t *testing.T) {
+		content := "<script>\n" + strings.Repeat("var x=1\n", 6) + "</script>"
+		plan := SplitMarkdownForAppend(content, 20)
+		if len(plan.Chunks) < 2 {
+			t.Fatalf("expected a split, got %d", len(plan.Chunks))
+		}
+		for i, chunk := range plan.Chunks {
+			if i > 0 && strings.HasPrefix(chunk, "<script>") {
+				t.Errorf("chunk %d reopened <script> — script must not be repaired: %q", i, chunk)
+			}
+		}
+		for _, d := range plan.Degradations {
+			if d.Tier == "repair" && d.Kind == "html_block_split" {
+				t.Errorf("script was repaired: %#v", d)
+			}
+		}
+	})
+
+	t.Run("oversized single HTML line reports html_tag_hard_split with upload guidance", func(t *testing.T) {
+		content := "<div>" + strings.Repeat("x", 60) + "</div>"
+		plan := SplitMarkdownForAppend(content, 20)
+		if !strings.Contains(strings.Join(degradationKinds(plan), ","), "html_tag_hard_split") {
+			t.Fatalf("expected html_tag_hard_split, got %v", degradationKinds(plan))
+		}
+		joined := strings.Join(plan.Warnings(), " ")
+		if !strings.Contains(joined, "doc import") {
+			t.Errorf("warning must point at dws doc import: %q", joined)
+		}
+	})
+}

internal/helpers/markdown_scan_test.go

@@ -0,0 +1,399 @@
+package helpers
+
+import (
+	"strings"
+	"testing"
+)
+
+// These are the CommonMark/GFM line predicates the whole tier model rests on.
+// They are tested directly because a misclassification here silently downgrades
+// or upgrades a split tier, and an upgraded tier corrupts documents.
+
+func TestCrossPlatformCoverageMarkdownScanLinePredicates(t *testing.T) {
+	t.Run("leadingIndent counts tabs as four columns", func(t *testing.T) {
+		for _, tc := range []struct {
+			line string
+			want int
+		}{
+			{"none", 0}, {"  two", 2}, {"\ttab", 4}, {" \ttab", 4}, {"\t\t", 8}, {"    ", 4},
+		} {
+			if got := leadingIndent(tc.line); got != tc.want {
+				t.Errorf("leadingIndent(%q) = %d, want %d", tc.line, got, tc.want)
+			}
+		}
+	})
+
+	t.Run("fenceMarkerOf requires three or more markers", func(t *testing.T) {
+		for _, tc := range []struct {
+			line  string
+			ch    byte
+			n     int
+			ok    bool
+			isOpe bool
+		}{
+			{"```", '`', 3, true, true},
+			{"```go", '`', 3, true, true},
+			{"````", '`', 4, true, true},
+			{"~~~", '~', 3, true, true},
+			{"~~~ yaml", '~', 3, true, true},
+			{"``", 0, 0, false, false},      // too short to fence
+			{"`code`", 0, 0, false, false},  // inline code
+			{"text", 0, 0, false, false},    // not a marker at all
+			{"", 0, 0, false, false},        // blank line inside a fence
+			{"```a`b", '`', 3, true, false}, // backtick in the info string
+		} {
+			ch, n, ok := fenceMarkerOf(tc.line)
+			if ch != tc.ch || n != tc.n || ok != tc.ok {
+				t.Errorf("fenceMarkerOf(%q) = %q,%d,%v want %q,%d,%v", tc.line, ch, n, ok, tc.ch, tc.n, tc.ok)
+			}
+			if got := isFenceOpen(tc.line); got != tc.isOpe {
+				t.Errorf("isFenceOpen(%q) = %v, want %v", tc.line, got, tc.isOpe)
+			}
+		}
+	})
+
+	t.Run("closingFenceIsBare rejects a trailing info string", func(t *testing.T) {
+		for _, tc := range []struct {
+			line string
+			ch   byte
+			n    int
+			want bool
+		}{
+			{"```", '`', 3, true},
+			{"```  ", '`', 3, true},
+			{"`````", '`', 3, true}, // a longer run still closes
+			{"```go", '`', 3, false},
+		} {
+			if got := closingFenceIsBare(tc.line, tc.ch, tc.n); got != tc.want {
+				t.Errorf("closingFenceIsBare(%q) = %v, want %v", tc.line, got, tc.want)
+			}
+		}
+	})
+
+	t.Run("isATXHeading", func(t *testing.T) {
+		for line, want := range map[string]bool{
+			"# h": true, "###### h": true, "#": true, "#hash": false,
+			"####### too deep": false, "text": false, "": false, "#\tt": true,
+		} {
+			if got := isATXHeading(line); got != want {
+				t.Errorf("isATXHeading(%q) = %v, want %v", line, got, want)
+			}
+		}
+	})
+
+	t.Run("isRunOf and isThematicBreak", func(t *testing.T) {
+		for _, tc := range []struct {
+			line     string
+			runDash  bool
+			breakAst bool
+		}{
+			{"---", true, false},
+			{"-", true, false},
+			{"", false, false},
+			{"-x-", false, false},
+			{"***", false, true},
+			{"* * *", false, true}, // interior spaces are allowed
+			{"**", false, false},   // fewer than three
+			{"*x*", false, false},
+		} {
+			if got := isRunOf(tc.line, '-'); got != tc.runDash {
+				t.Errorf("isRunOf(%q,'-') = %v, want %v", tc.line, got, tc.runDash)
+			}
+			if got := isThematicBreak(tc.line, '*'); got != tc.breakAst {
+				t.Errorf("isThematicBreak(%q,'*') = %v, want %v", tc.line, got, tc.breakAst)
+			}
+		}
+	})
+
+	t.Run("isTableDelimiterRow requires a pipe", func(t *testing.T) {
+		for line, want := range map[string]bool{
+			"|---|---|":      true,
+			"---|---":        true,
+			"| :-: | ---: |": true,
+			"---":            false, // a thematic break or setext underline, never a table
+			"--":             false,
+			"| a | b |":      false, // a header row, not a delimiter
+			"|":              false,
+			"| |":            false, // empty cell, and no dash
+			"|---|x|":        false, // one cell is not a run of dashes
+			"|---| |":        false, // one cell is empty
+			"":               false,
+		} {
+			if got := isTableDelimiterRow(line); got != want {
+				t.Errorf("isTableDelimiterRow(%q) = %v, want %v", line, got, want)
+			}
+		}
+	})
+
+	t.Run("tableCellCount", func(t *testing.T) {
+		for line, want := range map[string]int{
+			"| a | b |": 2, "a | b": 2, "| a |": 1, "no pipes": 0,
+		} {
+			if got := tableCellCount(line); got != want {
+				t.Errorf("tableCellCount(%q) = %d, want %d", line, got, want)
+			}
+		}
+	})
+
+	t.Run("listMarkerOf", func(t *testing.T) {
+		for _, tc := range []struct {
+			line       string
+			ordered    bool
+			contentCol int
+			ok         bool
+		}{
+			{"- item", false, 2, true},
+			{"+ item", false, 2, true},
+			{"* item", false, 2, true},
+			{"1. item", true, 3, true},
+			{"12) item", true, 4, true},
+			{"-", false, 1, true},          // a marker with no content
+			{"-     wide", false, 2, true}, // more than four spaces resets to one
+			{"  - nested", false, 4, true}, // indentation is included
+			{"-item", false, 0, false},     // no space after the marker
+			{"1.item", false, 0, false},    // no space after the number
+			{"1x item", false, 0, false},   // not a marker
+			{"text", false, 0, false},
+			{"", false, 0, false},
+			{"   ", false, 0, false}, // whitespace only
+		} {
+			ordered, col, ok := listMarkerOf(tc.line)
+			if ordered != tc.ordered || ok != tc.ok || (ok && col != tc.contentCol) {
+				t.Errorf("listMarkerOf(%q) = %v,%d,%v want %v,%d,%v",
+					tc.line, ordered, col, ok, tc.ordered, tc.contentCol, tc.ok)
+			}
+		}
+	})
+
+	t.Run("listMarkerNumber", func(t *testing.T) {
+		for line, want := range map[string]int{
+			"1. a": 1, "7. a": 7, "12) a": 12, "- a": 0,
+		} {
+			if got := listMarkerNumber(line); got != want {
+				t.Errorf("listMarkerNumber(%q) = %d, want %d", line, got, want)
+			}
+		}
+	})
+
+	t.Run("htmlBlockKind classifies the seven types", func(t *testing.T) {
+		for _, tc := range []struct {
+			line string
+			kind uint8
+			ok   bool
+		}{
+			{"<script>", 1, true},
+			{"<PRE>", 1, true},
+			{"<style>", 1, true},
+			{"<textarea>", 1, true},
+			{"<!-- comment", 2, true},
+			{"<?php", 3, true},
+			{"<!DOCTYPE html>", 4, true},
+			{"<![CDATA[", 5, true},
+			{"<div>", 6, true},
+			{"</ul>", 6, true},
+			{"<custom-tag>", 7, true},
+			{"<1>", 0, false}, // a tag name may not start with a digit
+			{"<>", 0, false},  // no tag name at all
+			{"</>", 0, false}, // closing marker with no name
+			{"text", 0, false},
+			{"", 0, false},
+		} {
+			kind, ok := htmlBlockKind(tc.line)
+			if kind != tc.kind || ok != tc.ok {
+				t.Errorf("htmlBlockKind(%q) = %d,%v want %d,%v", tc.line, kind, ok, tc.kind, tc.ok)
+			}
+		}
+	})
+
+	t.Run("htmlCloser per type", func(t *testing.T) {
+		for kind, want := range map[uint8]string{2: "-->", 3: "?>", 4: ">", 5: "]]>", 1: "</script>"} {
+			if got := htmlCloser(kind); got != want {
+				t.Errorf("htmlCloser(%d) = %q, want %q", kind, got, want)
+			}
+		}
+	})
+
+	t.Run("isLinkReferenceDefinition", func(t *testing.T) {
+		for line, want := range map[string]bool{
+			"[ref]: https://example.com": true, "[a]: x": true,
+			"[]: x": false, "[ref] not a def": false, "text": false, "": false,
+		} {
+			if got := isLinkReferenceDefinition(line); got != want {
+				t.Errorf("isLinkReferenceDefinition(%q) = %v, want %v", line, got, want)
+			}
+		}
+	})
+
+	t.Run("trimTrailingWhitespaceEnd", func(t *testing.T) {
+		for _, tc := range []struct {
+			content string
+			end     int
+			want    int
+		}{
+			{"abc\n\n", 5, 3}, {"abc", 3, 3}, {"\n\n\n", 3, 0}, {"a \t\n", 4, 1},
+		} {
+			if got := trimTrailingWhitespaceEnd(tc.content, tc.end); got != tc.want {
+				t.Errorf("trimTrailingWhitespaceEnd(%q,%d) = %d, want %d", tc.content, tc.end, got, tc.want)
+			}
+		}
+	})
+}
+
+func TestCrossPlatformCoverageMarkdownScanRegionGrouping(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		content string
+		// wantKinds lists the region kind of each region, in order.
+		wantKinds []regionKind
+	}{
+		{"unterminated fence swallows the tail", "before\n\n```go\nnever closed\nmore",
+			[]regionKind{regionParagraph, regionFence}},
+		{"indented fence is still a fence", "  ```go\ncode\n  ```",
+			[]regionKind{regionFence}},
+		{"quote ends at a heading", "> quoted\n# heading",
+			[]regionKind{regionQuote, regionLeaf}},
+		{"quote absorbs a lazy continuation", "> quoted\nlazy line\n\nafter",
+			[]regionKind{regionQuote, regionParagraph}},
+		{"setext beats a table delimiter", "heading\n---",
+			[]regionKind{regionSetext}},
+		{"delimiter row with a mismatched header is not a table", "para\n|---|---|---|",
+			[]regionKind{regionParagraph}},
+		{"table keeps rows that have no pipes", "| a | b |\n|---|---|\n| 1 | 2 |\nstray",
+			[]regionKind{regionTable}},
+		{"paragraph before a table is its own region", "intro\n| a | b |\n|---|---|\n| 1 | 2 |",
+			[]regionKind{regionParagraph, regionTable}},
+		{"list ends at an unindented paragraph", "- item\n\nplain paragraph",
+			[]regionKind{regionList, regionParagraph}},
+		{"list ends at an adjacent heading with no blank line", "- item\n# heading",
+			[]regionKind{regionList, regionLeaf}},
+		{"list ends at end of input after a blank line", "- item\n\n",
+			[]regionKind{regionList}},
+		{"list keeps an indented continuation across a blank line", "- item\n\n  continued\n\nplain",
+			[]regionKind{regionList, regionParagraph}},
+		{"html type 6 ends at a blank line", "<div>\nbody\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		{"html type 1 spans blank lines", "<script>\n\nstill script\n</script>\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		// Each type-1 tag must end at its OWN closer, not only </script>; a
+		// mis-terminated <pre>/<style>/<textarea> would swallow everything after it.
+		{"html type 1 pre ends at its own closer", "<pre>\ncode\n</pre>\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		{"html type 1 style ends at its own closer", "<style>\n.x{}\n</style>\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		{"html type 1 textarea ends at its own closer", "<textarea>\nhi\n</textarea>\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		{"html type 2 comment ends at its own terminator", "<!-- note -->\n\nafter",
+			[]regionKind{regionHTML, regionParagraph}},
+		{"html type 2 comment without a terminator runs to end of input", "<!--\nunclosed comment",
+			[]regionKind{regionHTML}},
+		{"indented code spans a blank line", "    one\n\n    two\n\nplain",
+			[]regionKind{regionIndentedCode, regionParagraph}},
+		{"link reference definition is a leaf", "[ref]: https://example.com\n\npara",
+			[]regionKind{regionLeaf, regionParagraph}},
+		{"dash rule with no paragraph above is a leaf", "---\n\npara",
+			[]regionKind{regionLeaf, regionParagraph}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			scan := scanMarkdownStructure(tc.content)
+			got := make([]regionKind, 0, len(scan.regions))
+			for _, r := range scan.regions {
+				got = append(got, r.kind)
+			}
+			if len(got) != len(tc.wantKinds) {
+				t.Fatalf("regions = %v, want %v", got, tc.wantKinds)
+			}
+			for i := range got {
+				if got[i] != tc.wantKinds[i] {
+					t.Errorf("region %d = %d, want %d (all: %v)", i, got[i], tc.wantKinds[i], got)
+				}
+			}
+			// Every line must belong to exactly the region that claims it, and
+			// the regions must tile the non-blank lines in order.
+			for i, r := range scan.regions {
+				for k := r.firstLine; k <= r.lastLine; k++ {
+					if scan.lines[k].region != int32(i) {
+						t.Errorf("line %d claims region %d, want %d", k, scan.lines[k].region, i)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMarkdownScanHTMLRepairDetection(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		content string
+		repair  bool
+		closer  string
+	}{
+		{"pre is repairable", "<pre>\na\nb\n</pre>", true, "</pre>"},
+		{"style is repairable", "<style>\n.a{}\n.b{}\n</style>", true, "</style>"},
+		{"textarea is repairable", "<textarea>\na\nb\n</textarea>", true, "</textarea>"},
+		{"multi-line opening tag is repairable", "<pre\n class=\"c\">\na\nb\n</pre>", true, "</pre>"},
+		{"script is never repaired", "<script>\na\nb\n</script>", false, ""},
+		{"div is not repairable", "<div>\na\nb\n</div>", false, ""},
+		{"single-line pre has no interior", "<pre>x</pre>\n\ntail", false, ""},
+		{"unterminated pre is not repaired", "<pre>\na\nb", false, ""},
+		{"pre without a closing '>' is not repaired", "<pre\nno gt ever here", false, ""},
+		{"<presentation> is not <pre>", "<presentation>\na\n</presentation>", false, ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			scan := scanMarkdownStructure(tc.content)
+			var html *region
+			for i := range scan.regions {
+				if scan.regions[i].kind == regionHTML {
+					html = &scan.regions[i]
+					break
+				}
+			}
+			if html == nil {
+				t.Fatalf("no HTML region in %q (regions=%d)", tc.content, len(scan.regions))
+			}
+			if html.htmlRepair != tc.repair {
+				t.Errorf("htmlRepair = %v, want %v", html.htmlRepair, tc.repair)
+			}
+			if html.htmlRepair && html.htmlCloser != tc.closer {
+				t.Errorf("htmlCloser = %q, want %q", html.htmlCloser, tc.closer)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMarkdownScanInterruptsParagraph(t *testing.T) {
+	// A construct that cannot interrupt a paragraph must not produce a safe
+	// boundary, because splitting there changes how the text above it parses.
+	for _, tc := range []struct {
+		name       string
+		content    string
+		limit      int
+		wantSafe   bool
+		wantDegrad string
+	}{
+		{"ordered list starting at one interrupts", "para text\n1. item", 10, true, ""},
+		// `7.` cannot interrupt a paragraph, so the marker line is paragraph
+		// text and the boundary is a paragraph split, not a block boundary.
+		{"ordered list starting past one does not", "para text\n7. item", 10, false, "paragraph_split"},
+		{"unordered list interrupts", "para text\n- item", 10, true, ""},
+		{"heading interrupts", "para text\n## head", 10, true, ""},
+		// The limit must leave room for the whole fence in the second chunk;
+		// otherwise the fence itself needs splitting and that is a separate case.
+		{"fence interrupts", "para text\n```go\nx\n```", 12, true, ""},
+		{"quote interrupts", "para text\n> quoted", 10, true, ""},
+		{"html type 6 interrupts", "para text\n<div>x</div>", 13, true, ""},
+		{"asterisk rule interrupts", "para text\n***", 10, true, ""},
+		{"dash rule does not interrupt", "para text\n---", 10, false, ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			plan := SplitMarkdownForAppend(tc.content, tc.limit)
+			if tc.wantSafe && plan.Degraded() {
+				t.Errorf("expected a clean split, got %v", degradationKinds(plan))
+			}
+			if tc.wantDegrad != "" {
+				if got := strings.Join(degradationKinds(plan), ","); !strings.Contains(got, tc.wantDegrad) {
+					t.Errorf("degradations = %q, want to contain %q", got, tc.wantDegrad)
+				}
+			}
+		})
+	}
+}

internal/helpers/minutes.go

@@ -28,7 +28,7 @@ func newMinutesCommand() *cobra.Command {
 			},
 		},
 	})
-	minutesListCmd := &cobra.Command{Use: "list", Short: "听记列表", RunE: groupRunE}
+	minutesListCmd := newGroupCommand(&cobra.Command{Use: "list", Short: "听记列表", RunE: groupRunE})
 
 	minutesListMineCmd := &cobra.Command{
 		Use:   "mine",
@@ -173,7 +173,7 @@ func newMinutesCommand() *cobra.Command {
 		},
 	})
 
-	minutesGetCmd := &cobra.Command{Use: "get", Short: "获取听记内容", RunE: groupRunE}
+	minutesGetCmd := newGroupCommand(&cobra.Command{Use: "get", Short: "获取听记内容", RunE: groupRunE})
 
 	minutesGetInfoCmd := &cobra.Command{
 		Use:   "info",
@@ -544,7 +544,7 @@ func newMinutesCommand() *cobra.Command {
 		},
 	})
 
-	minutesUpdateCmd := &cobra.Command{Use: "update", Short: "更新听记信息", RunE: groupRunE}
+	minutesUpdateCmd := newGroupCommand(&cobra.Command{Use: "update", Short: "更新听记信息", RunE: groupRunE})
 
 	minutesUpdateTitleCmd := &cobra.Command{
 		Use:     "title",
@@ -659,7 +659,7 @@ func newMinutesCommand() *cobra.Command {
 	// 单个工具通过 cmd 参数覆盖 create/pause/resume/end 四种指令。
 	const listeningNoteCmdTool = "执行听记指令-发起AI听记录音"
 
-	minutesRecordCmd := &cobra.Command{Use: "record", Short: "控制听记录音", RunE: groupRunE}
+	minutesRecordCmd := newGroupCommand(&cobra.Command{Use: "record", Short: "控制听记录音", RunE: groupRunE})
 
 	minutesRecordStartCmd := &cobra.Command{
 		Use:   "start",
@@ -942,7 +942,7 @@ func newMinutesCommand() *cobra.Command {
 	minutesUpdateCmd.AddCommand(minutesUpdateTitleCmd, minutesUpdateSummaryCmd)
 
 	// ── mind-graph 子组 ─────────────────────────────────────────
-	mindGraphCmd := &cobra.Command{Use: "mind-graph", Short: "思维导图管理", RunE: groupRunE}
+	mindGraphCmd := newGroupCommand(&cobra.Command{Use: "mind-graph", Short: "思维导图管理", RunE: groupRunE})
 
 	mindGraphCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -1059,7 +1059,7 @@ func newMinutesCommand() *cobra.Command {
 	mindGraphCmd.AddCommand(mindGraphCreateCmd, mindGraphStatusCmd)
 
 	// ── speaker 子组 ────────────────────────────────────────────
-	speakerCmd := &cobra.Command{Use: "speaker", Short: "发言人管理", RunE: groupRunE}
+	speakerCmd := newGroupCommand(&cobra.Command{Use: "speaker", Short: "发言人管理", RunE: groupRunE})
 
 	speakerReplaceCmd := &cobra.Command{
 		Use:   "replace",
@@ -1127,7 +1127,7 @@ func newMinutesCommand() *cobra.Command {
 	// 对应 MCP 工具 create_speaker_summary / get_speaker_summary
 	// 批量按听记维度汇总每位发言人的段落总结
 
-	speakerSummaryCmd := &cobra.Command{Use: "summary", Short: "发言人段落总结", RunE: groupRunE}
+	speakerSummaryCmd := newGroupCommand(&cobra.Command{Use: "summary", Short: "发言人段落总结", RunE: groupRunE})
 
 	speakerSummaryCreateCmd := &cobra.Command{
 		Use:   "create",
@@ -1243,7 +1243,7 @@ func newMinutesCommand() *cobra.Command {
 	speakerCmd.AddCommand(speakerReplaceCmd, speakerSummaryCmd)
 
 	// ── hot-word 子组 ───────────────────────────────────────────
-	hotWordCmd := &cobra.Command{Use: "hot-word", Short: "个人热词管理", RunE: groupRunE}
+	hotWordCmd := newGroupCommand(&cobra.Command{Use: "hot-word", Short: "个人热词管理", RunE: groupRunE})
 
 	hotWordAddCmd := &cobra.Command{
 		Use:   "add",
@@ -1462,7 +1462,7 @@ func newMinutesCommand() *cobra.Command {
 	// 完整流程：create → HTTP PUT → complete，或 create → cancel 取消。
 	// 注意：upload 子组的所有命令均使用 callMCPToolUnescaped 输出 JSON，
 	// 避免 presignedUrl 中的 & 被 Go 标准库转义为 \u0026。
-	uploadCmd := &cobra.Command{Use: "upload", Short: "文件上传管理", RunE: groupRunE}
+	uploadCmd := newGroupCommand(&cobra.Command{Use: "upload", Short: "文件上传管理", RunE: groupRunE})
 
 	// upload create — 对应 MCP 工具 create_upload_session
 	// 必填参数：fileName(--file-name), fileSize(--file-size)
@@ -1681,7 +1681,7 @@ func newMinutesCommand() *cobra.Command {
 	// ── permission 子组 ─────────────────────────────────────────
 	// 听记成员权限管理：批量添加/移除成员及其权限、为当前用户申请权限。
 	// 对应 MCP 工具 add_member_permission / remove_member_permission / apply_minutes_permission。
-	permissionCmd := &cobra.Command{Use: "permission", Short: "听记成员权限管理", RunE: groupRunE}
+	permissionCmd := newGroupCommand(&cobra.Command{Use: "permission", Short: "听记成员权限管理", RunE: groupRunE})
 
 	// permission add — 对应 MCP 工具 add_member_permission
 	// 批量给多个听记增加成员，并设置成员的权限。
@@ -1951,7 +1951,7 @@ func newMinutesCommand() *cobra.Command {
 	// 听记标签/分组管理：查询用户标签列表、按标签查询听记。
 	// 对应 MCP 工具 query_user_tag_list / query_minutes_by_tag_id。
 	// 标签/分组由用户在听记页面手动创建，此处仅提供查询能力。
-	tagCmd := &cobra.Command{Use: "tag", Short: "听记标签/分组管理", RunE: groupRunE}
+	tagCmd := newGroupCommand(&cobra.Command{Use: "tag", Short: "听记标签/分组管理", RunE: groupRunE})
 
 	// tag list — 对应 MCP 工具 query_user_tag_list
 	// 无需传入参数，系统自动识别当前用户身份。
@@ -2075,7 +2075,7 @@ func newMinutesCommand() *cobra.Command {
 	// 用户身份由网关按登录态注入 uid，agent/CLI 无需传入。
 	// 返回值 items[].audioUrl 为带签名的音频 URL（含 &），因此使用
 	// callMCPToolUnescaped 输出，避免 & 被转义为 \u0026（与 upload 一致）。
-	audioMemoCmd := &cobra.Command{Use: "audio-memo", Short: "语音备忘查询", RunE: groupRunE}
+	audioMemoCmd := newGroupCommand(&cobra.Command{Use: "audio-memo", Short: "语音备忘查询", RunE: groupRunE})
 
 	audioMemoListCmd := &cobra.Command{
 		Use:   "list",
@@ -2179,12 +2179,12 @@ func newMinutesCommand() *cobra.Command {
 	audioMemoListCmd.Flags().String("end", "", "结束时间 ISO-8601 (可选)")
 	audioMemoCmd.AddCommand(audioMemoListCmd)
 
-	minutesCmd := &cobra.Command{
+	minutesCmd := newGroupCommand(&cobra.Command{
 		Use:   "minutes",
 		Short: "AI 听记 / 会议纪要",
 		Long:  `管理钉钉AI听记：查询列表、获取详情、摘要、转写、待办、关键字、音频地址、思维导图、发言人管理、文件上传、成员权限管理、语音备忘查询，以及修改标题和纪要内容。`,
 		RunE:  groupRunE,
-	}
+	})
 	minutesCmd.AddCommand(minutesListCmd, minutesGetCmd, minutesUpdateCmd, minutesRecordCmd, mindGraphCmd, speakerCmd, hotWordCmd, replaceTextCmd, audioMemoCmd, uploadCmd, permissionCmd, tagCmd)
 	return minutesCmd
 }

internal/helpers/oa.go

@@ -369,11 +369,11 @@ func runOAAttachmentUpload(cmd *cobra.Command, _ []string) error {
 }
 
 func newOAAttachmentCommand() *cobra.Command {
-	attachmentCmd := &cobra.Command{
+	attachmentCmd := newGroupCommand(&cobra.Command{
 		Use:   "attachment",
 		Short: "审批附件授权、上传、下载与链接管理",
 		RunE:  groupRunE,
-	}
+	})
 
 	downloadURLCmd := NewLeafCommand(LeafSpec{
 		Use:           "download-url",
@@ -724,14 +724,14 @@ func newOaCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "oa",
 		Short: "OA 审批 / 同意 / 拒绝 / 撤销",
 		Long:  `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表与附件授权。`,
 		RunE:  groupRunE,
-	}
+	})
 
-	approvalCmd := &cobra.Command{Use: "approval", Short: "审批管理", RunE: groupRunE}
+	approvalCmd := newGroupCommand(&cobra.Command{Use: "approval", Short: "审批管理", RunE: groupRunE})
 
 	approvalListPendingCmd := &cobra.Command{
 		Use:     "list-pending",

internal/helpers/polling_coverage_more_test.go

@@ -177,6 +177,17 @@ func TestCrossPlatformCoverageChunkedWriteCoverage(t *testing.T) {
 	os.Args = []string{"dws", "doc"}
 	t.Cleanup(func() { os.Args = oldArgs })
 
+	// Every fixture below scripts a fixed number of MCP calls, so it silently
+	// depends on the splitter producing exactly two chunks. Assert that up front:
+	// otherwise a chunk-count change surfaces as a script-exhaustion panic deep
+	// inside a subtest rather than as a clear failure here.
+	if got := len(SplitMarkdownForAppend("abcdef", 3).Chunks); got != 2 {
+		t.Fatalf("fixtures assume 2 chunks for \"abcdef\" at limit 3, got %d", got)
+	}
+	if got := len(SplitMarkdownForAppend(strings.Repeat("x", 12000), 6000).Chunks); got != 2 {
+		t.Fatalf("fixtures assume 2 chunks for 12000 runes at limit 6000, got %d", got)
+	}
+
 	cases := []struct {
 		name      string
 		tool      string
@@ -205,7 +216,7 @@ func TestCrossPlatformCoverageChunkedWriteCoverage(t *testing.T) {
 				cancel()
 				ctx = cancelled
 			}
-			_, _, _, _ = chunkedWrite(ctx, tc.tool, tc.args, tc.markdown, "test", tc.chunkSize)
+			_, _ = chunkedWrite(ctx, tc.tool, tc.args, tc.markdown, "test", tc.chunkSize)
 		})
 	}
 }

internal/helpers/recruit.go

@@ -61,17 +61,17 @@ func newRecruitCommand() *cobra.Command {
 		},
 	})
 
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:   "recruit",
 		Short: "钉钉招聘",
 		Long:  "查询和创建钉钉招聘中的职位信息。",
 		RunE:  groupRunE,
-	}
-	job := &cobra.Command{
+	})
+	job := newGroupCommand(&cobra.Command{
 		Use:   "job",
 		Short: "招聘职位管理",
 		RunE:  groupRunE,
-	}
+	})
 	job.AddCommand(
 		newRecruitJobListCommand(),
 		newRecruitJobGetCommand(),

internal/helpers/register_edu.go

@@ -1,28 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import "github.com/spf13/cobra"
-
-// 家校/高校系列（家校通讯录、家校群、家校应用、家庭群、高校通讯录）是开源库
-// 显式维护的公开命令，不依赖生成式产品注册表（register_products.go）。
-// 其 MCP server 端点由运行时宿主按 serverID 解析。
-func init() {
-	eduCommands := []struct {
-		name    string
-		buildFn func() *cobra.Command
-	}{
-		{"edu-contact", newEduContactCommand},
-		{"edu-group", newEduGroupCommand},
-		{"edu-app", newEduAppCommand},
-		{"edu-familygroup", newEduFamilyGroupCommand},
-		{"college-contact", newCollegeContactCommand},
-	}
-	for _, c := range eduCommands {
-		c := c
-		RegisterPublic(func() Handler {
-			return wukongHandler{name: c.name, buildFn: c.buildFn}
-		})
-	}
-}

internal/helpers/report.go

@@ -23,8 +23,8 @@ const (
 	reportDingtalkOpenLinkDescription = "点击后打开钉钉客户端的日志详情页，可查看或修改刚创建的日志。"
 	reportContentsMaxBytes            = 10 * 1024 * 1024
 	reportDispatchTemplateSuccessHint = "dws report template get --name <模板名> --format json"
-	reportDispatchTemplateDetailHint  = "dws report entry submit --template-id <templateId> --contents-file <tmp.json> --format json"
-	reportDispatchCreateHint          = "dws report template list --format json\n  dws report template get --name <模板名> --format json\n  dws report entry submit --template-id <templateId> --contents-file <tmp.json> --format json"
+	reportDispatchTemplateDetailHint  = "dws report entry submit --template-id <templateId> --contents-file <tmp.json> --to-user-ids <userId1>,<userId2> --format json"
+	reportDispatchCreateHint          = "dws report template list --format json\n  dws report template get --name <模板名> --format json\n  dws report entry submit --template-id <templateId> --contents-file <tmp.json> --to-user-ids <userId1>,<userId2> --format json"
 	reportDispatchDetailHint          = "dws report outbox list --cursor 0 --size 20 --format json\n  dws report entry get --report-id <reportId> --format json"
 	reportDispatchStatsHint           = "dws report outbox list --cursor 0 --size 20 --format json\n  dws report entry stats --report-id <reportId> --format json"
 	reportDispatchListHint            = "dws report inbox list --start \"YYYY-MM-DDT00:00:00+08:00\" --end \"YYYY-MM-DDT23:59:59+08:00\" --cursor 0 --size 20 --format json"
@@ -64,7 +64,7 @@ func newReportCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newGroupCommand(&cobra.Command{
 		Use:     "report",
 		Aliases: []string{"log"},
 		Short:   "钉钉日志（OA 周报应用 / 日志模版填报）",
@@ -84,10 +84,10 @@ func newReportCommand() *cobra.Command {
 
 别名：dws log 等价 dws report（注意：此处 log 特指 OA 周报应用，不是通用日志/记录）。`,
 		RunE: groupRunE,
-	}
+	})
 
 	// === template subtree（template list 不变；新增 template get；template detail 转 deprecated alias）===
-	templateCmd := &cobra.Command{Use: "template", Short: "日志模版", RunE: groupRunE}
+	templateCmd := newGroupCommand(&cobra.Command{Use: "template", Short: "日志模版", RunE: groupRunE})
 
 	templateListCmd := &cobra.Command{
 		Use:     "list",
@@ -179,7 +179,7 @@ func newReportCommand() *cobra.Command {
 	templateCmd.AddCommand(templateListCmd, templateGetCmd, templateDetailCmd)
 
 	// === entry subtree（单条日报操作 — get / stats / submit）===
-	entryCmd := &cobra.Command{Use: "entry", Short: "日志条目（单条日报操作 — get / stats / submit）", RunE: groupRunE}
+	entryCmd := newGroupCommand(&cobra.Command{Use: "entry", Short: "日志条目（单条日报操作 — get / stats / submit）", RunE: groupRunE})
 
 	entryGetCmd := &cobra.Command{
 		Use:   "get",
@@ -279,14 +279,15 @@ func newReportCommand() *cobra.Command {
 		Long: `按模版提交一份日报。--contents 为 JSON 数组，每项需含 key、sort、content、contentType、type，
 与远程 create_report 一致；可先通过 report template list / template get 取得 templateId 与控件定义。
 
+--to-user-ids 必填：无接收人的提交服务端仍会返回成功，但日志实际对任何人都不可见，因此 dws 侧强制要求接收人。
 长内容（含中文换行 / Markdown）建议走 --contents-file 避免 shell 引号问题；
 也可用 --contents - 从 stdin 读取。
 提交成功后会自动反查详情，并在返回中追加 dingtalkOpenUrl / dingtalkOpenMarkdownLink 跳转链接字段。`,
-		Example: `  dws report entry submit --template-id TPL_ID --contents '[{"content":"完成开发","sort":"0","key":"今日完成","contentType":"markdown","type":"1"}]'
+		Example: `  dws report entry submit --template-id TPL_ID --contents '[{"content":"完成开发","sort":"0","key":"今日完成","contentType":"markdown","type":"1"}]' --to-user-ids userId1
   # 推荐：长内容走文件
-  dws report entry submit --template-id TPL_ID --contents-file ./report.json
+  dws report entry submit --template-id TPL_ID --contents-file ./report.json --to-user-ids userId1,userId2
   # 或 stdin
-  cat report.json | dws report entry submit --template-id TPL_ID --contents -
+  cat report.json | dws report entry submit --template-id TPL_ID --contents - --to-user-ids userId1
   dws report entry submit --template-id TPL_ID --contents '[...]' --to-chat --to-user-ids userId1,userId2`,
 		RunE: runReportCreate,
 	}
@@ -312,14 +313,17 @@ func newReportCommand() *cobra.Command {
 			},
 			Selection: contract.SelectionSpec{
 				AgentSummary: "按模版提交一份新日报",
-				UseWhen:      []string{"已取得 templateId 与字段定义，需要按模版提交日报/周报（contents[].key 必须等于模板 field_name）时"},
+				UseWhen: []string{
+					"已取得 templateId 与字段定义，需要按模版提交日报/周报（contents[].key 必须等于模板 field_name）时",
+					"提交时必须通过 --to-user-ids 指定至少一个接收人；无接收人的日志提交后对任何人都不可见",
+				},
 				AvoidWhen: []string{
 					"尚未读取模板字段时先用 dws report template list / template get",
 					"只需查看已有日志正文时改用 dws report entry get",
 				},
 				Examples: []string{
-					"dws report entry submit --template-id <templateId> --contents-file ./report.json --format json",
-					"dws report entry submit --template-id <templateId> --contents '[{\"key\":\"今日完成\",\"sort\":\"0\",\"content\":\"完成了需求评审\",\"contentType\":\"markdown\",\"type\":\"1\"}]' --format json",
+					"dws report entry submit --template-id <templateId> --contents-file ./report.json --to-user-ids <userId1>,<userId2> --format json",
+					"dws report entry submit --template-id <templateId> --contents '[{\"key\":\"今日完成\",\"sort\":\"0\",\"content\":\"完成了需求评审\",\"contentType\":\"markdown\",\"type\":\"1\"}]' --to-user-ids <userId1> --format json",
 				},
 			},
 			Parameters: []contract.ParamDecl{
@@ -386,9 +390,10 @@ func newReportCommand() *cobra.Command {
 	addReportListFlags(inboxListCmd)
 
 	inboxCmd.AddCommand(inboxListCmd)
+	newHybridGroupCommand(inboxCmd)
 
 	// === outbox subtree（我发出的日报）===
-	outboxCmd := &cobra.Command{Use: "outbox", Short: "发件箱（我发出的日报）", RunE: groupRunE}
+	outboxCmd := newGroupCommand(&cobra.Command{Use: "outbox", Short: "发件箱（我发出的日报）", RunE: groupRunE})
 
 	outboxListCmd := &cobra.Command{
 		Use:   "list",
@@ -447,7 +452,7 @@ func newReportCommand() *cobra.Command {
 	createCmd := &cobra.Command{
 		Use:     "create",
 		Short:   "[deprecated] 已废弃，请改用 `dws report entry submit`",
-		Example: `  dws report create --template-id TPL_ID --contents-file ./report.json`,
+		Example: `  dws report create --template-id TPL_ID --contents-file ./report.json --to-user-ids userId1,userId2`,
 		RunE:    withReportDeprecationWarning("create", "entry submit", runReportCreate),
 	}
 	addReportCreateFlags(createCmd)
@@ -595,14 +600,24 @@ func runReportCreate(cmd *cobra.Command, args []string) error {
 		ddFrom = "dws"
 	}
 	toChat, _ := cmd.Flags().GetBool("to-chat")
+	// Cobra required 只拦截 flag 未传，不拦截空值；create_report 对无接收人的
+	// 提交仍返回成功，但日志对任何接收人都不可见，因此这里对解析后的空接收人
+	// 列表同样 fail-closed。
+	toUserIDs := parseReportUserIDs(mustGetFlag(cmd, "to-user-ids"))
+	if len(toUserIDs) == 0 {
+		return &CLIError{
+			Code:       CodeMissingParam,
+			Message:    "to-user-ids is required",
+			Suggestion: "通过 --to-user-ids userId1,userId2 指定至少一个日志接收人；无接收人的提交服务端仍返回成功，但日志对任何人都不可见",
+			Operation:  "report.create",
+		}
+	}
 	toolArgs := map[string]any{
 		"templateId": tplID,
 		"contents":   contents,
 		"ddFrom":     ddFrom,
 		"toChat":     toChat,
-	}
-	if v, _ := cmd.Flags().GetString("to-user-ids"); v != "" {
-		toolArgs["toUserIds"] = parseReportUserIDs(v)
+		"toUserIds":  toUserIDs,
 	}
 	return callReportCreateWithDetailURL(toolArgs)
 }
@@ -764,7 +779,11 @@ func addReportCreateFlags(cmd *cobra.Command) {
 	cmd.Flags().String("contents-file", "", "从文件读取 contents JSON（推荐用于含中文/换行/Markdown 的长内容，避免 shell 引号转义；优先级：--contents-file > --contents - (stdin) > --contents '<json>'）")
 	cmd.Flags().String("dd-from", "dws", "创建来源标识")
 	cmd.Flags().Bool("to-chat", false, "是否发送到日志接收人单聊")
-	cmd.Flags().String("to-user-ids", "", "接收人 userId，逗号分隔 (可选)")
+	// 无接收人的 create_report 服务端仍返回成功但日志不可见；openAPI 历史参数
+	// 保持可选，dws 侧强制必填（dws report entry submit 与废弃别名 report create
+	// 共用本函数，两侧 required 标记保持一致）。
+	cmd.Flags().String("to-user-ids", "", "接收人 userId，逗号分隔 (必填)；无接收人的日志提交后对任何人都不可见")
+	_ = cmd.MarkFlagRequired("to-user-ids")
 }
 
 // withReportDeprecationWarning 包装旧命令的 RunE：调用时往 stderr 打废弃提醒，

internal/helpers/report_recipient_required_test.go

@@ -0,0 +1,118 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+package helpers
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+// reportCreateArgsRecorder 记录 create_report 收到的原始参数，
+// 用于验证 runReportCreate 对 --to-user-ids 的解析与传递。
+type reportCreateArgsRecorder struct {
+	response string
+	format   string
+	args     map[string]any
+}
+
+func (c *reportCreateArgsRecorder) CallTool(_ context.Context, _, tool string, args map[string]any) (*edition.ToolResult, error) {
+	if tool == "create_report" {
+		c.args = args
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: c.response}}}, nil
+}
+
+func (c *reportCreateArgsRecorder) Format() string { return c.format }
+func (*reportCreateArgsRecorder) DryRun() bool     { return false }
+func (*reportCreateArgsRecorder) Fields() string   { return "" }
+func (*reportCreateArgsRecorder) JQ() string       { return "" }
+
+func TestReportEntrySubmitRequiresRecipientFlag(t *testing.T) {
+	t.Cleanup(func() { contract.ClearProductDeclForTest("report") })
+	root := newReportCommand()
+	// 主命令与废弃别名共用 addReportCreateFlags，两侧的 Cobra required
+	// 标记必须同时存在（NativeRequired 一致性校验要求严格相等）。
+	for _, path := range [][]string{{"entry", "submit"}, {"create"}} {
+		leaf, _, err := root.Find(path)
+		if err != nil || leaf == nil {
+			t.Fatalf("%v command missing: %v", path, err)
+		}
+		flag := leaf.Flags().Lookup("to-user-ids")
+		if flag == nil {
+			t.Fatalf("%v missing --to-user-ids", path)
+		}
+		if _, required := flag.Annotations[cobra.BashCompOneRequiredFlag]; !required {
+			t.Fatalf("%v --to-user-ids must stay Cobra required", path)
+		}
+	}
+
+	root.SetOut(io.Discard)
+	root.SetErr(io.Discard)
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	// Cobra 的 Execute 会跳回 Root 执行，必须携带完整命令路径；
+	// required 校验在 RunE 之前拦截未传的 --to-user-ids。
+	root.SetArgs([]string{
+		"entry", "submit",
+		"--template-id", "TPL",
+		"--contents", `[{"key":"k","sort":"0","content":"c","contentType":"markdown","type":"1"}]`,
+	})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "to-user-ids") {
+		t.Fatalf("missing --to-user-ids error = %v", err)
+	}
+}
+
+func TestReportCreateRejectsBlankRecipient(t *testing.T) {
+	t.Cleanup(func() { contract.ClearProductDeclForTest("report") })
+	root := newReportCommand()
+	submit, _, _ := root.Find([]string{"entry", "submit"})
+	_ = submit.Flags().Set("template-id", "TPL")
+	_ = submit.Flags().Set("contents", `[{"key":"k","sort":"0","content":"c","contentType":"markdown","type":"1"}]`)
+	// Cobra required 只拦未传；空值/纯分隔符仍会进入 RunE，必须 fail-closed。
+	_ = submit.Flags().Set("to-user-ids", " , ")
+	err := runReportCreate(submit, nil)
+	cliErr, ok := err.(*CLIError)
+	if !ok || cliErr.Code != CodeMissingParam {
+		t.Fatalf("blank to-user-ids error = %#v", err)
+	}
+}
+
+func TestReportCreatePassesRecipientsToCreateReport(t *testing.T) {
+	t.Cleanup(func() { contract.ClearProductDeclForTest("report") })
+	recorder := &reportCreateArgsRecorder{
+		format:   "json",
+		response: `{"reportId":"id","url":"dingtalk://direct"}`,
+	}
+	testseam.Protect(t, &deps)
+	InitDeps(recorder)
+	out := &bytes.Buffer{}
+	errOut := &bytes.Buffer{}
+	deps.Out.w = out
+	deps.Out.errW = errOut
+
+	root := newReportCommand()
+	submit, _, _ := root.Find([]string{"entry", "submit"})
+	_ = submit.Flags().Set("template-id", "TPL")
+	_ = submit.Flags().Set("contents", `[{"key":"k","sort":"0","content":"c","contentType":"markdown","type":"1"}]`)
+	_ = submit.Flags().Set("to-user-ids", " userA , userB ")
+	if err := runReportCreate(submit, nil); err != nil {
+		t.Fatalf("runReportCreate: %v", err)
+	}
+	got, _ := recorder.args["toUserIds"].([]string)
+	if len(got) != 2 || got[0] != "userA" || got[1] != "userB" {
+		t.Fatalf("toUserIds = %#v", recorder.args["toUserIds"])
+	}
+}

internal/helpers/run_all_edu_commands_test.go

@@ -1,280 +0,0 @@
-package helpers
-
-import (
-	"fmt"
-	"io"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-// TestRunAllEduCommands 逐条执行 5 个教育产品的全部 156 条叶子命令（dry-run 模式），
-// 并打印每条命令对应的 MCP 工具名和参数。相当于在终端逐一执行 dws <cmd> --dry-run。
-func TestRunAllEduCommands(t *testing.T) {
-	type cmdCase struct {
-		product string
-		args    []string
-	}
-
-	allCmds := []cmdCase{
-		// ═══════════════════════════════════════════════════════════
-		// edu-contact: 29 commands
-		// ═══════════════════════════════════════════════════════════
-		// school (6)
-		{"edu-contact", []string{"school", "roles"}},
-		{"edu-contact", []string{"school", "structure"}},
-		{"edu-contact", []string{"school", "periods"}},
-		{"edu-contact", []string{"school", "type"}},
-		{"edu-contact", []string{"school", "stats", "--statistics-type", "1"}},
-		{"edu-contact", []string{"school", "class-list"}},
-		// class (19)
-		{"edu-contact", []string{"class", "detail", "--dept-id", "12345"}},
-		{"edu-contact", []string{"class", "students", "--dept-id", "12345"}},
-		{"edu-contact", []string{"class", "teachers", "--dept-id", "12345"}},
-		{"edu-contact", []string{"class", "same-name", "--dept-id", "12345"}},
-		{"edu-contact", []string{"class", "user-role", "--dept-id", "12345"}},
-		{"edu-contact", []string{"class", "search-by-name", "--query-type", "student", "--name", "张三"}},
-		{"edu-contact", []string{"class", "headmaster", "--class-name", "一年级1班"}},
-		{"edu-contact", []string{"class", "search-by-teacher", "--name", "张老师"}},
-		{"edu-contact", []string{"class", "update-student", "--class-id", "123", "--student-user-id", "u1"}},
-		{"edu-contact", []string{"class", "add-student", "--dept-id", "123", "--student-name", "张三", "--student-mobile", "13800138000"}},
-		{"edu-contact", []string{"class", "modify-student-info", "--dept-id", "123", "--target-user-id", "u1", "--nick", "小明"}},
-		{"edu-contact", []string{"class", "delete-teacher", "--class-id", "123", "--teacher-user-id", "u1"}},
-		{"edu-contact", []string{"class", "update-info", "--class-id", "123", "--nick", "火箭班"}},
-		{"edu-contact", []string{"class", "update-student-number", "--class-id", "123", "--student-user-id", "u1", "--student-number", "S001"}},
-		{"edu-contact", []string{"class", "add-unofficial-student", "--dept-id", "123", "--student-staff-ids", "s1,s2"}},
-		{"edu-contact", []string{"class", "delete-students", "--dept-id", "123", "--student-user-ids", "u1,u2"}},
-		{"edu-contact", []string{"class", "update-student-mobile", "--dept-id", "123", "--student-user-id", "u1", "--mobile", "13800138000"}},
-		{"edu-contact", []string{"class", "move-student", "--student-user-ids", "u1,u2", "--origin-class-id", "123", "--target-class-id", "456"}},
-		{"edu-contact", []string{"class", "add-teachers", "--dept-id", "123", "--teacher-user-ids", "u1,u2"}},
-		// family (2)
-		{"edu-contact", []string{"family", "children"}},
-		{"edu-contact", []string{"family", "parents"}},
-		// teacher (2)
-		{"edu-contact", []string{"teacher", "classes"}},
-		{"edu-contact", []string{"teacher", "update-course", "--teacher-class-infos", `[{"classId":123,"courseCode":"MATH","courseName":"数学"}]`}},
-
-		// ═══════════════════════════════════════════════════════════
-		// edu-group: 14 commands
-		// ═══════════════════════════════════════════════════════════
-		// student-group (7)
-		{"edu-group", []string{"student-group", "info", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "exists", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "members", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "is-in", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "conversation", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "create", "--dept-id", "12345"}},
-		{"edu-group", []string{"student-group", "disband", "--dept-id", "12345"}},
-		// class-group (4)
-		{"edu-group", []string{"class-group", "conversation-id", "--dept-id", "12345"}},
-		{"edu-group", []string{"class-group", "conversation", "--dept-id", "12345"}},
-		{"edu-group", []string{"class-group", "exists", "--dept-id", "12345"}},
-		{"edu-group", []string{"class-group", "list-by-cids", "--conversation-ids", "cid1,cid2,cid3"}},
-		// batch (3)
-		{"edu-group", []string{"batch", "check-student-group", "--class-ids", "12345,67890"}},
-		{"edu-group", []string{"batch", "get-class-groups", "--class-ids", "12345,67890"}},
-		{"edu-group", []string{"batch", "create-student-groups"}},
-
-		// ═══════════════════════════════════════════════════════════
-		// edu-app: 42 commands
-		// ═══════════════════════════════════════════════════════════
-		// message (1)
-		{"edu-app", []string{"message", "summary-list", "--class-id", "1", "--cid", "c1", "--target-role", "guardian", "--status", "0"}},
-		// task (3)
-		{"edu-app", []string{"task", "publish-list"}},
-		{"edu-app", []string{"task", "all-list", "--biz-id", "1"}},
-		{"edu-app", []string{"task", "student-list", "--students", `[{"userId":"u1","bizId":"1"}]`}},
-		// report (5)
-		{"edu-app", []string{"report", "get", "--ids", "1001,1002"}},
-		{"edu-app", []string{"report", "by-teacher"}},
-		{"edu-app", []string{"report", "by-class", "--report-id", "1001", "--class-id", "12345"}},
-		{"edu-app", []string{"report", "by-student-list", "--class-id", "12345", "--student-id", "u1"}},
-		{"edu-app", []string{"report", "by-student-detail", "--report-id", "1001", "--student-id", "u1", "--class-id", "12345"}},
-		// notice (7)
-		{"edu-app", []string{"notice", "confirm", "--notice-id", "n1", "--student-id", "u1"}},
-		{"edu-app", []string{"notice", "create", "--identifer", "org1-staff1-uuid", "--content", "明天放假"}},
-		{"edu-app", []string{"notice", "delete", "--notice-id", "12345"}},
-		{"edu-app", []string{"notice", "list-by-teacher"}},
-		{"edu-app", []string{"notice", "get", "--notice-id", "12345"}},
-		{"edu-app", []string{"notice", "confirm-status", "--notice-id", "12345", "--class-id", "c1"}},
-		{"edu-app", []string{"notice", "list-by-student", "--student-id", "u1", "--class-id", "c1"}},
-		// circle (1)
-		{"edu-app", []string{"circle", "posts", "--class-id", "12345", "--student-id", "u1", "--target-role", "guardian"}},
-		// card (5)
-		{"edu-app", []string{"card", "update", "--card-id", "1", "--identifier", "org1-staff1-uuid", "--title", "新标题"}},
-		{"edu-app", []string{"card", "end", "--card-id", "1"}},
-		{"edu-app", []string{"card", "list", "--status", "UNFINISH"}},
-		{"edu-app", []string{"card", "user-statistic", "--card-id", "1", "--task-code", "code1", "--class-id", "cid1"}},
-		{"edu-app", []string{"card", "finish-info", "--card-id", "1", "--card-biz-id", "bid1"}},
-		// diploma (9)
-		{"edu-app", []string{"diploma", "create", "--identifier", "org1-staff1-uuid", "--content", "三好学生", "--user-name", "张三"}},
-		{"edu-app", []string{"diploma", "read", "--diploma-id", "1"}},
-		{"edu-app", []string{"diploma", "list-by-teacher"}},
-		{"edu-app", []string{"diploma", "get", "--diploma-id", "1"}},
-		{"edu-app", []string{"diploma", "statistics", "--diploma-id", "1"}},
-		{"edu-app", []string{"diploma", "detail", "--diploma-id", "1"}},
-		{"edu-app", []string{"diploma", "list-by-student", "--student-id", "u1", "--class-id", "c1"}},
-		{"edu-app", []string{"diploma", "student-detail", "--diploma-id", "1", "--student-id", "u1", "--class-id", "c1"}},
-		{"edu-app", []string{"diploma", "delete", "--diploma-id", "1"}},
-		// homework (11)
-		{"edu-app", []string{"homework", "create", "--identifier", "org1-staff1-uuid", "--hw-content", "完成练习册第3页"}},
-		{"edu-app", []string{"homework", "delete", "--homework-id", "1"}},
-		{"edu-app", []string{"homework", "submit", "--hw-content-detail-id", "1"}},
-		{"edu-app", []string{"homework", "get", "--homework-id", "1"}},
-		{"edu-app", []string{"homework", "class-by-homework", "--homework-id", "1"}},
-		{"edu-app", []string{"homework", "class-detail", "--homework-id", "1", "--class-id", "c1", "--user-name", "张老师"}},
-		{"edu-app", []string{"homework", "submit-statistics", "--homework-id", "1", "--class-id", "c1"}},
-		{"edu-app", []string{"homework", "list-by-student", "--student-id", "u1", "--class-id", "c1", "--user-name", "张三"}},
-		{"edu-app", []string{"homework", "student-detail", "--homework-id", "1", "--student-id", "u1", "--class-id", "c1"}},
-		{"edu-app", []string{"homework", "list-by-teacher"}},
-		{"edu-app", []string{"homework", "create-comment", "--comment", "做得很好", "--hw-content-detail-id", "1"}},
-
-		// ═══════════════════════════════════════════════════════════
-		// edu-familygroup: 6 commands
-		// ═══════════════════════════════════════════════════════════
-		// group (2)
-		{"edu-familygroup", []string{"group", "check-exists", "--uid", "12345", "--group-name", "小明一家"}},
-		{"edu-familygroup", []string{"group", "list-children", "--uid", "12345"}},
-		// manage (4)
-		{"edu-familygroup", []string{"manage", "create", "--uid", "12345", "--children", `[{"name":"小明","students":[{"corpId":"corp1","staffId":"staff1"}]}]`}},
-		{"edu-familygroup", []string{"manage", "invite-parent", "--org-id", "12345", "--uid", "67890", "--mobile", "13800138000"}},
-		{"edu-familygroup", []string{"manage", "add-child", "--org-id", "12345", "--uid", "67890", "--name", "小红", "--mobile", "13900139000"}},
-		{"edu-familygroup", []string{"manage", "toggle-app", "--org-id", "12345", "--uid", "67890", "--child-staff-id", "staff1", "--app-type", "XIAOTIANDI", "--open", "true"}},
-
-		// ═══════════════════════════════════════════════════════════
-		// college-contact: 65 commands
-		// ═══════════════════════════════════════════════════════════
-		// dept (9)
-		{"college-contact", []string{"dept", "get-standard-structure"}},
-		{"college-contact", []string{"dept", "get-detail", "--dept-id", "12345"}},
-		{"college-contact", []string{"dept", "get-chain", "--dept-id", "12345"}},
-		{"college-contact", []string{"dept", "search", "--dept-id", "12345", "--keyword", "计算机"}},
-		{"college-contact", []string{"dept", "create", "--super-id", "1", "--stru-dept-id", "2", "--name", "计算机学院", "--dept-type", "COLLEGE", "--create-dept-group", "true"}},
-		{"college-contact", []string{"dept", "update", "--dept-id", "12345", "--dept-type", "COLLEGE"}},
-		{"college-contact", []string{"dept", "delete", "--dept-id", "12345"}},
-		{"college-contact", []string{"dept", "batch-update-type", "--dept-ids", "1,2,3", "--target-dept-type", "COLLEGE"}},
-		{"college-contact", []string{"dept", "overview"}},
-		// employee (11)
-		{"college-contact", []string{"employee", "get-detail", "--staff-id", "staff001"}},
-		{"college-contact", []string{"employee", "add", "--emp-type", "TEACHER", "--main-dept-id", "12345", "--exclusive-account", "false"}},
-		{"college-contact", []string{"employee", "remove", "--staff-ids", "s1,s2"}},
-		{"college-contact", []string{"employee", "change-type", "--staff-id", "staff001", "--emp-type", "STUDENT"}},
-		{"college-contact", []string{"employee", "change-dept", "--staff-id", "staff001", "--target-dept-id", "67890"}},
-		{"college-contact", []string{"employee", "send-active-sms", "--dept-id", "12345"}},
-		{"college-contact", []string{"employee", "list-employees", "--dept-id", "12345"}},
-		{"college-contact", []string{"employee", "list-unaccepted", "--dept-id", "12345"}},
-		{"college-contact", []string{"employee", "list-unactive", "--dept-id", "12345"}},
-		{"college-contact", []string{"employee", "upgrade-status"}},
-		{"college-contact", []string{"employee", "start-upgrade"}},
-		// alumni (20)
-		{"college-contact", []string{"alumni", "get-dept-tree", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "get-info", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "list", "--alumni-dept-id", "12345", "--order-field", "NAME", "--ordering", "ASC"}},
-		{"college-contact", []string{"alumni", "query", "--staff-id", "staff001"}},
-		{"college-contact", []string{"alumni", "search", "--keyword", "张三"}},
-		{"college-contact", []string{"alumni", "list-unaccepted", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "get-group", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "create-dept", "--alumni-dept-id", "12345", "--dept-name", "2020届"}},
-		{"college-contact", []string{"alumni", "update-dept", "--alumni-dept-id", "12345", "--dept-name", "2020届计算机"}},
-		{"college-contact", []string{"alumni", "delete-dept", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "update-managers", "--alumni-dept-id", "12345", "--admin-user-ids", "u1,u2"}},
-		{"college-contact", []string{"alumni", "add-alumnus", "--dept-ids", "1,2", "--name", "张三", "--mobile", "13800138000"}},
-		{"college-contact", []string{"alumni", "update-alumnus", "--dept-ids", "1,2", "--staff-id", "s1", "--name", "张三"}},
-		{"college-contact", []string{"alumni", "remove-alumnus", "--staff-id", "s1", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "cancel-invite", "--alumni-dept-id", "12345", "--staff-ids", "s1,s2"}},
-		{"college-contact", []string{"alumni", "create-group", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "disband-group", "--alumni-dept-id", "12345"}},
-		{"college-contact", []string{"alumni", "get-alumni-org-from-graduate"}},
-		{"college-contact", []string{"alumni", "create-alumni-org", "--org-name", "计算机校友会"}},
-		{"college-contact", []string{"alumni", "add-alumni-org-main-admins", "--admin-user-ids", "u1,u2"}},
-		// graduate (16)
-		{"college-contact", []string{"graduate", "query-graduate-years"}},
-		{"college-contact", []string{"graduate", "query-graduate-depts", "--dept-id", "12345"}},
-		{"college-contact", []string{"graduate", "query-graduate-sub-depts", "--dept-id", "12345"}},
-		{"college-contact", []string{"graduate", "query-page-graduate-users", "--dept-id", "12345"}},
-		{"college-contact", []string{"graduate", "get-task-result", "--request-no", "req001"}},
-		{"college-contact", []string{"graduate", "get-alumni-org"}},
-		{"college-contact", []string{"graduate", "query-restore-sub-depts", "--dept-id", "12345"}},
-		{"college-contact", []string{"graduate", "query-dept-deleted-emps", "--dept-id", "12345"}},
-		{"college-contact", []string{"graduate", "search-graduate", "--keyword", "张三"}},
-		{"college-contact", []string{"graduate", "commit-graduate", "--graduate-dept-ids", "1,2", "--graduate-year", "2026"}},
-		{"college-contact", []string{"graduate", "all-graduate", "--graduate-year", "2026"}},
-		{"college-contact", []string{"graduate", "batch-graduate", "--dept-id", "12345", "--staff-ids", "s1,s2"}},
-		{"college-contact", []string{"graduate", "delete-and-graduate", "--dept-id", "12345", "--staff-ids", "s1,s2"}},
-		{"college-contact", []string{"graduate", "batch-delete-pending", "--dept-id", "12345", "--staff-ids", "s1,s2"}},
-		{"college-contact", []string{"graduate", "batch-update-pending", "--dept-id", "12345", "--staff-ids", "s1,s2", "--graduate-year", "2026"}},
-		{"college-contact", []string{"graduate", "commit-restore", "--graduate-dept-ids", "1,2"}},
-		// group (9)
-		{"college-contact", []string{"group", "query-group-rule"}},
-		{"college-contact", []string{"group", "get-group-rule-schedule"}},
-		{"college-contact", []string{"group", "query-preview-data"}},
-		{"college-contact", []string{"group", "create-group-rule", "--name", "自动分组", "--tag-code", "TAG1", "--dept-type", "COLLEGE"}},
-		{"college-contact", []string{"group", "delete-group-rule", "--rule-id", "1"}},
-		{"college-contact", []string{"group", "enable-group-rule", "--rule-id", "1"}},
-		{"college-contact", []string{"group", "disable-group-rule", "--rule-id", "1"}},
-		{"college-contact", []string{"group", "set-group-rule-schedule"}},
-		{"college-contact", []string{"group", "execute-group-rule"}},
-	}
-
-	// 按产品分组的命令构建器
-	builders := map[string]func() *cobra.Command{
-		"edu-contact":     newEduContactCommand,
-		"edu-group":       newEduGroupCommand,
-		"edu-app":         newEduAppCommand,
-		"edu-familygroup": newEduFamilyGroupCommand,
-		"college-contact": newCollegeContactCommand,
-	}
-
-	// 安装 dry-run caller
-	caller := &recruitCaptureCaller{dryRun: true}
-	InitDepsForTest(t, caller)
-	deps.Out.w = io.Discard
-
-	passed := 0
-	failed := 0
-	currentProduct := ""
-
-	for i, c := range allCmds {
-		if c.product != currentProduct {
-			currentProduct = c.product
-			fmt.Printf("\n══════════════════════════════════════════════════════\n")
-			fmt.Printf("  %s\n", strings.ToUpper(currentProduct))
-			fmt.Printf("══════════════════════════════════════════════════════\n")
-		}
-
-		buildFn, ok := builders[c.product]
-		if !ok {
-			t.Fatalf("unknown product: %s", c.product)
-		}
-		root := buildFn()
-		root.SetArgs(c.args)
-		root.SetOut(io.Discard)
-		root.SetErr(io.Discard)
-
-		// Reset caller capture
-		caller.productID = ""
-		caller.tool = ""
-		caller.args = nil
-
-		err := root.Execute()
-		cmdPath := fmt.Sprintf("dws %s %s", c.product, strings.Join(c.args, " "))
-
-		if err != nil {
-			failed++
-			fmt.Printf("  [%3d] ✗ FAIL: %s\n", i+1, cmdPath)
-			fmt.Printf("        Error: %v\n", err)
-			t.Errorf("command %d failed: %s → %v", i+1, cmdPath, err)
-		} else {
-			passed++
-			fmt.Printf("  [%3d] ✓ %s\n", i+1, cmdPath)
-			if caller.tool != "" {
-				fmt.Printf("        → MCP: %s.%s\n", caller.productID, caller.tool)
-			}
-		}
-	}
-
-	fmt.Printf("\n══════════════════════════════════════════════════════\n")
-	fmt.Printf("  SUMMARY: %d passed, %d failed, %d total\n", passed, failed, passed+failed)
-	fmt.Printf("══════════════════════════════════════════════════════\n")
-}

internal/helpers/runtime_defaults_test.go

@@ -0,0 +1,50 @@
+package helpers
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+// Relocated verbatim from content_splitter_test.go, which was deleted along with
+// the block-rebuilding splitter. This test targets runtime_defaults.go and has
+// nothing to do with markdown chunking.
+func TestCrossPlatformCoverageRuntimeDefaultsRegistryValidationAndSnapshot(t *testing.T) {
+	runtimeDefaultsMu.Lock()
+	previous := runtimeDefaults
+	runtimeDefaults = make(map[string]edition.RuntimeDefaultFn)
+	runtimeDefaultsMu.Unlock()
+	t.Cleanup(func() {
+		runtimeDefaultsMu.Lock()
+		runtimeDefaults = previous
+		runtimeDefaultsMu.Unlock()
+	})
+
+	resolver := func(context.Context) (string, bool) { return "value", true }
+	RegisterRuntimeDefault("$value", resolver)
+	snapshot := RuntimeDefaultsSnapshot()
+	if len(snapshot) != 1 || snapshot["$value"] == nil {
+		t.Fatalf("RuntimeDefaultsSnapshot() = %#v", snapshot)
+	}
+	delete(snapshot, "$value")
+	if len(RuntimeDefaultsSnapshot()) != 1 {
+		t.Fatal("snapshot mutated the runtime registry")
+	}
+
+	for _, tc := range []struct {
+		name string
+		fn   edition.RuntimeDefaultFn
+	}{
+		{"", resolver}, {"$nil", nil}, {"$value", resolver},
+	} {
+		func() {
+			defer func() {
+				if recover() == nil {
+					t.Errorf("RegisterRuntimeDefault(%q) did not panic", tc.name)
+				}
+			}()
+			RegisterRuntimeDefault(tc.name, tc.fn)
+		}()
+	}
+}

internal/helpers/sheet.go

@@ -38,7 +38,7 @@ func newSheetCommand() *cobra.Command {
 			},
 		},
 	})
-	root := &cobra.Command{
+	root := newDeepGroupCommand(&cobra.Command{
 		Use:   "sheet",
 		Short: "钉钉表格管理",
 		Long: `管理钉钉在线电子表格：创建表格、工作表管理、数据读写、单元格搜索、查找替换、单元格合并与取消合并、行列插入删除移动追加与属性更新、附件上传、浮动图片管理、筛选视图管理、下拉列表管理。
@@ -119,7 +119,7 @@ func newSheetCommand() *cobra.Command {
   dws sheet template list                       获取表格模板列表
   dws sheet template search                     搜索表格模板
   dws sheet template apply                      应用表格模板创建新表格文档`,
-	}
+	})
 
 	// ── Build commands via factory functions ──────────────────────────
 	workbookCmds := newWorkbookCmds()
@@ -296,15 +296,6 @@ func newSheetCommand() *cobra.Command {
 		attachSheetConfirmationGuard(root, guard.path, guard.operation, guard.targetHint)
 	}
 
-	// Guards for grouped parent commands
-	attachUnknownSubcommandGuard(root)
-	attachUnknownSubcommandGuard(rangeCmd)
-	attachUnknownSubcommandGuard(filterCmd)
-	attachUnknownSubcommandGuard(filterViewCmd)
-	attachUnknownSubcommandGuard(condFormatCmd)
-	attachUnknownSubcommandGuard(chartCmd)
-	attachUnknownSubcommandGuard(pivotTableCmd)
-
 	return root
 }
 
@@ -315,73 +306,3 @@ func attachSheetConfirmationGuard(root *cobra.Command, path, operation, targetHi
 	}
 	protectSheetMutationCommand(command, operation, targetHint)
 }
-
-// attachUnknownSubcommandGuard 为分组型命令挂上拼错子命令时的 did-you-mean 提示。
-//
-// 背景：cobra 对父命令的 Args 校验发生在 ParseFlags 之后，而 pflag 默认把未知 flag
-// 当作硬错误抛出。于是 `dws sheet read --sheet-id X` 会先报 `unknown flag: --sheet-id`，
-// 真正的根因（read 不是 sheet 的直接子命令）被彻底掩盖；同时 `dws sheet reead` 会被
-// 当成位置参数静默吞掉、打印 help 后 exit=0，AI Agent 无法察觉命令执行失败。
-//
-// 本函数通过三件套让分组命令在"没匹配到子命令"时给出明确的错误与建议：
-//  1. FParseErrWhitelist.UnknownFlags=true —— pflag 不再因未知 flag 中断，
-//     未知 flag 连同其值一起被静默消化；
-//  2. Args=ArbitraryArgs —— 允许把剩余位置参数交给 RunE 处理；
-//  3. RunE —— 取 args[0] 作为拼错的子命令名，先在后代命令里查找完全同名的叶子
-//     （能把 `sheet read` 精准引导到 `sheet range read`），找不到再退回 cobra
-//     自带的同级编辑距离建议；最终返回 error 以保证 exit!=0。
-//
-// 仅挂在分组型父命令（sheet/range/filter-view）上，不会影响已在 cobra Find 阶段
-// 精确匹配到的合法叶子命令。
-func attachUnknownSubcommandGuard(cmd *cobra.Command) {
-	cmd.Args = cobra.ArbitraryArgs
-	cmd.FParseErrWhitelist = cobra.FParseErrWhitelist{UnknownFlags: true}
-	cmd.SilenceUsage = true
-	// cobra 仅在 root 自动把 SuggestionsMinimumDistance 兑成 2，子命令默认为 0，
-	// 会导致 `sheet range reead` 这样的同级近似拼写无法触发内置建议。
-	if cmd.SuggestionsMinimumDistance <= 0 {
-		cmd.SuggestionsMinimumDistance = 2
-	}
-	cmd.RunE = func(c *cobra.Command, args []string) error {
-		if len(args) == 0 {
-			return c.Help()
-		}
-		name := args[0]
-		var buf strings.Builder
-		fmt.Fprintf(&buf, "unknown command %q for %q", name, c.CommandPath())
-		suggestions := deepSuggestSubcommand(c, name)
-		if len(suggestions) == 0 {
-			suggestions = c.SuggestionsFor(name)
-		}
-		if len(suggestions) > 0 {
-			buf.WriteString("\n\nDid you mean this?")
-			for _, s := range suggestions {
-				fmt.Fprintf(&buf, "\n\t%s %s", c.CommandPath(), s)
-			}
-		}
-		fmt.Fprintf(&buf, "\n\nRun '%s --help' for usage.", c.CommandPath())
-		return fmt.Errorf("%s", buf.String())
-	}
-}
-
-// deepSuggestSubcommand 在所有后代命令里查找与 name 完全同名的可用子命令，
-// 返回从 parent 出发的相对路径列表。用于把 `sheet read` 这样的平铺习惯引导到
-// 真实的深路径 `sheet range read`。
-func deepSuggestSubcommand(parent *cobra.Command, name string) []string {
-	var out []string
-	var walk func(c *cobra.Command, rel []string)
-	walk = func(c *cobra.Command, rel []string) {
-		for _, sub := range c.Commands() {
-			if !sub.IsAvailableCommand() {
-				continue
-			}
-			next := append(append([]string{}, rel...), sub.Name())
-			if sub.Name() == name {
-				out = append(out, strings.Join(next, " "))
-			}
-			walk(sub, next)
-		}
-	}
-	walk(parent, nil)
-	return out
-}