ci: enforce complete Go test coverage

ci: shorten workflow name and require 100% changed-code coverage

.github/PULL_REQUEST_TEMPLATE.md

@@ -5,6 +5,13 @@
 
 ## Verification
 
+For an exact in-place `CHANGELOG.md`-only pull request, the full-suite checks
+may be marked `N/A`, but the targeted CHANGELOG check is required. For every
+other pull request, mark the targeted check `N/A` and complete the applicable
+full-suite checks.
+
+- [ ] Exact `CHANGELOG.md`-only check (otherwise `N/A`):
+  `./scripts/policy/check-changelog-pr.sh --fast-path "$(git merge-base HEAD origin/main)" HEAD`
 - [ ] `make build`
 - [ ] `make lint`
 - [ ] `make test`

.github/actionlint.yaml

@@ -0,0 +1,6 @@
+paths:
+  .github/workflows/release.yml:
+    ignore:
+      # 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/badges/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 54.2%"><title>coverage: 54.2%</title><filter id="blur"><feGaussianBlur in="SourceGraphic" stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#dd4343"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".80" filter="url(#blur)" transform="scale(.1)" textLength="510">coverage</text><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="835" y="150" fill="#010101" fill-opacity=".80" filter="url(#blur)" transform="scale(.1)" textLength="370">54.2%</text><text aria-hidden="true" x="835" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="370">54.2%</text><text x="835" y="140" transform="scale(.1)" fill="#fff" textLength="370">54.2%</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 100.0%"><title>coverage: 100.0%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4b0"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">100.0%</text><text x="865" y="150" fill-opacity=".3" textLength="430">100.0%</text></g><text x="865" y="140" textLength="430">100.0%</text></g></g></svg>

.github/workflows/ai-behavior-check.yml

@@ -0,0 +1,131 @@
+name: Code Admission — AI Behavior
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: read
+  statuses: write
+
+jobs:
+  ai-behavior-check:
+    name: AI Behavior
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # Deliberately do not check out or execute pull-request code here.
+      # pull_request_target keeps this policy anchored to the base branch.
+      - name: Check AI-generated PR boundaries
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pullRequest = context.payload.pull_request;
+            const sha = context.eventName === 'push' ? context.sha : pullRequest.head.sha;
+            const setStatus = (state, description) =>
+              github.rest.repos.createCommitStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha,
+                state,
+                context: 'AI Behavior',
+                description,
+              });
+
+            await setStatus('pending', 'Evaluating AI-generated PR boundaries');
+
+            if (context.eventName === 'push') {
+              await setStatus('success', 'Not applicable to the protected main push');
+              core.notice('AI Behavior is a PR policy; the main push context is sealed.');
+              return;
+            }
+
+            try {
+              const expectedHead = pullRequest.head.sha;
+              const expectedBase = pullRequest.base.sha;
+              const currentPull = async (phase) => {
+                const { data: pull } = await github.rest.pulls.get({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: context.issue.number,
+                });
+                if (pull.head.sha !== expectedHead || pull.base.sha !== expectedBase) {
+                  throw new Error(
+                    `Pull request revision changed during ${phase}: ` +
+                    `expected base/head ${expectedBase}/${expectedHead}, ` +
+                    `got ${pull.base.sha}/${pull.head.sha}`
+                  );
+                }
+                return pull;
+              };
+
+              const before = await currentPull('pre-policy check');
+              const labels = before.labels.map(({ name }) => name);
+              if (!labels.includes('ai-generated')) {
+                await setStatus('success', 'Not labeled ai-generated');
+                core.notice('Not an ai-generated PR; no AI-only policy applied.');
+                return;
+              }
+
+              const files = await github.paginate(github.rest.pulls.listFiles, {
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.issue.number,
+                per_page: 100,
+              });
+              await currentPull('post-policy check');
+
+              const maxChangedFiles = 30;
+              if (files.length > maxChangedFiles) {
+                await setStatus(
+                  'failure',
+                  `Changes ${files.length} files; limit is ${maxChangedFiles}`
+                );
+                core.setFailed(
+                  `AI-generated PR changes ${files.length} files; limit is ${maxChangedFiles}.`
+                );
+                return;
+              }
+
+              const isProtectedPath = (filename) =>
+                typeof filename === 'string' &&
+                (
+                  filename.startsWith('.github/workflows/') ||
+                  filename.startsWith('scripts/ci/') ||
+                  filename.startsWith('scripts/policy/') ||
+                  filename.startsWith('scripts/release/') ||
+                  filename === 'test/fixtures/cli-interface-baseline.txt' ||
+                  filename === '.goreleaser.yaml' ||
+                  filename === 'Makefile'
+                );
+              const protectedPaths = [...new Set(
+                files
+                  .flatMap(({ filename, previous_filename }) => [filename, previous_filename])
+                  .filter(isProtectedPath)
+              )];
+
+              if (protectedPaths.length > 0) {
+                await setStatus('failure', 'Modifies protected release/CI infrastructure');
+                core.setFailed(
+                  'AI-generated PR modifies protected release/CI infrastructure:\n' +
+                  protectedPaths.map((filename) => `  - ${filename}`).join('\n') +
+                  '\nSplit these changes into a human-owned PR with explicit review.'
+                );
+                return;
+              }
+
+              await setStatus(
+                'success',
+                `Passed with ${files.length} changed files (limit ${maxChangedFiles})`
+              );
+              core.notice(
+                `AI behavior check passed (${files.length} changed files; limit ${maxChangedFiles}).`
+              );
+            } catch (error) {
+              await setStatus('error', 'Could not evaluate the exact pull request revision');
+              throw error;
+            }

.github/workflows/mirror-to-gitee.yml

@@ -1,4 +1,5 @@
-# 把本仓库代码自动镜像到 Gitee，供国内用户访问（raw 脚本入口 + tags）。
+# 把本仓库 main 代码自动镜像到 Gitee，供国内用户访问 raw 脚本入口。
+# Release tag 与附件只由 release.yml 的受控 publication queue 发布。
 # 用 HTTPS + 令牌直接 git push（无需 SSH key），复用已配置的 secret：
 #   GITEE_TOKEN  —— Gitee 私人令牌（勾 projects）
 #   GITEE_USER   —— 令牌所属 Gitee 用户名（用于 https 推送鉴权）
@@ -10,22 +11,25 @@ on:
   push:
     branches:
       - main
-    tags:
-      - 'v*'
   schedule:
     - cron: '0 18 * * *'
   workflow_dispatch:
 
+concurrency:
+  group: gitee-code-mirror
+  cancel-in-progress: false
+
 jobs:
   mirror:
     runs-on: ubuntu-latest
+    if: ${{ github.ref_name == github.event.repository.default_branch && github.repository_owner == 'DingTalk-Real-AI' }}
     # GitHub Actions 不允许在 job-level if 直接引用 secrets，故先用 env 暴露再在 step 守卫。
     env:
       GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
       GITEE_USER: ${{ secrets.GITEE_USER }}
       GITEE_REPO: ${{ secrets.GITEE_REPO }}
     steps:
-      - name: Checkout (full history + tags)
+      - name: Checkout main history
         if: env.GITEE_TOKEN != ''
         uses: actions/checkout@v4
         with:
@@ -36,8 +40,8 @@ jobs:
         run: |
           set -eu
           REMOTE="https://${GITEE_USER}:${GITEE_TOKEN}@gitee.com/${GITEE_REPO}.git"
-          # 取到 main 与所有 tag（落到 origin/* 与本地 tags，避免推当前分支引用冲突）
-          git fetch --force --tags origin 'refs/heads/main:refs/remotes/origin/main'
+
+          git fetch --force origin 'refs/heads/main:refs/remotes/origin/main'
 
           # Gitee 专属分支：在 origin/main 之上叠加一个 README 本地化 commit。
           # GitHub 那份 README 不变；只有推往 Gitee 的副本被改写。
@@ -69,7 +73,6 @@ jobs:
           git add README.md README_zh.md 2>/dev/null || true
           git commit -m "docs(gitee): localize install commands + coverage badge for Gitee mirror" || true
 
-          # 镜像对齐（force：Gitee 始终跟随 GitHub + Gitee 专属 README 本地化）
+          # main 镜像对齐；release tag 由 release.yml 单独校验后创建，禁止在这里 force。
           git push --force "$REMOTE" 'gitee-main:refs/heads/main'
-          git push --force --tags "$REMOTE"
-          echo "✅ 已镜像 main(+Gitee README 本地化) + tags 到 Gitee ${GITEE_REPO}"
+          echo "✅ 已镜像 main（含 Gitee README 本地化）到 Gitee ${GITEE_REPO}"

.github/workflows/multi-profile-e2e.yml

@@ -1,8 +1,9 @@
-name: Multi Profile E2E
+name: Main Integration — 主干集成
 
 on:
-  pull_request:
   push:
+    branches:
+      - main
   workflow_dispatch:
 
 permissions:
@@ -14,7 +15,7 @@ concurrency:
 
 jobs:
   multi-profile-e2e:
-    name: Multi Profile E2E
+    name: Multi-profile E2E
     runs-on: ubuntu-latest
     timeout-minutes: 15
     env:
@@ -36,7 +37,7 @@ jobs:
           mkdir -p .tmp-bin
           bash scripts/dev/test-multi-profile-e2e.sh --keep-workdir | tee "$MULTI_PROFILE_E2E_LOG"
           {
-            echo "### Multi Profile E2E"
+            echo "### Multi-profile E2E"
             echo "- Command: \`bash scripts/dev/test-multi-profile-e2e.sh --keep-workdir\`"
             echo "- Scope: isolated auth/profile storage, profile switch/use, one-shot profile override, CSV multi-profile aggregation, legacy migration"
             echo "- Result: passed"

.github/workflows/notify-wukong.yml

@@ -0,0 +1,38 @@
+name: Main Integration — Wukong Overlay
+
+on:
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+
+permissions: {}
+
+jobs:
+  notify-downstream:
+    name: Notify Wukong Overlay
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Trigger downstream CI
+        env:
+          UPSTREAM_SHA: ${{ github.event.workflow_run.head_sha }}
+          WUKONG_TRIGGER_TOKEN: ${{ secrets.WUKONG_TRIGGER_TOKEN }}
+          WUKONG_TRIGGER_URL: ${{ secrets.WUKONG_TRIGGER_URL }}
+        run: |
+          if [ -n "$WUKONG_TRIGGER_TOKEN" ]; then
+            curl --fail --silent --show-error \
+              -X POST \
+              -F "token=$WUKONG_TRIGGER_TOKEN" \
+              -F "ref=main" \
+              -F "variables[UPSTREAM_SHA]=$UPSTREAM_SHA" \
+              "$WUKONG_TRIGGER_URL"
+            echo "Downstream CI triggered."
+          else
+            echo "No WUKONG_TRIGGER_TOKEN configured, skipping downstream notification."
+          fi

.github/workflows/sync-release-to-gitee.yml

@@ -1,49 +0,0 @@
-name: Sync release to Gitee
-
-# Manually mirror a published GitHub release's assets to the matching Gitee
-# release. Use this to repair a release whose Gitee mirror is incomplete (e.g.
-# the Release job timed out mid-upload). It runs ONLY the idempotent Gitee sync
-# step — it does not run GoReleaser and does not touch the GitHub release, so
-# there is no release outage. The sync script skips assets already on Gitee, so
-# this only uploads what is missing.
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: "Release tag to mirror to Gitee (e.g. v1.0.42)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-
-jobs:
-  sync-gitee:
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@v4
-
-      - name: Download GitHub release assets
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -eu
-          mkdir -p dist
-          gh release download "${{ inputs.version }}" \
-            --repo "${{ github.repository }}" \
-            --dir dist \
-            --pattern 'dws-*' \
-            --pattern 'checksums.txt' \
-            --clobber
-          ls -la dist
-
-      - name: Mirror release to Gitee (China)
-        # Idempotent: uploads only assets not already present on the Gitee release.
-        run: ./scripts/release/sync-to-gitee.sh
-        env:
-          VERSION: ${{ inputs.version }}
-          GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
-          GITEE_REPO: ${{ secrets.GITEE_REPO }}

.gitignore

@@ -19,6 +19,7 @@ test/cli_compat/testdata/
 /internal/compat/testdata/*
 .gitignore
 .worktrees/
+.qoder/
 
 # Secrets & credentials
 .env
@@ -42,5 +43,14 @@ dws.zip
 # 功能测试运行产物
 results.jsonl
 test/dev_functional/results.jsonl
+/auto-test/
+/eval-runs/
+/.qoder/
 .vercel
 .env*
+# Local Go coverage output
+/coverage.txt
+/coverage-base.txt
+/coverage-policy.txt
+/coverage.html
+dwsbin

.goreleaser.yaml

@@ -1,19 +1,14 @@
 # GoReleaser configuration for dws
 # Docs: https://goreleaser.com
 #
-# To release:
-#   git tag -a v0.1.0 -m "Release v0.1.0"
-#   git push origin v0.1.0
+# To release, use scripts/release/release.sh. It seals main, validates the
+# CHANGELOG and packages, then pushes the annotated tag for CI/CD to publish.
 #
 # To test locally (no publish):
 #   goreleaser release --snapshot --clean
 
 version: 2
 
-before:
-  hooks:
-    - go mod tidy
-
 builds:
   - main: ./cmd
     binary: dws
@@ -67,7 +62,9 @@ release:
     # 用当前运行 CI 的仓库 owner: fork CI 发到 fork, 官方 CI 发到官方, 两边都对
     owner: "{{ .Env.GITHUB_REPOSITORY_OWNER }}"
     name: dingtalk-workspace-cli
-  draft: false
+  # Keep the release private until post-processing has replaced the Darwin
+  # archives and verified every finalized asset digest.
+  draft: true
   prerelease: auto
   name_template: "v{{.Version}}"
   mode: replace

.workflow/gitee-release.yml

@@ -0,0 +1,51 @@
+name: Gitee Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release tag to build on Gitee, e.g. v1.0.48"
+        required: false
+        type: string
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Install packaging tools
+        run: |
+          set -eu
+          sudo apt-get update
+          sudo apt-get install -y zip unzip curl
+
+      - name: Install rcodesign
+        run: |
+          set -eu
+          RCS_VERSION="0.27.0"
+          curl -fsSL -o /tmp/rcodesign.tar.gz \
+            "https://github.com/indygreg/apple-platform-rs/releases/download/apple-codesign%2F${RCS_VERSION}/apple-codesign-${RCS_VERSION}-x86_64-unknown-linux-musl.tar.gz"
+          mkdir -p /tmp/rcodesign
+          tar -xzf /tmp/rcodesign.tar.gz -C /tmp/rcodesign --strip-components=1
+          sudo install -m 0755 /tmp/rcodesign/rcodesign /usr/local/bin/rcodesign
+          rcodesign --version
+
+      - name: Build and publish Gitee release
+        env:
+          VERSION: ${{ inputs.version || github.ref_name }}
+          GITEE_TOKEN: ${{ secrets.GITEE_TOKEN }}
+          GITEE_REPO: DingTalk-Real-AI/dingtalk-workspace-cli
+        run: ./scripts/release/build-and-publish-gitee.sh

AGENTS.md

@@ -0,0 +1,357 @@
+# Repository Agent Guide
+
+This file applies to the entire repository. Keep changes scoped, preserve
+unrelated work, and use `gofmt` for every modified Go file.
+
+## Build and test
+
+- Build: `go build ./cmd`
+- Full test suite: `DWS_PACKAGE_VERSION=0.0.0-test go test ./...`
+- Generate Schema assets: `go generate ./internal/cli`
+- Check generated drift: `./scripts/policy/check-generated-drift.sh`
+- Check the Schema contract: `./scripts/policy/check-schema-catalog.sh`
+
+Generated Schema JSON is committed. Change its source inputs and generators,
+then regenerate; do not hand-edit generated Catalog or Agent metadata files.
+`internal/cli/schema_command_registry.json` is different: it is a reviewed
+`CommandRegistry` source, not a generated snapshot. It is the single reviewed
+source of stable canonical identity,
+primary paths, aliases, and navigation. Edit it only when reviewed exposure,
+identity, primary path, or aliases change; parameter, Skill, and metadata-only
+changes must not rewrite it mechanically.
+
+## Agent Schema contract
+
+The Schema data flow is one way:
+
+```text
+1. app.NewRootCommand()
+   └─ builds the real Cobra command tree and flags
+
+2. schema_command_registry.json
+   + schema_hints/metadata/<product>.json tool parameters (+ cli_path)
+   └─ forms EffectiveCommandRegistry
+      └─ binds exactly to real Cobra leaves and aliases
+
+3. Parameter resolution
+   Cobra flags
+   + schema_parameter_bindings.json
+   + metadata tool parameters
+   └─ produces ParameterSpec and constraints
+
+4. Agent and interface semantics
+   schema_hints/selection/<product>.json   (selection prose)
+   + schema_hints/metadata/<product>.json  (safety/interface/runtime_gate)
+   + pinned MCP metadata
+   └─ resolves Agent metadata by source precedence
+      Markdown is evidence only; it is not concatenated into final prose
+
+5. One typed hub
+   BoundCommandRegistry
+   + ParameterSpec
+   + Agent metadata
+   + Interface metadata
+   └─ resolves every command exactly once into ToolSpec
+      └─ aggregates SchemaRegistry + SchemaIndex
+
+6. One-way publication
+   SchemaRegistry
+   └─ internal/cli/schema_catalog.json
+      └─ dws schema list/product/group/leaf/--all
+```
+
+Parameter overlays from metadata are merged into `EffectiveCommandRegistry`
+*before* Cobra binding; after that point there is no second identity source and
+no identity precedence winner. The binder must reject a missing/non-runnable
+Cobra path, an alias collision, and any native identity annotation that
+disagrees with the effective registry. A missing native identity annotation is
+allowed because annotations are implementation-side assertions, not identity
+fallbacks.
+
+The assembler resolves every bound command exactly once into one `ToolSpec`.
+Build-time gates and the snapshot serializer consume that source-resolved typed
+registry/index. Runtime projections and delivery gates consume the typed
+registry/index returned by the production snapshot loader. Neither path may
+reopen annotations, merge source records, or use a previous Catalog or other
+generated JSON as a source. `schema_catalog.json` is output-only in the
+generation graph. The production loader decoding the embedded published
+snapshot is a delivery boundary, not source resolution; it must never create or
+repair a Cobra command, flag, registry entry, or later Catalog generation.
+
+This split is architecturally isomorphic to Lark's typed metadata registry,
+navigation catalog, and schema renderer. DWS intentionally preserves its
+existing flat JSON wire contract for compatibility; do not treat architectural
+alignment as permission to make an unversioned wire-format change.
+
+The reviewed `CommandRegistry` is the sole source of stable command identity
+and navigation. The executable Cobra tree remains the source of truth for
+whether a CLI path exists, is runnable, and which flags it accepts. Schema
+coverage is bidirectional:
+
+1. Every final `SchemaRegistry` tool, including its serialized Catalog
+   projection, must resolve to an executable Cobra command.
+2. Every public runnable Cobra leaf must either resolve to Schema or appear as
+   an exact, reviewed exclusion with a non-empty reason in
+   `internal/cli/schema_command_exclusions.json`.
+
+Do not use prefix or wildcard exclusions: they can silently hide future
+commands. Remove an exclusion when its command enters Schema; stale, invalid,
+or duplicate exclusions must fail generation and CI.
+
+When adding or changing an Agent-visible command, review all relevant inputs:
+
+- `internal/cli/schema_command_registry.json` for the reviewed
+  `CommandRegistry`: canonical identity, primary CLI path, aliases, and stable
+  navigation. It is the identity source and is not a generated artifact.
+- `internal/cli/schema_command_registry.schema.json` is its closed,
+  machine-readable editing contract. Preserve the local `$schema` reference;
+  unknown fields, invalid visibility values, stale paths, and collisions fail
+  Go validation and policy.
+- `internal/cli/schema_hints/metadata/<product>.json` for safety, interface,
+  `runtime_gate`, and optional parameter overlays (`parameters` / `cli_path`).
+- `internal/cli/schema_hints/selection/<product>.json` for reviewed Agent
+  selection prose (`agent_summary`, `use_when`, `avoid_when`, `examples`).
+- `internal/cli/schema_hints/index.json` only maps product IDs to those files.
+- Native Runtime Schema identity annotations, when present, as consistency
+  assertions against `EffectiveCommandRegistry`. They must agree exactly and
+  must never materialize, infer, or override registry identity.
+- Flag-to-interface property mappings and required/default semantics.
+- Generated files under `internal/cli/schema_agent_metadata/` and
+  `internal/cli/schema_catalog.json` after running generation.
+
+Run the reverse-completeness tests whenever the Cobra tree changes. A command
+that works through `dws <path>` but cannot be found through the matching
+`dws schema` lookup is a contract failure unless it has a reviewed exact
+exclusion.
+
+Metadata parameter overlays must reference an exact public runnable Cobra leaf
+and real flags. They may override Schema description, interface-property/type
+mapping, `required`, and `required_when`; they must not create commands or
+flags, define an interface, or advertise an unknown RPC. Every authored entry
+requires `reviewed: true` and a non-empty review reason.
+
+For Agent-authored metadata or selection edits:
+
+1. Confirm the exact command and flag names in the current Cobra tree.
+2. Edit only the owning block (`metadata/` or `selection/`); do not mix fields.
+3. Add the smallest possible entry; do not copy generated Catalog fields into
+   the input.
+4. Describe user-visible semantics in `review_reason` and parameter
+   descriptions.
+5. Run generation, drift, Schema policy, and the focused CLI tests before
+   proposing the change.
+
+## Agent curation workflow (Schema hints)
+
+Use this workflow when refreshing Agent selection prose and confirmation
+alignment. Prefer **agent-authored review** over bulk merge scripts that dump
+`selection-review.json` or Skill Markdown into Catalog fields.
+
+Human-authored inputs are split into two blocks:
+
+| Block | Path | Owns |
+|---|---|---|
+| **metadata** | `internal/cli/schema_hints/metadata/<product>.json` | `effect` / `risk` / `confirmation` / `idempotency` / `interface_*` / `runtime_gate` / optional `parameters` |
+| **selection** | `internal/cli/schema_hints/selection/<product>.json` | `agent_summary` / `use_when` / `avoid_when` / `examples` (+ product routing) |
+
+`index.json` only maps product IDs to those files. Do not mix selection fields
+into metadata files or metadata fields into selection files.
+
+### Goals
+
+1. **Selection prose** is decision-oriented (Feishu/Lark style): trigger intent,
+   sibling-command routing, and outcome shape — not a restatement of the
+   summary. Delivered Catalog provenance is `reviewed_explicit` from
+   `selection/`.
+2. **Safety** follows Runtime: `confirmation=user_required` iff the tool's
+   metadata `runtime_gate != none` (for example `confirm_delete`, `typed_yes`,
+   `confirm_dangerous`).
+3. **Parameter overrides** (former Manual `commands`) live on metadata tools as
+   `parameters` (+ `cli_path`) and are applied into EffectiveCommandRegistry.
+
+### Authoring
+
+For every curated tool:
+
+1. Edit `metadata/<product>.json` for safety/interface/gates/parameters.
+2. Edit `selection/<product>.json` for selection prose (`reviewed: true`,
+   `review_reason`, `source_refs`).
+3. Run `make generate-schema`. Do not hand-edit generated
+   `schema_agent_metadata/` or `schema_catalog.json`.
+
+### Pull live MCP descriptions (personal token)
+
+Pinned `internal/cli/schema_mcp_metadata.json` is a sanitized baseline. Prefer
+live Schema from a logged-in personal session:
+
+```bash
+dws auth status                 # token_valid should be true
+dws cache refresh               # refresh discovery / tools cache
+dws schema <mcp-canonical> -f json
+# or CLI path: dws schema --cli-path "drive copy" -f json
+```
+
+Resolve MCP identity via `interface_ref` when CLI canonical ≠ MCP path
+(example: CLI `drive.copy_document` → live `doc.copy_document`). On pull
+failure, fall back to Skill + Cobra Help + pinned MCP, and record evidence
+(for example `live-dws-schema:<path>#FAILED`). Never print or commit tokens.
+
+Precedence when sources disagree: **Runtime/Cobra > live MCP > pinned MCP >
+Skill (evidence only)**.
+
+### Parallel product agents
+
+Split work by product groups. Each agent must:
+
+- Read Skill, Cobra/`--help`, Runtime confirmation sites, and live `dws schema`
+  for its tools.
+- Hand-write selection + metadata; forbid wholesale JSON merges from review
+  dumps.
+- Edit only its `metadata/<product>.json` and `selection/<product>.json`.
+- **Never** `git checkout` unrelated product files to “clean scope”.
+
+### Regenerate and gates
+
+```bash
+make generate-schema
+./scripts/policy/check-runtime-confirmation-truth.sh
+go test ./internal/app -run '^TestSheetFinalSchemaConfirmationMatchesRuntimeGuards$' -count=1
+```
+
+Example rules (fail generation otherwise):
+
+- At most two examples per tool; no `--yes` in stored examples.
+- Examples must match live Cobra argv (path, flags, required groups).
+- No shell comments in examples.
+
+After generation, spot-check Catalog: selection provenance is
+`reviewed_explicit` from `selection/`, and `user_required` count equals
+metadata `runtime_gate != none`.
+
+`make generate-schema` is a full deterministic snapshot rebuild, not an
+incremental patch over the previous Catalog. It rereads every reviewed input,
+removes stale generated product metadata, and rewrites the exact metadata and
+Catalog projections. Incremental work happens only when an Agent or human
+edits selected `metadata/` or `selection/` entries; the next publication still
+recomputes all outputs. Generated files must never be read back as merge input,
+and byte guards fail generation if it changes the hint inputs or CommandRegistry.
+
+Selection prose may choose a more or less restrictive recommendation. It cannot
+create a Cobra command or flag, change parameter facts, invent an
+RPC/interface, alter safety metadata, or bypass command completeness. Examples
+must use an executable primary/alias path and flags accepted by the live Cobra
+command; never add `--yes` to stored examples.
+
+Every example is always checked against its real `BoundCommand`: exact path,
+accepted flags, Cobra required flags/positionals, and the effective
+`require_one_of`, `require_together`, and `mutually_exclusive` constraints must
+all pass before execution eligibility is considered. A missing required value,
+constraint failure, runtime error, or MCP resolution error is a contract bug;
+none is a valid reason to skip an example.
+
+Example execution defaults to contract validation only. Runtime execution is
+opt-in: an example enters `dry_run` only when its final `ToolSpec` publishes an
+explicit reviewed dry-run capability. The test never injects `--yes`, and
+`risk`/`confirmation` values do not manufacture preview support. A narrow
+runtime precondition that cannot be derived from the typed contract may use an
+exact zero-based `example_dispositions` entry with `mode=contract_only`,
+`reviewed=true`, one of the schema-enumerated reason codes, and a concrete
+non-empty reason. Such a disposition may only narrow an explicit dry-run
+capability; it cannot turn an ordinary contract-only example into a skip.
+Duplicate, missing, and out-of-range indexes fail validation. Never catch a
+dry-run failure and dynamically downgrade it to `contract_only`.
+
+Normal Go tests run the exhaustive contract gate. Run
+`make test-schema-agent-examples` to additionally execute the eligible subset
+through the real Cobra `--dry-run` path with isolated HOME and blocked proxies.
+The test reports stable `total`, `contract`, `dry_run`, `contract_only`,
+`reviewed_manual`, and per-reason counts; changing those counts requires a
+review of the corresponding typed dry-run capability or manual disposition.
+This target is also part of `make policy`.
+
+Treat every tool `use_when` entry as a reviewed positive selection scenario
+whose expected result is that tool's canonical path, and every `avoid_when`
+entry as a reviewed negative scenario that must not choose that tool. The
+deterministic gate derives a typed evaluation fixture from these same fields;
+it requires exact tool coverage, a real runnable `BoundCommandRegistry`
+primary command, at least one positive and negative assertion per tool, and no
+literal contradictory expectations. It does not claim that string matching
+proves natural-language understanding.
+
+Semantic selection is an explicit opt-in live-model check. Run the smoke set
+(one positive and one negative scenario per product) with
+`DWS_AGENT_SELECTION_LIVE=1 ARK_API_KEY=... ARK_BASE_URL=... ARK_MODEL=... go test ./internal/app -run TestManualAgentSelectionArkLive -count=1`.
+Add `DWS_AGENT_SELECTION_FULL=1` to evaluate every committed tool scenario, or
+set `DWS_AGENT_SELECTION_CASES` to comma-separated fixture case IDs. Normal CI
+never calls a model; its blockers remain the reproducible fixture, binding,
+example, provenance, and final-delivery facts.
+
+The live evaluator sends only case IDs/scenarios plus one same-product
+candidate table; expected/forbidden assertions stay local and must never be
+included in the model prompt. Built-in Ark HTTPS bases are allowlisted. A
+different HTTPS provider requires its exact base in
+`DWS_AGENT_SELECTION_ALLOWED_BASE_URLS`; plaintext HTTP is accepted only for a
+loopback test server so API credentials are never sent to an arbitrary clear
+text endpoint.
+
+## Safety metadata
+
+Parameter and safety resolution is mostly source-precedence based and
+value-neutral: do not choose a winner because one value looks stricter. A
+higher-priority reviewed metadata/explicit source may intentionally raise or
+lower description, mapping, `effect`, `risk`, `confirmation`, or `idempotency`.
+Preserve all candidates and the selected source in provenance, and fail
+same-precedence conflicts rather than silently merging them.
+
+`required` is the exception. Cobra `MarkFlagRequired` is a hard floor: the
+final Agent projection must keep `required=true` and cannot be lowered by
+manual/hint overlays. Overlays may still raise an optional flag to required.
+`cli_required` continues to mirror the executable Cobra marker.
+
+For command text, reviewed `ToolSchemaHint` wins first, then command-specific
+Cobra Help, then MCP metadata. Generic RPC prose may remain an unselected
+provenance candidate (and parameter-level `interface_description`); it must not
+overwrite a specialized leaf's title or description.
+
+For every delivered `ToolSpec` and `ParameterSpec` field, the provenance
+winner value must exactly equal the delivered value. Checking only source,
+count, presence, or hash is not a sufficient final-delivery invariant.
+
+The same resolved `ToolSpec` must drive every projection. The full leaf payload
+must equal the corresponding tool in `schema --all` and the full Catalog tool.
+Overview/product/group summaries and Catalog summaries must equal
+`ToolSpec.ToSummaryPayload()`. An alias lookup may change only the view fields
+`cli_path` and `is_alias`; it must not re-resolve or mutate the command
+contract.
+
+This build-time rule is distinct from runtime drift handling. If shipped Help
+and leaf Schema disagree, pass only flags accepted by Cobra. For conflicting
+safety information, do not silently take the less restrictive behavior: use
+the safer interpretation or stop and report the contract drift.
+
+Do not infer one safety field from another. In particular, `effect=destructive`
+or `risk=high` does not mechanically rewrite `confirmation`; the final
+precedence winner for each field is authoritative. When
+`confirmation=user_required`, obtain confirmation before adding `--yes`.
+Keep CLI confirmation behavior and Schema metadata consistent, and add a
+semantic regression test through the final embedded loader/query delivery
+path; a generator unit test or JSON count alone is insufficient.
+
+## Current Schema boundaries
+
+- `schema list` remains a progressive overview. `schema --all` is the stable
+  full-export contract: every final `SchemaIndex` tool must contain its
+  complete leaf parameters, constraints, and safety semantics, including an empty
+  `parameters` object for commands without flags. Keep it suitable for the #602
+  compatibility baseline and fail rather than silently emitting a partial
+  export.
+- `schema --all` is not normal command discovery. Use overview -> product/group
+  -> leaf for routine Agent work. `--compact` is supported for context-saving
+  projections, but a compact full export is not a complete compatibility
+  baseline.
+- `dws <path> --help` defines whether Cobra exposes a path and which flags the
+  executable accepts. A leaf Schema defines Agent selection, parameter mapping
+  and constraints, and safety/confirmation semantics. A conflict is contract
+  drift, not permission to guess.
+- Schema and Help describe commands; neither returns DingTalk business data.
+  After discovery, execute the real read/search/list command to obtain data.

CHANGELOG.md

@@ -6,6 +6,171 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th
 
 ## [Unreleased]
 
+### Changed
+
+- **Fast guarded beta and stable releases** — successful local release checks now leave a six-hour proof bound to the exact version, commit, repository identity, remote `main`, and stable baseline, so the subsequent guarded `--publish` invocation revalidates authority without repeating tests and packaging. A default-branch governance smoke uses the same dedicated immutable-release credential as the tag workflow before any tag is allocated.
+- **Protected existing-tag recovery** — `dws-release recover <version>` can resume a failed, unpublished annotated tag through the normal contract, build, Developer ID signing, immutable GitHub Release, Homebrew, npm, and OSS jobs. Recovery requires the exact tag object, peeled commit, failed tag-push run, typed version confirmation, and the protected `release-recovery` environment; successful runs are accepted as future beta/stable delivery evidence.
+
+### Fixed
+
+- **Consistent access-token caching and errors** — runtime, recovery, Skill, PAT polling, and personal/portal event clients now resolve user access tokens through one expiry- and publication-aware manager, so long-running processes reload rotated credentials while keychain, refresh, parse, permission, and cancellation failures remain observable instead of being collapsed into “not authenticated.”
+- **Tag-push GitHub Release publication** — Draft publication now locks one GitHub Release database ID, verifies its exact tag, channel, notes, recovery marker, asset set, and uploaded bytes, then publishes and rechecks that same ID as immutable. Recovery runs use the trusted default-branch release helpers instead of the sealed tag's historical scripts, fixing the Draft-only `GET /releases/tags/{tag}` 404 without allowing the release identity to drift during recovery.
+- **Release preflight reliability** — source-mode installer tests now use isolated temporary checkouts and HOME directories instead of overwriting and deleting the real repository `dws` binary, release preflight explicitly rebuilds before policy checks, and the full-suite runner gives the growing script package a non-flaky five-minute per-suite budget.
+
+## [1.0.53-beta.4] - 2026-07-17
+
+This beta validates the expanded personal IM event subscriptions and the flattened `event consume` structured output introduced after v1.0.53-beta.3.
+
+### Added
+
+- **Expanded personal IM event subscriptions** (#651) — adds one-to-one and group events for message read receipts, recalls, and reactions; publishes the specified-sender receive event; and lets one-to-one/sender subscriptions target either a staff `--user` or an `--open-dingtalk-id`. Event Schema now exposes these alternatives through machine-readable parameter constraints.
+
+### Changed
+
+- **Personal event structured output is now flat** (#651) — `event consume` projects NDJSON/JSON/pretty/compact output into event-specific top-level DTOs, so consumers read fields such as `content`, `sender`, and `conversation_id` directly instead of parsing `.data | fromjson`. This is a breaking change for scripts using the former transport envelope; the original server payload remains available through `-f raw`, while `--debug-raw-events` preserves the full diagnostic envelope.
+
+## [1.0.53-beta.3] - 2026-07-17
+
+This beta validates multi-account profile support and the post-v1.0.53-beta.2 compatibility fixes for Windows portable authentication, IM shortcuts, and Aitable import uploads.
+
+### Added
+
+- **Multiple accounts in one DingTalk organization** — profiles are keyed by `corpId:userId`, `--profile` accepts organization IDs/names plus user IDs/names, and organization-only selection uses its explicitly remembered current account or asks for an exact account when ambiguous.
+
+### Changed
+
+- **Profile-scoped logout and consistent token storage** — `dws auth logout --profile` can remove one account or every account in an organization, while identity token slots remain the source of truth and legacy organization/global mirrors stay compatible without overwriting newer account credentials.
+
+### Fixed
+
+- **Windows portable-auth contract** — `dws auth export` and `dws auth import` now fail early without reading credentials, bundles, or writing files instead of claiming portable-bundle support for DPAPI-protected HKCU Registry credentials.
+- **IM shortcut message tags and compatibility aliases** (#646) — IM send shortcuts now add the same AI-sent marker as `chat message send` by default, support `--ai-tag=false` to opt out, and preserve compatible search, conversation-ID, and page-size aliases.
+- **Aitable import upload file-size validation** (#654) — `dws aitable import upload` and `dws aitable +import-upload` now require a positive `--file-size` and always send it to the upload-preparation API, preventing invalid requests without the actual file size.
+
+## [1.0.53-beta.2] - 2026-07-16
+
+This beta validates the accumulated post-v1.0.52 command surface, release automation, and runtime hardening changes, including enterprise contact onboarding, declarative shortcuts, Sheet/Aitable writes, multi-platform Homebrew formulas, and credential and target-validation fixes.
+
+### Added
+
+- **Contact enterprise onboarding commands** — adds `contact org create`, `contact user invite`, and `contact account create` for creating a DingTalk enterprise, inviting an employee by mobile, and provisioning an enterprise login account, with reviewed Schema contracts and mono/multi Skill routing.
+- **Declarative shortcut commands** (#592) — adds 366 `dws <service> +<command>` shortcuts across 16 services, including one-to-one MCP wrappers and multi-step smart workflows. Shortcuts publish stable Agent-visible contracts with named flags, validation and confirmation metadata, dry-run protection for writes, catalog/help routing, and optional local YAML extensions and usage recording.
+- **Sheet imports and Aitable workflow writes** (#624) — adds `dws sheet import` / `sheet import create` for converting local xlsx/xls files into new online sheets, `sheet import get` for polling import tasks, and `dws aitable workflow create/update` for applying validated `workflow-dsl/v1` definitions, with matching reviewed Agent Schema and bundled Skill guidance.
+- **Official multi-platform Homebrew channel** — stable `Formula/dingtalk-workspace-cli.rb` and keg-only `Formula/dingtalk-workspace-cli-beta.rb` live in this repository and select signed macOS Intel/Apple Silicon or Linux amd64/arm64 artifacts at install time. Stable and beta releases open isolated Formula update PRs after final artifact signing, so beta never replaces the stable Formula. Agent Skills stay under `pkgshare` without mutating the user's home directory, and both tracks are covered by the six-channel post-release verifier.
+
+### Changed
+
+- **Guarded prerelease and stable automation** — adds the guided `dws-release` entry for one-command CHANGELOG preparation, validation-only and annotated-tag publication flows; promotes only an explicitly validated beta; verifies command-tree compatibility and all six packaged binaries; and serializes immutable GitHub Release, npm channel, OSS, Homebrew, and optional Gitee delivery with fail-closed recovery checks.
+- **Reviewed historical release recovery proofs** — release preflight can recognize an explicitly pinned successful recovery delivery for a historical stable tag while still rejecting arbitrary workflow dispatches, mismatched commits, and incomplete release, signing, or publication jobs.
+
+### Fixed
+
+- **PAT organization-policy denials stop immediately** — `PAT_ORG_POLICY_DENIED` now remains terminal even if a backend also returns `flowId`, authorization URLs, or client credentials; the CLI does not mutate process credentials, open a browser, poll, or retry until an organization administrator changes the policy.
+- **Sheet and task invalid-target failures** — `sheet range read/get` now rejects a null cell-info response instead of printing `null` and exiting successfully, while task completion and attachment listing verify that a task exists before calling lenient backend endpoints. Attachment listing is also published through Runtime Schema for schema-first Agent discovery.
+- **Concurrent credential writes and reentrant CLI execution** — secure-token writers now use isolated, exclusive temporary files before atomic replacement so concurrent processes cannot remove each other's in-flight data, and repeated in-process CLI runs close the previous file logger before replacing it instead of retaining the prior log-file handle.
+
+## [1.0.52] - 2026-07-14
+
+This release seals the `v1.0.52` line with personal event subscriptions, a deterministic 22-product Agent command catalog, local user-operation auditing, expanded Open product commands, safer macOS credentials and release signing, and more reliable Connect and IM delivery.
+
+### Added
+
+- **Personal event subscriptions** (#589) — adds `dws event list/schema/consume/status/stop` for user @ mentions, selected one-to-one chats, and selected group chats. `consume` can create or reuse a personal subscription, multiple local consumers share one bus while keeping outputs isolated by event type and subscription, and the mono/multi event Skills ship with the binary.
+- **Open product command capabilities** (#608) — adds Sheet table, pivot-table, and gridline commands; Chat message favorites; Drive statistics and shortcuts; and Doc comment update/delete, with matching mono/multi Skill documentation and command-contract coverage.
+- **Local user-operation audit log** (#555) — operations executed through `dws` now produce redacted daily JSONL records with actor, command and endpoint, result or error category, duration, CLI/platform metadata, and a SHA-256 previous-hash chain for tamper evidence. Writers coordinate through a cross-process file lock and rotate logs safely; `dws audit tail` inspects recent records, `dws audit export` emits date-filtered JSONL or CSV, and `dws audit verify` reports the first broken link in a file's hash chain.
+- **Stable Agent command catalog** (#598) — `dws schema` now ships a deterministic 22-product / 564-tool catalog generated from the executable Cobra tree, with progressive product/group/leaf queries, complete parameter contracts, reviewed command identity and aliases, safety/confirmation metadata, field provenance, and final-delivery completeness/drift gates. The catalog is embedded at build time and does not require runtime MCP `tools/list` discovery.
+- **Reviewed Schema for local commands** (#598, #609) — `event consume/list/schema/status/stop` and `audit export/tail/verify` enter the reviewed `CommandRegistry`, bind to the real Cobra tree at generation time, and ship through the same typed `ToolSpec` and embedded Catalog path as public MCP-backed commands. Leaf, group, product, and `--all` queries are projections of that single delivered model.
+- **Safe macOS Keychain → file-DEK migration** (#597) — `dws auth migrate-keychain --to file-dek` preflights every legacy/profile auth entry before rewriting, ignores unrelated application secrets, supports side-effect-free `--dry-run`, requires explicit `--yes`, and lets sandboxed and normal processes share an existing login without exposing tokens.
+
+### Changed
+
+- **`event consume` AI-subprocess contract** (#609) — emits a fixed ready line and a final controlled-exit summary, supports parent-pipe stdin EOF as graceful shutdown, forwards `--profile` to the detached bus, surfaces bus startup errors, and cleans up subscriptions according to ownership so orchestrators can drive event streams without sleeps or leaked server-side subscriptions.
+- **Wukong IM read-result parity** (#618) — `chat message list` preserves quoted merged-forward and image context; message-search entitlement failures retain the server-provided friendly hint and action URL; and `ding message list` exposes each DING's content alongside its ID and status.
+- **Developer ID signing for official macOS archives** (#605) — official releases now require both Darwin archives to be signed with the configured Apple Developer ID certificate, timestamp, and hardened runtime. The release job validates credentials and signatures and fails closed instead of silently publishing ad-hoc-signed official binaries.
+
+### Fixed
+
+- **Smart-category mappings and runtime network diagnostics** (#591) — `chat category create-smart` now maps category names, group-name keywords, and member OpenDingTalk IDs to the live MCP contract, rejects blank or empty supplied values locally, and reports runtime `tools/call` connection failures as actionable API/network errors instead of internal discovery failures.
+- **Connect daemon restart lifecycle** (#599) — pins the Stream SDK reconnect-race fix, snapshots the running executable before detaching, uses a real 30-second keepalive, and manages each worker as its own Unix process group so launcher cleanup or worker panics no longer cause restart loops or orphan local-agent processes.
+- **Complex Connect messages and attachments** (#606, #612) — rich-text messages retain all embedded pictures in order, queued turns keep every pending attachment, and unknown or future callback shapes reach each Agent backend with their message type and raw JSON instead of being discarded. Attachment recovery is locator-based, nested `chatRecord` pictures/audio/video/files can be recovered from message APIs after Stream ACK, and OpenCode uses a full-duration storyboard for large videos to avoid base64 OOMs while preserving the original download for the turn.
+- **macOS auth survives Keychain mode changes** (#597) — credential reads try existing compatible DEKs without creating key material, updates preserve the DEK that decrypted existing ciphertext, unreadable slots fail closed before token exchange, profile slots use the canonical auth backend, and `auth status` reports ciphertext/key mismatches instead of treating them as ordinary logout. Dedicated macOS race and Windows DPAPI coverage protect the cross-platform paths.
+
+## [1.0.51] - 2026-07-10
+
+This release promotes the sealed `v1.0.51-beta.1` contents to stable. It syncs the hardcoded Wukong command surface, prevents `dev connect` conversations from blocking on messages received mid-turn, and makes local credential failures diagnosable without mutating key material.
+
+### Added
+
+- **Agoal product commands** (#585) — adds `dws agoal` strategy, contract, scorecard, user-objective, report, and objective-template command groups, together with static routing and the bundled mono/multi Agoal skills.
+- **Wukong chat command parity** (#585) — adds `chat group notice create|edit|get|list`, `group share-invite`, `text translate`, `category create-smart`, and `message list-emotion-replies`.
+- **Wukong document import commands** (#585) — adds `doc import` for starting imports and `doc import get` for querying import tasks.
+- **Wukong mail command parity** (#585) — adds mailbox profile, message batch-get, sent-message recall and recall-detail, auto-reply update, plus allow-list and block-list management.
+- **Wukong sheet grouping commands** (#585) — adds `sheet group-dimension` and `sheet ungroup-dimension` for whole-row or whole-column ranges.
+- **Keychain health diagnostics** (#578) — `dws doctor` now includes a keychain check, while `dws auth status` distinguishes ordinary logged-out state from `keychain_unavailable` and `dek_missing` failures and returns remediation hints in table and JSON output.
+
+### Changed
+
+- **`dws pat chmod` defaults to permanent grants** (#584) — running `dws pat chmod <scope>` without `--grant-type` now requests a `permanent` grant instead of `session`, aligning the direct CLI path with the recommend-authorization helper. Session grants remain available by passing `--grant-type session --session-id <id>`.
+- **The `dev connect --channel gemini` path now uses the Gemini `generateContent` API** (#587) — configure it with `GEMINI_API_KEY` or `GOOGLE_API_KEY`, optionally override the compatible endpoint with `GEMINI_API_BASE_URL` or `GOOGLE_GEMINI_API_BASE_URL`, and select a model with `--agent-model` or `GEMINI_MODEL`; a local `gemini` executable is no longer required.
+
+### Fixed
+
+- **Non-blocking `dev connect` turn scheduling** (#587) — stream and `@`-poll callbacks no longer wait for the active turn to finish. Turns stay serialized per conversation, messages received mid-turn are coalesced into one pending follow-up, and different conversations can continue in parallel.
+- **Connect agent recovery and headless execution** (#587) — stale addressable sessions retry once with a fresh session, unsupported Qoder control requests receive an immediate response instead of hanging, OpenCode and bypass-mode channels receive non-interactive permission settings, and backend/API failures are no longer posted as successful assistant replies.
+- **Side-effect-free credential reads** (#578) — keychain reads inspect encrypted credential data before looking up the DEK and never generate a replacement key on a read path. Missing DEKs and unavailable macOS Keychains are surfaced as explicit diagnostic failures instead of silently mutating credential state.
+
+## [1.0.50] - 2026-07-08
+
+This release fixes a long-standing gap where the global `--jq` / `--fields` output filters were silently ignored on product commands, lands a JSON-mode output path for the sheet batch-style command, and aligns the bundled skill surface with the real command semantics uncovered by the round-2 real-machine QA sweep.
+
+### Fixed
+
+- **Global `--jq` / `--fields` are honored on product commands** (#575) — `Formatter.PrintJSON` / `PrintJSONUnescaped` now route through `output.WriteFiltered` when either flag is set, so product commands accept the same filters that `dws api` has always supported. The tool-caller adapter exposes `Fields()` / `JQ()` so helpers can read the flags without re-parsing.
+- **`skill setup --dry-run` is a no-op preview** (#575) — it now prints what would be written without touching the skill directory, the registry, or the agent config. Help text and docs are updated to match.
+- **Skill docs alignment to the real command surface** (#575) — per-product references and the cross-product intent guide clarify that `--fields` projects top-level / list keys only (use `--jq` for nested paths); `minutes_extract_todos.py`, `calendar_free_slot_finder.py`, `chat_export_messages.py` / `chat_history_with_user.py`, and `contact_dept_members.py` are rewritten against the current response shapes; `aisearch` / `aitable` / `attendance` / `calendar` / `chat` / `contact` / `dev` / `doc` / `doc-comment` / `doc-file-ops` / `doc-list` / `doc-search` / `drive` / `mail` / `minutes` / `oa` / `sheet` / `sheet-export` / `url-patterns` / `best_practices/lite-recipes.md` / `global-reference.md` / `intent-guide.md` are re-synced; the QA voice ("真机" phrasing) and environment-specific quirks stated as absolute rules are removed from the docs.
+
+### Changed
+
+- **`sheet range batch-set-style` emits per-row JSON in JSON mode** (#575) — when `--format json` is set, each update is reported as `{index, sheetId, range, ok, error}` instead of only the final aggregate, so callers can programmatically track partial failures under `--continue-on-error`.
+- **Command-merge helpers exported** — `pkg/cmdutil.LeafMerge*` and the provenance helpers are now public so downstream command trees can reuse the same merge semantics.
+
+## [1.0.49] - 2026-07-08
+
+This release lands a full real-machine QA sweep across the CLI, helper scripts, and skill docs (#572), and hardens the release pipeline so npm publishing can no longer be blocked by Gitee mirror issues (#570).
+
+### Fixed
+
+- **Real-machine QA fixes across CLI commands** (#572) — `aitable chart/dashboard share update --enabled` now takes a string so `--enabled false` disables; `chat conversation-info --user` resolves openDingTalkId and registers `--id/--conversation-id/--chat` aliases; `chat list-all-conversations --limit` is capped at 100 and rejects larger values; custom-robot webhook failures surface `errcode` instead of masquerading as success; `contact` registers `--dept/--depts` as the primary flags so the documented spelling actually works; `sheet media-upload` and `sheet export` emit clean JSON under `--format json` (progress lines no longer leak); `wiki node create --type` enum is corrected (drops unsupported `asheet`, adds `axls/able/appt/adraw/amind`); `ding message list --type` defaults to `ALL` since the server rejects empty type.
+- **Helper script fixes (mono and multi)** (#572) — aitable import/export flag names and the tableId regex (7-char default tables were rejected); mail search `--limit`, contact dept response keys (`deptList`/`deptUserList`) and `userInfo` nesting; `attendance_my_record` whoami compatibility; `calendar_schedule_meeting` event-id unwrapping; `drive_tree_list` recursion via `fileId`; report scripts migrated off the deprecated `report list`/`report detail`.
+- **Skill docs sync (mono and multi)** (#572) — command indexes, flag names, enums, return-structure keys and cross-product intent routing are re-aligned to real-machine behavior across all products. Genuinely server-side limitations (permission gates, org-level restrictions, unregistered tool keys) are annotated instead of code-patched, and the cross-cutting hazards (`success` always true, `--jq`/`--fields` currently no-op) are documented.
+
+### Changed
+
+- **Release pipeline unblocks npm publish from Gitee mirror** (#570) — the Release workflow now publishes to npm before touching the Gitee mirror, so Gitee upload issues cannot block `npm/latest`. GitHub→Gitee attachment upload is disabled by default (unreliable from US runners) and only runs when `ENABLE_GITEE_UPLOAD_FALLBACK=true`; the legacy upload fallback path is guarded with timeout and retry so it fails fast when re-enabled.
+- **Repair modes for release republish** (#570) — the Release workflow gains a repair input and a standalone npm-only repair workflow, used to republish an existing release to npm without re-running the full pipeline.
+
+## [1.0.48] - 2026-07-07
+
+This release promotes the sealed **remove-discovery delivery** from the beta line to the stable `v1.0.48` package. It removes dynamic service discovery from the open-edition runtime, keeps legacy CLI compatibility aliases, syncs the open command/help/skill surface with the dws-wukong baseline, and includes the `dev connect` default-yolo behavior on the stable upgrade track.
+
+### Changed
+
+- **Remove-discovery delivery is now formal/stable** — the beta validation line is ready to cut as `v1.0.48`; normal stable channels (`dws upgrade`, GitHub `releases/latest`, install scripts, and npm `latest`) should receive this release after the official tag is published.
+- **Static endpoint runtime sealed for stable delivery** — the open edition no longer depends on dynamic service discovery at runtime, while preserving legacy command compatibility aliases and the synced help/skill surface from the beta.
+- **`contact label` is restored as real wukong-compatible functionality** — `dws contact label list/get/list-members` now call `get_org_labels`, `search_label_by_name`, and `get_label_members_by_labelId`; `contact role` remains an alias, and the common top-level compatibility entries (`contact search/find/list/get/self/me/whoami/get-self`) now dispatch to real user/dept/label tools where unambiguous.
+- **Skill docs match the sealed command surface** — contact docs again describe the real `contact label` three-step role lookup flow; video-conference start/invite/share flows remain explicitly unsupported and point users to the DingTalk client.
+
+### Fixed
+
+- **`calendar event list --dry-run` no longer executes the real list call** — the sorted event-list wrapper now respects dry-run and prints the `list_calendar_events` preview instead of calling the backend.
+- **`chat file upload` is downlined** — the hidden compatibility entry now returns a clear downline message and never calls `chat/upload_conversation_file_by_url`; the supported file path remains `chat message send --msg-type file --file-path`.
+- **Optional plugin version validation no longer pollutes every command** — incompatible local plugins such as conference are skipped at debug level during command-tree construction instead of printing a WARN on unrelated commands.
+- **PR #45 review follow-ups are folded into the release** — doc version rollback pagination now unwraps nested result/content/data envelopes for `nextCursor`, mail helper scripts handle `{result:{emailAccounts:[...]}}`, and the generated attendance `.xlsx` fixture is removed from the skill scripts.
+
+### Tests
+
+- **Command-surface regression tests** — root-command tests now cover real `contact label`/`role` dry-runs, hidden top-level contact compatibility entries, `chat file upload` downline behavior, and `calendar event list --dry-run`.
+- **Release hygiene tests** — skill markdown policy still blocks unsupported conference routes, plugin loader tests assert optional validation failures stay quiet at WARN level, and doc version cursor extraction has nested-envelope coverage.
 ## [1.0.47] - 2026-07-05
 
 This release adds **connector supervision & health monitoring** (`dev connect list/status/restart/stop`) and fixes **bot-to-bot @-mention** delivery end-to-end.

CONTRIBUTING.md

@@ -36,8 +36,8 @@ Common repository checks already used here include:
 ./scripts/policy/check-open-source-assets.sh
 go test ./...
 make test
+make test-plan
 make lint
-bash test/scripts/run_all_tests.sh --jobs 8
 ./scripts/policy/check-generated-drift.sh
 ./scripts/policy/check-command-surface.sh --strict
 ./scripts/release/verify-package-managers.sh
@@ -48,7 +48,7 @@ git diff --check
 
 1. Keep implementation and tests in sync.
 2. Run `./scripts/dev/ci-local.sh`.
-3. Run `./scripts/policy/check-command-surface.sh --strict` when command paths/flags change.
+3. Run `./scripts/policy/check-command-surface.sh --strict` when command paths/flags change. CI also runs `./scripts/policy/check-command-compatibility.sh --base-ref <main-ref> --stable-ref <latest-GA-tag>` against both the target branch and latest stable release.
 4. Run `./scripts/policy/check-generated-drift.sh` when generated artifacts may change.
 5. Run `./scripts/release/verify-package-managers.sh` when packaging or installer surfaces change (run `make package` first).
 6. Update docs and `CHANGELOG.md` for behavior/interface changes.

Formula/dingtalk-workspace-cli-beta.rb

@@ -0,0 +1,63 @@
+class DingtalkWorkspaceCliBeta < Formula
+  desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
+  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  version "1.0.53-beta.4"
+  license "Apache-2.0"
+  keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-darwin-arm64.tar.gz"
+      sha256 "32a442d5b42dfed8512a695a7cef513722db6912f3c3168954cfaefb68e0b075"
+    else
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-darwin-amd64.tar.gz"
+      sha256 "00c694677b9ce2e1a711535740681defe0a5f83d6b72140f305483501628faf8"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-linux-arm64.tar.gz"
+      sha256 "98516620e861e516cf846cf418f1a0ad5c5eb9a8681bd066b1fd29f4847aca6a"
+    else
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-linux-amd64.tar.gz"
+      sha256 "266df80e8a989971789a157dd134685a7c9eda01dd1d082719ec9e09d5a07bf0"
+    end
+  end
+
+  resource "skills" do
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.53-beta.4/dws-skills.zip"
+    sha256 "6770511ab9b04b4d97da1858069ff694830ba91d47c1e8564fd85856f95b016e"
+  end
+
+  def install
+    root = Dir["dws-*"].find { |entry| File.directory?(entry) } || "."
+    binary = File.join(root, "dws")
+    raise "binary not found: #{binary}" unless File.exist?(binary)
+
+    bin.install binary => "dws"
+
+    %w[LICENSE NOTICE README.md CHANGELOG.md].each do |name|
+      source = File.join(root, name)
+      pkgshare.install source if File.exist?(source)
+    end
+
+    skill_dest = pkgshare/"skills/dws"
+    skill_dest.mkpath
+    resource("skills").stage do
+      cp_r(Dir["*"], skill_dest)
+    end
+  end
+
+  def caveats
+    <<~EOS
+      Agent Skills are bundled in #{pkgshare}/skills/dws.
+      Run `dws skill setup` to install them into your Agent directories.
+      This beta is keg-only. Add #{opt_bin} to PATH to use its `dws` binary.
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/dws version")
+  end
+end

Formula/dingtalk-workspace-cli.rb

@@ -0,0 +1,61 @@
+class DingtalkWorkspaceCli < Formula
+  desc "Automate DingTalk workspace tasks from the terminal"
+  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  version "1.0.52"
+  license "Apache-2.0"
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-darwin-arm64.tar.gz"
+      sha256 "4f6b4d064a76bcefac42feb5f356253fe43f9499b8cec9d2cdf202e7d3b9b60c"
+    else
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-darwin-amd64.tar.gz"
+      sha256 "abc87128f4b98d0a01ea99235449031971db8fa4ce94167403e3b736c4b81e9a"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-linux-arm64.tar.gz"
+      sha256 "0d357ef0535f99f2f63b5ecbfdee9c32448be2a2c24f3096c03126b3b7570bc5"
+    else
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-linux-amd64.tar.gz"
+      sha256 "b7dfd9a4b3489211359261747ed0cb9c8c261434bb762ad3f76df33bdbabd5cb"
+    end
+  end
+
+  resource "skills" do
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.52/dws-skills.zip"
+    sha256 "0fa3c8dec500c1659e6480d6772ae901b2d12d24322dd5d7283f016024290c21"
+  end
+
+  def install
+    root = Dir["dws-*"].find { |entry| File.directory?(entry) } || "."
+    binary = File.join(root, "dws")
+    raise "binary not found: #{binary}" unless File.exist?(binary)
+
+    bin.install binary => "dws"
+
+    %w[LICENSE NOTICE README.md CHANGELOG.md].each do |name|
+      source = File.join(root, name)
+      pkgshare.install source if File.exist?(source)
+    end
+
+    skill_dest = pkgshare/"skills/dws"
+    skill_dest.mkpath
+    resource("skills").stage do
+      cp_r(Dir["*"], skill_dest)
+    end
+  end
+
+  def caveats
+    <<~EOS
+      Agent Skills are bundled in #{pkgshare}/skills/dws.
+      Run `dws skill setup` to install them into your Agent directories.
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/dws version")
+  end
+end

Makefile

@@ -1,6 +1,14 @@
 GO ?= go
+DWS_PACKAGE_VERSION ?= 0.0.0-test
+REMOTE ?=
+PUBLISH ?= 0
+YES ?= 0
+DWS_POLICY_TMPDIR ?= $(CURDIR)/.worktrees/policy-tmp
+POLICY_GOTMPDIR ?= $(DWS_POLICY_TMPDIR)/go
+POLICY_ENV = DWS_POLICY_TMPDIR="$(DWS_POLICY_TMPDIR)" GOTMPDIR="$(POLICY_GOTMPDIR)"
+GO_SOURCE_LIST = git ls-files -z --cached --others --exclude-standard -- '*.go'
 
-.PHONY: all help build rebuild test lint fmt policy edition-test package release publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema generate-schema-agent-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
 
 all: setup-hooks fmt lint build test rebuild
 
@@ -8,11 +16,30 @@ help:
 	@printf "Available targets:\n"
 	@printf "  make build         - Build the dws CLI binary\n"
 	@printf "  make test          - Run the Go test suite\n"
-	@printf "  make lint          - Run formatting checks and golangci-lint when available\n"
-	@printf "  make fmt           - Format Go source files\n"
-	@printf "  make policy        - Run open-source asset and command-surface checks\n"
-	@printf "  make package       - Build all release artifacts locally (goreleaser snapshot)\n"
-	@printf "  make release       - Build and publish a release via goreleaser\n"
+	@printf "  make test-plan     - Verify every default Go package belongs to one CI test shard\n"
+	@printf "  make lint          - Run formatting checks, go vet, and staticcheck\n"
+	@printf "  make format-check  - Check all repository Go source files with gofmt\n"
+	@printf "  make fmt           - Format all repository Go source files\n"
+	@printf "  make policy        - Check the built dws plus open-source and Schema policies\n"
+	@printf "  make interface-integrity - Check historical commands and help contracts still work\n"
+	@printf "  make authoritative-interface-integrity BASE_REF=<ref> - Check the Git-owned PR merge-base\n"
+	@printf "  make coverage-gate BASE_REF=<ref> - Enforce overall non-regression and 100%% changed-code coverage\n"
+	@printf "  make coverage-gate-platform BASE_REF=<ref> PROFILE=<file> - Enforce 100%% native changed-code coverage\n"
+	@printf "  make update-interface-baseline - Add new CLI contracts without removing history\n"
+	@printf "  make reset-interface-baseline - DANGEROUS: replace all CLI compatibility history\n"
+	@printf "  make schema-compatibility BASE_REF=<ref> - Check the complete Schema contract against the PR merge-base\n"
+	@printf "  make skill-command-integrity - Check dws commands referenced by skills exist\n"
+	@printf "  make cli-smoke     - Verify help for every public top-level command\n"
+	@printf "  make mock-mcp-smoke - Verify HTTP and stdio MCP request/response transport\n"
+	@printf "  make test-schema-agent-examples - Contract-check all Agent examples and dry-run the eligible subset\n"
+	@printf "  make generate-schema - Regenerate embedded Agent metadata and the release Catalog\n"
+	@printf "  make generate-schema-agent-metadata - Regenerate versioned Agent metadata\n"
+	@printf "  make generate-schema-catalog - Regenerate the embedded release Catalog\n"
+	@printf "  make package       - Build all release artifacts locally\n"
+	@printf "  make changelog-pre VERSION=vX.Y.Z-beta.N - Prepare prerelease notes\n"
+	@printf "  make changelog-stable VERSION=vX.Y.Z FROM_BETA=vX.Y.Z-beta.N - Prepare stable notes\n"
+	@printf "  make release-pre VERSION=vX.Y.Z-beta.N [PUBLISH=1] - Validate or publish prerelease\n"
+	@printf "  make release-stable VERSION=vX.Y.Z FROM_BETA=vX.Y.Z-beta.N [PUBLISH=1] - Validate or publish stable\n"
 	@printf "  make publish-homebrew-formula - Push dist/homebrew/dingtalk-workspace-cli.rb to a tap repo\n"
 
 build:
@@ -22,24 +49,117 @@ rebuild:
 	@./scripts/dev/build.sh
 
 test:
-	@./test/scripts/run_all_tests.sh
+	@DWS_PACKAGE_VERSION="$(DWS_PACKAGE_VERSION)" $(GO) test -count=1 -timeout=10m ./...
+
+test-plan:
+	@./scripts/ci/test-packages.sh verify
 
 lint:
 	@./scripts/dev/lint.sh
 
+format-check:
+	@set -eu; \
+	go_files="$$(mktemp "$${TMPDIR:-/tmp}/dws-go-files.XXXXXX")"; \
+	trap 'rm -f "$$go_files"' EXIT HUP INT TERM; \
+	$(GO_SOURCE_LIST) > "$$go_files"; \
+	unformatted="$$(xargs -0 sh -c 'if [ "$$#" -gt 0 ]; then exec gofmt -l -- "$$@"; fi' sh < "$$go_files")"; \
+	if [ -n "$$unformatted" ]; then \
+		printf '%s\n' "$$unformatted"; \
+		printf '%s\n' "Go files are not formatted. Run 'make fmt'." >&2; \
+		exit 1; \
+	fi
+
 fmt:
-	@find cmd internal test -name '*.go' -print0 2>/dev/null | xargs -0r gofmt -w
+	@set -eu; \
+	go_files="$$(mktemp "$${TMPDIR:-/tmp}/dws-go-files.XXXXXX")"; \
+	trap 'rm -f "$$go_files"' EXIT HUP INT TERM; \
+	$(GO_SOURCE_LIST) > "$$go_files"; \
+	xargs -0 sh -c 'if [ "$$#" -gt 0 ]; then exec gofmt -w -- "$$@"; fi' sh < "$$go_files"
 
 policy:
-	@./scripts/policy/check-open-source-assets.sh
-	@./scripts/policy/check-command-surface.sh --strict
+	@mkdir -p "$(POLICY_GOTMPDIR)"
+	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
+	@$(POLICY_ENV) ./scripts/policy/check-schema-command-registry.sh
+	@$(POLICY_ENV) ./scripts/policy/check-command-surface.sh --strict
+	@$(POLICY_ENV) ./scripts/policy/check-generated-drift.sh
+	@$(POLICY_ENV) ./scripts/policy/check-schema-catalog.sh
+	@$(POLICY_ENV) ./scripts/policy/check-schema-binary.sh
+	@$(POLICY_ENV) $(MAKE) test-schema-agent-examples
 
 edition-test:
 	$(GO) test -v -count=1 ./pkg/editiontest/...
 
+interface-integrity:
+	@./scripts/policy/check-interface-baseline.sh
+
+authoritative-interface-integrity:
+	@./scripts/policy/check-authoritative-interface-baselines.sh --base-ref "$(BASE_REF)"
+
+coverage-gate:
+	@./scripts/policy/check-coverage-gate.sh --base-ref "$(BASE_REF)" --scope-buildable
+
+coverage-gate-platform:
+	@./scripts/policy/run-platform-coverage-gate.sh --base-ref "$(BASE_REF)" --profile "$(PROFILE)"
+
+update-interface-baseline:
+	@./scripts/policy/check-interface-baseline.sh --update
+
+reset-interface-baseline:
+	@./scripts/policy/check-interface-baseline.sh --reset
+
+schema-compatibility:
+	@./scripts/policy/check-authoritative-schema-compatibility.sh --base-ref "$(BASE_REF)"
+
+skill-command-integrity:
+	@./scripts/policy/check-skill-commands.sh
+
+cli-smoke:
+	@./scripts/policy/check-cli-smoke.sh
+
+mock-mcp-smoke:
+	$(GO) test -v -count=1 -run '^(TestHTTPClientEndToEnd|TestStdioClientEndToEnd)$$' ./internal/transport
+
+test-schema-agent-examples:
+	DWS_AGENT_EXAMPLES_DRY_RUN=1 $(GO) test -v -count=1 ./internal/app -run '^TestManualAgentExamplesDryRun$$'
+
+generate-schema:
+	@set -e; \
+	registry_guard=$$(mktemp); \
+	metadata_guard=$$(mktemp -d); \
+	selection_guard=$$(mktemp -d); \
+	trap 'rm -rf "$$registry_guard" "$$metadata_guard" "$$selection_guard"' EXIT HUP INT TERM; \
+	cp internal/cli/schema_command_registry.json "$$registry_guard"; \
+	cp -R internal/cli/schema_hints/metadata/. "$$metadata_guard/"; \
+	cp -R internal/cli/schema_hints/selection/. "$$selection_guard/"; \
+	$(GO) generate ./internal/cli; \
+	cmp -s internal/cli/schema_command_registry.json "$$registry_guard" || { \
+		printf '%s\n' 'generation modified reviewed input internal/cli/schema_command_registry.json' >&2; \
+		exit 1; \
+	}; \
+	diff -qr internal/cli/schema_hints/metadata "$$metadata_guard" >/dev/null || { \
+		printf '%s\n' 'generation modified reviewed input internal/cli/schema_hints/metadata' >&2; \
+		exit 1; \
+	}; \
+	diff -qr internal/cli/schema_hints/selection "$$selection_guard" >/dev/null || { \
+		printf '%s\n' 'generation modified reviewed input internal/cli/schema_hints/selection' >&2; \
+		exit 1; \
+	}
+
+generate-schema-agent-metadata:
+	$(GO) run ./internal/generator/cmd_schema_agent_metadata \
+		-root . \
+		-registry internal/cli/schema_command_registry.json \
+		-output-dir internal/cli/schema_agent_metadata \
+		-audit-output internal/cli/schema_agent_metadata_audit.json
+
+generate-schema-catalog:
+	$(GO) run -a ./internal/generator/cmd_schema_catalog \
+		-root . \
+		-output internal/cli/schema_catalog.json
+
 package:
-	@./scripts/dev/build-all.sh
-	@./scripts/release/post-goreleaser.sh
+	@version="$(if $(VERSION),$(VERSION),v0.0.0-SNAPSHOT)"; VERSION="$${version#v}" ./scripts/dev/build-all.sh
+	@version="$(if $(VERSION),$(VERSION),v0.0.0-SNAPSHOT)"; DWS_PACKAGE_VERSION="$$version" ./scripts/release/post-goreleaser.sh
 
 publish-homebrew-formula:
 	@./scripts/release/publish-homebrew-formula.sh
@@ -47,6 +167,32 @@ publish-homebrew-formula:
 setup-hooks:
 	@git config core.hooksPath scripts/hooks 2>/dev/null || true
 
+changelog-pre:
+	@test -n "$(VERSION)" || (printf 'VERSION is required, e.g. v1.2.3-beta.1\n' >&2; exit 2)
+	@./scripts/release/prepare-changelog.sh prerelease "$(VERSION)"
+
+changelog-stable:
+	@test -n "$(VERSION)" || (printf 'VERSION is required, e.g. v1.2.3\n' >&2; exit 2)
+	@test -n "$(FROM_BETA)" || (printf 'FROM_BETA is required, e.g. v1.2.3-beta.2\n' >&2; exit 2)
+	@./scripts/release/prepare-changelog.sh stable "$(VERSION)" --from-beta "$(FROM_BETA)"
+
+release-pre:
+	@test -n "$(VERSION)" || (printf 'VERSION is required, e.g. v1.2.3-beta.1\n' >&2; exit 2)
+	@test -n "$(REMOTE)" || (printf 'REMOTE is required, e.g. origin\n' >&2; exit 2)
+	@args=""; \
+	  if [ "$(PUBLISH)" = "1" ]; then args="$$args --publish"; fi; \
+	  if [ "$(YES)" = "1" ]; then args="$$args --yes"; fi; \
+	  ./scripts/release/release.sh prerelease "$(VERSION)" --remote "$(REMOTE)" $$args
+
+release-stable:
+	@test -n "$(VERSION)" || (printf 'VERSION is required, e.g. v1.2.3\n' >&2; exit 2)
+	@test -n "$(FROM_BETA)" || (printf 'FROM_BETA is required, e.g. v1.2.3-beta.2\n' >&2; exit 2)
+	@test -n "$(REMOTE)" || (printf 'REMOTE is required, e.g. origin\n' >&2; exit 2)
+	@args=""; \
+	  if [ "$(PUBLISH)" = "1" ]; then args="$$args --publish"; fi; \
+	  if [ "$(YES)" = "1" ]; then args="$$args --yes"; fi; \
+	  ./scripts/release/release.sh stable "$(VERSION)" --from-beta "$(FROM_BETA)" --remote "$(REMOTE)" $$args
+
 release:
-	goreleaser release --clean
-	@./scripts/release/post-goreleaser.sh
+	@printf 'Use make release-pre or make release-stable; direct goreleaser publishing is disabled.\n' >&2
+	@exit 2

README.md

@@ -71,9 +71,9 @@ The installer ships skills in one of two layouts. CLI commands (`dws aitable ...
 | Mode | What gets installed | Best for |
 |------|----------------------|----------|
 | **mono** (stable, default) | One `dws` skill covering all products | Cross-product workflows; single entry point |
-| **multi** 🧪 **EXPERIMENTAL** | 18 per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
+| **multi** 🧪 **EXPERIMENTAL** | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
 
-> 🧪 **`multi` is currently EXPERIMENTAL / preview.** 18 product-scoped skills all pass the dispatch verifier, but interface, naming and cross-skill references may change in future releases. For production / shared environments, prefer `mono`. File issues if you hit problems.
+> 🧪 **`multi` is currently EXPERIMENTAL / preview.** All product-scoped skills pass the dispatch verifier, but interface, naming and cross-skill references may change in future releases. For production / shared environments, prefer `mono`. File issues if you hit problems.
 
 How to pick:
 
@@ -93,6 +93,30 @@ How to pick:
 npm install -g dingtalk-workspace-cli
 ```
 
+Install the latest beta:
+
+```bash
+npm install -g dingtalk-workspace-cli@beta
+```
+
+**Homebrew** (macOS / Linux):
+
+```bash
+brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
+brew install dingtalk-workspace-cli
+```
+
+> The Formula lives in this repository, so the first `tap` command must include the explicit repository URL. Afterwards, use `brew upgrade dingtalk-workspace-cli` normally.
+
+Install the keg-only Homebrew beta without replacing the stable Formula:
+
+```bash
+brew install dingtalk-workspace-cli-beta
+$(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version
+```
+
+To make the beta `dws` the default for the current shell, prepend `$(brew --prefix dingtalk-workspace-cli-beta)/bin` to PATH.
+
 **Pre-built binary**: download from [GitHub Releases](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases).
 
 > **macOS users**: If you see "cannot be opened because Apple cannot check it for malicious software", run:
@@ -109,6 +133,10 @@ go build -o dws ./cmd       # build to current directory
 cp dws ~/.local/bin/         # install to PATH
 ```
 
+Static endpoint data is generated from the Wukong baseline and committed in this
+repository under `internal/syncdata`, so source builds do not require a sibling
+data checkout.
+
 > Requires Go 1.25+. Use `make package` to cross-compile for all platforms (macOS / Linux / Windows x amd64 / arm64).
 
 </details>
@@ -152,12 +180,30 @@ dws has built-in self-upgrade capability. Updates are pulled directly from [GitH
 ```bash
 dws upgrade                    # interactive upgrade to latest version
 dws upgrade --check            # check for new versions without installing
-dws upgrade --list             # list all available versions
+dws upgrade --list             # list stable release versions
+dws upgrade --beta             # upgrade to the latest beta pre-release
+dws upgrade --check --beta     # check the beta track without installing
+dws upgrade --list --beta      # list beta pre-release versions
 dws upgrade --version v1.0.7   # upgrade to a specific version
+dws upgrade --version v1.0.8-beta.1  # upgrade to a specific beta version
 dws upgrade --rollback         # rollback to the previous version
 dws upgrade -y                 # skip confirmation prompt
 ```
 
+By default, `dws upgrade` follows the stable release track. Use `--beta` only when you explicitly want the newest GitHub pre-release build.
+
+### Six-channel post-release verification
+
+Maintainers and release validators can run the release-quality smoke checks for curl, PowerShell, npm stable, npm beta, Homebrew, and `dws upgrade`:
+
+```bash
+git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git /tmp/dws-verify
+cd /tmp/dws-verify/verify
+bash verify-all-channels.sh
+```
+
+The verifier uses isolated directories and does not replace the `dws` on the current PATH. It reports `PASS`, `FAIL`, and `SKIP`; a platform skip is not a pass and must be covered on the matching host. See [`verify/README.md`](verify/README.md) for the platform matrix.
+
 <details>
 <summary><strong>How it works</strong></summary>
 
@@ -171,8 +217,9 @@ A backup of the current version is automatically created before each upgrade. Us
 | Flag | Description |
 |------|-------------|
 | `--check` | Check for updates without installing |
-| `--list` | List all available versions with changelogs |
-| `--version` | Upgrade to a specific version (e.g. `v1.0.7`) |
+| `--list` | List available stable release versions with changelogs |
+| `--beta` | Use the beta pre-release track for `upgrade`, `--check`, or `--list` |
+| `--version` | Upgrade to a specific version (e.g. `v1.0.7` or `v1.0.8-beta.1`) |
 | `--rollback` | Rollback to the previous backed-up version |
 | `--force` | Force reinstall even if already on the latest version |
 | `--skip-skills` | Skip skill package update |
@@ -236,16 +283,32 @@ Credentials are securely persisted after first login (Keychain). Subsequent runs
 <details>
 <summary><strong>Multiple organizations (profiles)</strong></summary>
 
-`dws` can stay logged in to several DingTalk organizations at once. Each organization is one **profile**; the current profile decides which org a command runs against (credentials are stored per organization).
+`dws` can stay logged in to several DingTalk accounts at once, including multiple accounts in the same organization. A profile is uniquely identified by `corpId:userId`; the current profile decides which identity a command runs as.
 
 ```bash
-dws auth login                              # log in to another org → adds a profile (first login becomes the primary)
-dws profile list                            # list logged-in orgs (primary / current marker, status)
-dws profile switch <name|corpId>            # switch the default org (use - to toggle back to the previous one)
-dws --profile <name|corpId> contact user search --query "..."   # run one command against a specific org, without changing the default
+dws auth login                              # add or refresh one account
+dws profile list                            # list every logged-in account
+dws profile switch <corpId:userId>          # persistently switch; use - to toggle back
+dws profile switch "<corpName>:<userName>"  # friendly input; names must be unique
+dws --profile <corpId> contact user search --query "..."        # use that org's explicitly recorded current account
+dws --profile <corpId:userId> contact user search --query "..." # use one exact account without changing the default
 ```
 
-Cross-org reads are orchestrated by the agent rather than a built-in `--all-orgs`: list the profiles, run the query per org with `--profile`, then merge. Writes default to the current org only — confirm the target org before writing across orgs.
+Selectors support `corpId:userId`, `corpId:userName`, `corpName:userId`, and `corpName:userName`. Friendly names are input aliases only; use the stable `profile` value returned by `profile list` for automation. Duplicate organization or account names fail with explicit `corpId:userId` candidates. If an organization has multiple accounts but no recorded current account, `--profile <corpId>` fails instead of choosing the first or most recently used account.
+
+`currentProfile`, `previousProfile`, and per-organization defaults are stored as exact identities. `primaryProfile` remains in JSON only for compatibility and is not used for selection. `profile list` reads status and expiry from each real identity Token without refreshing it. `auth logout --profile <corpId>` removes all local accounts in that organization; an exact selector or local profile name removes one account.
+
+Cross-org reads are orchestrated by the agent rather than a built-in `--all-orgs`: list profiles, group by `corpId`, and use the unique `isOrgCurrent=true` account for each organization. If a multi-account organization has no default, ask the user to choose an account first. Writes default to the current account — confirm both organization and account before cross-org writes.
+
+On macOS, an unreadable registered token slot blocks a new OAuth login rather than risking a mixed Keychain/file-DEK state. If normal terminal commands can still read the login while a sandbox using `DWS_DISABLE_KEYCHAIN=1` cannot, migrate the legacy and profile auth entries without exposing tokens:
+
+```bash
+env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json
+env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --yes --format json
+DWS_DISABLE_KEYCHAIN=1 dws auth status --format json
+```
+
+The migration validates every selected auth ciphertext before writing, ignores unrelated application secrets, and can be rerun after an interrupted commit. If validation identifies genuinely damaged ciphertext, remove only the affected account with `dws auth logout --profile <corpId:userId>`, or all accounts in one organization with `--profile <corpId>`, then log in again. Use `dws auth reset` only when you intend to discard every local profile.
 
 </details>
 
@@ -266,6 +329,9 @@ dws auth status   # confirm "Refresh Token: valid"
 ```
 
 The bundle includes the encrypted keychain under `~/.local/share/dws-cli` (with `auth-token.enc` and `dek`) plus required `~/.dws` config files.
+Windows export and import are intentionally rejected before credentials or
+bundles are read: Windows stores credentials as DPAPI-protected HKCU Registry
+values, and the current file-DEK bundle has no safe DPAPI-to-portable conversion.
 
 </details>
 
@@ -300,30 +366,37 @@ dws contact user search --query "engineering" --dry-run
 dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'
 ```
 
-### Schema Discovery
+### Command Help and Schema
 
-Agents don't need pre-built knowledge of every command. Use `dws schema` to dynamically discover capabilities:
+Use Cobra help and Schema for different parts of the command contract:
+
+- `dws <path> --help` is the source of truth for whether a command exists and which flags the binary accepts.
+- `dws schema "<path>"` is the Agent contract for command selection, parameter mappings and constraints, risk, and confirmation semantics.
+- If Help and Schema disagree, treat it as contract drift: pass only flags accepted by Cobra and use the more conservative safety semantics.
+- Schema describes commands; it does not read or search DingTalk business data. Execute the real product command after discovery.
 
 ```bash
-# Step 1: Discover all available products
-dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'
+# Confirm that the command exists and inspect accepted flags
+dws aitable record query --help
 
-# Step 2: Inspect target tool's parameter schema
-dws schema aitable.query_records --jq '.tool.parameters'
+# Discover within a product, then inspect the selected leaf contract
+dws schema aitable
+dws schema "aitable record query"
 
-# Optional: inspect DingTalk authorization metadata for PAT planning
-dws schema aitable.query_records --jq '.tool.auth'
-
-# Step 3: Construct the correct call
+# Execute the real business query
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
 ```
 
+`dws schema --all` exports the complete contract for tooling, CI, audits, and compatibility baselines. Agents should prefer product/group discovery followed by a leaf query to avoid loading the full Catalog into context.
+
 ### Agent Skills
 
-The repo ships a complete Agent Skill system under `skills/`, now organized into two layouts:
+The repo ships a complete Agent Skill system under `skills/`, organized into two layouts:
 
 - `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), recommended default.
-- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ... 20 products in total), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**
+- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**
+
+Shared reviewed inputs for Schema generation live separately under `internal/cli/schema_hints/`. They are not Agent Skills and are excluded from binaries and release skill bundles.
 
 After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:
 
@@ -398,6 +471,56 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
 
 ## Features
 
+<details>
+<summary><strong>Personal Event Subscription</strong> — real-time DingTalk messages for event-driven agents</summary>
+
+`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog currently covers messages that mention the current user, one-to-one messages with a specified user, and messages in a specified group.
+
+> **Prerequisite**: run `dws auth login`. Personal identity is resolved from the OAuth token and cannot be supplied through command-line identity flags.
+
+For an event-focused installation, use the official convenience installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh
+```
+
+```bash
+# Inspect the public personal event catalog and schema
+dws event list
+dws event schema user_im_message_receive_o2o
+
+# Listen for messages that mention the current user
+dws event consume user_im_message_receive_at -f ndjson
+
+# Listen for one-to-one messages with a specified user
+dws event consume user_im_message_receive_o2o --user <userId> -f ndjson
+
+# Listen by openDingtalkId (external contact, bot, or cross-organization identity)
+dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> -f ndjson
+
+# Listen for messages in a specified group
+dws event consume user_im_message_receive_group --group <openConversationId> -f ndjson
+
+# Inspect local consumers and cancel a subscription
+dws event status
+dws event stop <subscribe_id>
+```
+
+For one-to-one and specified-sender events, use exactly one target identity: `--user` for an internal `userId`, or `--open-dingtalk-id` for an `openDingtalkId`. The CLI does not infer or convert between these identity types.
+
+| Feature | Details |
+|---------|---------|
+| Managed lifecycle | `consume` creates or reuses the personal subscription; `stop` cancels it and cleans local state |
+| Shared connection | Consumers for the same user share one local bus and cloud connection |
+| Subscription isolation | Normal consumers match both event type and `subscribe_id` |
+| Agent-friendly output | Stream events are written to stdout as NDJSON; status and diagnostics use stderr |
+| Observability | `status` shows remote subscriptions, the personal bus, and local consumers |
+| Cross-platform | Unix Socket on macOS/Linux, Windows Named Pipe on Windows |
+
+See `skills/multi/dingtalk-event/SKILL.md` for the Agent workflow and supported event parameters.
+
+</details>
+
 <details>
 <summary><strong>Raw API Access</strong> — call any DingTalk OpenAPI directly</summary>
 
@@ -479,7 +602,7 @@ dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-i
 ```bash
 # Built-in jq expressions
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
-dws schema --jq '.products[] | {id, tools: (.tools | length)}'
+dws schema "dev app create" --jq '.tool.required'
 
 # Return only specific fields
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response
@@ -488,14 +611,13 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocati
 </details>
 
 <details>
-<summary><strong>Schema Introspection</strong> — query parameter schemas before making calls</summary>
+<summary><strong>Schema Introspection</strong> — Agent command discovery and execution contracts</summary>
 
 ```bash
-dws schema                                              # list all products and tools
-dws schema aitable.query_records                        # view parameter schema
-dws schema aitable.query_records --jq '.tool.required'   # view required fields
-dws schema aitable.query_records --jq '.tool.auth'       # view authorization metadata
-dws schema --jq '.products[].id'                        # extract all product IDs
+dws schema aitable                                      # discover product commands
+dws schema "aitable record query"                       # view the selected leaf contract
+dws schema "aitable record query" --jq '.tool.required' # view required fields
+dws schema --all                                        # full export for CI/audit/baselines
 ```
 
 </details>
@@ -547,7 +669,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step
 
 | Service | Command | Capabilities |
 |---------|---------|--------------|
-| Contact | `contact` | Look up users by name / mobile / job-number, departments, labels & roles, roster profiles & dismissals |
+| Contact | `contact` | Look up users, departments, labels, roster profiles and dismissals; create enterprises and enterprise accounts; invite employees |
 | Chat / IM | `chat` (`im`) | Send / reply / search messages, group & member management, bot & webhook messaging, reactions, recall |
 | Calendar | `calendar` | Events CRUD, attendees, meeting rooms, free/busy & time suggestions |
 | Todo | `todo` | Create / list / update / complete tasks and comments |
@@ -626,7 +748,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step
 
 - [Command Index](./docs/command-index.md) — every runtime command with description and when-to-use guidance
 - [Reference](./docs/reference.md) — environment variables, exit codes, output formats, shell completion
-- [Architecture](./docs/architecture.md) — discovery-driven pipeline, IR, transport layer
+- [Architecture](./docs/architecture.md) — static endpoint pipeline, command surface, transport layer
 - [Open Platform App Command Routing](./docs/dev-yulan-command-routing.md) — yulan dev app command design, MCP overlay, permission flow, and Agent routing
 - [Changelog](./CHANGELOG.md) — release history and migration notes
 

README_zh.md

@@ -71,9 +71,9 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 | 模式 | 安装内容 | 适合场景 |
 |------|----------|----------|
 | **mono**（稳定，默认） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
-| **multi** 🧪 **试验版 / Preview** | 20 个独立产品 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
+| **multi** 🧪 **试验版 / Preview** | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
 
-> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。20 个独立 skill 全部通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。
+> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。全部独立 skill 均通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。
 
 怎么选：
 
@@ -93,6 +93,30 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma
 npm install -g dingtalk-workspace-cli
 ```
 
+安装最新 beta：
+
+```bash
+npm install -g dingtalk-workspace-cli@beta
+```
+
+**Homebrew**（macOS / Linux）：
+
+```bash
+brew tap DingTalk-Real-AI/dingtalk-workspace-cli https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git
+brew install dingtalk-workspace-cli
+```
+
+> Formula 与代码位于同一个仓库，因此首次 `tap` 需要显式指定仓库 URL。后续可直接使用 `brew upgrade dingtalk-workspace-cli`。
+
+安装 Homebrew beta（keg-only，不覆盖稳定版）：
+
+```bash
+brew install dingtalk-workspace-cli-beta
+$(brew --prefix dingtalk-workspace-cli-beta)/bin/dws version
+```
+
+如需让 beta 的 `dws` 成为当前 shell 默认版本，将 `$(brew --prefix dingtalk-workspace-cli-beta)/bin` 放到 PATH 最前面。
+
 **预编译二进制文件**：从 [GitHub Releases](https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases) 下载。
 
 > **macOS 用户注意**：如果提示“无法打开，因为 Apple 无法检查其是否包含恶意软件”，请执行：
@@ -110,6 +134,7 @@ cp dws ~/.local/bin/         # 安装到 PATH
 ```
 
 > 需要 Go 1.25+。也可以用 `make package` 构建所有平台产物（macOS / Linux / Windows × amd64 / arm64）。
+> 静态端点数据由悟空基线生成并提交在本仓库 `internal/syncdata`，源码构建不需要额外 checkout 数据仓库。
 
 </details>
 
@@ -152,12 +177,30 @@ dws 内置自升级能力，直接从 [GitHub Releases](https://github.com/DingT
 ```bash
 dws upgrade                    # 交互式升级到最新版本
 dws upgrade --check            # 仅检查是否有新版本
-dws upgrade --list             # 列出所有可用版本
+dws upgrade --list             # 列出正式 release 版本
+dws upgrade --beta             # 升级到最新 beta 预发布版本
+dws upgrade --check --beta     # 仅检查 beta 轨道是否有新版本
+dws upgrade --list --beta      # 列出 beta 预发布版本
 dws upgrade --version v1.0.7   # 升级到指定版本
+dws upgrade --version v1.0.8-beta.1  # 升级到指定 beta 版本
 dws upgrade --rollback         # 回滚到上一版本
 dws upgrade -y                 # 跳过确认直接升级
 ```
 
+默认情况下，`dws upgrade` 只跟随正式 release 轨道。只有显式传入 `--beta` 时，才会选择 GitHub pre-release 里的 beta 构建。
+
+### 六渠道发布后验证
+
+维护者和验证同学可按发版质量保障 SOP，对 curl、PowerShell、npm stable、npm beta、Homebrew、`dws upgrade` 执行安装与冒烟验证：
+
+```bash
+git clone https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli.git /tmp/dws-verify
+cd /tmp/dws-verify/verify
+bash verify-all-channels.sh
+```
+
+脚本使用隔离目录，不会替换当前 PATH 中的 `dws`；输出 `PASS`、`FAIL`、`SKIP` 汇总。跨平台渠道必须由对应平台补测，`SKIP` 不计为通过。验证范围和平台矩阵见 [`verify/README.md`](verify/README.md)。
+
 <details>
 <summary><strong>工作原理</strong></summary>
 
@@ -171,8 +214,9 @@ dws upgrade -y                 # 跳过确认直接升级
 | Flag | 说明 |
 |------|------|
 | `--check` | 仅检查更新，不安装 |
-| `--list` | 列出所有可用版本及更新日志 |
-| `--version` | 升级到指定版本（如 `v1.0.7`） |
+| `--list` | 列出正式 release 版本及更新日志 |
+| `--beta` | 对 `upgrade`、`--check`、`--list` 使用 beta 预发布轨道 |
+| `--version` | 升级到指定版本（如 `v1.0.7` 或 `v1.0.8-beta.1`） |
 | `--rollback` | 回滚到上一个备份版本 |
 | `--force` | 强制重新安装，即使已是最新版本 |
 | `--skip-skills` | 跳过技能包更新 |
@@ -236,16 +280,32 @@ dws auth login --client-id <your-app-key> --client-secret <your-app-secret>
 <details>
 <summary><strong>多组织（profile）</strong></summary>
 
-`dws` 可以同时登录多个钉钉组织。一个组织就是一个 **profile**，当前 profile 决定本次命令操作哪个组织（凭证按组织分别存储）。
+`dws` 可以同时登录多个钉钉账号，同一组织也能保留多个账号。一个 profile 由 `corpId + userId` 唯一确定。
 
 ```bash
-dws auth login                              # 再登录一个组织 → 新增一个 profile（首次登录的为主组织）
-dws profile list                            # 列出已登录组织（主 / 当前标记、状态）
-dws profile switch <名称|corpId>            # 切换默认组织（用 - 切回上一个）
-dws --profile <名称|corpId> contact user search --query "..."   # 单次对指定组织执行，不改默认组织
+dws auth login                              # 新增或刷新一个账号
+dws profile list                            # 列出全部账号，profile 字段是稳定的 corpId:userId
+dws profile switch <corpId:userId>          # 持久切换账号；用 - 切回上一个
+dws profile switch "组织名:用户名"          # 名称输入要求唯一
+dws --profile <corpId> contact user search --query "..."        # 使用该组织明确记录的当前账号
+dws --profile <corpId:userId> contact user search --query "..." # 单次精确指定账号，不改默认账号
 ```
 
-跨组织读取由 agent 编排，而非内置 `--all-orgs`：先 `dws profile list` 拿到组织，再对每个组织带 `--profile` 各查一遍，然后合并。写操作默认只在当前组织进行——跨组织写之前先确认目标组织。
+支持 `corpId:userId`、`corpId:userName`、`corpName:userId`、`corpName:userName`。名称只用于输入，自动化应使用 `profile list` 返回的稳定 `profile`。组织名或用户名重名时会列出候选并报错；同组织多账号但没有明确当前账号时，只传组织也会报错，不会选择第一项或最近使用账号。
+
+`currentProfile`、`previousProfile` 和组织默认账号都保存精确身份。`primaryProfile` 只为 JSON 兼容保留，不再参与选择。`profile list` 直接读取各身份 Token 计算状态和到期时间，不触发刷新。`auth logout --profile <corpId>` 退出该组织全部账号；精确选择器或本地 profile 名只退出一个账号。
+
+跨组织读取由 agent 编排，而非内置 `--all-orgs`：先 `dws profile list`，每个组织使用唯一的 `isOrgCurrent=true` 账号；若多账号组织没有默认账号，先让用户指定账号。写操作默认只在当前账号执行——跨组织写之前先确认目标组织和账号。
+
+macOS 下，如果已登记的 token slot 无法解密，为避免把系统 Keychain 和 file-DEK 写成混合状态，新的 OAuth 登录会直接拒绝。如果普通终端仍能读取登录态、只有设置 `DWS_DISABLE_KEYCHAIN=1` 的沙箱读不到，可在不暴露 token 的情况下迁移 legacy 与各 profile 的认证条目：
+
+```bash
+env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json
+env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --yes --format json
+DWS_DISABLE_KEYCHAIN=1 dws auth status --format json
+```
+
+迁移会先验证全部认证密文再写入、忽略无关的应用密钥；提交中断后可安全重跑。如果预检确认是密文本身损坏，优先使用 `dws auth logout --profile <corpId:userId>` 只清理受影响账号；只有确认要丢弃全部本地 profile 时才用 `dws auth reset`。
 
 </details>
 
@@ -300,27 +360,37 @@ dws contact user search --query "张三" --dry-run
 dws contact user get-self --jq '.result[0].orgEmployeeModel | {name: .orgUserName, dept: .depts[0].deptName, userId}'
 ```
 
-### Schema 发现
+### 命令帮助与 Schema
 
-Agent 无需预置所有命令知识，通过 `dws schema` 动态发现可用能力：
+命令帮助和 Schema 分别负责命令契约的不同部分：
+
+- `dws <path> --help` 是命令是否存在、当前二进制接受哪些 flags 的事实源。
+- `dws schema "<path>"` 是 Agent 选命令、参数映射与约束、风险和确认语义的契约。
+- Help 与 Schema 冲突时视为契约漂移：执行只传 Cobra 接受的参数，安全语义取更保守值。
+- Schema 只描述命令，不读取或搜索钉钉业务数据；发现命令后仍需执行真实产品命令。
 
 ```bash
-# 第一步：发现所有可用产品
-dws schema --jq '.products[] | {id, tool_count: (.tools | length)}'
+# 确认命令存在并查看当前接受的 flags
+dws aitable record query --help
 
-# 第二步：查看目标工具的参数结构
-dws schema aitable.query_records --jq '.tool.parameters'
+# 先在产品内发现命令，再查看选中 leaf 的契约
+dws schema aitable
+dws schema "aitable record query"
 
-# 第三步：构造正确的调用
+# 执行真实业务查询
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10
 ```
 
+`dws schema --all` 会完整导出命令契约，供工具、CI、审计和兼容性基线使用。Agent 应优先按产品/分组发现后查询 leaf，避免把整个 Catalog 加载进上下文。
+
 ### Agent Skills
 
-仓库内置完整的 Agent Skill 体系（`skills/` 目录），目前重组为两套布局：
+仓库内置完整的 Agent Skill 体系（`skills/` 目录），分为两套布局：
 
 - `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），默认推荐。
-- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ... 共 18 个），每个 skill 自带 `SKILL.md`。🧪 **试验版 / Preview — 各 multi `SKILL.md` 头部有详细注意事项。**
+- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。🧪 **试验版 / Preview — 各 multi `SKILL.md` 头部有详细注意事项。**
+
+Schema 生成共享的 reviewed 输入单独位于 `internal/cli/schema_hints/`。它们不是 Agent Skill，也不会进入二进制或发布 skill 包。
 
 安装之后，Claude Code / Cursor 等 AI 工具就能通过自然语言直接操作钉钉：
 
@@ -395,6 +465,56 @@ DWS_SKILL_SOURCE=/path/to/skills dws skill setup --mode multi
 
 ## 功能特性
 
+<details>
+<summary><strong>个人事件订阅</strong> — 实时接收钉钉消息，驱动事件触发的 Agent</summary>
+
+`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录包括：当前用户被 @ 的消息、与指定用户的单聊消息、指定群的消息。
+
+> **前置条件**：先运行 `dws auth login`。个人身份从 OAuth token 解析，不允许通过命令行伪造。
+
+只需要 event 能力时，可以使用官方便捷安装脚本：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-event.sh | sh
+```
+
+```bash
+# 查看公开个人事件目录和 schema
+dws event list
+dws event schema user_im_message_receive_o2o
+
+# 监听当前用户被 @ 的消息
+dws event consume user_im_message_receive_at -f ndjson
+
+# 监听与指定用户的单聊消息
+dws event consume user_im_message_receive_o2o --user <userId> -f ndjson
+
+# 使用 openDingtalkId 监听外部联系人、机器人或跨组织身份
+dws event consume user_im_message_receive_o2o --open-dingtalk-id <openDingtalkId> -f ndjson
+
+# 监听指定群的消息
+dws event consume user_im_message_receive_group --group <openConversationId> -f ndjson
+
+# 查看本地 consume，并取消指定订阅
+dws event status
+dws event stop <subscribe_id>
+```
+
+单聊和指定发送人事件必须且只能选择一种目标身份：企业内部 `userId` 使用 `--user`，`openDingtalkId` 使用 `--open-dingtalk-id`。CLI 不会自动猜测或转换身份类型。
+
+| 特性 | 说明 |
+|------|------|
+| 自动编排 | `consume` 创建或复用个人订阅，`stop` 取消订阅并清理本地状态 |
+| 共享连接 | 同一用户的多个 consumer 共享本地 bus 和云端长连接 |
+| 订阅隔离 | 正常 consumer 同时按事件类型和 `subscribe_id` 匹配 |
+| Agent 友好输出 | Stream 事件写入 stdout，连接状态和诊断信息写入 stderr |
+| 状态可观测 | `status` 同时显示服务端订阅、personal bus 和本地 consumers |
+| 跨平台 | macOS/Linux 使用 Unix Socket，Windows 使用 Named Pipe |
+
+Agent 工作流和事件参数详见 `skills/multi/dingtalk-event/SKILL.md`。
+
+</details>
+
 <details>
 <summary><strong>Raw API 调用</strong> — 直接调用钉钉 OpenAPI</summary>
 
@@ -476,7 +596,7 @@ dws aitable record query --base-id BASE_ID --tabel-id TABLE_ID       # --tabel-i
 ```bash
 # 内置 jq 表达式
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --jq '.invocation.params'
-dws schema --jq '.products[] | {id, tools: (.tools | length)}'
+dws schema "dev app create" --jq '.tool.required'
 
 # 只返回指定字段
 dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocation,response
@@ -485,13 +605,13 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --fields invocati
 </details>
 
 <details>
-<summary><strong>Schema 自省</strong> — 调用前查询任意工具的参数结构</summary>
+<summary><strong>Schema 自省</strong> — Agent 命令发现与执行契约</summary>
 
 ```bash
-dws schema                                              # 列出所有产品和工具
-dws schema aitable.query_records                        # 查看参数 Schema
-dws schema aitable.query_records --jq '.tool.required'   # 查看必填字段
-dws schema --jq '.products[].id'                        # 提取所有产品 ID
+dws schema aitable                                      # 发现产品命令
+dws schema "aitable record query"                       # 查看选中 leaf 契约
+dws schema "aitable record query" --jq '.tool.required' # 查看必填字段
+dws schema --all                                        # CI/审计/基线的全量导出
 ```
 
 </details>
@@ -538,7 +658,7 @@ dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <sec
 
 | 服务 | 命令 | 能力 |
 |------|------|------|
-| 通讯录 | `contact` | 按姓名 / 手机号 / 工号查人，部门、角色标签、花名册与离职 |
+| 通讯录 | `contact` | 按姓名 / 手机号 / 工号查人，部门、角色标签、花名册与离职；创建企业、企业账号及邀请员工 |
 | 群聊 | `chat`（`im`）| 发送 / 回复 / 搜索消息，群与成员管理，机器人与 Webhook 发消息，表情反应，撤回 |
 | 日历 | `calendar` | 日程 CRUD、参与者、会议室、闲忙与时间建议 |
 | 待办 | `todo` | 创建 / 列表 / 修改 / 完成待办及评论 |
@@ -619,7 +739,7 @@ dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <sec
 
 - [命令索引](./docs/command-index.md) — 全部运行时命令，带描述与使用场景
 - [参考手册](./docs/reference.md) — 环境变量、退出码、输出格式、Shell 补全
-- [架构设计](./docs/architecture.md) — 发现驱动管道、IR、Transport 层
+- [架构设计](./docs/architecture.md) — 静态端点管道、命令面、Transport 层
 - [开放平台应用指令设计](./docs/dev-yulan-command-routing.md) — yulan dev app 应用侧命令、MCP overlay、权限流程与 Agent 路由
 - [更新日志](./CHANGELOG.md) — 版本历史与迁移说明
 

build/homebrew-release.rb.tmpl

@@ -0,0 +1,63 @@
+class __CLASS_NAME__ < Formula
+  desc "__DESCRIPTION__"
+  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
+  version "__VERSION__"
+  license "Apache-2.0"
+__KEG_ONLY_LINE__
+
+  on_macos do
+    if Hardware::CPU.arm?
+      url "__DARWIN_ARM64_URL__"
+      sha256 "__DARWIN_ARM64_SHA256__"
+    else
+      url "__DARWIN_AMD64_URL__"
+      sha256 "__DARWIN_AMD64_SHA256__"
+    end
+  end
+
+  on_linux do
+    if Hardware::CPU.arm?
+      url "__LINUX_ARM64_URL__"
+      sha256 "__LINUX_ARM64_SHA256__"
+    else
+      url "__LINUX_AMD64_URL__"
+      sha256 "__LINUX_AMD64_SHA256__"
+    end
+  end
+
+  resource "skills" do
+    url "__SKILLS_URL__"
+    sha256 "__SKILLS_SHA256__"
+  end
+
+  def install
+    root = Dir["dws-*"].find { |entry| File.directory?(entry) } || "."
+    binary = File.join(root, "dws")
+    raise "binary not found: #{binary}" unless File.exist?(binary)
+
+    bin.install binary => "dws"
+
+    %w[LICENSE NOTICE README.md CHANGELOG.md].each do |name|
+      source = File.join(root, name)
+      pkgshare.install source if File.exist?(source)
+    end
+
+    skill_dest = pkgshare/"skills/dws"
+    skill_dest.mkpath
+    resource("skills").stage do
+      cp_r(Dir["*"], skill_dest)
+    end
+  end
+
+  def caveats
+    <<~EOS
+      Agent Skills are bundled in #{pkgshare}/skills/dws.
+      Run `dws skill setup` to install them into your Agent directories.
+__CHANNEL_CAVEAT__
+    EOS
+  end
+
+  test do
+    assert_match version.to_s, shell_output("#{bin}/dws version")
+  end
+end

build/homebrew.rb.tmpl

@@ -1,5 +1,5 @@
 class __CLASS_NAME__ < Formula
-  desc "DingTalk Workspace CLI"
+  desc "Install locally built DingTalk workspace CLI artifacts for verification"
   homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
   url "__ARCHIVE_URL__"
   sha256 "__ARCHIVE_SHA256__"
@@ -12,8 +12,6 @@ __KEG_ONLY_LINE__
   end
 
   def install
-    require "fileutils"
-
     root = Dir["dws-*"].find { |entry| File.directory?(entry) } || "."
     binary = File.join(root, "dws")
     raise "binary not found: #{binary}" unless File.exist?(binary)
@@ -28,44 +26,15 @@ __KEG_ONLY_LINE__
     skill_dest = pkgshare/"skills/dws"
     skill_dest.mkpath
     resource("skills").stage do
-      FileUtils.cp_r(Dir["*"], skill_dest)
+      cp_r(Dir["*"], skill_dest)
     end
   end
 
-  def post_install
-    require "fileutils"
-
-    skill_root = pkgshare/"skills/dws"
-    entries = Dir["#{skill_root}/*"]
-    return if entries.empty?
-
-    targets = [
-      Pathname.new(File.join(Dir.home, ".agents/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".claude/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".cursor/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".qoder/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".qoderwork/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".gemini/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".codex/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".github/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".windsurf/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".augment/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".cline/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".amp/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".kiro/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".trae/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".openclaw/skills/dws")),
-      Pathname.new(File.join(Dir.home, ".hermes/skills/dws")),
-    ]
-
-    targets.each_with_index do |dest, index|
-      parent_gate = dest.parent.parent
-      next if index > 0 && !parent_gate.directory?
-
-      FileUtils.rm_rf(dest)
-      FileUtils.mkdir_p(dest)
-      FileUtils.cp_r(entries, dest)
-    end
+  def caveats
+    <<~EOS
+      Agent Skills are bundled in #{pkgshare}/skills/dws.
+      Run `dws skill setup` to install them into your Agent directories.
+    EOS
   end
 
   test do

cmd/interface-snapshot/main.go

@@ -0,0 +1,195 @@
+// 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.
+
+// interface-snapshot is an internal CI helper. It is intentionally a separate
+// binary so it can be copied into a temporary worktree and compiled against an
+// older revision's real Cobra root.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/i18n"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/interfacesnapshot"
+)
+
+func main() {
+	os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
+}
+
+func run(args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 {
+		printUsage(stderr)
+		return 2
+	}
+
+	switch args[0] {
+	case "generate":
+		if err := runGenerate(args[1:], stdout, stderr); err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		return 0
+	case "compare":
+		compatible, err := runCompare(args[1:], stdout, stderr)
+		if err != nil {
+			fmt.Fprintln(stderr, err)
+			return 2
+		}
+		if !compatible {
+			return 1
+		}
+		return 0
+	default:
+		fmt.Fprintf(stderr, "unknown command %q\n", args[0])
+		printUsage(stderr)
+		return 2
+	}
+}
+
+func runGenerate(args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("generate", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	output := flags.String("output", "-", "snapshot output path, or - for stdout")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if flags.NArg() != 0 {
+		return fmt.Errorf("generate accepts no positional arguments")
+	}
+
+	home, err := os.MkdirTemp("", "dws-interface-snapshot-*")
+	if err != nil {
+		return fmt.Errorf("create isolated home: %w", err)
+	}
+	defer os.RemoveAll(home)
+
+	environment := map[string]string{
+		"DWS_CONFIG_DIR": home,
+		"DWS_LANG":       "en",
+		"HOME":           home,
+		"NO_COLOR":       "1",
+		"USERPROFILE":    home,
+	}
+	type previousEnv struct {
+		value string
+		set   bool
+	}
+	previous := make(map[string]previousEnv, len(environment))
+	for key, value := range environment {
+		oldValue, wasSet := os.LookupEnv(key)
+		previous[key] = previousEnv{value: oldValue, set: wasSet}
+		if err := os.Setenv(key, value); err != nil {
+			return fmt.Errorf("set %s: %w", key, err)
+		}
+	}
+	defer func() {
+		for key, old := range previous {
+			if old.set {
+				_ = os.Setenv(key, old.value)
+			} else {
+				_ = os.Unsetenv(key)
+			}
+		}
+	}()
+	previousLang := i18n.Lang()
+	defer i18n.SetLang(previousLang)
+	i18n.SetLang("en")
+
+	snapshot := interfacesnapshot.Capture(app.NewRootCommand())
+	if *output == "-" {
+		return interfacesnapshot.Write(stdout, snapshot)
+	}
+
+	file, err := os.Create(filepath.Clean(*output))
+	if err != nil {
+		return fmt.Errorf("create snapshot %q: %w", *output, err)
+	}
+	writeErr := interfacesnapshot.Write(file, snapshot)
+	closeErr := file.Close()
+	if writeErr != nil {
+		return fmt.Errorf("write snapshot %q: %w", *output, writeErr)
+	}
+	if closeErr != nil {
+		return fmt.Errorf("close snapshot %q: %w", *output, closeErr)
+	}
+	return nil
+}
+
+func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
+	flags := flag.NewFlagSet("compare", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	currentPath := flags.String("current", "", "candidate snapshot path")
+	basePath := flags.String("base", "", "target main/development baseline snapshot path")
+	stablePath := flags.String("stable", "", "latest stable GA snapshot path")
+	if err := flags.Parse(args); err != nil {
+		return false, err
+	}
+	if flags.NArg() != 0 {
+		return false, fmt.Errorf("compare accepts no positional arguments")
+	}
+	if *currentPath == "" {
+		return false, fmt.Errorf("compare requires --current")
+	}
+	if *basePath == "" && *stablePath == "" {
+		return false, fmt.Errorf("compare requires --base, --stable, or both")
+	}
+
+	current, err := readSnapshot(*currentPath)
+	if err != nil {
+		return false, fmt.Errorf("read current snapshot: %w", err)
+	}
+	references := make(map[string]interfacesnapshot.Snapshot, 2)
+	if *basePath != "" {
+		references["main"], err = readSnapshot(*basePath)
+		if err != nil {
+			return false, fmt.Errorf("read main/development baseline snapshot: %w", err)
+		}
+	}
+	if *stablePath != "" {
+		references["stable"], err = readSnapshot(*stablePath)
+		if err != nil {
+			return false, fmt.Errorf("read stable snapshot: %w", err)
+		}
+	}
+
+	report := interfacesnapshot.CompareAll(current, references)
+	encoder := json.NewEncoder(stdout)
+	encoder.SetEscapeHTML(false)
+	encoder.SetIndent("", "  ")
+	if err := encoder.Encode(report); err != nil {
+		return false, fmt.Errorf("write comparison report: %w", err)
+	}
+	return report.Compatible, nil
+}
+
+func readSnapshot(path string) (interfacesnapshot.Snapshot, error) {
+	file, err := os.Open(filepath.Clean(path))
+	if err != nil {
+		return interfacesnapshot.Snapshot{}, err
+	}
+	defer file.Close()
+	return interfacesnapshot.Read(file)
+}
+
+func printUsage(w io.Writer) {
+	fmt.Fprintln(w, "usage:")
+	fmt.Fprintln(w, "  interface-snapshot generate [--output FILE]")
+	fmt.Fprintln(w, "  interface-snapshot compare --current FILE [--base FILE] [--stable FILE]")
+}

cmd/interface-snapshot/main_test.go

@@ -0,0 +1,130 @@
+// 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 main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/interfacesnapshot"
+)
+
+func TestCrossPlatformCoverageRunGenerateCapturesActualRootOffline(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	if exitCode := run([]string{"generate"}, &stdout, &stderr); exitCode != 0 {
+		t.Fatalf("run(generate) exit=%d stderr=%s", exitCode, stderr.String())
+	}
+	snapshot, err := interfacesnapshot.Read(bytes.NewReader(stdout.Bytes()))
+	if err != nil {
+		t.Fatalf("decode generated snapshot: %v", err)
+	}
+
+	commands := make(map[string]interfacesnapshot.Command, len(snapshot.Commands))
+	for _, command := range snapshot.Commands {
+		commands[command.Path] = command
+	}
+	for _, path := range []string{"dws", "dws chat", "dws dev app create"} {
+		if _, ok := commands[path]; !ok {
+			t.Errorf("actual root snapshot is missing %q", path)
+		}
+	}
+	for _, path := range []string{"dws completion", "dws help"} {
+		if _, ok := commands[path]; ok {
+			t.Errorf("framework-noise path %q leaked into snapshot", path)
+		}
+	}
+
+	create := commands["dws dev app create"]
+	if !hasFlag(create.LocalFlags, "name", "string") {
+		t.Errorf("dev app create local flags do not contain --name string: %#v", create.LocalFlags)
+	}
+	if !hasFlag(create.InheritedFlags, "profile", "string") {
+		t.Errorf("dev app create inherited flags do not contain --profile string: %#v", create.InheritedFlags)
+	}
+}
+
+func TestCrossPlatformCoverageRunCompareUsesBothSnapshotInputsAndExitCode(t *testing.T) {
+	current := commandSnapshot("dws")
+	mergeBase := commandSnapshot("dws")
+	stable := commandSnapshot("dws", "dws legacy")
+
+	dir := t.TempDir()
+	currentPath := writeSnapshot(t, dir, "current.json", current)
+	mergeBasePath := writeSnapshot(t, dir, "base.json", mergeBase)
+	stablePath := writeSnapshot(t, dir, "stable.json", stable)
+
+	var stdout, stderr bytes.Buffer
+	exitCode := run([]string{
+		"compare",
+		"--current", currentPath,
+		"--base", mergeBasePath,
+		"--stable", stablePath,
+	}, &stdout, &stderr)
+	if exitCode != 1 {
+		t.Fatalf("run(compare) exit=%d, want 1; stdout=%s stderr=%s", exitCode, stdout.String(), stderr.String())
+	}
+	if !bytes.Contains(stdout.Bytes(), []byte(`"reference": "main"`)) ||
+		!bytes.Contains(stdout.Bytes(), []byte(`"reference": "stable"`)) ||
+		!bytes.Contains(stdout.Bytes(), []byte(`"kind": "command_removed"`)) {
+		t.Fatalf("comparison report does not contain both references and the blocking change:\n%s", stdout.String())
+	}
+}
+
+func commandSnapshot(paths ...string) interfacesnapshot.Snapshot {
+	commands := make([]interfacesnapshot.Command, 0, len(paths))
+	for _, path := range paths {
+		commands = append(commands, interfacesnapshot.Command{
+			Path:           path,
+			Aliases:        []string{},
+			LocalFlags:     []interfacesnapshot.Flag{},
+			InheritedFlags: []interfacesnapshot.Flag{},
+		})
+	}
+	return interfacesnapshot.Snapshot{
+		SchemaVersion: interfacesnapshot.SchemaVersion,
+		Rules: interfacesnapshot.Rules{
+			ExcludedCommandSubtrees: []string{},
+			ExcludedFlags:           []string{},
+		},
+		Commands: commands,
+	}
+}
+
+func writeSnapshot(t *testing.T, dir, name string, snapshot interfacesnapshot.Snapshot) string {
+	t.Helper()
+	path := filepath.Join(dir, name)
+	file, err := os.Create(path)
+	if err != nil {
+		t.Fatalf("create %s: %v", path, err)
+	}
+	if err := interfacesnapshot.Write(file, snapshot); err != nil {
+		file.Close()
+		t.Fatalf("write %s: %v", path, err)
+	}
+	if err := file.Close(); err != nil {
+		t.Fatalf("close %s: %v", path, err)
+	}
+	return path
+}
+
+func hasFlag(flags []interfacesnapshot.Flag, name, flagType string) bool {
+	for _, flag := range flags {
+		if flag.Name == name && flag.Type == flagType {
+			return true
+		}
+	}
+	return false
+}

cmd/main.go

@@ -19,6 +19,8 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/app"
 )
 
+var exit = os.Exit
+
 func main() {
-	os.Exit(app.Execute())
+	exit(app.Execute())
 }

cmd/main_test.go

@@ -0,0 +1,27 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func TestCrossPlatformCoverageMainExitsWithSuccessfulVersionCommand(t *testing.T) {
+	previousExit := exit
+	previousArgs := os.Args
+	t.Cleanup(func() {
+		exit = previousExit
+		os.Args = previousArgs
+	})
+
+	called := false
+	code := -1
+	exit = func(value int) {
+		called = true
+		code = value
+	}
+	os.Args = []string{"dws", "version"}
+	main()
+	if !called || code != 0 {
+		t.Fatalf("main exit = called %v, code %d", called, code)
+	}
+}

docs/architecture.md

@@ -1,22 +1,26 @@
 # Architecture
 
-`dws` is a Go CLI that turns DingTalk MCP metadata into a command-line surface for both humans and AI agents.
+`dws` is a Go CLI with a versioned, static command surface for DingTalk MCP capabilities. Cobra help serves humans; the embedded Command Catalog serves AI agents.
 
 ## High-Level Flow
 
 1. `cmd` is the CLI entrypoint, invoking `internal/app` to build the root Cobra command tree.
-2. `internal/app` wires static utility commands (`auth`, `audit`, `schema`, `completion`) and dynamically loads product commands via `internal/plugin`.
+2. `internal/app` wires static utility commands (`auth`, `audit`, `schema`, `completion`), product helpers, and versioned plugin descriptors.
 3. `internal/helpers` contains the main command handlers for all product surfaces (`dev`, `chat`, `calendar`, `contact`, `aitable`, etc.).
 4. `internal/executor` and `internal/transport` execute MCP JSON-RPC calls; `internal/output` formats responses.
 5. `internal/auth` manages login state, PAT tokens, and agent-code detection.
+6. Schema generation starts from the reviewed `CommandRegistry`, binds each identity to the exact current Cobra leaf, and then resolves typed constraints, sanitized MCP snapshots, Agent hints, and Skills into one `SchemaRegistry`. Startup and Schema queries do not call MCP `tools/list`.
+7. The embedded Catalog is a downstream release artifact and never backfills identity or participates in regeneration. Stable flag-to-interface property bindings come from the reviewed, content-addressed v3 manifest in `schema_parameter_bindings.json`; its exact active tuples, corrections, removals, and mapping exclusions are validated against the final bound `SchemaRegistry`. CLI `required` and constraints come from the resolved typed contract, while MCP `required` remains interface-only metadata.
+8. Agent selection results are fixed in versioned review inputs. Every public tool has explicit use/avoid/example and interface disposition metadata; Skill references that are not current leaves require an explicit alias/group/stale/out-of-surface review instead of fuzzy runtime matching.
 
 ## Repository Structure
 
 - `cmd`: CLI entrypoint
 - `internal/app`: root command wiring, static utility commands, and plugin loading
 - `internal/helpers`: product command handlers (dev, chat, calendar, contact, etc.)
-- `internal/plugin`: plugin-based dynamic command loader
-- `internal/cli`: catalog types and endpoint loader (static endpoint mode)
+- `internal/plugin`: versioned plugin manifest, hook, skill, and transport descriptor loading
+- `internal/cli`: embedded Agent Command Catalog, static schema query, and catalog contracts
+- `internal/generator`: deterministic Agent metadata and Command Catalog generators
 - `internal/executor`: invocation dispatch and result handling
 - `internal/transport`: MCP HTTP client and request signing
 - `internal/auth`: login, token management, agent-code detection, identity
@@ -35,7 +39,42 @@
 - `pkg/config`: configuration constants and paths
 - `pkg/edition`: edition detection (oss vs enterprise)
 - `pkg/mcptypes`: MCP protocol type definitions
+- `internal/syncdata`: generated static endpoint and command-routing data synced from the Wukong baseline
 - `skills/`: bundled agent skills (mono/ and multi/ layouts)
 - `test/`: CLI, integration, contract, unit, and skill E2E tests
 - `scripts/`: install scripts, policy checks, and CI helpers
-- `envelope/`: pre-built discovery payloads for offline use
+
+## Quality Pipeline
+
+Quality enforcement is layered so a pull request receives fast, deterministic
+admission feedback without pretending that downstream integration has already
+run.
+
+```mermaid
+flowchart TB
+  PR["Pull request"] --> CA["CI"]
+  subgraph CA_CHECKS["Nine required contexts"]
+    L["Lint"]
+    T["Test"]
+    C["Coverage"]
+    P["Policy"]
+    E["Edition"]
+    I["Interface Integrity"]
+    A["AI Behavior"]
+    S["CLI Smoke"]
+    M["Mock MCP"]
+  end
+  CA --> CA_CHECKS
+  CA_CHECKS --> MAIN["Protected main"]
+  MAIN --> MP["Main Integration — 主干集成<br/>Multi-profile E2E"]
+  MAIN --> PLATFORM["Risk-selected / release native platform validation"]
+  MP --> RELEASE["Release delivery"]
+  PLATFORM --> RELEASE
+```
+
+Complete Multi-profile E2E and the ordinary full native-platform matrix are
+downstream of PR admission. PRs still run primary-environment assurance and
+fast cross-platform compilation; auth, keychain, OS-specific, installer, and
+release changes additionally select native platform tests before merge. See
+[`docs/ci-pr-gates.md`](ci-pr-gates.md) for the exact context and ruleset
+contract.

docs/audit-log.md

@@ -1,227 +0,0 @@
-# 审计日志（Audit Log）
-
-DWS 自动记录每次 MCP HTTP 调用的审计事件，用于合规追溯和安全审查。默认启用，无需额外配置。
-
-## 功能特性
-
-- **自动记录**：每次命令执行产生一条 JSONL 审计事件
-- **按天轮转**：日志文件按日期分割（`audit-YYYYMMDD.jsonl`），默认留存 90 天
-- **防篡改**：L1 哈希链（sha256），每条事件链接前一条的 hash，可验证完整性
-- **远端转发**：支持 POST 到外部 SIEM 或审计平台
-- **三级脱敏**：转发时可按 none/hashed/minimal 脱敏敏感字段
-- **CLI 命令**：内置 `dws audit tail/export/verify` 查看和验证
-
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `DWS_AUDIT` | 启用 | 设 `0`/`false`/`off` 关闭审计 |
-| `DWS_AUDIT_DIR` | `~/.dws/audit` | 审计日志目录 |
-| `DWS_AUDIT_RETENTION_DAYS` | `90` | 日志留存天数 |
-| `DWS_AUDIT_FORWARD_URL` | （空） | 远端转发 URL（POST JSON） |
-| `DWS_AUDIT_FORWARD_TOKEN` | （空） | 远端转发 Bearer Token |
-| `DWS_AUDIT_FORWARD_REDACT` | `none` | 转发脱敏级别：`none`/`hashed`/`minimal` |
-
-## 审计事件格式
-
-每条事件是一行 JSON，字段如下：
-
-```json
-{
-  "ts": "2026-07-06T10:59:06+08:00",
-  "execution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
-  "agent_id": "agent-xxx",
-  "actor": {
-    "user_id": "525018",
-    "name": "胡奕舟",
-    "corp_id": "ding8196cd9a2b2405da24f2f5cc6abecb85",
-    "corp_name": "钉钉"
-  },
-  "product": "calendar",
-  "command": "list_events",
-  "endpoint": "https://api.dingtalk.com/v1.0/calendar/users/xxx/calendars/primary/events",
-  "params_summary": "maxResults=20",
-  "result": "success",
-  "error_category": "",
-  "error_reason": "",
-  "duration_ms": 234,
-  "cli_version": "1.0.47",
-  "os": "darwin",
-  "arch": "arm64",
-  "prev_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
-}
-```
-
-**字段说明**：
-
-- `ts`：事件时间戳（RFC3339）
-- `execution_id`：本次命令执行的唯一 ID
-- `agent_id`：Agent 标识（若有）
-- `actor`：执行者信息（从登录态获取）
-- `product`：调用的产品（如 `calendar`、`chat`、`contact`）
-- `command`：调用的命令（如 `list_events`、`send_message`）
-- `endpoint`：实际请求的 API 端点（已脱敏）
-- `params_summary`：参数摘要（已脱敏）
-- `result`：`success` 或 `error`
-- `error_category` / `error_reason`：错误分类和原因（成功时为空）
-- `duration_ms`：命令执行耗时（毫秒）
-- `prev_hash` / `hash`：哈希链字段，用于防篡改验证
-
-## CLI 命令
-
-### 查看最近日志
-
-```bash
-# 查看最近 20 条审计事件（默认）
-dws audit tail
-
-# 查看最近 50 条
-dws audit tail -n 50
-```
-
-输出示例：
-
-```
-2026-07-06 10:59:06  calendar list_events  user=525018  result=success  234ms
-2026-07-06 10:58:42  chat send_message     user=525018  result=success  156ms
-2026-07-06 10:57:15  contact search        user=525018  result=success   89ms
-```
-
-### 导出日志
-
-```bash
-# 导出最近 7 天的 JSONL
-dws audit export --since 2026-06-29 --until 2026-07-06 --format jsonl > audit-7d.jsonl
-
-# 导出为 CSV（方便 Excel 打开）
-dws audit export --since 2026-07-01 --format csv > audit-july.csv
-```
-
-### 验证哈希链
-
-```bash
-# 验证当前最新日志文件的哈希链完整性
-dws audit verify
-
-# 验证指定文件
-dws audit verify --file ~/.dws/audit/audit-20260706.jsonl
-```
-
-输出：
-
-```
-✓ 哈希链完整：234 条事件全部校验通过
-```
-
-或：
-
-```
-✗ 哈希链断裂：第 156 条事件的 hash 不匹配
-```
-
-## 哈希链防篡改
-
-每条事件的 `hash` 字段由以下公式计算：
-
-```
-hash = sha256(prev_hash + event_json_without_hash_fields)
-```
-
-- 首条事件的 `prev_hash` 为空字符串
-- 后续事件的 `prev_hash` = 前一条的 `hash`
-- 任何对历史事件的篡改都会导致后续所有 hash 失效
-
-**验证流程**：
-
-1. 读取日志文件，逐行解析
-2. 对每条事件，移除 `prev_hash` 和 `hash` 字段，重新序列化
-3. 用前一条的 hash + 当前事件 JSON 计算新 hash
-4. 对比计算结果与文件中记录的 hash
-5. 全部匹配 = 完整；某条不匹配 = 被篡改
-
-## 远端转发
-
-设置 `DWS_AUDIT_FORWARD_URL` 后，每条审计事件会异步 POST 到指定端点：
-
-```bash
-export DWS_AUDIT_FORWARD_URL=https://siem.example.com/ingest/audit
-export DWS_AUDIT_FORWARD_TOKEN=your-bearer-token  # 可选
-```
-
-**请求格式**：
-
-```http
-POST /ingest/audit HTTP/1.1
-Host: siem.example.com
-Authorization: Bearer your-bearer-token
-Content-Type: application/json
-
-{"ts":"2026-07-06T10:59:06+08:00","product":"calendar",...}
-```
-
-**超时与重试**：3 秒超时，失败不阻塞命令执行（best-effort），不自动重试。
-
-## 脱敏分级
-
-转发时可通过 `DWS_AUDIT_FORWARD_REDACT` 控制脱敏级别：
-
-| 级别 | 行为 | 适用场景 |
-|------|------|----------|
-| `none`（默认） | 原样转发，不脱敏 | 内部审计平台 |
-| `hashed` | actor.name 哈希化，params_summary 脱敏 | 跨部门共享 |
-| `minimal` | 仅保留 ts/product/command/result/duration_ms，移除 actor/endpoint/params | 对外合规报告 |
-
-**示例**：
-
-```bash
-# 最小化脱敏（仅保留元数据）
-export DWS_AUDIT_FORWARD_REDACT=minimal
-export DWS_AUDIT_FORWARD_URL=https://compliance.example.com/audit
-```
-
-## 常见问题
-
-### Q: 审计日志占多少磁盘？
-
-典型场景（每天 100 条命令）约 50KB/天，90 天约 4.5MB。日志文件是 JSONL 纯文本，gzip 压缩后约 1/5。
-
-### Q: 关闭审计会影响性能吗？
-
-设置 `DWS_AUDIT=0` 后，审计模块不初始化，零开销。默认启用时，每条事件写入耗时 <1ms（异步磁盘 IO）。
-
-### Q: 哈希链断了怎么办？
-
-可能原因：
-1. 手动编辑过日志文件
-2. 磁盘损坏
-3. 并发写入导致顺序错乱（罕见）
-
-**处理**：
-- 备份当前日志
-- 用 `dws audit verify` 定位断裂位置
-- 从断裂点之后的事件可继续验证（前缀已不可信）
-
-### Q: 如何清理旧日志？
-
-自动清理：`DWS_AUDIT_RETENTION_DAYS=90`（默认），超过 90 天的文件在下次启动时 best-effort 删除。
-
-手动清理：
-
-```bash
-# 删除 2026 年 6 月之前的日志
-rm ~/.dws/audit/audit-202605*.jsonl
-```
-
-## 技术实现
-
-- **核心包**：`internal/audit`
-- **集成点**：`internal/app/runner.go` 的 `executeInvocation` 方法（defer 调用 `emitAudit`）
-- **身份获取**：从 `auth.LoadTokenData` 读取当前登录用户
-- **参数脱敏**：调用 `logging.SanitizeArguments`（与现有日志脱敏逻辑一致）
-
-## 相关文档
-
-- [环境变量参考](./reference.md)
-- [架构概览](./architecture.md)
-- [自动化与脚本](./automation.md)

docs/automation.md

@@ -62,6 +62,68 @@ make lint
 git diff --check
 ```
 
+## Homebrew Formula PR Automation
+
+Official tag releases require the repository Actions secret
+`HOMEBREW_PR_TOKEN`. Prefer a fine-grained personal access token owned by a
+maintainer or release-bot account, limited to this repository with
+`Contents: write` and `Pull requests: write`. If organization policy prevents
+that account from targeting the repository, use a dedicated classic token with
+only the `public_repo` scope. Do not reuse a broad developer token.
+
+Store the dedicated token as the `HOMEBREW_PR_TOKEN` repository Actions secret
+and rotate it before its configured expiration. Replace it immediately if it is
+exposed, its owner loses repository access, or the release-bot ownership
+changes. The Release workflow uses this
+dedicated token only to push an `automation/homebrew-*` branch and open the
+stable or beta Formula PR. It does not push Formula changes directly to `main`.
+The default-branch governance preflight and every tag contract authenticate the
+token before publication, reject over-scoped classic tokens, confirm its
+identity, and run a controlled write canary. The canary pushes a unique
+`automation/homebrew-token-canary-*` branch with a `[skip ci]` commit, creates a
+draft PR, closes it, and deletes the branch with the same token. This proves both
+Contents and Pull requests write access before publication without merging
+anything. The gate also rejects reuse of `RELEASE_GOVERNANCE_TOKEN`.
+No maintainer environment variable is required when creating a tag. Using the
+built-in `GITHUB_TOKEN` is insufficient because organization policy prevents
+Actions from creating pull requests, and its generated PR events may require
+separate workflow approval.
+
+## Release Governance and Recovery
+
+Store `RELEASE_GOVERNANCE_TOKEN` as a dedicated Actions secret with only
+repository `Administration: read`. The immutable-releases REST endpoint is an
+administration setting and cannot be read by the workflow's built-in
+`GITHUB_TOKEN`. Both the default-branch governance preflight and the tag
+contract use this same credential so a missing or expired identity is detected
+before an irreversible tag is created.
+
+Create a protected `release-recovery` environment limited to protected
+branches, with a required reviewer, self-review disabled, and administrator
+bypass disabled. The workflow reads the environment through the GitHub API and
+fails closed unless the required-reviewer, prevent-self-review, and protected-
+branch rules are present.
+Recovery is restricted to an existing annotated tag whose exact tag object,
+commit, and failed tag-push run all match; it then reuses the normal release
+jobs. Do not put publication secrets in temporary branches or create ad-hoc
+recovery workflows.
+
+If the immutable GitHub Release and npm package were delivered but a downstream
+China mirror failed, dispatch the normal `Release` workflow from the protected
+default branch with exactly one of `repair_gitee_version` or
+`repair_oss_version`. Channel repair accepts a failed exact-tag run only when
+its latest attempt completed the release contract, build, Apple signature,
+immutable GitHub publication, and npm delivery checks for the exact tagged
+commit. It then downloads and re-verifies the immutable assets before invoking
+only the selected mirror. An OSS repair requires the OSS step itself to be the
+recorded failure. A Gitee repair accepts either a failed Gitee job or a Gitee
+job that was skipped behind that OSS failure; the latter is an explicit Gitee
+backfill and does not claim that OSS has been repaired. Gitee repair requires
+`GITEE_TOKEN`, `GITEE_USER`, and `GITEE_REPO`; OSS repair requires
+`OSS_ACCESS_KEY_ID`, `OSS_ACCESS_KEY_SECRET`, `OSS_ENDPOINT`, and `OSS_BUCKET`
+(with optional `OSS_PREFIX`) as Actions secrets. Missing credentials fail the
+selected repair closed.
+
 ## Handoff Checklist
 
 Before handoff, include:

docs/ci-pr-gates.md

@@ -0,0 +1,158 @@
+# CI — PR 合入门禁
+
+The pull-request admission layer has exactly nine required external contexts:
+
+| Required context | Contract |
+|---|---|
+| `Lint` | Stable PR revision classification, formatting, `go vet`, and Actionlint |
+| `Test` | Race/unit/release-script tests plus fast cross-platform compilation |
+| `Coverage` | Overall non-regression and 100% changed-code coverage |
+| `Policy` | Repository policy and the fail-closed CHANGELOG contract |
+| `Edition` | Edition contract tests |
+| `Interface Integrity` | CLI, Schema, Skill, and stable-release compatibility |
+| `AI Behavior` | Base-owned policy for PRs labeled `ai-generated` |
+| `CLI Smoke` | Offline help for every public top-level command |
+| `Mock MCP` | HTTP and stdio MCP lifecycle smoke tests |
+
+The workflow display name is `CI`. Parallel helper
+jobs may implement `Test` and `Coverage`, but they are not ruleset contexts.
+Do not require an aggregate alias or a downstream integration check in place of
+the nine contracts above.
+
+`AI Behavior` is evaluated by a `pull_request_target` workflow that never
+checks out or executes PR code. It writes the exact `AI Behavior` status to the
+current PR head. Its Files API read is bracketed by base/head revision checks,
+so a synchronize race fails closed. The same workflow supplies a successful
+`AI Behavior` check run on protected `main` pushes for release governance.
+
+## Exact CHANGELOG-only fast path
+
+A pull request qualifies only when GitHub reports exactly one changed file,
+that file is an in-place modification of `CHANGELOG.md`, and the base and head
+both retain it as a regular non-executable `100644` blob. Add, delete, rename,
+symlink, executable-mode, and second-file changes do not qualify.
+
+`Lint` classifies the Files API result only after verifying that the API's base
+and head equal the event revision both before and after pagination. `Policy`
+checks out GitHub's PR merge ref and verifies its parents:
+
+```text
+HEAD^1 = pull_request.base.sha
+HEAD^2 = pull_request.head.sha
+```
+
+It then runs:
+
+```sh
+./scripts/policy/check-changelog-pr.sh \
+  --fast-path "$PR_BASE_SHA" HEAD
+```
+
+Because the verified PR diff contains only `CHANGELOG.md`, the validator and
+its policy dependencies in that merge tree are byte-for-byte the current base
+versions. Validation targets the synthetic merge tree, not the feature-branch
+tree, so a stale branch cannot supply an older validator or combine with newer
+base notes into an invalid final CHANGELOG.
+
+All nine admission contexts are still emitted and must succeed. Expensive
+implementation helpers are skipped; the named contexts record that their code
+surface is unaffected. After merge, the protected `main` push executes the
+full admission suite.
+
+Any PR that touches `CHANGELOG.md` but also changes another file runs the same
+content contract in `Policy` with `--content-only`. That mode permits the
+second file but still rejects invalid dates or versions, missing bullets,
+placeholder `TODO`/`TBD`, unmanaged-section changes, and unsafe tree modes.
+Adding a second file therefore cannot bypass CHANGELOG validation.
+
+## Platform and downstream boundaries
+
+Ordinary PRs run the primary Linux assurance plus fast Darwin/Windows compile
+checks. Full native macOS/Windows tests and platform coverage run on a PR only
+when its diff touches auth, keychain, OS-specific Go files, installers,
+packaging, Formulae, or release automation. Protected `main` pushes run the
+complete native matrix.
+
+Complete `Multi-profile E2E` is not a PR admission context. It belongs to the
+`Main Integration — 主干集成` workflow and runs only after a push to `main` (or
+an explicit manual dispatch). A failing downstream run remains a real
+regression and must be repaired, but it must not be represented by a synthetic
+successful PR check.
+
+```mermaid
+flowchart TB
+  PR["Pull request"] --> ADMISSION["CI"]
+  ADMISSION --> L["Lint"]
+  ADMISSION --> T["Test"]
+  ADMISSION --> C["Coverage"]
+  ADMISSION --> P["Policy"]
+  ADMISSION --> E["Edition"]
+  ADMISSION --> I["Interface Integrity"]
+  ADMISSION --> A["AI Behavior"]
+  ADMISSION --> S["CLI Smoke"]
+  ADMISSION --> M["Mock MCP"]
+  ADMISSION --> MAIN["Protected main"]
+  MAIN --> NATIVE["Full native platform matrix"]
+  MAIN --> E2E["Multi-profile E2E"]
+  MAIN --> RELEASE["Release delivery"]
+```
+
+## Running focused gates locally
+
+Run the contracts relevant to the change:
+
+```sh
+make build
+make policy
+make interface-integrity
+make authoritative-interface-integrity BASE_REF=<merge-base>
+make schema-compatibility BASE_REF=<merge-base>
+make skill-command-integrity
+make cli-smoke
+make mock-mcp-smoke
+go test -v -count=1 ./pkg/editiontest/...
+```
+
+For an exact CHANGELOG-only branch:
+
+```sh
+base_ref=$(git merge-base HEAD origin/main)
+./scripts/policy/check-changelog-pr.sh --fast-path "$base_ref" HEAD
+```
+
+`make coverage-gate` is an enforcement step, not a profile generator. CI
+generates the candidate, supporting, merge-base, and (when risk-selected)
+native profiles before the aggregate `Coverage` context evaluates them. The
+aggregate and native gates require 100% coverage for changed executable Go
+statements. Overall coverage remains an unrounded, zero-tolerance merge-base
+non-regression check. Candidate and baseline profiles are evaluated by the
+same block-deduplicating checker; supporting policy and shortcut profiles
+contribute to changed-code coverage only. The checked-in badge is presentation
+only and is never read as a gate input.
+
+Compatibility checks derive authoritative Interface snapshots from the PR
+merge-base and the latest reachable stable release. The candidate cannot bless
+a breaking change by editing a fixture. Schema additions are allowed;
+historical products, tools, parameters, mappings, positional execution fields,
+constraints, and safety semantics remain protected.
+
+## Required GitHub repository settings
+
+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:
+
+- `Lint`
+- `Test`
+- `Coverage`
+- `Policy`
+- `Edition`
+- `Interface Integrity`
+- `AI Behavior`
+- `CLI Smoke`
+- `Mock MCP`
+
+Do not require helper jobs, `Multi-profile E2E`, or an aggregate admission
+alias. Update ruleset contexts only after the new names have appeared on the
+protected branch, so a rename cannot silently remove enforcement or leave an
+unproducible required context.

docs/command-index.md

@@ -147,8 +147,8 @@ _Group chats, conversations, messages, and robot/webhook integrations._
 | `dws chat group members remove` | Remove one or more members from a group chat. | When the agent kicks users who should no longer have access to the group. |
 | `dws chat group rename` | Update the display name of a group chat. | When the agent is rebranding or clarifying the purpose of an existing group. |
 | `dws chat list-top-conversations` | Fetch the list of conversations the current user has pinned to the top of their chat list. | When the agent needs to prioritize the user's most important conversations in a summary or dashboard. |
-| `dws chat message list` | Pull the recent message history of a specific conversation (v2), paginated. | When the agent needs to read what has recently been said in a conversation to summarize or reason about it. |
-| `dws chat message list-all` | Search all messages across the current user's conversations within a time range. | When the agent needs to audit or summarize everything the user saw across chats in a window. |
+| `dws chat message list` | Pull the recent message history of a specific conversation, including quoted-message context for merged forwards and images. | When the agent needs to read what has recently been said in a conversation and retain the context of replies. |
+| `dws chat message list-all` | Search all messages across the current user's conversations within a time range, surfacing any search-entitlement guidance. | When the agent needs to audit or summarize everything the user saw across chats in a window. |
 | `dws chat message list-by-sender` | Fetch messages authored by a specific sender across both single and group chats. | When the agent needs to pull everything a particular colleague said recently. |
 | `dws chat message list-focused` | Fetch messages from users the current user has marked as "special focus" (starred contacts). | When the agent builds a priority-inbox view highlighting messages from important people. |
 | `dws chat message list-mentions` | Fetch messages where the current user was @-mentioned. | When the agent wants to surface items that explicitly require the user's attention. |
@@ -164,16 +164,19 @@ _Group chats, conversations, messages, and robot/webhook integrations._
 
 ## `dws contact` — Contact Directory
 
-_Users, departments, and directory lookups._
+_Users, departments, directory lookups, and enterprise onboarding._
 
-**6 commands**
+**9 commands**
 
 | Command | Description | When to use |
 |---|---|---|
+| `dws contact account create` | Create a dedicated login account in the current enterprise. | When the user explicitly asks for an enterprise account or login account, rather than a new enterprise organization. |
 | `dws contact dept list-members` | List members of a specific department by department ID. | When the agent needs the roster of a department to target communication or build a team overview. |
 | `dws contact dept search` | Search departments in the organization's contact directory by keyword. | When the agent needs to resolve a department name to a department ID. |
+| `dws contact org create` | Create a new DingTalk enterprise organization. | When the user explicitly asks to create or initialize an enterprise and provides its name and creator display name. |
 | `dws contact user get` | Batch-fetch detailed profile information for one or more users by user ID. | When the agent needs names, titles, emails, or departments for a known set of user IDs. |
 | `dws contact user get-self` | Retrieve the profile of the currently authenticated user. | When the agent needs to identify who it is acting on behalf of (user ID, name, org). |
+| `dws contact user invite` | Invite one employee by mobile number into the current enterprise. | When the user explicitly asks to add an employee and has supplied the employee name and mobile number. |
 | `dws contact user search` | Search users in the contact directory by keyword (name, title, etc.). | When the agent needs to resolve a person's display name to a user ID. |
 | `dws contact user search-mobile` | Look up a user by mobile phone number. | When the agent has only a phone number and needs to find the corresponding DingTalk user. |
 

docs/event-subprocess-contract.md

@@ -0,0 +1,112 @@
+# Event consume — AI subprocess contract
+
+Defines the stable `dws event consume` subprocess contract so an
+orchestrator can determine when the consumer is ready, stop it cleanly,
+and machine-read why it exited.
+
+Scope of this branch: the four **contract** items below. Reconnect
+resilience (keeping the stream alive across a transient upstream drop) is
+tracked separately and intentionally out of scope here.
+
+## Baseline (already present, no work)
+
+- `--max-events N` — stop after N events (exit 0).
+- `--duration D` — wall-clock budget (exit 0). Kept as `--duration`, NOT
+  aliased to `--timeout`: the global `--timeout` is the HTTP request
+  timeout (int seconds) and would collide (different type and meaning).
+- Bus idle-shutdown fires only with **zero** consumers, so a connected
+  consumer is never idle-killed.
+- SIGINT/SIGTERM already cancel the run context and return cleanly.
+
+## Improvements
+
+### 1. Ready marker (standardized)
+
+On connect, emit a fixed stderr line **before** any stdout event:
+
+```
+[event] ready event_key=<key> bus_pid=<pid> subscribe_id=<id>
+```
+
+Parents block on stderr until this line, then read stdout. Suppressed
+under `--quiet`. Replaces the ad-hoc `connected bus pid=...` line (which
+omits `event_key`).
+
+**Verification**
+- T1a: stderr contains a line matching `^\[event\] ready event_key=<key>`.
+- T1b: that line appears before the first stdout event (ordering).
+- T1c: with `--quiet`, the line is absent.
+
+### 2. stdin EOF = graceful exit
+
+`consume` watches stdin; closing stdin is a shutdown signal (wired for AI
+subprocess callers). To stay resident, feed a never-EOF stdin
+(`< <(tail -f /dev/null)`) or run bounded (`--max-events` / `--duration`).
+
+**Verification**
+- T2a: `printf '' | dws event consume <key>` exits ≤2s, code 0, final
+  line `reason: signal` (stdin-eof classified as signal).
+- T2b: `dws event consume <key> < <(tail -f /dev/null)` still alive after
+  5s, connection intact.
+- T2c (unit): a controllable stdin reader hitting EOF makes Run return nil
+  via the cleanup path.
+
+### 3. Exit reason contract + exit codes
+
+On exit, final stderr line:
+
+```
+[event] exited — received N event(s) in Xs (reason: <limit|timeout|signal|bus_shutdown>)
+```
+
+Exit codes: controlled exit (limit/timeout/signal/stdin-eof) = 0; startup
+or runtime failure (permissions, network, params) = non-zero, with no
+`exited` line and an `Error:` line instead.
+
+**Verification**
+- T3a: `--max-events 1` + 1 event → exit 0, reason=`limit`, N=1.
+- T3b: `--duration 2s`, no events → exit 0, reason=`timeout`.
+- T3c: SIGTERM mid-run → exit 0, reason=`signal`.
+- T3d: bad params / permission failure → exit≠0, no `exited` line, has `Error:`.
+- Unit tests assert (reason string, exit code) for each path.
+
+### 4. Cleanup on exit (no `kill -9`)
+
+Ownership-based cleanup:
+- If this run **created** the subscription (no `--subscribe-id`), a clean
+  exit (SIGTERM / SIGINT / stdin-EOF / limit / timeout) **unsubscribes**
+  it server-side and sends Bye.
+- If `--subscribe-id` was passed (reusing an existing subscription), the
+  subscription is **left intact** — the caller owns its lifecycle.
+- `--ephemeral` remains as an explicit "always unsubscribe" override.
+- Help/docs warn: avoid `kill -9` (skips the unsubscribe → leaked
+  server-side subscription: "subscription already exists" on restart,
+  duplicate delivery). Prefer SIGTERM or closing stdin.
+
+**Verification**
+- T4a: start consume (self-created subscription), record subscribe_id;
+  SIGTERM; afterwards `dws event status` no longer lists that subscribe_id
+  and the server-side subscription is gone.
+- T4b: start consume with `--subscribe-id <existing>`; SIGTERM; the
+  subscription is still present (reuse case preserved).
+- T4c (control): `kill -9` leaves subscribe_id lingering (documented risk;
+  we only guarantee SIGTERM is clean, we do not fix kill -9 itself).
+
+## Out of scope (next branch)
+
+**Reconnect resilience** — today `personal source` retries only
+`retryable` errors (1–30s backoff); a non-retryable error tears the bus
+down and takes consume with it (the likely cause of the observed silent
+drop). Making more drops retryable, keeping the bus alive across a
+reconnect, and emitting `reason: source_lost` only after exhausting the
+budget — tracked on its own branch, since it needs error-classification
+judgement and real flaky-network testing, and would otherwise couple clean
+contract work with resilience work.
+
+## Test surface
+
+- Unit: extend `internal/event/consume/*_test.go` with fake bus conn /
+  stdin / stderr sink for T1c, T2c, T3 (all paths), T4 ownership branch.
+- Integration/e2e: `--foreground` + mock source (or a short real run) for
+  T1a/b, T2a/b, T3a–d, T4a/b/c — assert the stderr contract lines and exit
+  codes.

docs/reference.md

@@ -5,7 +5,7 @@
 | Variable | Purpose / 用途 |
 |---------|---------|
 | `DWS_CONFIG_DIR` | Override default config directory / 覆盖默认配置目录 |
-| `DWS_SERVERS_URL` | Point discovery at a custom server registry endpoint / 将服务发现指向自定义端点 |
+| `DWS_<PRODUCT>_MCP_URL` | Override a product MCP endpoint for local development / 本地开发时覆盖指定产品 MCP endpoint |
 | `DWS_CLIENT_ID` | OAuth client ID (DingTalk AppKey) |
 | `DWS_CLIENT_SECRET` | OAuth client secret (DingTalk AppSecret) |
 | `DWS_TRUSTED_DOMAINS` | Comma-separated trusted domains for bearer token (default: `*.dingtalk.com`). `*` for dev only / Bearer token 允许发送的域名白名单，默认 `*.dingtalk.com`，仅开发环境可设为 `*` |
@@ -22,7 +22,7 @@
 | 3 | Validation | Invalid input, flags, or parameter schema mismatch / 输入参数校验失败 |
 | 4 | PAT | PAT authorization interception; stderr carries raw machine-readable PAT JSON / PAT 授权拦截；stderr 返回原始机器可解析 JSON |
 | 5 | Internal | Unexpected internal error / 未预期的内部错误 |
-| 6 | Discovery | Server discovery, cache, or protocol negotiation failure / 服务发现、缓存或协议协商失败 |
+| 6 | Discovery | Static endpoint resolution or protocol negotiation failure / 静态端点解析或协议协商失败 |
 
 With `-f json`, error responses include structured payloads: `category`, `reason`, `hint`, `actions`.
 
@@ -34,7 +34,7 @@ With `-f json`, error responses include structured payloads: `category`, `reason
 dws contact user search --query "Alice" -f table   # Table (default, human-friendly / 表格，默认)
 dws contact user search --query "Alice" -f json    # JSON (for agents and piping / 适合 agent)
 dws contact user search --query "Alice" -f raw     # Raw API response / 原始响应
-dws schema -f pretty ding.send_ding_message          # Pretty (ANSI-colored, schema-aware / 彩色分区，专为 schema 设计)
+dws schema -f pretty "calendar event create"         # Pretty Agent schema view / Agent Schema 彩色查看
 ```
 
 ## Dry Run / 试运行
@@ -51,44 +51,59 @@ dws contact user search --query "Alice" -o result.json
 
 ## Schema Introspection / Schema 查询
 
-`dws schema` 查询已发现的 MCP 产品和工具元数据。不带参数列出所有产品，带路径输出单个工具的完整 schema。
+`--help` 展示当前二进制的 Cobra 命令和可接受 flag，`dws schema` 查询同版本内嵌的 Agent 命令契约。Schema 查询不访问 MCP endpoint、不执行 `tools/list`，也不搜索钉钉文档或任何业务数据。
+
+Schema 的稳定 `canonical_path`、主 CLI 路径和 aliases 来自 reviewed `CommandRegistry`，并在发布时逐项绑定当前 Cobra tree。编辑 `internal/cli/schema_command_registry.json` 时必须遵守同目录的 `schema_command_registry.schema.json`；普通生成流程只校验该 reviewed input，不会覆盖它。Native annotation 只做实现一致性校验；Catalog 是该统一强类型契约的发布输出，不作为命令发现或下一轮生成的输入。
 
 ### 路径写法
 
 ```bash
-dws schema                                  # 列出所有产品 + 工具名
-dws schema ding.send_ding_message           # canonical: product.rpc_name
-dws schema ding.message.send                # CLI 点路径: product.group.cli_name
-dws schema "ding message send"              # CLI 空格路径（同上）
-dws schema --cli-path "ding message send"   # 显式 flag（脚本友好，免转义）
-dws schema -f pretty ding.send_ding_message # ANSI 着色分区展示（人肉查看最舒服）
+dws schema                                      # 当前公开产品面的紧凑概览
+dws schema calendar                             # 展开一个产品
+dws schema "calendar event"                     # 展开一个命令分组
+dws schema "calendar event create"              # 按 CLI 空格路径查询工具
+dws schema calendar.create_calendar_event       # 按 canonical path 查询工具
+dws schema --cli-path "calendar event create"   # 显式 CLI path
+dws schema "calendar event create" --compact    # 支持：省略 provenance/debug 字段
+dws schema --all                                # 全部工具的完整 leaf Schema，用于审计/CI/baseline
 ```
 
-Canonical 路径先匹配；落空后走 CLI 路径（product → group.. → cli_name）。
+兼容入口 `dws schema list` 等价于根概览。`schema --all` 是完整导出：每个工具都包含完整 leaf 参数、约束和安全语义。它输出很大，只用于明确要求的全量导出、审计、CI 或参数 baseline；普通 Agent 任务应按概览、产品/分组、leaf 渐进查询，不要把 `--all` 直接注入上下文。`schema --all --compact` 虽受支持，但会裁掉 provenance 和接口映射字段，不能作为完整 baseline。
+
+Leaf 查询、`--all` 中对应工具和 Catalog full tool 均由同一个 resolved `ToolSpec` 投影，内容必须一致；概览、产品/分组和 Catalog summary 也由该 `ToolSpec` 的统一 summary 投影生成。通过 alias 查询时，只允许 `cli_path` 和 `is_alias` 发生视图变化，参数、安全和接口契约不得变化。
+
+`--compact` 是 Schema 的展示选项。当前版本支持该 flag；若兼容旧二进制时收到 `unknown_flag: --compact`，用同一个 Schema 查询去掉 `--compact` 重试。这只降低输出裁剪能力，不表示 leaf 不存在，也不能改用 Schema 查询业务数据。
+
+### Schema、Help 与业务数据的边界
+
+| 问题 | 事实源 |
+|------|--------|
+| 命令是否由当前二进制暴露、Cobra 接受哪些 flags | `dws <path> --help` |
+| Agent 选哪个命令、参数映射与组合约束、risk/confirmation | 对应的 leaf `dws schema "<path>"` |
+| 当前钉钉中的文档、文件、日程、消息等业务数据 | 实际执行 `dws doc read`、`dws drive search` 等 read/search/list 命令 |
+
+Schema 与 Help 冲突表示发布契约漂移，不能静默猜测。执行参数必须以 Cobra 实际接受的 flag 为准；安全语义冲突时采用更保守的处理（例如先确认）或停止执行并报告漂移。完成命令发现后，仍必须执行真实业务命令；`dws schema` 本身不会读取或搜索业务内容。
 
 ### 单工具输出字段
 
 | 字段 | 说明 |
 |------|------|
-| `name` / `cli_name` / `canonical_path` | MCP RPC 名 / CLI 叶子名 / `product.rpc_name` |
-| `group` | CLI 父级 group 路径（dot-separated） |
-| `title` / `description` | 工具名/说明（overlay 优先） |
-| `parameters` / `required` | MCP 输入 JSON Schema 的 properties / required |
-| `output_schema` | MCP 输出 Schema（上游下发时才有） |
-| `sensitive` | 敏感写操作，需 `--yes` 确认 |
-| `auth` | DingTalk 授权元数据，包括 `requiredScopes` / `requiredPermissions` / `recommendedScopes` / `grantProductCodes` / `riskAction` / `confirmationRequired` |
-| `annotations.destructive_hint` | 对齐 MCP 2025+ annotations，目前从 `sensitive` 映射 |
-| `flag_overlay[param]` | CLI 层对 MCP 参数的改写：`alias` / `transform` / `transform_args` / `env_default` / `default` / `hidden` |
+| `canonical_path` / `primary_cli_path` / `aliases` | 稳定工具 ID、主 CLI 路径和兼容路径 |
+| `product_id` / `interface_ref` | CLI 产品与实际 MCP product/RPC binding |
+| `title` / `description` / `agent_summary` | 人类说明、接口说明和 Agent 摘要 |
+| `parameters.<flag>` | CLI flag 的类型、属性名、required、默认值、格式、枚举和条件必填 |
+| `constraints` | one-of、互斥、联动等组合约束 |
+| `effect` / `risk` / `confirmation` / `idempotency` | Agent 执行与安全策略 |
+| `use_when` / `avoid_when` / `examples` | Agent 选择提示和示例 |
+| `reviewed` / `agent_source_refs` | 语义审核状态与来源追踪 |
 
-**调试 `--flag` 行为的第一站**是 `flag_overlay` —— 比如 `--users 0232...` 能不能直接用，看 `receiverUserIdList.transform == "csv_to_array"` 即可判断。
+`parameters.<flag>.required` 是按来源 precedence 解析后的 Agent 参数契约；`cli_required=true` 才表示 Cobra 将该 flag 标记为硬必填。条件必填或别名选择通过 `required_when` 和 `constraints.require_one_of` 表达。`required` 不直接复制 MCP input schema，也不取代 Cobra 的实际执行校验。
 
 ### 筛选输出
 
 ```bash
-dws schema ding.send_ding_message --jq '.tool.flag_overlay'       # 只看 overlay
-dws schema calendar.create_event --jq '.tool.auth'                # 只看授权元数据
-dws schema --jq '.products[] | {id, count: (.tools|length)}'      # 各产品工具数
-dws schema aitable.delete_base --jq '.tool.annotations'           # 敏感操作提示
+dws schema "calendar event create" --jq '.parameters'                              # 只看参数
+dws schema "calendar event create" --jq '[.parameters | to_entries[] | select(.value.required)]'  # 只看 Agent required 参数
 ```
 
 ## Shell Completion / 自动补全

docs/releasing.md

@@ -0,0 +1,143 @@
+# 发布手册（预发 / 正式）
+
+发布只走一条链路：本地脚本负责封板、验证并推送 annotated tag；GitHub Actions 负责构建和发布最终产物。不要直接运行 `goreleaser release`，也不要手工补打或移动 tag。
+
+发布前必须完成平台治理：目标 GitHub 仓库已启用 immutable releases，`main` 精确要求 `CI` workflow 的九个 context：`Lint`、`Test`、`Coverage`、`Policy`、`Edition`、`Interface Integrity`、`AI Behavior`、`CLI Smoke`、`Mock MCP`，操作机已安装并登录 `gh`。本地脚本会在封 tag 前通过 API 检查 immutable releases、当前 SHA 的全部九个 context 和在途 Release；`v*` tag ruleset 仍需仓库管理员预先配置并由操作人确认。
+
+## 日常只用一个入口
+
+安装发布 Skill 后直接运行：
+
+```bash
+dws-release
+```
+
+零参数会进入引导模式。仓库内的等价入口是 `./scripts/release/dws-release.sh`。第一次使用只需配置一次生产发布远端，命令会把远端名及其规范化仓库身份一起保存在当前 Git 仓库中：
+
+```bash
+dws-release config --remote origin
+```
+
+之后命令按仓库状态自动走到正确步骤：缺少精确 CHANGELOG 章节时只生成模板并停止；补全、提交并合入 `main` 后，再运行同一条命令就会安全快进本地 `main` 并执行完整预检。若同名 remote 后续被改指向其他仓库会直接拒绝。只有显式增加 `--publish` 才会进入 tag 发布，且底层仍要求最终版本确认。
+
+## 发布模型
+
+```text
+main 上的候选代码 + beta CHANGELOG
+  → vX.Y.Z-beta.N（预发验证）
+  → 只允许补正式 CHANGELOG，源码不得再变化
+  → vX.Y.Z（正式发布）
+```
+
+正式版必须显式指定本次验证过的 beta。脚本会比较两者：除 `CHANGELOG.md` 外只要有任何文件变化，就拒绝正式发布。这样预发测过的代码、命令树和正式发布的代码是同一份。
+
+## 预发发布
+
+运行统一入口：
+
+```bash
+dws-release v1.2.3-beta.1
+```
+
+如果 CHANGELOG 尚不存在，该命令只生成模板并停止。补全内容、删除所有 `TODO`，提交后通过 PR 合入 `main`；然后重新运行完全相同的命令，它会执行完整预检：
+
+```bash
+dws-release v1.2.3-beta.1
+```
+
+预检包含测试、策略检查、旧正式版命令树兼容检查、全平台打包、npm 安装验证，以及 macOS 环境下的 Homebrew 安装验证。它还会从默认分支触发一次无发布权限的 `Release governance preflight`，用正式流水线相同的身份检查该精确 commit 的九个 Code Admission context 和 immutable releases。通过后会在当前 Git worktree 的私有 Git 状态目录写入一个有效期六小时的证明，绑定版本、精确 commit、发布仓库、beta/stable 基线和远端 `main`：
+
+```bash
+dws-release v1.2.3-beta.1 --publish
+```
+
+若源码、版本、远端身份和 stable 基线均未变化，`--publish` 会复用该证明，只执行远端契约、发布身份和最终治理复核，不再重复测试与打包。也可以直接运行 `--publish`；没有可复用证明时只会完整执行一次预检。命令在封 tag 前仍要求再次输入完整版本号，统一入口不提供跳过确认的参数。
+
+## 正式发布
+
+beta 验证通过后，运行正式版入口：
+
+```bash
+dws-release v1.2.3 --from-beta v1.2.3-beta.1
+```
+
+首次运行只生成正式版 CHANGELOG 并停止。补全内容、删除 `TODO`，提交后通过 PR 合入 `main`；重新运行同一条命令做完整预检，确认后增加 `--publish`：
+
+```bash
+dws-release v1.2.3 --from-beta v1.2.3-beta.1
+dws-release v1.2.3 --from-beta v1.2.3-beta.1 --publish
+```
+
+`FROM_BETA` 不会自动推断，并会写入 stable annotated tag 的 `From-Beta` 元数据，CI 会再次读取和验证。
+
+## CHANGELOG 契约
+
+每个 tag 必须有唯一、非空且不含 `TODO/TBD` 的精确章节：
+
+```markdown
+## [1.2.3-beta.1] - 2026-07-11
+
+### Changed
+
+- 本次 beta 验证的用户可见变化。
+```
+
+正式版使用 `## [1.2.3] - YYYY-MM-DD`。该章节会直接成为 GitHub Release Notes。
+
+## CI/CD 保证
+
+- 只接受 `vX.Y.Z-beta.N` 和 `vX.Y.Z`，且新版本必须高于上一正式版。这里的“上一正式版”必须同时具备公开非草稿 GitHub Release 和同 tag/commit 的成功 Release workflow；只有 tag、没有交付成功的孤儿版本会阻断后续发布，要求先重跑补齐。历史版本若曾通过专用 recovery workflow 完成交付，只能使用仓库内 `delivered-stable-recoveries.json` 中精确到 tag、commit、run、workflow SHA 与 attempt 的 reviewed 证据；验证仍要求 release、Darwin 签名和最终发布三个 job 全部成功，不能接受任意 workflow_dispatch。
+- tag 必须是 annotated tag；本地脚本在推送前重新确认 HEAD 与远端 `main` 完全一致，CI 允许其后 `main` 前进，但要求封板提交仍位于 `main` 历史中。
+- 日常 CI 和发布前都会对比“最新已交付正式版”的完整命令树；若长时间预检期间该 baseline 发生变化，会针对新的 baseline 重新比较。
+- GoReleaser 只构建；Darwin 重签、checksums 重算和 npm 安装验证通过后，才统一上传 GitHub Release 的最终产物。
+- 六个平台归档会逐个解包并核验二进制内嵌版本；公开资产集合、checksums 集合和 npm tarball integrity 都必须精确一致。npm tarball 固定由 npm `10.9.2` 打包，避免重跑时因 runner 自带 npm 漂移产生不同字节。
+- stable 发布到 npm `latest`，更新 OSS `latest.txt` 和共享安装脚本；prerelease 发布到 npm `beta`，只更新 OSS `beta.txt`，不会覆盖稳定入口。
+- Release workflow 使用一个最多容纳 100 个 pending run 的串行 publication queue；本地入口仍要求上一条 Release 完成后才能封下一个 tag。
+- 本地 tag push 失败时会删除本次新建的本地 tag。tag 一旦成功推送，后续发布归 CI 所有，禁止改 tag 指向或复用版本号。
+
+npm 补发只允许从默认分支触发 Release workflow 的 `repair_npm_version`。它只支持启用 immutable releases 后、由本流水线成功产出的公开 immutable release：目标必须是 `main` 历史中的 annotated tag，并且同 commit 的 `Build immutable GitHub Release` job 已成功。即使后续 npm 分发失败，这个独立的产物封存边界仍可作为补发依据。补发会用目标 commit 的 npm 模板重组包，逐平台核验资产和二进制版本，再发布到隔离的 `backfill` dist-tag，不会回滚 `latest` / `beta`。历史 mutable release 不进入自动补发路径，避免把可被替换的资产带入 npm。
+
+OSS/Gitee 分发失败且 GitHub immutable Release、npm 已交付时，从受保护的默认分支触发
+Release workflow，并且只填写 `repair_oss_version` 或 `repair_gitee_version` 之一。channel
+repair 会精确绑定失败 tag run 的最新 attempt；contract、构建、Developer ID 签名、
+immutable GitHub 发布和 npm delivery 必须全部成功，且只能有一个 OSS/Gitee 下游失败，
+随后才会下载并重新校验原始资产、修复所选镜像。OSS repair 必须匹配失败的 OSS step；
+Gitee repair 还允许其 job 因该 OSS 失败而 skipped，此时只代表 Gitee backfill 成功，
+不会把仍未修复的 OSS 标成成功。该证据不能用于 beta → stable 或
+stable baseline，后两者仍要求整条 Release 成功或受保护 recovery 成功。不要重跑旧
+attempt 的单个 failed job，以免在 attempts 之间拼接交付证据。独立 Gitee release
+workflow 和本地直发脚本已停用，避免绕开 publication queue 或用重新构建的不同字节覆盖镜像。
+
+## 既有 tag 的紧急恢复
+
+tag push 已成功、但 Release workflow 失败且 GitHub Release 尚未公开时，不要新建临时 workflow、移动 tag 或跳过门禁。在最新且干净的 `main` worktree 运行：
+
+```bash
+dws-release recover v1.2.3-beta.1
+```
+
+命令会自动解析 annotated tag object、peeled commit 和最近一次匹配的失败 tag-push run；也可以用 `--failed-run <run-id>` 精确指定。确认完整版本号后，它从默认分支触发受保护的恢复模式并等待完成。恢复模式必须满足：
+
+- 输入精确绑定原 annotated tag object、commit 和失败的 exact-tag `Release` run；commit 必须仍在 `main` 历史中。
+- 目标只允许不存在 GitHub Release 或仍为 Draft；已经公开的版本只能走对应的 channel repair，不能全量重建。
+- `release-recovery` environment 必须限制为受保护分支、配置至少一名 required reviewer，并禁止自审；workflow 会通过 API 复核这些设置，未配置时 fail closed。
+- 恢复复用正常的 contract、构建、Developer ID 签名、资产校验、immutable 发布、Homebrew、npm 和 OSS jobs，不存在 recovery 专用 publisher 或门禁跳过。
+- 如果 GitHub Release 已在 recovery 中封存、后续 Homebrew/npm 校验发生瞬时失败，只重跑该 run 的 failed jobs；流水线仅在隐藏 run marker、tag object、commit 和 finalized artifact 字节全部精确一致时复用公开 Release。
+
+成功的默认分支恢复 run 会成为后续 beta → stable 和 stable baseline 验证的可审计交付证据；历史临时分支恢复仍只接受 reviewed manifest 中的固定证据。
+
+OSS 的 `latest.txt` / `beta.txt` 当前是镜像频道元数据；仓库内安装器仍从 GitHub/Gitee 解析版本，不能把 OSS pointer 当成已接入的安装通道。
+
+Homebrew 当前只属于本机预检/手工公式通道：预检会在当前 macOS 架构真实安装，但 Release workflow 不发布 tap，CI 生成的单主机公式也不应当作 Darwin 双架构正式交付。正式自动交付范围是 GitHub Release、npm、OSS，以及显式开启时的 Gitee fallback；Homebrew 双架构 tap 发布需另立需求。
+
+## 平台治理前置
+
+仓库管理员还需要在 GitHub 平台配置以下不可由脚本替代的规则：
+
+- `main` 必须精确要求 `Lint`、`Test`、`Coverage`、`Policy`、`Edition`、`Interface Integrity`、`AI Behavior`、`CLI Smoke`、`Mock MCP` 九个 Code Admission context；tag workflow 也会通过 Checks API 再确认该封板 SHA 上九项全部成功。
+- 必须启用 immutable releases；它只保护启用后发布的 release，因此应在第一次使用新流水线前配置。为 `v*` 增加 tag ruleset，限制创建权限，并在 release 发布前保护 tag 的短暂窗口。
+- 配置 `RELEASE_GOVERNANCE_TOKEN` Actions secret，只授予目标仓库 `Administration: read`；内置 `GITHUB_TOKEN` 不具备 immutable-releases API 所需的仓库治理权限。每次本地预检和 tag workflow 都使用这一个身份进行 fail-closed 验证。
+- 单独配置 `HOMEBREW_PR_TOKEN`，优先使用仅授权本仓库且具备 `Contents: write`、`Pull requests: write` 的 fine-grained PAT；若组织策略不允许该账号使用 fine-grained PAT，则回退到仅带 `public_repo` scope 的专用 classic PAT。治理预检和 tag contract 会验证 token 身份、classic scope，并用 `[skip ci]` 临时分支和 draft PR 完成真实写权限 canary，随后立即关闭 PR、删除分支；任何清理失败都会 fail closed。门禁也会拒绝与治理 token 复用。
+- 创建 `release-recovery` environment，只允许受保护分支，设置 required reviewer、禁止自审并关闭管理员绕过。workflow 会读取 environment 的 required-reviewer、prevent-self-review 和 protected-branch 规则；规则缺失时紧急恢复会失败，正常 beta/stable tag 发布不受影响。
+
+immutable releases，或任一 Code Admission context 缺失、未成功时，发布脚本会自动拒绝封 tag。tag ruleset 可能来自组织层，脚本不自动推断其最终作用范围；管理员确认不能省略，脚本约定也不能替代平台强制。

docs/schema-dynamic-endpoint-design.md

@@ -0,0 +1,311 @@
+# DWS Agent Schema 统一方案
+
+## 1. 核心定义
+
+DWS Schema 是当前二进制公开 CLI 的版本化 Agent 执行契约。它描述真实 Cobra 命令，并补充 Agent 选择、参数映射、组合约束、安全确认和接口事实。
+
+设计遵循三条硬规则：
+
+1. **Schema 描述 CLI，不制造 CLI。** `CommandRegistry`、manual hint、metadata 和 Catalog 都不能凭空创建 Cobra 命令或 flag；registry 中的每个路径都必须精确绑定真实 runnable Cobra leaf。
+2. **所有来源只解析一次。** 来源经过统一 resolver 进入 typed `SchemaRegistry`，所有查询、导出和门禁都消费同一个 `SchemaRegistry/SchemaIndex`。
+3. **Registry-first，Catalog 只出不进。** reviewed `CommandRegistry` 是稳定 command identity/navigation 的唯一事实源；`schema_catalog.json` 和其他生成 JSON 只是下游发布物，不能成为命令、metadata 或下一轮 Catalog 的来源。运行时 production loader 解码 embedded snapshot 只是交付边界，不是 source resolution。
+
+Schema 不调用 MCP `tools/list`，不访问网络，也不读取用户本地 discovery cache。
+
+## 2. 单向数据流
+
+```text
+schema_command_registry.json           (reviewed CommandRegistry source)
+  + reviewed manual command additions
+                         |
+                         v
+             EffectiveCommandRegistry
+                         |
+                         v
+          exact binder to live Cobra tree
+       + native identity consistency assertions
+                         |
+                         v
+               BoundCommandRegistry
+                         |
+                         +----------------------+
+                                                |
+skills/mono Markdown + internal/cli/schema_hints/*.json |
+  + schema_mcp_metadata.json                     |
+                         |                       |
+                         v                       |
+             Agent-metadata normalization       |
+                         |                       |
+                         v                       |
+             schema_agent_metadata/*.json       |
+               (generated normalized input)     |
+                         |                       |
+                         +-----------------------+
+                         |
+live Cobra flag facts / typed parameter metadata
+  + schema_hints/metadata/*.json      (reviewed parameter overlay + safety)
+  + schema_hints/selection/*.json     (reviewed Agent selection prose)
+  + schema_parameter_bindings.json    (reviewed flag -> RPC property)
+  + schema_mcp_metadata.json          (pinned, sanitized interface facts)
+  + normalized Agent metadata
+                         |
+                         v
+              source adapters + resolvers
+                         |
+                         v
+             one typed SchemaRegistry
+              (one ToolSpec per command)
+                         +
+                    typed SchemaIndex
+             +-----------+-----------+
+             |                       |
+             v                       v
+     build-time typed gates    snapshot serializer
+                                     |
+                                     v
+                              schema_catalog.json
+                              (release output only)
+                                     |
+                                     v
+                           go:embed -> typed loader
+                                     |
+                                     v
+                         SchemaRegistry + SchemaIndex
+                                     |
+               +---------------------+------------------+
+               |                     |                  |
+      overview/product/group        leaf              --all
+            projections          projection      full projection
+               |                     |                  |
+               +---------------------+------------------+
+                                     |
+                                     v
+                         runtime query + delivery gates
+```
+
+`--help` 是 Cobra 自身的人类可读投影，不从 Catalog 生成。Schema projections 和 `--help` 共享同一真实 Cobra 命令面，但承担不同职责。Binder 之后不得再从 annotation、manual hint 或生成 JSON 重新解析 command identity。
+
+## 3. 与 Lark 的关系
+
+DWS 与 Lark 保持**架构同构**，而不是强行复制字段：
+
+| Lark 分层 | DWS 对应层 |
+|---|---|
+| typed command/metadata registry | `EffectiveCommandRegistry`、`BoundCommandRegistry` 与最终 `SchemaRegistry` |
+| navigation catalog/index | 从同一 `ToolSpec` 派生的 `SchemaIndex` |
+| schema renderer/envelope | overview、product/group、leaf、`--all` projections |
+
+共同点是：强类型 registry 持有已审核、已绑定、已解析的事实，index 只负责确定性导航，renderer 只投影，不重新读取来源或做 precedence。DWS 的 base Registry 与 reviewed manual command additions 在绑定前合并为唯一的 `EffectiveCommandRegistry`，因此不存在 “native-first”、“legacy registry fallback” 或 Catalog fallback。
+
+DWS 内部 resolved model 为：
+
+```text
+SchemaRegistry
+  -> []ProductSpec
+       -> []ToolSpec
+            -> ToolIdentitySpec
+            -> []ParameterSpec
+            -> RuntimeSchemaConstraints + []RuntimeSchemaPositional
+            -> SafetySpec
+            -> InterfaceSpec
+            -> SelectionSpec
+            -> map[field]FieldProvenance
+```
+
+字段合并和 precedence 在进入该模型前完成。`map[string]any`/flat JSON 只允许存在于 renderer 和 snapshot/wire boundary，不能作为内部 resolver、navigation 或 gate 的第二套数据模型。
+
+DWS 当前对外仍保留兼容 wire：leaf 使用 flat `parameters`，安全和选择字段也保持现有键名。架构对齐不等于未版本化地切换到 Lark `inputSchema/outputSchema/_meta` envelope；若未来提供该格式，应作为明确版本的新投影，并保留现有兼容输出。
+
+## 4. 来源职责
+
+| 来源 | 负责内容 | 明确不负责 |
+|---|---|---|
+| `schema_command_registry.json` | reviewed `CommandRegistry`：稳定 canonical identity、primary CLI path、alias、exposure 和导航 | 创建 Cobra 命令/flag、参数、安全、endpoint/token |
+| reviewed manual command additions | 将一个精确存在的 runnable Cobra leaf 合并进 `EffectiveCommandRegistry`；必须 reviewed 且带 reason | 运行时 fallback、覆盖冲突 identity、创建命令 |
+| Go/Cobra | 路径是否真实可执行、Cobra 接受的 flag、CLI 类型/默认值、执行校验、help 文本 | 稳定 canonical identity、Agent 场景选择、虚构 RPC |
+| native Schema identity annotations | implementation-side consistency evidence；存在时必须与 `EffectiveCommandRegistry` 精确一致 | 提供、补全、推断或覆盖 identity |
+| `schema_hints/metadata/*.json` parameter overlays | 精确覆盖现有 flag 的描述、映射、类型和 required 语义；并承载 safety / `runtime_gate` / interface | 创建命令/flag、绕过 completeness、虚构 RPC |
+| typed parameter metadata / constraints | `required_when`、one-of、互斥、联动、格式、枚举、位置参数 | 命令 identity |
+| `schema_parameter_bindings.json` | 稳定 CLI flag 到 RPC property 的映射 | 命令发现、risk 推断 |
+| `schema_mcp_metadata.json` | pinned RPC identity、接口描述和脱敏参数事实 | CLI identity、运行时路由、risk 推断 |
+| `schema_hints/selection/*.json` | reviewed selection prose（summary / use_when / avoid_when / examples） | 创建 Cobra 命令或参数、改写 safety |
+| Skills/Markdown | 产品路由、工作流和使用建议 | 命令存在性和 flag 事实 |
+| `schema_catalog.json` 及其他 generated JSON | resolved registry 的兼容发布序列化；运行时由 production loader 解回 typed registry/index | generation/source resolution 输入、identity fallback、手工修复源 |
+
+`schema_command_registry.json` 承载 reviewed `CommandRegistry`。Manual command addition 先以确定性规则合并进 effective registry；从 binder 开始，下游只看到一个稳定 identity/navigation 模型。旧 wire 中的 `surface_hash` / `surface_tools` 字段仅为兼容名称，语义已经是 effective Registry hash/coverage，不构成第二事实源。
+
+## 5. 统一解析与 precedence
+
+### 5.1 Identity
+
+- Reviewed base `CommandRegistry` 是 stable canonical identity、primary path、alias 和 navigation 的唯一基础事实源。
+- Reviewed manual command addition 只能引用精确存在的 runnable Cobra leaf；它在绑定前合并进 `EffectiveCommandRegistry`。若与 base Registry 的 identity/path/alias 冲突，生成失败，不能按 precedence 静默覆盖。
+- Binder 必须把 effective entry 的 primary path 和每个 alias 精确解析到同一个真实 executable leaf；stale path、phantom path、重复 identity 或 alias collision 全部失败。
+- Native identity annotation 是可选的一致性证据：存在时必须与 effective entry 精确一致；缺失不触发补写、推断或 fallback。
+- Public runnable Cobra leaf 未进入 effective registry 时，必须存在 exact、reviewed、带 reason 的 exclusion；不得用 prefix/wildcard 排除。
+- Identity 不做名称推断，不从 Catalog/generated metadata fallback，也没有多来源 winner。
+
+删除 native materialization 前已做写入审计：旧
+`ApplyNativeRuntimeSchemaContracts` 的唯一写操作是对已存在命令调用
+`AttachRuntimeSchema`，只写 command identity 的 product/tool/source annotation；
+它不写 flag property/type/required、constraints、positionals、title/description
+或 interface mapping。这些字段原本已分别由 parameter binding/metadata、
+constraint、Cobra help 和 interface resolver 提供，因此删除该过渡层没有数据迁移缺口。
+CI 同时禁止重新加入 generated native contracts 或 materialization 入口。
+
+#### CommandRegistry 输入审计
+
+`schema_command_registry.json` 是 reviewed source，不是生成快照。它必须保留
+`$schema: ./schema_command_registry.schema.json`。该 JSON Schema 对 root、product
+和 CommandSpec 全部使用 `additionalProperties: false`，并约束：
+
+- canonical identity、`source_product_id` 和精确 CLI path 的格式；
+- `aliases` 唯一且不能复用 primary path；
+- `visibility` 只允许 `public | compat | internal`，省略时明确归一化为
+  `public`；
+- primary path、alias、canonical 和 product 之间无法由 JSON Schema 表达的
+  交叉约束，继续由 Go strict loader 和 Cobra binder fail-closed 校验。
+
+Registry semantic hash 覆盖 canonical、primary CLI path、alias 集合、
+`source_product_id` 和 normalized visibility。格式、顺序以及省略的等价默认值
+不改变 hash；上述任一稳定契约字段变化都必须改变 hash。测试逐字段验证这一点，
+不使用当前命令数量作为常量。
+
+普通 `go generate ./internal/cli` 只把 Registry 作为 validation-only 输入并生成
+Agent metadata/Catalog 等单向下游资产，不生成或覆盖 Registry。drift policy 在生成
+前后对 reviewed Registry 做 byte-for-byte guard；独立的
+`check-schema-command-registry.sh` 在 interface/provenance/Catalog policy 之前检查
+JSON 输入契约、禁用旧 native materialization 符号，并从 Registry 动态计算审计
+数量，不能硬编码某次快照的 tool count。
+
+### 5.2 Parameter
+
+每个字段按明确的来源 precedence 选择一次，并把 winner、候选值和来源写入 provenance。precedence **与值无关**：不能因为 `required=true` 看起来更严格就让它越级获胜。更高优先级的 reviewed manual override 可以把 `required`、映射、interface type 或描述调高，也可以调低。
+
+实现中的参数字段顺序固定为：
+
+```text
+reviewed manual > versioned binding > command constraint > typed metadata
+                > native/Cobra contract > ToolSchemaHint > MCP metadata
+                > inference/default
+```
+
+命令 `title` / `description` 使用独立但同样确定的文本顺序：
+
+```text
+reviewed ToolSchemaHint > command-specific Cobra Help > MCP metadata > inference
+```
+
+因此多个 CLI leaf 复用同一个 RPC 时，通用 RPC 文案只能作为未选中的
+provenance candidate 保留；参数级 RPC 文案可进入 `interface_description`，
+但不得覆盖 leaf 自己的标题和执行语义。
+
+Cobra hard-required 是独立的 executable fact，并通过 `cli_required`/provenance 保留；它不应在 renderer 中再次静默改写已经解析的 Agent projection。
+
+### 5.3 Safety、selection 与 interface
+
+`effect`、`risk`、`confirmation`、`idempotency`、selection 和 interface disposition 同样按 source precedence 解析，而不是按值的“严格程度”合并。更高优先级的 reviewed explicit/manual source 可以升高或降低最终值；同 precedence 的不同值必须报冲突。
+
+最终 interface disposition 还必须满足 conflict matrix：
+
+- `mode` 与 `availability` 正交：`mode` 只允许 `mcp | local | composite`，`availability` 只允许 `available | unavailable`；`unavailable` 不是第四种 mode。
+- `mcp + available`：只表示命令可由一个 pinned、参数可映射且语义等价的 `interface_ref` 完整表达；本地 wrapper 只是固定默认值或投影返回值时，也必须先证明参数和执行语义没有漂移。
+- `local + available`：仅用于纯本地进程、静态数据或策略操作，不得携带 direct `interface_ref`；“远端 RPC 尚未进入 pinned metadata”不能归类为 local。
+- `composite + available`：用于多 RPC、条件路由、本地投影，或 reviewed unpinned remote adapter；不得用单个 `interface_ref` 冒充完整实现，且必须提供 reviewed reason。未来需要表达多个 RPC 时使用单独的复合接口模型。
+- 任意合法 mode + `unavailable`：不得携带 `interface_ref`，必须提供明确 reason，并且 Agent 不得把它当作可用接口。
+
+## 6. Schema、Help 与业务数据边界
+
+| 问题 | 事实源 |
+|---|---|
+| 当前二进制是否暴露命令、Cobra 接受哪些 flags | `dws <path> --help` |
+| Agent 选哪个命令、参数映射/required/约束、risk/confirmation | 对应 leaf `dws schema "<path>"` |
+| 钉钉中的文档、文件、日程、消息等实际数据 | 真正执行 `dws doc read`、`dws drive search` 等 read/search/list 命令 |
+
+Schema 和 Help 冲突是契约漂移，不能静默猜测：
+
+- 执行参数以 Cobra 实际接受的 flags 为准；不要发送 Help 中不存在的 flag。
+- 安全语义冲突时不要采用更宽松值。先按更保守的解释确认；如果无法确定安全执行方式，停止并报告漂移。
+- Schema/Help 只完成命令发现和契约读取。需要业务结果时，必须继续执行真实 read/search/list 命令。
+
+上述运行时漂移策略不改变构建期的 value-neutral precedence；前者是在契约已经互相矛盾时保护用户，后者是在确定性生成同一契约。
+
+## 7. 查询投影
+
+```bash
+dws schema                                      # 产品紧凑概览
+dws schema calendar                             # 产品摘要
+dws schema "calendar event"                    # 分组摘要
+dws schema "calendar event create"             # 完整 leaf
+dws schema "calendar event create" --compact   # 支持：裁掉 provenance/debug 字段
+dws schema --all                               # 所有工具的完整 leaf 导出
+```
+
+`schema list` 是根概览的兼容入口。
+
+`schema --all` 必须包含最终 `SchemaIndex` 中每个 tool 的完整 leaf 参数、约束和安全语义；无业务参数的命令也要包含空 `parameters` 对象。它用于审计、CI 和参数防丢 baseline，但输出很大，普通 Agent 命令发现不得使用，应按 overview -> product/group -> leaf 渐进查询。
+
+`--compact` 当前受支持，适合减少常规 leaf 查询上下文。`schema --all --compact` 也可执行，但会移除 provenance/debug 和接口映射字段，不能作为完整兼容性 baseline。
+
+兼容旧二进制时，如果 Schema 查询返回 `unknown_flag: --compact`，只去掉 `--compact` 重试同一个查询。这是展示能力降级，不代表 leaf 缺失，也不能改用 Schema 查询业务数据。
+
+## 8. 生成与发布
+
+当 Cobra、flag、identity、binding、manual hint、Agent hint 或 Skill 发生变化时：
+
+1. 审核真实 Cobra 变化，确认命令和 flag 已实际存在。新增或修改稳定 command identity、primary CLI path 或 alias 时，精确编辑 reviewed `CommandRegistry`（当前持久化文件为 `schema_command_registry.json`）。参数、Skill 或 metadata 单独变化时不要机械改写 Registry，也不要从旧 Catalog 反向生成它。
+2. 仅对明确例外使用 reviewed manual command addition；它必须精确引用现有 runnable leaf、带 reason，并在生成时归一化进 `EffectiveCommandRegistry`。Native identity annotation 若存在，应作为与 Registry 一致的实现断言维护，而不是用来 materialize identity。
+3. 生成 Agent metadata：
+
+   ```bash
+   make generate-schema-agent-metadata
+   ```
+
+4. 从统一 typed registry 生成最终 Catalog：
+
+   ```bash
+   make generate-schema-catalog
+   ```
+
+也可以运行 `go generate ./internal/cli` 生成正常发布资产。生成文件包括：
+
+- `internal/cli/schema_agent_metadata/index.json`
+- `internal/cli/schema_agent_metadata/<product>.json`
+- `internal/cli/schema_agent_metadata_audit.json`
+- `internal/cli/schema_catalog.json`
+
+只编辑来源；不要手工编辑 Agent metadata 或 Catalog 输出。
+
+## 9. Completeness 与 final-delivery invariant
+
+门禁必须验证最终交付对象，而不是某个中间层或数量：
+
+- 每个 public runnable Cobra leaf 要么能通过最终 embedded `SchemaIndex` 查询，要么有 exact、reviewed、带 reason 的 exclusion。
+- 每个最终 canonical path、primary CLI path 和 alias 都必须解析到同一个可执行 leaf；不得有 phantom path 或 collision。
+- `EffectiveCommandRegistry`、`SchemaRegistry/SchemaIndex`、Agent metadata 和 Catalog canonical sets 必须精确一致，不能只比较 count。
+- Leaf payload、`--all` 中对应 tool 和 Catalog full tool 必须是同一个 resolved `ToolSpec` 的内容级等价投影，并通过 production loader round-trip。
+- overview/product/group summary 与 Catalog summary 必须等于同一个 `ToolSpec.ToSummaryPayload()`；alias 查询只允许 `cli_path` 和 `is_alias` 这两个视图字段变化。
+- 每个最终字段及 parameter field 的 provenance winner value 必须与 delivered value 精确一致；不能只验证 provenance source、count 或字段是否存在。
+- 每个 MCP `interface_ref` 必须在 pinned interface registry 精确存在；local/composite/unavailable 必须满足同一 conflict matrix。
+- `--all` 的 tool set 必须与最终 index 一对一，且每个工具包含完整参数契约。
+- 连续两次生成必须字节稳定，提交的生成物不得漂移。
+
+推荐本地验证：
+
+```bash
+make generate-schema-agent-metadata
+make generate-schema-catalog
+./scripts/policy/check-generated-drift.sh
+./scripts/policy/check-schema-catalog.sh
+go test ./internal/cli ./internal/app ./internal/generator/... -count=1
+```
+
+## 10. 明确禁止
+
+- 运行时调用 MCP `tools/list` 或访问网络生成 Schema。
+- 从旧 `schema_catalog.json` 或其他 generated JSON 反向创建/补齐 Cobra leaf、flag、CommandRegistry 或下一轮 Catalog。
+- 把 native annotation、legacy registry 或 Catalog 当作 identity fallback；或在 `EffectiveCommandRegistry` 之后再次选择 identity winner。
+- renderer、query 或 gate 在 `SchemaRegistry` 之后重新读取 source 并做第二次 merge。
+- 用 prefix/wildcard exclusion 隐藏未来命令。
+- 让 manual hint、CommandRegistry 或 interface metadata 宣称一个不存在的命令、flag 或 RPC 可用。
+- 把 `schema --all` 当作普通业务数据查询，或把其完整结果无条件注入 Agent 上下文。

docs/shortcut-backend-mcp-issues.md

@@ -0,0 +1,174 @@
+# Shortcut 真实测试：后端 / MCP 问题整理
+
+这份报告只汇总 `failure_category = backend-or-mcp-error` 的 case，已尽量排除权限、缺真实资源、当前账号无数据等噪音。
+
+## 总览
+
+- Backend/MCP case 总数：33
+- 聚合问题数：8
+- 复现口径：真实 dws CLI；无 mock；无 dry-run；命令输入和 trace_id 均来自真实测试结果。
+
+## 建议优先看
+
+1. [P1] Chat/IM 会话 ID 字段在 MCP/后端映射中疑似丢失（15 case）
+2. [P1] Chat card 发送 receiverUid 疑似未从 receiver 透传（1 case）
+3. [P1] Chat 入群审批 applicantUid/inviterUid 疑似未透传（1 case）
+4. [P1] AI 表格 MCP 错误 envelope 语义不一致：success=true 但 error 非空/status=error（5 case）
+5. [P1] AI 表格 Workflow 查询在真实 Base 下返回系统级错误（2 case）
+6. [P1] AI 表格 roleId 参数疑似未被 MCP 正确读取（3 case）
+7. [P2] AI 表格记录主文档查询在真实 record 下返回 no record/SYSTEM_ERROR（2 case）
+8. [P2] AI 表格无效 Base/Table/Field/Record 被包装成 SYSTEM_ERROR（4 case）
+
+## Chat/IM 会话 ID 字段在 MCP/后端映射中疑似丢失
+
+- 优先级：P1
+- 建议 owner：IM MCP / IM 后端字段映射
+- 现象：CLI 已传 group/conversation-id/open-conversation-id（部分 case 使用真实 cid），后端仍报 openCid/openConversationId/cid required。
+- 期望：MCP schema/网关应接受并透传 openConversationId/openCid/cid 中的兼容字段；如果资源无效，应返回“无效会话”，而不是 required。
+- 涉及 case：15
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `read` | `chat +chat-members-get` | `tools/call` | `2127d89817840997754345760e07bd` | [UNCLASSIFIED] openCid or cid is required (operation: im/list_group_member_by_ids) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +chat-members-get --id DWSREALREADNOSUCHID0000000000000 --users '冬翔' --yes --format json` |
+| `read` | `chat +chat-messages` | `tools/call` | `2104a64c17840997767792656e085e` | [UNCLASSIFIED] openCid or cid is required hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +chat-messages --group cid3Jijzhe2aqs9ysOXjhi05g== --time '2026-07-15 10:00:00' --limit 10 --direction older --yes --format json` |
+| `read` | `chat +messages-list` | `tools/call` | `2127d89817840997797873841e0757` | [UNCLASSIFIED] openCid or cid is required hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +messages-list --group cid3Jijzhe2aqs9ysOXjhi05g== --time '2026-07-15 10:00:00' --forward --limit 10 --yes --format json` |
+| `write` | `chat +chat-mute-member` | `tools/call` | `2104a64c17840999166036583e08a3` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/set_group_member_mute_list) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +chat-mute-member --group cidDWSREALTESTNOSUCHCONV --users __DWS_SHORTCUT_REAL_TEST_NO_SUCH_USER__ --mute-time 1 --off --yes --format json` |
+| `write` | `chat +chat-transfer-owner` | `tools/call` | `0b5deb3217840999222318863e087a` | [UNCLASSIFIED] openConversationId is required (operation: im/transfer_group_owner) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +chat-transfer-owner --group cidDWSREALTESTNOSUCHCONV --new-owner __DWS_SHORTCUT_REAL_TEST_NO_SUCH_USER__ --yes --format json` |
+| `write` | `chat +conversation-clear-messages` | `tools/call` | `2127d89817840999254816721e079b` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/clear_conversation_messages) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-clear-messages --conversation-id cidDWSREALTESTNOSUCHCONV --yes --format json` |
+| `write` | `chat +conversation-clear-red-point` | `tools/call` | `2104a64c17840999265511295e085f` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/clear_conversation_red_point) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-clear-red-point --conversation-id cidDWSREALTESTNOSUCHCONV --yes --format json` |
+| `write` | `chat +conversation-hide` | `tools/call` | `2127d89817840999276117140e079b` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/hide_conversation) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-hide --conversation-id cidDWSREALTESTNOSUCHCONV --yes --format json` |
+| `write` | `chat +conversation-mark-unread` | `tools/call` | `0bb7c36217840999298744910e0758` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/mark_conversation_unread) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-mark-unread --conversation-id cidDWSREALTESTNOSUCHCONV --yes --format json` |
+| `write` | `chat +conversation-mute` | `tools/call` | `2104a64c17840999309241865e085f` | [UNCLASSIFIED] openConversationId is required (operation: im/update_notification_off) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-mute --conversation-id cidDWSREALTESTNOSUCHCONV --off --yes --format json` |
+| `write` | `chat +conversation-mute-at-all` | `tools/call` | `2127d89817840999320028068e07dd` | [UNCLASSIFIED] openConversationId is required (operation: im/update_at_all_notification_off) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-mute-at-all --conversation-id cidDWSREALTESTNOSUCHCONV --off --yes --format json` |
+| `write` | `chat +conversation-mute-red-envelope` | `tools/call` | `0bb7c36217840999330228283e07fe` | [UNCLASSIFIED] openConversationId is required (operation: im/update_red_env_notification_off) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-mute-red-envelope --conversation-id cidDWSREALTESTNOSUCHCONV --off --yes --format json` |
+| `write` | `chat +conversation-set-top` | `tools/call` | `2127d89817840999341302961e07fe` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/set_top_conversation) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +conversation-set-top --conversation-id cidDWSREALTESTNOSUCHCONV --off --yes --format json` |
+| `write` | `chat +messages-set-pin` | `tools/call` | `0bb7c36217840999521117991e0758` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/set_pin_message) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +messages-set-pin --open-conversation-id cidDWSREALTESTNOSUCHCONV --msg-id DWSREALTESTNOSUCHID0000000000000 --yes --format json` |
+| `write` | `chat +messages-unset-pin` | `tools/call` | `2104a64c17840999544428103e08ee` | [UNCLASSIFIED] openConversationId or cid is required (operation: im/unset_pin_message) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +messages-unset-pin --open-conversation-id cidDWSREALTESTNOSUCHCONV --msg-id DWSREALTESTNOSUCHID0000000000000 --yes --format json` |
+
+## Chat card 发送 receiverUid 疑似未从 receiver 透传
+
+- 优先级：P1
+- 建议 owner：IM MCP / card 发送参数映射
+- 现象：CLI 传入 receiver=103262，后端仍报 receiverUid 和 openConversationId 不能同时为空。
+- 期望：receiver 应映射为 receiverUid，或 schema 明确要求 receiverUid；真实入参不应在 MCP 层丢失。
+- 涉及 case：1
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `write` | `chat +messages-send-card` | `tools/call` | `2104a64c17840999509255753e081a` | [UNCLASSIFIED] receiverUid和openConversationId不能同时为空 (operation: im/create_and_send_card) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +messages-send-card --receiver 103262 --yes --format json` |
+
+## Chat 入群审批 applicantUid/inviterUid 疑似未透传
+
+- 优先级：P1
+- 建议 owner：IM MCP / 入群审批参数映射
+- 现象：CLI 传入 applicant=103262、inviter=519019，后端仍报 applicantUid required。
+- 期望：applicant/inviter 应映射为 applicantUid/inviterUid；如果 recordId/group 无效，应返回对应资源错误而不是 applicantUid 缺失。
+- 涉及 case：1
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `write` | `chat +chat-audit-join` | `tools/call` | `0bb7c36217840999154832733e0758` | [UNCLASSIFIED] applicantUid is required (operation: im/audit_join_group) hint: Use --verbose for detailed error logs |
+| | input | | | `/private/tmp/dws-real-test chat +chat-audit-join --group cidDWSREALTESTNOSUCHCONV --record-id 999999999999 --applicant 103262 --inviter 519019 --status AuditApprove --description 'DWS shortcut 真实测试描述，可删除' --yes --format json` |
+
+## AI 表格 MCP 错误 envelope 语义不一致：success=true 但 error 非空/status=error
+
+- 优先级：P1
+- 建议 owner：AI 表格 MCP wrapper
+- 现象：多条 AI 表格命令返回 MCP_TOOL_ERROR，内部 JSON 同时出现 success=true、status=error、error 非空。
+- 期望：只要 error 非空或 status=error，success 应为 false，外层也应按业务错误返回稳定错误码/trace。
+- 涉及 case：5
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `read` | `aitable +export-data` | `-` | `2104a64c17840997514714448e0817` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"taskId cannot be combined with scope, format, tableId or viewId","retryable":false,"type":"INPUT_ERROR"},"m… |
+| | input | | | `/private/tmp/dws-real-test aitable +export-data --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --task-id DWSREALREADNOSUCHID0000000000000 --scope all --format excel --table-id hERWDMS --view-id qvGDAH2 --timeout-ms 1 --yes` |
+| `write` | `aitable +chart-update` | `-` | `2106d98117840998553244877e08df` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"config is required","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"error","success":true,"summ… |
+| | input | | | `/private/tmp/dws-real-test aitable +chart-update --base-id DWSREALTESTNOSUCHID0000000000000 --dashboard-id DWSREALTESTNOSUCHID0000000000000 --chart-id DWSREALTESTNOSUCHID0000000000000 --config '{}' --layout '{}' --yes --format json` |
+| `write` | `aitable +record-update` | `-` | `0bab027317840998747383236e090b` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_RECORDS","message":"records must contain at least one writable record","retryable":false,"type":"INPUT_ERROR"},"meta":{},"stat… |
+| | input | | | `/private/tmp/dws-real-test aitable +record-update --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --records '[{"recordId":"recDWSREALTEST","cells":{}}]' --yes --format json` |
+| `write` | `aitable +record-upsert` | `-` | `2106d98117840998759832182e087b` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMETER","message":"records is required and must not be empty","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"e… |
+| | input | | | `/private/tmp/dws-real-test aitable +record-upsert --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --records '[]' --yes --format json` |
+| `write` | `aitable +view-set-fill-color-rule` | `-` | `2106d98117840998924181709e08df` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"conditionalFormats is required","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"error","success… |
+| | input | | | `/private/tmp/dws-real-test aitable +view-set-fill-color-rule --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --view-id DWSREALTESTNOSUCHID0000000000000 --json '{}' --yes --format json` |
+
+## AI 表格 Workflow 查询在真实 Base 下返回系统级错误
+
+- 优先级：P1
+- 建议 owner：AI 表格 Workflow MCP / 后端
+- 现象：使用真实可访问 Base 查询 workflow list/get，返回 LIST_WORKFLOWS_ERROR/GET_WORKFLOW_ERROR。
+- 期望：无 workflow 时应返回空列表或 WORKFLOW_NOT_FOUND；有后端异常时需提供稳定错误码和可排查 trace。
+- 涉及 case：2
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `read` | `aitable +workflow-get` | `-` | `2104a64c17840997556363676e08ee` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"GET_WORKFLOW_ERROR","message":"调用远程服务业务异常","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary"… |
+| | input | | | `/private/tmp/dws-real-test aitable +workflow-get --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --workflow-id DWSREALREADNOSUCHID0000000000000 --yes --format json` |
+| `read` | `aitable +workflow-list` | `-` | `2127d89817840997572427879e075d` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"LIST_WORKFLOWS_ERROR","message":"biz error","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary… |
+| | input | | | `/private/tmp/dws-real-test aitable +workflow-list --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --limit 10 --offset 1 --yes --format json` |
+
+## AI 表格 roleId 参数疑似未被 MCP 正确读取
+
+- 优先级：P1
+- 建议 owner：AI 表格 MCP role 接口
+- 现象：CLI 已传 --role-id，但 MCP 返回 roleId is required。
+- 期望：role-id/roleId 字段应被正确映射；如果 role 不存在，返回 ROLE_NOT_FOUND，而不是 required。
+- 涉及 case：3
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `read` | `aitable +role-get` | `-` | `2104a64c17840997542904838e0817` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"roleId is required","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"error","success":true,"summ… |
+| | input | | | `/private/tmp/dws-real-test aitable +role-get --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --role-id x --yes --format json` |
+| `write` | `aitable +role-delete` | `-` | `2106d98117840998782482701e089c` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"roleId is required","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"error","success":true,"summ… |
+| | input | | | `/private/tmp/dws-real-test aitable +role-delete --base-id DWSREALTESTNOSUCHID0000000000000 --role-id DWSREALTESTNOSUCHID0000000000000 --yes --format json` |
+| `write` | `aitable +role-update` | `-` | `2132f5ca17840998794483634e08d8` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"INVALID_PARAMS","message":"roleId is required","retryable":false,"type":"INPUT_ERROR"},"meta":{},"status":"error","success":true,"summ… |
+| | input | | | `/private/tmp/dws-real-test aitable +role-update --base-id DWSREALTESTNOSUCHID0000000000000 --role-id DWSREALTESTNOSUCHID0000000000000 --name 'DWS shortcut 真实测试 20260715-151724' --role-type x --flow-type x --sub-roles '[]' --yes --format json` |
+
+## AI 表格记录主文档查询在真实 record 下返回 no record/SYSTEM_ERROR
+
+- 优先级：P2
+- 建议 owner：AI 表格 primary doc MCP / 后端
+- 现象：record-query 已能查到真实 recordId，但 primary-doc 查询返回 no record、type=SYSTEM_ERROR。
+- 期望：若该记录无主文档，应返回空/未创建；若 recordId 语义不匹配，应返回明确参数错误，不应是系统错误。
+- 涉及 case：2
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `read` | `aitable +base-get-primary-doc-id` | `-` | `0b5deb3217840997466255627e08ee` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"-1","message":"no record","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary":"Failed to query… |
+| | input | | | `/private/tmp/dws-real-test aitable +base-get-primary-doc-id --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --table-id hERWDMS --record-id 1015oH3OXy --yes --format json` |
+| `read` | `aitable +record-primary-doc-get` | `-` | `2127d89817840997528393730e079c` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"-1","message":"no record","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary":"Failed to query… |
+| | input | | | `/private/tmp/dws-real-test aitable +record-primary-doc-get --base-id gpG2NdyVXQyZ0OmoSbd1vbA6JMwvDqPk --table-id hERWDMS --record-id 1015oH3OXy --yes --format json` |
+
+## AI 表格无效 Base/Table/Field/Record 被包装成 SYSTEM_ERROR
+
+- 优先级：P2
+- 建议 owner：AI 表格 MCP wrapper / 后端错误码
+- 现象：安全负向 ID 下，部分写接口返回 getDentryDTO returns null、type=SYSTEM_ERROR、retryable=true。
+- 期望：资源不存在应返回 INPUT_ERROR/NOT_FOUND 且 retryable=false，避免误导调用方重试。
+- 涉及 case：4
+
+| 套件 | shortcut | operation | trace_id | 证据 |
+|---|---|---|---|---|
+| `write` | `aitable +field-delete` | `-` | `0bab027317840998611338768e08c8` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"404","message":"getDentryDTO returns null","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary"… |
+| | input | | | `/private/tmp/dws-real-test aitable +field-delete --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --field-id DWSREALTESTNOSUCHID0000000000000 --yes --format json` |
+| `write` | `aitable +field-update` | `-` | `213ee25c17840998623207342e08e2` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"404","message":"getDentryDTO returns null","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary"… |
+| | input | | | `/private/tmp/dws-real-test aitable +field-update --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --field-id DWSREALTESTNOSUCHID0000000000000 --name 'DWS shortcut 真实测试 20260715-151724' --config '{}' --ai-config '{}' --yes --format json` |
+| `write` | `aitable +record-delete` | `-` | `2132f5ca17840998724753149e0853` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"404","message":"getDentryDTO returns null","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary"… |
+| | input | | | `/private/tmp/dws-real-test aitable +record-delete --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --record-ids DWSREALTESTNOSUCHID0000000000000 --yes --format json` |
+| `write` | `aitable +table-update` | `-` | `213ee25c17840998877246229e087f` | [MCP_TOOL_ERROR] {"data":{},"error":{"code":"404","message":"getDentryDTO returns null","retryable":true,"type":"SYSTEM_ERROR"},"meta":{},"status":"error","success":true,"summary"… |
+| | input | | | `/private/tmp/dws-real-test aitable +table-update --base-id DWSREALTESTNOSUCHID0000000000000 --table-id DWSREALTESTNOSUCHID0000000000000 --name 'DWS shortcut 真实测试 20260715-151724' --description 'DWS shortcut 真实测试描述，可删除' --record-name-key task --yes --format json` |

docs/shortcut-error-review.html

@@ -0,0 +1,279 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Shortcut 真实测试失败逐项 review</title>
+<style>
+:root{--bg:#0f1420;--card:#151d2b;--line:#263246;--text:#dce7f7;--muted:#91a0b5;--blue:#8fd3ff;--green:#66d38a;--yellow:#e2b23c;--red:#f27272;--purple:#d3a7ff}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--text);font:13px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"PingFang SC","Microsoft YaHei",sans-serif}
+header{padding:28px 32px 14px;border-bottom:1px solid var(--line);background:linear-gradient(180deg,#172033,#0f1420)}
+h1{margin:0 0 8px;font-size:26px}
+h2{margin:28px 0 10px;font-size:18px}
+.sub,.note,.count{color:var(--muted)}
+.wrap{padding:18px 32px 40px;max-width:1800px;margin:0 auto}
+.note{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 14px;margin:10px 0 18px}
+.stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin:18px 0}
+.stat{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px}
+.stat .n{font-size:24px;color:var(--blue);font-weight:700}
+.stat .l{color:var(--muted);font-size:12px}
+.summary-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(320px,1fr));gap:18px;margin:16px 0 22px}
+table{width:100%;border-collapse:collapse;background:var(--card);border:1px solid var(--line);border-radius:10px;overflow:hidden}
+th,td{padding:8px 10px;border-bottom:1px solid var(--line);vertical-align:top;text-align:left}
+th{background:#1b2536;color:var(--muted);font-size:12px;font-weight:600;position:sticky;top:0;z-index:1}
+tr:last-child td{border-bottom:none}
+code{font-family:"SF Mono",Menlo,Consolas,monospace;color:#c7cfdb;font-size:12px}
+.review{table-layout:fixed}
+.review th:nth-child(1),.review td:nth-child(1){width:44px}
+.review th:nth-child(2),.review td:nth-child(2){width:165px}
+.review th:nth-child(3),.review td:nth-child(3){width:70px}
+.review th:nth-child(4),.review td:nth-child(4){width:120px}
+.review th:nth-child(5),.review td:nth-child(5){width:130px}
+.review th:nth-child(8),.review td:nth-child(8){width:130px}
+.review th:nth-child(9),.review td:nth-child(9){width:180px}
+.review td{word-break:break-word}
+.num{color:var(--muted);text-align:right}
+.risk{color:var(--green)}
+.cat{color:var(--yellow)}
+.owner{color:var(--purple)}
+.evidence{color:#c7cfdb;font-size:12px}
+a{color:var(--blue)}
+</style>
+</head>
+<body>
+<header>
+<h1>Shortcut 真实测试失败逐项 review</h1>
+<div class="sub">由 <code>scripts/gen_shortcut_error_review.py</code> 从真实测试结果生成；目标是把每个失败项落到“应该改哪里”。</div>
+</header>
+<main class="wrap">
+<div class="note">
+Read：204 条，成功 162，失败 41，超时 0。
+Write：162 条，成功 48，失败 114，超时 0。
+判定口径：如果 fake MCP 已看到字段但真实后端仍报 required，按后端/MCP schema 映射处理；如果真实后端报资源无效/不存在，按 fixture 处理；权限类不在 CLI 中绕过。
+</div>
+
+<div class="stats"><div class="stat"><div class="n">41</div><div class="l">Read 失败</div></div>
+<div class="stat"><div class="n">114</div><div class="l">Write 失败</div></div>
+<div class="stat"><div class="n">156</div><div class="l">逐项 review</div></div>
+<div class="stat"><div class="n">72</div><div class="l">测试数据/fixture</div></div>
+<div class="stat"><div class="n">22</div><div class="l">权限/应用配置</div></div>
+<div class="stat"><div class="n">33</div><div class="l">后端/MCP schema</div></div></div>
+<div class="summary-grid">
+<section><h2>按错误类型</h2><table><thead><tr><th>类型</th><th>数量</th></tr></thead><tbody><tr><td>输入/业务校验</td><td>36</td></tr>
+<tr><td>后端/MCP</td><td>33</td></tr>
+<tr><td>缺 AI 表格 fixture</td><td>31</td></tr>
+<tr><td>缺真实资源</td><td>30</td></tr>
+<tr><td>鉴权/权限</td><td>22</td></tr>
+<tr><td>缺妙记 fixture</td><td>3</td></tr>
+<tr><td>敏感/高风险暂缓</td><td>1</td></tr></tbody></table></section>
+<section><h2>按要改哪里</h2><table><thead><tr><th>要改哪里</th><th>数量</th></tr></thead><tbody><tr><td>测试数据</td><td>72</td></tr>
+<tr><td>后端/MCP schema</td><td>33</td></tr>
+<tr><td>权限/应用配置</td><td>22</td></tr>
+<tr><td>测试输入/业务校验</td><td>13</td></tr>
+<tr><td>后端业务/测试 fixture</td><td>11</td></tr>
+<tr><td>测试输入</td><td>2</td></tr>
+<tr><td>人工安全确认</td><td>1</td></tr>
+<tr><td>测试输入/shortcut 枚举</td><td>1</td></tr>
+<tr><td>测试输入/业务规则</td><td>1</td></tr></tbody></table></section>
+</div>
+
+
+<h2>缺真实资源复盘 <span class="count">· 可自造/可查资源处理结果</span></h2>
+<table>
+<thead><tr><th>命令/范围</th><th>处理状态</th><th>本次实际排查/造数结果</th><th>后续建议</th></tr></thead>
+<tbody><tr><td><code>chat +group-members</code></td><td><span class="cat">已补齐</span></td><td>查到真实群名 `浅曦-kida,Dennis,秋画`，runner 已改为用群名而不是 openConversationId；真实回归成功。</td><td>无需后续动作。</td></tr>
+<tr><td><code>chat +messages-mget</code></td><td><span class="cat">已补齐</span></td><td>复用真实单聊消息 `msgEuOor1PmFBNlx9M06N9z1Q==`；真实回归成功。</td><td>无需后续动作。</td></tr>
+<tr><td><code>chat +messages-read-status</code></td><td><span class="cat">已补齐</span></td><td>复用真实单聊会话 `cidie1367hAfBxqipzE59k5sknHLrHmvYkw98NADhfnjPI=` 与同一 openMessageId；真实回归成功。</td><td>无需后续动作。</td></tr>
+<tr><td><code>chat +messages-query-send-status</code></td><td><span class="cat">已补齐</span></td><td>复用真实发送返回的 openTaskId；真实回归成功。</td><td>无需后续动作。</td></tr>
+<tr><td><code>ding +receiver-status</code></td><td><span class="cat">已补齐</span></td><td>先只读 `ding +list` 找到已有 openDingId，再查询 receiver status；没有新发 DING，真实回归成功。</td><td>无需后续动作。</td></tr>
+<tr><td><code>sheet +list-sheets</code></td><td><span class="cat">已自造</span></td><td>创建临时在线表格 `DWS shortcut 真实测试表格 20260715`，nodeId=`mweZ92PV6O36dZbnsMZx70ylJxEKBD6p`；真实回归成功。</td><td>后续可保留为稳定 fixture，或测试结束后人工清理。</td></tr>
+<tr><td><code>todo +todo-done</code></td><td><span class="cat">已自造并修复 CLI</span></td><td>runner 会先创建当前账号自己的临时待办，再执行 `todo +todo-done`；同时修复了 todo 列表 pageSize=50 返回空、响应多层 result unwrap 不稳的问题；真实回归成功。</td><td>无需后续动作；代码已有单测覆盖 nested result。</td></tr>
+<tr><td><code>contact +by-mobile</code></td><td><span class="cat">已按用户授权补齐</span></td><td>使用用户指定手机号 `13161187007` 作为真实 fixture；runner 只在该命令上替换 mobile，不扩散到其它服务。</td><td>真实回归成功后该项将从失败列表移除；若后续要脱敏公开报告，可再加展示层脱敏。</td></tr>
+<tr><td><code>attendance +get-class / +get-group / +get-group-filtered</code></td><td><span class="cat">不建议自造</span></td><td>`attendance +search-class` 与 `+search-group --type FIXED` 均返回空；创建班次/考勤组会改组织考勤配置，属于高影响业务数据。</td><td>需要考勤后端/业务同学提供可读测试班次与考勤组 ID。</td></tr>
+<tr><td><code>chat +chat-get-by-id</code></td><td><span class="cat">暂未找到</span></td><td>该 shortcut 只接受数字 groupId；真实群列表只返回 openConversationId，没有数字群号字段。</td><td>需要 IM 后端提供可用数字 groupId，或评估是否新增 openConversationId 形态的 shortcut。</td></tr>
+<tr><td><code>chat +messages-resource-url</code></td><td><span class="cat">暂未自造</span></td><td>需要真实含 mediaId 的图片/文件/视频消息；当前文本消息无法产生 resource-id。</td><td>可在测试群发一条图片/文件消息并提取 mediaId 后补 fixture；注意会产生群消息。</td></tr>
+<tr><td><code>chat +thread-replies</code></td><td><span class="cat">暂未自造</span></td><td>需要真实话题消息 topicId；普通群消息不能替代。</td><td>需要话题群 fixture，或由 IM 同学提供当前账号可访问 topicId。</td></tr>
+<tr><td><code>aitable +dashboard-share-get</code></td><td><span class="cat">真实资源仍失败</span></td><td>已有真实 base/dashboard，但 share-get 返回 404 `Failed to get dashboard share config`；更像分享配置未开启或后端接口行为问题。</td><td>需要 AI 表格/后端确认如何创建/开启 dashboard share fixture，或修正 404 语义。</td></tr>
+<tr><td><code>write 类 delete/recall/approve/wiki move/copy 等</code></td><td><span class="cat">不自动自造</span></td><td>这些命令即便能造资源，也会涉及删除、撤回、审批通过、知识库移动/复制等高影响动作。</td><td>需要逐项授权和专门测试空间/机器人/审批单据，不建议混在批量回归里自动跑。</td></tr></tbody>
+</table>
+
+
+<h2>Read 失败逐项 <span class="count">· 42 条</span></h2>
+<table class="review">
+<thead><tr>
+<th>#</th><th>命令</th><th>风险</th><th>类型</th><th>要改哪里</th><th>具体改法</th><th>验证方式</th><th>operation</th><th>trace_id</th><th>证据</th>
+</tr></thead>
+<tbody>
+<tr><td class="num">1</td><td><code>aitable +base-get-primary-doc-id</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;-1&quot;,&quot;message&quot;:&quot;no record&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to query cell doc for record 1015oH3OXy in table…</td></tr>
+<tr><td class="num">2</td><td><code>aitable +chart-share-get</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `aitable +chart-share-get`；若仍是 permission，再看 trace_id。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;403&quot;,&quot;message&quot;:&quot;Forbidden&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;AUTH_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get chart share config for chart widget-dlxFo…</td></tr>
+<tr><td class="num">3</td><td><code>aitable +dashboard-share-get</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `aitable +dashboard-share-get`。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;404&quot;,&quot;message&quot;:&quot;Not Found&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get dashboard share config for dashboard KY9…</td></tr>
+<tr><td class="num">4</td><td><code>aitable +export-data</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;taskId cannot be combined with scope, format, tableId or viewId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,…</td></tr>
+<tr><td class="num">5</td><td><code>aitable +record-primary-doc-get</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;-1&quot;,&quot;message&quot;:&quot;no record&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to query cell doc for record 1015oH3OXy in table…</td></tr>
+<tr><td class="num">6</td><td><code>aitable +role-get</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;roleId is required&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get role because roleId …</td></tr>
+<tr><td class="num">7</td><td><code>aitable +workflow-get</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;GET_WORKFLOW_ERROR&quot;,&quot;message&quot;:&quot;调用远程服务业务异常&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get workflow in base &#x27;gpG2Nd…</td></tr>
+<tr><td class="num">8</td><td><code>aitable +workflow-list</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;LIST_WORKFLOWS_ERROR&quot;,&quot;message&quot;:&quot;biz error&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to list workflows in base &#x27;gpG…</td></tr>
+<tr><td class="num">9</td><td><code>attendance +get-class</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实考勤班次/考勤组/员工/假期等资源 ID；当前 no-such ID 只能验证负向路径。</td><td>先用考勤列表/管理后台拿真实 ID，再重跑该 attendance 命令。</td><td><code>tools/call</code></td><td><code>2127d89817840997588238831e0757</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/get_class_detail) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">10</td><td><code>attendance +get-global-setting</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `attendance +get-global-setting`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840997604718062e085e</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/query_global_setting) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">11</td><td><code>attendance +get-group</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实考勤班次/考勤组/员工/假期等资源 ID；当前 no-such ID 只能验证负向路径。</td><td>先用考勤列表/管理后台拿真实 ID，再重跑该 attendance 命令。</td><td><code>tools/call</code></td><td><code>0b5deb3217840997620512305e08ef</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/get_group_detail) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">12</td><td><code>attendance +get-group-filtered</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实考勤班次/考勤组/员工/假期等资源 ID；当前 no-such ID 只能验证负向路径。</td><td>先用考勤列表/管理后台拿真实 ID，再重跑该 attendance 命令。</td><td><code>tools/call</code></td><td><code>2104a64c17840997638062468e08c7</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/get_group_filtered_detail) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">13</td><td><code>attendance +get-leave-balance</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `attendance +get-leave-balance` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2104a64c17840997652901307e081a</code></td><td class="evidence">[UNCLASSIFIED] 亲，假期类型没有余额 (operation: attendance-wukong/get_leave_balance_quota) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">14</td><td><code>attendance +list-report-columns</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `attendance +list-report-columns`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2127d89817840997666188472e0756</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/get_report_columns) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">15</td><td><code>attendance +query-report-leave</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `attendance +query-report-leave`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840997679973065e085f</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/get_leave_time_by_leave_names) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">16</td><td><code>calendar +find-room</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入</span></td><td>会议室类命令需要真实 roomId 或更小会议室分组；修改 runner 先定位会议室/分组，再喂给查询命令。</td><td>用真实 roomId/分组重跑 calendar room/freebusy 命令。</td><td><code>tools/call</code></td><td><code>0bb7c36217840997694975303e0758</code></td><td class="evidence">[UNCLASSIFIED] 查询范围内的会议室数量，超过上限100，请选择更小范围的分组进行查询。 hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">17</td><td><code>calendar +room-find</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入</span></td><td>会议室类命令需要真实 roomId 或更小会议室分组；修改 runner 先定位会议室/分组，再喂给查询命令。</td><td>用真实 roomId/分组重跑 calendar room/freebusy 命令。</td><td><code>tools/call</code></td><td><code>2104a64c17840997709913005e0819</code></td><td class="evidence">[UNCLASSIFIED] 查询范围内的会议室数量，超过上限100，请选择更小范围的分组进行查询。 (operation: calendar/query_available_meeting_room) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">18</td><td><code>chat +category-list-conversations</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `chat +category-list-conversations` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0bb7c36217840997724375834e0758</code></td><td class="evidence">[UNCLASSIFIED] listConversationsByCategoryV2 error hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">19</td><td><code>chat +chat-get-by-id</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +chat-get-by-id`。</td><td><code>tools/call</code></td><td><code>2127d89817840997739165535e07bd</code></td><td class="evidence">[UNCLASSIFIED] verifyGroupId error: The group id does not exit (operation: im/get_conv_info_by_group_id) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">20</td><td><code>chat +chat-members-get</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840997754345760e07bd</code></td><td class="evidence">[UNCLASSIFIED] openCid or cid is required (operation: im/list_group_member_by_ids) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">21</td><td><code>chat +chat-messages</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840997767792656e085e</code></td><td class="evidence">[UNCLASSIFIED] openCid or cid is required hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">22</td><td><code>chat +messages-list</code></td><td><span class="risk">read</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840997797873841e0757</code></td><td class="evidence">[UNCLASSIFIED] openCid or cid is required hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">23</td><td><code>chat +messages-resource-url</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +messages-resource-url`。</td><td><code>tools/call</code></td><td><code>2127d89817840997855423145e07dd</code></td><td class="evidence">[UNCLASSIFIED] failed to get download url for resourceId: x (operation: im/get_resource_download_url) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">24</td><td><code>chat +search-msg</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>tools/call</code></td><td><code>0b5deb3217840997866824643e0853</code></td><td class="evidence">[UNCLASSIFIED] 当前用户暂无消息搜索权益，无法执行本次搜索。请提示用户开通消息搜索权益后重试。 hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">25</td><td><code>chat +thread-replies</code></td><td><span class="risk">read</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +thread-replies`。</td><td><code>tools/call</code></td><td><code>0b5deb3217840997883504915e0853</code></td><td class="evidence">[UNCLASSIFIED] failed to decrypt openConvThreadId hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">26</td><td><code>contact +get-roster</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `contact +get-roster`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2106d98117840997920166915e087b</code></td><td class="evidence">[UNCLASSIFIED] 操作人无花名册管理权限 (operation: hrmregister/get_authorized_emp_rosterInfo) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">27</td><td><code>contact +list-roster-fields</code></td><td><span class="risk">read</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `contact +list-roster-fields`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>213ee25c17840997934295673e08e2</code></td><td class="evidence">[UNCLASSIFIED] 操作人无花名册管理权限 (operation: hrmregister/list_authorized_roster_fields) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">28</td><td><code>devapp +credentials-get</code></td><td><span class="risk">read</span></td><td><span class="cat">敏感/高风险暂缓</span></td><td><span class="owner">人工安全确认</span></td><td>该项涉及敏感读取或无安全负向目标，不适合自动用真实资源跑；需要在安全环境逐项人工确认。</td><td>人工确认后单独重跑 `devapp +credentials-get`，并避免在报告中泄露密钥/凭证。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">该命令会读取真实应用凭证/密钥；不能用真实 app 自动执行。当前仅用占位 ID 验证负向路径，真实成功需人工在安全环境单独确认。</td></tr>
+<tr><td class="num">29</td><td><code>drive +download</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `drive +download` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0bab027317840997956923965e08c9</code></td><td class="evidence">[UNCLASSIFIED] 该文件类型不支持通过 download_file 下载。download_file 仅支持普通文件（如 PDF、Word、Excel 等），不支持钉钉在线文档/表格/脑图等在线编辑类型。如需导出在线文档内容，请使用钉钉文档导出相关接口。 (operation: drive/download_file) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">30</td><td><code>drive +list</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `drive +list` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2106d98117840997968627612e087b</code></td><td class="evidence">[UNCLASSIFIED] parentId 不属于指定的 spaceId，请确认 parentId 和 spaceId 属于同一个钉盘空间。 hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">31</td><td><code>minutes +action-items</code></td><td><span class="risk">read</span></td><td><span class="cat">缺妙记 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备当前账号可见的真实妙记/听记/录制会话，或把 runner 的搜索关键词改成必然能命中的会议产物。</td><td>用真实 taskUuid/note/minutes 资源重跑 minutes 命令。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">暂无妙记</td></tr>
+<tr><td class="num">32</td><td><code>minutes +latest-minutes</code></td><td><span class="risk">read</span></td><td><span class="cat">缺妙记 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备当前账号可见的真实妙记/听记/录制会话，或把 runner 的搜索关键词改成必然能命中的会议产物。</td><td>用真实 taskUuid/note/minutes 资源重跑 minutes 命令。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">暂无妙记</td></tr>
+<tr><td class="num">33</td><td><code>minutes +minutes-search</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没搜到妙记</td></tr>
+<tr><td class="num">34</td><td><code>minutes +transcript</code></td><td><span class="risk">read</span></td><td><span class="cat">缺妙记 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备当前账号可见的真实妙记/听记/录制会话，或把 runner 的搜索关键词改成必然能命中的会议产物。</td><td>用真实 taskUuid/note/minutes 资源重跑 minutes 命令。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">暂无妙记</td></tr>
+<tr><td class="num">35</td><td><code>oa +done-approvals</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没有已处理的审批记录</td></tr>
+<tr><td class="num">36</td><td><code>oa +pending</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">当前没有待我审批的任务</td></tr>
+<tr><td class="num">37</td><td><code>report +report-latest</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">暂无日志</td></tr>
+<tr><td class="num">38</td><td><code>todo +due-today</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">今天没有到期的待办</td></tr>
+<tr><td class="num">39</td><td><code>todo +related-tasks</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没有与你相关的待办（creator/executor/participant 三种角色下均为空）</td></tr>
+<tr><td class="num">40</td><td><code>wiki +node-list</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2132f5ca17840998189126304e08d9</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">41</td><td><code>wiki +resolve-space</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试数据</span></td><td>准备能命中的真实数据，或把 runner 查询词改成当前账号一定存在的对象；shortcut 本身不需要改。</td><td>造数后重跑，预期从 validation empty result 变为成功。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没有找到名称包含 DWS shortcut 真实测试 的知识空间</td></tr>
+<tr><td class="num">42</td><td><code>wiki +space-list</code></td><td><span class="risk">read</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `wiki +space-list` 并比较 stdout/stderr。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">参数 --type 取值 &quot;ALL&quot; 不合法，允许值：orgWikiSpace, myWikiSpace</td></tr>
+</tbody>
+</table>
+
+
+<h2>Write 失败逐项 <span class="count">· 114 条</span></h2>
+<table class="review">
+<thead><tr>
+<th>#</th><th>命令</th><th>风险</th><th>类型</th><th>要改哪里</th><th>具体改法</th><th>验证方式</th><th>operation</th><th>trace_id</th><th>证据</th>
+</tr></thead>
+<tbody>
+<tr><td class="num">1</td><td><code>aitable +advperm-disable</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `aitable +advperm-disable`；若仍是 permission，再看 trace_id。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to set adv…</td></tr>
+<tr><td class="num">2</td><td><code>aitable +advperm-enable</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `aitable +advperm-enable`；若仍是 permission，再看 trace_id。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to set adv…</td></tr>
+<tr><td class="num">3</td><td><code>aitable +attachment-upload</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;BASE_NOT_FOUND&quot;,&quot;message&quot;:&quot;Specified base does not exist, has been deleted, or is inaccessible&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:t…</td></tr>
+<tr><td class="num">4</td><td><code>aitable +base-copy</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:null,&quot;message&quot;:&quot;Invalid source baseId: DWSREALTESTNOSUCHID0000000000000&quot;,&quot;retryable&quot;:null,&quot;type&quot;:&quot;USER_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Invalid sou…</td></tr>
+<tr><td class="num">5</td><td><code>aitable +base-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `aitable +base-delete`。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;52600003&quot;,&quot;message&quot;:&quot;Data not found&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete base DWSREALTESTNOSUCHID000…</td></tr>
+<tr><td class="num">6</td><td><code>aitable +base-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;BASE_NOT_FOUND&quot;,&quot;message&quot;:&quot;Specified base does not exist, has been deleted, or is inaccessible&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:t…</td></tr>
+<tr><td class="num">7</td><td><code>aitable +chart-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete …</td></tr>
+<tr><td class="num">8</td><td><code>aitable +chart-share-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">9</td><td><code>aitable +chart-update</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;config is required&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update chart because con…</td></tr>
+<tr><td class="num">10</td><td><code>aitable +dashboard-arrange</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to align d…</td></tr>
+<tr><td class="num">11</td><td><code>aitable +dashboard-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete …</td></tr>
+<tr><td class="num">12</td><td><code>aitable +dashboard-share-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">13</td><td><code>aitable +dashboard-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">14</td><td><code>aitable +field-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;404&quot;,&quot;message&quot;:&quot;getDentryDTO returns null&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get current field info befor…</td></tr>
+<tr><td class="num">15</td><td><code>aitable +field-update</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;404&quot;,&quot;message&quot;:&quot;getDentryDTO returns null&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to get current field info for u…</td></tr>
+<tr><td class="num">16</td><td><code>aitable +form-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete …</td></tr>
+<tr><td class="num">17</td><td><code>aitable +form-field-hide</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">18</td><td><code>aitable +form-field-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">19</td><td><code>aitable +form-share-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">20</td><td><code>aitable +form-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">21</td><td><code>aitable +import-data</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `aitable +import-data`。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_IMPORT_ID&quot;,&quot;message&quot;:&quot;importId not found: either invalid or expired&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;impo…</td></tr>
+<tr><td class="num">22</td><td><code>aitable +import-upload</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;无法解析 baseId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;无效的 baseId&quot;,&quot;trace_id&quot;:&quot;0bab027317840998…</td></tr>
+<tr><td class="num">23</td><td><code>aitable +record-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;404&quot;,&quot;message&quot;:&quot;getDentryDTO returns null&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete records&quot;,&quot;trace_id&quot;:&quot;…</td></tr>
+<tr><td class="num">24</td><td><code>aitable +record-primary-doc-create</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;RESOLVE_DOC_ID_ERROR&quot;,&quot;message&quot;:&quot;Failed to resolve docId from baseId&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to c…</td></tr>
+<tr><td class="num">25</td><td><code>aitable +record-update</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_RECORDS&quot;,&quot;message&quot;:&quot;records must contain at least one writable record&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Fa…</td></tr>
+<tr><td class="num">26</td><td><code>aitable +record-upsert</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMETER&quot;,&quot;message&quot;:&quot;records is required and must not be empty&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;records …</td></tr>
+<tr><td class="num">27</td><td><code>aitable +role-create</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to create …</td></tr>
+<tr><td class="num">28</td><td><code>aitable +role-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;roleId is required&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete role because role…</td></tr>
+<tr><td class="num">29</td><td><code>aitable +role-update</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;roleId is required&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to patch role because roleI…</td></tr>
+<tr><td class="num">30</td><td><code>aitable +section-create</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to create …</td></tr>
+<tr><td class="num">31</td><td><code>aitable +section-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete …</td></tr>
+<tr><td class="num">32</td><td><code>aitable +section-move-node</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to move no…</td></tr>
+<tr><td class="num">33</td><td><code>aitable +section-rename</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to rename …</td></tr>
+<tr><td class="num">34</td><td><code>aitable +section-reorder</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to reorder…</td></tr>
+<tr><td class="num">35</td><td><code>aitable +table-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;BASE_NOT_FOUND&quot;,&quot;message&quot;:&quot;Specified base does not exist, has been deleted, or is inaccessible&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:t…</td></tr>
+<tr><td class="num">36</td><td><code>aitable +table-update</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;404&quot;,&quot;message&quot;:&quot;getDentryDTO returns null&quot;,&quot;retryable&quot;:true,&quot;type&quot;:&quot;SYSTEM_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update table DWSREALTESTNOSU…</td></tr>
+<tr><td class="num">37</td><td><code>aitable +view-delete</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to delete …</td></tr>
+<tr><td class="num">38</td><td><code>aitable +view-duplicate</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to duplica…</td></tr>
+<tr><td class="num">39</td><td><code>aitable +view-lock</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to lock_or…</td></tr>
+<tr><td class="num">40</td><td><code>aitable +view-set-fill-color-rule</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>修 aitable MCP wrapper 的参数校验和错误语义：不要返回 success=true+error；对 required 字段给出 CLI 可识别的参数名，系统错误要带 retryable/trace。</td><td>MCP 修完后重跑该 aitable 命令，并确认 stdout JSON 不再出现 success=true 但 error 非空。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_PARAMS&quot;,&quot;message&quot;:&quot;conditionalFormats is required&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to set fill col…</td></tr>
+<tr><td class="num">41</td><td><code>aitable +view-set-frozen-cols</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to set fro…</td></tr>
+<tr><td class="num">42</td><td><code>aitable +view-set-row-height</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to set cel…</td></tr>
+<tr><td class="num">43</td><td><code>aitable +view-update</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;INVALID_BASE_ID&quot;,&quot;message&quot;:&quot;baseId cannot be resolved to docId&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;status&quot;:&quot;error&quot;,&quot;success&quot;:true,&quot;summary&quot;:&quot;Failed to update …</td></tr>
+<tr><td class="num">44</td><td><code>aitable +workflow-disable</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;BASE_NOT_FOUND&quot;,&quot;message&quot;:&quot;Cannot resolve base &#x27;DWSREALTESTNOSUCHID0000000000000&#x27;, please check if the baseId is valid&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;sta…</td></tr>
+<tr><td class="num">45</td><td><code>aitable +workflow-enable</code></td><td><span class="risk">write</span></td><td><span class="cat">缺 AI 表格 fixture</span></td><td><span class="owner">测试数据</span></td><td>准备真实 Base/Table/View/Field/Record/Role/Chart/Dashboard 等 fixture，并把真实 ID 写入真实测试 runner；当前安全负向 ID 只能证明调用链，不可能成功。</td><td>fixture 准备好后重跑对应 aitable 命令；预期从 not_found/invalid_base_id 变为成功或更具体业务错误。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">[MCP_TOOL_ERROR] {&quot;data&quot;:{},&quot;error&quot;:{&quot;code&quot;:&quot;BASE_NOT_FOUND&quot;,&quot;message&quot;:&quot;Cannot resolve base &#x27;DWSREALTESTNOSUCHID0000000000000&#x27;, please check if the baseId is valid&quot;,&quot;retryable&quot;:false,&quot;type&quot;:&quot;INPUT_ERROR&quot;},&quot;meta&quot;:{},&quot;sta…</td></tr>
+<tr><td class="num">46</td><td><code>attendance +boss-check</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>213ee25c17840998998942184e087d</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/boss_check) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">47</td><td><code>attendance +create-class</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>0bab027317840999009926838e090b</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/create_class_setting) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">48</td><td><code>attendance +create-group</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2106d98117840999021121258e08b8</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/create_group_setting) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">49</td><td><code>attendance +import-schedule</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2104a64c17840999034845189e085e</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/generateTurnSchedule) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">50</td><td><code>attendance +save-leave-balance</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `attendance +save-leave-balance`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2127d89817840999045751134e079c</code></td><td class="evidence">[UNCLASSIFIED] 无权更新指定员工的假期余额 (operation: attendance-wukong/update_leave_balance) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">51</td><td><code>attendance +update-class</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999058236471e08b5</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/update_class_setting) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">52</td><td><code>attendance +update-group</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999068826691e087a</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/update_group_setting) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">53</td><td><code>attendance +update-group-members</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2127d89817840999081094644e07dd</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: attendance-wukong/update_group_member) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">54</td><td><code>attendance +update-leave-type</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `attendance +update-leave-type`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999093924897e07fe</code></td><td class="evidence">[RESOURCE_NOT_FOUND] Requested resource not found (operation: attendance-wukong/save_leave_type) hint: Check if the resource exists or if your account has permission</td></tr>
+<tr><td class="num">55</td><td><code>calendar +respond-event</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `calendar +respond-event`。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999105062121e07db</code></td><td class="evidence">[UNCLASSIFIED] code: 300000, developerMessage: Event does not exist. (operation: calendar/respond) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">56</td><td><code>chat +category-add-conversation</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `chat +category-add-conversation`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999117776203e08f9</code></td><td class="evidence">[RESOURCE_NOT_FOUND] Requested resource not found (operation: im/add_conv_to_categories) hint: Check if the resource exists or if your account has permission</td></tr>
+<tr><td class="num">57</td><td><code>chat +category-remove-conversation</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `chat +category-remove-conversation`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999130466520e085e</code></td><td class="evidence">[RESOURCE_NOT_FOUND] Requested resource not found (operation: im/remove_conv_from_categories) hint: Check if the resource exists or if your account has permission</td></tr>
+<tr><td class="num">58</td><td><code>chat +chat-add-bot</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `chat +chat-add-bot`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999144193460e08c7</code></td><td class="evidence">[RESOURCE_NOT_FOUND] Requested resource not found (operation: bot/add_robot_to_group) hint: Check if the resource exists or if your account has permission</td></tr>
+<tr><td class="num">59</td><td><code>chat +chat-audit-join</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999154832733e0758</code></td><td class="evidence">[UNCLASSIFIED] applicantUid is required (operation: im/audit_join_group) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">60</td><td><code>chat +chat-mute-member</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840999166036583e08a3</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/set_group_member_mute_list) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">61</td><td><code>chat +chat-quit</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `chat +chat-quit` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999176728426e0779</code></td><td class="evidence">[UNCLASSIFIED] listBaseConversationByIds error (operation: im/quit_group) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">62</td><td><code>chat +chat-remove-bot</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +chat-remove-bot`。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999189888305e08b5</code></td><td class="evidence">[UNCLASSIFIED] 无效的会话 (operation: bot/remove_robot_in_group) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">63</td><td><code>chat +chat-role-remove</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `chat +chat-role-remove` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2127d89817840999200483204e079c</code></td><td class="evidence">[UNCLASSIFIED] listBaseConversationByIds error (operation: im/remove_custom_group_role) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">64</td><td><code>chat +chat-role-remove-user</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `chat +chat-role-remove-user` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2127d89817840999211317952e0757</code></td><td class="evidence">[UNCLASSIFIED] listBaseConversationByIds error (operation: im/remove_custom_user_roles) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">65</td><td><code>chat +chat-transfer-owner</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999222318863e087a</code></td><td class="evidence">[UNCLASSIFIED] openConversationId is required (operation: im/transfer_group_owner) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">66</td><td><code>chat +chat-update-icon</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `chat +chat-update-icon` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2104a64c17840999232478654e0819</code></td><td class="evidence">[UNCLASSIFIED] listBaseConversationByIds error (operation: im/update_group_icon) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">67</td><td><code>chat +chat-update-settings</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/shortcut 枚举</span></td><td>把测试输入的 setting-key 从 x 改为后端支持的 key；同时可在 shortcut flag 上补 enum，避免用户传非法 key。</td><td>改 runner 后重跑；如果补 enum，跑 shortcut 单测确认校验文案。</td><td><code>tools/call</code></td><td><code>2127d89817840999244326971e07dd</code></td><td class="evidence">[UNCLASSIFIED] unsupported setting key: x (operation: im/update_group_settings) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">68</td><td><code>chat +conversation-clear-messages</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840999254816721e079b</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/clear_conversation_messages) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">69</td><td><code>chat +conversation-clear-red-point</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840999265511295e085f</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/clear_conversation_red_point) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">70</td><td><code>chat +conversation-hide</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840999276117140e079b</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/hide_conversation) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">71</td><td><code>chat +conversation-mark-read</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为当前账号真实可访问的群/会话 openConversationId；如果用真实群仍报“无效”，再查 IM 后端解析。</td><td>先用 `chat +my-groups` 或群搜索拿真实会话 ID，再重跑。</td><td><code>tools/call</code></td><td><code>2127d89817840999287654280e07bd</code></td><td class="evidence">[UNCLASSIFIED] openConversationId无效，无法解析为cid (operation: im/mark_message_read) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">72</td><td><code>chat +conversation-mark-unread</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999298744910e0758</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/mark_conversation_unread) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">73</td><td><code>chat +conversation-mute</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840999309241865e085f</code></td><td class="evidence">[UNCLASSIFIED] openConversationId is required (operation: im/update_notification_off) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">74</td><td><code>chat +conversation-mute-at-all</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840999320028068e07dd</code></td><td class="evidence">[UNCLASSIFIED] openConversationId is required (operation: im/update_at_all_notification_off) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">75</td><td><code>chat +conversation-mute-red-envelope</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999330228283e07fe</code></td><td class="evidence">[UNCLASSIFIED] openConversationId is required (operation: im/update_red_env_notification_off) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">76</td><td><code>chat +conversation-set-top</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2127d89817840999341302961e07fe</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/set_top_conversation) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">77</td><td><code>chat +messages-add-emoji</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>2127d89817840999352941910e0756</code></td><td class="evidence">[UNCLASSIFIED] invalid openMsgId: DWSREALTESTNOSUCHID0000000000000 (operation: im/add_emoji_reaction) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">78</td><td><code>chat +messages-add-text-emotion</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999362862711e08b5</code></td><td class="evidence">[UNCLASSIFIED] invalid openMsgId: DWSREALTESTNOSUCHID0000000000000 (operation: im/add_text_emotion) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">79</td><td><code>chat +messages-batch-recall-by-bot</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +messages-batch-recall-by-bot`。</td><td><code>tools/call</code></td><td><code>2104a64c17840999373456305e0817</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: bot/batch_recall_robot_users_msg) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">80</td><td><code>chat +messages-batch-send-by-bot</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +messages-batch-send-by-bot`。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999385748776e0757</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: bot/batch_send_robot_msg_to_users) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">81</td><td><code>chat +messages-combine-forward</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为当前账号真实可访问的群/会话 openConversationId；如果用真实群仍报“无效”，再查 IM 后端解析。</td><td>先用 `chat +my-groups` 或群搜索拿真实会话 ID，再重跑。</td><td><code>tools/call</code></td><td><code>2104a64c17840999396596163e08ee</code></td><td class="evidence">[UNCLASSIFIED] srcOpenCid无效，无法解析为cid (operation: im/combine_forward_messages) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">82</td><td><code>chat +messages-create-text-emotion</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务规则</span></td><td>换成后端支持的文字表情组合，或把该命令保留为业务负向；CLI 不应绕过后端限制。</td><td>用一个真实可保存的表情模板重跑。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999407422891e08cd</code></td><td class="evidence">[UNCLASSIFIED] 暂不支持保存该文字表情 (operation: im/create_text_emotion) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">83</td><td><code>chat +messages-forward</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>2104a64c17840999417966407e08ee</code></td><td class="evidence">[UNCLASSIFIED] openMessageId解密失败 (operation: im/forward_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">84</td><td><code>chat +messages-forward-topic</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>2127d89817840999428541474e07dd</code></td><td class="evidence">[UNCLASSIFIED] openMessageId解密失败 (operation: im/forward_topic) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">85</td><td><code>chat +messages-recall</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为当前账号真实可访问的群/会话 openConversationId；如果用真实群仍报“无效”，再查 IM 后端解析。</td><td>先用 `chat +my-groups` 或群搜索拿真实会话 ID，再重跑。</td><td><code>tools/call</code></td><td><code>2104a64c17840999441138103e08c7</code></td><td class="evidence">[UNCLASSIFIED] openConversationId无效，无法解析为cid (operation: im/recall_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">86</td><td><code>chat +messages-recall-by-bot</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2104a64c17840999454382709e08a3</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: bot/recall_robot_group_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">87</td><td><code>chat +messages-remove-emoji</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999467733059e08f9</code></td><td class="evidence">[UNCLASSIFIED] invalid openMsgId: DWSREALTESTNOSUCHID0000000000000 (operation: im/remove_emoji_reaction) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">88</td><td><code>chat +messages-remove-text-emotion</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999478923406e087f</code></td><td class="evidence">[UNCLASSIFIED] invalid openMsgId: DWSREALTESTNOSUCHID0000000000000 (operation: im/remove_text_emotion) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">89</td><td><code>chat +messages-send-by-bot</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `chat +messages-send-by-bot`。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999494005921e08ef</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: bot/send_robot_group_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">90</td><td><code>chat +messages-send-card</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840999509255753e081a</code></td><td class="evidence">[UNCLASSIFIED] receiverUid和openConversationId不能同时为空 (operation: im/create_and_send_card) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">91</td><td><code>chat +messages-set-pin</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999521117991e0758</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/set_pin_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">92</td><td><code>chat +messages-set-top</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>2104a64c17840999532438476e0817</code></td><td class="evidence">[UNCLASSIFIED] openMessageId解密失败 (operation: im/set_top_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">93</td><td><code>chat +messages-unset-pin</code></td><td><span class="risk">write</span></td><td><span class="cat">后端/MCP</span></td><td><span class="owner">后端/MCP schema</span></td><td>CLI fake MCP 已证明字段已装配；需要修 MCP tool schema 或网关字段映射，确认 openConversationId/openCid/cid、receiverUid、applicantUid 等字段没有在 schema 校验/转发时被丢弃。</td><td>修 MCP 后不改 shortcut，直接重跑真实命令；预期错误从 required 变为资源无效或成功。</td><td><code>tools/call</code></td><td><code>2104a64c17840999544428103e08ee</code></td><td class="evidence">[UNCLASSIFIED] openConversationId or cid is required (operation: im/unset_pin_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">94</td><td><code>chat +messages-unset-top</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实 openMessageId，并保证消息属于当前账号可访问会话；当前 no-such ID 只能验证负向路径。</td><td>先用消息列表拿 messageId，再重跑消息详情/状态/撤回类命令。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999554154221e08f9</code></td><td class="evidence">[UNCLASSIFIED] openMessageId解密失败 (operation: im/unset_top_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">95</td><td><code>devapp +event-subscribe</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +event-subscribe`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999564022020e08c7</code></td><td class="evidence">[UNCLASSIFIED] 当前用户没有应用事件订阅权限 (operation: devapp/subscribe_dev_app_events) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">96</td><td><code>devapp +event-unsubscribe</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +event-unsubscribe`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999575698500e07db</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/unsubscribe_dev_app_events) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">97</td><td><code>devapp +permission-add</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +permission-add`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2127d89817840999587758457e079c</code></td><td class="evidence">[UNCLASSIFIED] 当前用户没有开发者身份 (operation: devapp/apply_dev_app_permissions) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">98</td><td><code>devapp +permission-remove</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +permission-remove`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999598445247e085e</code></td><td class="evidence">[UNCLASSIFIED] 当前用户没有开发者身份 (operation: devapp/remove_dev_app_permissions) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">99</td><td><code>devapp +robot-config</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +robot-config`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999609828961e07db</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/set_extension_robot_config) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">100</td><td><code>devapp +robot-disable</code></td><td><span class="risk">high-risk-write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +robot-disable`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999620461113e08ee</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/disable_dev_app_robot) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">101</td><td><code>devapp +robot-enable</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +robot-enable`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999632641525e0758</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/enable_dev_app_robot) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">102</td><td><code>devapp +security-config</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `devapp +security-config`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2104a64c17840999645522046e0817</code></td><td class="evidence">[UNCLASSIFIED] 当前用户没有开发者身份 (operation: devapp/update_dev_app_security_config) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">103</td><td><code>devapp +version-create</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999656705920e0853</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/create_dev_app_version) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">104</td><td><code>devapp +version-publish</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">后端业务/测试 fixture</span></td><td>后端只返回 success=false，信息不足；先准备真实合法 fixture，若仍无细节，需要后端补充错误码/错误信息。</td><td>用真实资源重跑；若仍 success=false，把 operation+trace_id 给后端。</td><td><code>tools/call</code></td><td><code>2127d89817840999667906017e075d</code></td><td class="evidence">[UNCLASSIFIED] business error: success=false (operation: devapp/publish_dev_app_version) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">105</td><td><code>ding +send-by-message</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `ding +send-by-message` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0b5deb3217840999678466213e0853</code></td><td class="evidence">[UNCLASSIFIED] remindType非法，合法值：APP/SMS/PHONE (operation: im/send_ding_by_message) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">106</td><td><code>doc +comment-create-inline</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实文档/节点 ID；文档评论、分享、版本等命令需要资源存在且账号可访问。</td><td>用真实 doc/node 重跑；若仍失败再看 doc/doc-comment 工具字段。</td><td><code>tools/call</code></td><td><code>2127d89817840999689931893e079c</code></td><td class="evidence">[TABLE_NOT_FOUND] Requested resource not found (operation: doc-comment/create_inline_comment) hint: Document may have been deleted or moved</td></tr>
+<tr><td class="num">107</td><td><code>doc +template-apply</code></td><td><span class="risk">write</span></td><td><span class="cat">鉴权/权限</span></td><td><span class="owner">权限/应用配置</span></td><td>给当前登录账号、DWS 应用或对应资源补齐权限/scope；本仓库 shortcut 不应绕过权限。拿 trace_id 给服务端/开放平台排查具体 scope。</td><td>补权限后重跑 `doc +template-apply`；若仍是 permission，再看 trace_id。</td><td><code>tools/call</code></td><td><code>2127d89817840999701186954e0757</code></td><td class="evidence">[RESOURCE_NOT_FOUND] Requested resource not found (operation: doc/apply_doc_template) hint: Check if the resource exists or if your account has permission</td></tr>
+<tr><td class="num">108</td><td><code>minutes +record-pause</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `minutes +record-pause` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999713124987e0757</code></td><td class="evidence">[UNCLASSIFIED] aiAgentTestRunCmdUnknownError (operation: minutes/执行听记指令-发起AI听记录音) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">109</td><td><code>minutes +record-resume</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `minutes +record-resume` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999724452848e0758</code></td><td class="evidence">[UNCLASSIFIED] aiAgentTestRunCmdUnknownError (operation: minutes/执行听记指令-发起AI听记录音) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">110</td><td><code>minutes +record-stop</code></td><td><span class="risk">write</span></td><td><span class="cat">输入/业务校验</span></td><td><span class="owner">测试输入/业务校验</span></td><td>当前命令已进入后端业务校验；先把测试输入换成真实合法 fixture，再判断是否需要改 shortcut。</td><td>重跑 `minutes +record-stop` 并比较 stdout/stderr。</td><td><code>tools/call</code></td><td><code>2127d89817840999735397508e0757</code></td><td class="evidence">[UNCLASSIFIED] aiAgentTestRunCmdUnknownError (operation: minutes/执行听记指令-发起AI听记录音) hint: Use --verbose for detailed error logs</td></tr>
+<tr><td class="num">111</td><td><code>oa +approve-by</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `oa +approve-by`。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没找到待审批单据：待我处理的审批里没有标题/单号包含 &quot;__DWS_SHORTCUT_REAL_TEST_NO_SUCH_APPROVAL_20260715-151724__&quot; 的单据。</td></tr>
+<tr><td class="num">112</td><td><code>wiki +node-copy</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实文档/节点 ID；文档评论、分享、版本等命令需要资源存在且账号可访问。</td><td>用真实 doc/node 重跑；若仍失败再看 doc/doc-comment 工具字段。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999769818495e0779</code></td><td class="evidence">[TABLE_NOT_FOUND] Requested resource not found (operation: doc/copy_document) hint: Document may have been deleted or moved</td></tr>
+<tr><td class="num">113</td><td><code>wiki +node-move</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>替换为真实文档/节点 ID；文档评论、分享、版本等命令需要资源存在且账号可访问。</td><td>用真实 doc/node 重跑；若仍失败再看 doc/doc-comment 工具字段。</td><td><code>tools/call</code></td><td><code>0bb7c36217840999780286509e07fe</code></td><td class="evidence">[TABLE_NOT_FOUND] Requested resource not found (operation: doc/move_document) hint: Document may have been deleted or moved</td></tr>
+<tr><td class="num">114</td><td><code>wiki +wiki-new-doc</code></td><td><span class="risk">write</span></td><td><span class="cat">缺真实资源</span></td><td><span class="owner">测试数据</span></td><td>把 runner 里的安全负向 ID 换成真实资源 ID；当前错误说明调用已进后端，但资源不存在。</td><td>准备 fixture 后重跑 `wiki +wiki-new-doc`。</td><td><code>-</code></td><td><code>-</code></td><td class="evidence">没找到名为 &quot;__DWS_SHORTCUT_REAL_TEST_NO_SUCH_SPACE__&quot; 的知识库；换个更完整/精确的空间名再试。</td></tr>
+</tbody>
+</table>
+
+</main>
+</body>
+</html>

docs/shortcut-handoff.md

@@ -0,0 +1,223 @@
+# DWS Shortcut — 方法论与进展交接文档（换会话续跑用）
+
+> 目的：换新会话直接照此续跑。记录**方法论、已完成进展、如何继续、关键坑位、验证命令**。
+> 分支：`feature/shortcut`（**改动全部未提交**，commit 由用户主动决定）。
+
+---
+
+## 0. 一句话现状
+
+> 2026-07-09 **去冗余（重大修订）**：复盘发现 `internal/helpers/` 早有 ~697 个 `dws <svc> <verb>` 产品命令封装了 281 个 tool；1:1 shortcut 层有 235 个 tool 与之重复。按「tool 已被 helper 封装 且 shortcut 用 CallMCP 无投影」精确删除 **213 条纯重复 shortcut**，1:1 层 511→298、总数 579→366、服务 19→16（aisearch/live/devdoc 整包移除，其 dws 命令仍由 helper 提供）。全绿+真机复验保留命令可用。**教训：建封装层前先审已有封装。**
+
+
+在 `internal/shortcut/` 下建成一套声明式 shortcut 体系：**366 条命令 = 298 条 1:1 封装 + 68 条真·智能编排**（1:1 层原 511，已删 213 条纯重复——helper 层早已封装同一批 tool），另有 **~60 条封装升级到 lark 输出投影保真度**、P2 高频自动沉淀闭环、深度对齐 lark 矩阵。**全绿**（build/gofmt/vet/shortcut 全量测试 `shortcuts=366 assembled=322 validated=44 failed=0`/app 全量回归 72s/真机抽验）。
+
+> 2026-07-09 批33（净新增 1 条·+conflicts 的互补品）：`calendar +free-slots`（找某天工作时段内的空闲时段，list_calendar_events + 合并忙碌区间 + 工作窗口求补集，默认今天 09:00-18:00/--from/--to/--in-days）。真机验证：今日 4 段空档（09:00-09:15/15min、12:00-13:30/90min、14:00-14:30/30min、16:00-17:15/75min），正是忙碌事件的精确补集。conflicts+free-slots 构成真实排期智能。总数 578→579、smart 67→68。全绿。
+
+> 2026-07-09 批32b（净新增 1 条·dws 原生编排，lark 也没有）：`calendar +conflicts`（检测某天日程时间冲突/双重预订，list_calendar_events + 本地两两 [start,end) 重叠检测，默认今天/--in-days）。真机验证：抓到今日 9 个日程里 2 处真实冲突（技术标评审 10:00-11:00 × AIX 共创 10:30-12:00；尖角班 14:30-15:30 × 中控项目 15:00-16:00）。证明复杂写死胡同之外，纯 MCP-tool 的本地编排仍有净新增价值。总数 577→578、smart 66→67。全绿。
+
+> 2026-07-09 批32（review lark 复杂写类 + 架构边界结论，用户指定方向）：fresh review lark 复杂写 shortcut（mail +send/+reply/+forward、drive +import、doc +media-insert/download、base +record-upload-attachment），交叉 dws helpers。**关键结论——架构性死胡同，非没使劲**：① `mail +send` dws 已有 1:1 `+send`(send_email)+`+draft-*`，且 **contact 无 email 字段**→无法按名解析收件人（矩阵早 skip），也无 signature/template/lint 工具；② `drive +import`/`doc +media-*`/`base +record-upload-attachment` 核心是**本地文件字节 PUT/下载落盘**——dws 里由 helper 内部 `httpPutFile`/`http PUT/GET`（drive.go/doc.go）实现、已在 1:1 层覆盖（如 `drive upload --convert`），但 **shortcut 框架 `rt.CallMCP/CallMCPData` 只编排 MCP tool、结构上做不了原始文件 I/O**，故无法在 smart 层组合。**建议**：剩余复杂写要么卡此边界、要么已被 1:1 覆盖；真要补文件类能力应在 helper/1:1 层加命令，而非 shortcut 层。本批 review、无代码改动，总数仍 577。注：本轮触及 session 限额（8:20pm 重置）+ 分类器一度不可用，Bash 受限。
+
+> 2026-07-09 批31（净新增 1 条）：`calendar +my-free`（我自己的忙闲，自动解析当前 userId、默认今天，复用 +free 的 freebusySlots 投影；无需像 +free 传别人姓名）。真机正向验证：返回今日/明日真实忙碌时段 {busy:[{start,end}],userId,free}。总数 576→577、smart 65→66。文档全量同步。全绿。
+
+> 2026-07-09 批30（净新增 1 条）：`contact +me`（当前用户 `get_current_user_profile` + 投影 `{name,userId,mobile,dept,org,email}`，agent 的「我是谁」；区别于 1:1 `+get-self` 吐冗长 `result[].orgEmployeeModel` raw）。真机正向验证：董鑫阳/202397/模型算法/钉钉。总数 575→576、smart 64→65。文档全量同步。全绿。
+
+> 2026-07-09 批29（净新增便利读 3 条 + 真机抓修 1 bug）：`oa +done-approvals`（审批历史 get_done_tasks）、`mail +recent-mail`（近期收件 list_mailbox_threads + 解析绑定邮箱/收件箱 folder）、`attendance +this-month`（本月打卡 query_check_record on attendance-wukong，复用 +my-attendance）。**真机抓到并修复 bug**：`+done-approvals` 原来 --limit 不传时 pageSize=0 → 后端 business error（1:1 list-executed 有默认所以正常）；改为默认 pageSize=20，真机复验走空路径「没有已处理的审批记录」。+this-month 真机有效空、+recent-mail 正确报未绑定邮箱。总数 572→575、smart 61→64。文档全量同步。全绿。
+
+> 2026-07-09 批28（净新增便利读 smart，多 agent 并行 + 手工）：再建 3 条只读 smart——`oa +pending`（`list_pending_approvals` 只读列待我审批，区别于会审批的 +approve-by）、`todo +due-today`（`get_user_todos_in_current_org` + `planFinishDateStart/End` 服务端过滤今天到期，区别于 +overdue 已过期）、`calendar +tomorrow`（明天日程，复用 +today/+week 投影）。真机：+tomorrow 返回真实明日日程；+pending/+due-today 空路径正确且复用已验证 helper。3 条为 dws 原生便利读、不对应 lark gap，矩阵 42/48 不变，总数 569→572、smart 58→61。文档全量同步。全绿。
+
+> 2026-07-09 批27（写类输出扫荡收尾，确认无更多 bug）：扫 smart 里丢弃 CallMCPData 结果的 3 处——`broadcast`（per-recipient 循环、最终结构化输出，OK）、`book`（弃 add-participant 结果但最终 `get_calendar_detail` 确认 + 失败回滚，OK）、`reschedule`（弃存在性 check detail 是有意的，随后打 update 结果，OK）。**无更多 silent-success bug**。结论：**输出质量扫荡完成**，只读投影 clean、写类确认结果、honor --format。剩余仅复杂 net-new gap-buildable（mail +send/drive +import 等多步写、难安全真机验）或 commit。真机+一致性改进累计 13 条，总数 569，全绿。
+
+> 2026-07-09 批26（写类 smart 输出一致性批量修）：扫 smart 里用 `fmt.Print*` / 无标准输出的。修 2 条：`chat +broadcast`（`fmt.Printf` 群发摘要忽略 --format → `rt.Output({sentCount,failedCount,sent,failed})`）；`wiki +wiki-new-doc`（**原创建文档后丢弃 create_file 结果、静默 return nil**，真 UX bug 拿不到新文档 id/url → 捕获并 `rt.Output({created,space,title,result})`）。写类无法真机验（会真建/发），assemble 测试确认组装正确、低风险。总数仍 569。
+
+> 2026-07-09 批25（+next-event 输出一致性修复 + sweep 确认多数已 clean）：sweep 探 chat +conversation-list/+category-list、aitable +base-list 等——**多数 1:1 只读命令输出已 clean**（属先前 ~60 升级覆盖），保真度工作基本到位。**修复 1 条一致性**：`calendar +next-event` 原用 `fmt.Println` 打固定文本行、**忽略 --format/--jq/--fields**，改为 `rt.Output(map{event:项目投影})`（复用 +today/+week 同款投影），真机复验 `--format json` 出结构化 `{event:{title,start,end,location,eventId}}`、`--jq '.event.title'` 可用。这是 Agent 友好性修复。同时删除死代码 `shortcutNextEventSummary` + 无用 fmt import。总数仍 569。
+
+> 2026-07-09 批24（1:1 层保真度升级续）：`contact +list-followings` 原 `rt.CallMCP` 吐 `{arguments,result:{models:[…]}}` 信封噪音，改为 `CallMCPData`+`listFollowingsProject`，真机复验干净 `{count:13, followings:[{openDingTalkId}]}`。总数仍 569。**判断**：真机验证 + 保真度升级已到深度边际收益区（本批仅拍平 ID 列表）；1:1 层多数只读命令要么需特定参数、要么后端权限受限、要么输出已可接受。**建议优先 commit 留存 24 批成果**（10 个真机改进 + 58 smart + 保真度升级 + P2 + 全套文档），再按需推进剩余 1:1 微升级。
+
+> 2026-07-09 批23（验证驱动的 1:1 层保真度升级起步）：真机探 1:1 只读命令，`drive +recent` 原 `rt.CallMCP` 吐冗长 raw（logId/nextCursor 噪音 + 每项巨型 docUrl + hasMore），改为 `CallMCPData`+`recentListProject`：投影 `{count, hasMore, items:[{name,nodeType,contentType,accessTime,docUrl,nodeId}], nextCursor}`，去 logId 噪音、保留分页与链接，真机复验干净。`drive +list-spaces` 真机空（有 errorCode 包裹噪音但 result.items 为空，暂不动）。总数仍 569。**注**：1:1 层仍有数十个 list 命令可类似升级，但属边际收益、量大，建议按需/被动推进，优先 commit 留存已有成果。
+
+> 2026-07-09 批22（报告综合更新，反映真机验证战役）：给 `shortcut-report.md` 新增 §2.4「真机验证战役」：记录 9 批真机验证（正向验证 20+ 条、抓修 8 个真实 bug 的表格、后端受限项、resolveUser 非 bug 澄清）；`shortcut-report.html` §③ 测试表补 2 行 + 一段说明。诚实反映「assemble 合成测试盲区 → 真机验证补齐」的价值。纯文档，无代码改动，总数仍 569。
+
+> 2026-07-09 批21（find-record 验证 + +suggest-time 保真度升级）：`aitable +find-record` 真机正常（返回真实记录；cells 按字段 ID 键值、内含附件对象，天然复杂，clean 投影需 field-id→name 解析属更大改造，暂留）。**升级 1 条**：`calendar +suggest-time` 原 `rt.CallMCP` 吐 `result.recommendEventTimes[]` 且 `timeConflictAttendees:[null]` 噪音，改为 `CallMCPData`+`suggestTimeSlots`+`Output`：拍平 result、丢弃 null 冲突项，真机复验干净 `{suggestions:[{start,end}]}`（有真实冲突时才带 conflicts）。总数仍 569。**说明**：真机验证扫荡已进入边际收益递减区（明显 raw-verbose 的 wart 基本清完），剩余多为 minutes org-gated、写类、或输出已可接受。列出 12 条只读仍用 raw `rt.CallMCP` 的 smart（多为 minutes org-gated 或已验证 clean）。**升级 1 条**：`calendar +today` 原直吐 17 字段冗长事件（含完整 attendees 数组），改为 `CallMCPData`+复用 `+week` 的 `shortcutNextEventList/Start` 投影，真机复验干净输出 `{events:[{title,start,end,location,eventId}]}`（与 +week 一致 + location）。总数仍 569。剩余 raw-CallMCP 只读 smart：action-items/latest-minutes/transcript（minutes org-gated 无法真机验）、org/report-latest（已验 clean）、find-record/suggest-time/by-mobile/lookup/team（待验或权限受限）。
+
+> 2026-07-09 批19（日历只读 smart 验证 + +free 保真度升级）：`calendar +next-event` 真机正常（可读摘要「下一个日程：致拓 AI FDE 经验分享…」，但**忽略 --format json 只吐文本**，已知小瑕疵未改）。**升级 1 条**：`calendar +free` 终结步原 `rt.CallMCP` 直吐冗长 `result[].scheduleItems[].{start,end}.dateTime` 嵌套，改为 `CallMCPData`+`freebusySlots`+`Output`，真机复验干净输出 `{who,userId,free,busy:[{start,end}]}`（董鑫阳 2026-07-10 忙 4 段）。总数仍 569。
+
+> 2026-07-09 批18（真机验证续 + +group-members 保真度升级）：**验证正常**：`contact +org`（董鑫阳→模型算法/17人，3步链）、`drive +find-file`（干净投影 {dentryId,fileSize,name,type}）。**后端受限（非 bug）**：`contact +team`（列部门成员 `PAT_MEDIUM_RISK_NO_PERMISSION`）、`chat +search-msg`（org 未开 CLI 数据访问 `TOKEN_VERIFIED_FAILED`）。**升级 1 条**：`chat +group-members` 终结步原用 `rt.CallMCP`（直吐原始冗长 `result.list[]` + memberAvatarMediaId + arguments/errorCode 噪音），改为 `CallMCPData`+`groupMemberProject`+`Output`，真机复验干净输出 `{count, members:[{name,nick,role,openDingtalkId}]}`（刘力/怒龙/群主…）。总数仍 569。
+
+> 2026-07-09 批17（修复批16 发现的 +at-me 投影）：`chat +at-me` 原来因 `atMeMessageItems` 不认识真实两层嵌套 `result.conversationMessagesList[].messages[]` → 命中 fallback、直接吐原始结构。真机 dump 出真实结构（group 有 title/openConversationId/messages；message 有 sender/content/createTime/openConversationId），新增 `atMeFlattenGroups` 把各会话组拍平成单一消息列表、并把组的会话 title 下沉到每条消息。真机复验：43 条消息干净投影为 `{conversation,sender,text,time}`（如 conversation:"AI全栈"、sender:"龙衔"）。总数仍 569。
+
+> 2026-07-09 批16（只读 smart 真机验证扫荡 + 质量修复）：真机跑一批时间/自身类只读 smart。**验证正常**：`calendar +today`（真实日程+参会人）、`calendar +week`（干净投影）、`todo +overdue`（空）、`attendance +my-attendance`（空）、`report +report-latest`（"暂无日志"空路径）、`oa +my-initiated`（真实审批数据）。**修复 1 个输出 wart**：`chat +unread-chats` 每行都吐 `unread: null`——因 `unread_message_conversation_list` 根本不返回每会话未读数（在列表里即代表未读），改为「仅当 gateway 真返回未读数时才带 unread 字段」，真机复验输出已干净 `{conversationId,name}`。**已知待优化（未改）**：`chat +at-me` 返回 `result.conversationMessagesList[].messages[]` 冗长嵌套原始结构、未拍平成干净消息列表（功能正常，投影可再优化）。总数仍 569。
+
+> 2026-07-09 批15（质量修复 + resolveUser 排查，真机）：**修复** `contact +dept-members` 消歧消息 `<red>` 标记泄漏——复用 `stripHighlightTags`（resolve_dept.go）在 name 提取处剥离，真机复验消息已干净（"开放平台(666202009)、技术平台-开放平台研发(1085781688)…"）。注：`dept_members.go` 本身容器解析(含 deptList)+数值 deptId 早已健壮，仅 name markup 未剥。**排查澄清（非 bug）**：`resolveUser` 对 `董鑫阳` 真机端到端正常（userId 202397、部门 模型算法）；但对 `秋画` 这类联系人 `search_contact_by_key_word` 返回 name/userId 全 null（仅 openDingTalkId），resolveUser 正确报「没找到」而非瞎猜——这是钉钉数据模型现实（外部/受限联系人无 userId），非代码 bug。**已知限制**：按名解析仅对「搜索能返回 userId 的组织内成员」有效。总数仍 569。
+
+> 2026-07-09 批14（真机验证续，需具体 ID 的只读 shortcut）：**正向验证过**：`chat +my-groups`（98 真实群+投影）、`aitable +base-list`/`+list-tables`（真实 base/table）、`aitable +resolve-table`（单命中 通用→99dV75A、多候选消歧，容器 key `tables` 正确，无 deptList-class bug）。**后端权限受限、无法正向验证（非代码 bug）**：`chat +chat-messages`（`PAT_MEDIUM_RISK_NO_PERMISSION`，读会话消息需更高权限）、`minutes +*`（该 org 未开启 CLI 数据访问 `TOKEN_VERIFIED_FAILED`）。结论：可验证的 read/resolve shortcut 全部投影正确，仅批13 的 resolve-dept 有真 bug 已修。
+
+> 2026-07-09 批13（真机验证 + bug 修复，登录态 corp「钉钉」）：用登录态把批9-12 只读 shortcut 打真实后端。**正向验证过**：`doc +find-doc`（10 真实文档、投影干净）、`aitable +resolve-base`（多候选真实 baseId）、`mail +find-mail-user`（命中真实用户+邮箱）、`contact +resolve-dept`（修复后返回真实候选）。**真机抓到并修复 1 个真 bug**：`contact +resolve-dept` 原来对任何真实部门名都返回「未找到」——真实 `search_dept_by_keyword` 响应容器 key 是 **`deptList`**（agent 的探测清单漏了），且 `deptName` 带 `<red>…</red>` 高亮标记、`deptId` 是数值。已修：容器加 `deptList`、`stripHighlightTags` 去标记、deptId 数值 coerce 成串（`resolve_dept.go`），真机复验通过（开放平台→666202009、财务→846624121，名称干净）。**已知遗留（未改）**：`contact +dept-members` 的消歧提示消息里 `<red>` 标记未剥离（仅 cosmetic，功能正常）。总数仍 569，本批未加新命令。
+
+> 2026-07-09 批12（多 agent 并行，dws 原生 resolver 层）：再建 3 条「按名解析 ID」智能 shortcut——`wiki +resolve-space`（search_wikiSpaces 名→spaceId）、`aitable +resolve-table`（get_tables 在 Base 内本地名→tableId）、`contact +resolve-dept`（search_dept_by_keyword 名→deptId，**已修数值 ID 兼容**：deptId 为 JSON number 时 coerce 成串，非 string-only）。均 0/1/多候选消歧，对标 resolveUser 各资源版。这 3 条不对应具体 lark gap（是 dws 原生便利层），故 gap-buildable/covered-smart 矩阵计数不变(42/48)，仅总数 566→569、smart 55→58。文档全量同步。全绿。
+
+> 2026-07-09 批11（多 agent 并行）：再建 3 条智能 shortcut——`aitable +resolve-base`（search_bases 按名解析 baseId + 0/1/多候选消歧）、`chat +chat-messages`（群/单聊会话消息 list_conversation_message_v2 / list_individual_chat_message，ExactlyOne 互斥 + 投影）、`mail +find-mail-user`（search_mail_users 按名搜企业邮箱联系人 + 投影）。文档全量同步 566/505/55（gap-buildable 49→42、covered-smart→48）。全绿。注：本批 app 回归首跑因并发负载 flaky FAIL 一次（80s），连跑 2 次稳定 PASS（71s）——非本次改动导致。
+
+> 2026-07-09 批10（多 agent 并行）：再建 3 条智能 shortcut——`chat +thread-replies`（list_topic_replies 拉话题回复 + sender/text/time 投影）、`todo +related-tasks`（get_user_todos_in_current_org 三角色 creator+executor+participant 并集 + taskId 去重 + 投影）、`doc +find-doc`（search_documents 关键词搜文档 + title/url/type/token 投影）。均以 helper 为 ground truth、0 编造。文档全量同步到 563/503/52（report.md/html、lark-alignment.md gap-buildable 49→44、covered-smart→46、comparison.html 重生成）。全量测试 + app 回归全绿。
+
+> 2026-07-09 续跑增量（批9·手工）：新建 3 条智能 shortcut——`minutes +detail`（单命令聚合一条听记 basic/summary/keywords/transcript/todos、partial-failure 容错）、`minutes +replace-batch`（多组 `原文=>替换` 批量替换、去重校验+逐组聚合）、`aitable +record-share-links`（>20 条记录分享链接：去重+分片≤20/批+跨 `aitable-helper` server fanout+合并）。均以 helper 为 ground truth。**同步刷新全部文档到 560/501/49**：`shortcut-report.md`、`shortcut-report.html`、`shortcut-lark-alignment.md`（gap-buildable 49→46、covered-smart 41→44）、重生成 `shortcut-comparison.html`。全量测试 + app 回归全绿。
+
+---
+
+## 1. 背景与目标
+
+- 对齐基准：`/Users/dennis/Projects/larksuite/cli`（lark-cli 的 `shortcuts/` 框架，飞书 REST API）。
+- dws 执行底座：**钉钉 MCP**（粗粒度：一个 tool = 一个完整操作）。
+- 目标：把 lark 的 shortcut 能力**深度对齐每一个**到 dws，并补钉钉侧系统性能力。
+- 关键认知：lark 的"组合性"多源于飞书 API 细粒度（先查 token→id→再操作）；钉钉 MCP 粗粒度，**lark 的多步在钉钉大量塌缩成 1:1（已被封装层覆盖）**。真正需要"编排"的是「按名解析 ID + 多工具串联 + 跨服务」——这些做成了 smart 层。
+
+---
+
+## 2. 架构与关键文件
+
+```
+internal/shortcut/
+  types.go        # Shortcut / Flag / Risk 声明结构
+  runner.go       # RuntimeContext + mount(编译成cobra) + CallMCP/CallMCPData/Output + 校验/dry-run/风险确认
+  validate.go     # 跨字段校验 helper：MutuallyExclusive/AtLeastOne/ExactlyOne/RangeInt/RequireAll
+  register.go     # Register() / Commands() / All()
+  shortcut_test.go# 框架单测
+  builtin/
+    builtin.go       # blank-import 所有服务包 + smart 包；Commands() 汇总
+    coverage_test.go # ★全量测试：TestAllShortcutsAssemble / TestAllToolLiteralsAreReal / TestAllHaveIntent / TestNoDuplicateCommands
+  <service>/         # 19 个服务包：contact/chat/calendar/todo/doc/drive/mail/wiki/minutes/oa/report/attendance/aitable/sheet/devapp/ding/aisearch/live/devdoc
+    <service>.go     # 该服务的 1:1 封装 shortcut（var + init(){shortcut.Register(...)}）
+  smart/             # ★真·智能层（多步/编排/按名解析/跨服务）
+    resolve.go       # resolveUser(rt,name) 名→userId+消歧；contactUser{userID,name}；extractUsers/userLabels
+    dm.go lookup.go assign.go book.go free.go ... # 每条一个文件
+  usage/          # P2 埋点：recorder.go(记形状不记值) stats.go command.go(dws shortcut list/stats/suggest/add)
+  userdef/        # P2 自定义 shortcut YAML 运行时加载 loader.go
+
+internal/app/legacy.go   # 接线点：newLegacyPublicCommands 里 append builtin.Commands() + userdef.Load()
+internal/app/root.go     # 装配 recordingToolCaller(埋点) + dws shortcut 命令
+internal/helpers/*.go     # ★Ground truth：钉钉真实 MCP tool 名 + 参数（callMCPTool("tool",{...})）
+
+docs/
+  shortcut-plan.md            # 总规划
+  shortcut-p2-design.md       # P2 自动沉淀设计
+  shortcut-report.md / .html  # 综合报告 + GSB
+  shortcut-comparison.html    # 逐条三方对照(dws vs lark vs 原生MCP)
+  shortcut-lark-alignment.md  # ★深度对齐矩阵(lark 361条逐条分析, 49 gap-buildable)
+  shortcut-handoff.md         # 本文件
+scripts/gen_shortcut_comparison.py  # 生成三方对照 HTML
+```
+
+---
+
+## 3. 框架契约（写新 shortcut 必读）
+
+一个 shortcut = 包级 `var X = shortcut.Shortcut{...}` + `func init(){ shortcut.Register(X) }`。
+
+```go
+var SearchUser = shortcut.Shortcut{
+    Service: "contact",        // 顶层命令
+    Command: "+search-user",   // + 前缀，kebab-case
+    Product: "contact",        // MCP server id（默认=Service；注意跨 server，见坑位）
+    Description: "...",         // 一行
+    Intent: "自然语言：做什么/何时用/副作用",  // 每条必填(TestAllHaveIntent 强制)
+    Risk: shortcut.RiskRead,   // Read / Write / HighWrite(删除等，框架二次确认)
+    Flags: []shortcut.Flag{{Name:"query", Type:shortcut.FlagString, Required:true, Desc:"...", Enum:[]string{...}}},
+    Validate: func(rt *shortcut.RuntimeContext) error { return rt.RequireAll("query") }, // 可选
+    Execute: func(rt *shortcut.RuntimeContext) error { ... },
+}
+```
+
+RuntimeContext 方法（`internal/shortcut/runner.go`/`validate.go`）：
+- 读参数：`rt.Str/Bool/Int/StrSlice(name)`、`rt.Changed(name)`
+- **调 MCP 并打印**（终结步，1:1 封装用）：`rt.CallMCP(tool, params) error`（用自身 Product）
+- **调 MCP 拿数据**（多步/投影用，不打印，可跨 server）：`rt.CallMCPData(product, tool, params) (map[string]any, error)`
+- **投影输出**：`rt.Output(payload) error`（吃 --format/--jq/--fields）
+- 校验：`rt.MutuallyExclusive/AtLeastOne/ExactlyOne(flags...)`、`rt.RangeInt(flag,min,max)`、`rt.RequireAll(flags...)`
+- smart 复用：`resolveUser(rt, name) (contactUser, error)`（名→userId+消歧，在 smart/resolve.go）
+
+对标 lark：`CallMCPData`≈`CallAPITyped`；`resolveUser`≈`ResolveOpenIDsTyped`；`rt.Output`≈`OutFormat`；`Validate helper`≈lark 的 MutuallyExclusive/AtLeastOne。
+
+---
+
+## 4. 方法论（怎么高效批量建，屡试不爽）
+
+**核心：多 agent workflow 并行 + helper 为 ground truth + 严格 skip + build/test 门禁。**
+
+1. **每个 shortcut/服务一个 agent**，并行（`parallel(...)`）。
+2. **Ground truth 铁律**：tool 名和参数 key **只能逐字取自 `internal/helpers/<svc>.go` 的真实 `callMCPTool("tool",{params})` 调用点**，严禁编造。agent 必须先 Read+grep helper。
+3. **宁缺勿错**：拿不准的 tool/参数/结构 → **skip 并说明**，不瞎写（已多次证明 agent 会正确 skip，如 mail 无 email 字段）。
+4. **响应字段防御式解析**：返回结构无契约保证 → 多候选 key 探测（result/data/list/items + 字段别名），不硬编码。
+5. **不同 agent 写不同文件**（服务包 vs smart 包，或不同 service 文件）→ 无写冲突；**禁止 agent 改 builtin.go**（我事后统一维护 blank import）。
+6. **落地后统一**：`gofmt -w` → `go build ./...` → shortcut 全量测试 → 命名冲突用 rename 修（如 smart 的 `+approve` 撞 1:1 层 → 改 `+approve-by`）。
+7. **周期性 app 全量回归**（改多个服务文件后）：`go test ./internal/app/...`（~73s）验证接线。
+
+workflow 脚本模板见任意 `~/.claude/.../workflows/scripts/build-smart-*.js` 或 `upgrade-fidelity-*.js`（每次 Workflow 调用都存了盘，可 `{scriptPath}` 复用/改）。
+
+---
+
+## 5. 已完成进展
+
+### 5.1 覆盖层（511 条 1:1 封装 / 19 服务）
+chat89 aitable86 mail43 attendance36 doc33 minutes31 devapp30 sheet29 calendar24 drive24 oa20 todo18 wiki15 contact14 report7 ding7 aisearch3 live1 devdoc1。每条带自然语言 Intent。
+
+### 5.2 智能层（~46 条 `internal/shortcut/smart/`）
+按名操作人/群、多步编排+失败回滚、时间/自身智能、跨服务、钉钉原生编排。已建（举例）：
+`chat +dm/+send-to-group/+broadcast/+group-members/+at-me/+search-msg/+unread-chats`、`contact +lookup/+org/+team/+by-mobile/+dept-members`、`calendar +book(回滚)/+free/+today/+week/+next-event/+invite/+suggest-time/+reschedule/+cancel-event/+respond-event/+find-room`、`todo +assign/+assign-multi/+overdue/+todo-done/+remind/+created-todos`、`minutes +latest-minutes/+action-items/+transcript/+minutes-search/+detail/+replace-batch`、`oa +approve-by/+my-initiated`、`attendance +my-attendance`、`report +report-latest`、`aitable +find-record/+list-tables`、`doc +share-doc/+doc-append`、`wiki +wiki-new-doc`、`drive +find-file`、`mail +search-mail/+unread-mail`。
+
+### 5.3 框架系统性能力（对齐 lark）
+`resolveUser`、`CallMCPData`、`rt.Output`、`Validate×5`。
+
+### 5.4 保真度升级（~64 条封装：CallMCP→CallMCPData+投影+Output，对齐 lark 96% 输出投影）
+覆盖 contact/chat/calendar/todo/doc/drive/mail/wiki/aitable/oa/devapp/attendance/minutes/report/sheet 等服务的列表类命令。
+
+### 5.5 P2 高频自动沉淀（差异化，lark 无）
+埋点(记形状不记值,默认关/opt-in DWS_USAGE_TRACKING=1) → `dws shortcut stats/suggest` → `dws shortcut add` 写 `~/.dws/shortcuts/*.yaml` → 运行时 `userdef.Load()` 编译注册。**闭环端到端跑通。**
+
+### 5.6 深度对齐矩阵
+`docs/shortcut-lark-alignment.md`：逐条分析 lark 361 条 → covered-1to1 144 / no-dingtalk-tool 127 / **gap-buildable 49** / covered-smart 41。
+
+---
+
+## 6. 如何继续（下一步 backlog）
+
+1. **保真度升级剩余列表命令**（还有部分服务的 list 命令仍是裸 CallMCP）：起 `upgrade-fidelity-N` workflow，每服务 agent 挑 1-2 个未升级(`grep 'rt.CallMCP('`)的列表读命令，改成 CallMCPData+投影+Output。范式见 `contact.go` 的 `searchUserProject`/`listRolesProject`。
+2. **补剩余 gap-buildable smart shortcut**（矩阵里 49 个，已建 ~20+）：起 `build-smart-N` workflow（smart 包，不碰服务包）。剩余偏复杂（sheets/base 操作、消息富化、分片下载），谨慎、允许 skip。
+3. **每批**：gofmt→build→shortcut 测试→（改多文件后）app 回归→更新 `docs/shortcut-report.md`。
+4. **收尾**：把 `docs/shortcut-report.md/html` 的计数刷新到最终（部分 §2 测试数字可能还停在旧值 511/456，实际 ~557/~500），重跑 `python3 scripts/gen_shortcut_comparison.py`。
+
+---
+
+## 7. 关键坑位（务必注意）
+
+- **跨 server 路由**：有些 tool 不在本服务 server。已知：contact 花名册 tool 走 `hrmregister`；chat 部分 tool 走 `im`/`bot`；`query_check_record` 走 `attendance-wukong`（不是 attendance）；wiki `create_file` 走 `doc` server。→ 这类必须用 `rt.CallMCPData("<真实server>", ...)`，不能用 `rt.CallMCP`（它按 shortcut.Product 路由会打错 server）。判断依据：helper 里是 `callMCPToolOnServer("<server>", ...)`。
+- **命名冲突**：smart 命令别撞 1:1 层（如 `+approve`→用 `+approve-by`，`+freebusy`→用 `+free`）。`TestNoDuplicateCommands` 会抓。
+- **参数别名**：aitable 查询关键词是 `keyword`（不是 query）；todo 建待办用嵌套 `PersonalTodoCreateVO`；日程 create/update 时间是 ISO 字符串，而 list/busy 是毫秒——一切以 helper 调用点为准。
+- **中文 const tool 名**：minutes 录音 tool 是中文 `"执行听记指令-发起AI听记录音"`（const `listeningNoteCmdTool`）——真实，别当编造。
+- **测试真机验证**：token 有时效（`dws auth status` 看 expires），过期会报错非代码问题。真机跑命令时第一次有 catalog 发现 banner（stderr），结果 JSON 在后面，别用 `head` 截断。
+- **工具标签格式**（给 AI：本会话我多次误用错标签导致工具调用失败——务必用正确的 function-call 格式）。
+
+---
+
+## 8. 验证命令速查
+
+```bash
+cd /Users/dennis/Projects/dingtalk-workspace/dingtalk-workspace-cli
+go build ./...                                    # 编译
+gofmt -l internal/shortcut/                        # 格式(应空)
+go test ./internal/shortcut/...                    # shortcut 全量(含 assemble/tool-real/intent/no-dup)
+go test ./internal/app/...                         # app 回归(~73s，改服务文件后必跑)
+go test ./internal/shortcut/builtin/ -run TestAllShortcutsAssemble -v 2>&1 | grep shortcuts=  # 看总数
+
+# 真机(需登录 dws auth login)
+DWS_USAGE_TRACKING=0 dws contact +lookup --name <真实姓名>   # 智能多步示范
+DWS_USAGE_TRACKING=0 dws calendar +today                     # 时间智能
+DWS_USAGE_TRACKING=0 dws contact +search-user --query <名>   # 投影输出示范
+```
+
+测试口径：`TestAllShortcutsAssemble` = 假 Caller 拦截，给每条命令(含写/删)喂合成参数、走完解析→校验→组装 MCP 调用、断言 tool 真实无 panic（零副作用全量验证）。`TestAllToolLiteralsAreReal` = 所有 CallMCP tool 名比对 helper ground truth 防编造。
+
+---
+
+## 9. 未提交提醒
+
+所有工作在 `feature/shortcut`，**未 commit**。建议尽快分语义化 commit 留存（框架 / 511封装 / smart层 / 保真度升级 / P2 / 文档）。

docs/shortcut-lark-alignment.md

@@ -0,0 +1,187 @@
+# lark-cli Shortcut 深度对齐矩阵
+
+> 12 个 agent 逐条深读 lark 每个 shortcut 的智能实现（Validate/DryRun/ID解析/投影/多步/分页），映射钉钉、标注保真度差距。
+
+## 2026-07-13 最新源码复核
+
+对比基线：
+
+- DWS：`feature/shortcut@b7c14c1`（已合并 `origin/main@390b611`）
+- lark-cli：`main@e96c4fa5`
+- lark-cli 本轮更新范围：`f495cbb1..e96c4fa5`
+
+本轮 lark-cli **没有增加或删除生产 shortcut 命令**，变化集中在已有命令的实现保真度：统一 `--json` shorthand、文档分享锚点读取、whiteboard 本地文件安全内联、VC meeting events 的 identity/timeline/NDJSON 投影、Apps DB 环境自动选择、Drive push 错误分类，以及 Wiki token 解析兼容性。因此下方历史 gap 清单的命令面没有因本轮 pull 新增条目，但若要追平体验，以下实现差距需要上调优先级。
+
+### 当前命令面快照
+
+| 指标 | 数量 | 说明 |
+|---|---:|---|
+| DWS built-in shortcut | 366 | 16 个服务；运行时 registry 实测 |
+| lark-cli primary shortcut | 363 | 19 个服务；排除 `_test.go` 与 42 个 `sheets/backward` 隐藏兼容别名 |
+| 双方可映射服务内命令 | DWS 313 / lark 324 | 12 组产品映射，不含平台特有服务 |
+| 同服务同名命令 | 50 | 仅是名称交集，不等于语义等价或保真度一致 |
+| DWS 平台特有 shortcut | 53 | attendance / ding / oa / report 等 |
+| lark 平台特有 shortcut | 39 | okr / vc / slides / markdown / whiteboard / note / event |
+
+双方重叠服务的命令面如下；“同名”只用于定位，能力判断仍需看参数、验证、多步编排、输出投影和 dry-run：
+
+| 产品映射 | DWS | lark | 同名 |
+|---|---:|---:|---:|
+| aitable ↔ base | 82 | 87 | 31 |
+| calendar ↔ calendar | 23 | 10 | 3 |
+| chat ↔ im | 89 | 21 | 2 |
+| contact ↔ contact | 16 | 2 | 1 |
+| devapp ↔ apps | 30 | 63 | 3 |
+| doc ↔ doc | 19 | 14 | 1 |
+| drive ↔ drive | 9 | 26 | 3 |
+| mail ↔ mail | 10 | 21 | 0 |
+| minutes ↔ minutes | 13 | 9 | 1 |
+| sheet ↔ sheets | 2 | 42 | 0 |
+| todo ↔ task | 13 | 17 | 2 |
+| wiki ↔ wiki | 7 | 12 | 3 |
+
+### 最新优先差距
+
+1. **文档与白板资源保真度**：lark `doc +fetch/+update` 已支持分享链接 selection anchor、HTML5 block 资源引用，以及相对路径内的 SVG/Mermaid/PlantUML whiteboard 安全内联。DWS 具备文档读写和媒体原子能力，但缺少统一引用解析、路径门禁和资源回写编排。
+2. **Sheets typed workflow**：lark 的 typed table、批量样式、维度移动/冻结、range copy/fill/sort、workbook import/export 仍是最大可建设缺口。DWS 原生 helper 已有部分底层能力，但 shortcut 层只有 2 个精选命令，缺少跨 sheet 分块写、类型推断和 partial rollback。
+3. **Drive 本地同步体验**：lark `+push/+pull/+sync/+import/+export` 带批量计划、错误分类、路径保护和版本操作；DWS 目前偏原子上传/搜索，缺完整目录同步和可恢复批处理。
+4. **Mail 高保真写链路**：lark 对 send/reply/reply-all/forward 提供模板、签名、HTML lint、线程头、定时和附件编排；DWS 有底层发信/草稿工具，但 smart shortcut 尚未覆盖这些组合体验。
+5. **消息资源与统一搜索**：DWS 已有 `+search-msg/+chat-messages/+thread-replies/+at-me` 等拆分场景，lark `+messages-search` 仍在统一多维过滤、会话上下文富化、reaction/资源下载方面更完整。
+6. **会议事件输出**：lark `vc +meeting-events` 本轮新增当前身份、actor、会议状态推断、timeline 与 NDJSON 元数据。DWS 最新 main 已有更强的实时 event bus 和个人事件订阅，但尚未沉淀成同等级 shortcut 投影；这是“底层能力领先、shortcut UX 未收口”。
+
+### 不建议机械追平
+
+- lark Apps DB、Spark 发布、Lark Drive/Wiki 特有对象模型属于平台差异，不应只为同名率复制。
+- DWS 的 attendance、DING、OA、report、agoal 和最新 event bus 是钉钉侧差异化能力，应优先做场景化组合，而不是追求 363 vs 366 的数字对齐。
+- DWS 已具备按姓名解析、跨产品智能编排、失败回滚和 usage→自定义 shortcut 沉淀闭环，这些能力无法由同名命令统计体现。
+
+> 注：下方“361 条”汇总是上一轮逐条人工分类的历史基线；当前 lark-cli primary shortcut 是 363 条，另有 42 个不应重复计为能力的 Sheets 隐藏兼容别名。历史条目的判断仍可复用，但总量数字不能直接代表本轮最新覆盖率，后续应把新增条目按 covered-1to1 / covered-smart / gap-buildable / no-dingtalk-tool 四类补录。
+
+## 汇总（361 条 lark shortcut）
+
+| dws_status | 数量 | 含义 |
+|---|:---:|---|
+| covered-1to1 | 144 | lark 组合在钉钉塌缩成 1:1，封装层已覆盖 |
+| no-dingtalk-tool | 127 | 钉钉无对应工具，客观不可对齐 |
+| **gap-buildable** | **42** | 钉钉有工具、值得补成智能 shortcut（**建设目标**）；已建 minutes `+detail`/`+replace-batch`、base `+record-share-links`/`+resolve-base`、im `+thread-replies`/`+chat-messages`、task `+related-tasks` |
+| covered-smart | 48 | 已建智能 shortcut / 部分覆盖 |
+
+## 🎯 gap-buildable 目标清单（原 49 条，已建 7 → 剩 42，按服务）
+
+> 已落地：minutes `+detail`（✅ smart `+detail`）、minutes `+word-replace`（✅ smart `+replace-batch`，批量+去重）、base `+record-share-link-create`（✅ smart `+record-share-links`，>20 去重+分片+合并）、im `+threads-messages-list`（✅ smart `chat +thread-replies`，list_topic_replies + 投影）、task `+get-related-tasks`（✅ smart `todo +related-tasks`，三角色并集+去重+投影）。
+
+### im → chat（6）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+chat-list` | read | dws 有 list-my-groups/list-all-conversations 原子 tool，但无 types 枚举+bot剥p2p降级、无 exclude-muted 客户端过滤、无字段投影 |
+| `+chat-messages-list` ✅ | read | **已建 smart `chat +chat-messages`**：群/单聊 list_conversation_message_v2 / list_individual_chat_message 互斥 + sender/text/time 投影。剩余未做：reactions 富化、资源下载 |
+| `+chat-search` | read | dws 无群名模糊搜索v2对应 tool(search_common_groups/find 语义不同)，缺 query规范化、mode映射、mute过滤、meta投影 |
+| `+messages-resources-download` | write | dws download-media 走 get_resource_download_url 拿URL，缺分片Range下载/重试/扩展名推断/安全落盘路径校验 |
+| `+messages-search` | read | dws 有 search_messages_by_keyword/by_time_range/by_sender/at_me 多个原子 tool，但各自单点，缺统一多维filter编排+mget+chat上下文富化+跨字段Validate |
+| `+threads-messages-list` ✅ | read | **已建 smart `chat +thread-replies`**：list_topic_replies + sender/text/time 投影。剩余未做：reactions 富化、资源下载 |
+
+### task → todo（3）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+reminder` | write | dws 有 add_todo_reminder/reset_todo_reminder 但无 lark 的先查现有再替换编排、相对时间(15m/1h)解析与互斥校验，值得补智能 shortcut |
+| `+get-related-tasks` ✅ | read | **已建 smart `todo +related-tasks`**：creator+executor+participant 三角色并集 + taskId 去重 + 投影。剩余未做：followed-by-me 成员比对、subtask_count/tasklists 富投影 |
+| `+upload-attachment` | write | dws add-attachment 走 init→PUT→commit 三步 MCP 上传(能力更重)，但无 50MB/regular 校验、applink 提取与 dry-run 计划展示；可对齐成更智能 shortcut |
+
+### calendar → calendar（1）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+room-find` | read | dws 有 room search(query_available_meeting_room 按单一时间段+过滤)和 busy search，但无多slot并发room_find聚合、无city/building/floor/capacity维度过滤、无按attendee推荐可用室，值得补成智能 shortcut 但未建 |
+
+### doc (docs) → doc（2）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+media-insert` | write | dws doc media insert 为3步(取凭证→PUT→insert_document_block)无回滚、无selection定位、无剪贴板、无宽高比补算、无wiki解析；可补成带回滚的智能shortcut |
+| `+media-download` | read | dws doc media download 走resourceId→downloadUrl两段,缺whiteboard导图分支、自动扩展名、路径安全、overwrite防护；media分支可对齐，whiteboard无工具 |
+
+### drive → drive（1）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+import` | write | dws drive upload 有 --workspace --convert 可转在线文档，但缺按目标类型(docx/sheet/bitable/slides)导入、缺 target-token 挂载与异步轮询 |
+
+### mail → mail（4）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+reply` | write | dws reply 走 create_reply_draft+send_draft 两步、附件仅上传会话，缺 EML 线程头构造、签名自动注入、模板合并、HTML lint、读回执、send-time 定时、跨字段校验 |
+| `+reply-all` | write | dws reply-all 两步且收件人由服务端决定，缺原文收件人抽取去重排己、线程头、签名/模板/lint/定时等编排保真 |
+| `+send` | write | dws send_email 单步(附件时先 create_draft 再传再 send)，缺签名/模板/lint/日历内嵌/定时发送/发件人profile解析/跨字段校验 |
+| `+forward` | write | dws forward 走 create_forward_draft+send_draft，缺 Fw:主题/引用块/原附件转载 EML 构建、签名/模板/lint/定时保真 |
+
+### wiki → wiki（1）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+node-get` | read | dws 无 get_node 对应 tool(proxy wiki doc read 读的是文档正文而非节点元数据/space解析)；缺 token/obj_token/URL→node 解析、obj_type推断、space交叉校验——是值得补的智能 shortcut 缺口 |
+
+### minutes → minutes（4）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+search` | read | dws list_by_keyword_and_time_range 只按 keyword+时间+归属(created/shared)过滤，缺 owner/participant 的 me 解析与筛选、缺 query 长度与跨字段互斥校验、缺输出投影与去头像 |
+| `+download` | read | dws 只有 query_minutes_audio_url 返回 OSS 地址(相当于 --url-only 单条)，缺真正落盘下载、批量 fanout+限速+去重、文件名推断、SSRF 防护与覆盖保护 |
+| `+word-replace` ✅ | write | **已建 smart `+replace-batch`**：多组 `原文=>替换` 批量替换 + 去重校验 + 逐组结果聚合（补齐 1:1 `+word-replace` 的单组限制）。剩余未做：@file/stdin 输入 |
+| `+detail` ✅ | read | **已建 smart `+detail`**：单命令按 `--artifacts` fanout basic/summary/keywords/transcript/todos + partial-failure 容错 + rt.Output 投影。剩余未做：wait-ready 轮询、transcript 落盘 |
+
+### base → aitable（10）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+title-resolve` ✅ | read | **已建 smart `aitable +resolve-base`**：search_bases 按名解析 baseId + 0/1/多候选消歧投影。剩余未做：Drive doc_wiki 全文搜索 |
+| `+field-create` | write | dws create_fields 支持批量,但缺 formula/lookup guide-ack 门禁与逐字段节流,可补智能 shortcut |
+| `+field-update` | write | dws update_field 缺 formula/lookup guide-ack 保护 |
+| `+record-share-link-create` ✅ | read | **已建 smart `+record-share-links`**：>20 条记录去重 + 分片(≤20/批) + 跨 aitable-helper server fanout + 合并 {recordId,shareUrl}，补齐单批 20 条上限 |
+| `+record-upload-attachment` | write | dws 只有 prepare_attachment_upload(拿上传凭证),缺 分片上传编排+append_attachments 回填单元格的完整链路 |
+| `+dashboard-block-list` | read | dws 仪表盘块是 chart(create/get/update/delete_chart),缺通用 block list,可对齐补 |
+| `+dashboard-block-get` | read | dws get_chart 覆盖 chart 类块,缺通用 block get |
+| `+dashboard-block-create` | write | dws create_chart 覆盖图表块,缺其他 block 类型的通用创建 |
+| `+dashboard-block-update` | write | dws update_chart 覆盖图表块更新 |
+| `+dashboard-block-delete` | high-risk-write | dws delete_chart 覆盖图表块删除 |
+
+### sheets → sheet（14）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+sheet-hide` | write | dws update_sheet可能含hidden属性但未见独立hide命令,需确认 |
+| `+sheet-unhide` | write | 同上,dws无独立unhide命令 |
+| `+sheet-set-tab-color` | write | dws update_sheet或可设tab色但无独立命令 |
+| `+sheet-show-gridline` | write | dws无网格线显隐命令 |
+| `+sheet-hide-gridline` | write | dws无网格线显隐命令 |
+| `+workbook-create` | write | dws有create_workspace_sheet但仅建空表,缺typed一步建表+填充+样式+partial回滚编排 |
+| `+dim-hide` | write | dws update-dimension或含hidden但无独立hide命令 |
+| `+dim-unhide` | write | 同上,dws无独立unhide命令 |
+| `+dim-freeze` | write | dws update-dimension可能含frozen但无独立freeze命令 |
+| `+cells-get` | read | dws range read存在但缺include样式/公式投影统一封装 |
+| `+table-get` | read | dws缺typed table读回+列类型推断+多sheet编排,只有裸csv/range读 |
+| `+table-put` | write | dws有append/set_cell_range但缺typed多sheet分块写+建缺失sheet+样式+partial回滚编排 |
+| `+rows-resize` | write | dws update-dimension可调尺寸但无独立rows-resize+size/type互斥校验 |
+| `+cols-resize` | write | dws update-dimension可调尺寸但无独立cols-resize+互斥校验 |
+
+### apps → devapp（3）
+
+| lark 命令 | risk | 保真度差距（钉钉有 tool，缺什么智能） |
+|---|---|---|
+| `+release-create` | write | dws 有 create_dev_app_version(开放平台版本)可类比，但妙搭 release 是低代码应用发布、语义与产物不同 |
+| `+release-get` | read | dws 有 get_dev_app_version_detail 可类比但产品域(开放平台vs妙搭)不同 |
+| `+release-list` | read | dws 有 list_dev_app_versions 可类比但无 status 枚举过滤且产品域不同 |
+
+## 已建智能 shortcut（covered-smart，48）— 可继续升级保真度
+
+- **im**: +chat-members-list +messages-send +threads-messages-list
+- **task**: +complete +assign +get-my-tasks +get-related-tasks
+- **contact**: +search-user
+- **calendar**: +agenda +create +update +freebusy +suggestion
+- **doc (docs)**: +history-revert
+- **drive**: +upload +search +inspect
+- **mail**: +triage
+- **minutes**: +upload +latest-minutes +action-items +transcript +minutes-search +detail +replace-batch
+- **base**: +table-get +table-create +view-create +view-get-filter +view-set-filter +view-get-visible-fields +view-set-visible-fields +view-get-group +view-set-group +view-get-sort +view-set-sort +view-get-timebar +view-set-timebar +view-get-card +view-set-card +record-list +record-search +record-get +record-upsert +base-create +workflow-list +form-create +form-list +form-get +record-share-link-create

docs/shortcut-p2-design.md

@@ -0,0 +1,204 @@
+# DWS Shortcut P2 详细设计 — 高频场景自动沉淀为自定义 Shortcut
+
+> 前置：P1 已交付静态声明式 shortcut 框架（`internal/shortcut/`），见 `docs/shortcut-plan.md`。
+> P2 目标：**观察用户高频使用 → 主动建议 → 一键沉淀为可复用的自定义 shortcut**，
+> 让 CLI 越用越顺手。这是 dws 相对 larksuite/cli 的差异化能力。
+
+## 0. 体验闭环（一句话）
+
+```
+用户反复敲 dws chat send_message --json '{"open_conversation_id":"cid_x","text":"..."}'
+        │  （每次执行被静默记录到 ~/.dws/usage.jsonl）
+        ▼
+第 N 次后，dws 主动提示：
+  💡 你已 12 次向「项目群」发消息，是否沉淀为 `dws chat +notify-team`？[y/N]
+        │  y
+        ▼
+写入 ~/.dws/shortcuts/chat.notify-team.yaml
+        ▼
+之后：dws chat +notify-team --text "发布完成"   ← 参数从一堆 JSON 收敛成一个 flag
+```
+
+## 1. 总体架构
+
+复用 P1 的 `Shortcut` 模型作为「编译目标」，新增四个部件：
+
+| 部件 | 位置（建议） | 职责 |
+|------|-------------|------|
+| Usage 埋点 | `internal/shortcut/usage/recorder.go` | 每次 MCP 调用后追加一条 usage 记录 |
+| 模式挖掘 | `internal/shortcut/usage/miner.go` | 聚合 usage → 高频候选 + 打分 |
+| 主动提示 | `internal/shortcut/usage/nudge.go` | 命中候选时在命令收尾处提示 |
+| YAML 加载 | `internal/shortcut/userdef/loader.go` | 扫描 `~/.dws/shortcuts/*.yaml` → 编译成 `Shortcut` → 注册 |
+| 管理命令 | `internal/shortcut/usage`（cobra） | `dws shortcut list/suggest/add/rm/stats` |
+
+数据流：
+
+```
+CallMCP ──► recorder.Append(usage)                 [写侧，热路径，必须极轻]
+                                    ┌─► miner.TopCandidates()  [读侧，suggest 时才算]
+~/.dws/usage.jsonl ─────────────────┤
+                                    └─► nudge (命令收尾抽样触发)
+~/.dws/shortcuts/*.yaml ──► loader.Compile() ──► shortcut.Register()  [启动时]
+```
+
+## 2. Usage 埋点
+
+### 2.1 采集点（choke point）
+
+**首选**：装饰 `executor.Runner` / `edition.ToolCaller`。`internal/app/tool_caller_adapter.go`
+的 `CallTool(ctx, productID, toolName, args)` 是**所有 MCP 调用的唯一必经点**，天然拿到
+`(product, tool, args)` 三元组。用装饰器包一层即可，零侵入命令层：
+
+```go
+type recordingCaller struct{ inner edition.ToolCaller }
+func (r recordingCaller) CallTool(ctx, product, tool string, args map[string]any) (*edition.ToolResult, error) {
+    res, err := r.inner.CallTool(ctx, product, tool, args)
+    usage.Append(product, tool, args, err == nil)   // 异步/带 recover，绝不影响主流程
+    return res, err
+}
+```
+
+> 注意：P1 的 shortcut 也走这条 `CallMCP → helpers → deps.Caller`，所以内建 shortcut 的
+> 使用同样会被记录，可用于「哪些内建 shortcut 最受欢迎」的洞察。
+
+### 2.2 记录内容（**隐私优先：记形状不记值**）
+
+`~/.dws/usage.jsonl`，每行一条：
+
+```json
+{
+  "ts": "2026-07-08T10:12:33+08:00",
+  "product": "chat",
+  "tool": "send_message",
+  "arg_keys": ["open_conversation_id", "text"],
+  "const_args": {"open_conversation_id": "cid_x"},
+  "ok": true
+}
+```
+
+- `arg_keys`：参数键集合（排序），用于识别「同一种调用形状」。
+- `const_args`：**仅收敛出的「疑似固定值」**（见 §3 挖掘时判定），写入时不保证脱敏，
+  因此需要一层白名单/黑名单：`text/content/body/message` 等自由文本字段**永不入库**，
+  只保留看起来像 ID/枚举的短值（长度阈值 + 无空格 + 非多行）。
+- 绝不记录：token、手机号、邮箱、文件内容、消息正文。用 `internal/logging/redact.go`
+  已有的脱敏能力复核。
+
+### 2.3 热路径约束
+
+- 追加写用 `O_APPEND`，单行 < 1KB；失败静默（`recover` + debug 日志），**绝不阻断命令**。
+- 文件滚动：超过 N 行（如 5000）或 M 天，截断/归档，避免无限增长。
+- 开关：默认关闭（opt-in），环境变量 `DWS_USAGE_TRACKING=1` 开启（本地遥测即便只记形状也不应未经用户同意默认开启）。
+  首次启用时在 `dws` 首跑给一次性告知（尊重知情）。
+
+## 3. 模式挖掘
+
+`dws shortcut suggest` 触发（也被 nudge 复用）。算法：
+
+1. 读 usage.jsonl，按 `(product, tool, arg_keys)` 分桶。
+2. 对每桶：
+   - `count` = 出现次数；低于阈值（默认 5）直接丢弃。
+   - 对每个 arg_key，统计其值的分布：某值占比 ≥ 80% → 判定为**固定值**（进 `const_args`）；
+     否则判定为**可变参数**（沉淀后成为 flag）。
+   - `recency` = 最近一次使用距今；越近权重越高。
+3. 打分 `score = count * log(distinct_days+1) * recencyDecay`，取 TopN。
+4. 生成候选 `Candidate{product, tool, fixed{...}, varFlags[...], score, samples}`。
+
+输出示例（`dws shortcut suggest --format table`）：
+
+```
+候选  | 命令建议            | 依据                     | 固定参数           | 可变flag
+#1    | chat +notify-team  | 12 次 / 近 3 天          | open_conv=cid_x    | text
+#2    | doc +new-agenda    | 7 次 / 近 5 天           | template=agenda    | title
+```
+
+## 4. 主动提示（nudge）
+
+- **时机**：命令成功收尾时（root `PersistentPostRunE`），**抽样**触发（如每 N 次调用或每次
+  命中新达标候选时），避免打扰。仅在 TTY 交互态提示；非交互（Agent/管道/`--yes`）**不提示**。
+- **频控**：同一候选提示过一次被拒后，冷却期内不再提示（记 `~/.dws/shortcuts/.declined`）。
+- **交互**：
+  ```
+  💡 检测到高频操作：你已 12 次向同一会话发消息。
+     沉淀为快捷指令  dws chat +notify-team --text "..."  ？
+     [y] 沉淀  [n] 以后再说  [d] 不再提示此项
+  ```
+- y → 走 §5 生成 YAML；命名默认 `+<tool 去下划线的动宾>`，允许用户改名。
+
+## 5. 自定义 Shortcut：YAML 格式与运行时加载
+
+### 5.1 YAML schema（与 P1 `Shortcut` 一一对应）
+
+`~/.dws/shortcuts/chat.notify-team.yaml`：
+
+```yaml
+version: 1
+service: chat
+command: "+notify-team"
+product: chat
+description: "发消息到 项目群（自动沉淀于 2026-07-08）"
+risk: write                    # 默认 read；send 类判定为 write
+source: auto                   # auto=沉淀 / manual=手写
+flags:
+  - name: text
+    type: string
+    required: true
+    desc: 消息内容
+execute:
+  tool: send_message
+  bind:                        # 参数绑定：常量 + ${flag} 模板
+    open_conversation_id: "cid_x"
+    text: "${text}"
+```
+
+### 5.2 编译与注册
+
+`userdef.Compile(yaml)` → `shortcut.Shortcut`，其 `Execute` 由 `bind` 生成：
+遍历 `bind`，`${flag}` 用 `rt.Str(flag)` 填充，常量原样，组装 params 后 `rt.CallMCP(tool, params)`。
+完全复用 P1 的 runner，不新增执行路径。
+
+加载时机：`legacy.go` 装配点，在 `builtin.Commands()` 之后追加 `userdef.Commands()`，
+一起 merge。复用 `internal/plugin/loader.go` 已验证的「扫 `~/.dws/` 目录 + 挂 cobra」模式。
+
+### 5.3 冲突与优先级
+
+- 自定义 shortcut 命令名若与内建 shortcut / helper 冲突：**内建优先**，自定义重命名或跳过并告警。
+- `+` 前缀天然与 helper leaf 区分，冲突面小。
+
+## 6. 管理命令面
+
+```
+dws shortcut list                 # 列出内建 + 自定义 shortcut
+dws shortcut suggest [--min N]    # 展示高频候选（不写入）
+dws shortcut add <candidate|--from-last>   # 交互式/从最近一次调用沉淀
+dws shortcut rm <service> <+cmd>  # 删除自定义 shortcut
+dws shortcut stats                # usage 统计概览
+```
+
+`dws shortcut` 本身作为一个新的顶层 utility 命令注册（对齐 `dws plugin`）。
+
+## 7. 安全与隐私边界（红线）
+
+1. **值不入库**：自由文本/正文/凭证一律不记；`const_args` 仅短 ID/枚举，且过 redact 复核。
+2. **可关可清**：`DWS_USAGE_TRACKING=0` 关闭；`dws shortcut stats --purge` 清空 usage。
+3. **执行白名单**：自定义 shortcut 的 `execute.tool` 必须解析到合法 MCP server（过
+   `internal/security` endpoint 白名单），禁止指向任意 endpoint。
+4. **不自动执行**：沉淀只生成命令定义，**绝不**自动发起写操作；写类 shortcut 仍受 P1 的
+   risk 确认约束。
+5. **知情**：首次开启埋点一次性告知；提示可永久关闭。
+
+## 8. 实现顺序（P2 分步，便于 loop 推进）
+
+- P2-1 usage 埋点：`recordingCaller` 装饰器 + `usage.Append` + jsonl 写 + 开关 + 脱敏白名单。
+- P2-2 `dws shortcut stats` / `list`：先让数据可见，验证埋点质量。
+- P2-3 miner + `dws shortcut suggest`：离线挖掘与打分。
+- P2-4 userdef YAML 加载 + `Compile` + 注册 + 冲突处理（打通「手写 YAML 也能用」）。
+- P2-5 `dws shortcut add`（从候选/最近调用沉淀）。
+- P2-6 nudge 主动提示（最后做，最谨慎，默认保守频控）。
+
+## 9. 待决策点（需产品确认）
+
+1. 埋点默认开还是默认关？→ **修订后：默认关（opt-in）+ 开启后首跑一次性告知**（原设计默认开，反思后改为 opt-in：自主 agent 不应单方面默认开本地遥测）
+   （`DWS_USAGE_TRACKING=0` / 配置项关闭；`dws shortcut stats --purge` 清空）。实现时以此为准。
+2. `const_args` 允许记录的字段白名单粒度？（保守起步：只记形如 `*_id/*Id/type/status` 的短值）
+3. nudge 触发频率与渠道？（建议：仅 TTY、命中新候选时、每候选一生仅一次）
+4. 自定义 shortcut 是否需要跨设备同步？（v1 先本地 `~/.dws/`，同步留待后续）

docs/shortcut-plan.md

@@ -0,0 +1,127 @@
+# DWS Shortcut 能力 — 总体规划
+
+> 目标：为 dws 引入一套 **声明式高保真命令（Shortcut）** 能力，对齐 larksuite/cli 的 `+command`
+> 体验（如 `lark-cli contact +search-user`），并在此之上做 dws 差异化：**基于用户高频使用场景，
+> 主动把常用操作沉淀为自定义 shortcut**。
+
+## 1. 背景与动机
+
+dws 当前的命令有三类来源：
+
+1. **MCP 运行时动态发现** —— `dws mcp <service> <tool> --json '{...}'`，通用但裸、参数需手拼 JSON。
+2. **`internal/helpers/` 产品命令** —— 手写 cobra 命令，体验好但每个都从零写、缺统一框架。
+3. **`internal/registry/recipes.yaml`** —— 多步工作流的静态描述。
+
+痛点：想新增一个「精选、参数友好、带 dry-run/format/身份」的单命令，只能手写 helper，
+没有统一的声明式框架，重复劳动多、一致性差。larksuite 的 shortcut 框架正好解决这一层。
+
+## 2. 与 larksuite/cli 的架构差异（关键）
+
+| 维度 | larksuite/cli | dws-cli |
+|------|---------------|---------|
+| 命令来源 | 静态硬编码 Go shortcut | MCP 运行时动态发现 + helpers |
+| 调用底座 | Lark SDK 直连 API | MCP JSON-RPC（`executor.Runner`） |
+| 精选命令层 | `shortcuts/`（200+ 声明式） | `internal/helpers/`（手写 cobra） |
+| 全局 flag | 框架注入 | root 已内建 `--format/--dry-run/--jq/--yes/--fields/--profile` |
+
+**结论**：不能直接搬代码。移植的是 shortcut 的**声明式设计**，执行底座换成 dws 的
+`executor.Runner`，全局能力复用 dws 已有的 output/safety/auth。
+
+## 3. 分期目标
+
+### P1 — 静态声明式框架（本期，正在做）
+- 新建独立模块 `internal/shortcut/`（零侵入现有 helpers）。
+- `types.go`：`Shortcut` / `Flag` / `RuntimeContext` 声明层。
+- `runner.go`：把 `Shortcut` 编译成 `*cobra.Command`，串起 flag 注册 → 校验 → dry-run →
+  `executor.Runner.Run` → `output.WriteCommandPayload`。
+- `register.go`：按 service 分组产出命令，在 `internal/app/legacy.go` 装配点 merge 进命令树。
+- 样板命令 `contact +search-user`：打通 MCP 执行 / format / dry-run / 身份，作为后续命令模板。
+- 交付判据：`dws contact +search-user --help`、`--dry-run` 正常；`go build` / `go test` 通过。
+
+### P2 — 高频场景自动沉淀（后续，先设计再实现）
+- **使用埋点**：命令执行入口记录 `~/.dws/usage.jsonl`（只记参数形状，不记敏感值）。
+- **模式挖掘**：`dws shortcut suggest` 聚合高频 `(service, tool, 固定参数组合)`。
+- **主动沉淀**：命中候选时提示用户，一键写入 `~/.dws/shortcuts/*.yaml`（声明式，与 P1 结构对应）。
+- **运行时加载**：`register.go` 额外扫描 `~/.dws/shortcuts/*.yaml` 动态注册，复用
+  `internal/plugin/loader.go` 已验证的「从 `~/.dws/` 加载并挂 cobra 命令」模式。
+
+## 4. 落地方式（P1）
+
+采用**独立模块 + 装配点 merge**，不改 helpers 内部：
+
+```
+internal/shortcut/
+  types.go            # Shortcut / Flag / RuntimeContext
+  runner.go           # 声明式→cobra 编译 + 执行管道
+  register.go         # Commands(runner) []*cobra.Command，按 service 分组
+  contact/
+    search_user.go    # 样板：var SearchUser = shortcut.Shortcut{...}
+    shortcuts.go      # Shortcuts() []shortcut.Shortcut
+```
+
+接线：`internal/app/legacy.go: newLegacyPublicCommands` 里，
+`helpers.NewPublicCommands(runner)` 之后追加 `shortcut.Commands(runner)`，
+一起走 `mergeTopLevelCommands`（同名 service 命令自动合并，`+xxx` 作为其子命令）。
+
+复用点：
+- 执行：`executor.NewHelperInvocation` + `runner.Run`（与 helper 完全一致的调用路径）。
+- 输出：`output.WriteCommandPayload(cmd, resp, output.FormatJSON)`（自动吃 root 的 `--format/--jq/--fields`）。
+- dry-run：读 root `--dry-run`，置 `Invocation.DryRun`，由 runner 返回请求预览。
+- 身份/安全：复用 `--profile`、`internal/safety`（高风险 `--yes` 确认）。
+
+## 5. Shortcut 声明模型（草案）
+
+```go
+type Shortcut struct {
+    Service     string   // "contact"       → 顶层命令
+    Command     string   // "+search-user"  → 子命令（保留 + 前缀，对齐 larksuite）
+    Description string
+    Risk        string   // read | write | high-risk-write
+    Flags       []Flag
+    Validate    func(*RuntimeContext) error
+    Execute     func(*RuntimeContext) error   // 必填；内部调 rt.CallMCP(...)
+}
+
+type Flag struct {
+    Name, Type, Default, Desc string
+    Required bool
+    Enum     []string
+}
+```
+
+`RuntimeContext` 给 Execute 提供：flag 读取（`Str/Bool/Int/StrSlice/Changed`）、
+`CallMCP(product, tool, params)`（内部 `runner.Run`）、`Output(payload)`、`DryRun()`。
+
+## 6. 风险与边界
+
+- **与 `dws mcp` 通道的边界**：shortcut 是「人工精选的薄封装」，不替代通用 MCP 通道；
+  一个 tool 可以既能 `dws mcp` 直调，也能有 shortcut。
+- **自定义 shortcut 安全（P2）**：YAML 的 `execute` 若允许任意 MCP 调用，需过
+  `internal/security` 的 endpoint 白名单，且沉淀的参数值要脱敏。
+- **命名冲突**：`+` 前缀天然与现有 leaf 命令区分，降低与 helper 命令的冲突面。
+- **edition 差异**：oss / enterprise 的可用 service 不同，注册时按 edition 过滤（后续接入）。
+
+## 7. 进度看板
+
+- [x] P1-1 types.go — `Shortcut` / `Flag` / `Risk` 声明层
+- [x] P1-2 runner.go — `RuntimeContext` + `mount` 编译 + 校验/确认/dry-run；`CallMCP` 委托 `helpers.CallMCPToolOnServer`（复用错误分类/输出/dry-run）
+- [x] P1-3 register.go + `internal/shortcut/contact/search_user.go` + `builtin` 聚合包
+- [x] P1-4 接线 `legacy.go`（append 到 `mergeTopLevelCommands`）+ build/test 全绿
+- [ ] P2 设计文档（进行中）
+
+### P1 落地实证（已验证）
+
+- `dws contact +search-user --help`：命令挂载，继承全局 `--format/--dry-run/--jq/...`。
+- 必填校验：不传 `--query` → 结构化 validation 错误。
+- `--dry-run`：走 helpers 路径输出 `[DRY-RUN]` 预览（tool + 参数）。
+- 命令树 merge：`+search-user` 与现有 `user/dept/label/relation` 共存，`contact user search` 未受影响。
+- 测试：`internal/shortcut` 单测通过；`internal/app` 全量回归通过。
+
+### P1 关键决策记录
+
+- **执行底座复用 helpers 而非裸 `runner.Run`**：`CallMCP` 委托 `helpers.CallMCPToolOnServer(product, tool, params)`，
+  一步获得错误分类（auth/PAT/业务）+ 格式化输出 + dry-run，避免重造劣质输出层。代价是
+  `internal/shortcut → internal/helpers` 的单向依赖（无环）。后续若要 shortcut 做多调用编排/输出重塑，
+  再补一个返回原始 payload 的 `CallMCPRaw`。
+- **避免 import 环**：service 包（contact）import 核心 `shortcut` 包并在 `init()` 注册；
+  `builtin` 聚合包 blank-import 各 service 包；`app` 只依赖 `builtin`。

docs/shortcut-real-test-followups.md

@@ -0,0 +1,168 @@
+# Shortcut 真实测试跟进清单
+
+生成时间：`2026-07-15T16:58:39`
+
+来源：`docs/shortcut-real-read-results.json` 与 `docs/shortcut-real-write-results.json`。
+
+口径：记录真实后端测试中需要继续定位的 case，用于 CR 和问题分派；Agent 使用入口以公开 shortcut catalog 和产品 skill 为准。
+
+总计：156 条。
+
+| # | suite | shortcut | risk | status | category | fixability | 处理依据 |
+|---:|---|---|---|---|---|---|---|
+| 1 | read | `aitable +base-get-primary-doc-id` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 2 | read | `aitable +chart-share-get` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 3 | read | `aitable +dashboard-share-get` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 4 | read | `aitable +export-data` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 5 | read | `aitable +record-primary-doc-get` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 6 | read | `aitable +role-get` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 7 | read | `aitable +workflow-get` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 8 | read | `aitable +workflow-list` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 9 | read | `attendance +get-class` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 10 | read | `attendance +get-global-setting` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 11 | read | `attendance +get-group` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 12 | read | `attendance +get-group-filtered` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 13 | read | `attendance +get-leave-balance` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 14 | read | `attendance +list-report-columns` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 15 | read | `attendance +query-report-leave` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 16 | read | `calendar +find-room` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 17 | read | `calendar +room-find` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 18 | read | `chat +category-list-conversations` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 19 | read | `chat +chat-get-by-id` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 20 | read | `chat +chat-members-get` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 21 | read | `chat +chat-messages` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 22 | read | `chat +messages-list` | read | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 23 | read | `chat +messages-resource-url` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 24 | read | `chat +search-msg` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 25 | read | `chat +thread-replies` | read | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 26 | read | `contact +get-roster` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 27 | read | `contact +list-roster-fields` | read | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 28 | read | `devapp +credentials-get` | read | held | held | manual-approval | 高风险或无安全目标，需人工逐项授权后执行。 |
+| 29 | read | `drive +download` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 30 | read | `drive +list` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 31 | read | `minutes +action-items` | read | real-error | missing-real-minutes-fixture | not-cli-fixable-without-fixture | 当前账号没有满足条件的妙记/听记或录制会话；需准备真实会议产物后复测。 |
+| 32 | read | `minutes +latest-minutes` | read | real-error | missing-real-minutes-fixture | not-cli-fixable-without-fixture | 当前账号没有满足条件的妙记/听记或录制会话；需准备真实会议产物后复测。 |
+| 33 | read | `minutes +minutes-search` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 34 | read | `minutes +transcript` | read | real-error | missing-real-minutes-fixture | not-cli-fixable-without-fixture | 当前账号没有满足条件的妙记/听记或录制会话；需准备真实会议产物后复测。 |
+| 35 | read | `oa +done-approvals` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 36 | read | `oa +pending` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 37 | read | `report +report-latest` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 38 | read | `todo +due-today` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 39 | read | `todo +related-tasks` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 40 | read | `wiki +node-list` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 41 | read | `wiki +resolve-space` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 42 | read | `wiki +space-list` | read | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 43 | write | `aitable +advperm-disable` | high-risk-write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 44 | write | `aitable +advperm-enable` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 45 | write | `aitable +attachment-upload` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 46 | write | `aitable +base-copy` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 47 | write | `aitable +base-delete` | high-risk-write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 48 | write | `aitable +base-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 49 | write | `aitable +chart-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 50 | write | `aitable +chart-share-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 51 | write | `aitable +chart-update` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 52 | write | `aitable +dashboard-arrange` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 53 | write | `aitable +dashboard-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 54 | write | `aitable +dashboard-share-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 55 | write | `aitable +dashboard-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 56 | write | `aitable +field-delete` | high-risk-write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 57 | write | `aitable +field-update` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 58 | write | `aitable +form-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 59 | write | `aitable +form-field-hide` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 60 | write | `aitable +form-field-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 61 | write | `aitable +form-share-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 62 | write | `aitable +form-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 63 | write | `aitable +import-data` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 64 | write | `aitable +import-upload` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 65 | write | `aitable +record-delete` | high-risk-write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 66 | write | `aitable +record-primary-doc-create` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 67 | write | `aitable +record-update` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 68 | write | `aitable +record-upsert` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 69 | write | `aitable +role-create` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 70 | write | `aitable +role-delete` | high-risk-write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 71 | write | `aitable +role-update` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 72 | write | `aitable +section-create` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 73 | write | `aitable +section-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 74 | write | `aitable +section-move-node` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 75 | write | `aitable +section-rename` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 76 | write | `aitable +section-reorder` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 77 | write | `aitable +table-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 78 | write | `aitable +table-update` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 79 | write | `aitable +view-delete` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 80 | write | `aitable +view-duplicate` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 81 | write | `aitable +view-lock` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 82 | write | `aitable +view-set-fill-color-rule` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | 后端/MCP 服务返回内部错误；CLI 无法直接修复，但报告保留 trace/stdout 供服务端排查。 |
+| 83 | write | `aitable +view-set-frozen-cols` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 84 | write | `aitable +view-set-row-height` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 85 | write | `aitable +view-update` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 86 | write | `aitable +workflow-disable` | high-risk-write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 87 | write | `aitable +workflow-enable` | write | real-error | missing-real-aitable-fixture | not-cli-fixable-without-fixture | AI 表格命令需要真实 Base/Table/View/Record 等资源；安全负向 ID 只能验证调用链，不能让后端成功。 |
+| 88 | write | `attendance +boss-check` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 89 | write | `attendance +create-class` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 90 | write | `attendance +create-group` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 91 | write | `attendance +import-schedule` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 92 | write | `attendance +save-leave-balance` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 93 | write | `attendance +update-class` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 94 | write | `attendance +update-group` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 95 | write | `attendance +update-group-members` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 96 | write | `attendance +update-leave-type` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 97 | write | `calendar +respond-event` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 98 | write | `chat +category-add-conversation` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 99 | write | `chat +category-remove-conversation` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 100 | write | `chat +chat-add-bot` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 101 | write | `chat +chat-audit-join` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | dry-run 已证明 CLI 装配了 applicantUid/inviterUid；真实后端仍报 applicantUid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 102 | write | `chat +chat-mute-member` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 103 | write | `chat +chat-quit` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 104 | write | `chat +chat-remove-bot` | high-risk-write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 105 | write | `chat +chat-role-remove` | high-risk-write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 106 | write | `chat +chat-role-remove-user` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 107 | write | `chat +chat-transfer-owner` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 108 | write | `chat +chat-update-icon` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 109 | write | `chat +chat-update-settings` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 110 | write | `chat +conversation-clear-messages` | high-risk-write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 111 | write | `chat +conversation-clear-red-point` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 112 | write | `chat +conversation-hide` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 113 | write | `chat +conversation-mark-read` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 114 | write | `chat +conversation-mark-unread` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 115 | write | `chat +conversation-mute` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 116 | write | `chat +conversation-mute-at-all` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 117 | write | `chat +conversation-mute-red-envelope` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 118 | write | `chat +conversation-set-top` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 119 | write | `chat +messages-add-emoji` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 120 | write | `chat +messages-add-text-emotion` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 121 | write | `chat +messages-batch-recall-by-bot` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 122 | write | `chat +messages-batch-send-by-bot` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 123 | write | `chat +messages-combine-forward` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 124 | write | `chat +messages-create-text-emotion` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 125 | write | `chat +messages-forward` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 126 | write | `chat +messages-forward-topic` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 127 | write | `chat +messages-recall` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 128 | write | `chat +messages-recall-by-bot` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 129 | write | `chat +messages-remove-emoji` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 130 | write | `chat +messages-remove-text-emotion` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 131 | write | `chat +messages-send-by-bot` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 132 | write | `chat +messages-send-card` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | dry-run 已证明 CLI 装配了 receiverUid；真实后端仍报 receiverUid/openConversationId 为空，优先按 MCP schema/服务端字段映射问题处理。 |
+| 133 | write | `chat +messages-set-pin` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 134 | write | `chat +messages-set-top` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 135 | write | `chat +messages-unset-pin` | write | real-error | backend-or-mcp-error | not-cli-fixable-first | fake MCP 已证明 CLI 已装配会话 ID 字段；真实后端仍报 openConversationId/openCid/cid 缺失，优先按 MCP schema/服务端字段映射问题处理。 |
+| 136 | write | `chat +messages-unset-top` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 137 | write | `devapp +event-subscribe` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 138 | write | `devapp +event-unsubscribe` | high-risk-write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 139 | write | `devapp +permission-add` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 140 | write | `devapp +permission-remove` | high-risk-write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 141 | write | `devapp +robot-config` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 142 | write | `devapp +robot-disable` | high-risk-write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 143 | write | `devapp +robot-enable` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 144 | write | `devapp +security-config` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 145 | write | `devapp +version-create` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 146 | write | `devapp +version-publish` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 147 | write | `ding +send-by-message` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 148 | write | `doc +comment-create-inline` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 149 | write | `doc +template-apply` | write | real-error | auth-or-permission | not-cli-fixable | 真实账号、应用 scope 或资源权限不足；CLI 只能如实暴露，不能在本仓库内修复权限。 |
+| 150 | write | `minutes +record-pause` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 151 | write | `minutes +record-resume` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 152 | write | `minutes +record-stop` | write | real-error | input-or-business-validation | test-input-or-backend-rule | 命令已真实进入本地/后端校验；若该项仍使用安全负向输入，则失败符合预期；若使用真实 fixture 仍失败，再作为 CLI bug 处理。 |
+| 153 | write | `oa +approve-by` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 154 | write | `wiki +node-copy` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 155 | write | `wiki +node-move` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |
+| 156 | write | `wiki +wiki-new-doc` | write | real-error | missing-real-resource | not-cli-fixable-without-fixture | 真实测试使用的资源/单据/消息/群/文档不存在；需要准备对应 fixture 后才能期望成功，不属于 shortcut 参数投影错误。 |

docs/shortcut-report.html

@@ -0,0 +1,186 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DWS Shortcut 完成情况报告</title>
+<style>
+  :root{--bg:#0f1420;--card:#161d2c;--ink:#e6edf6;--muted:#93a1b5;--line:#26314a;
+    --blue:#4f9cff;--green:#3fb950;--yellow:#d5a429;--red:#f25c5c;--accent:#6ea8fe;--purple:#a371f7}
+  *{box-sizing:border-box}
+  body{margin:0;background:linear-gradient(180deg,#0d1220,#0f1420);color:var(--ink);
+    font:15px/1.7 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;padding:0 0 80px}
+  .wrap{max-width:1080px;margin:0 auto;padding:0 22px}
+  header{padding:52px 22px 28px;text-align:center;border-bottom:1px solid var(--line);
+    background:radial-gradient(1200px 300px at 50% -60px,rgba(79,156,255,.16),transparent)}
+  h1{font-size:29px;margin:0 0 8px;letter-spacing:.5px}
+  .sub{color:var(--muted);font-size:14px}
+  .stats{display:flex;gap:13px;justify-content:center;flex-wrap:wrap;margin:26px 0 4px}
+  .stat{background:var(--card);border:1px solid var(--line);border-radius:14px;padding:15px 20px;min-width:118px}
+  .stat .n{font-size:27px;font-weight:700;color:var(--accent)}
+  .stat .l{color:var(--muted);font-size:12.5px;margin-top:2px}
+  h2{font-size:21px;margin:44px 0 14px;padding-bottom:8px;border-bottom:1px solid var(--line)}
+  h2 .ico{color:var(--accent);margin-right:8px}
+  h3{font-size:15.5px;margin:22px 0 9px;color:var(--accent)}
+  table{width:100%;border-collapse:collapse;margin:12px 0;font-size:13.5px;background:var(--card);
+    border:1px solid var(--line);border-radius:10px;overflow:hidden}
+  th,td{padding:9px 12px;text-align:left;border-bottom:1px solid var(--line);vertical-align:top}
+  th{background:#1b2536;color:var(--muted);font-weight:600;font-size:12.5px}
+  tr:last-child td{border-bottom:none}
+  td.c,th.c{text-align:center}
+  .num{color:var(--accent);font-weight:700;text-align:center}
+  .g{color:var(--green);font-weight:700}.s{color:var(--yellow);font-weight:700}.b{color:var(--red);font-weight:700}
+  .ok{color:var(--green)}.star{color:var(--yellow)}
+  code{background:#0c1120;border:1px solid var(--line);border-radius:5px;padding:1px 6px;font-size:12.5px;color:#cfe0ff}
+  .card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:15px 18px;margin:13px 0}
+  .two{display:grid;grid-template-columns:1fr 1fr;gap:14px}
+  .layer{border-radius:12px;padding:16px 18px}
+  .l-wrap{background:linear-gradient(180deg,rgba(79,156,255,.08),transparent);border:1px solid #234b6b}
+  .l-smart{background:linear-gradient(180deg,rgba(163,113,247,.10),transparent);border:1px solid #4a3a6b}
+  .layer h3{margin-top:0}
+  .pill{display:inline-block;background:#12283a;color:#7fc6ff;border:1px solid #234b6b;border-radius:6px;padding:1px 7px;font-size:12px;margin:2px 3px 2px 0}
+  .flow{display:flex;align-items:center;gap:7px;flex-wrap:wrap;font-size:13px;color:var(--muted)}
+  .flow b{color:var(--ink)}.flow .arw{color:var(--purple)}
+  .concl{background:linear-gradient(90deg,rgba(63,185,80,.10),transparent);border-left:3px solid var(--green);padding:14px 18px;border-radius:8px;margin-top:16px}
+  .keyfind{background:linear-gradient(90deg,rgba(213,164,41,.10),transparent);border-left:3px solid var(--yellow);padding:14px 18px;border-radius:8px;margin:14px 0}
+  footer{color:var(--muted);text-align:center;font-size:12.5px;margin-top:40px}
+  a{color:var(--accent)}
+</style>
+</head>
+<body>
+<header>
+  <h1>DWS Shortcut 完成情况报告</h1>
+  <div class="sub">对齐基准 larksuite/cli　·　执行底座 钉钉 MCP　·　随 loop 持续更新</div>
+  <div class="stats">
+    <div class="stat"><div class="n">366</div><div class="l">shortcut 总数</div></div>
+    <div class="stat"><div class="n">298</div><div class="l">1:1 封装层</div></div>
+    <div class="stat"><div class="n">68</div><div class="l">真·智能层</div></div>
+    <div class="stat"><div class="n">16</div><div class="l">覆盖服务</div></div>
+    <div class="stat"><div class="n">0</div><div class="l">失败/panic/编造</div></div>
+  </div>
+</header>
+<div class="wrap">
+
+  <h2><span class="ico">①</span>做了什么：两个层次</h2>
+  <p>诚实区分——shortcut 分两层，价值定位不同，不混为一谈。</p>
+  <div class="two">
+    <div class="layer l-wrap">
+      <h3>🔵 1:1 封装层 · 298 条</h3>
+      <div style="color:var(--muted);font-size:13.5px">一个 shortcut ≡ 一个 MCP tool。把裸 <code>dws mcp &lt;svc&gt; &lt;tool&gt; --json '{…}'</code> 收敛成命名 flag，附校验/风险确认/Intent。</div>
+      <div style="margin:10px 0"><b>价值</b>：DX 与 AI-agent 可发现性，<b>不是新能力</b>。</div>
+      <div><span class="pill">命名 flag</span><span class="pill">required/enum 校验</span><span class="pill">风险确认</span><span class="pill">自然语言 Intent</span><span class="pill">dry-run/format</span></div>
+    </div>
+    <div class="layer l-smart">
+      <h3>🟣 真·智能层 · 68 条</h3>
+      <div style="color:var(--muted);font-size:13.5px">照 lark-cli 范式的多步/编排/智能，<b>不是 1:1</b>。框架新增 <code>CallMCPData</code>（多步取数，对标 lark <code>CallAPITyped</code>）+ <code>resolveUser</code>（名→ID，对标 <code>ResolveOpenIDsTyped</code>）。</div>
+      <div style="margin:10px 0"><b>价值</b>：<b>这才是「shortcut 作为新能力」</b>。</div>
+      <div><span class="pill" style="background:#241a3a;color:#c9b3ff;border-color:#4a3a6b">按名解析+消歧</span><span class="pill" style="background:#241a3a;color:#c9b3ff;border-color:#4a3a6b">多工具编排</span><span class="pill" style="background:#241a3a;color:#c9b3ff;border-color:#4a3a6b">失败回滚</span><span class="pill" style="background:#241a3a;color:#c9b3ff;border-color:#4a3a6b">跨服务</span></div>
+    </div>
+  </div>
+
+  <h2><span class="ico">②</span>真·智能层 68 条明细（节选）</h2>
+  <table>
+    <thead><tr><th>shortcut</th><th>多步/智能逻辑</th><th class="c">验证</th></tr></thead>
+    <tbody>
+      <tr><td><code>chat +dm --to &lt;名&gt;</code></td><td>搜人→解析 userId→发单聊；多人消歧</td><td class="c ok">真机 dry-run</td></tr>
+      <tr><td><code>contact +lookup --name &lt;名&gt;</code></td><td>搜人→解析→取完整资料</td><td class="c ok">✅ 真机端到端</td></tr>
+      <tr><td><code>todo +assign --to &lt;名&gt;</code></td><td>解析人→建待办并设执行人</td><td class="c ok">真机 dry-run</td></tr>
+      <tr><td><code>contact +org --name &lt;名&gt;</code></td><td>解析人→取 deptId→查部门详情（3 步）</td><td class="c ok">✅ 真机端到端</td></tr>
+      <tr><td><code>contact +team --name &lt;名&gt;</code></td><td>解析人→取部门→列部门成员</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>calendar +free --who &lt;名&gt;</code></td><td>解析人→查其时段忙闲</td><td class="c ok">✅ 真机端到端</td></tr>
+      <tr><td><code>calendar +book [--with &lt;名CSV&gt;]</code></td><td>建日程→按名加参与者→<b>失败回滚删日程</b></td><td class="c ok">真机 dry-run</td></tr>
+      <tr><td><code>calendar +invite --event --with</code></td><td>解析多人→加入已有日程</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>calendar +suggest-time --with</code></td><td>解析多人→推荐可开会时间</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>calendar +today</code></td><td>算今天范围→列我今天日程</td><td class="c ok">✅ 真机端到端</td></tr>
+      <tr><td><code>calendar +next-event</code></td><td>近 7 天→取最近一个日程</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>calendar +reschedule --event</code></td><td>查日程详情→改时间</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>chat +send-to-group --group &lt;群名&gt;</code></td><td>按群名搜群→消歧→发消息</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>chat +group-members --group &lt;群名&gt;</code></td><td>搜群→列群成员</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>chat +broadcast --to &lt;名CSV&gt;</code></td><td>多名逐一解析→群发单聊，失败汇总</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>todo +todo-done --task &lt;关键词&gt;</code></td><td>列我待办→按标题匹配→标完成</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>todo +remind --task --at</code></td><td>给自己建带提醒的待办</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>minutes +latest-minutes</code></td><td>列妙记→取最新一条详情</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>minutes +action-items</code></td><td>列妙记→取最新→取其待办</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>wiki +wiki-new-doc --space &lt;名&gt;</code></td><td>按名搜知识空间→建文档（跨 doc server 路由）</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>doc +doc-append --doc --text</code></td><td>文档末尾追加文本</td><td class="c ok">编译/挂载</td></tr>
+      <tr><td><code>doc +share-doc --to &lt;名&gt; --url</code></td><td>解析人→把文档链接私信 TA（跨服务）</td><td class="c ok">编译/挂载</td></tr>
+    </tbody>
+  </table>
+  <div class="card">
+    <b>质量亮点（agent 严守 ground truth）</b>：<code>+send-to-group</code> 纠正了「按群名搜群」的正确工具（<code>search_groups</code> 而非按成员昵称的 <code>search_common_groups</code>）；<code>+wiki-new-doc</code> 发现 <code>create_file</code> 在 doc server 并正确跨服务路由；<code>+mail-to</code> 因钉钉无 email 字段<b>主动 skip 拒绝编造</b>。
+  </div>
+
+  <h2><span class="ico">③</span>测试验证（零副作用全量）</h2>
+  <p>写/删命令不能真跑，用<b>假 Caller 拦截</b>——每条命令走完「解析→校验→确认→组装 MCP 调用」，捕获组装出的 <code>(product,tool,params)</code>，不真发网络。</p>
+  <table>
+    <thead><tr><th>验证项</th><th>范围</th><th>结果</th></tr></thead>
+    <tbody>
+      <tr><td><code>go build ./...</code> / gofmt / vet</td><td>全仓</td><td class="ok">✅ 0 告警</td></tr>
+      <tr><td>TestAllShortcutsAssemble</td><td>全部 366</td><td class="ok">✅ 322 组装真实MCP · 44 自校验 · 0 失败/panic</td></tr>
+      <tr><td>TestAllToolLiteralsAreReal</td><td>tool 字面量</td><td class="ok">✅ 0 编造（比对 helper ground truth）</td></tr>
+      <tr><td>TestAllHaveIntent</td><td>全部 366</td><td class="ok">✅ 每条均有自然语言描述</td></tr>
+      <tr><td>TestNoDuplicateCommands</td><td>全部</td><td class="ok">✅ 无重复 · 命名规范</td></tr>
+      <tr><td>usage / userdef 单测</td><td>埋点/沉淀</td><td class="ok">✅ 全通过</td></tr>
+      <tr><td>app 包全量回归</td><td>internal/app</td><td class="ok">✅ ~72s 通过（未破坏现有命令）</td></tr>
+      <tr><td>智能层真机验证（9 批）</td><td>只读/解析类 20+ 条</td><td class="ok">✅ 端到端返回真实数据、投影正确</td></tr>
+      <tr><td>真机抓修真实 bug</td><td>合成测试盖不住的投影/解析偏差</td><td class="ok">✅ 修复 8 处（resolve-dept/at-me/group-members/free/today/suggest-time/unread-chats/dept-members）</td></tr>
+    </tbody>
+  </table>
+  <p style="color:var(--muted);font-size:13px">真机验证补齐了 assemble 测试的盲区：合成响应验证不了「防御式投影是否匹配真实响应结构」。9 批真机验证抓到并修复 8 处解析/投影偏差（如 <code>+resolve-dept</code> 漏了真实容器 key <code>deptList</code>、<code>+at-me</code> 未拍平嵌套、<code>+today/+free</code> 直吐冗长 raw）。少数命令（chat 会话消息读、minutes）因 org/PAT 权限受限无法真机跑通，组装链路仍由 assemble 测试覆盖。</p>
+
+  <h2><span class="ico">④</span>效果评估 GSB（vs lark-cli）</h2>
+  <h3>4.1 能力覆盖 GSB（按 dws 实际暴露的 MCP tool 数 = helper∪shortcut，非 shortcut 数）</h3>
+  <table>
+    <thead><tr><th>lark 服务</th><th class="c">lark</th><th>dws</th><th class="c">dws</th><th class="c">GSB</th><th>说明</th></tr></thead>
+    <tbody>
+      <tr><td>im</td><td class="c">21</td><td>chat</td><td class="c">95</td><td class="c g">G</td><td>群/消息/机器人更全</td></tr>
+      <tr><td>mail</td><td class="c">21</td><td>mail</td><td class="c">43</td><td class="c g">G</td><td>覆盖更广</td></tr>
+      <tr><td>doc</td><td class="c">14</td><td>doc</td><td class="c">34</td><td class="c g">G</td><td>块级读写更细</td></tr>
+      <tr><td>minutes</td><td class="c">14</td><td>minutes</td><td class="c">25</td><td class="c g">G</td><td>录音/说话人更全</td></tr>
+      <tr><td>calendar</td><td class="c">12</td><td>calendar</td><td class="c">24</td><td class="c g">G</td><td>会议室/ACL 更全</td></tr>
+      <tr><td>contact</td><td class="c">2</td><td>contact</td><td class="c">15</td><td class="c g">G</td><td>部门/角色/花名册更全</td></tr>
+      <tr><td>wiki</td><td class="c">12</td><td>wiki</td><td class="c">16</td><td class="c g">G</td><td>略优</td></tr>
+      <tr><td>base</td><td class="c">87</td><td>aitable</td><td class="c">79</td><td class="c s">S</td><td>持平；helper 仅 16，<b>shortcut 补齐 +63</b>（真 gap-fill）</td></tr>
+      <tr><td>task</td><td class="c">18</td><td>todo</td><td class="c">20</td><td class="c s">S</td><td>持平</td></tr>
+      <tr><td>drive</td><td class="c">26</td><td>drive</td><td class="c">25</td><td class="c s">S</td><td>持平</td></tr>
+      <tr><td>apps</td><td class="c">63</td><td>devapp</td><td class="c">25</td><td class="c b">B</td><td><b>helper 无 devapp，25 全由 shortcut 补</b>，但仍少于 lark</td></tr>
+      <tr><td>sheets</td><td class="c">84</td><td>sheet</td><td class="c">60</td><td class="c b">B</td><td>钉钉表格 MCP 较少；helper 已覆盖</td></tr>
+      <tr><td>vc/okr/slides/markdown/whiteboard/note/event</td><td class="c">62</td><td>—</td><td class="c">0</td><td class="c b">B</td><td>钉钉无对应能力，<b>客观不可对齐</b></td></tr>
+    </tbody>
+  </table>
+  <div style="color:var(--muted);font-size:13px;margin:6px 0 2px">🟢 G 7 领域　·　🟡 S 3 领域　·　🔴 B（apps/sheets 少于 lark + 6 领域钉钉无能力）。base 的"持平"几乎全靠 shortcut gap-fill（helper 仅 16）。dws 独有：oa/attendance/report/ding/aisearch/live/devdoc。</div>
+
+  <h3>4.2 组合/智能层 GSB（关键发现）</h3>
+  <div class="keyfind">
+    <b>关键结论</b>：lark 有 ~104 个组合(≥2 次 API)shortcut，但 <b>lark 的组合性多源于飞书 REST API 太细粒度</b>（要先查 spreadsheetToken→sheetId→再操作）；<b>钉钉 MCP 是粗粒度的——一个 tool = 一个完整操作</b>，所以 lark 的组合在钉钉这边<b>大量塌缩成 1:1</b>（已被封装层覆盖），或<b>根本没有对应 tool</b>。
+  </div>
+  <table>
+    <thead><tr><th>lark 组合来源</th><th class="c">数量</th><th class="c">GSB</th><th>钉钉现实</th></tr></thead>
+    <tbody>
+      <tr><td>sheets（先解析 sheetId）</td><td class="c">41</td><td class="c s">S</td><td>钉钉直接吃 token → 1:1 层已覆盖</td></tr>
+      <tr><td>apps db-env/audit/log/trace</td><td class="c">17</td><td class="c b">B</td><td>钉钉无对应工具</td></tr>
+      <tr><td>drive/doc/im（上传/媒体/搜索）</td><td class="c">23</td><td class="c s">S</td><td>多为钉钉 1:1 已覆盖</td></tr>
+      <tr><td>calendar/contact/wiki/minutes/todo 编排</td><td class="c">~10</td><td class="c g">G</td><td>✅ 已建为真·智能 shortcut（+book/+lookup/+org/+wiki-new-doc/+reschedule…）</td></tr>
+      <tr><td>okr/whiteboard/slides/vc</td><td class="c">11</td><td class="c b">B</td><td>钉钉无对应能力</td></tr>
+    </tbody>
+  </table>
+  <div style="color:var(--muted);font-size:13px">→ 钉钉真正需要「组合」的场景（按名解析+多工具编排+跨服务），dws 已覆盖并<b>额外做了 lark 没有的</b>（+today/+broadcast/+share-doc/+action-items 等）。<b>不盲目复刻 lark 的机械多步</b>（在钉钉会成冗余假组合）。</div>
+
+  <h2><span class="ico">⑤</span>dws 差异化优势</h2>
+  <div class="card"><b>复用生产级 MCP 通道</b>（架构性）—— <code>CallMCP</code> 统一继承错误分类(auth/PAT/业务)、dry-run、<code>--format/--jq/--fields</code>；lark 每命令各自实现。</div>
+  <div class="card"><b>协作能力覆盖更全</b> —— chat 95/mail 43/doc 34/minutes 25（dws tool 覆盖）是 lark 对应 2–4 倍。</div>
+  <div class="card"><b>钉钉原生特有能力</b>（lark 完全没有）—— 审批/日志/考勤/DING/企业智能搜索，75 条差异化封装。</div>
+  <div class="card"><b>真·智能编排（22 条）</b> —— 按名解析+消歧、失败回滚、跨服务；<code>resolveUser</code>/<code>CallMCPData</code> 让新智能 shortcut 越写越快。</div>
+  <div class="card"><b>高频自动沉淀（P2 · lark 无此设计）</b>
+    <div class="flow" style="margin-top:9px"><b>高频使用</b><span class="arw">→</span><b>埋点</b><span class="arw">→</span><b>suggest</b><span class="arw">→</span><b>add 写 YAML</b><span class="arw">→</span><b>运行时加载可用</b></div>
+  </div>
+  <div class="card"><b>工程质量</b> —— 假 Caller 拦截，366 条（含写/删）零副作用全量验证，可复跑回归。</div>
+
+  <div class="concl">
+    <b>一句话结论</b>：dws 已把钉钉侧<b>能对齐的都对齐</b>（366 条 = 298 封装 + 68 智能 / 16 服务，1:1 层已去 213 条纯重复），即时协作显著优于 lark，拥有审批/考勤/DING 等原生差异化能力与「高频自动沉淀」独有闭环。lark 的组合优势多因飞书 API 细粒度、在钉钉粗粒度 MCP 下塌缩为 1:1（已覆盖），真正需编排的钉钉侧已建齐；受限项均为钉钉客观无对应能力，非工程遗漏。全部 366 条通过零副作用全量验证。
+  </div>
+
+  <footer>DWS Shortcut Report · 由持续精进 loop 维护 · 另见 <a href="shortcut-comparison.html">逐条三方对照 HTML</a> · <a href="shortcut-report.md">Markdown 版</a></footer>
+</div>
+</body>
+</html>

docs/shortcut-report.md

@@ -0,0 +1,289 @@
+# DWS Shortcut 能力整合与对齐报告
+
+> 版本：截至本轮 loop　|　对齐基准：larksuite/cli（lark-cli）　|　执行底座：钉钉 MCP
+> 相关文档：[总规划](shortcut-plan.md) · [P2 自动沉淀设计](shortcut-p2-design.md) · [HTML 报告](shortcut-report.html) · [**逐条三方对照 HTML**](shortcut-comparison.html)（每个 shortcut：dws +命令 vs lark-cli vs 原生 MCP 组合）
+
+---
+
+## 1. Shortcut 整合了哪些能力
+
+`dws` 现内建 **298 个 1:1 封装 shortcut** + **68 条 smart 智能编排命令**（§1.3）= **合计 366 条**，覆盖 **16 个钉钉服务**，以 `dws <service> +<command>` 形式提供。
+
+> ⚠️ **重要修订（去冗余）**：1:1 层原为 511 条，**复盘发现 `internal/helpers/` 早已把大量 MCP tool 封装成 `dws <svc> <verb>` 产品命令**——其中 **213 条 1:1 shortcut 只是把已被 helper 封装过的同一个 tool 用 `+` 前缀又封了一遍、且无输出投影增量，属纯重复**，已删除。**保留的 298 条 = 233 条填 helper 空白（helper 从没封装的 tool）+ 65 条虽 tool 重复但加了干净投影**。这是对"建 1:1 层前没先摸清 helper 已封装什么"的纠偏（详见 §5 复盘）。aisearch/live/devdoc 三个服务的 shortcut 全属纯重复、已整包移除（其 `dws <svc>` 命令仍由 helper 层提供）。
+
+### 1.1 能力清单（按服务，prune 后）
+
+| 服务 | 1:1 shortcut 数 | 覆盖能力（摘要） |
+|------|:---:|------|
+| chat（群聊/消息） | 79 | 群管理、群成员、群身份角色、消息收发/撤回/转发/表情/卡片、会话置顶/免打扰、消息分组、机器人 |
+| aitable（多维表 base） | 77 | 数据表/字段/记录/视图/表单/仪表盘/图表/角色/协作全生命周期 |
+| attendance（考勤）★ | 33 | 打卡记录、审批、排班、班次、考勤组、统计报表、请假 |
+| devapp（开放平台应用 apps） | 30 | 应用增删改查、成员、权限、版本发布、事件订阅、扩展机器人/H5 配置 |
+| doc（文档） | 16 | 文档/文件夹、正文块读写、权限、附件、节点 |
+| contact（通讯录） | 9 | 用户/部门搜索与详情、角色、花名册 |
+| drive（钉盘） | 8 | 文件/文件夹管理、下载、复制移动、权限、最近访问 |
+| calendar（日历） | 8 | 日程、参与人、会议室、忙闲、ACL、日历本 |
+| minutes（AI 听记） | 7 | 妙记详情/逐字稿、录音控制、说话人 |
+| oa（审批）★ | 6 | 审批实例、单据处理、模板、流程 |
+| mail（邮箱） | 6 | 邮件搜索/线程、标签、联系人、收信规则（投影类保留） |
+| wiki（知识库） | 5 | 知识空间、节点、成员 |
+| todo（待办 task） | 5 | 待办、子任务、执行人/参与人、附件 |
+| ding（DING）★ | 5 | 机器人/个人 DING 发送、撤回、接收状态 |
+| sheet（钉钉表格） | 2 | 区域读写（投影类保留） |
+| report（日志）★ | 2 | 日志收件箱/发件箱 |
+| **合计** | **298** | **16 个服务** |
+
+★ = 钉钉特有服务，lark-cli 无对应（详见 §3 GSB）。**注**：多数服务的 `shortcut 数` 已远小于该服务的 MCP tool 总数——因为 tool 的基础封装由 helper 层的 `dws <svc> <verb>` 命令承担，1:1 shortcut 只保留 helper 没覆盖的、或加了投影的。
+
+### 1.2 每个 shortcut 统一具备的能力（框架注入）
+
+不是简单命令别名，而是叠加在裸 MCP 之上的**精选薄封装**，统一获得：
+
+- **声明式定义**：`Shortcut{Service, Command, Product, Risk, Flags, Execute}`，一处声明、框架编译成 cobra 命令。
+- **自然语言 Intent**：每条 shortcut 均带一段自然语言描述（做什么/何时用/关键输入产出，写删类点明副作用），面向用户与 AI agent 的意图匹配；`--help` 展示为长描述，`dws shortcut list` 输出 `intent` 字段。全部 366 条覆盖（`TestAllHaveIntent` 强制校验）。
+- **参数收敛**：把裸 `dws mcp <svc> <tool> --json '{...}'` 的手拼 JSON，收敛成命名 flag（`--query`/`--group`…）。
+- **内建校验**：required / enum 声明式校验，结构化错误提示。
+- **风险确认**：read / write / high-risk-write 分级，写/删操作 `--yes` 前二次确认。
+- **复用生产级 MCP 通道**：错误分类（auth/PAT/业务）、`--dry-run` 预览、`--format`/`--jq`/`--fields` 输出，全部免费继承（详见 §4）。
+
+### 1.3 两个层次：1:1 封装层 vs 真·多步/智能层（重要澄清）
+
+诚实区分——上面 298 条**绝大多数是 1 shortcut ≡ 1 个 MCP tool 的 1:1 封装**，本质是「给 MCP 套命名 flag + 校验 + Intent 的友好外壳」，价值在 DX 与 agent 可发现性，**不是新能力**。
+
+真正的「shortcut 作为新能力」是 `internal/shortcut/smart/` 下的**多步/智能** shortcut——照 larksuite/cli 的实现范式（`CallAPITyped` 链式多步、按名解析 ID、Validate、DryRun 计划、失败回滚）落地。框架为此新增 `RuntimeContext.CallMCPData(product, tool, params)`（对应 lark 的 `CallAPITyped`：调用并返回 data 供下一步，跨服务）。
+
+已落地的真·智能 shortcut（`internal/shortcut/smart/`，共 68 条，下表为代表性节选）：
+
+| shortcut | 多步/智能逻辑 | 验证 |
+|----------|--------------|------|
+| `chat +dm --to <姓名> --text` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 |
+| `contact +lookup --name <姓名>` | 搜人→解析 userId→取完整资料 | ✅ **真机端到端** |
+| `todo +assign --to <姓名> --task` | 解析人→建待办并把 TA 设为执行人 | ✅ dry-run 真机 |
+| `chat +send-to-group --group <群名> --text` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 |
+| `calendar +book --title --start --end [--with <姓名CSV>]` | 建日程→按名加参与者→**失败回滚删日程**（对标 lark `calendar +create`） | ✅ dry-run 真机 |
+| `calendar +free --who <姓名> --start --end` | 解析人→查其时段忙闲 | ✅ **真机端到端**（解析 202397→查忙闲） |
+| `chat +broadcast --to <姓名CSV> --text` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 |
+| `minutes +latest-minutes` | 列妙记→取最新一条详情 | ✅ 编译/挂载 |
+| `chat +group-members --group <群名>` | 按群名搜群→列群成员 | ✅ 编译/挂载 |
+| `contact +org --name <姓名>` | 解析人→取详情拿 deptId→查部门详情 | ✅ **真机端到端**（3 步：董鑫阳→模型算法/16人） |
+| `calendar +suggest-time --with <姓名CSV>` | 解析多人→推荐可开会时间 | ✅ 编译/挂载 |
+| `calendar +invite --event <id> --with <姓名CSV>` | 解析多人→加入已有日程 | ✅ 编译/挂载 |
+| `doc +share-doc --to <姓名> --url` | 解析人→把文档链接私信 TA | ✅ 编译/挂载 |
+| `calendar +today` | 算出今天时间范围→列我今天的日程 | ✅ **真机端到端**（返回真实日程+参会人） |
+| `calendar +next-event` | 近 7 天日程→按时间取最近一个 | ✅ 编译/挂载 |
+| `contact +team --name <姓名>` | 解析人→取部门→列部门直接成员 | ✅ 编译/挂载 |
+| `todo +remind --task --at` | 给自己建带截止/提醒时间的待办 | ✅ 编译/挂载 |
+| `todo +todo-done --task <关键词>` | 列我的待办→按标题匹配→标记完成 | ✅ 编译/挂载 |
+| `calendar +reschedule --event <id>` | 查日程详情→改时间（查→改机械多步） | ✅ 编译/挂载 |
+| `wiki +wiki-new-doc --space <名>` | 按名搜知识空间→在其下建文档（跨 doc server 路由） | ✅ 编译/挂载 |
+| `doc +doc-append --doc --text` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 |
+| `minutes +action-items` | 列妙记→取最新→取其待办事项 | ✅ 编译/挂载 |
+| `minutes +detail --id <taskUuid>` | 一条命令聚合听记 basic/summary/keywords/transcript/todos，partial-failure 容错 | ✅ 全量测试 |
+| `minutes +replace-batch --id --pair "原文=>替换"…` | 多组批量替换文字，去重校验+逐组结果聚合 | ✅ 全量测试 |
+
+| `oa +approve-by --keyword` ★ | 列待审批→匹配→取 taskId→通过（钉钉原生，lark 无） | ✅ 编译/挂载 |
+| `attendance +my-attendance` ★ | 当前用户→算今天→查我打卡（路由 attendance-wukong server） | ✅ 编译/挂载 |
+| `todo +overdue` | 列我待办→本地过滤过期→投影输出 | ✅ **真机端到端** |
+| `report +report-latest` ★ | 列我日志→取最新→取详情 | ✅ 编译/挂载 |
+| `aitable +find-record --base --table` | 表内按关键词查记录 | ✅ 编译/挂载 |
+
+另有 gap-buildable 补齐（批6）：`chat +my-groups`（列群+类型过滤+投影）、`calendar +find-room`（时段找可用会议室）、`minutes +minutes-search`（关键词搜妙记）、`mail +search-mail`（搜邮件+自动解析绑定邮箱）、`drive +find-file`（搜钉盘文件+投影）。
+
+批7-8 续补（10 条）：`chat +at-me`（近期@我）、`calendar +cancel-event`（查→删，高危二次确认）、`todo +assign-multi`（多人指派）、`contact +dept-members`（搜部门→列成员）、`minutes +transcript`（最新妙记逐字稿）、`calendar +week`（本周日程）、`contact +by-mobile`（手机号→资料）、`todo +created-todos`（我创建的）、`chat +unread-chats`（未读会话）、`mail +unread-mail`（未读邮件）。
+
+批9 续补（3 条·手工，对齐 gap-buildable）：`minutes +detail`（单命令聚合一条听记的 basic/summary/keywords/transcript/todos，partial-failure 容错）、`minutes +replace-batch`（多组 `原文=>替换` 批量替换 + 去重校验 + 逐组结果聚合，补齐一次一组的 1:1 `+word-replace`）、`aitable +record-share-links`（>20 条记录分享链接：去重+分片(≤20/批)+跨 `aitable-helper` server fanout+合并，补齐单批 20 条上限）。
+
+批10 续补（3 条·多 agent 并行，对齐 gap-buildable）：`chat +thread-replies`（拉某条话题消息的全部回复 list_topic_replies + sender/text/time 投影）、`todo +related-tasks`（creator+executor+participant 三角色并集「与我相关的待办」+ taskId 去重 + 投影）、`doc +find-doc`（按关键词搜云文档 search_documents + title/url/type/token 投影）。
+
+批11 续补（3 条·多 agent 并行）：`aitable +resolve-base`（按名搜 Base 解析 baseId，0/1/多候选消歧 search_bases）、`chat +chat-messages`（群/单聊会话消息列表，list_conversation_message_v2 / list_individual_chat_message 互斥+投影）、`mail +find-mail-user`（按名/邮箱搜企业邮箱联系人 search_mail_users + 投影）。
+
+批12 续补（3 条·多 agent 并行，dws 原生 resolver 层，按名解析 ID）：`wiki +resolve-space`（search_wikiSpaces 名→spaceId）、`aitable +resolve-table`（get_tables 在 Base 内名→tableId，本地匹配）、`contact +resolve-dept`（search_dept_by_keyword 名→deptId，含数值 ID 兼容）。均 0/1/多候选消歧，对标 `resolveUser` 的各资源版。
+
+批28 续补（3 条·净新增便利读，dws 原生）：`oa +pending`（**只读**列待我审批，区别于会审批的 +approve-by）、`todo +due-today`（今天到期待办，planFinishDate 服务端过滤，区别于 +overdue 已过期）、`calendar +tomorrow`（明天日程，复用 +today/+week 投影）。均只读、真机验证（+tomorrow 返回真实明日日程；+pending/+due-today 空路径正确且复用已验证 helper）。
+
+批29 续补（3 条·净新增便利读，dws 原生）：`oa +done-approvals`（我已处理的审批历史 get_done_tasks；真机抓到并修复 pageSize=0 → 默认 20 的后端报错 bug）、`mail +recent-mail`（近期收件箱会话 list_mailbox_threads + 解析绑定邮箱/收件箱）、`attendance +this-month`（本月打卡 query_check_record on attendance-wukong，复用 +my-attendance 自身解析）。真机：+this-month 返回有效空、+done-approvals 修后走空路径、+recent-mail 正确报未绑定邮箱。
+
+批30 续补（1 条·净新增便利读）：`contact +me`（当前用户 get_current_user_profile + 投影 {name,userId,mobile,dept,org,email}，agent 的「我是谁」；区别于 1:1 +get-self 吐冗长 raw，真机验证 董鑫阳/202397/模型算法）。
+
+批31 续补（1 条·净新增便利读）：`calendar +my-free`（我自己的忙闲，自动解析当前 userId，默认今天，复用 +free 的 freebusySlots 投影；无需像 +free 传别人姓名，真机验证返回今日忙碌时段）。
+
+批32 续补（1 条·净新增 dws 原生编排，lark 也没有）：`calendar +conflicts`（检测某天日程时间冲突/双重预订，list_calendar_events + 本地两两重叠检测，默认今天/--in-days；真机验证抓到今日 2 处真实冲突）。这类纯 MCP-tool 的本地编排是复杂写死胡同之外仍有价值的方向。
+
+批33 续补（1 条·净新增 dws 原生编排，+conflicts 的互补品）：`calendar +free-slots`（找某天工作时段内的空闲时段"什么时候能安排会"，list_calendar_events + 合并忙碌区间 + 工作窗口内求补集，默认今天 09:00-18:00/--from/--to/--in-days；真机验证今日 4 段空档）。
+
+共 **68 条真·智能 shortcut**（多批多 agent 工作流并行生成 + 手工续补）。★=钉钉原生编排，lark 完全没有。
+
+**真机验证（登录态抽样，返回真实数据）**：`calendar +today/+week`（真实日程+投影）、`contact +org`（3 步→部门详情）、`contact +lookup/+free`、`todo +overdue`、`attendance +my-attendance` 等端到端可用。
+
+### 深度对齐矩阵（逐条分析 lark 361 条 shortcut）
+
+见 [`shortcut-lark-alignment.md`](shortcut-lark-alignment.md)——12 agent 逐条深读 lark 每个 shortcut 的智能实现（Validate/DryRun/ID解析/投影/多步/分页），映射钉钉：
+
+| dws_status | 数量 | 含义 |
+|---|:---:|---|
+| covered-1to1 | 144 (40%) | lark 组合在钉钉塌缩成 1:1，封装层已覆盖 |
+| no-dingtalk-tool | 127 (35%) | 钉钉无对应工具，客观不可对齐 |
+| **gap-buildable** | **42 (12%)** | 钉钉有工具、值得补成智能 shortcut（建设目标） |
+| covered-smart | 48 (13%) | 已建智能 shortcut / 部分覆盖 |
+
+**框架系统性能力已对齐 lark**：`resolveUser`（名→ID）· `CallMCPData`（多步取数）· `rt.Output`（输出投影）· `rt.MutuallyExclusive/AtLeastOne/ExactlyOne/RangeInt/RequireAll`（跨字段校验）。
+
+### 保真度升级（对齐 lark 96% 的输出投影）
+
+lark 96% 的 shortcut 都做**输出投影**（把原始 API 返回精简为干净字段列表）。已给 **~60 条列表/读类封装**升级到此保真度——从 `rt.CallMCP`（打印原始 MCP 返回）改为 `rt.CallMCPData` + 防御式投影 + `rt.Output`（自动吃 `--format/--jq/--fields`）：
+
+`contact +search-user/+search-mobile/+list-roles/+list-sub-depts` · `todo +get-my-tasks/+list-sub` · `calendar +book-list/+attendee-list` · `drive +list` · `wiki +node-list` · `chat +conversation-list/+category-list/+messages-list-unread-conversations/+messages-list-pin` · `doc +search/+list` · `mail +tag-list/+contact-list` · `aitable +base-list/+base-search` · `oa …`
+
+示例：`contact +search-user` 由原始 MCP 返回 → 干净 `{count, users:[{name,userId,flowerName,openDingTalkId,title}]}`（真机验证）。这是把封装层往 lark 高保真水平系统性拉升的开始。另有 `mail +to`（按名发邮件）被 agent **正确 skip**——钉钉 contact 无 email 字段、mail `send_email` 需发件人邮箱 `from` 无法解析，宁缺勿错不编造。关键复用：「按名解析人」抽成共享 helper `resolveUser`（对标 lark `ResolveOpenIDsTyped`，带 0/多人消歧，不瞎猜）；多步靠 `CallMCPData`（对标 lark `CallAPITyped`）。其中 5 条由多 agent 工作流并行生成——各自以 helper 为 ground truth 研究参数、`send-to-group` 的 agent 还主动纠正了「按群名搜群」的正确工具（`search_groups` 而非按成员昵称的 `search_common_groups`）。
+
+> 定位：1:1 层是「MCP 友好外壳」，smart 层才是「真 shortcut」。二者不混淆。
+
+---
+
+## 2. 测试验证报告
+
+**验证理念**：写/删命令不能真跑（会发消息、解散群、删数据），故用**假 Caller 拦截**——让每条命令（含写/删）真实走完「解析→校验→确认→组装 MCP 调用」全流程，捕获组装出的 `(product, tool, params)`，只是不真发网络。以此对**全部 366 条**做零副作用验证。
+
+### 2.1 结果总览（全绿）
+
+| 验证项 | 范围 | 结果 |
+|------|------|------|
+| `go build ./...` | 全仓 | ✅ 通过 |
+| `gofmt -l` / `go vet` | shortcut 全包 | ✅ 0 未格式化 / 0 告警 |
+| 框架单元测试（5） | 类型/挂载/校验/分组 | ✅ 全通过 |
+| **TestAllShortcutsAssemble** | **全部 366 条** | ✅ 322 组装真实 MCP · 44 自校验拦截 · **0 失败 · 0 panic** |
+| **TestAllToolLiteralsAreReal** | 全部 tool 字面量（逐条） | ✅ **0 编造**（tool 名逐一比对 helper ground truth） |
+| TestNoDuplicateCommands | 全部 366 条 | ✅ 无重复、命名规范（均 `+` 前缀） |
+| **TestAllHaveIntent** | 全部 366 条 | ✅ 每条均有自然语言 Intent 描述（无一遗漏） |
+| usage 包单测（4） | 埋点/脱敏/聚合/开关 | ✅ 全通过 |
+| app 包全量回归 | `internal/app` | ✅ 72.2s 通过（接线未破坏任何现有命令） |
+| 只读命令真机验证 | ~25 条（登录态，见 §2.4） | ✅ `contact +me`/`+org`/`+lookup`、`calendar +today/+week/+free/+conflicts/+free-slots`、`doc +find-doc`、`aitable +resolve-base/+resolve-table`、`drive +find-file`、`oa +my-initiated` 等端到端返回真实数据、投影核对 |
+
+### 2.2 关键指标解读
+
+- **322 「组装真实 MCP」**：喂合成参数后成功组装出 MCP 调用，且 tool 名经 helper ground truth 核验真实、非编造。
+- **44 「自校验拦截」**：这些命令有结构化/JSON/互斥输入（如多维表建记录需 JSON、DING 三选一接收人），dummy 值被其**自身校验正确拒绝**——证明校验链路健全。其 tool 名由静态测试 `TestAllToolLiteralsAreReal` 单独覆盖，无遗漏。
+- **0 编造 / 0 panic / 0 失败**：无幻觉工具名，无运行时崩溃，无死命令。
+
+> ⚠️ **验证强度分层（诚实口径，勿把"全绿"读成"真机全对"）**：`TestAllShortcutsAssemble` 的"0 失败"只证明**能正确组装 MCP 调用、零副作用**——它用**合成响应**，**验证不了防御式投影是否匹配真实响应结构**（真机验证正是靠这个抓到过 deptList 容器、pageSize=0 等 assemble 盖不住的 bug，见 §2.4）。按真机验证强度分三层：**(A) 真机正向验证** ~25 条只读/解析类（返回真实数据、投影核对）；**(B) 仅 assemble + 复用已验证 helper**（如 +due-today/+this-month 等，逻辑同构于已验证命令，但该条本身未在真机跑出正样本）；**(C) 未对真实后端跑过**——17 条写类 smart（不宜真跑，会发消息/建数据）、6 条 minutes smart（该 org 未开 CLI 数据访问）、mail +recent-mail（无绑定邮箱）。(C) 类**很可能仍有 assemble 盖不住的投影/参数 bug**，不应因"全绿"就当作"真机可用"。
+
+### 2.3 防幻觉机制（工作流生成时）
+
+生成阶段每个服务由独立 agent 负责，硬性规则：tool 名与参数 key **只能逐字取自 dws helper 的真实调用点**，无法确定参数的 tool 主动跳过并记录原因（如嵌套对象、时间戳转换、本地文件分片上传）。测试阶段再用 ground truth 二次核验，双重保险。
+
+### 2.4 真机验证战役（登录态打真实钉钉后端）
+
+assemble 测试用**合成响应**，能验证「调用是否组装正确」，但验证不了「防御式投影解析是否匹配真实响应结构」。为此做了 9 批真机验证（登录态 corp「钉钉」，token 有效期内），把只读/解析类 smart shortcut 打真实后端、逐条核对投影输出。
+
+**正向验证 20+ 条**（返回真实数据、投影正确）：`doc +find-doc`、`aitable +resolve-base`/`+resolve-table`/`+list-tables`/`+base-list`/`+find-record`、`mail +find-mail-user`、`chat +my-groups`/`+group-members`/`+at-me`、`contact +org`/`+lookup`、`calendar +today`/`+week`/`+next-event`/`+free`/`+suggest-time`、`todo +overdue`/`+related-tasks`、`attendance +my-attendance`、`report +report-latest`、`oa +my-initiated`、`drive +find-file`、`wiki +resolve-space` 等。
+
+**真机抓到并修复 8 个真实问题**（assemble 测试抓不到，只有真机能抓）：
+
+| shortcut | 真机发现的问题 | 修复 |
+|---|---|---|
+| `contact +resolve-dept` | 对任何真实部门名都「未找到」——真实响应容器 key 是 `deptList`（防御探测清单漏了），deptName 带 `<red>` 高亮、deptId 是数值 | 加 `deptList` 探测 + `stripHighlightTags` + 数值 coerce |
+| `contact +dept-members` | 消歧消息泄漏 `<red>` 标记 | 复用 `stripHighlightTags` |
+| `chat +unread-chats` | 每行吐 `unread: null`（底层不返回每会话未读数） | 仅当有值才带该字段 |
+| `chat +at-me` | 直吐原始两层嵌套、未拍平 | 新增 `atMeFlattenGroups`，拍平 43 条为 `{conversation,sender,text,time}` |
+| `chat +group-members` | 终结步 raw `CallMCP` 吐冗长 raw（含 avatar 媒体 ID + errorCode 噪音） | 升级 `CallMCPData`+投影 `{name,nick,role,openDingtalkId}` |
+| `calendar +free` | 吐冗长 `result[].scheduleItems[].{start,end}.dateTime` 嵌套 | 投影为 `{who,userId,free,busy:[{start,end}]}` |
+| `calendar +today` | 吐 17 字段冗长事件（含完整 attendees 数组），与 `+week` 不一致 | 投影为 `{title,start,end,location,eventId}`，对齐 `+week` |
+| `calendar +suggest-time` | `timeConflictAttendees:[null]` 噪音 + result 包裹 | 拍平 + 丢 null 冲突 → `{suggestions:[{start,end}]}` |
+
+**后端受限、无法真机正向验证的（非代码问题）**：`chat +chat-messages`/`+search-msg`（读会话消息需更高 PAT 权限 / org 未开 CLI 数据访问）、`minutes +*`（org 未开 CLI 数据访问 `TOKEN_VERIFIED_FAILED`）、`contact +team`（列部门成员 medium-risk 权限墙）。这些命令的**组装链路**经 assemble 测试验证正确，仅无法在本环境跑通后端。
+
+**一个已澄清的非 bug**：`resolveUser` 对组织内成员（如董鑫阳→userId 202397）真机端到端正常；对外部/资料受限联系人 `search_contact_by_key_word` 只返回 openDingTalkId（name/userId 全 null），此时正确报「没找到」而非瞎猜——钉钉数据模型现实，非代码缺陷。
+
+> **结论**：真机验证证明「防御式多候选 key 投影」在真实响应上整体成立，并纠正了 8 处「合成测试盖不住」的解析/投影偏差。这是把可用性从「组装正确」提升到「真机输出正确」的关键一环。
+
+---
+
+## 3. 效果评估 GSB（vs lark-cli）
+
+以 lark-cli 各服务领域为基准，评估 dws shortcut 的相对表现。**G**ood=优于/更全，**S**ame=持平，**B**ad=弱于/缺失。
+
+> ⚠️ 重要前提：两边是**不同 API**（飞书 vs 钉钉），数量不能机械 1:1；覆盖度受钉钉实际能力约束。
+>
+> **口径（prune 后重做）**：不再用 shortcut 数（会因去冗余失真），改用**「dws 该服务实际暴露的 distinct MCP tool 数」= helper 命令 ∪ shortcut 覆盖的 tool 合集**——这才代表真实能力，与 helper/shortcut 怎么分层无关。对比 lark 的 shortcut 数（不同 API，只作量级参考）。
+
+| lark 服务 | lark 数 | dws 对应 | dws tool 覆盖 | (其中 shortcut 补) | GSB | 说明 |
+|-----------|:---:|---------|:---:|:---:|:---:|------|
+| im | 21 | chat | **95** | +3 | 🟢 G | 群/消息/机器人能力更全 |
+| mail | 21 | mail | **43** | +0 | 🟢 G | 覆盖更广（几乎全由 helper 提供，shortcut 曾重复、已 prune） |
+| doc | 14 | doc | **34** | +4 | 🟢 G | 块级读写更细 |
+| minutes | 14 | minutes | **25** | +0 | 🟢 G | 录音控制/说话人更全 |
+| calendar | 12 | calendar | **24** | +5 | 🟢 G | 会议室/ACL/忙闲；shortcut 另补排期智能 |
+| contact | 2 | contact | **15** | +0 | 🟢 G | 部门/角色/花名册更全 |
+| wiki | 12 | wiki | **16** | +0 | 🟢 G | 略优 |
+| base | 87 | aitable | **79** | **+63** | 🟡 S | 基本持平；**helper 仅 16，shortcut 层补齐了绝大部分**（真·gap-fill） |
+| task | 18 | todo | **20** | +1 | 🟡 S | 持平 |
+| drive | 26 | drive | **25** | +4 | 🟡 S | 基本持平 |
+| apps | 63 | devapp | **25** | **+25** | 🔴 B | **helper 无 devapp 命令、25 个全由 shortcut 提供**（纯 gap-fill），但仍少于 lark |
+| sheets | 84 | sheet | **60** | +1 | 🔴 B | 钉钉表格 MCP 较少；helper 已覆盖，shortcut 曾重复、已 prune |
+| vc | 18 | — | 0 | — | 🔴 B | 钉钉 conference 无干净 MCP tool |
+| okr | 13 | — | 0 | — | 🔴 B | 钉钉无对应能力，**不可对齐** |
+| slides / markdown / whiteboard / note / event | 17 | — | 0 | — | 🔴 B | 钉钉无对应能力，**不可对齐** |
+
+**dws 独有（lark 无对应服务）**：oa 审批(~20 tool) · attendance 考勤(~38) · report 日志(~7) · ding(~8) · aisearch/live/devdoc（helper 层提供）——钉钉工作流核心，构成差异化。
+
+### GSB 汇总
+
+- 🟢 **G（7 领域）**：im/mail/doc/minutes/calendar/contact/wiki——dws tool 覆盖更全。
+- 🟡 **S（3 领域）**：base/task/drive 量级持平（base 的持平**几乎全靠 shortcut 层 gap-fill**，helper 只有 16）。
+- 🔴 **B（受限 2 + 不可对齐 6）**：apps/sheets 少于 lark（sheets 受钉钉 API 限，apps 全由 shortcut 补但仍少）；vc/okr/slides/markdown/whiteboard/note/event 客观不可对齐（非遗漏）。
+- **注**：这张表也印证了 1:1 层的真实价值分布——**base/apps 靠 shortcut 补了大量 helper 没有的 tool（gap-fill），而 mail/sheets 的 shortcut 基本是重复 helper（已 prune）**。
+
+---
+
+## 4. dws 差异化于 lark 的优势
+
+### 4.1 执行底座：复用生产级 MCP 通道（架构性优势）
+lark-cli 每个 shortcut 直连飞书 SDK，错误处理/输出各自实现。dws shortcut 的 `CallMCP` **委托统一的 MCP 调用路径**，一步继承：
+- **错误分类**：auth 过期 / 未登录 / PAT / 业务错误，自动给出可执行提示；
+- **`--dry-run` 预览**：不发网络，输出将执行的 tool + 参数；
+- **`--format`/`--jq`/`--fields`**：机器可解析输出，Agent 友好。
+
+lark 需在每个命令重复实现这些；dws 由框架统一注入，一致性与维护成本双赢。
+
+### 4.2 覆盖更全的高频协作能力
+按 **dws tool 覆盖**（helper∪shortcut，§3 口径）：chat 95 / mail 43 / doc 34 / minutes 25 / calendar 24 等即时协作场景，多为 lark 对应服务的 2–4 倍。
+
+### 4.3 钉钉原生特有能力（lark 完全没有）
+审批 oa、日志 report、考勤 attendance、DING、企业智能搜索 aisearch —— 这些是钉钉工作流的核心，构成差异化护城河。
+
+### 4.4 高频自动沉淀（P2，lark 无此设计）
+基于用户高频使用**主动把常用操作沉淀为自定义 shortcut**（`~/.dws/shortcuts/*.yaml` 运行时加载），让 CLI 越用越顺手。埋点**默认关（opt-in，`DWS_USAGE_TRACKING=1` 开启）**+开启后首跑告知，隐私优先（记形状不记值）。详见 [P2 设计](shortcut-p2-design.md)。**lark-cli 无任何等价能力。**
+
+### 4.5 AI Agent 友好
+`--yes` 跳过确认、结构化错误、`--dry-run` 预览、`--print-schema`（规划中）——为 Agent 自动化调用而设计。
+
+### 4.6 工程质量：全量自动化测试
+假 Caller 拦截，对全部 366 条（含写/删）做零副作用验证 + tool 名 ground truth 核验，可复跑、可回归。
+
+---
+
+## 5. 复盘与后续（loop 持续项）
+
+### 5.0 关键复盘：1:1 层去冗余（511 → 298）
+**问题**：建 1:1 shortcut 层之前，**没有先摸清 `internal/helpers/` 已经把哪些 MCP tool 封装成了 `dws <svc> <verb>` 产品命令**。结果对 **213 个 tool 重复封装**——同一个 tool，helper 有 `dws contact user search`、我又造了 `dws contact +search-user`，且这批无投影增量，纯重复。
+**纠偏**：按「tool 已被 helper 封装 且 shortcut 用 CallMCP 无投影」精确删除 213 条，1:1 层 511 → **298**（保留 233 填空白 + 65 有投影），总数 579 → **366**，服务 19 → **16**（aisearch/live/devdoc 整包移除）。全绿、真机复验保留命令仍可用。
+**教训**：**做封装层前先审已有封装**。对齐 lark「每一条 shortcut」时，应先问「dws 这边是不是已经有等价命令了」，而不是无脑对齐。这是本项目最大的方法论盲点。
+
+1. ~~补 apps（↔devapp）~~ ✅ 已完成：新增 30 个 devapp shortcut。
+2. **P2 落地**（差异化能力，lark 无）：
+   - ✅ **P2-1 usage 埋点**：装饰 MCP 调用唯一必经点记录 `~/.dws/usage.jsonl`（**记形状不记值**，敏感/自由文本字段脱敏；**默认关/opt-in**，`DWS_USAGE_TRACKING=1` 开启、开启后首跑告知）。端到端验证通过。
+   - ✅ **stats/list**：`dws shortcut list [--service]`、`dws shortcut stats [--top N] [--purge]`（按 `(product,tool,arg_keys)` 聚合、识别固定值 fixed_args）。
+   - ✅ **P2-2 suggest**：`dws shortcut suggest [--min N]` 把高频分组转成「建议沉淀的 +command」候选（含固定/可变参数拆分）。
+   - ✅ **P2-3 YAML 自定义 shortcut 沉淀闭环**：`dws shortcut add` 写 `~/.dws/shortcuts/*.yaml` → 下次运行 `userdef.Load()` 编译成 Shortcut 注册（复用同一 runner；`${flag}` 绑定+常量；与内建冲突自动跳过）。**端到端验证通过**：add→重载→`dws <svc> +<cmd>` 可用，dry-run 组装正确。
+   - ⏳ **P2-4 nudge**：命中高频候选时主动提示（TTY、频控、可永久关闭）。
+
+   > 至此，**「高频使用 → 建议 → 一键沉淀 → 自定义 shortcut 运行时生效」完整闭环已打通**——这是 lark-cli 完全没有的差异化能力。
+3. **深化 sheets**：随钉钉表格 MCP 能力增强补齐。
+4. **实机全读回归**：登录态下对全部只读 shortcut 做真实调用回归（需有效 token + 真实资源 ID）。
+5. **不可对齐项归档**：okr/slides/whiteboard/note/vc/event 明确标注为钉钉无能力，避免误解为遗漏。
+
+---
+
+## 附：一句话结论
+
+> dws 已把钉钉侧**能对齐的主要服务全部对齐**（16 服务 / **366 shortcut** = 298 封装 + 68 智能编排），在即时协作能力上显著优于 lark，并拥有审批/考勤/日志/DING 等钉钉原生差异化能力与「高频自动沉淀」独有设计；受限项均为钉钉客观无对应能力，非工程遗漏。全部 366 条通过零副作用全量自动化验证。

go.mod

@@ -1,17 +1,19 @@
 module github.com/DingTalk-Real-AI/dingtalk-workspace-cli
 
-go 1.25.8
+go 1.25.9
 
 require (
+	github.com/Microsoft/go-winio v0.6.2
 	github.com/RealAlexandreAI/json-repair v0.0.15
 	github.com/charmbracelet/bubbletea v1.3.6
 	github.com/charmbracelet/huh v1.0.0
 	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/fatih/color v1.18.0
 	github.com/google/uuid v1.6.0
+	github.com/gorilla/websocket v1.5.0
 	github.com/itchyny/gojq v0.12.18
 	github.com/muesli/termenv v0.16.0
-	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
+	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad
 	github.com/spf13/cobra v1.10.2
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/crypto v0.49.0
@@ -35,7 +37,6 @@ require (
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/godbus/dbus/v5 v5.2.2 // indirect
-	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/itchyny/timefmt-go v0.1.7 // indirect
 	github.com/lucasb-eyer/go-colorful v1.2.0 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect

go.sum

@@ -1,5 +1,7 @@
 github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
 github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/RealAlexandreAI/json-repair v0.0.15 h1:AN8/yt8rcphwQrIs/FZeki+cKaIERUNr25zf1flirIs=
 github.com/RealAlexandreAI/json-repair v0.0.15/go.mod h1:GKJi5borR78O8c7HCVbgqjhoiVibZ6hJldxbc6dGrAI=
 github.com/atotto/clipboard v0.1.4 h1:EH0zSVneZPSuFR11BlR9YppQTVDbh5+16AmcJi4g1z4=
@@ -86,8 +88,8 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc=
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
-github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv81PdkYOiWbI8CNBi1boC8=
-github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad h1:Bb4I+suYd+ehQ8e22aimLLze+5XTN3+WTc/x2LafmH8=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.2-0.20260705041131-325e7c1049ad/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ=

internal/apiclient/client.go

@@ -49,6 +49,8 @@ var AllowedMethods = map[string]bool{
 	"GET": true, "POST": true, "PUT": true, "PATCH": true, "DELETE": true,
 }
 
+var newHTTPRequest = http.NewRequestWithContext
+
 // RawAPIRequest describes a raw API request to DingTalk OpenAPI.
 type RawAPIRequest struct {
 	Method string         // GET, POST, PUT, PATCH, DELETE
@@ -112,7 +114,7 @@ func (c *APIClient) Do(ctx context.Context, req RawAPIRequest) (*RawAPIResponse,
 		bodyReader = bytes.NewReader(data)
 	}
 
-	httpReq, err := http.NewRequestWithContext(ctx, method, fullURL, bodyReader)
+	httpReq, err := newHTTPRequest(ctx, method, fullURL, bodyReader)
 	if err != nil {
 		return nil, fmt.Errorf("creating HTTP request: %w", err)
 	}

internal/apiclient/coverage_edges_test.go

@@ -0,0 +1,293 @@
+package apiclient
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+)
+
+type failingReader struct{ err error }
+
+func (r failingReader) Read([]byte) (int, error) { return 0, r.err }
+
+type failingWriter struct{ err error }
+
+func (w failingWriter) Write([]byte) (int, error) { return 0, w.err }
+
+func TestCrossPlatformCoverageDryRunAndParseCoverageEdges(t *testing.T) {
+	for _, tc := range []struct {
+		base string
+		path string
+	}{
+		{DefaultBaseURL, "/v1.0/test"},
+		{LegacyBaseURL, "/topapi/test"},
+	} {
+		var out bytes.Buffer
+		err := PrintDryRun(&out, RawAPIRequest{
+			Method: "post", Path: tc.path,
+			Params: map[string]any{"page": 1}, Data: map[string]any{"name": "value"},
+		}, tc.base, "token-value")
+		if err != nil || !strings.Contains(out.String(), "Dry Run") || !strings.Contains(out.String(), "toke****") {
+			t.Fatalf("PrintDryRun(%s) = %q, %v", tc.base, out.String(), err)
+		}
+	}
+	var out bytes.Buffer
+	if err := PrintDryRun(&out, RawAPIRequest{Method: "get", Path: "/x", Params: map[string]any{"bad": make(chan int)}, Data: make(chan int)}, DefaultBaseURL, "tiny"); err != nil {
+		t.Fatalf("PrintDryRun unsupported preview: %v", err)
+	}
+
+	wantErr := errors.New("read failed")
+	if _, err := ParseJSONMap("-", "--params", failingReader{err: wantErr}); !errors.Is(err, wantErr) {
+		t.Fatalf("ParseJSONMap read error = %v", err)
+	}
+	if got, err := ParseJSONMap("-", "--params", strings.NewReader(" \n")); err != nil || got != nil {
+		t.Fatalf("ParseJSONMap empty stdin = %#v, %v", got, err)
+	}
+	if _, err := ParseOptionalBody("POST", "-", failingReader{err: wantErr}); !errors.Is(err, wantErr) {
+		t.Fatalf("ParseOptionalBody read error = %v", err)
+	}
+	if got, err := ParseOptionalBody("POST", "-", strings.NewReader(" \n")); err != nil || got != nil {
+		t.Fatalf("ParseOptionalBody empty stdin = %#v, %v", got, err)
+	}
+	if _, err := ParseOptionalBody("POST", "{", strings.NewReader("")); err == nil {
+		t.Fatal("invalid optional body should fail")
+	}
+}
+
+func TestCrossPlatformCoverageResponseHandlingCoverageEdges(t *testing.T) {
+	jsonHeader := http.Header{"Content-Type": []string{"application/json"}}
+	textHeader := http.Header{"Content-Type": []string{"text/plain"}}
+	var out, errOut bytes.Buffer
+	opts := ResponseOptions{Format: output.FormatJSON, Out: &out, ErrOut: &errOut}
+
+	if err := HandleResponse(&RawAPIResponse{StatusCode: 500, Header: textHeader, Body: []byte(" failed ")}, opts); err == nil {
+		t.Fatal("plain HTTP error should fail")
+	}
+	for _, body := range [][]byte{nil, []byte("{")} {
+		if err := HandleResponse(&RawAPIResponse{StatusCode: 200, Header: jsonHeader, Body: body}, opts); err == nil {
+			t.Errorf("invalid JSON body %q should fail", body)
+		}
+	}
+	out.Reset()
+	if err := HandleResponse(&RawAPIResponse{StatusCode: 200, Header: jsonHeader, Body: []byte(`{"ok":true}`)}, opts); err != nil || !strings.Contains(out.String(), "ok") {
+		t.Fatalf("successful JSON response = %q, %v", out.String(), err)
+	}
+	for _, payload := range []string{
+		`{"errcode":1}`,
+		`{"message":"message failure"}`,
+		`{"error":"error failure"}`,
+		`{}`,
+	} {
+		status := 200
+		if !strings.Contains(payload, "errcode") {
+			status = 500
+		}
+		if err := HandleResponse(&RawAPIResponse{StatusCode: status, Header: jsonHeader, Body: []byte(payload)}, opts); err == nil {
+			t.Errorf("business/HTTP payload %s should fail", payload)
+		}
+	}
+	if err := checkDingTalkError([]any{1}, 200); err != nil || checkDingTalkError(map[string]any{"errcode": 0}, 200) != nil {
+		t.Fatal("successful DingTalk response classified as error")
+	}
+
+	if err := HandleResponse(&RawAPIResponse{StatusCode: 200, Header: textHeader, Body: []byte("binary")}, opts); err == nil {
+		t.Fatal("binary response without filename should fail")
+	}
+	invalidCD := http.Header{"Content-Type": []string{"application/octet-stream"}, "Content-Disposition": []string{`attachment; filename="unterminated`}}
+	if inferFilename(invalidCD) != "" {
+		t.Fatal("invalid content disposition should not infer filename")
+	}
+	if inferFilename(http.Header{}) != "" {
+		t.Fatal("missing content disposition should not infer filename")
+	}
+
+	dir := t.TempDir()
+	blockedParent := filepath.Join(dir, "file")
+	if err := os.WriteFile(blockedParent, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	opts.OutputPath = filepath.Join(blockedParent, "child.bin")
+	if err := handleBinaryResponse(&RawAPIResponse{Header: textHeader, Body: []byte("x")}, opts); err == nil {
+		t.Fatal("binary mkdir failure should fail")
+	}
+	opts.OutputPath = dir
+	if err := handleBinaryResponse(&RawAPIResponse{Header: textHeader, Body: []byte("x")}, opts); err == nil {
+		t.Fatal("binary write to directory should fail")
+	}
+	opts.OutputPath = ""
+	inferred := filepath.Join(dir, "inferred.bin")
+	header := http.Header{"Content-Type": []string{"application/octet-stream"}, "Content-Disposition": []string{`attachment; filename="` + inferred + `"`}}
+	if err := handleBinaryResponse(&RawAPIResponse{Header: header, Body: []byte("bytes")}, opts); err != nil {
+		t.Fatalf("inferred binary save: %v", err)
+	}
+	if !strings.Contains(errOut.String(), "已保存") {
+		t.Fatalf("binary status = %q", errOut.String())
+	}
+
+	for _, ct := range []string{" application/json; charset=utf-8 ", "text/json", "application/problem+json", "text/plain"} {
+		_ = isJSONContentType(ct)
+	}
+	for _, value := range []any{float64(1), 2, int64(3), json.Number("4"), json.Number("bad"), "5"} {
+		_ = toFloat64(value)
+	}
+}
+
+func TestCrossPlatformCoveragePaginationParsingAndInjectionEdges(t *testing.T) {
+	jsonHeader := http.Header{"Content-Type": []string{"application/json"}}
+	for _, resp := range []*RawAPIResponse{
+		{StatusCode: 200, Header: http.Header{"Content-Type": []string{"text/plain"}}, Body: []byte("x")},
+		{StatusCode: 200, Header: jsonHeader},
+		{StatusCode: 200, Header: jsonHeader, Body: []byte("{")},
+		{StatusCode: 500, Header: jsonHeader, Body: []byte(`{"message":"bad"}`)},
+	} {
+		if _, _, _, err := parsePaginatedResponse(resp); err == nil {
+			t.Errorf("parsePaginatedResponse(%#v) should fail", resp)
+		}
+	}
+	responses := []struct {
+		body  string
+		more  bool
+		token string
+	}{
+		{`{"result":{"has_more":true,"next_cursor":12}}`, true, "12"},
+		{`{"has_more":true,"next_cursor":13}`, true, "13"},
+		{`{"next_token":"next"}`, true, "next"},
+		{`{"result":[],"has_more":false}`, false, ""},
+	}
+	for _, tc := range responses {
+		_, more, token, err := parsePaginatedResponse(&RawAPIResponse{StatusCode: 200, Header: jsonHeader, Body: []byte(tc.body)})
+		if err != nil || more != tc.more || token != tc.token {
+			t.Errorf("pagination %s = %v, %q, %v", tc.body, more, token, err)
+		}
+	}
+
+	getCases := []RawAPIRequest{
+		{Method: "GET"},
+		{Method: "GET", Params: map[string]any{"cursor": "old"}},
+		{Method: "GET", Params: map[string]any{"next_token": "old"}},
+		{Method: "POST", Data: map[string]any{"cursor": "old"}},
+		{Method: "PUT", Data: map[string]any{}},
+		{Method: "POST", Data: "not-a-map"},
+	}
+	for _, req := range getCases {
+		_ = injectPageToken(req, "new")
+	}
+	logf(nil, "ignored")
+}
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { return f(req) }
+
+func jsonHTTPResponse(body string) *http.Response {
+	return &http.Response{StatusCode: 200, Header: http.Header{"Content-Type": []string{"application/json"}}, Body: io.NopCloser(strings.NewReader(body))}
+}
+
+func TestCrossPlatformCoveragePaginationControlFlowEdges(t *testing.T) {
+	wantErr := errors.New("transport failed")
+	client := NewClient("token", DefaultBaseURL)
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: 200, Header: http.Header{"Content-Type": []string{"text/plain"}}, Body: io.NopCloser(strings.NewReader("bad"))}, nil
+	})
+	if _, err := client.PaginateAll(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{}); err == nil {
+		t.Fatal("first page parse error should fail")
+	}
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) { return nil, wantErr })
+	if _, err := client.PaginateAll(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{}); !errors.Is(err, wantErr) {
+		t.Fatalf("first page transport error = %v", err)
+	}
+
+	calls := 0
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		calls++
+		if calls == 1 {
+			return jsonHTTPResponse(`{"next_token":"next"}`), nil
+		}
+		return nil, wantErr
+	})
+	if pages, err := client.PaginateAll(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{PageDelay: 1}); err == nil || len(pages) != 1 {
+		t.Fatalf("later transport error pages=%d err=%v", len(pages), err)
+	}
+
+	calls = 0
+	var logs bytes.Buffer
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		calls++
+		if calls == 1 {
+			return jsonHTTPResponse(`{"next_token":"next"}`), nil
+		}
+		return &http.Response{StatusCode: 200, Header: http.Header{"Content-Type": []string{"text/plain"}}, Body: io.NopCloser(strings.NewReader("bad"))}, nil
+	})
+	if pages, err := client.PaginateAll(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{PageDelay: 1, LogWriter: &logs}); err != nil || len(pages) != 1 || !strings.Contains(logs.String(), "解析失败") {
+		t.Fatalf("later parse failure pages=%d logs=%q err=%v", len(pages), logs.String(), err)
+	}
+
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return jsonHTTPResponse(`{"next_token":"next"}`), nil
+	})
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	if pages, err := client.PaginateAll(ctx, RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{PageDelay: 10}); !errors.Is(err, context.Canceled) || len(pages) != 1 {
+		t.Fatalf("pagination cancellation pages=%d err=%v", len(pages), err)
+	}
+	logs.Reset()
+	if pages, err := client.PaginateAll(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}, PaginationOptions{PageLimit: 1, PageDelay: 1, LogWriter: &logs}); err != nil || len(pages) != 1 || !strings.Contains(logs.String(), "安全上限") {
+		t.Fatalf("pagination safety cap pages=%d logs=%q err=%v", len(pages), logs.String(), err)
+	}
+}
+
+func TestCrossPlatformCoverageClientAndValidationFailureEdges(t *testing.T) {
+	client := NewClient("token", DefaultBaseURL)
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "GET", Path: "https://api.dingtalk.com/%zz"}); err == nil {
+		t.Fatal("Do with invalid URL should fail")
+	}
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "GET", Path: "https://example.test/x"}); err == nil {
+		t.Fatal("Do to untrusted host should fail")
+	}
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "POST", Path: "/x", Data: make(chan int)}); err == nil {
+		t.Fatal("unmarshalable request body should fail")
+	}
+	if _, err := client.buildURL("https://api.dingtalk.com/%zz", nil); err == nil {
+		t.Fatal("invalid URL should fail")
+	}
+	oldNewRequest := newHTTPRequest
+	t.Cleanup(func() { newHTTPRequest = oldNewRequest })
+	wantCreateErr := errors.New("request creation failed")
+	newHTTPRequest = func(context.Context, string, string, io.Reader) (*http.Request, error) { return nil, wantCreateErr }
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}); !errors.Is(err, wantCreateErr) {
+		t.Fatalf("request creation error = %v", err)
+	}
+	newHTTPRequest = oldNewRequest
+	wantErr := errors.New("request failed")
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) { return nil, wantErr })
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}); !errors.Is(err, wantErr) {
+		t.Fatalf("HTTP transport error = %v", err)
+	}
+	client.HTTPClient.Transport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: 200, Header: http.Header{}, Body: io.NopCloser(failingReader{err: wantErr})}, nil
+	})
+	if _, err := client.Do(context.Background(), RawAPIRequest{Method: "GET", Path: "/x"}); !errors.Is(err, wantErr) {
+		t.Fatalf("response read error = %v", err)
+	}
+
+	if ValidateTargetHost("http://%zz") == nil {
+		t.Fatal("invalid target URL should fail")
+	}
+	for _, r := range []rune{0x200B, 0xFEFF, 0x202A, 0x2028, 0x2066, 0x061C, 0xFDD0} {
+		if !isDangerousUnicode(r) || ValidateUserInput("x"+string(r), "field") == nil {
+			t.Errorf("dangerous rune %U was accepted", r)
+		}
+	}
+	if isDangerousUnicode('中') || ValidateUserInput("safe\t\n中文", "field") != nil {
+		t.Fatal("safe Unicode/input was rejected")
+	}
+}

internal/app/access_token_manager_test.go

@@ -0,0 +1,223 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+type tokenManagerSnapshotProvider struct {
+	load func() (*authpkg.TokenData, error)
+}
+
+func (p tokenManagerSnapshotProvider) GetAccessToken(context.Context) (string, error) {
+	data, err := p.load()
+	if err != nil || data == nil {
+		return "", err
+	}
+	return data.AccessToken, nil
+}
+
+func (p tokenManagerSnapshotProvider) GetTokenSnapshot(context.Context) (*authpkg.TokenData, error) {
+	return p.load()
+}
+
+type tokenManagerLegacyGetter struct {
+	token string
+	err   error
+}
+
+func (g tokenManagerLegacyGetter) GetToken() (string, string, error) {
+	return g.token, "file", g.err
+}
+
+func installTokenManagerFakes(t *testing.T, load func() (*authpkg.TokenData, error)) {
+	t.Helper()
+	oldProvider, oldLegacy := newAccessTokenProvider, newLegacyTokenManager
+	oldEdition := edition.Get()
+	edition.Override(&edition.Hooks{})
+	newAccessTokenProvider = func(string) accessTokenGetter {
+		return tokenManagerSnapshotProvider{load: load}
+	}
+	newLegacyTokenManager = func(string) legacyTokenGetter {
+		return tokenManagerLegacyGetter{err: authpkg.ErrTokenDataNotFound}
+	}
+	t.Cleanup(func() {
+		newAccessTokenProvider, newLegacyTokenManager = oldProvider, oldLegacy
+		edition.Override(oldEdition)
+	})
+}
+
+func TestCrossPlatformCoverageTokenManagerCachesUntilMarkerRevisionChanges(t *testing.T) {
+	configDir := t.TempDir()
+	if err := authpkg.WriteTokenMarker(configDir); err != nil {
+		t.Fatal(err)
+	}
+	var calls atomic.Int32
+	token := "token-a"
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
+		calls.Add(1)
+		return &authpkg.TokenData{AccessToken: token, ExpiresAt: time.Now().Add(time.Hour)}, nil
+	})
+
+	manager := NewTokenManager()
+	first, err := manager.Get(context.Background(), configDir, "")
+	if err != nil || first.AccessToken != "token-a" {
+		t.Fatalf("first token = %#v, %v", first, err)
+	}
+	second, err := manager.Get(context.Background(), configDir, "")
+	if err != nil || second.AccessToken != "token-a" || calls.Load() != 1 {
+		t.Fatalf("cached token = %#v, %v, calls=%d", second, err, calls.Load())
+	}
+
+	token = "token-b"
+	if err := authpkg.WriteTokenMarker(configDir); err != nil {
+		t.Fatal(err)
+	}
+	rotated, err := manager.Get(context.Background(), configDir, "")
+	if err != nil || rotated.AccessToken != "token-b" || calls.Load() != 2 {
+		t.Fatalf("rotated token = %#v, %v, calls=%d", rotated, err, calls.Load())
+	}
+}
+
+func TestCrossPlatformCoverageTokenManagerDoesNotCacheWithoutExpiryOrRevision(t *testing.T) {
+	configDir := t.TempDir()
+	var calls atomic.Int32
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
+		calls.Add(1)
+		return &authpkg.TokenData{AccessToken: "token"}, nil
+	})
+	manager := NewTokenManager()
+	for range 2 {
+		if _, err := manager.Get(context.Background(), configDir, ""); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if calls.Load() != 2 {
+		t.Fatalf("provider calls = %d, want 2", calls.Load())
+	}
+}
+
+func TestCrossPlatformCoverageTokenManagerTreatsMalformedMarkerAsUncacheable(t *testing.T) {
+	configDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(configDir, "token.json"), []byte("{"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var calls atomic.Int32
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
+		calls.Add(1)
+		return &authpkg.TokenData{AccessToken: "token", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	})
+	manager := NewTokenManager()
+	for range 2 {
+		if snapshot, err := manager.Get(context.Background(), configDir, ""); err != nil || snapshot.AccessToken != "token" {
+			t.Fatalf("snapshot = %#v, error = %v", snapshot, err)
+		}
+	}
+	if calls.Load() != 2 {
+		t.Fatalf("provider calls = %d, want 2", calls.Load())
+	}
+}
+
+func TestCrossPlatformCoverageTokenManagerDoesNotCacheOpaqueEditionStorageWithProviderFallback(t *testing.T) {
+	configDir := t.TempDir()
+	if err := authpkg.WriteTokenMarker(configDir); err != nil {
+		t.Fatal(err)
+	}
+	var calls atomic.Int32
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
+		calls.Add(1)
+		return &authpkg.TokenData{AccessToken: "token", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	})
+	edition.Override(&edition.Hooks{
+		LoadToken: func(string) ([]byte, error) { return nil, nil },
+		TokenProvider: func(_ context.Context, fallback func() (string, error)) (string, error) {
+			return fallback()
+		},
+	})
+	manager := NewTokenManager()
+	for range 2 {
+		if _, err := manager.Get(context.Background(), configDir, ""); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if calls.Load() != 2 {
+		t.Fatalf("provider calls = %d, want 2", calls.Load())
+	}
+}
+
+func TestCrossPlatformCoverageTokenManagerCoalescesConcurrentLoads(t *testing.T) {
+	configDir := t.TempDir()
+	if err := authpkg.WriteTokenMarker(configDir); err != nil {
+		t.Fatal(err)
+	}
+	var calls atomic.Int32
+	release := make(chan struct{})
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) {
+		calls.Add(1)
+		<-release
+		return &authpkg.TokenData{AccessToken: "token", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	})
+	manager := NewTokenManager()
+	const workers = 8
+	var wg sync.WaitGroup
+	wg.Add(workers)
+	errs := make(chan error, workers)
+	for range workers {
+		go func() {
+			defer wg.Done()
+			_, err := manager.Get(context.Background(), configDir, "")
+			errs <- err
+		}()
+	}
+	for calls.Load() == 0 {
+		time.Sleep(time.Millisecond)
+	}
+	close(release)
+	wg.Wait()
+	close(errs)
+	for err := range errs {
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	if calls.Load() != 1 {
+		t.Fatalf("provider calls = %d, want 1", calls.Load())
+	}
+}
+
+func TestCrossPlatformCoverageTokenManagerPreservesProviderFailure(t *testing.T) {
+	configDir := t.TempDir()
+	want := errors.New("keychain permission denied")
+	installTokenManagerFakes(t, func() (*authpkg.TokenData, error) { return nil, want })
+	_, err := NewTokenManager().Get(context.Background(), configDir, "")
+	if !errors.Is(err, want) {
+		t.Fatalf("error = %v, want cause %v", err, want)
+	}
+	if errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("provider failure was misclassified as missing credentials: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageTokenResolutionErrorOnlyClassifiesTrueMissingCredential(t *testing.T) {
+	missing := tokenResolutionError(authpkg.ErrTokenDataNotFound)
+	var typed interface{ Unwrap() error }
+	if !errors.As(missing, &typed) || !errors.Is(missing, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("missing error = %v", missing)
+	}
+	want := errors.New("decrypt failed")
+	if got := tokenResolutionError(want); !errors.Is(got, want) || errors.Is(got, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("storage error = %v", got)
+	}
+	if got := tokenResolutionError(context.Canceled); !errors.Is(got, context.Canceled) {
+		t.Fatalf("cancellation = %v", got)
+	}
+}

internal/app/access_token_resolve.go

@@ -21,63 +21,283 @@ import (
 	"log/slog"
 	"path/filepath"
 	"strings"
+	"sync"
+	"time"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
-// resolveAccessTokenFromDir loads OAuth then legacy token from configDir, applying
-// the same host compatibility hooks as MCP. It mirrors the former body of
-// getCachedRuntimeToken (excluding process-level cache and timing).
-func resolveAccessTokenFromDir(ctx context.Context, configDir string) (string, error) {
-	disc := slog.New(slog.NewTextHandler(io.Discard, nil))
-	provider := authpkg.NewOAuthProvider(configDir, disc)
-	configureOAuthProviderCompatibility(provider, configDir)
-	token, tokenErr := provider.GetAccessToken(ctx)
-	if tokenErr == nil && strings.TrimSpace(token) != "" {
-		return strings.TrimSpace(token), nil
-	}
-	if tokenErr != nil && errors.Is(tokenErr, authpkg.ErrTokenDecryption) {
-		return "", tokenErr
-	}
-	manager := authpkg.NewManager(configDir, nil)
-	configureLegacyAuthManagerCompatibility(manager)
-	if leg, _, err := manager.GetToken(); err == nil && strings.TrimSpace(leg) != "" {
-		return strings.TrimSpace(leg), nil
-	}
-	return "", nil
+const accessTokenRefreshWindow = 5 * time.Minute
+
+type legacyTokenGetter interface {
+	GetToken() (string, string, error)
 }
 
-// ResolveAuxiliaryAccessToken resolves a bearer token for HTTP clients that should
-// align with MCP tool calls. Non-empty explicitToken wins. When configDir matches
-// the active edition config directory, the same process-cached path as MCP is used.
-// Otherwise tokens are loaded from configDir with host compatibility hooks applied.
-func ResolveAuxiliaryAccessToken(ctx context.Context, configDir, explicitToken string) (string, error) {
-	if t := strings.TrimSpace(explicitToken); t != "" {
-		return t, nil
+type accessTokenSnapshotGetter interface {
+	GetTokenSnapshot(context.Context) (*authpkg.TokenData, error)
+}
+
+// AccessTokenSnapshot is the minimal bearer view needed by the process cache.
+// Refresh-token material never leaves the auth package.
+type AccessTokenSnapshot struct {
+	AccessToken string
+	ExpiresAt   time.Time
+	Source      string
+}
+
+type tokenManagerKey struct {
+	configDir string
+	profile   string
+}
+
+type tokenManagerEntry struct {
+	mu       sync.Mutex
+	snapshot AccessTokenSnapshot
+	revision string
+}
+
+// TokenManager is the only process cache for user access tokens. Cache entries
+// are isolated by config directory and profile, expiry-aware, and invalidated
+// by the credential publication marker written by auth storage.
+type TokenManager struct {
+	mu      sync.Mutex
+	entries map[tokenManagerKey]*tokenManagerEntry
+	now     func() time.Time
+}
+
+func NewTokenManager() *TokenManager {
+	return &TokenManager{entries: make(map[tokenManagerKey]*tokenManagerEntry), now: time.Now}
+}
+
+var runtimeTokenManager = NewTokenManager()
+
+var (
+	newAccessTokenProvider = func(configDir string) accessTokenGetter {
+		discard := slog.New(slog.NewTextHandler(io.Discard, nil))
+		provider := authpkg.NewOAuthProvider(configDir, discard)
+		configureOAuthProviderCompatibility(provider, configDir)
+		return provider
+	}
+	newLegacyTokenManager = func(configDir string) legacyTokenGetter {
+		manager := authpkg.NewManager(configDir, nil)
+		configureLegacyAuthManagerCompatibility(manager)
+		return manager
+	}
+)
+
+// Get resolves an access token for the active runtime profile.
+func (m *TokenManager) Get(ctx context.Context, configDir, explicitToken string) (AccessTokenSnapshot, error) {
+	if token := strings.TrimSpace(explicitToken); token != "" {
+		return AccessTokenSnapshot{AccessToken: token, Source: "explicit"}, nil
 	}
 	if strings.TrimSpace(configDir) == "" {
-		return "", fmt.Errorf("config directory is empty")
+		return AccessTokenSnapshot{}, fmt.Errorf("config directory is empty")
 	}
-	if filepath.Clean(configDir) == filepath.Clean(defaultConfigDir()) {
-		if tok := resolveRuntimeAuthToken(ctx, ""); tok != "" {
-			return tok, nil
+	key := tokenManagerKey{
+		configDir: canonicalTokenConfigDir(configDir),
+		profile:   strings.TrimSpace(authpkg.RuntimeProfile()),
+	}
+	entry := m.entry(key)
+	entry.mu.Lock()
+	defer entry.mu.Unlock()
+
+	now := time.Now()
+	if m != nil && m.now != nil {
+		now = m.now()
+	}
+	revision, present, err := authpkg.ReadTokenMarkerRevision(configDir)
+	if err != nil {
+		return AccessTokenSnapshot{}, err
+	}
+	if tokenSnapshotUsable(entry.snapshot, now) && present && revision != "" && revision == entry.revision {
+		return entry.snapshot, nil
+	}
+
+	// Treat the marker and credential as one optimistic snapshot. A concurrent
+	// login/refresh between the reads causes a retry instead of caching stale A
+	// under the publication marker for B.
+	for attempt := 0; attempt < 4; attempt++ {
+		beforeRevision, beforePresent, err := authpkg.ReadTokenMarkerRevision(configDir)
+		if err != nil {
+			return AccessTokenSnapshot{}, err
 		}
-		return "", noCredentialsError()
+		snapshot, err := resolveTokenSnapshotWithEdition(ctx, configDir, key.profile)
+		if err != nil {
+			return AccessTokenSnapshot{}, err
+		}
+		afterRevision, afterPresent, err := authpkg.ReadTokenMarkerRevision(configDir)
+		if err != nil {
+			return AccessTokenSnapshot{}, err
+		}
+		if beforePresent != afterPresent || beforeRevision != afterRevision {
+			continue
+		}
+		if strings.TrimSpace(snapshot.AccessToken) == "" {
+			return AccessTokenSnapshot{}, noCredentialsError()
+		}
+		if tokenSnapshotUsable(snapshot, now) && afterPresent && afterRevision != "" {
+			entry.snapshot = snapshot
+			entry.revision = afterRevision
+		} else {
+			entry.snapshot = AccessTokenSnapshot{}
+			entry.revision = ""
+		}
+		return snapshot, nil
 	}
-	tok, err := resolveAccessTokenFromDir(ctx, configDir)
+	return AccessTokenSnapshot{}, fmt.Errorf("token publication changed repeatedly while resolving credentials")
+}
+
+func (m *TokenManager) entry(key tokenManagerKey) *tokenManagerEntry {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if m.entries == nil {
+		m.entries = make(map[tokenManagerKey]*tokenManagerEntry)
+	}
+	entry := m.entries[key]
+	if entry == nil {
+		entry = &tokenManagerEntry{}
+		m.entries[key] = entry
+	}
+	return entry
+}
+
+func (m *TokenManager) Invalidate() {
+	if m == nil {
+		return
+	}
+	m.mu.Lock()
+	m.entries = make(map[tokenManagerKey]*tokenManagerEntry)
+	m.mu.Unlock()
+}
+
+func resolveTokenSnapshotWithEdition(ctx context.Context, configDir, profile string) (AccessTokenSnapshot, error) {
+	hooks := edition.Get()
+	opaqueStorage := hooks.LoadToken != nil || hooks.SaveToken != nil || hooks.DeleteToken != nil
+	provider := hooks.TokenProvider
+	if provider == nil {
+		snapshot, err := resolveAccessTokenSnapshotFromDir(ctx, configDir, profile)
+		if err != nil {
+			return AccessTokenSnapshot{}, err
+		}
+		// Opaque edition storage hooks have no publication-revision contract.
+		// Resolve them on every logical request instead of caching a token that
+		// may be replaced outside the default auth store.
+		if opaqueStorage {
+			snapshot.ExpiresAt = time.Time{}
+		}
+		return snapshot, nil
+	}
+	var fallbackSnapshot AccessTokenSnapshot
+	var fallbackCalled bool
+	token, err := provider(ctx, func() (string, error) {
+		fallbackCalled = true
+		var fallbackErr error
+		fallbackSnapshot, fallbackErr = resolveAccessTokenSnapshotFromDir(ctx, configDir, profile)
+		if fallbackErr != nil {
+			return "", fallbackErr
+		}
+		return fallbackSnapshot.AccessToken, nil
+	})
+	if err != nil {
+		return AccessTokenSnapshot{}, fmt.Errorf("edition token provider: %w", err)
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return AccessTokenSnapshot{}, noCredentialsError()
+	}
+	if fallbackCalled && token == fallbackSnapshot.AccessToken {
+		if opaqueStorage {
+			fallbackSnapshot.ExpiresAt = time.Time{}
+		}
+		return fallbackSnapshot, nil
+	}
+	// Edition providers expose no lifetime metadata, so resolve them on every
+	// logical request instead of recreating a process-lifetime string cache.
+	return AccessTokenSnapshot{AccessToken: token, Source: "edition"}, nil
+}
+
+func resolveAccessTokenSnapshotFromDir(ctx context.Context, configDir, profile string) (AccessTokenSnapshot, error) {
+	provider := newAccessTokenProvider(configDir)
+	if snapshotProvider, ok := provider.(accessTokenSnapshotGetter); ok {
+		data, err := snapshotProvider.GetTokenSnapshot(ctx)
+		if err == nil && data != nil && strings.TrimSpace(data.AccessToken) != "" {
+			return AccessTokenSnapshot{
+				AccessToken: strings.TrimSpace(data.AccessToken),
+				ExpiresAt:   data.ExpiresAt,
+				Source:      "oauth",
+			}, nil
+		}
+		if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+			return AccessTokenSnapshot{}, err
+		}
+		if strings.TrimSpace(profile) != "" {
+			return AccessTokenSnapshot{}, authpkg.ErrTokenDataNotFound
+		}
+		return resolveLegacyToken(configDir, err)
+	}
+
+	token, err := provider.GetAccessToken(ctx)
+	if err == nil && strings.TrimSpace(token) != "" {
+		return AccessTokenSnapshot{AccessToken: strings.TrimSpace(token), Source: "oauth_compat"}, nil
+	}
+	if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		return AccessTokenSnapshot{}, err
+	}
+	if strings.TrimSpace(profile) != "" {
+		return AccessTokenSnapshot{}, authpkg.ErrTokenDataNotFound
+	}
+	return resolveLegacyToken(configDir, err)
+}
+
+func resolveLegacyToken(configDir string, oauthErr error) (AccessTokenSnapshot, error) {
+	token, source, err := newLegacyTokenManager(configDir).GetToken()
+	if err == nil && strings.TrimSpace(token) != "" {
+		return AccessTokenSnapshot{AccessToken: strings.TrimSpace(token), Source: source}, nil
+	}
+	if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		return AccessTokenSnapshot{}, err
+	}
+	if oauthErr != nil {
+		return AccessTokenSnapshot{}, oauthErr
+	}
+	return AccessTokenSnapshot{}, authpkg.ErrTokenDataNotFound
+}
+
+func resolveAccessTokenFromDir(ctx context.Context, configDir string) (string, error) {
+	snapshot, err := resolveAccessTokenSnapshotFromDir(ctx, configDir, authpkg.RuntimeProfile())
 	if err != nil {
 		return "", err
 	}
-	if tok != "" {
-		return tok, nil
+	return snapshot.AccessToken, nil
+}
+
+// ResolveAuxiliaryAccessToken resolves every non-runner bearer token through
+// the same TokenManager used by MCP tool calls.
+func ResolveAuxiliaryAccessToken(ctx context.Context, configDir, explicitToken string) (string, error) {
+	snapshot, err := runtimeTokenManager.Get(ctx, configDir, explicitToken)
+	if err != nil {
+		return "", err
 	}
-	return "", noCredentialsError()
+	return snapshot.AccessToken, nil
+}
+
+func tokenSnapshotUsable(snapshot AccessTokenSnapshot, now time.Time) bool {
+	return strings.TrimSpace(snapshot.AccessToken) != "" &&
+		!snapshot.ExpiresAt.IsZero() &&
+		now.Before(snapshot.ExpiresAt.Add(-accessTokenRefreshWindow))
+}
+
+func canonicalTokenConfigDir(configDir string) string {
+	if absolute, err := filepath.Abs(configDir); err == nil {
+		return filepath.Clean(absolute)
+	}
+	return filepath.Clean(configDir)
 }
 
 func noCredentialsError() error {
 	if edition.Get().IsEmbedded {
-		return fmt.Errorf("认证信息已失效，请重新认证")
+		return fmt.Errorf("认证信息已失效，请重新认证: %w", authpkg.ErrTokenDataNotFound)
 	}
-	return fmt.Errorf("no credentials found, run: dws auth login")
+	return fmt.Errorf("no credentials found, run: dws auth login: %w", authpkg.ErrTokenDataNotFound)
 }

internal/app/access_token_resolve_test.go

@@ -5,7 +5,15 @@ package app
 
 import (
 	"context"
+	"errors"
+	"net/http"
+	"path/filepath"
+	"strings"
 	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 )
 
 func TestResolveAuxiliaryAccessToken_explicitToken(t *testing.T) {
@@ -24,3 +32,48 @@ func TestResolveAuxiliaryAccessToken_emptyConfigDir(t *testing.T) {
 		t.Fatal("expected error for empty config directory")
 	}
 }
+
+func TestResolveAccessTokenFromDirPreservesRefreshFailure(t *testing.T) {
+	root := t.TempDir()
+	configDir := filepath.Join(root, "config")
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, filepath.Join(root, "keychain"))
+
+	if err := authpkg.SaveTokenData(configDir, &authpkg.TokenData{
+		AccessToken:  "expired-access",
+		RefreshToken: "refresh-token",
+		ExpiresAt:    time.Now().Add(-time.Hour),
+		RefreshExpAt: time.Now().Add(24 * time.Hour),
+		CorpID:       "corp_refresh",
+		UserID:       "user_refresh",
+		ClientID:     "client_refresh",
+		Source:       "mcp",
+	}); err != nil {
+		t.Fatalf("SaveTokenData() error = %v", err)
+	}
+
+	originalTransport := http.DefaultTransport
+	t.Cleanup(func() {
+		http.DefaultTransport = originalTransport
+	})
+	http.DefaultTransport = refreshFailureRoundTripFunc(func(*http.Request) (*http.Response, error) {
+		return nil, errors.New("refresh endpoint rejected token")
+	})
+
+	token, err := resolveAccessTokenFromDir(context.Background(), configDir)
+	if token != "" {
+		t.Fatalf("token = %q, want empty", token)
+	}
+	if err == nil {
+		t.Fatal("resolveAccessTokenFromDir() error = nil")
+	}
+	if !strings.Contains(err.Error(), "refresh endpoint rejected token") {
+		t.Fatalf("error = %q, want original refresh failure", err)
+	}
+}
+
+type refreshFailureRoundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f refreshFailureRoundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}

internal/app/api_command.go

@@ -38,6 +38,19 @@ type apiFlags struct {
 	baseURL   string
 }
 
+type appTokenGetter interface {
+	GetToken(context.Context) (string, error)
+}
+
+var newAppTokenProvider = func(configDir, appKey, appSecret string) appTokenGetter {
+	return &authpkg.AppTokenProvider{ConfigDir: configDir, AppKey: appKey, AppSecret: appSecret}
+}
+
+var (
+	apiClientID     = authpkg.ClientID
+	apiClientSecret = authpkg.ClientSecret
+)
+
 // newAPICommand creates the `dws api` subcommand for raw DingTalk OpenAPI calls.
 func newAPICommand(flags *GlobalFlags) *cobra.Command {
 	af := &apiFlags{}
@@ -271,10 +284,7 @@ func parseQueryStringToJSON(rawQuery string) string {
 		return "{}"
 	}
 
-	data, err := json.Marshal(paramsMap)
-	if err != nil {
-		return "{}"
-	}
+	data, _ := json.Marshal(paramsMap)
 	return string(data)
 }
 
@@ -289,8 +299,8 @@ func resolveRawAPIToken(ctx context.Context, explicitToken string) (string, erro
 	}
 
 	// Resolve app credentials (clientID/clientSecret).
-	appKey := authpkg.ClientID()
-	appSecret := authpkg.ClientSecret()
+	appKey := apiClientID()
+	appSecret := apiClientSecret()
 
 	if appKey == "" || appSecret == "" || strings.HasPrefix(appKey, "<") || strings.HasPrefix(appSecret, "<") {
 		return "", apperrors.NewAuth(
@@ -308,11 +318,7 @@ func resolveRawAPIToken(ctx context.Context, explicitToken string) (string, erro
 
 	// Use AppTokenProvider for automatic caching and refresh.
 	configDir := defaultConfigDir()
-	provider := &authpkg.AppTokenProvider{
-		ConfigDir: configDir,
-		AppKey:    appKey,
-		AppSecret: appSecret,
-	}
+	provider := newAppTokenProvider(configDir, appKey, appSecret)
 	token, err := provider.GetToken(ctx)
 	if err != nil {
 		return "", apperrors.NewAuth(fmt.Sprintf("获取应用级访问令牌失败: %v", err))

internal/app/app_small_coverage_test.go

@@ -0,0 +1,404 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/plugin"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type appFailWriter struct{ err error }
+
+func (w appFailWriter) Write([]byte) (int, error) { return 0, w.err }
+
+type fakeAccessTokenGetter struct {
+	token string
+	err   error
+}
+
+func (g fakeAccessTokenGetter) GetAccessToken(context.Context) (string, error) {
+	return g.token, g.err
+}
+
+func (g fakeAccessTokenGetter) ForceRefreshRejectedToken(context.Context, string) (string, error) {
+	return g.token, g.err
+}
+
+type fakeLegacyTokenGetter struct {
+	token string
+	err   error
+}
+
+func (g fakeLegacyTokenGetter) GetToken() (string, string, error) {
+	return g.token, "test", g.err
+}
+
+type fakeAppTokenGetter struct {
+	token string
+	err   error
+}
+
+func (g fakeAppTokenGetter) GetToken(context.Context) (string, error) { return g.token, g.err }
+
+type fakeSkillDirEntry struct{ dir bool }
+
+func (e fakeSkillDirEntry) Name() string               { return "entry" }
+func (e fakeSkillDirEntry) IsDir() bool                { return e.dir }
+func (e fakeSkillDirEntry) Type() os.FileMode          { return 0 }
+func (e fakeSkillDirEntry) Info() (os.FileInfo, error) { return nil, nil }
+
+func docPreflightServer(t *testing.T, result map[string]any) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var request struct {
+			ID int `json:"id"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&request)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"jsonrpc": "2.0",
+			"id":      request.ID,
+			"result":  result,
+		})
+	}))
+}
+
+func TestCrossPlatformCoverageDocDownloadPreflightCoverage(t *testing.T) {
+	runner := &runtimeRunner{}
+	base := executor.Invocation{CanonicalProduct: "doc", Tool: "download_file", Params: map[string]any{"nodeId": " node "}}
+	if err := runner.preflightDocDownload(context.Background(), transport.NewClient(nil), "", executor.Invocation{}); err != nil {
+		t.Fatal(err)
+	}
+	if err := runner.preflightDocDownload(context.Background(), transport.NewClient(nil), "", executor.Invocation{CanonicalProduct: "DOC", Tool: "download_file"}); err != nil {
+		t.Fatal(err)
+	}
+	if !isDocDownloadInvocation(base) || docDownloadNodeID(map[string]any{"node": " n "}) != "n" || docDownloadNodeID(map[string]any{"dentryUuid": " d "}) != "d" || docDownloadNodeID(map[string]any{"nodeId": 1}) != "" {
+		t.Fatal("doc download invocation helpers returned unexpected values")
+	}
+	if documentInfoExtension(map[string]any{"data": map[string]any{"extension": " doc "}}) != "doc" ||
+		documentInfoExtension(map[string]any{"extension": " pdf "}) != "pdf" ||
+		stringAtPath(map[string]any{"x": "value"}, "x", "nested") != "" ||
+		stringAtPath(map[string]any{"x": 1}, "x") != "" {
+		t.Fatal("document extension helpers returned unexpected values")
+	}
+	if unsupportedAXLSDownloadError() == nil {
+		t.Fatal("missing AXLS validation error")
+	}
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	hookErr := errors.New("classified")
+	for _, tc := range []struct {
+		name   string
+		result map[string]any
+		hooks  *edition.Hooks
+		want   string
+	}{
+		{name: "ok", result: map[string]any{"content": map[string]any{"result": map[string]any{"extension": "docx"}}}, hooks: &edition.Hooks{}},
+		{name: "edition classifier", result: map[string]any{"content": map[string]any{}}, hooks: &edition.Hooks{ClassifyToolResult: func(map[string]any) error { return hookErr }}, want: "classified"},
+		{name: "pat", result: map[string]any{"content": map[string]any{"errorCode": "PAT_NO_PERMISSION"}}, hooks: &edition.Hooks{}, want: "PAT_NO_PERMISSION"},
+		{name: "mcp error", result: map[string]any{"isError": true, "content": []map[string]any{{"type": "text", "text": "mcp failed"}}}, hooks: &edition.Hooks{}, want: "mcp failed"},
+		{name: "business error", result: map[string]any{"content": map[string]any{"success": false, "errorMsg": "business failed"}}, hooks: &edition.Hooks{}, want: "business failed"},
+		{name: "axls", result: map[string]any{"content": map[string]any{"data": map[string]any{"extension": "AXLS"}}}, hooks: &edition.Hooks{}, want: "extension=axls"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			edition.Override(tc.hooks)
+			server := docPreflightServer(t, tc.result)
+			defer server.Close()
+			client := transport.NewClient(nil)
+			client.TrustedDomains = []string{"127.0.0.1"}
+			err := runner.preflightDocDownload(context.Background(), client, server.URL, base)
+			if tc.want == "" && err != nil {
+				t.Fatalf("preflight error = %v", err)
+			}
+			if tc.want != "" && (err == nil || !strings.Contains(err.Error(), tc.want)) {
+				t.Fatalf("preflight error = %v, want %q", err, tc.want)
+			}
+		})
+	}
+	server := docPreflightServer(t, map[string]any{})
+	endpoint := server.URL
+	server.Close()
+	client := transport.NewClient(nil)
+	client.TrustedDomains = []string{"127.0.0.1"}
+	client.MaxRetries = 0
+	if err := runner.preflightDocDownload(context.Background(), client, endpoint, base); err == nil {
+		t.Fatal("network preflight failure succeeded")
+	}
+}
+
+func TestCrossPlatformCoverageRootHelpRemainingCoverage(t *testing.T) {
+	configureRootHelp(nil)
+	renderRootGlobalFlags(nil)
+	if visiblePersistentFlags(nil) != nil || formatRootFlag(nil) != "" || commandShort(nil) != "" || visibleMCPRootCommands(nil) != nil || visibleUtilityRootCommands(nil) != nil {
+		t.Fatal("nil root helper contract changed")
+	}
+
+	oldEdition := edition.Get()
+	edition.Override(&edition.Hooks{VisibleProducts: func() []string { return []string{"service"} }})
+	t.Cleanup(func() { edition.Override(oldEdition); SetDynamicServers(nil) })
+	root := &cobra.Command{Use: "root", Long: "long help"}
+	root.SetOut(io.Discard)
+	root.PersistentFlags().StringP("value", "x", "", "value")
+	root.PersistentFlags().Bool("hidden", false, "hidden")
+	_ = root.PersistentFlags().MarkHidden("hidden")
+	root.AddCommand(&cobra.Command{Use: "service", Short: "service"}, &cobra.Command{Use: "utility", Short: "utility"})
+	configureRootHelp(root)
+	if err := root.Commands()[0].Help(); err != nil {
+		t.Fatal(err)
+	}
+	root.SetArgs([]string{"help", "missing"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	root.SetArgs([]string{"help", "utility"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if got := formatRootFlag(root.PersistentFlags().Lookup("value")); !strings.Contains(got, "-x") {
+		t.Fatalf("formatted flag = %q", got)
+	}
+	if got := formatRootFlag(root.PersistentFlags().Lookup("hidden")); !strings.Contains(got, "--hidden") {
+		t.Fatalf("formatted long flag = %q", got)
+	}
+	_ = commandShort(&cobra.Command{Use: "help", Short: "Help about any command"})
+	renderRootGlobalFlags(&cobra.Command{Use: "no-flags"})
+	edition.Override(&edition.Hooks{})
+	SetDynamicServers(nil)
+	_ = visibleMCPRootCommands(root)
+}
+
+func TestCrossPlatformCoverageConfigAndTokenSeamsCoverage(t *testing.T) {
+	oldHome, oldExe, oldEval := userHomeDir, executablePath, evaluateSymlink
+	oldEdition := edition.Get()
+	t.Cleanup(func() {
+		userHomeDir, executablePath, evaluateSymlink = oldHome, oldExe, oldEval
+		edition.Override(oldEdition)
+	})
+	t.Setenv("DWS_CONFIG_DIR", "")
+	edition.Override(&edition.Hooks{})
+	userHomeDir = func() (string, error) { return "", errors.New("home") }
+	executablePath = func() (string, error) { return "", errors.New("exe") }
+	if got := defaultConfigDir(); got != ".dws" {
+		t.Fatalf("fallback config dir = %q", got)
+	}
+	executablePath = func() (string, error) { return filepath.Join("", "tmp", "dws"), nil }
+	evaluateSymlink = func(string) (string, error) { return "", errors.New("link") }
+	if got := exeRelativeConfigDir(); !strings.HasSuffix(got, filepath.Join("tmp", ".dws")) {
+		t.Fatalf("executable config dir = %q", got)
+	}
+	userHomeDir = func() (string, error) { return "/home/test", nil }
+	if got := defaultConfigDir(); got != filepath.Join("/home/test", ".dws") {
+		t.Fatalf("home config dir = %q", got)
+	}
+	edition.Override(&edition.Hooks{ConfigDir: func() string { return "/edition" }})
+	if got := defaultConfigDir(); got != "/edition" {
+		t.Fatalf("edition config dir = %q", got)
+	}
+
+	oldProvider, oldManager := newAccessTokenProvider, newLegacyTokenManager
+	t.Cleanup(func() { newAccessTokenProvider, newLegacyTokenManager = oldProvider, oldManager })
+	newAccessTokenProvider = func(string) accessTokenGetter { return fakeAccessTokenGetter{err: authpkg.ErrTokenDecryption} }
+	if _, err := resolveAccessTokenFromDir(context.Background(), "unused"); !errors.Is(err, authpkg.ErrTokenDecryption) {
+		t.Fatalf("decryption error = %v", err)
+	}
+	newAccessTokenProvider = func(string) accessTokenGetter {
+		return fakeAccessTokenGetter{err: authpkg.ErrTokenDataNotFound}
+	}
+	newLegacyTokenManager = func(string) legacyTokenGetter { return fakeLegacyTokenGetter{token: " legacy "} }
+	if got, err := resolveAccessTokenFromDir(context.Background(), "unused"); err != nil || got != "legacy" {
+		t.Fatalf("legacy token = %q, %v", got, err)
+	}
+	authpkg.SetRuntimeProfile("corp:user")
+	t.Cleanup(func() { authpkg.SetRuntimeProfile("") })
+	if got, err := resolveAccessTokenFromDir(context.Background(), "unused"); got != "" || !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("explicit profile fallback = token %q error %v, want profile error", got, err)
+	}
+	authpkg.SetRuntimeProfile("")
+	newAccessTokenProvider = func(string) accessTokenGetter { return fakeAccessTokenGetter{err: errors.New("load")} }
+	newLegacyTokenManager = func(string) legacyTokenGetter { return fakeLegacyTokenGetter{err: errors.New("missing")} }
+	edition.Override(&edition.Hooks{})
+	other := filepath.Join(t.TempDir(), "other")
+	if _, err := ResolveAuxiliaryAccessToken(context.Background(), other, ""); err == nil {
+		t.Fatal("auxiliary provider failure succeeded")
+	}
+	newAccessTokenProvider = func(string) accessTokenGetter { return fakeAccessTokenGetter{err: authpkg.ErrTokenDecryption} }
+	if _, err := ResolveAuxiliaryAccessToken(context.Background(), other, ""); !errors.Is(err, authpkg.ErrTokenDecryption) {
+		t.Fatalf("auxiliary decryption error = %v", err)
+	}
+	t.Setenv("DWS_CONFIG_DIR", other)
+	ResetRuntimeTokenCache()
+	if _, err := ResolveAuxiliaryAccessToken(context.Background(), other, ""); err == nil {
+		t.Fatal("current config without credentials succeeded")
+	}
+	edition.Override(&edition.Hooks{IsEmbedded: true})
+	if !strings.Contains(noCredentialsError().Error(), "认证") {
+		t.Fatal("embedded credentials error changed")
+	}
+}
+
+func TestCrossPlatformCoverageForceRefreshAndStdioFailureCoverage(t *testing.T) {
+	oldLoad, oldFactory := loadRefreshTokenData, newRefreshProvider
+	oldStop := stopStdio
+	t.Cleanup(func() {
+		loadRefreshTokenData, newRefreshProvider = oldLoad, oldFactory
+		stopStdio = oldStop
+		stdioMu.Lock()
+		stdioClients = make(map[string]*transport.StdioClient)
+		stdioMu.Unlock()
+	})
+	fail := errors.New("failure")
+	_ = oldFactory(t.TempDir())
+	loadRefreshTokenData = func(string) (*authpkg.TokenData, error) { return nil, fail }
+	if _, err := ForceRefreshAccessToken(context.Background(), "config"); !errors.Is(err, fail) {
+		t.Fatalf("load rejected token error = %v", err)
+	}
+	loadRefreshTokenData = func(string) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{AccessToken: "rejected"}, nil
+	}
+	for _, tc := range []struct {
+		getter fakeAccessTokenGetter
+		want   string
+	}{
+		{getter: fakeAccessTokenGetter{err: fail}, want: "failure"},
+		{getter: fakeAccessTokenGetter{token: "  "}, want: "empty"},
+		{getter: fakeAccessTokenGetter{token: " refreshed "}},
+	} {
+		newRefreshProvider = func(string) rejectedAccessTokenRefresher { return tc.getter }
+		got, err := ForceRefreshAccessToken(context.Background(), "config")
+		if tc.want != "" && (err == nil || !strings.Contains(err.Error(), tc.want)) {
+			t.Fatalf("refresh error = %v, want %q", err, tc.want)
+		}
+		if tc.want == "" && (err != nil || got != "refreshed") {
+			t.Fatalf("refreshed token = %q, %v", got, err)
+		}
+	}
+
+	stopStdio = func(*transport.StdioClient) error { return fail }
+	RegisterStdioClient("all", transport.NewStdioClient("unused", nil, nil))
+	StopAllStdioClients()
+	RegisterStdioClient("one", transport.NewStdioClient("unused", nil, nil))
+	if !StopStdioClient("one") {
+		t.Fatal("registered stdio client not stopped")
+	}
+	RegisterStdioClient("plugin/server", transport.NewStdioClient("unused", nil, nil))
+	if got := StopStdioClientsByPlugin("plugin"); got != 1 {
+		t.Fatalf("stopped plugin clients = %d", got)
+	}
+}
+
+func TestCrossPlatformCoverageOverlayRecoveryHostAndHelperRemainingCoverage(t *testing.T) {
+	root := t.TempDir()
+	writeOverlay := filepath.Join(root, "overlay.json")
+	if err := os.WriteFile(writeOverlay, []byte(`{"toolOverrides":{"tool":{}}}`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, raw := range []json.RawMessage{
+		json.RawMessage(`"missing.json"`),
+		json.RawMessage(`"unterminated`),
+		json.RawMessage(`{`),
+		json.RawMessage(`"overlay.json"`),
+		json.RawMessage(`{"id":"","command":"","toolOverrides":{"tool":{}}}`),
+	} {
+		p := &plugin.Plugin{Root: root, Manifest: plugin.Manifest{Name: "plugin", Description: "description", MCPServers: map[string]*plugin.MCPServer{"server": {CLI: raw}}}}
+		overlay := resolveStdioOverlay(p, plugin.StdioServerClient{Key: "server", Client: transport.NewStdioClient("unused", nil, nil)})
+		if overlay.ID == "" || overlay.Command == "" {
+			t.Fatalf("overlay defaults missing: %#v", overlay)
+		}
+	}
+	p := &plugin.Plugin{Root: root, Manifest: plugin.Manifest{Name: "plugin", Description: "description", MCPServers: map[string]*plugin.MCPServer{"server": {CLI: json.RawMessage(`{}`)}}}}
+	if descriptor := registerStdioServerFromManifest(p, plugin.StdioServerClient{Key: "server"}); descriptor.Endpoint == "" {
+		t.Fatalf("empty overlay descriptor = %#v", descriptor)
+	}
+	p.Manifest.MCPServers["server"].CLI = json.RawMessage(`{"toolOverrides":{"tool":{}}}`)
+	if descriptor := registerStdioServerFromManifest(p, plugin.StdioServerClient{Key: "server", Client: transport.NewStdioClient("unused", nil, nil)}); descriptor.Endpoint == "" {
+		t.Fatalf("stdio overlay registration = %#v", descriptor)
+	}
+
+	oldEdition := edition.Get()
+	t.Cleanup(func() { edition.Override(oldEdition); SetDynamicServers(nil) })
+	edition.Override(&edition.Hooks{ConfigDir: func() string { return "" }})
+	captureRuntimeFailure(executor.Invocation{}, nil, nil)
+	captureRuntimeFailure(executor.Invocation{}, errors.New("raw"), nil)
+	oldArgs := os.Args
+	os.Args = []string{"dws", "doc", "download", "--node", "n"}
+	if got := runtimeCommandPath(executor.Invocation{}); len(got) != 2 {
+		t.Fatalf("runtime command path = %#v", got)
+	}
+	os.Args = oldArgs
+
+	t.Setenv(authpkg.AgentCodeEnv, "")
+	if hostControlProviderFromEnv() != "" {
+		t.Fatal("host control enabled without agent code")
+	}
+	t.Setenv(authpkg.AgentCodeEnv, "agent")
+	edition.Override(&edition.Hooks{MergeHeaders: func(headers map[string]string) map[string]string { return headers }})
+	if got := hostControlProviderFromEnv(); got != edition.DefaultOSSClawType {
+		t.Fatalf("default claw type = %q", got)
+	}
+	edition.Override(&edition.Hooks{MergeHeaders: func(map[string]string) map[string]string { return map[string]string{"claw-type": "custom"} }})
+	if got := effectiveClawType(); got != "custom" {
+		t.Fatalf("custom claw type = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageConfigAndCacheCommandRemainingCoverage(t *testing.T) {
+	for _, command := range []*cobra.Command{newConfigCommand(), newCacheCommand()} {
+		command.SetOut(io.Discard)
+		if err := command.RunE(command, nil); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Setenv("DWS_CONFIG_DIR", "configured")
+	configCmd := &cobra.Command{Use: "config"}
+	var configOut bytes.Buffer
+	configCmd.SetOut(&configOut)
+	if err := writeConfigJSON(configCmd, filterVisible(nil), true); err != nil {
+		t.Fatal(err)
+	}
+	list := newConfigListCommand()
+	list.SetOut(io.Discard)
+	_ = list.Flags().Set("category", "core")
+	_ = list.Flags().Set("show-values", "true")
+	_ = list.Flags().Set("show-hidden", "true")
+	_ = list.Flags().Set("json", "true")
+	if err := runConfigList(list, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	cacheRoot := &cobra.Command{Use: "root"}
+	cacheRoot.PersistentFlags().String("format", "", "")
+	cacheCmd := &cobra.Command{Use: "cache"}
+	cacheRoot.AddCommand(cacheCmd)
+	for _, format := range []string{"json", "pretty", "table"} {
+		_ = cacheRoot.PersistentFlags().Set("format", format)
+		cacheCmd.SetOut(io.Discard)
+		if err := printCacheCompatNotice(cacheCmd, "status"); err != nil {
+			t.Fatal(err)
+		}
+	}
+	fail := errors.New("write")
+	cacheCmd.SetOut(appFailWriter{err: fail})
+	_ = cacheRoot.PersistentFlags().Set("format", "pretty")
+	if err := printCacheCompatNotice(cacheCmd, "status"); !errors.Is(err, fail) {
+		t.Fatalf("pretty write error = %v", err)
+	}
+	_ = cacheRoot.PersistentFlags().Set("format", "table")
+	if err := printCacheCompatNotice(cacheCmd, "status"); !errors.Is(err, fail) {
+		t.Fatalf("table write error = %v", err)
+	}
+}

internal/app/app_tiny_coverage_test.go

@@ -0,0 +1,282 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"io"
+	"io/fs"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/apiclient"
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageAPIAndTimingRemainingCoverage(t *testing.T) {
+	oldProvider := newAppTokenProvider
+	oldClientID, oldClientSecret := apiClientID, apiClientSecret
+	oldMarshal, oldMkdir := timingMarshalIndent, timingMkdirAll
+	oldWrite, oldRemove, oldRename := timingWriteFile, timingRemove, timingRename
+	oldRead, oldHome := timingReadFile, timingUserHomeDir
+	t.Cleanup(func() {
+		newAppTokenProvider = oldProvider
+		apiClientID, apiClientSecret = oldClientID, oldClientSecret
+		timingMarshalIndent, timingMkdirAll = oldMarshal, oldMkdir
+		timingWriteFile, timingRemove, timingRename = oldWrite, oldRemove, oldRename
+		timingReadFile, timingUserHomeDir = oldRead, oldHome
+		authpkg.SetClientID("")
+		authpkg.SetClientSecret("")
+	})
+	fail := errors.New("failure")
+	apiClientID = func() string { return "" }
+	apiClientSecret = func() string { return "" }
+	if _, err := resolveRawAPIToken(context.Background(), ""); err == nil {
+		t.Fatal("missing raw API credentials succeeded")
+	}
+	apiClientID = func() string { return "<placeholder>" }
+	apiClientSecret = func() string { return "secret" }
+	if _, err := resolveRawAPIToken(context.Background(), ""); err == nil {
+		t.Fatal("placeholder raw API credentials succeeded")
+	}
+	apiClientID, apiClientSecret = authpkg.ClientID, authpkg.ClientSecret
+	authpkg.SetClientID("app-key")
+	authpkg.SetClientSecret("app-secret")
+	for _, tc := range []struct {
+		getter fakeAppTokenGetter
+		want   string
+	}{
+		{getter: fakeAppTokenGetter{err: fail}, want: "failure"},
+		{getter: fakeAppTokenGetter{token: " "}, want: "为空"},
+		{getter: fakeAppTokenGetter{token: " token "}},
+	} {
+		newAppTokenProvider = func(string, string, string) appTokenGetter { return tc.getter }
+		got, err := resolveRawAPIToken(context.Background(), "")
+		if tc.want != "" && (err == nil || !containsText(err.Error(), tc.want)) {
+			t.Fatalf("raw token error = %v, want %q", err, tc.want)
+		}
+		if tc.want == "" && (err != nil || got != "token") {
+			t.Fatalf("raw token = %q, %v", got, err)
+		}
+	}
+	server := httptest.NewServer(http.HandlerFunc(func(http.ResponseWriter, *http.Request) {}))
+	endpoint := server.URL
+	server.Close()
+	apiclient.AllowedHosts["127.0.0.1"] = true
+	t.Cleanup(func() { delete(apiclient.AllowedHosts, "127.0.0.1") })
+	cmd := &cobra.Command{Use: "api"}
+	cmd.SetContext(context.Background())
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := runAPI(cmd, []string{"GET", "/path"}, &GlobalFlags{Token: "token", Timeout: 1}, &apiFlags{baseURL: endpoint}); err == nil {
+		t.Fatal("closed raw API endpoint succeeded")
+	}
+
+	collector := NewTimingCollector()
+	collector.Print(io.Discard)
+	t.Setenv(PerfReportEnv, t.TempDir()+"/report.json")
+	timingMarshalIndent = func(any, string, string) ([]byte, error) { return nil, fail }
+	collector.WriteReportIfEnabled("v", "cmd")
+	timingMarshalIndent = oldMarshal
+	timingUserHomeDir = func() (string, error) { return "", fail }
+	t.Setenv(PerfReportEnv, "auto")
+	collector.WriteReportIfEnabled("v", "cmd")
+	if defaultPerfReportPath() != "" {
+		t.Fatal("home-dir failure produced a report path")
+	}
+	t.Setenv(PerfReportEnv, t.TempDir()+"/report.json")
+	timingMkdirAll = func(string, os.FileMode) error { return fail }
+	collector.WriteReportIfEnabled("v", "cmd")
+	timingMkdirAll = oldMkdir
+	timingWriteFile = func(string, []byte, os.FileMode) error { return fail }
+	removed := false
+	timingRemove = func(string) error { removed = true; return nil }
+	collector.WriteReportIfEnabled("v", "cmd")
+	if !removed {
+		t.Fatal("failed temporary report was not removed")
+	}
+	timingWriteFile = oldWrite
+	timingRemove = oldRemove
+	renamed := false
+	timingRename = func(string, string) error { renamed = true; return fail }
+	collector.WriteReportIfEnabled("v", "cmd")
+	if !renamed {
+		t.Fatal("report rename was not attempted")
+	}
+	timingReadFile = func(string) ([]byte, error) { return []byte("{"), nil }
+	if _, err := LoadLatestReport(); err == nil {
+		t.Fatal("malformed performance report succeeded")
+	}
+}
+
+func TestCrossPlatformCoverageDirectRuntimeRemainingCoverage(t *testing.T) {
+	oldEdition := edition.Get()
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		SetDynamicServers(nil)
+	})
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	for _, raw := range []string{
+		"not a url",
+		"https://mcp.dingtalk.com/path?q=1#fragment",
+		"https://pre-mcp.example.test:8443/path/",
+		"https://mcp.example.test/path/",
+	} {
+		if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte(raw), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if got := defaultPATGatewayBaseURL(); got == "" {
+			t.Fatalf("gateway for %q is blank", raw)
+		}
+	}
+
+	endpoints := map[string]string{}
+	products := map[string]bool{}
+	aliases := map[string]string{}
+	tools := map[string]string{}
+	registerDynamicServer(mcptypes.ServerDescriptor{CLI: mcptypes.CLIOverlay{Skip: true}}, endpoints, products, aliases, tools)
+	registerDynamicServer(mcptypes.ServerDescriptor{
+		Endpoint: "https://server.test",
+		CLI: mcptypes.CLIOverlay{
+			ID: "id", Command: "command", Aliases: []string{"alias", " "},
+			Tools:         []mcptypes.CLITool{{Name: "tool"}, {Name: " "}},
+			ToolOverrides: map[string]mcptypes.CLIToolOverride{"override": {}, " ": {}},
+		},
+	}, endpoints, products, aliases, tools)
+	if endpoints["command"] == "" || aliases["alias"] != "id" || tools["override"] == "" {
+		t.Fatalf("registered dynamic server = %#v %#v %#v", endpoints, aliases, tools)
+	}
+
+	SetDynamicServers(nil)
+	dynamicMu.Lock()
+	dynamicEndpoints = map[string]string{}
+	dynamicProducts = map[string]bool{}
+	dynamicAliases = map[string]string{}
+	dynamicToolEndpoints = map[string]string{}
+	dynamicMu.Unlock()
+	if got, ok := directRuntimeEndpoint(defaultPATProductID, ""); !ok || got == "" {
+		t.Fatal("cold-start PAT fallback did not resolve")
+	}
+	SetDynamicServers(nil)
+	if _, ok := directRuntimeEndpoint(" ", " "); ok {
+		t.Fatal("blank runtime endpoint resolved")
+	}
+	t.Setenv("DINGTALK_CUSTOM_MCP_URL", "https://override.test")
+	if got, ok := directRuntimeEndpoint("custom", ""); !ok || got != "https://override.test" {
+		t.Fatalf("environment runtime endpoint = %q, %v", got, ok)
+	}
+	if got, ok := directRuntimeEndpoint(devappProductID, ""); !ok || got == "" {
+		t.Fatal("devapp fallback did not resolve")
+	}
+	if got, ok := directRuntimeEndpoint(defaultPATProductID, ""); !ok || got == "" {
+		t.Fatal("PAT fallback did not resolve")
+	}
+	edition.Override(&edition.Hooks{
+		StaticServers: func() []edition.ServerInfo { return []edition.ServerInfo{{ID: "other", Endpoint: ""}} },
+		SupplementServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{{ID: "other", Endpoint: "https://other.test", Prefixes: []string{" ", "wanted"}}}
+		},
+	})
+	if got, ok := directRuntimeEndpoint("wanted", ""); !ok || got != "https://other.test" {
+		t.Fatalf("edition runtime endpoint = %q, %v", got, ok)
+	}
+
+	dynamicMu.Lock()
+	dynamicEndpoints, dynamicProducts, dynamicAliases, dynamicToolEndpoints = nil, nil, nil, nil
+	dynamicMu.Unlock()
+	AppendDynamicServer(mcptypes.ServerDescriptor{
+		Endpoint: "https://append.test",
+		CLI: mcptypes.CLIOverlay{
+			ID: "append", Command: "append-command", Aliases: []string{"append-alias"},
+			Tools: []mcptypes.CLITool{{Name: "append-tool"}},
+			ToolOverrides: map[string]mcptypes.CLIToolOverride{
+				"append-override": {}, "skip": {ServerOverride: "other"}, " ": {},
+			},
+		},
+	})
+	if got, ok := directRuntimeToolEndpoint("append-override"); !ok || got != "https://append.test" {
+		t.Fatalf("append override endpoint = %q, %v", got, ok)
+	}
+}
+
+func containsText(value, substring string) bool {
+	for i := 0; i+len(substring) <= len(value); i++ {
+		if value[i:i+len(substring)] == substring {
+			return true
+		}
+	}
+	return false
+}
+
+func TestCrossPlatformCoverageEmbeddedSkillAndTinyCommandsRemainingCoverage(t *testing.T) {
+	oldStat, oldTemp, oldRemove := embeddedSkillStat, embeddedSkillMkdirTemp, embeddedSkillRemoveAll
+	oldWalk, oldRead := embeddedSkillWalkDir, embeddedSkillReadFile
+	oldMkdir, oldWrite := embeddedSkillMkdirAll, embeddedSkillWriteFile
+	t.Cleanup(func() {
+		embeddedSkillStat, embeddedSkillMkdirTemp, embeddedSkillRemoveAll = oldStat, oldTemp, oldRemove
+		embeddedSkillWalkDir, embeddedSkillReadFile = oldWalk, oldRead
+		embeddedSkillMkdirAll, embeddedSkillWriteFile = oldMkdir, oldWrite
+	})
+	fail := errors.New("failure")
+	embeddedSkillStat = func(string) (os.FileInfo, error) { return nil, nil }
+	embeddedSkillMkdirTemp = func(string, string) (string, error) { return "", fail }
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) {
+		t.Fatalf("embedded mkdir error = %v", err)
+	}
+	embeddedSkillMkdirTemp = func(string, string) (string, error) { return t.TempDir(), nil }
+	removed := false
+	embeddedSkillRemoveAll = func(string) error { removed = true; return nil }
+	embeddedSkillWalkDir = func(_ string, fn fs.WalkDirFunc) error {
+		return fn("entry", nil, fail)
+	}
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) || !removed {
+		t.Fatalf("embedded walk error = %v, removed=%v", err, removed)
+	}
+	embeddedSkillWalkDir = func(_ string, fn fs.WalkDirFunc) error {
+		return fn("skills/codex/file", fakeSkillDirEntry{}, nil)
+	}
+	embeddedSkillReadFile = func(string) ([]byte, error) { return nil, fail }
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) {
+		t.Fatalf("embedded read error = %v", err)
+	}
+	embeddedSkillReadFile = func(string) ([]byte, error) { return []byte("skill"), nil }
+	embeddedSkillMkdirAll = func(string, os.FileMode) error { return fail }
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) {
+		t.Fatalf("embedded nested mkdir error = %v", err)
+	}
+	embeddedSkillWalkDir = func(_ string, fn fs.WalkDirFunc) error {
+		return fn("skills/codex/dir", fakeSkillDirEntry{dir: true}, nil)
+	}
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) {
+		t.Fatalf("embedded directory mkdir error = %v", err)
+	}
+	embeddedSkillWalkDir = func(_ string, fn fs.WalkDirFunc) error {
+		return fn("skills/codex/file", fakeSkillDirEntry{}, nil)
+	}
+	embeddedSkillMkdirAll = func(string, os.FileMode) error { return nil }
+	embeddedSkillWriteFile = func(string, []byte, os.FileMode) error { return fail }
+	if _, _, err := materializeEmbeddedSkillSource("codex"); !errors.Is(err, fail) {
+		t.Fatalf("embedded write error = %v", err)
+	}
+
+	merged := mergeTopLevelCommands([]*cobra.Command{nil, {}})
+	if len(merged) != 0 {
+		t.Fatalf("empty legacy commands = %#v", merged)
+	}
+	root := &cobra.Command{Use: "root"}
+	completion := newCompletionCommand(root)
+	if err := completion.RunE(completion, []string{"other"}); err != nil {
+		t.Fatal(err)
+	}
+	catalog := newCatalogCommand(nil)
+	catalog.SetOut(io.Discard)
+	if err := catalog.RunE(catalog, nil); err != nil {
+		t.Fatal(err)
+	}
+}

internal/app/audit_command.go

@@ -0,0 +1,262 @@
+package app
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/csv"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+	"github.com/spf13/cobra"
+)
+
+var (
+	auditCSVWrite = func(writer *csv.Writer, record []string) error { return writer.Write(record) }
+	auditCSVFlush = func(writer *csv.Writer) { writer.Flush() }
+	auditCSVError = func(writer *csv.Writer) error { return writer.Error() }
+	auditExit     = os.Exit
+	auditVerify   = audit.VerifyFile
+)
+
+func newAuditCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "audit",
+		Short: "操作审计日志管理",
+		Long:  "查看、导出和校验本地操作审计日志。",
+	}
+	cmd.AddCommand(
+		newAuditTailCommand(),
+		newAuditExportCommand(),
+		newAuditVerifyCommand(),
+	)
+	return cmd
+}
+
+func newAuditTailCommand() *cobra.Command {
+	var n int
+	cmd := &cobra.Command{
+		Use:   "tail",
+		Short: "查看最近的审计记录",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if n < 1 {
+				return fmt.Errorf("--lines 必须为正整数，收到 %d", n)
+			}
+			dir := auditDir()
+			file, err := audit.LatestAuditFile(dir)
+			if err != nil {
+				return fmt.Errorf("无审计记录: %w", err)
+			}
+			lines, err := tailFile(file, n)
+			if err != nil {
+				return err
+			}
+			for _, line := range lines {
+				fmt.Println(line)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().IntVarP(&n, "lines", "n", 20, "显示最近 N 条记录")
+	return cmd
+}
+
+func newAuditExportCommand() *cobra.Command {
+	var since, until, format string
+	cmd := &cobra.Command{
+		Use:   "export",
+		Short: "导出审计日志",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			dir := auditDir()
+
+			sinceDate := strings.ReplaceAll(since, "-", "")
+			untilDate := strings.ReplaceAll(until, "-", "")
+
+			files, err := audit.AuditFilesInRange(dir, sinceDate, untilDate)
+			if err != nil {
+				return fmt.Errorf("查找审计文件失败: %w", err)
+			}
+			if len(files) == 0 {
+				return fmt.Errorf("指定范围内无审计文件")
+			}
+
+			switch format {
+			case "jsonl":
+				return exportJSONL(files)
+			case "csv":
+				return exportCSV(files)
+			default:
+				return fmt.Errorf("不支持的格式: %s（可选 jsonl, csv）", format)
+			}
+		},
+	}
+	cmd.Flags().StringVar(&since, "since", "", "起始日期 (YYYY-MM-DD)")
+	cmd.Flags().StringVar(&until, "until", "", "截止日期 (YYYY-MM-DD)")
+	cmd.Flags().StringVar(&format, "format", "jsonl", "输出格式: jsonl 或 csv")
+	return cmd
+}
+
+func newAuditVerifyCommand() *cobra.Command {
+	var file string
+	cmd := &cobra.Command{
+		Use:   "verify",
+		Short: "校验审计日志哈希链完整性",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			target := file
+			if target == "" {
+				dir := auditDir()
+				var err error
+				target, err = audit.LatestAuditFile(dir)
+				if err != nil {
+					return fmt.Errorf("无审计文件: %w", err)
+				}
+			}
+
+			valid, brokenAt, verifyErr := auditVerify(target)
+			if output.ResolveFormat(cmd, output.FormatTable) == output.FormatJSON {
+				if verifyErr != nil && brokenAt == 0 {
+					return fmt.Errorf("校验失败: %w", verifyErr)
+				}
+				payload := map[string]any{
+					"valid":    valid,
+					"file":     target,
+					"brokenAt": brokenAt,
+				}
+				if verifyErr != nil {
+					payload["reason"] = verifyErr.Error()
+				}
+				if err := output.WriteCommandPayload(cmd, payload, output.FormatTable); err != nil {
+					return err
+				}
+				if !valid {
+					auditExit(1)
+				}
+				return nil
+			}
+			if verifyErr != nil {
+				return fmt.Errorf("校验失败: %w", verifyErr)
+			}
+			if valid {
+				fmt.Printf("✓ %s 哈希链完整（全部通过）\n", filepath.Base(target))
+			} else {
+				fmt.Printf("✗ %s 哈希链在第 %d 行断裂\n", filepath.Base(target), brokenAt)
+				auditExit(1)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&file, "file", "", "指定审计文件路径（默认最新文件）")
+	return cmd
+}
+
+func auditDir() string {
+	if dir := os.Getenv(audit.EnvAuditDir); dir != "" {
+		return dir
+	}
+	return filepath.Join(defaultConfigDir(), "audit")
+}
+
+func tailFile(path string, n int) ([]string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	var lines []string
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
+	for scanner.Scan() {
+		lines = append(lines, scanner.Text())
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+
+	if len(lines) > n {
+		lines = lines[len(lines)-n:]
+	}
+	return lines, nil
+}
+
+func exportJSONL(files []string) error {
+	for _, file := range files {
+		f, err := os.Open(file)
+		if err != nil {
+			return err
+		}
+		scanner := bufio.NewScanner(f)
+		scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
+		for scanner.Scan() {
+			fmt.Println(scanner.Text())
+		}
+		f.Close()
+		if err := scanner.Err(); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func exportCSV(files []string) error {
+	w := csv.NewWriter(os.Stdout)
+
+	header := []string{"timestamp", "execution_id", "user_id", "corp_id", "product", "command", "result", "duration_ms", "error_category"}
+	if err := auditCSVWrite(w, header); err != nil {
+		return fmt.Errorf("写入 CSV 表头失败: %w", err)
+	}
+
+	for _, file := range files {
+		f, err := os.Open(file)
+		if err != nil {
+			return err
+		}
+		scanner := bufio.NewScanner(f)
+		scanner.Buffer(make([]byte, 1024*1024), 1024*1024)
+		lineNum := 0
+		for scanner.Scan() {
+			lineNum++
+			line := scanner.Bytes()
+			if len(bytes.TrimSpace(line)) == 0 {
+				continue
+			}
+			var evt audit.Event
+			if err := json.Unmarshal(line, &evt); err != nil {
+				f.Close()
+				return fmt.Errorf("解析审计记录失败 %s:%d: %w", file, lineNum, err)
+			}
+			row := []string{
+				evt.Timestamp.Format(time.RFC3339),
+				evt.ExecutionID,
+				evt.Actor.UserID,
+				evt.Actor.CorpID,
+				evt.Product,
+				evt.Command,
+				evt.Result,
+				strconv.FormatInt(evt.DurationMs, 10),
+				evt.ErrCategory,
+			}
+			if err := auditCSVWrite(w, row); err != nil {
+				f.Close()
+				return fmt.Errorf("写入 CSV 记录失败: %w", err)
+			}
+		}
+		if err := scanner.Err(); err != nil {
+			f.Close()
+			return err
+		}
+		f.Close()
+	}
+
+	auditCSVFlush(w)
+	if err := auditCSVError(w); err != nil {
+		return fmt.Errorf("刷新 CSV 输出失败: %w", err)
+	}
+	return nil
+}

internal/app/audit_command_test.go

@@ -0,0 +1,106 @@
+package app
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestAuditTailRejectsNonPositiveLines(t *testing.T) {
+	for _, n := range []string{"0", "-1"} {
+		cmd := newAuditTailCommand()
+		cmd.SetArgs([]string{"--lines", n})
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		err := cmd.Execute()
+		if err == nil {
+			t.Fatalf("--lines %s: expected error, got nil", n)
+		}
+		if !strings.Contains(err.Error(), "正整数") {
+			t.Fatalf("--lines %s: unexpected error: %v", n, err)
+		}
+	}
+}
+
+func TestTailFileReturnsLastN(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "audit-20260101.jsonl")
+	if err := os.WriteFile(path, []byte("a\nb\nc\nd\ne\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	lines, err := tailFile(path, 2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(lines) != 2 || lines[0] != "d" || lines[1] != "e" {
+		t.Fatalf("got %v, want [d e]", lines)
+	}
+}
+
+func TestExportCSVWritesHeaderAndRows(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "audit-20260101.jsonl")
+	rec := `{"timestamp":"2026-01-01T00:00:00Z","execution_id":"e1","actor":{"user_id":"u1","corp_id":"c1"},"product":"calendar","command":"event_list","result":"success","duration_ms":12,"hash":"h","prev_hash":""}`
+	if err := os.WriteFile(path, []byte(rec+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout = w
+	exportErr := exportCSV([]string{path})
+	w.Close()
+	os.Stdout = stdout
+
+	if exportErr != nil {
+		t.Fatalf("exportCSV error: %v", exportErr)
+	}
+	buf := make([]byte, 4096)
+	n, _ := r.Read(buf)
+	out := string(buf[:n])
+	if !strings.Contains(out, "timestamp,execution_id") {
+		t.Fatalf("missing CSV header, got: %q", out)
+	}
+	if !strings.Contains(out, "e1") || !strings.Contains(out, "event_list") {
+		t.Fatalf("missing CSV row data, got: %q", out)
+	}
+}
+
+// TestExportCSVFailsOnMalformedJSON guards the reviewer's V9 finding: a corrupt
+// JSONL line must surface an error with file/line evidence instead of being
+// silently skipped while the command exits 0.
+func TestExportCSVFailsOnMalformedJSON(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "audit-20260101.jsonl")
+	good := `{"timestamp":"2026-01-01T00:00:00Z","execution_id":"e1","actor":{"user_id":"u1"},"product":"calendar","command":"event_list","result":"success","duration_ms":1,"hash":"h","prev_hash":""}`
+	if err := os.WriteFile(path, []byte(good+"\nnot-json\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	stdout := os.Stdout
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	os.Stdout = w
+	exportErr := exportCSV([]string{path})
+	w.Close()
+	os.Stdout = stdout
+	// Drain the pipe so the writer never blocks.
+	buf := make([]byte, 4096)
+	_, _ = r.Read(buf)
+
+	if exportErr == nil {
+		t.Fatal("expected error on malformed JSONL, got nil")
+	}
+	if !strings.Contains(exportErr.Error(), "解析审计记录失败") {
+		t.Fatalf("error missing parse context: %v", exportErr)
+	}
+	if !strings.Contains(exportErr.Error(), ":2") {
+		t.Fatalf("error missing line evidence: %v", exportErr)
+	}
+}

internal/app/audit_coverage_more_test.go

@@ -0,0 +1,264 @@
+package app
+
+import (
+	"encoding/csv"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
+)
+
+type auditCoverageSink struct {
+	events   []*audit.Event
+	emitErr  error
+	closeErr error
+}
+
+func (sink *auditCoverageSink) Emit(event *audit.Event) error {
+	sink.events = append(sink.events, event)
+	return sink.emitErr
+}
+
+func (sink *auditCoverageSink) Close() error { return sink.closeErr }
+
+func TestCrossPlatformCoverageAuditCommandsAndFileHelpersCoverage(t *testing.T) {
+	originalExit, originalVerify := auditExit, auditVerify
+	t.Cleanup(func() { auditExit, auditVerify = originalExit, originalVerify })
+	dir := t.TempDir()
+	t.Setenv(audit.EnvAuditDir, dir)
+	if auditDir() != dir {
+		t.Fatalf("auditDir() = %q", auditDir())
+	}
+
+	tail := newAuditTailCommand()
+	tail.SetArgs([]string{"--lines", "1"})
+	if err := tail.Execute(); err == nil || !strings.Contains(err.Error(), "无审计记录") {
+		t.Fatalf("audit tail(empty) error = %v", err)
+	}
+	path := filepath.Join(dir, "audit-20260101.jsonl")
+	if err := os.WriteFile(path, []byte("one\ntwo\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	tail = newAuditTailCommand()
+	tail.SetArgs([]string{"--lines", "1"})
+	if err := tail.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tailFile(filepath.Join(dir, "missing"), 1); err == nil {
+		t.Fatal("tailFile(missing) error = nil")
+	}
+	tailErrorDir := t.TempDir()
+	if err := os.Mkdir(filepath.Join(tailErrorDir, "audit-20260101.jsonl"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(audit.EnvAuditDir, tailErrorDir)
+	tail = newAuditTailCommand()
+	if err := tail.Execute(); err == nil {
+		t.Fatal("audit tail(directory record) error = nil")
+	}
+	oversize := filepath.Join(dir, "oversize")
+	if err := os.WriteFile(oversize, []byte(strings.Repeat("x", 2*1024*1024)), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := tailFile(oversize, 1); err == nil {
+		t.Fatal("tailFile(oversize) error = nil")
+	}
+
+	exportDir := t.TempDir()
+	t.Setenv(audit.EnvAuditDir, exportDir)
+	export := newAuditExportCommand()
+	if err := export.Execute(); err == nil || !strings.Contains(err.Error(), "无审计文件") {
+		t.Fatalf("audit export(empty) error = %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(exportDir, "audit-20260102.jsonl"), []byte("{}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for _, format := range []string{"jsonl", "csv"} {
+		export = newAuditExportCommand()
+		export.SetArgs([]string{"--since", "2026-01-01", "--until", "2026-01-03", "--format", format})
+		if err := export.Execute(); err != nil {
+			t.Fatalf("audit export(%s) error = %v", format, err)
+		}
+	}
+	export = newAuditExportCommand()
+	export.SetArgs([]string{"--format", "xml"})
+	if err := export.Execute(); err == nil || !strings.Contains(err.Error(), "不支持的格式") {
+		t.Fatalf("audit export(xml) error = %v", err)
+	}
+	t.Setenv(audit.EnvAuditDir, filepath.Join(exportDir, "missing"))
+	export = newAuditExportCommand()
+	if err := export.Execute(); err == nil || !strings.Contains(err.Error(), "查找审计文件失败") {
+		t.Fatalf("audit export(missing dir) error = %v", err)
+	}
+
+	if err := exportJSONL([]string{filepath.Join(dir, "missing")}); err == nil {
+		t.Fatal("exportJSONL(missing) error = nil")
+	}
+	if err := exportJSONL([]string{oversize}); err == nil {
+		t.Fatal("exportJSONL(oversize) error = nil")
+	}
+	if err := exportCSV([]string{filepath.Join(dir, "missing")}); err == nil {
+		t.Fatal("exportCSV(missing) error = nil")
+	}
+	blank := filepath.Join(dir, "blank")
+	if err := os.WriteFile(blank, []byte("\n \n{}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := exportCSV([]string{blank}); err != nil {
+		t.Fatal(err)
+	}
+	if err := exportCSV([]string{oversize}); err == nil {
+		t.Fatal("exportCSV(oversize) error = nil")
+	}
+
+	originalWrite, originalFlush, originalError := auditCSVWrite, auditCSVFlush, auditCSVError
+	t.Cleanup(func() { auditCSVWrite, auditCSVFlush, auditCSVError = originalWrite, originalFlush, originalError })
+	auditCSVWrite = func(*csv.Writer, []string) error { return errors.New("write") }
+	if err := exportCSV(nil); err == nil || !strings.Contains(err.Error(), "表头") {
+		t.Fatalf("exportCSV(header error) = %v", err)
+	}
+	calls := 0
+	auditCSVWrite = func(writer *csv.Writer, row []string) error {
+		calls++
+		if calls > 1 {
+			return errors.New("row")
+		}
+		return originalWrite(writer, row)
+	}
+	if err := exportCSV([]string{blank}); err == nil || !strings.Contains(err.Error(), "记录") {
+		t.Fatalf("exportCSV(row error) = %v", err)
+	}
+	auditCSVWrite = originalWrite
+	auditCSVError = func(*csv.Writer) error { return errors.New("flush") }
+	if err := exportCSV(nil); err == nil || !strings.Contains(err.Error(), "刷新") {
+		t.Fatalf("exportCSV(flush error) = %v", err)
+	}
+
+	t.Setenv(audit.EnvAuditDir, t.TempDir())
+	verify := newAuditVerifyCommand()
+	if err := verify.Execute(); err == nil || !strings.Contains(err.Error(), "无审计文件") {
+		t.Fatalf("audit verify(empty) error = %v", err)
+	}
+	verify = newAuditVerifyCommand()
+	verify.SetArgs([]string{"--file", filepath.Join(dir, "missing")})
+	if err := verify.Execute(); err == nil || !strings.Contains(err.Error(), "校验失败") {
+		t.Fatalf("audit verify(missing) error = %v", err)
+	}
+	validDir := t.TempDir()
+	writer, err := audit.NewDateRotatingWriter(validDir, 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sink := audit.NewFileSink(writer, audit.NewChain(validDir), nil)
+	if err := sink.Emit(&audit.Event{Timestamp: time.Now(), Product: "test", Command: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := sink.Close(); err != nil {
+		t.Fatal(err)
+	}
+	validFile, err := audit.LatestAuditFile(validDir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	verify = newAuditVerifyCommand()
+	verify.SetArgs([]string{"--file", validFile})
+	if err := verify.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	broken := filepath.Join(t.TempDir(), "audit-broken.jsonl")
+	if err := os.WriteFile(broken, []byte(`{"prev_hash":"wrong","hash":"wrong"}`+"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	exitCode := 0
+	auditExit = func(code int) { exitCode = code }
+	auditVerify = func(string) (bool, int, error) { return false, 1, nil }
+	verify = newAuditVerifyCommand()
+	verify.SetArgs([]string{"--file", broken})
+	if err := verify.Execute(); err != nil || exitCode != 1 {
+		t.Fatalf("audit verify(broken) = %v, exit=%d", err, exitCode)
+	}
+	t.Setenv(audit.EnvAuditDir, "")
+	if auditDir() == "" {
+		t.Fatal("default auditDir() is empty")
+	}
+}
+
+func TestCrossPlatformCoverageAuditRuntimeCoverage(t *testing.T) {
+	previousSink, previousLoader := sharedAuditSink, loadTokenForProfile
+	t.Cleanup(func() {
+		sharedAuditSink = previousSink
+		loadTokenForProfile = previousLoader
+		auditSinkOnce, auditCloseOnce = sync.Once{}, sync.Once{}
+		resetAuditIdentityCache()
+	})
+
+	sharedAuditSink = nil
+	auditCloseOnce = sync.Once{}
+	CloseAuditSink()
+	failedClose := &auditCoverageSink{closeErr: errors.New("close")}
+	sharedAuditSink = failedClose
+	auditCloseOnce = sync.Once{}
+	CloseAuditSink()
+
+	bad := filepath.Join(t.TempDir(), "file")
+	if err := os.WriteFile(bad, []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(audit.EnvAudit, "1")
+	t.Setenv(audit.EnvAuditDir, filepath.Join(bad, "child"))
+	auditSinkOnce = sync.Once{}
+	sharedAuditSink = nil
+	if _, ok := setupAuditSink().(audit.NopSink); !ok {
+		t.Fatalf("setupAuditSink(error) = %T", sharedAuditSink)
+	}
+
+	t.Setenv(audit.EnvAuditDebug, "1")
+	fileLogger = logging.Setup(t.TempDir())
+	t.Cleanup(func() {
+		if fileLogger != nil {
+			fileLogger.Close()
+			fileLogger = nil
+		}
+	})
+	auditReport("coverage %d", 1)
+	loadTokenForProfile = func(string, string) (*auth.TokenData, error) { return nil, errors.New("identity") }
+	resetAuditIdentityCache()
+	if actor, _ := auditIdentity(); actor.UserID != "" {
+		t.Fatalf("auditIdentity(error) = %+v", actor)
+	}
+
+	invocation := executor.Invocation{CanonicalProduct: "calendar", Tool: "list", Params: map[string]any{"token": "secret"}}
+	emitAudit(nil, "nil", time.Now(), invocation, "https://example.com?token=secret", nil, "test")
+	emitAudit(audit.NopSink{}, "nop", time.Now(), invocation, "", nil, "test")
+	recording := &auditCoverageSink{}
+	emitAudit(recording, "ok", time.Now(), invocation, "https://example.com?token=secret", nil, "test")
+	if len(recording.events) != 1 || recording.events[0].Result != "success" {
+		t.Fatalf("successful audit events = %#v", recording.events)
+	}
+	typed := &apperrors.Error{Category: apperrors.CategoryAuth, Reason: "expired"}
+	emitAudit(recording, "typed", time.Now(), invocation, "", typed, "test")
+	if recording.events[1].ErrReason != "expired" {
+		t.Fatalf("typed audit event = %#v", recording.events[1])
+	}
+	recording.emitErr = errors.New("emit")
+	emitAudit(recording, "failed", time.Now(), invocation, "", errors.New("plain"), "test")
+	if category, reason := classifyAuditError(nil); category != "" || reason != "" {
+		t.Fatalf("classifyAuditError(nil) = %q, %q", category, reason)
+	}
+	if category, reason := classifyAuditError(fmt.Errorf("wrapped: %w", typed)); category != string(apperrors.CategoryAuth) || reason != "expired" {
+		t.Fatalf("classifyAuditError(typed) = %q, %q", category, reason)
+	}
+	if category, reason := classifyAuditError(errors.New("plain")); category != "unknown" || reason != "plain" {
+		t.Fatalf("classifyAuditError(plain) = %q, %q", category, reason)
+	}
+}

internal/app/audit_output_contract_test.go

@@ -0,0 +1,65 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package app
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func executeAuditVerifyJSON(t *testing.T, verify func(string) (bool, int, error)) (map[string]any, int, error) {
+	t.Helper()
+	previousVerify, previousExit := auditVerify, auditExit
+	t.Cleanup(func() {
+		auditVerify, auditExit = previousVerify, previousExit
+	})
+	auditVerify = verify
+	exitCode := 0
+	auditExit = func(code int) { exitCode = code }
+
+	root := &cobra.Command{Use: "dws"}
+	root.SilenceErrors = true
+	root.SilenceUsage = true
+	root.PersistentFlags().String("format", "json", "output format")
+	root.AddCommand(newAuditVerifyCommand())
+	var stdout bytes.Buffer
+	root.SetOut(&stdout)
+	root.SetArgs([]string{"verify", "--file", "/tmp/audit.jsonl"})
+	err := root.Execute()
+
+	var payload map[string]any
+	if decodeErr := json.Unmarshal(stdout.Bytes(), &payload); decodeErr != nil {
+		t.Fatalf("audit verify stdout must be one JSON document: %v\n%s", decodeErr, stdout.String())
+	}
+	return payload, exitCode, err
+}
+
+func TestCrossPlatformCoverageAuditVerifyJSONOutputIsSingleDocument(t *testing.T) {
+	payload, exitCode, err := executeAuditVerifyJSON(t, func(string) (bool, int, error) {
+		return true, 0, nil
+	})
+	if err != nil || exitCode != 0 {
+		t.Fatalf("audit verify returned err=%v exit=%d", err, exitCode)
+	}
+	if payload["valid"] != true || payload["file"] != "/tmp/audit.jsonl" || payload["brokenAt"] != float64(0) {
+		t.Fatalf("unexpected audit payload: %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageAuditVerifyBrokenJSONIncludesReasonBeforeExit(t *testing.T) {
+	payload, exitCode, err := executeAuditVerifyJSON(t, func(string) (bool, int, error) {
+		return false, 3, errors.New("prev_hash mismatch")
+	})
+	if err != nil || exitCode != 1 {
+		t.Fatalf("broken audit verify returned err=%v exit=%d", err, exitCode)
+	}
+	if payload["valid"] != false || payload["brokenAt"] != float64(3) || payload["reason"] != "prev_hash mismatch" {
+		t.Fatalf("unexpected broken audit payload: %#v", payload)
+	}
+}

internal/app/audit_runtime.go

@@ -0,0 +1,164 @@
+package app
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"runtime"
+	"sync"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+var (
+	auditSinkOnce   sync.Once
+	auditCloseOnce  sync.Once
+	sharedAuditSink audit.Sink
+
+	auditIDMu      sync.Mutex
+	cachedActor    audit.Actor
+	cachedAgentID  string
+	cachedProfile  string
+	identityLoaded bool
+
+	// loadTokenForProfile is the profile-scoped token loader. It is a package
+	// variable so profile-switch Actor attribution can be tested deterministically
+	// without touching the OS keychain.
+	loadTokenForProfile = auth.LoadTokenDataForProfile
+)
+
+// setupAuditSink builds the process-wide audit sink once and caches it so the
+// runner and the shutdown hook share a single writer/forwarder instance.
+func setupAuditSink() audit.Sink {
+	auditSinkOnce.Do(func() {
+		sink, err := audit.BuildSink(defaultConfigDir(), auditReport)
+		if err != nil {
+			auditReport("initialization failed, audit disabled for this session: %v", err)
+			sharedAuditSink = audit.NopSink{}
+			return
+		}
+		sharedAuditSink = sink
+	})
+	return sharedAuditSink
+}
+
+// CloseAuditSink flushes in-flight remote forwards and closes the audit writer.
+// It is invoked from an unconditional defer in Execute so the drain happens for
+// both successful and failed commands (Cobra skips PersistentPostRunE when RunE
+// returns an error). The sync.Once makes repeated calls safe.
+func CloseAuditSink() {
+	auditCloseOnce.Do(func() {
+		if sharedAuditSink == nil {
+			return
+		}
+		if err := sharedAuditSink.Close(); err != nil {
+			auditReport("close failed: %v", err)
+		}
+	})
+}
+
+// auditReport routes non-fatal audit-subsystem diagnostics to the structured
+// file log (always, when available) and to stderr when DWS_AUDIT_DEBUG is set,
+// so init/write/forward failures are observable instead of silently swallowed.
+func auditReport(format string, args ...any) {
+	msg := "audit: " + fmt.Sprintf(format, args...)
+	if l := FileLoggerInstance(); l != nil {
+		l.Warn(msg)
+	}
+	if audit.DebugEnabled() {
+		fmt.Fprintln(os.Stderr, "[dws] "+msg)
+	}
+}
+
+// auditIdentity resolves the Actor for the active runtime profile. The result
+// is cached per-profile so a profile switch within a long-running process (e.g.
+// serve mode) re-resolves rather than reusing a stale identity.
+func auditIdentity() (audit.Actor, string) {
+	profile := auth.RuntimeProfile()
+
+	auditIDMu.Lock()
+	defer auditIDMu.Unlock()
+	if identityLoaded && profile == cachedProfile {
+		return cachedActor, cachedAgentID
+	}
+
+	configDir := defaultConfigDir()
+	var actor audit.Actor
+	if td, err := loadTokenForProfile(configDir, profile); err == nil && td != nil {
+		actor = audit.Actor{
+			UserID:   td.UserID,
+			Name:     td.UserName,
+			CorpID:   td.CorpID,
+			CorpName: td.CorpName,
+		}
+	} else if err != nil {
+		auditReport("resolve actor for profile %q failed: %v", profile, err)
+	}
+
+	agentID := ""
+	if id := auth.Load(configDir); id != nil {
+		agentID = id.AgentID
+	}
+
+	cachedActor, cachedAgentID, cachedProfile, identityLoaded = actor, agentID, profile, true
+	return actor, agentID
+}
+
+func emitAudit(sink audit.Sink, execID string, invokeStart time.Time, invocation executor.Invocation, endpoint string, retErr error, cliVersion string) {
+	if sink == nil {
+		return
+	}
+	if _, ok := sink.(audit.NopSink); ok {
+		return
+	}
+
+	actor, agentID := auditIdentity()
+
+	result := "success"
+	var errCat, errReason string
+	if retErr != nil {
+		result = "error"
+		errCat, errReason = classifyAuditError(retErr)
+	}
+
+	paramsSummary := logging.SanitizeArguments(invocation.Params, 1024)
+
+	evt := &audit.Event{
+		Timestamp:     invokeStart,
+		ExecutionID:   execID,
+		AgentID:       agentID,
+		Actor:         actor,
+		Product:       invocation.CanonicalProduct,
+		Command:       invocation.Tool,
+		Endpoint:      transport.RedactURL(endpoint),
+		ParamsSummary: paramsSummary,
+		Result:        result,
+		ErrCategory:   errCat,
+		ErrReason:     errReason,
+		DurationMs:    time.Since(invokeStart).Milliseconds(),
+		CLIVersion:    cliVersion,
+		OS:            runtime.GOOS,
+		Arch:          runtime.GOARCH,
+	}
+
+	if err := sink.Emit(evt); err != nil {
+		auditReport("emit event failed (exec %s): %v", execID, err)
+	}
+}
+
+func classifyAuditError(err error) (category, reason string) {
+	if err == nil {
+		return "", ""
+	}
+	var typed *apperrors.Error
+	if errors.As(err, &typed) {
+		return string(typed.Category), typed.Reason
+	}
+	return "unknown", err.Error()
+}

internal/app/audit_runtime_test.go

@@ -0,0 +1,131 @@
+package app
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+)
+
+// TestAuditIdentityReresolvesOnProfileSwitch guards the reviewer's finding that a
+// long-running process (e.g. serve mode) must attribute events to the ACTIVE
+// runtime profile rather than reusing a process-global first Actor. It also
+// asserts the per-profile cache avoids redundant token loads within one profile.
+func TestAuditIdentityReresolvesOnProfileSwitch(t *testing.T) {
+	prevLoader := loadTokenForProfile
+	prevProfile := auth.RuntimeProfile()
+	t.Cleanup(func() {
+		loadTokenForProfile = prevLoader
+		auth.SetRuntimeProfile(prevProfile)
+		resetAuditIdentityCache()
+	})
+	resetAuditIdentityCache()
+
+	var mu sync.Mutex
+	calls := map[string]int{}
+	loadTokenForProfile = func(_ /*configDir*/, profile string) (*auth.TokenData, error) {
+		mu.Lock()
+		calls[profile]++
+		mu.Unlock()
+		switch profile {
+		case "orgA":
+			return &auth.TokenData{UserID: "ua", UserName: "Alice", CorpID: "ca", CorpName: "CorpA"}, nil
+		case "orgB":
+			return &auth.TokenData{UserID: "ub", UserName: "Bob", CorpID: "cb", CorpName: "CorpB"}, nil
+		default:
+			return nil, nil
+		}
+	}
+
+	auth.SetRuntimeProfile("orgA")
+	if actor, _ := auditIdentity(); actor.UserID != "ua" || actor.CorpName != "CorpA" {
+		t.Fatalf("orgA: got %+v, want Alice/CorpA", actor)
+	}
+	// Second call under the same profile must hit the cache (no extra load).
+	if actor, _ := auditIdentity(); actor.UserID != "ua" {
+		t.Fatalf("orgA cached: got %+v", actor)
+	}
+
+	auth.SetRuntimeProfile("orgB")
+	if actor, _ := auditIdentity(); actor.UserID != "ub" || actor.CorpName != "CorpB" {
+		t.Fatalf("orgB: got %+v, want Bob/CorpB (stale Actor reused?)", actor)
+	}
+
+	mu.Lock()
+	defer mu.Unlock()
+	if calls["orgA"] != 1 {
+		t.Fatalf("orgA loaded %d times, want 1 (cache miss?)", calls["orgA"])
+	}
+	if calls["orgB"] != 1 {
+		t.Fatalf("orgB loaded %d times, want 1", calls["orgB"])
+	}
+}
+
+func resetAuditIdentityCache() {
+	auditIDMu.Lock()
+	defer auditIDMu.Unlock()
+	cachedActor = audit.Actor{}
+	cachedAgentID = ""
+	cachedProfile = ""
+	identityLoaded = false
+}
+
+// TestCloseAuditSinkDrainsOnErrorPath guards the reviewer's V5 finding: when a
+// command's RunE returns an error, Cobra skips PersistentPostRunE, so the audit
+// drain must instead happen through the unconditional defer in Execute that calls
+// CloseAuditSink. This test wires a real forwarder-backed sink into the shared
+// slot and asserts CloseAuditSink flushes the queued forward exactly as the
+// error-path defer would, and that a second call is a harmless no-op.
+func TestCloseAuditSinkDrainsOnErrorPath(t *testing.T) {
+	var delivered int64
+	var releaseOnce sync.Once
+	release := make(chan struct{})
+	releaseFn := func() { releaseOnce.Do(func() { close(release) }) }
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		<-release // hold the request until the drain awaits it
+		atomic.AddInt64(&delivered, 1)
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+	defer releaseFn() // LIFO: unblock any in-flight handler before srv.Close()
+
+	writer, err := audit.NewDateRotatingWriter(t.TempDir(), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fwd := audit.NewHTTPForwarder(srv.URL, "", audit.RedactNone, nil)
+	sink := audit.NewFileSink(writer, audit.NewChain(""), fwd)
+
+	prevSink := sharedAuditSink
+	t.Cleanup(func() {
+		sharedAuditSink = prevSink
+		auditCloseOnce = sync.Once{}
+	})
+	sharedAuditSink = sink
+	auditCloseOnce = sync.Once{}
+
+	if err := sink.Emit(&audit.Event{Timestamp: time.Unix(0, 0), Product: "calendar", Command: "event_list", Result: "error"}); err != nil {
+		t.Fatalf("emit: %v", err)
+	}
+	if got := atomic.LoadInt64(&delivered); got != 0 {
+		t.Fatalf("forward delivered before drain: %d", got)
+	}
+
+	// Let the held request complete, then drain via the same entry point the
+	// error-path defer uses. CloseAuditSink blocks until the forward goroutine
+	// observes the HTTP response, so the counter is settled when it returns.
+	releaseFn()
+	CloseAuditSink()
+
+	if got := atomic.LoadInt64(&delivered); got != 1 {
+		t.Fatalf("forward not drained on error path: delivered=%d, want 1", got)
+	}
+
+	// Idempotent: the success-path PersistentPostRunE and the defer both call it.
+	CloseAuditSink()
+}

internal/app/auth_command.go

@@ -30,6 +30,7 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
@@ -82,9 +83,10 @@ func buildAuthCommand(patCaller edition.ToolCaller) *cobra.Command {
 	cmd.AddCommand(
 		newAuthLogoutCommand(),
 		newAuthStatusCommand(),
+		newAuthMigrateKeychainCommand(),
 		newAuthExportCommand(),
 		newAuthImportCommand(),
-		newAuthExchangeCommand(),
+		newAuthExchangeCommand(patCaller),
 		newAuthResetCommand(),
 	)
 	return cmd
@@ -135,7 +137,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 					AccessToken: cfg.Token,
 					ExpiresAt:   time.Now().Add(config.ManualTokenExpiry),
 				}
-				if err := authpkg.SaveTokenData(configDir, tokenData); err != nil {
+				if err := authSaveTokenData(configDir, tokenData); err != nil {
 					return apperrors.NewInternal(fmt.Sprintf("failed to persist auth token: %v", err))
 				}
 			case cfg.Device:
@@ -145,7 +147,10 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				provider := authpkg.NewDeviceFlowProvider(configDir, nil)
 				provider.Output = cmd.ErrOrStderr()
 				provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser")
-				tokenData, err = provider.Login(loginCtx)
+				provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error {
+					return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data)
+				}
+				tokenData, err = authDeviceLogin(provider, loginCtx)
 				if err != nil {
 					return apperrors.NewAuth(fmt.Sprintf("device authorization failed: %v", err))
 				}
@@ -157,8 +162,11 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				provider.Output = cmd.ErrOrStderr()
 				provider.NoBrowser, _ = cmd.Flags().GetBool("no-browser")
 				provider.TargetCorpID = cfg.TargetCorpID
+				provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error {
+					return enrichAuthLoginProfileFromContact(ctx, configDir, patCaller, data)
+				}
 				configureOAuthProviderCompatibility(provider, configDir)
-				tokenData, err = provider.Login(loginCtx, authLoginForcesAuthorization(cfg))
+				tokenData, err = authOAuthLogin(provider, loginCtx, authLoginForcesAuthorization(cfg))
 				if err != nil {
 					return apperrors.NewAuth(fmt.Sprintf("dingtalk login failed: %v", err))
 				}
@@ -166,22 +174,18 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 
 			ResetRuntimeTokenCache()
 			clearCompatCache()
-			if tokenData != nil && strings.TrimSpace(tokenData.CorpID) != "" {
-				_ = enrichAuthLoginProfileFromContact(cmd.Context(), configDir, patCaller, tokenData)
-				ResetRuntimeTokenCache()
-				clearCompatCache()
-			}
-
 			w := cmd.OutOrStdout()
 			runPostLoginAuthorization := func() error {
 				if !recommendAuthMode {
 					return nil
 				}
+				restoreProfile := replaceRuntimeProfile(authpkg.TokenProfileSelector(tokenData))
+				defer restoreProfile()
 				recommendScopeMode := pat.LoginRecommendScopeRecommended
 				var initialPlan *pat.LoginRecommendPlan
 				if postLoginTUIMode {
 					var planErr error
-					initialPlan, planErr = pat.PlanLoginRecommendAuthorization(cmd.Context(), patCaller)
+					initialPlan, planErr = authPlanLoginRecommend(cmd.Context(), patCaller)
 					if planErr != nil {
 						return planErr
 					}
@@ -206,11 +210,11 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 					retryFormat = "table"
 				}
 				run := func(ctx context.Context) error {
-					return pat.RunLoginRecommendAuthorizationWithOptions(ctx, patCaller, cmd.ErrOrStderr(), opts)
+					return authRunLoginRecommend(ctx, patCaller, cmd.ErrOrStderr(), opts)
 				}
 				err := run(cmd.Context())
 				if patErr := apperrors.AsPatAuthCheckError(err); patErr != nil {
-					return runDirectPATAuthCheckWaitOnly(
+					return authRunDirectPATWait(
 						cmd.Context(),
 						&GlobalFlags{Format: retryFormat},
 						patErr,
@@ -233,11 +237,7 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 				return err
 			}
 			fmt.Fprintln(w)
-			if !cfg.Device && tokenData != nil && tokenData.IsAccessTokenValid() && !authLoginForcesAuthorization(cfg) {
-				fmt.Fprintln(w, authLoginStatusLine("Token 有效，无需重新登录"))
-			} else {
-				fmt.Fprintln(w, authLoginStatusLine("登录成功！"))
-			}
+			fmt.Fprintln(w, authLoginStatusLine("登录成功！"))
 			if tokenData != nil {
 				if tokenData.CorpName != "" {
 					fmt.Fprintln(w, authLoginInfoLine("企业", tokenData.CorpName))
@@ -278,11 +278,53 @@ func newAuthLoginCommand(patCaller edition.ToolCaller) *cobra.Command {
 }
 
 var (
-	authLoginGuideActionSelector    = selectAuthLoginGuideAction
-	authLoginGuideActionApplier     = applyAuthLoginGuideAction
-	loginRecommendScopeModeSelector = selectLoginRecommendScopeMode
-	loginRecommendProductSelector   = selectLoginRecommendProducts
-	authLoginInteractiveTerminal    = isInteractiveTerminal
+	authLoginGuideActionSelector     = selectAuthLoginGuideAction
+	authLoginGuideActionApplier      = applyAuthLoginGuideAction
+	authLoginManualCredentialsPrompt = promptAuthLoginManualCredentials
+	loginRecommendScopeModeSelector  = selectLoginRecommendScopeMode
+	loginRecommendProductSelector    = selectLoginRecommendProducts
+	authLoginInteractiveTerminal     = isInteractiveTerminal
+	migrateKeychainToFileDEK         = authpkg.MigrateKeychainToFileDEK
+	authMigrateTarget                = func(cmd *cobra.Command) (string, error) { return cmd.Flags().GetString("to") }
+	authRunForm                      = (*huh.Form).Run
+	authSaveTokenData                = authpkg.SaveTokenData
+	authSaveAppConfig                = authpkg.SaveAppConfig
+	authDeviceLogin                  = func(provider *authpkg.DeviceFlowProvider, ctx context.Context) (*authpkg.TokenData, error) {
+		return provider.Login(ctx)
+	}
+	authOAuthLogin = func(provider *authpkg.OAuthProvider, ctx context.Context, force bool) (*authpkg.TokenData, error) {
+		return provider.Login(ctx, force)
+	}
+	authOAuthStatus      = func(provider *authpkg.OAuthProvider) (*authpkg.TokenData, error) { return provider.Status() }
+	authOAuthAccessToken = func(provider *authpkg.OAuthProvider, ctx context.Context) (string, error) {
+		return provider.GetAccessToken(ctx)
+	}
+	authOAuthExchange = func(provider *authpkg.OAuthProvider, ctx context.Context, code, uid string) (*authpkg.TokenData, error) {
+		return provider.ExchangeAuthCode(ctx, code, uid)
+	}
+	authPlanLoginRecommend      = pat.PlanLoginRecommendAuthorization
+	authRunLoginRecommend       = pat.RunLoginRecommendAuthorizationWithOptions
+	authRunDirectPATWait        = runDirectPATAuthCheckWaitOnly
+	authResolveProfile          = authpkg.ResolveProfile
+	authResolveProfileDeletion  = authpkg.ResolveProfileDeletionScope
+	authRevokeToken             = authpkg.RevokeTokenRemote
+	authRevokeTokenForData      = authpkg.RevokeTokenRemoteForData
+	authLoadTokenForProfile     = authpkg.LoadTokenDataForProfile
+	authDeleteProfileToken      = authpkg.DeleteTokenDataForProfile
+	authEnsureProfilesMigration = authpkg.EnsureProfilesMigration
+	authLoadProfiles            = authpkg.LoadProfiles
+	authDeleteAllTokenData      = authpkg.DeleteAllTokenData
+	authDeleteTokenData         = authpkg.DeleteTokenData
+	authMarkProfileStatus       = authpkg.MarkProfileStatus
+	authPortableExportSupported = authpkg.PortableExportSupported
+	authPortableSourceReady     = authpkg.PortableAuthSourceReady
+	authPortableTargetPopulated = authpkg.PortableAuthTargetPopulated
+	authExportPortableBundle    = authpkg.ExportPortableAuthBundle
+	authImportPortableBundle    = authpkg.ImportPortableAuthBundle
+	authAtomicWrite             = helpers.AtomicWrite
+	authReadFile                = os.ReadFile
+	authRemove                  = os.Remove
+	authDeleteAppConfig         = authpkg.DeleteAppConfig
 )
 
 func selectAuthLoginGuideAction() (authLoginGuideAction, error) {
@@ -299,7 +341,7 @@ func selectAuthLoginGuideAction() (authLoginGuideAction, error) {
 				Value(&choice),
 		),
 	).WithTheme(authLoginHuhTheme())
-	if err := form.Run(); err != nil {
+	if err := authRunForm(form); err != nil {
 		return "", fmt.Errorf("使用引导选择中止: %w", err)
 	}
 	return choice, nil
@@ -313,13 +355,13 @@ func applyAuthLoginGuideAction(cmd *cobra.Command, configDir string, action auth
 		fmt.Fprintln(cmd.ErrOrStderr(), "一键配置智能体应用暂未开放，已继续使用 CLI 登录")
 		return nil
 	case authLoginGuideManualCredentials:
-		clientID, clientSecret, err := promptAuthLoginManualCredentials()
+		clientID, clientSecret, err := authLoginManualCredentialsPrompt()
 		if err != nil {
 			return err
 		}
 		authpkg.SetClientID(clientID)
 		authpkg.SetClientSecret(clientSecret)
-		if err := authpkg.SaveAppConfig(configDir, &authpkg.AppConfig{
+		if err := authSaveAppConfig(configDir, &authpkg.AppConfig{
 			ClientID:     clientID,
 			ClientSecret: authpkg.PlainSecret(clientSecret),
 		}); err != nil {
@@ -333,33 +375,34 @@ func applyAuthLoginGuideAction(cmd *cobra.Command, configDir string, action auth
 
 func promptAuthLoginManualCredentials() (string, string, error) {
 	var clientID, clientSecret string
-	nonEmpty := func(label string) func(string) error {
-		return func(value string) error {
-			if strings.TrimSpace(value) == "" {
-				return fmt.Errorf("%s 不能为空", label)
-			}
-			return nil
-		}
-	}
 	form := huh.NewForm(
 		huh.NewGroup(
 			huh.NewInput().
 				Title("输入 AppKey").
 				Value(&clientID).
-				Validate(nonEmpty("AppKey")),
+				Validate(authLoginNonEmpty("AppKey")),
 			huh.NewInput().
 				Title("输入 AppSecret").
 				EchoMode(huh.EchoModePassword).
 				Value(&clientSecret).
-				Validate(nonEmpty("AppSecret")),
+				Validate(authLoginNonEmpty("AppSecret")),
 		),
 	).WithTheme(authLoginHuhTheme())
-	if err := form.Run(); err != nil {
+	if err := authRunForm(form); err != nil {
 		return "", "", fmt.Errorf("应用凭证输入中止: %w", err)
 	}
 	return strings.TrimSpace(clientID), strings.TrimSpace(clientSecret), nil
 }
 
+func authLoginNonEmpty(label string) func(string) error {
+	return func(value string) error {
+		if strings.TrimSpace(value) == "" {
+			return fmt.Errorf("%s 不能为空", label)
+		}
+		return nil
+	}
+}
+
 func selectLoginRecommendScopeMode() (pat.LoginRecommendScopeMode, error) {
 	choice := pat.LoginRecommendScopeRecommended
 	form := huh.NewForm(
@@ -374,7 +417,7 @@ func selectLoginRecommendScopeMode() (pat.LoginRecommendScopeMode, error) {
 				Value(&choice),
 		),
 	).WithTheme(authLoginHuhTheme())
-	if err := form.Run(); err != nil {
+	if err := authRunForm(form); err != nil {
 		return "", fmt.Errorf("授权范围选择中止: %w", err)
 	}
 	return choice, nil
@@ -386,9 +429,10 @@ func newAuthLogoutCommand() *cobra.Command {
 		Short: "清除认证信息（默认退出所有组织）",
 		Long: `清除本机钉钉登录态。
 
-默认退出所有已登录组织 profile；指定 --profile 时只退出该组织，不影响其他组织。`,
+默认退出全部账号。--profile 传组织时退出该组织全部账号；传精确账号或本地 profile 名时只退出一个账号。`,
 		Example: `  dws auth logout
   dws auth logout --profile <corpId>
+  dws auth logout --profile <corpId>:<userId>
   dws auth logout --profile "钉钉"`,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -418,7 +462,7 @@ func newAuthLogoutCommand() *cobra.Command {
 			return nil
 		},
 	}
-	cmd.Flags().String("profile", "", "指定要退出的 profile 名或 corpId")
+	cmd.Flags().String("profile", "", "指定组织或账号：corpId、corpName、corpId:userId、corpId:userName、corpName:userId、corpName:userName 或本地 profile 名")
 	return cmd
 }
 
@@ -431,7 +475,8 @@ func newAuthStatusCommand() *cobra.Command {
 指定 --profile 时只读取并刷新被选中的 token slot，不会修改 currentProfile。`,
 		Example: `  dws auth status
   dws auth status --profile <corpId>
-  dws auth status --profile "钉钉"
+  dws auth status --profile <corpId>:<userId>
+  dws auth status --profile "钉钉:孙博文"
   dws auth status --profile <corpId> --format json`,
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -440,40 +485,61 @@ func newAuthStatusCommand() *cobra.Command {
 			if err != nil {
 				return apperrors.NewInternal("failed to read --profile")
 			}
+			profileSelector = strings.TrimSpace(profileSelector)
+			if profileSelector != "" {
+				selected, resolveErr := authpkg.ResolveProfile(configDir, profileSelector)
+				if resolveErr != nil {
+					return apperrors.NewValidation(resolveErr.Error())
+				}
+				if selected == nil {
+					return apperrors.NewValidation(fmt.Sprintf("profile %q not found", profileSelector))
+				}
+				profileSelector = authpkg.ProfileSelector(*selected)
+			}
 			restoreProfile := pushRuntimeProfile(profileSelector)
 			defer restoreProfile()
 
 			authenticated := false
 			refreshed := false
 			var tokenData *authpkg.TokenData
+			var statusErr error
+			var refreshFailure error
 			provider := authpkg.NewOAuthProvider(configDir, nil)
 			configureOAuthProviderCompatibility(provider, configDir)
-			if data, err := provider.Status(); err == nil {
+			if data, err := authOAuthStatus(provider); err == nil {
 				tokenData = data
 				if !data.IsAccessTokenValid() && data.IsRefreshTokenValid() {
 					refreshCtx, cancel := context.WithTimeout(cmd.Context(), 15*time.Second)
-					_, refreshErr := provider.GetAccessToken(refreshCtx)
+					_, refreshErr := authOAuthAccessToken(provider, refreshCtx)
 					cancel()
 					if refreshErr == nil {
-						if updatedData, statusErr := provider.Status(); statusErr == nil {
+						if updatedData, statusErr := authOAuthStatus(provider); statusErr == nil {
 							tokenData = updatedData
 							refreshed = true
 						}
 					} else if edition.Get().AutoPurgeToken {
-						_ = authpkg.DeleteTokenData(configDir)
+						refreshFailure = refreshErr
+						_ = authDeleteTokenData(configDir)
 					} else if tokenData != nil {
-						_ = authpkg.MarkProfileStatus(configDir, tokenData.CorpID, authpkg.ProfileStatusExpired)
+						refreshFailure = refreshErr
+						_ = authMarkProfileStatus(configDir, authpkg.TokenProfileSelector(tokenData), authpkg.ProfileStatusExpired)
 					}
 				}
-				if authStatusAuthenticated(tokenData) {
+				if refreshFailure == nil && authStatusAuthenticated(tokenData) {
 					authenticated = true
 				}
+			} else {
+				statusErr = err
+			}
+			diagnostic := authStatusDiagnosticFromError(statusErr)
+			if refreshFailure != nil {
+				diagnostic = authStatusRefreshDiagnostic(refreshFailure)
 			}
 
 			// Check if JSON output is requested
 			format, _ := cmd.Root().PersistentFlags().GetString("format")
 			if strings.EqualFold(strings.TrimSpace(format), "json") {
-				return writeAuthStatusJSON(cmd.OutOrStdout(), authenticated, refreshed, tokenData)
+				return writeAuthStatusJSON(cmd.OutOrStdout(), authenticated, refreshed, tokenData, diagnostic)
 			}
 
 			// Default table output
@@ -503,48 +569,130 @@ func newAuthStatusCommand() *cobra.Command {
 				}
 			} else {
 				fmt.Fprintf(w, "%-16s%s\n", "状态:", "未登录")
-				if !edition.Get().IsEmbedded {
+				if diagnostic != nil {
+					fmt.Fprintf(w, "%-16s%s\n", "原因:", diagnostic.Message)
+					fmt.Fprintf(w, "%-16s%s\n", "提示:", diagnostic.Hint)
+				} else if !edition.Get().IsEmbedded {
 					fmt.Fprintln(w, "运行 dws auth login --recommend 进行登录")
 				}
 			}
 			return nil
 		},
 	}
-	cmd.Flags().String("profile", "", "指定要查看的 profile 名或 corpId")
+	cmd.Flags().String("profile", "", "指定组织或账号：corpId、corpName、corpId:userId、corpId:userName、corpName:userId、corpName:userName 或本地 profile 名")
+	return cmd
+}
+
+func newAuthMigrateKeychainCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "migrate-keychain",
+		Short: "将 macOS 系统 Keychain 登录态安全迁移到 file-DEK",
+		Long: `将 dws-cli 的 legacy 与 profile 登录 token 统一重加密为 file-DEK，使 Codex 等沙箱进程与普通终端共享同一登录态。
+
+迁移必须从仍可读取原登录态的系统 Keychain 模式运行。命令会先验证全部认证密文；任何认证条目不可解密时均不会写入。应用密钥等无关条目不在迁移范围内。
+先用 --dry-run 预检，确认后加 --yes 执行。`,
+		Example: `  env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run --format json
+  env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --yes --format json`,
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			target, err := authMigrateTarget(cmd)
+			if err != nil {
+				return apperrors.NewInternal("failed to read --to")
+			}
+			if strings.TrimSpace(target) != "file-dek" {
+				return apperrors.NewValidation("--to 当前仅支持 file-dek")
+			}
+			if os.Getenv(keychain.DisableKeychainEnv) != "" {
+				return apperrors.NewValidation(fmt.Sprintf(
+					"迁移必须从系统 Keychain 模式运行；请使用 `env -u %s dws auth migrate-keychain --to file-dek ...`",
+					keychain.DisableKeychainEnv,
+				))
+			}
+
+			dryRun, _ := cmd.Root().PersistentFlags().GetBool("dry-run")
+			yes, _ := cmd.Root().PersistentFlags().GetBool("yes")
+			if !dryRun && !yes {
+				return apperrors.NewValidation("迁移会重加密全部本地登录 token；请先使用 --dry-run 预检，确认后加 --yes 执行")
+			}
+			count, err := migrateKeychainToFileDEK(defaultConfigDir(), dryRun)
+			if err != nil {
+				return apperrors.NewInternal(fmt.Sprintf("keychain migration failed: %v", err))
+			}
+
+			result := struct {
+				Success bool   `json:"success"`
+				DryRun  bool   `json:"dry_run"`
+				Target  string `json:"target"`
+				Entries int    `json:"entries"`
+			}{Success: true, DryRun: dryRun, Target: "file-dek", Entries: count}
+			format, _ := cmd.Root().PersistentFlags().GetString("format")
+			if strings.EqualFold(strings.TrimSpace(format), "json") {
+				return json.NewEncoder(cmd.OutOrStdout()).Encode(result)
+			}
+			if dryRun {
+				fmt.Fprintf(cmd.OutOrStdout(), "预检通过：%d 个本地认证条目可迁移到 file-DEK\n", count)
+			} else {
+				fmt.Fprintf(cmd.OutOrStdout(), "迁移完成：%d 个本地认证条目已统一使用 file-DEK\n", count)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().String("to", "file-dek", "目标密钥后端（当前仅支持 file-dek）")
 	return cmd
 }
 
 func logoutOneProfile(_ *cobra.Command, ctx context.Context, configDir, selector string) error {
-	if _, err := authpkg.ResolveProfile(configDir, selector); err != nil {
+	selected, exact, err := authResolveProfileDeletion(configDir, selector)
+	if err != nil {
 		return apperrors.NewValidation(err.Error())
 	}
-	restoreProfile := pushRuntimeProfile(selector)
-	defer restoreProfile()
-	_ = authpkg.RevokeTokenRemote(ctx)
-	if err := authpkg.DeleteTokenDataForProfile(configDir, selector); err != nil {
+	if selected == nil {
+		return apperrors.NewValidation(fmt.Sprintf("profile %q not found", selector))
+	}
+	stableSelector := selected.CorpID
+	if exact {
+		stableSelector = authpkg.ProfileSelector(*selected)
+		if data, loadErr := authLoadTokenForProfile(configDir, stableSelector); loadErr == nil {
+			_ = authRevokeTokenForData(ctx, data)
+		}
+	} else if cfg, loadErr := authLoadProfiles(configDir); loadErr == nil {
+		for _, profile := range cfg.Profiles {
+			if profile.CorpID != selected.CorpID {
+				continue
+			}
+			if data, tokenErr := authLoadTokenForProfile(configDir, authpkg.ProfileSelector(profile)); tokenErr == nil {
+				_ = authRevokeTokenForData(ctx, data)
+			}
+		}
+	}
+	if err := authDeleteProfileToken(configDir, stableSelector); err != nil {
+		if strings.Contains(err.Error(), "not found") {
+			return apperrors.NewValidation(err.Error())
+		}
 		return apperrors.NewInternal(fmt.Sprintf("failed to clear token data: %v", err))
 	}
 	return nil
 }
 
 func logoutAllProfiles(_ *cobra.Command, ctx context.Context, configDir string) error {
-	if err := authpkg.EnsureProfilesMigration(configDir); err != nil {
+	if err := authEnsureProfilesMigration(configDir); err != nil {
 		return apperrors.NewInternal(fmt.Sprintf("failed to migrate profiles: %v", err))
 	}
-	cfg, err := authpkg.LoadProfiles(configDir)
+	cfg, err := authLoadProfiles(configDir)
 	if err != nil {
 		return apperrors.NewInternal(fmt.Sprintf("failed to load profiles: %v", err))
 	}
 	if cfg == nil || len(cfg.Profiles) == 0 {
-		_ = authpkg.RevokeTokenRemote(ctx)
+		_ = authRevokeToken(ctx)
 	} else {
 		for _, profile := range cfg.Profiles {
-			restoreProfile := pushRuntimeProfile(profile.CorpID)
-			_ = authpkg.RevokeTokenRemote(ctx)
-			restoreProfile()
+			if data, tokenErr := authLoadTokenForProfile(configDir, authpkg.ProfileSelector(profile)); tokenErr == nil {
+				_ = authRevokeTokenForData(ctx, data)
+			}
 		}
 	}
-	if err := authpkg.DeleteAllTokenData(configDir); err != nil {
+	if err := authDeleteAllTokenData(configDir); err != nil {
 		return apperrors.NewInternal(fmt.Sprintf("failed to clear token data: %v", err))
 	}
 	return nil
@@ -562,25 +710,19 @@ func pushRuntimeProfile(selector string) func() {
 	}
 }
 
-func cleanupAuthConfigIfNoProfiles(configDir string) {
-	cfg, err := authpkg.LoadProfiles(configDir)
-	if err == nil && len(cfg.Profiles) > 0 {
-		return
+func replaceRuntimeProfile(selector string) func() {
+	previous := authpkg.RuntimeProfile()
+	authpkg.SetRuntimeProfile(strings.TrimSpace(selector))
+	return func() {
+		authpkg.SetRuntimeProfile(previous)
 	}
-	if authpkg.TokenDataExistsKeychain() {
-		return
-	}
-	appKey, _ := authpkg.ResolveAppCredentials(configDir)
-	if appKey != "" {
-		_ = authpkg.DeleteAppTokenData(appKey)
-	}
-	_ = authpkg.DeleteAppConfig(configDir)
-	_ = os.Remove(filepath.Join(configDir, "mcp_url"))
-	_ = os.Remove(filepath.Join(configDir, "token"))
-	_ = authpkg.DeleteTokenMarker(configDir)
 }
 
 func newAuthExportCommand() *cobra.Command {
+	return newAuthExportCommandWithSupport(authpkg.PortableExportSupportError)
+}
+
+func newAuthExportCommandWithSupport(supportError func() error) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "export",
 		Short: "导出可迁移认证包",
@@ -605,18 +747,21 @@ func newAuthExportCommand() *cobra.Command {
 			if !asBase64 && output == "" {
 				return apperrors.NewValidation("--output is required unless --base64 is used")
 			}
-			if !authpkg.PortableExportSupported() {
+			if err := supportError(); err != nil {
+				return apperrors.NewValidation(err.Error())
+			}
+			if !authPortableExportSupported() {
 				return apperrors.NewValidation(fmt.Sprintf(
-					"macOS 默认将 DEK 存在系统 Keychain，导出的包无法在其它机器解密；请设置 %s=1 后重新登录再导出",
+					"macOS 导出认证包需要 file-DEK 模式；请先设置 %s=1 并运行 dws auth status 验证，只有提示密钥不匹配且确认可丢弃旧登录态时，才执行 dws auth reset 后重新登录",
 					keychain.DisableKeychainEnv,
 				))
 			}
-			if !authpkg.PortableAuthSourceReady() {
+			if !authPortableSourceReady() {
 				return apperrors.NewValidation("尚未登录，请先运行 dws auth login --recommend")
 			}
 
 			var bundle bytes.Buffer
-			if err := authpkg.ExportPortableAuthBundle(defaultConfigDir(), &bundle); err != nil {
+			if err := authExportPortableBundle(defaultConfigDir(), &bundle); err != nil {
 				return apperrors.NewInternal(fmt.Sprintf("failed to export auth bundle: %v", err))
 			}
 
@@ -626,7 +771,7 @@ func newAuthExportCommand() *cobra.Command {
 					_, err := cmd.OutOrStdout().Write(payload)
 					return err
 				}
-				if err := helpers.AtomicWrite(output, payload, config.FilePerm); err != nil {
+				if err := authAtomicWrite(output, payload, config.FilePerm); err != nil {
 					return apperrors.NewInternal(fmt.Sprintf("failed to write auth bundle: %v", err))
 				}
 				fmt.Fprintf(cmd.OutOrStdout(), "[OK] 已导出认证包: %s\n", output)
@@ -634,7 +779,7 @@ func newAuthExportCommand() *cobra.Command {
 				return nil
 			}
 
-			if err := helpers.AtomicWrite(output, bundle.Bytes(), config.FilePerm); err != nil {
+			if err := authAtomicWrite(output, bundle.Bytes(), config.FilePerm); err != nil {
 				return apperrors.NewInternal(fmt.Sprintf("failed to write auth bundle: %v", err))
 			}
 			fmt.Fprintf(cmd.OutOrStdout(), "[OK] 已导出认证包: %s\n", output)
@@ -648,6 +793,10 @@ func newAuthExportCommand() *cobra.Command {
 }
 
 func newAuthImportCommand() *cobra.Command {
+	return newAuthImportCommandWithSupport(authpkg.PortableImportSupportError)
+}
+
+func newAuthImportCommandWithSupport(supportError func() error) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "import",
 		Short: "导入可迁移认证包",
@@ -676,13 +825,15 @@ func newAuthImportCommand() *cobra.Command {
 			if err != nil {
 				return apperrors.NewInternal("failed to read --force")
 			}
-
+			if err := supportError(); err != nil {
+				return apperrors.NewValidation(err.Error())
+			}
 			configDir := defaultConfigDir()
-			if !force && authpkg.PortableAuthTargetPopulated(configDir) {
+			if !force && authPortableTargetPopulated(configDir) {
 				return apperrors.NewValidation("检测到已有登录态，请使用 --force 确认覆盖")
 			}
 
-			payload, err := os.ReadFile(input)
+			payload, err := authReadFile(input)
 			if err != nil {
 				return apperrors.NewInternal(fmt.Sprintf("failed to read auth bundle: %v", err))
 			}
@@ -692,7 +843,7 @@ func newAuthImportCommand() *cobra.Command {
 					return apperrors.NewValidation(fmt.Sprintf("invalid base64 auth bundle: %v", err))
 				}
 			}
-			report, err := authpkg.ImportPortableAuthBundle(configDir, bytes.NewReader(payload))
+			report, err := authImportPortableBundle(configDir, bytes.NewReader(payload))
 			if err != nil {
 				return apperrors.NewInternal(fmt.Sprintf("failed to import auth bundle: %v", err))
 			}
@@ -712,7 +863,7 @@ func newAuthImportCommand() *cobra.Command {
 	return cmd
 }
 
-func newAuthExchangeCommand() *cobra.Command {
+func newAuthExchangeCommand(caller edition.ToolCaller) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "exchange",
 		Short:             "Exchange an authorization code for credentials",
@@ -734,10 +885,13 @@ func newAuthExchangeCommand() *cobra.Command {
 
 			configDir := defaultConfigDir()
 			provider := authpkg.NewOAuthProvider(configDir, nil)
+			provider.IdentityEnricher = func(ctx context.Context, data *authpkg.TokenData) error {
+				return enrichAuthLoginProfileFromContact(ctx, configDir, caller, data)
+			}
 			configureOAuthProviderCompatibility(provider, configDir)
 			exchangeCtx, cancel := context.WithTimeout(cmd.Context(), time.Minute)
 			defer cancel()
-			tokenData, err := provider.ExchangeAuthCode(exchangeCtx, code, strings.TrimSpace(uid))
+			tokenData, err := authOAuthExchange(provider, exchangeCtx, code, strings.TrimSpace(uid))
 			if err != nil {
 				return apperrors.NewAuth(fmt.Sprintf("failed to exchange authorization code: %v", err))
 			}
@@ -776,12 +930,12 @@ func newAuthResetCommand() *cobra.Command {
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			configDir := defaultConfigDir()
-			if err := authpkg.DeleteAllTokenData(configDir); err != nil {
+			if err := authDeleteAllTokenData(configDir); err != nil {
 				return apperrors.NewInternal(fmt.Sprintf("failed to reset token data: %v", err))
 			}
-			_ = os.Remove(filepath.Join(configDir, "mcp_url"))
-			_ = os.Remove(filepath.Join(configDir, "token"))
-			_ = authpkg.DeleteAppConfig(configDir)
+			_ = authRemove(filepath.Join(configDir, "mcp_url"))
+			_ = authRemove(filepath.Join(configDir, "token"))
+			_ = authDeleteAppConfig(configDir)
 			ResetRuntimeTokenCache()
 			clearCompatCache()
 			w := cmd.OutOrStdout()
@@ -857,20 +1011,22 @@ func selectLoginRecommendProducts(products []pat.LoginRecommendProduct) ([]strin
 				Options(options...).
 				Height(height).
 				Value(&selected).
-				Validate(func(values []string) error {
-					if len(values) == 0 {
-						return fmt.Errorf("至少选择一个授权业务域")
-					}
-					return nil
-				}),
+				Validate(authLoginProductsNonEmpty),
 		),
 	).WithTheme(authLoginHuhTheme())
-	if err := form.Run(); err != nil {
+	if err := authRunForm(form); err != nil {
 		return nil, fmt.Errorf("授权业务域选择中止: %w", err)
 	}
 	return selected, nil
 }
 
+func authLoginProductsNonEmpty(values []string) error {
+	if len(values) == 0 {
+		return fmt.Errorf("至少选择一个授权业务域")
+	}
+	return nil
+}
+
 func authLoginHuhTheme() *huh.Theme {
 	t := huh.ThemeBase()
 
@@ -956,10 +1112,6 @@ func authLoginMutedStyle() lipgloss.Style {
 	return lipgloss.NewStyle().Foreground(authLoginMuted)
 }
 
-func authLoginShouldShowPostLoginTUI(cmd *cobra.Command, format string, recommend bool) bool {
-	return authLoginShouldUsePostLoginTUIModeForTerminal(cmd, format, recommend, authLoginInteractiveTerminal())
-}
-
 func authLoginShouldShowPostLoginTUIForTerminal(cmd *cobra.Command, format string, recommend bool, interactive bool) bool {
 	return authLoginShouldUsePostLoginTUIModeForTerminal(cmd, format, recommend, interactive)
 }
@@ -1028,10 +1180,7 @@ func clipRunes(value string, limit int) string {
 }
 
 func clearCompatCache() {
-	store := cacheStoreFromEnv()
-	if store != nil {
-		_ = os.RemoveAll(store.Root)
-	}
+	// Cache store removed; no-op in static endpoint mode.
 }
 
 func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
@@ -1061,6 +1210,19 @@ func resolveAuthLoginConfig(cmd *cobra.Command) (authLoginConfig, error) {
 	if err != nil {
 		return authLoginConfig{}, err
 	}
+	flow := "oauth"
+	if strings.TrimSpace(token) != "" {
+		flow = "token"
+	} else if device {
+		flow = "device"
+	}
+	logging.AuthDebug(
+		"auth.login.request",
+		"flow", flow,
+		"profile_selector", strings.TrimSpace(profileSelector),
+		"target_corp_id", targetCorpID,
+		"recommend", recommend,
+	)
 	return authLoginConfig{
 		Token:        strings.TrimSpace(token),
 		Force:        force,
@@ -1080,7 +1242,7 @@ func resolveAuthLoginTargetCorpID(configDir, selector string) (string, error) {
 	if selector == "" {
 		return "", nil
 	}
-	if profile, err := authpkg.ResolveProfile(configDir, selector); err == nil && profile != nil {
+	if profile, err := authResolveProfile(configDir, selector); err == nil && profile != nil {
 		return strings.TrimSpace(profile.CorpID), nil
 	}
 	if strings.HasPrefix(selector, "ding") {
@@ -1096,7 +1258,11 @@ type contactProfileIdentity struct {
 	UserName string
 }
 
-func enrichAuthLoginProfileFromContact(ctx context.Context, configDir string, caller edition.ToolCaller, data *authpkg.TokenData) error {
+type tokenOverrideToolCaller interface {
+	CallToolWithToken(ctx context.Context, token, productID, toolName string, args map[string]any) (*edition.ToolResult, error)
+}
+
+func enrichAuthLoginProfileFromContact(ctx context.Context, _ string, caller edition.ToolCaller, data *authpkg.TokenData) error {
 	if caller == nil || data == nil {
 		return nil
 	}
@@ -1104,24 +1270,62 @@ func enrichAuthLoginProfileFromContact(ctx context.Context, configDir string, ca
 	if corpID == "" {
 		return nil
 	}
+	logging.AuthDebug(
+		"auth.login.identity.lookup.start",
+		"corp_id", corpID,
+		"user_id", strings.TrimSpace(data.UserID),
+		"user_name", strings.TrimSpace(data.UserName),
+		"corp_name", strings.TrimSpace(data.CorpName),
+	)
 	if strings.TrimSpace(data.CorpName) != "" && strings.TrimSpace(data.UserID) != "" && strings.TrimSpace(data.UserName) != "" {
+		logging.AuthDebug(
+			"auth.login.identity.lookup.result",
+			"source", "token_exchange",
+			"corp_id", corpID,
+			"user_id", strings.TrimSpace(data.UserID),
+			"user_name", strings.TrimSpace(data.UserName),
+			"corp_name", strings.TrimSpace(data.CorpName),
+		)
 		return nil
 	}
 
-	restoreProfile := pushRuntimeProfile(corpID)
-	defer restoreProfile()
-	ResetRuntimeTokenCache()
-
-	result, err := caller.CallTool(ctx, "contact", "get_current_user_profile", map[string]any{
-		"profile": corpID,
-	})
+	var (
+		result *edition.ToolResult
+		err    error
+	)
+	if tokenCaller, ok := caller.(tokenOverrideToolCaller); ok && strings.TrimSpace(data.AccessToken) != "" {
+		result, err = tokenCaller.CallToolWithToken(ctx, data.AccessToken, "contact", "get_current_user_profile", nil)
+	} else {
+		if strings.TrimSpace(data.UserID) == "" {
+			return fmt.Errorf("login identity lookup requires an in-memory token override")
+		}
+		return nil
+	}
 	if err != nil {
+		logging.AuthDebug(
+			"auth.login.identity.lookup.error",
+			"corp_id", corpID,
+			"existing_user_id", strings.TrimSpace(data.UserID),
+			"error", err,
+		)
+		if strings.TrimSpace(data.UserID) != "" {
+			return nil
+		}
 		return err
 	}
 	identity, ok := contactProfileIdentityFromToolResult(result)
 	if !ok {
+		logging.AuthDebug("auth.login.identity.lookup.empty", "corp_id", corpID)
 		return nil
 	}
+	logging.AuthDebug(
+		"auth.login.identity.lookup.result",
+		"source", "contact.get_current_user_profile",
+		"corp_id", strings.TrimSpace(identity.CorpID),
+		"user_id", strings.TrimSpace(identity.UserID),
+		"user_name", strings.TrimSpace(identity.UserName),
+		"corp_name", strings.TrimSpace(identity.CorpName),
+	)
 	if identity.CorpID != "" && identity.CorpID != corpID {
 		return fmt.Errorf("contact profile corpId %q does not match login corpId %q", identity.CorpID, corpID)
 	}
@@ -1137,12 +1341,23 @@ func enrichAuthLoginProfileFromContact(ctx context.Context, configDir string, ca
 		updated.UserName = identity.UserName
 	}
 	if updated.CorpName == data.CorpName && updated.UserID == data.UserID && updated.UserName == data.UserName {
+		logging.AuthDebug(
+			"auth.login.identity.resolved",
+			"corp_id", corpID,
+			"user_id", strings.TrimSpace(data.UserID),
+			"user_name", strings.TrimSpace(data.UserName),
+			"changed", false,
+		)
 		return nil
 	}
-	if err := authpkg.SaveTokenData(configDir, &updated); err != nil {
-		return err
-	}
 	*data = updated
+	logging.AuthDebug(
+		"auth.login.identity.resolved",
+		"corp_id", strings.TrimSpace(data.CorpID),
+		"user_id", strings.TrimSpace(data.UserID),
+		"user_name", strings.TrimSpace(data.UserName),
+		"changed", true,
+	)
 	return nil
 }
 
@@ -1169,6 +1384,7 @@ func contactProfileIdentityFromJSON(data []byte) (contactProfileIdentity, bool)
 				OrgName     string `json:"orgName"`
 				UserID      string `json:"userId"`
 				UserIDLower string `json:"userid"`
+				OrgUserID   string `json:"orgUserId"`
 				OrgUserName string `json:"orgUserName"`
 				Name        string `json:"name"`
 			} `json:"orgEmployeeModel"`
@@ -1184,7 +1400,7 @@ func contactProfileIdentityFromJSON(data []byte) (contactProfileIdentity, bool)
 	identity := contactProfileIdentity{
 		CorpID:   strings.TrimSpace(org.CorpID),
 		CorpName: strings.TrimSpace(org.OrgName),
-		UserID:   firstNonEmptyString(org.UserID, org.UserIDLower),
+		UserID:   firstNonEmptyString(org.UserID, org.UserIDLower, org.OrgUserID),
 		UserName: firstNonEmptyString(org.OrgUserName, org.Name),
 	}
 	return identity, identity.CorpID != "" || identity.CorpName != "" || identity.UserID != "" || identity.UserName != ""
@@ -1224,6 +1440,8 @@ type authStatusResponse struct {
 	Success           bool   `json:"success"`
 	Authenticated     bool   `json:"authenticated"`
 	Message           string `json:"message,omitempty"`
+	Reason            string `json:"reason,omitempty"`
+	Hint              string `json:"hint,omitempty"`
 	Refreshed         bool   `json:"refreshed,omitempty"`
 	TokenValid        bool   `json:"token_valid,omitempty"`
 	RefreshTokenValid bool   `json:"refresh_token_valid,omitempty"`
@@ -1235,14 +1453,65 @@ type authStatusResponse struct {
 	UserName          string `json:"user_name,omitempty"`
 }
 
-func writeAuthStatusJSON(w io.Writer, authenticated, refreshed bool, data *authpkg.TokenData) error {
+type authStatusDiagnostic struct {
+	Reason  string
+	Message string
+	Hint    string
+}
+
+func authStatusDiagnosticFromError(err error) *authStatusDiagnostic {
+	if err == nil {
+		return nil
+	}
+	if keychain.IsCiphertextKeyMismatch(err) {
+		return &authStatusDiagnostic{
+			Reason:  "ciphertext_key_mismatch",
+			Message: "本地登录态与可用登录密钥不匹配，已拒绝覆盖现有凭证",
+			Hint:    "macOS 请先在系统 Keychain 模式运行 `env -u DWS_DISABLE_KEYCHAIN dws auth migrate-keychain --to file-dek --dry-run`，预检通过后加 --yes 迁移；只有密文损坏且确认无法恢复时才按 profile 退出或执行 auth reset。",
+		}
+	}
+	if keychain.IsDEKMissing(err) {
+		return &authStatusDiagnostic{
+			Reason:  "dek_missing",
+			Message: "本地登录密钥缺失，无法解密已保存的登录态",
+			Hint:    "请先恢复或统一原登录密钥；确认旧登录态不可恢复后，执行 dws auth reset，再重新登录。",
+		}
+	}
+	if !keychain.IsUnavailable(err) {
+		return nil
+	}
+	return &authStatusDiagnostic{
+		Reason:  "keychain_unavailable",
+		Message: "无法读取 macOS Keychain 中的登录密钥，无法判断登录状态",
+		Hint:    "检查 macOS 默认钥匙串是否存在且已解锁；修复后重试，或在测试环境设置 DWS_DISABLE_KEYCHAIN=1 后重新登录。",
+	}
+}
+
+func authStatusRefreshDiagnostic(err error) *authStatusDiagnostic {
+	if err == nil {
+		return nil
+	}
+	return &authStatusDiagnostic{
+		Reason:  "token_refresh_failed",
+		Message: fmt.Sprintf("Token 刷新失败: %v", err),
+		Hint:    "请重新运行 dws auth login 完成授权。",
+	}
+}
+
+func writeAuthStatusJSON(w io.Writer, authenticated, refreshed bool, data *authpkg.TokenData, diagnostic *authStatusDiagnostic) error {
 	resp := authStatusResponse{
 		Success:       true,
 		Authenticated: authenticated,
 	}
 
 	if !authenticated {
-		resp.Message = "未登录"
+		if diagnostic != nil {
+			resp.Message = diagnostic.Message
+			resp.Reason = diagnostic.Reason
+			resp.Hint = diagnostic.Hint
+		} else {
+			resp.Message = "未登录"
+		}
 	} else if data != nil {
 		resp.Refreshed = refreshed
 		resp.TokenValid = data.IsAccessTokenValid()

internal/app/auth_command_full_coverage_test.go

@@ -0,0 +1,841 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pat"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/charmbracelet/huh"
+	"github.com/spf13/cobra"
+)
+
+type authCoverageCaller struct {
+	result *edition.ToolResult
+	err    error
+}
+
+func (c *authCoverageCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return c.result, c.err
+}
+func (c *authCoverageCaller) CallToolWithToken(ctx context.Context, _ string, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	return c.CallTool(ctx, productID, toolName, args)
+}
+func (*authCoverageCaller) Format() string { return "json" }
+func (*authCoverageCaller) DryRun() bool   { return false }
+func (*authCoverageCaller) Fields() string { return "" }
+func (*authCoverageCaller) JQ() string     { return "" }
+
+func authCoverageRoot(child *cobra.Command, format string, yes bool) (*cobra.Command, *bytes.Buffer, *bytes.Buffer) {
+	root := &cobra.Command{Use: "dws"}
+	root.SetContext(context.Background())
+	child.SetContext(context.Background())
+	root.PersistentFlags().String("format", format, "")
+	root.PersistentFlags().Bool("yes", yes, "")
+	root.PersistentFlags().String("profile", "", "")
+	root.AddCommand(child)
+	out := &bytes.Buffer{}
+	errOut := &bytes.Buffer{}
+	root.SetOut(out)
+	root.SetErr(errOut)
+	return root, out, errOut
+}
+
+func authCoverageRunLogin(t *testing.T, caller edition.ToolCaller, format string, yes bool, flags map[string]string) (string, string, error) {
+	t.Helper()
+	cmd := newAuthLoginCommand(caller)
+	root, out, errOut := authCoverageRoot(cmd, format, yes)
+	for name, value := range flags {
+		flagSet := cmd.Flags()
+		if root.PersistentFlags().Lookup(name) != nil {
+			flagSet = root.PersistentFlags()
+		}
+		if err := flagSet.Set(name, value); err != nil {
+			t.Fatalf("set %s: %v", name, err)
+		}
+	}
+	err := cmd.RunE(cmd, nil)
+	return out.String(), errOut.String(), err
+}
+
+func TestCrossPlatformCoverageAuthCoverageFormsParentAndTargets(t *testing.T) {
+	oldEdition := edition.Get()
+	oldClientID := authpkg.ClientID()
+	oldClientSecret := authpkg.ClientSecret()
+	oldRunForm := authRunForm
+	oldPrompt := authLoginManualCredentialsPrompt
+	oldSaveConfig := authSaveAppConfig
+	oldResolve := authResolveProfile
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		authpkg.SetClientID(oldClientID)
+		authpkg.SetClientSecret(oldClientSecret)
+		authRunForm = oldRunForm
+		authLoginManualCredentialsPrompt = oldPrompt
+		authSaveAppConfig = oldSaveConfig
+		authResolveProfile = oldResolve
+	})
+
+	edition.Override(&edition.Hooks{})
+	parent := buildAuthCommand(nil)
+	if parent.CommandPath() == "" || parent.RunE(parent, nil) != nil {
+		t.Fatal("auth parent should render help")
+	}
+	edition.Override(&edition.Hooks{HideAuthLogin: true})
+	if got := buildAuthCommand(nil).Commands(); len(got) != 7 {
+		t.Fatalf("hidden-login subcommands = %d, want 7", len(got))
+	}
+
+	authRunForm = func(*huh.Form) error { return nil }
+	if choice, err := selectAuthLoginGuideAction(); err != nil || choice != authLoginGuideDirectCLI {
+		t.Fatalf("guide choice = %q, %v", choice, err)
+	}
+	if id, secret, err := promptAuthLoginManualCredentials(); err != nil || id != "" || secret != "" {
+		t.Fatalf("manual prompt = %q/%q, %v", id, secret, err)
+	}
+	if mode, err := selectLoginRecommendScopeMode(); err != nil || mode != pat.LoginRecommendScopeRecommended {
+		t.Fatalf("scope mode = %q, %v", mode, err)
+	}
+	products := []pat.LoginRecommendProduct{{ProductCode: "doc"}, {ProductCode: ""}}
+	if selected, err := selectLoginRecommendProducts(products); err != nil || len(selected) != 1 || selected[0] != "doc" {
+		t.Fatalf("selected products = %#v, %v", selected, err)
+	}
+	if selected, err := selectLoginRecommendProducts(nil); err != nil || selected != nil {
+		t.Fatalf("empty selected products = %#v, %v", selected, err)
+	}
+	if selected, err := selectLoginRecommendProducts([]pat.LoginRecommendProduct{{}}); err != nil || selected != nil {
+		t.Fatalf("blank selected products = %#v, %v", selected, err)
+	}
+	many := make([]pat.LoginRecommendProduct, 16)
+	for i := range many {
+		many[i].ProductCode = fmt.Sprintf("p%d", i)
+	}
+	if selected, err := selectLoginRecommendProducts(many); err != nil || len(selected) != 16 {
+		t.Fatalf("many selected products = %d, %v", len(selected), err)
+	}
+	if authLoginProductsNonEmpty(nil) == nil || authLoginProductsNonEmpty([]string{"doc"}) != nil {
+		t.Fatal("product validator mismatch")
+	}
+
+	authRunForm = func(*huh.Form) error { return errors.New("cancel") }
+	if _, err := selectAuthLoginGuideAction(); err == nil {
+		t.Fatal("guide cancellation should fail")
+	}
+	if _, _, err := promptAuthLoginManualCredentials(); err == nil {
+		t.Fatal("credential cancellation should fail")
+	}
+	if _, err := selectLoginRecommendScopeMode(); err == nil {
+		t.Fatal("scope cancellation should fail")
+	}
+	if _, err := selectLoginRecommendProducts(products); err == nil {
+		t.Fatal("product cancellation should fail")
+	}
+	if authLoginNonEmpty("field")(" ") == nil || authLoginNonEmpty("field")("value") != nil {
+		t.Fatal("non-empty validator mismatch")
+	}
+
+	cmd := &cobra.Command{}
+	cmd.SetErr(io.Discard)
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), authLoginGuideDirectCLI); err != nil {
+		t.Fatal(err)
+	}
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), authLoginGuideConfigureAgentApp); err != nil {
+		t.Fatal(err)
+	}
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), "unknown"); err == nil {
+		t.Fatal("unknown guide action should fail")
+	}
+	authLoginManualCredentialsPrompt = func() (string, string, error) { return "", "", errors.New("cancel") }
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), authLoginGuideManualCredentials); err == nil {
+		t.Fatal("manual prompt error should propagate")
+	}
+	authLoginManualCredentialsPrompt = func() (string, string, error) { return "id", "secret", nil }
+	authSaveAppConfig = func(string, *authpkg.AppConfig) error { return errors.New("save") }
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), authLoginGuideManualCredentials); err == nil {
+		t.Fatal("app-config save error should propagate")
+	}
+	authSaveAppConfig = func(string, *authpkg.AppConfig) error { return nil }
+	if err := applyAuthLoginGuideAction(cmd, t.TempDir(), authLoginGuideManualCredentials); err != nil {
+		t.Fatal(err)
+	}
+
+	authResolveProfile = func(string, string) (*authpkg.Profile, error) {
+		return &authpkg.Profile{CorpID: " ding-profile "}, nil
+	}
+	if got, err := resolveAuthLoginTargetCorpID("cfg", "name"); err != nil || got != "ding-profile" {
+		t.Fatalf("resolved target = %q, %v", got, err)
+	}
+	authResolveProfile = func(string, string) (*authpkg.Profile, error) { return nil, errors.New("missing") }
+	for selector, want := range map[string]struct {
+		value string
+		err   bool
+	}{"": {"", false}, "ding-direct": {"ding-direct", false}, "other": {"", true}} {
+		got, err := resolveAuthLoginTargetCorpID("cfg", selector)
+		if got != want.value || (err != nil) != want.err {
+			t.Fatalf("target %q = %q, %v", selector, got, err)
+		}
+	}
+	badToken := &cobra.Command{}
+	badToken.Flags().Bool("token", false, "")
+	if _, err := resolveAuthLoginConfig(badToken); err == nil {
+		t.Fatal("invalid token flag should fail")
+	}
+	badDevice := &cobra.Command{}
+	badDevice.Flags().String("token", "", "")
+	badDevice.Flags().String("device", "", "")
+	if _, err := resolveAuthLoginConfig(badDevice); err == nil {
+		t.Fatal("invalid device flag should fail")
+	}
+	badForce := &cobra.Command{}
+	badForce.Flags().String("token", "", "")
+	badForce.Flags().Bool("device", false, "")
+	badForce.Flags().String("force", "", "")
+	if _, err := resolveAuthLoginConfig(badForce); err == nil {
+		t.Fatal("invalid force flag should fail")
+	}
+	badRecommend := &cobra.Command{}
+	badRecommend.Flags().String("token", "", "")
+	badRecommend.Flags().Bool("device", false, "")
+	badRecommend.Flags().Bool("force", false, "")
+	badRecommend.Flags().String("recommend", "", "")
+	if _, err := resolveAuthLoginConfig(badRecommend); err == nil {
+		t.Fatal("invalid recommend flag should fail")
+	}
+}
+
+func TestCrossPlatformCoverageAuthCoverageLoginFlows(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldSave := authSaveTokenData
+	oldDevice := authDeviceLogin
+	oldOAuth := authOAuthLogin
+	oldRunRecommend := authRunLoginRecommend
+	oldRunWait := authRunDirectPATWait
+	oldPlan := authPlanLoginRecommend
+	oldScope := loginRecommendScopeModeSelector
+	oldProducts := loginRecommendProductSelector
+	oldInteractive := authLoginInteractiveTerminal
+	oldResolve := authResolveProfile
+	t.Cleanup(func() {
+		authSaveTokenData = oldSave
+		authDeviceLogin = oldDevice
+		authOAuthLogin = oldOAuth
+		authRunLoginRecommend = oldRunRecommend
+		authRunDirectPATWait = oldRunWait
+		authPlanLoginRecommend = oldPlan
+		loginRecommendScopeModeSelector = oldScope
+		loginRecommendProductSelector = oldProducts
+		authLoginInteractiveTerminal = oldInteractive
+		authResolveProfile = oldResolve
+	})
+	authInteractiveFalse := func() bool { return false }
+	authLoginInteractiveTerminal = authInteractiveFalse
+	authResolveProfile = func(string, string) (*authpkg.Profile, error) { return nil, errors.New("missing") }
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"profile": "bad"}); err == nil {
+		t.Fatal("invalid login profile should fail")
+	}
+
+	authSaveTokenData = func(string, *authpkg.TokenData) error { return errors.New("save") }
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "token"}); err == nil {
+		t.Fatal("token save should fail")
+	}
+	authSaveTokenData = func(string, *authpkg.TokenData) error { return nil }
+	if out, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": " token "}); err != nil || !strings.Contains(out, "登录成功") {
+		t.Fatalf("token login = %q, %v", out, err)
+	}
+	if out, _, err := authCoverageRunLogin(t, nil, "json", true, map[string]string{"token": "token"}); err != nil || !strings.Contains(out, `"token_valid": true`) {
+		t.Fatalf("json token login = %q, %v", out, err)
+	}
+
+	authDeviceLogin = func(*authpkg.DeviceFlowProvider, context.Context) (*authpkg.TokenData, error) {
+		return nil, errors.New("device")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true"}); err == nil {
+		t.Fatal("device error should propagate")
+	}
+	authDeviceLogin = func(*authpkg.DeviceFlowProvider, context.Context) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"device": "true", "no-browser": "true"}); err != nil {
+		t.Fatal(err)
+	}
+
+	authOAuthLogin = func(*authpkg.OAuthProvider, context.Context, bool) (*authpkg.TokenData, error) {
+		return nil, errors.New("oauth")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, nil); err == nil {
+		t.Fatal("oauth error should propagate")
+	}
+	authOAuthLogin = func(*authpkg.OAuthProvider, context.Context, bool) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{
+			AccessToken: "a", ExpiresAt: time.Now().Add(time.Hour), RefreshToken: "r", RefreshExpAt: time.Now().Add(48 * time.Hour),
+			CorpName: "Corp", CorpID: "ding1", UserName: "User", UserID: "u",
+		}, nil
+	}
+	caller := &authCoverageCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Text: `{}`}}}}
+	if out, _, err := authCoverageRunLogin(t, caller, "table", true, map[string]string{"no-browser": "true"}); err != nil || !strings.Contains(out, "Corp") {
+		t.Fatalf("oauth success = %q, %v", out, err)
+	}
+
+	authRunLoginRecommend = func(context.Context, edition.ToolCaller, io.Writer, pat.LoginRecommendOptions) error {
+		return errors.New("recommend")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", true, map[string]string{"token": "x", "recommend": "true"}); err == nil {
+		t.Fatal("recommend error should propagate")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "json", true, map[string]string{"token": "x", "recommend": "true"}); err == nil {
+		t.Fatal("JSON recommend error should propagate")
+	}
+	authRunLoginRecommend = func(context.Context, edition.ToolCaller, io.Writer, pat.LoginRecommendOptions) error {
+		return &apperrors.PATError{RawJSON: `{"code":"PAT_SCOPE_AUTH_REQUIRED"}`}
+	}
+	waited := false
+	authRunDirectPATWait = func(context.Context, *GlobalFlags, *apperrors.PATError, io.Writer) error {
+		waited = true
+		return nil
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "json", true, map[string]string{"token": "x", "recommend": "true"}); err != nil || !waited {
+		t.Fatalf("PAT wait = %v, waited=%v", err, waited)
+	}
+
+	authLoginInteractiveTerminal = func() bool { return true }
+	authPlanLoginRecommend = func(context.Context, edition.ToolCaller) (*pat.LoginRecommendPlan, error) {
+		return nil, errors.New("plan")
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", false, map[string]string{"token": "x"}); err == nil {
+		t.Fatal("plan error should propagate")
+	}
+	authPlanLoginRecommend = func(context.Context, edition.ToolCaller) (*pat.LoginRecommendPlan, error) {
+		return &pat.LoginRecommendPlan{AllGranted: true}, nil
+	}
+	if _, stderr, err := authCoverageRunLogin(t, nil, "table", false, map[string]string{"token": "x"}); err != nil || !strings.Contains(stderr, "全部授权") {
+		t.Fatalf("all-granted plan = %q, %v", stderr, err)
+	}
+	authPlanLoginRecommend = func(context.Context, edition.ToolCaller) (*pat.LoginRecommendPlan, error) {
+		return &pat.LoginRecommendPlan{Scopes: []string{"scope"}, Products: []pat.LoginRecommendProduct{{ProductCode: "doc"}}}, nil
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) { return "", errors.New("scope") }
+	if _, _, err := authCoverageRunLogin(t, nil, "table", false, map[string]string{"token": "x"}); err == nil {
+		t.Fatal("scope selector error should propagate")
+	}
+	loginRecommendScopeModeSelector = func() (pat.LoginRecommendScopeMode, error) { return pat.LoginRecommendScopeAll, nil }
+	loginRecommendProductSelector = func([]pat.LoginRecommendProduct) ([]string, error) { return []string{"doc"}, nil }
+	selected := false
+	authRunLoginRecommend = func(_ context.Context, _ edition.ToolCaller, _ io.Writer, opts pat.LoginRecommendOptions) error {
+		if opts.ProductSelector != nil {
+			_, err := opts.ProductSelector(opts.InitialPlan.Products)
+			selected = err == nil
+		}
+		return nil
+	}
+	if _, _, err := authCoverageRunLogin(t, nil, "table", false, map[string]string{"token": "x"}); err != nil || !selected {
+		t.Fatalf("interactive recommendation = %v, selected=%v", err, selected)
+	}
+}
+
+func TestCrossPlatformCoverageAuthCoverageContactEnrichment(t *testing.T) {
+	oldSave := authSaveTokenData
+	t.Cleanup(func() { authSaveTokenData = oldSave })
+	ctx := context.Background()
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", nil, nil); err != nil {
+		t.Fatal(err)
+	}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", &authCoverageCaller{}, &authpkg.TokenData{}); err != nil {
+		t.Fatal(err)
+	}
+	complete := &authpkg.TokenData{CorpID: "ding", CorpName: "Corp", UserID: "u", UserName: "User"}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", &authCoverageCaller{}, complete); err != nil {
+		t.Fatal(err)
+	}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", &authCoverageCaller{err: errors.New("call")}, &authpkg.TokenData{CorpID: "ding"}); err == nil {
+		t.Fatal("caller error should propagate")
+	}
+	if err := enrichAuthLoginProfileFromContact(
+		ctx,
+		"cfg",
+		&authCoverageCaller{err: errors.New("call")},
+		&authpkg.TokenData{CorpID: "ding", UserID: "known", AccessToken: "token"},
+	); err != nil {
+		t.Fatalf("optional contact metadata failure with known userId = %v", err)
+	}
+	for _, text := range []string{"", "not-json", `{"result":[]}`, `{"result":[{"orgEmployeeModel":{}}]}`} {
+		caller := &authCoverageCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Text: text}}}}
+		if err := enrichAuthLoginProfileFromContact(ctx, "cfg", caller, &authpkg.TokenData{CorpID: "ding", AccessToken: "token"}); err != nil {
+			t.Fatalf("invalid contact %q: %v", text, err)
+		}
+	}
+	mismatch := &authCoverageCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Text: `{"result":[{"orgEmployeeModel":{"corpId":"other"}}]}`}}}}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", mismatch, &authpkg.TokenData{CorpID: "ding", AccessToken: "token"}); err == nil {
+		t.Fatal("corp mismatch should fail")
+	}
+	same := &authCoverageCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Text: `{"result":[{"orgEmployeeModel":{"corpId":"ding","orgName":"Corp","userid":"u","name":"User"}}]}`}}}}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", same, complete); err != nil {
+		t.Fatal(err)
+	}
+	unchangedPartial := &authCoverageCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Text: `{"result":[{"orgEmployeeModel":{"corpId":"ding","orgName":"Corp","userid":"u"}}]}`}}}}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", unchangedPartial, &authpkg.TokenData{CorpID: "ding", CorpName: "Corp", UserID: "u"}); err != nil {
+		t.Fatal(err)
+	}
+	authSaveTokenData = func(string, *authpkg.TokenData) error { return errors.New("save") }
+	data := &authpkg.TokenData{CorpID: "ding", AccessToken: "token"}
+	if err := enrichAuthLoginProfileFromContact(ctx, "cfg", same, data); err != nil || data.CorpName != "Corp" || data.UserID != "u" {
+		t.Fatalf("enriched = %#v, %v", data, err)
+	}
+	if _, ok := contactProfileIdentityFromToolResult(nil); ok {
+		t.Fatal("nil result should not parse")
+	}
+	if got := firstNonEmptyString(" ", " value ", "later"); got != "value" {
+		t.Fatalf("first non-empty = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageAuthCoverageDefaultSeamClosures(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	configDir := t.TempDir()
+	device := authpkg.NewDeviceFlowProvider(configDir, nil)
+	_, _ = authDeviceLogin(device, ctx)
+	oauth := authpkg.NewOAuthProvider(configDir, nil)
+	oauth.NoBrowser = true
+	_, _ = authOAuthStatus(oauth)
+	_, _ = authOAuthAccessToken(oauth, ctx)
+	_, _ = authOAuthLogin(oauth, ctx, true)
+	_, _ = authOAuthExchange(oauth, ctx, "code", "uid")
+	_ = fmt.Sprintf("%v", os.ErrNotExist)
+}
+
+func TestCrossPlatformCoverageAuthCoverageStatusAndLogout(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldEdition := edition.Get()
+	oldStatus := authOAuthStatus
+	oldAccess := authOAuthAccessToken
+	oldDelete := authDeleteTokenData
+	oldMark := authMarkProfileStatus
+	oldResolve := authResolveProfile
+	oldResolveDeletion := authResolveProfileDeletion
+	oldRevoke := authRevokeToken
+	oldRevokeForData := authRevokeTokenForData
+	oldLoadTokenForProfile := authLoadTokenForProfile
+	oldDeleteProfile := authDeleteProfileToken
+	oldMigrate := authEnsureProfilesMigration
+	oldLoadProfiles := authLoadProfiles
+	oldDeleteAll := authDeleteAllTokenData
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		authOAuthStatus = oldStatus
+		authOAuthAccessToken = oldAccess
+		authDeleteTokenData = oldDelete
+		authMarkProfileStatus = oldMark
+		authResolveProfile = oldResolve
+		authResolveProfileDeletion = oldResolveDeletion
+		authRevokeToken = oldRevoke
+		authRevokeTokenForData = oldRevokeForData
+		authLoadTokenForProfile = oldLoadTokenForProfile
+		authDeleteProfileToken = oldDeleteProfile
+		authEnsureProfilesMigration = oldMigrate
+		authLoadProfiles = oldLoadProfiles
+		authDeleteAllTokenData = oldDeleteAll
+	})
+
+	badStatus := newAuthStatusCommand()
+	bad := &cobra.Command{}
+	bad.Flags().Bool("profile", false, "")
+	if err := badStatus.RunE(bad, nil); err == nil {
+		t.Fatal("invalid profile flag should fail")
+	}
+
+	runStatus := func(format string) (string, error) {
+		cmd := newAuthStatusCommand()
+		_, out, _ := authCoverageRoot(cmd, format, false)
+		err := cmd.RunE(cmd, nil)
+		return out.String(), err
+	}
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return nil, nil }
+	edition.Override(&edition.Hooks{})
+	if out, err := runStatus("table"); err != nil || !strings.Contains(out, "auth login") {
+		t.Fatalf("plain unauthenticated status = %q, %v", out, err)
+	}
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) {
+		return nil, keychain.NewUnavailableError("read", errors.New("status"))
+	}
+	edition.Override(&edition.Hooks{})
+	if out, err := runStatus("table"); err != nil || !strings.Contains(out, "未登录") {
+		t.Fatalf("status error = %q, %v", out, err)
+	}
+	if out, err := runStatus("json"); err != nil || !strings.Contains(out, `"authenticated": false`) {
+		t.Fatalf("json status error = %q, %v", out, err)
+	}
+
+	now := time.Now()
+	valid := &authpkg.TokenData{AccessToken: "a", ExpiresAt: now.Add(time.Hour), CorpID: "ding", CorpName: "Corp"}
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return valid, nil }
+	if out, err := runStatus("table"); err != nil || !strings.Contains(out, "已登录") || !strings.Contains(out, "缺失或已过期") {
+		t.Fatalf("valid access status = %q, %v", out, err)
+	}
+	valid.RefreshToken = "r"
+	valid.RefreshExpAt = now.Add(time.Hour)
+	if out, err := runStatus("table"); err != nil || !strings.Contains(out, "Refresh Token:") {
+		t.Fatalf("valid refresh status = %q, %v", out, err)
+	}
+
+	expired := &authpkg.TokenData{AccessToken: "a", ExpiresAt: now.Add(-time.Hour), RefreshToken: "r", RefreshExpAt: now.Add(time.Hour), CorpID: "ding"}
+	updated := &authpkg.TokenData{AccessToken: "new", ExpiresAt: now.Add(time.Hour), RefreshToken: "r", RefreshExpAt: now.Add(time.Hour), CorpID: "ding"}
+	calls := 0
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) {
+		calls++
+		if calls == 1 {
+			return expired, nil
+		}
+		return updated, nil
+	}
+	authOAuthAccessToken = func(*authpkg.OAuthProvider, context.Context) (string, error) { return "new", nil }
+	if out, err := runStatus("table"); err != nil || !strings.Contains(out, "自动刷新") {
+		t.Fatalf("refreshed status = %q, %v", out, err)
+	}
+	calls = 0
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) {
+		calls++
+		if calls == 1 {
+			return expired, nil
+		}
+		return nil, errors.New("second status")
+	}
+	if _, err := runStatus("table"); err != nil {
+		t.Fatal(err)
+	}
+
+	authOAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return expired, nil }
+	authOAuthAccessToken = func(*authpkg.OAuthProvider, context.Context) (string, error) { return "", errors.New("refresh") }
+	deleted := false
+	marked := false
+	authDeleteTokenData = func(string) error { deleted = true; return errors.New("ignored") }
+	authMarkProfileStatus = func(string, string, string) error { marked = true; return errors.New("ignored") }
+	edition.Override(&edition.Hooks{AutoPurgeToken: true})
+	if _, err := runStatus("table"); err != nil || !deleted {
+		t.Fatalf("auto-purge = %v, deleted=%v", err, deleted)
+	}
+	edition.Override(&edition.Hooks{})
+	if _, err := runStatus("table"); err != nil || !marked {
+		t.Fatalf("mark-expired = %v, marked=%v", err, marked)
+	}
+
+	authResolveProfileDeletion = func(string, string) (*authpkg.Profile, bool, error) { return nil, false, errors.New("missing") }
+	if err := logoutOneProfile(nil, context.Background(), "cfg", "x"); err == nil {
+		t.Fatal("missing profile should fail")
+	}
+	authResolveProfileDeletion = func(string, string) (*authpkg.Profile, bool, error) {
+		return &authpkg.Profile{CorpID: "ding", UserID: "user"}, true, nil
+	}
+	authLoadTokenForProfile = func(string, string) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{CorpID: "ding", UserID: "user"}, nil
+	}
+	authRevokeTokenForData = func(context.Context, *authpkg.TokenData) error { return errors.New("ignored") }
+	var deletedSelector string
+	authDeleteProfileToken = func(_ string, selector string) error {
+		deletedSelector = selector
+		return errors.New("delete")
+	}
+	if err := logoutOneProfile(nil, context.Background(), "cfg", "x"); err == nil {
+		t.Fatal("profile delete should fail")
+	}
+	if deletedSelector != "ding:user" {
+		t.Fatalf("exact deletion selector = %q, want stable identity selector", deletedSelector)
+	}
+	authDeleteProfileToken = func(_ string, selector string) error {
+		deletedSelector = selector
+		return nil
+	}
+	if err := logoutOneProfile(nil, context.Background(), "cfg", "x"); err != nil {
+		t.Fatal(err)
+	}
+	if deletedSelector != "ding:user" {
+		t.Fatalf("exact deletion selector = %q, want stable identity selector", deletedSelector)
+	}
+
+	authResolveProfileDeletion = func(string, string) (*authpkg.Profile, bool, error) {
+		return &authpkg.Profile{CorpID: "ding", UserID: "user"}, false, nil
+	}
+	authLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{Profiles: []authpkg.Profile{{CorpID: "ding", UserID: "user"}}}, nil
+	}
+	if err := logoutOneProfile(nil, context.Background(), "cfg", "organization-name"); err != nil {
+		t.Fatal(err)
+	}
+	if deletedSelector != "ding" {
+		t.Fatalf("organization deletion selector = %q, want stable corpId", deletedSelector)
+	}
+
+	authEnsureProfilesMigration = func(string) error { return errors.New("migrate") }
+	if err := logoutAllProfiles(nil, context.Background(), "cfg"); err == nil {
+		t.Fatal("migration should fail")
+	}
+	authEnsureProfilesMigration = func(string) error { return nil }
+	authLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, errors.New("load") }
+	if err := logoutAllProfiles(nil, context.Background(), "cfg"); err == nil {
+		t.Fatal("load profiles should fail")
+	}
+	revokes := 0
+	authRevokeToken = func(context.Context) error { revokes++; return nil }
+	authRevokeTokenForData = func(context.Context, *authpkg.TokenData) error { revokes++; return nil }
+	authLoadTokenForProfile = func(string, string) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{AccessToken: "token"}, nil
+	}
+	authLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return nil, nil }
+	authDeleteAllTokenData = func(string) error { return nil }
+	if err := logoutAllProfiles(nil, context.Background(), "cfg"); err != nil || revokes != 1 {
+		t.Fatalf("empty profiles = %v, revokes=%d", err, revokes)
+	}
+	authLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) {
+		return &authpkg.ProfilesConfig{Profiles: []authpkg.Profile{{CorpID: "a"}, {CorpID: "b"}}}, nil
+	}
+	if err := logoutAllProfiles(nil, context.Background(), "cfg"); err != nil || revokes != 3 {
+		t.Fatalf("profile revokes = %v, revokes=%d", err, revokes)
+	}
+	authDeleteAllTokenData = func(string) error { return errors.New("delete all") }
+	if err := logoutAllProfiles(nil, context.Background(), "cfg"); err == nil {
+		t.Fatal("delete-all should fail")
+	}
+	logoutFailure := newAuthLogoutCommand()
+	_, _, _ = authCoverageRoot(logoutFailure, "table", false)
+	if err := logoutFailure.RunE(logoutFailure, nil); err == nil {
+		t.Fatal("logout-all command failure should propagate")
+	}
+	logoutFailure = newAuthLogoutCommand()
+	_, _, _ = authCoverageRoot(logoutFailure, "table", false)
+	_ = logoutFailure.Flags().Set("profile", "ding")
+	authDeleteProfileToken = func(string, string) error { return errors.New("delete") }
+	if err := logoutFailure.RunE(logoutFailure, nil); err == nil {
+		t.Fatal("logout-one command failure should propagate")
+	}
+
+	logout := newAuthLogoutCommand()
+	badLogout := &cobra.Command{}
+	badLogout.Flags().Bool("profile", false, "")
+	badLogout.SetContext(context.Background())
+	if err := logout.RunE(badLogout, nil); err == nil {
+		t.Fatal("invalid logout profile flag should fail")
+	}
+	authDeleteAllTokenData = func(string) error { return nil }
+	authLoadProfiles = func(string) (*authpkg.ProfilesConfig, error) { return &authpkg.ProfilesConfig{}, nil }
+	_, out, _ := authCoverageRoot(logout, "table", false)
+	if err := logout.RunE(logout, nil); err != nil || !strings.Contains(out.String(), "重新登录") {
+		t.Fatalf("logout = %q, %v", out.String(), err)
+	}
+	edition.Override(&edition.Hooks{IsEmbedded: true})
+	authDeleteProfileToken = func(string, string) error { return nil }
+	logout = newAuthLogoutCommand()
+	_, out, _ = authCoverageRoot(logout, "table", false)
+	if err := logout.Flags().Set("profile", "ding"); err != nil {
+		t.Fatal(err)
+	}
+	if err := logout.RunE(logout, nil); err != nil || strings.Contains(out.String(), "重新登录") {
+		t.Fatalf("embedded logout = %q, %v", out.String(), err)
+	}
+}
+
+func TestCrossPlatformCoverageAuthCoveragePortableExchangeAndReset(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	oldEdition := edition.Get()
+	oldSupported := authPortableExportSupported
+	oldReady := authPortableSourceReady
+	oldTarget := authPortableTargetPopulated
+	oldExport := authExportPortableBundle
+	oldImport := authImportPortableBundle
+	oldAtomic := authAtomicWrite
+	oldRead := authReadFile
+	oldExchange := authOAuthExchange
+	oldDeleteAll := authDeleteAllTokenData
+	oldRemove := authRemove
+	oldDeleteConfig := authDeleteAppConfig
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		authPortableExportSupported = oldSupported
+		authPortableSourceReady = oldReady
+		authPortableTargetPopulated = oldTarget
+		authExportPortableBundle = oldExport
+		authImportPortableBundle = oldImport
+		authAtomicWrite = oldAtomic
+		authReadFile = oldRead
+		authOAuthExchange = oldExchange
+		authDeleteAllTokenData = oldDeleteAll
+		authRemove = oldRemove
+		authDeleteAppConfig = oldDeleteConfig
+	})
+
+	export := newAuthExportCommandWithSupport(func() error { return nil })
+	badString := &cobra.Command{}
+	badString.Flags().Bool("output", false, "")
+	if err := export.RunE(badString, nil); err == nil {
+		t.Fatal("invalid output flag should fail")
+	}
+	badBool := &cobra.Command{}
+	badBool.Flags().String("output", "x", "")
+	badBool.Flags().String("base64", "", "")
+	if err := export.RunE(badBool, nil); err == nil {
+		t.Fatal("invalid base64 flag should fail")
+	}
+	_, _, _ = authCoverageRoot(export, "table", false)
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("missing export output should fail")
+	}
+	authPortableExportSupported = func() bool { return false }
+	_ = export.Flags().Set("output", "out")
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("unsupported export should fail")
+	}
+	authPortableExportSupported = func() bool { return true }
+	authPortableSourceReady = func() bool { return false }
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("unready export should fail")
+	}
+	authPortableSourceReady = func() bool { return true }
+	authExportPortableBundle = func(string, io.Writer) error { return errors.New("export") }
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("export failure should propagate")
+	}
+	authExportPortableBundle = func(_ string, w io.Writer) error { _, _ = io.WriteString(w, "bundle"); return nil }
+	authAtomicWrite = func(string, []byte, os.FileMode) error { return errors.New("write") }
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("raw write should fail")
+	}
+	authAtomicWrite = func(string, []byte, os.FileMode) error { return nil }
+	if err := export.RunE(export, nil); err != nil {
+		t.Fatal(err)
+	}
+	export = newAuthExportCommandWithSupport(func() error { return nil })
+	_, out, _ := authCoverageRoot(export, "table", false)
+	_ = export.Flags().Set("base64", "true")
+	export.SetOut(&appFailWriter{err: errors.New("stdout")})
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("stdout failure should propagate")
+	}
+	export.SetOut(out)
+	_ = export.Flags().Set("output", "encoded")
+	authAtomicWrite = func(string, []byte, os.FileMode) error { return errors.New("write") }
+	if err := export.RunE(export, nil); err == nil {
+		t.Fatal("base64 write should fail")
+	}
+	authAtomicWrite = func(string, []byte, os.FileMode) error { return nil }
+	if err := export.RunE(export, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	importCmd := newAuthImportCommandWithSupport(func() error { return nil })
+	badInput := &cobra.Command{}
+	badInput.Flags().Bool("input", false, "")
+	if err := importCmd.RunE(badInput, nil); err == nil {
+		t.Fatal("invalid input flag should fail")
+	}
+	badImportBase64 := &cobra.Command{}
+	badImportBase64.Flags().String("input", "x", "")
+	badImportBase64.Flags().String("base64", "", "")
+	if err := importCmd.RunE(badImportBase64, nil); err == nil {
+		t.Fatal("invalid import base64 flag should fail")
+	}
+	badForce := &cobra.Command{}
+	badForce.Flags().String("input", "x", "")
+	badForce.Flags().Bool("base64", false, "")
+	badForce.Flags().String("force", "", "")
+	if err := importCmd.RunE(badForce, nil); err == nil {
+		t.Fatal("invalid force flag should fail")
+	}
+	_, out, _ = authCoverageRoot(importCmd, "table", false)
+	if err := importCmd.RunE(importCmd, nil); err == nil {
+		t.Fatal("missing input should fail")
+	}
+	_ = importCmd.Flags().Set("input", "bundle")
+	authPortableTargetPopulated = func(string) bool { return true }
+	if err := importCmd.RunE(importCmd, nil); err == nil {
+		t.Fatal("populated target should require force")
+	}
+	authPortableTargetPopulated = func(string) bool { return false }
+	authReadFile = func(string) ([]byte, error) { return nil, errors.New("read") }
+	if err := importCmd.RunE(importCmd, nil); err == nil {
+		t.Fatal("read failure should propagate")
+	}
+	authReadFile = func(string) ([]byte, error) { return []byte("%%%"), nil }
+	_ = importCmd.Flags().Set("base64", "true")
+	if err := importCmd.RunE(importCmd, nil); err == nil {
+		t.Fatal("invalid base64 should fail")
+	}
+	authReadFile = func(string) ([]byte, error) { return []byte("YnVuZGxl"), nil }
+	authImportPortableBundle = func(string, io.Reader) (authpkg.PortableImportReport, error) {
+		return authpkg.PortableImportReport{}, errors.New("import")
+	}
+	if err := importCmd.RunE(importCmd, nil); err == nil {
+		t.Fatal("import failure should propagate")
+	}
+	authImportPortableBundle = func(string, io.Reader) (authpkg.PortableImportReport, error) {
+		return authpkg.PortableImportReport{BundleOS: "other", OSMismatch: true}, nil
+	}
+	if err := importCmd.RunE(importCmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	authImportPortableBundle = func(string, io.Reader) (authpkg.PortableImportReport, error) {
+		return authpkg.PortableImportReport{}, nil
+	}
+	if err := importCmd.RunE(importCmd, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	exchange := newAuthExchangeCommand(nil)
+	badCode := &cobra.Command{}
+	badCode.Flags().Bool("code", false, "")
+	if err := exchange.RunE(badCode, nil); err == nil {
+		t.Fatal("invalid code flag should fail")
+	}
+	badUID := &cobra.Command{}
+	badUID.Flags().String("code", "code", "")
+	badUID.Flags().Bool("uid", false, "")
+	if err := exchange.RunE(badUID, nil); err == nil {
+		t.Fatal("invalid uid flag should fail")
+	}
+	_, out, _ = authCoverageRoot(exchange, "table", false)
+	if err := exchange.RunE(exchange, nil); err == nil {
+		t.Fatal("missing code should fail")
+	}
+	_ = exchange.Flags().Set("code", "code")
+	authOAuthExchange = func(*authpkg.OAuthProvider, context.Context, string, string) (*authpkg.TokenData, error) {
+		return nil, errors.New("exchange")
+	}
+	if err := exchange.RunE(exchange, nil); err == nil {
+		t.Fatal("exchange error should propagate")
+	}
+	authOAuthExchange = func(*authpkg.OAuthProvider, context.Context, string, string) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{CorpID: "ding", ExpiresAt: time.Now().Add(time.Hour)}, nil
+	}
+	_ = exchange.Flags().Set("uid", " user ")
+	if err := exchange.RunE(exchange, nil); err != nil || !strings.Contains(out.String(), "ding") {
+		t.Fatalf("exchange = %q, %v", out.String(), err)
+	}
+
+	reset := newAuthResetCommand()
+	_, out, _ = authCoverageRoot(reset, "table", false)
+	authDeleteAllTokenData = func(string) error { return errors.New("reset") }
+	if err := reset.RunE(reset, nil); err == nil {
+		t.Fatal("reset delete should fail")
+	}
+	removed := 0
+	authDeleteAllTokenData = func(string) error { return nil }
+	authRemove = func(string) error { removed++; return errors.New("ignored") }
+	authDeleteAppConfig = func(string) error { removed++; return errors.New("ignored") }
+	edition.Override(&edition.Hooks{})
+	if err := reset.RunE(reset, nil); err != nil || removed != 3 || !strings.Contains(out.String(), "重新登录") {
+		t.Fatalf("reset = %q, %v, removed=%d", out.String(), err, removed)
+	}
+	edition.Override(&edition.Hooks{IsEmbedded: true})
+	reset = newAuthResetCommand()
+	_, out, _ = authCoverageRoot(reset, "table", false)
+	if err := reset.RunE(reset, nil); err != nil || strings.Contains(out.String(), "重新登录") {
+		t.Fatalf("embedded reset = %q, %v", out.String(), err)
+	}
+}

internal/app/auth_command_test.go

@@ -16,10 +16,15 @@ package app
 import (
 	"bytes"
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
+	"io"
+	"log/slog"
 	"net/http"
 	"os"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"testing"
 	"time"
@@ -33,29 +38,33 @@ import (
 )
 
 func TestAuthExportImportBase64RoundTrip(t *testing.T) {
-	t.Setenv(keychain.DisableKeychainEnv, "1")
-	sourceKeychain := filepath.Join(t.TempDir(), "source-keychain")
-	sourceConfig := filepath.Join(t.TempDir(), ".dws")
-	t.Setenv(keychain.StorageDirEnv, sourceKeychain)
-	t.Setenv("DWS_CONFIG_DIR", sourceConfig)
+	originalSupported := authPortableExportSupported
+	originalReady := authPortableSourceReady
+	originalExport := authExportPortableBundle
+	originalTarget := authPortableTargetPopulated
+	originalImport := authImportPortableBundle
+	t.Cleanup(func() {
+		authPortableExportSupported = originalSupported
+		authPortableSourceReady = originalReady
+		authExportPortableBundle = originalExport
+		authPortableTargetPopulated = originalTarget
+		authImportPortableBundle = originalImport
+	})
 
-	original := &authpkg.TokenData{
-		AccessToken:  "access-cli",
-		RefreshToken: "refresh-cli",
-		ExpiresAt:    time.Now().Add(-time.Hour),
-		RefreshExpAt: time.Now().Add(24 * time.Hour),
-		ClientID:     "client-cli",
-		Source:       "mcp",
-	}
-	if err := authpkg.SaveTokenData(sourceConfig, original); err != nil {
-		t.Fatalf("SaveTokenData() error = %v", err)
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	bundle := []byte("portable-auth-bundle")
+	authPortableExportSupported = func() bool { return true }
+	authPortableSourceReady = func() bool { return true }
+	authExportPortableBundle = func(_ string, w io.Writer) error {
+		_, err := w.Write(bundle)
+		return err
 	}
 
-	exportCmd := NewRootCommand()
+	exportCmd := newAuthExportCommandWithSupport(func() error { return nil })
 	var exported bytes.Buffer
 	exportCmd.SetOut(&exported)
 	exportCmd.SetErr(&bytes.Buffer{})
-	exportCmd.SetArgs([]string{"auth", "export", "--base64"})
+	exportCmd.SetArgs([]string{"--base64"})
 	if err := exportCmd.Execute(); err != nil {
 		t.Fatalf("auth export --base64 error = %v", err)
 	}
@@ -69,34 +78,245 @@ func TestAuthExportImportBase64RoundTrip(t *testing.T) {
 		t.Fatalf("write input bundle error = %v", err)
 	}
 
-	targetKeychain := filepath.Join(targetRoot, "target-keychain")
-	targetConfig := filepath.Join(targetRoot, ".dws")
-	t.Setenv(keychain.StorageDirEnv, targetKeychain)
-	t.Setenv("DWS_CONFIG_DIR", targetConfig)
+	authPortableTargetPopulated = func(string) bool { return false }
+	var imported []byte
+	authImportPortableBundle = func(_ string, r io.Reader) (authpkg.PortableImportReport, error) {
+		var err error
+		imported, err = io.ReadAll(r)
+		return authpkg.PortableImportReport{}, err
+	}
+
+	importCmd := newAuthImportCommandWithSupport(func() error { return nil })
+	importCmd.SetOut(&bytes.Buffer{})
+	importCmd.SetErr(&bytes.Buffer{})
+	importCmd.SetArgs([]string{"--input", inputPath, "--base64"})
+	if err := importCmd.Execute(); err != nil {
+		t.Fatalf("auth import --base64 error = %v", err)
+	}
+	if !bytes.Equal(imported, bundle) {
+		t.Fatalf("imported bundle = %q, want %q", imported, bundle)
+	}
+}
+
+func TestCrossPlatformCoverageAuthExportUnsupportedBackendIsValidationError(t *testing.T) {
+	exportCmd := newAuthExportCommandWithSupport(func() error {
+		return errors.New("portable auth export is unavailable for the test backend")
+	})
+	exportCmd.SetOut(&bytes.Buffer{})
+	exportCmd.SetErr(&bytes.Buffer{})
+	exportCmd.SetArgs([]string{"--base64"})
+
+	err := exportCmd.Execute()
+	if err == nil {
+		t.Fatal("auth export should reject an unsupported credential backend")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "test backend") {
+		t.Fatalf("error = %v, want backend-specific reason", err)
+	}
+}
+
+func TestCrossPlatformCoverageAuthExportRejectsWindowsDPAPIBackend(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows DPAPI contract requires a native Windows runner")
+	}
+	t.Cleanup(CloseFileLogger)
+
+	exportCmd := NewRootCommand()
+	exportCmd.SetOut(&bytes.Buffer{})
+	exportCmd.SetErr(&bytes.Buffer{})
+	exportCmd.SetArgs([]string{"auth", "export", "--base64"})
+
+	err := exportCmd.Execute()
+	if err == nil {
+		t.Fatal("auth export should reject the Windows DPAPI backend")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	for _, want := range []string{"Windows", "DPAPI", "HKCU"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error = %v, want substring %q", err, want)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageAuthImportUnsupportedBackendIsValidationErrorBeforeReadingInput(t *testing.T) {
+	root := t.TempDir()
+	configDir := filepath.Join(root, ".dws")
+	keychainDir := filepath.Join(root, "keychain")
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	t.Setenv(keychain.StorageDirEnv, keychainDir)
+
+	importCmd := newAuthImportCommandWithSupport(func() error {
+		return errors.New("portable auth import is unavailable for the test backend")
+	})
+	importCmd.SetOut(&bytes.Buffer{})
+	importCmd.SetErr(&bytes.Buffer{})
+	importCmd.SetArgs([]string{"--input", filepath.Join(root, "missing-bundle.tar.gz")})
+
+	err := importCmd.Execute()
+	if err == nil {
+		t.Fatal("auth import should reject an unsupported credential backend")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "test backend") {
+		t.Fatalf("error = %v, want backend-specific reason", err)
+	}
+	for _, path := range []string{configDir, keychainDir} {
+		if _, statErr := os.Stat(path); !os.IsNotExist(statErr) {
+			t.Fatalf("unsupported import touched %s: stat error = %v", path, statErr)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageAuthImportRejectsWindowsDPAPIBackend(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows DPAPI contract requires a native Windows runner")
+	}
+
+	root := t.TempDir()
+	// NewRootCommand initializes the normal CLI file logger below configDir.
+	// Register its cleanup after TempDir so the Windows handle is closed before
+	// testing removes the temporary directory.
+	t.Cleanup(CloseFileLogger)
+	configDir := filepath.Join(root, ".dws")
+	keychainDir := filepath.Join(root, "keychain")
+	inputPath := filepath.Join(root, "bundle.tar.gz")
+	if err := os.WriteFile(inputPath, []byte("the capability guard must run before this input is read"), 0o600); err != nil {
+		t.Fatalf("write input sentinel error = %v", err)
+	}
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	t.Setenv(keychain.StorageDirEnv, keychainDir)
 
 	importCmd := NewRootCommand()
 	importCmd.SetOut(&bytes.Buffer{})
 	importCmd.SetErr(&bytes.Buffer{})
-	importCmd.SetArgs([]string{"auth", "import", "--input", inputPath, "--base64"})
-	if err := importCmd.Execute(); err != nil {
-		t.Fatalf("auth import --base64 error = %v", err)
-	}
+	importCmd.SetArgs([]string{"auth", "import", "--input", inputPath})
 
-	loaded, err := authpkg.LoadTokenData(targetConfig)
-	if err != nil {
-		t.Fatalf("LoadTokenData() after CLI import error = %v", err)
+	err := importCmd.Execute()
+	if err == nil {
+		t.Fatal("auth import should reject the Windows DPAPI backend")
 	}
-	if loaded.RefreshToken != original.RefreshToken {
-		t.Fatalf("refresh token = %q, want %q", loaded.RefreshToken, original.RefreshToken)
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
 	}
-	if !loaded.IsRefreshTokenValid() {
-		t.Fatal("refresh token should remain valid after CLI import")
+	for _, want := range []string{"Windows", "DPAPI", "HKCU"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("error = %v, want substring %q", err, want)
+		}
+	}
+	// The root command may create configDir/logs as part of normal CLI startup.
+	// The capability guard must still run before any auth state is imported.
+	for _, path := range []string{
+		keychainDir,
+		authpkg.ProfilesPath(configDir),
+		filepath.Join(configDir, "app.json"),
+		filepath.Join(configDir, "token.json"),
+	} {
+		if _, statErr := os.Stat(path); !os.IsNotExist(statErr) {
+			t.Fatalf("unsupported Windows import touched %s: stat error = %v", path, statErr)
+		}
 	}
 }
 
-func TestAuthImportRequiresForceWhenPopulated(t *testing.T) {
+func TestCrossPlatformCoverageAuthImportRejectsWindowsDPAPIBackendWithPopulatedCredentialBeforeRead(t *testing.T) {
+	if runtime.GOOS != "windows" {
+		t.Skip("Windows DPAPI contract requires a native Windows runner")
+	}
+
+	previous, previousErr := authpkg.LoadTokenDataKeychain()
+	if previousErr != nil && !errors.Is(previousErr, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("capture existing Windows credential: %v", previousErr)
+	}
+	hadPrevious := previousErr == nil
+	t.Cleanup(func() {
+		if hadPrevious {
+			_ = authpkg.SaveTokenDataKeychain(previous)
+		} else {
+			_ = authpkg.DeleteTokenDataKeychain()
+		}
+	})
+
+	want := &authpkg.TokenData{
+		AccessToken:  "windows-existing-access",
+		RefreshToken: "windows-existing-refresh",
+		RefreshExpAt: time.Now().Add(24 * time.Hour),
+		CorpID:       "windows-existing-corp",
+	}
+	if err := authpkg.SaveTokenDataKeychain(want); err != nil {
+		t.Fatalf("seed cleanup-scoped Windows DPAPI credential: %v", err)
+	}
+
+	originalTarget := authPortableTargetPopulated
+	originalRead := authReadFile
+	targetChecks := 0
+	bundleReads := 0
+	authPortableTargetPopulated = func(configDir string) bool {
+		targetChecks++
+		return originalTarget(configDir)
+	}
+	authReadFile = func(path string) ([]byte, error) {
+		bundleReads++
+		return originalRead(path)
+	}
+	t.Cleanup(func() {
+		authPortableTargetPopulated = originalTarget
+		authReadFile = originalRead
+	})
+
+	root := t.TempDir()
+	inputPath := filepath.Join(root, "bundle.tar.gz")
+	if err := os.WriteFile(inputPath, []byte("unsupported Windows import must not read this bundle"), 0o600); err != nil {
+		t.Fatalf("write bundle sentinel: %v", err)
+	}
+	t.Setenv("DWS_CONFIG_DIR", filepath.Join(root, ".dws"))
+
+	importCmd := newAuthImportCommand()
+	importCmd.SetOut(&bytes.Buffer{})
+	importCmd.SetErr(&bytes.Buffer{})
+	importCmd.SetArgs([]string{"--input", inputPath})
+	err := importCmd.Execute()
+	if err == nil {
+		t.Fatal("auth import should reject a populated Windows DPAPI backend")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	for _, required := range []string{"Windows", "DPAPI", "HKCU"} {
+		if !strings.Contains(err.Error(), required) {
+			t.Fatalf("error = %v, want substring %q", err, required)
+		}
+	}
+	if strings.Contains(err.Error(), "--force") {
+		t.Fatalf("unsupported Windows import suggested impossible --force remediation: %v", err)
+	}
+	if targetChecks != 0 || bundleReads != 0 {
+		t.Fatalf("unsupported Windows import inspected credentials/bundle: target_checks=%d bundle_reads=%d", targetChecks, bundleReads)
+	}
+
+	got, err := authpkg.LoadTokenDataKeychain()
+	if err != nil {
+		t.Fatalf("reload Windows DPAPI credential after rejection: %v", err)
+	}
+	if got.AccessToken != want.AccessToken || got.RefreshToken != want.RefreshToken || got.CorpID != want.CorpID {
+		t.Fatalf("Windows auth state changed after rejected import: got=%#v want=%#v", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageAuthImportRequiresForceWhenPopulated(t *testing.T) {
 	t.Setenv(keychain.DisableKeychainEnv, "1")
 	root := t.TempDir()
+	t.Cleanup(CloseFileLogger)
 	configDir := filepath.Join(root, ".dws")
 	t.Setenv(keychain.StorageDirEnv, filepath.Join(root, "keychain"))
 	t.Setenv("DWS_CONFIG_DIR", configDir)
@@ -114,11 +334,11 @@ func TestAuthImportRequiresForceWhenPopulated(t *testing.T) {
 		t.Fatalf("write bundle stub error = %v", err)
 	}
 
-	importCmd := NewRootCommand()
+	importCmd := newAuthImportCommandWithSupport(func() error { return nil })
 	var stderr bytes.Buffer
 	importCmd.SetOut(&bytes.Buffer{})
 	importCmd.SetErr(&stderr)
-	importCmd.SetArgs([]string{"auth", "import", "--input", bundlePath})
+	importCmd.SetArgs([]string{"--input", bundlePath})
 	err := importCmd.Execute()
 	if err == nil {
 		t.Fatal("auth import without --force should fail when auth exists")
@@ -132,7 +352,154 @@ func TestAuthImportRequiresForceWhenPopulated(t *testing.T) {
 	}
 }
 
-func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
+func TestAuthImportRequiresForceWhenPopulated(t *testing.T) {
+	originalTarget := authPortableTargetPopulated
+	authPortableTargetPopulated = func(string) bool { return true }
+	t.Cleanup(func() { authPortableTargetPopulated = originalTarget })
+
+	root := t.TempDir()
+	configDir := filepath.Join(root, ".dws")
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+
+	bundlePath := filepath.Join(root, "bundle.tar.gz")
+	if err := os.WriteFile(bundlePath, []byte("not-a-real-bundle"), 0o600); err != nil {
+		t.Fatalf("write bundle stub error = %v", err)
+	}
+
+	importCmd := newAuthImportCommandWithSupport(func() error { return nil })
+	importCmd.SetOut(&bytes.Buffer{})
+	importCmd.SetErr(&bytes.Buffer{})
+	importCmd.SetArgs([]string{"--input", bundlePath})
+	err := importCmd.Execute()
+	if err == nil {
+		t.Fatal("auth import without --force should fail when auth exists")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("expected validation error, got %T: %v", err, err)
+	}
+	if !strings.Contains(err.Error(), "--force") {
+		t.Fatalf("error = %v, want --force hint", err)
+	}
+}
+
+func TestAuthStatusJSONReportsKeychainUnavailable(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", filepath.Join(t.TempDir(), "config"))
+
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		LoadToken: func(configDir string) ([]byte, error) {
+			return nil, keychain.NewUnavailableError("read DEK from macOS Keychain", errors.New("default keychain missing"))
+		},
+	})
+	t.Cleanup(func() {
+		edition.Override(prev)
+	})
+
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--format", "json", "auth", "status"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth status --format json error = %v\noutput:\n%s", err, out.String())
+	}
+
+	var resp struct {
+		Success       bool   `json:"success"`
+		Authenticated bool   `json:"authenticated"`
+		Reason        string `json:"reason"`
+		Message       string `json:"message"`
+		Hint          string `json:"hint"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal auth status JSON error = %v\noutput:\n%s", err, out.String())
+	}
+	if !resp.Success {
+		t.Fatalf("success = false, want true; response=%+v", resp)
+	}
+	if resp.Authenticated {
+		t.Fatalf("authenticated = true, want false; response=%+v", resp)
+	}
+	if resp.Reason != "keychain_unavailable" {
+		t.Fatalf("reason = %q, want keychain_unavailable; response=%+v", resp.Reason, resp)
+	}
+	if !strings.Contains(resp.Message, "Keychain") && !strings.Contains(resp.Message, "钥匙串") {
+		t.Fatalf("message should mention Keychain/钥匙串; response=%+v", resp)
+	}
+	if !strings.Contains(resp.Hint, keychain.DisableKeychainEnv) {
+		t.Fatalf("hint should mention %s; response=%+v", keychain.DisableKeychainEnv, resp)
+	}
+}
+
+func TestAuthStatusJSONReportsDEKMissing(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", filepath.Join(t.TempDir(), "config"))
+
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		LoadToken: func(configDir string) ([]byte, error) {
+			return nil, fmt.Errorf("load from keychain: %w", keychain.ErrDEKMissing)
+		},
+	})
+	t.Cleanup(func() {
+		edition.Override(prev)
+	})
+
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--format", "json", "auth", "status"})
+
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth status --format json error = %v\noutput:\n%s", err, out.String())
+	}
+
+	var resp struct {
+		Success       bool   `json:"success"`
+		Authenticated bool   `json:"authenticated"`
+		Reason        string `json:"reason"`
+		Message       string `json:"message"`
+		Hint          string `json:"hint"`
+	}
+	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal auth status JSON error = %v\noutput:\n%s", err, out.String())
+	}
+	if !resp.Success {
+		t.Fatalf("success = false, want true; response=%+v", resp)
+	}
+	if resp.Authenticated {
+		t.Fatalf("authenticated = true, want false; response=%+v", resp)
+	}
+	if resp.Reason != "dek_missing" {
+		t.Fatalf("reason = %q, want dek_missing; response=%+v", resp.Reason, resp)
+	}
+	if !strings.Contains(resp.Message, "登录密钥") {
+		t.Fatalf("message should mention 登录密钥; response=%+v", resp)
+	}
+	if !strings.Contains(resp.Hint, "重新登录") {
+		t.Fatalf("hint should mention 重新登录; response=%+v", resp)
+	}
+	if !strings.Contains(resp.Hint, "dws auth reset") {
+		t.Fatalf("hint should mention dws auth reset; response=%+v", resp)
+	}
+}
+
+func TestAuthStatusDiagnosticReportsCiphertextKeyMismatch(t *testing.T) {
+	diagnostic := authStatusDiagnosticFromError(fmt.Errorf("load token: %w", keychain.ErrCiphertextKeyMismatch))
+	if diagnostic == nil {
+		t.Fatal("authStatusDiagnosticFromError() = nil")
+	}
+	if diagnostic.Reason != "ciphertext_key_mismatch" {
+		t.Fatalf("reason = %q, want ciphertext_key_mismatch", diagnostic.Reason)
+	}
+	if !strings.Contains(diagnostic.Hint, keychain.DisableKeychainEnv) {
+		t.Fatalf("hint should mention %s: %q", keychain.DisableKeychainEnv, diagnostic.Hint)
+	}
+}
+
+func TestAuthStatusRefreshFailureReportsUnauthenticatedDiagnostic(t *testing.T) {
 	// Isolate keychain storage to a per-test directory so the saved
 	// token can't leak into other test packages running in parallel.
 	t.Setenv(keychain.StorageDirEnv, t.TempDir())
@@ -151,6 +518,9 @@ func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
 		ExpiresAt:    time.Now().Add(-time.Hour),
 		RefreshExpAt: time.Now().Add(24 * time.Hour),
 		CorpID:       "dingcorp",
+		UserID:       "user-dingcorp",
+		ClientID:     "client-dingcorp",
+		Source:       "mcp",
 	})
 	if err != nil {
 		t.Skipf("SaveTokenData() unavailable in this environment: %v", err)
@@ -168,7 +538,7 @@ func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
 	var out bytes.Buffer
 	cmd.SetOut(&out)
 	cmd.SetErr(&out)
-	cmd.SetArgs([]string{"auth", "status"})
+	cmd.SetArgs([]string{"--format", "json", "auth", "status"})
 
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("Execute() error = %v\noutput:\n%s", err, out.String())
@@ -179,8 +549,18 @@ func TestAuthStatusRefreshFailureLeavesStoredTokenIntact(t *testing.T) {
 		t.Fatal("secure token data should remain in keychain after refresh failure")
 	}
 
-	if !bytes.Contains(out.Bytes(), []byte("\"authenticated\"")) {
-		t.Fatalf("output should still report authenticated status:\n%s", out.String())
+	var resp authStatusResponse
+	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v\noutput:\n%s", err, out.String())
+	}
+	if resp.Authenticated {
+		t.Fatalf("authenticated = true after refresh failure: %+v", resp)
+	}
+	if resp.Reason != "token_refresh_failed" {
+		t.Fatalf("reason = %q, want token_refresh_failed: %+v", resp.Reason, resp)
+	}
+	if !strings.Contains(resp.Message, "refresh failed") {
+		t.Fatalf("message = %q, want original refresh failure", resp.Message)
 	}
 }
 
@@ -228,8 +608,120 @@ func TestAuthStatusProfileOverrideDoesNotSwitchCurrentProfile(t *testing.T) {
 	if err != nil {
 		t.Fatalf("LoadProfiles() error = %v", err)
 	}
-	if cfg.CurrentProfile != "corp_secondary" {
-		t.Fatalf("currentProfile = %q, want unchanged corp_secondary", cfg.CurrentProfile)
+	if cfg.CurrentProfile != "corp_secondary:user-corp_secondary" {
+		t.Fatalf("currentProfile = %q, want unchanged exact secondary identity", cfg.CurrentProfile)
+	}
+}
+
+func TestAuthStatusRejectsAmbiguousProfileSelector(t *testing.T) {
+	first := authLogoutTestToken("corp_first")
+	first.CorpName = "Shared Org"
+	second := authLogoutTestToken("corp_second")
+	second.CorpName = "Shared Org"
+	setupAuthLogoutProfiles(t, first, second)
+
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"--format", "json", "auth", "status", "--profile", "Shared Org"})
+	err := cmd.Execute()
+	if err == nil {
+		t.Fatalf("auth status accepted ambiguous profile selector\noutput:\n%s", out.String())
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("error = %T %v, want validation error", err, err)
+	}
+	for _, candidate := range []string{"corp_first", "corp_second"} {
+		if !strings.Contains(err.Error(), candidate) {
+			t.Fatalf("error = %q, want candidate %q", err.Error(), candidate)
+		}
+	}
+}
+
+func TestAuthMigrateKeychainDryRunAndConfirmedExecution(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "")
+	oldMigrate := migrateKeychainToFileDEK
+	t.Cleanup(func() { migrateKeychainToFileDEK = oldMigrate })
+
+	calls := 0
+	migrateKeychainToFileDEK = func(_ string, dryRun bool) (int, error) {
+		calls++
+		if calls == 1 && !dryRun {
+			t.Fatal("first migration call should be dry-run")
+		}
+		if calls == 2 && dryRun {
+			t.Fatal("second migration call should execute")
+		}
+		return 4, nil
+	}
+
+	newRoot := func() (*cobra.Command, *bytes.Buffer) {
+		root := &cobra.Command{Use: "dws"}
+		root.PersistentFlags().Bool("dry-run", false, "")
+		root.PersistentFlags().Bool("yes", false, "")
+		root.PersistentFlags().String("format", "json", "")
+		root.AddCommand(newAuthMigrateKeychainCommand())
+		var out bytes.Buffer
+		root.SetOut(&out)
+		root.SetErr(&out)
+		return root, &out
+	}
+
+	root, out := newRoot()
+	root.SetArgs([]string{"migrate-keychain", "--dry-run"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("migrate-keychain --dry-run error = %v\noutput:\n%s", err, out.String())
+	}
+	if !strings.Contains(out.String(), `"dry_run":true`) || !strings.Contains(out.String(), `"entries":4`) {
+		t.Fatalf("dry-run output = %q", out.String())
+	}
+
+	root, out = newRoot()
+	root.SetArgs([]string{"migrate-keychain", "--yes"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("migrate-keychain --yes error = %v\noutput:\n%s", err, out.String())
+	}
+	if !strings.Contains(out.String(), `"dry_run":false`) || !strings.Contains(out.String(), `"entries":4`) {
+		t.Fatalf("migration output = %q", out.String())
+	}
+	if calls != 2 {
+		t.Fatalf("migration calls = %d, want 2", calls)
+	}
+}
+
+func TestAuthMigrateKeychainRequiresConfirmationAndSystemMode(t *testing.T) {
+	oldMigrate := migrateKeychainToFileDEK
+	t.Cleanup(func() { migrateKeychainToFileDEK = oldMigrate })
+	migrateKeychainToFileDEK = func(_ string, _ bool) (int, error) {
+		t.Fatal("migration backend should not be called")
+		return 0, nil
+	}
+
+	newRoot := func() *cobra.Command {
+		root := &cobra.Command{Use: "dws"}
+		root.PersistentFlags().Bool("dry-run", false, "")
+		root.PersistentFlags().Bool("yes", false, "")
+		root.PersistentFlags().String("format", "json", "")
+		root.AddCommand(newAuthMigrateKeychainCommand())
+		root.SetOut(io.Discard)
+		root.SetErr(io.Discard)
+		return root
+	}
+
+	t.Setenv(keychain.DisableKeychainEnv, "")
+	root := newRoot()
+	root.SetArgs([]string{"migrate-keychain"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "--yes") {
+		t.Fatalf("unconfirmed migration error = %v, want --yes guidance", err)
+	}
+
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	root = newRoot()
+	root.SetArgs([]string{"migrate-keychain", "--dry-run"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "env -u") {
+		t.Fatalf("file-DEK mode migration error = %v, want system-mode guidance", err)
 	}
 }
 
@@ -318,8 +810,8 @@ func TestAuthLogoutProfileDeletesOnlySelectedProfile(t *testing.T) {
 	if err != nil {
 		t.Fatalf("LoadProfiles() error = %v", err)
 	}
-	if cfg.PrimaryProfile != "corp_secondary" || cfg.CurrentProfile != "corp_secondary" {
-		t.Fatalf("profiles pointers = primary %q current %q, want corp_secondary/corp_secondary", cfg.PrimaryProfile, cfg.CurrentProfile)
+	if cfg.PrimaryProfile != "" || cfg.CurrentProfile != "corp_secondary:user-corp_secondary" {
+		t.Fatalf("profiles pointers = primary %q current %q", cfg.PrimaryProfile, cfg.CurrentProfile)
 	}
 	if len(cfg.Profiles) != 1 || cfg.Profiles[0].CorpID != "corp_secondary" {
 		t.Fatalf("profiles = %#v, want only corp_secondary retained", cfg.Profiles)
@@ -339,6 +831,102 @@ func TestAuthLogoutProfileDeletesOnlySelectedProfile(t *testing.T) {
 	}
 }
 
+func TestAuthLogoutExactProfilePreservesSameCorpAccount(t *testing.T) {
+	first := authLogoutTestToken("corp_same")
+	first.UserID = "user_1"
+	second := authLogoutTestToken("corp_same")
+	second.AccessToken = "access-second"
+	second.RefreshToken = "refresh-second"
+	second.UserID = "user_2"
+	configDir := setupAuthLogoutProfiles(t, first, second)
+
+	originalTransport := http.DefaultTransport
+	t.Cleanup(func() {
+		http.DefaultTransport = originalTransport
+	})
+	http.DefaultTransport = roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return nil, errors.New("remote revoke disabled in unit test")
+	})
+
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"auth", "logout", "--profile", "corp_same:user_2"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth logout exact profile error = %v\noutput:\n%s", err, out.String())
+	}
+	cfg, err := authpkg.LoadProfiles(configDir)
+	if err != nil {
+		t.Fatalf("LoadProfiles() error = %v", err)
+	}
+	if len(cfg.Profiles) != 1 || cfg.Profiles[0].UserID != "user_1" {
+		t.Fatalf("profiles = %#v, want only user_1 retained", cfg.Profiles)
+	}
+	if authpkg.TokenDataExistsKeychainForIdentity("corp_same", "user_2") {
+		t.Fatal("selected identity token should be deleted")
+	}
+	loaded, err := authpkg.LoadTokenDataForProfile(configDir, "corp_same")
+	if err != nil {
+		t.Fatalf("LoadTokenDataForProfile(org) error = %v", err)
+	}
+	if loaded.UserID != "user_1" || loaded.AccessToken != first.AccessToken {
+		t.Fatalf("org current token = %#v, want retained user_1", loaded)
+	}
+}
+
+func TestAuthLogoutLocalProfileNameRevokesOnlySelectedAccount(t *testing.T) {
+	first := authLogoutTestToken("corp_same")
+	first.UserID = "user_1"
+	first.UserName = "账号一"
+	second := authLogoutTestToken("corp_same")
+	second.AccessToken = "access-second"
+	second.RefreshToken = "refresh-second"
+	second.UserID = "user_2"
+	second.UserName = "账号二"
+	configDir := setupAuthLogoutProfiles(t, first, second)
+
+	cfg, err := authpkg.LoadProfiles(configDir)
+	if err != nil {
+		t.Fatalf("LoadProfiles() error = %v", err)
+	}
+	var selector string
+	for _, profile := range cfg.Profiles {
+		if profile.UserID == "user_2" {
+			selector = profile.Name
+		}
+	}
+	if selector == "" || selector == second.CorpName {
+		t.Fatalf("second local profile name = %q, want unique non-org alias", selector)
+	}
+
+	requests := 0
+	originalTransport := http.DefaultTransport
+	t.Cleanup(func() {
+		http.DefaultTransport = originalTransport
+	})
+	http.DefaultTransport = roundTripFunc(func(*http.Request) (*http.Response, error) {
+		requests++
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Header:     make(http.Header),
+			Body:       io.NopCloser(strings.NewReader("")),
+		}, nil
+	})
+
+	cmd := NewRootCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&out)
+	cmd.SetArgs([]string{"auth", "logout", "--profile", selector})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth logout local profile error = %v\noutput:\n%s", err, out.String())
+	}
+	if requests != 1 {
+		t.Fatalf("remote revoke requests = %d, want 1", requests)
+	}
+}
+
 func TestAuthLoginPostLoginTUIModeRespectsRecommendAndFormat(t *testing.T) {
 	newRoot := func(t *testing.T) *cobra.Command {
 		t.Helper()
@@ -424,8 +1012,15 @@ func TestLoginRecommendProductLabelMatchesTUITarget(t *testing.T) {
 }
 
 func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) {
+	t.Setenv("DWS_DEBUG_AUTH", "1")
+	var logs bytes.Buffer
+	previousLogger := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(previousLogger) })
+
 	root := &cobra.Command{Use: "dws"}
 	root.PersistentFlags().Bool("yes", false, "")
+	root.PersistentFlags().String("profile", "", "")
 	login := &cobra.Command{Use: "login"}
 	login.Flags().String("token", "", "")
 	login.Flags().Bool("device", false, "")
@@ -450,6 +1045,11 @@ func TestResolveAuthLoginConfigReadsInheritedYes(t *testing.T) {
 	if !cfg.Yes {
 		t.Fatal("Yes = false, want true")
 	}
+	if got := logs.String(); !strings.Contains(got, `"msg":"auth.login.request"`) ||
+		!strings.Contains(got, `"profile_selector":""`) ||
+		!strings.Contains(got, `"target_corp_id":""`) {
+		t.Fatalf("login request diagnostic log missing selector resolution:\n%s", got)
+	}
 }
 
 func TestAuthLoginForcesAuthorizationByDefault(t *testing.T) {
@@ -500,6 +1100,12 @@ func TestAuthLoginRecommendSkipsPostLoginTUI(t *testing.T) {
 		`{"success":true,"data":{"items":[{"scope":"calendar.event:read","productCode":"calendar","productName":"日历"}],"selectedScopes":["calendar.event:read"]}}`,
 		`{"success":true,"data":{"grantedScopes":["calendar.event:read"]}}`,
 	}}
+	authpkg.SetRuntimeProfile("corp_old:user_old")
+	t.Cleanup(func() { authpkg.SetRuntimeProfile("") })
+	var authorizationProfiles []string
+	fake.beforeCall = func(string) {
+		authorizationProfiles = append(authorizationProfiles, authpkg.RuntimeProfile())
+	}
 	cmd := newAuthLoginCommand(fake)
 	var out bytes.Buffer
 	cmd.SetOut(&out)
@@ -518,6 +1124,61 @@ func TestAuthLoginRecommendSkipsPostLoginTUI(t *testing.T) {
 	if got := fake.args[0]["recommend"]; got != true {
 		t.Fatalf("--recommend plan recommend = %#v, want true", got)
 	}
+	for _, profile := range authorizationProfiles {
+		if profile != "" {
+			t.Fatalf("manual token post-login profile = %q, want empty runtime selector", profile)
+		}
+	}
+	if got := authpkg.RuntimeProfile(); got != "corp_old:user_old" {
+		t.Fatalf("runtime profile after authorization = %q, want restored selector", got)
+	}
+}
+
+func TestAuthLoginRecommendUsesNewExactIdentity(t *testing.T) {
+	t.Setenv(keychain.DisableKeychainEnv, "1")
+	t.Setenv(keychain.StorageDirEnv, t.TempDir())
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+
+	oldOAuthLogin := authOAuthLogin
+	oldInteractive := authLoginInteractiveTerminal
+	t.Cleanup(func() {
+		authOAuthLogin = oldOAuthLogin
+		authLoginInteractiveTerminal = oldInteractive
+		authpkg.SetRuntimeProfile("")
+	})
+	authLoginInteractiveTerminal = func() bool { return false }
+	authOAuthLogin = func(*authpkg.OAuthProvider, context.Context, bool) (*authpkg.TokenData, error) {
+		return &authpkg.TokenData{
+			AccessToken: "new-token",
+			CorpID:      "corp_same",
+			UserID:      "user_new",
+			ExpiresAt:   time.Now().Add(time.Hour),
+		}, nil
+	}
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"data":{"items":[],"selectedScopes":[]}}`,
+	}}
+	var authorizationProfiles []string
+	fake.beforeCall = func(string) {
+		authorizationProfiles = append(authorizationProfiles, authpkg.RuntimeProfile())
+	}
+	authpkg.SetRuntimeProfile("corp_same:user_old")
+
+	cmd := newAuthLoginCommand(fake)
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs([]string{"--recommend"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("auth login --recommend error = %v", err)
+	}
+	for _, profile := range authorizationProfiles {
+		if profile != "corp_same:user_new" {
+			t.Fatalf("post-login authorization profile = %q, want new exact identity", profile)
+		}
+	}
+	if got := authpkg.RuntimeProfile(); got != "corp_same:user_old" {
+		t.Fatalf("runtime profile after authorization = %q, want restored old identity", got)
+	}
 }
 
 func TestAuthLoginDefaultTUIModeSkipsSelectorWhenAllGranted(t *testing.T) {
@@ -742,7 +1403,7 @@ func TestAuthLoginDefaultTUIRunsAfterLoginTokenSaved(t *testing.T) {
 	}
 }
 
-func TestEnrichAuthLoginProfileFromContactPersistsCorpName(t *testing.T) {
+func TestEnrichAuthLoginProfileFromContactBeforePersist(t *testing.T) {
 	t.Setenv(keychain.DisableKeychainEnv, "1")
 	t.Setenv(keychain.StorageDirEnv, t.TempDir())
 	configDir := t.TempDir()
@@ -757,12 +1418,8 @@ func TestEnrichAuthLoginProfileFromContactPersistsCorpName(t *testing.T) {
 		ClientID:     "client-id",
 		Source:       "mcp",
 	}
-	if err := authpkg.SaveTokenData(configDir, token); err != nil {
-		t.Fatalf("SaveTokenData() error = %v", err)
-	}
-
 	fake := &authLoginRecommendSequenceCaller{responses: []string{
-		`{"success":true,"result":[{"orgEmployeeModel":{"corpId":"ding32fff839a3e0105d","orgName":"钉钉（中国）信息技术有限公司","userId":"011352590165863362195","orgUserName":"玄玦(主用钉)"}}]}`,
+		`{"success":true,"result":[{"isAdmin":false,"orgEmployeeModel":{"jobNumber":"202397","orgId":null,"orgName":"钉钉（中国）信息技术有限公司","orgUserId":"011352590165863362195","orgUserName":"玄玦(主用钉)"}}]}`,
 	}}
 	if err := enrichAuthLoginProfileFromContact(context.Background(), configDir, fake, token); err != nil {
 		t.Fatalf("enrichAuthLoginProfileFromContact() error = %v", err)
@@ -773,6 +1430,16 @@ func TestEnrichAuthLoginProfileFromContactPersistsCorpName(t *testing.T) {
 	if token.UserID != "011352590165863362195" || token.UserName != "玄玦(主用钉)" {
 		t.Fatalf("token user identity = (%q, %q), want contact result", token.UserID, token.UserName)
 	}
+	cfg, err := authpkg.LoadProfiles(configDir)
+	if err != nil {
+		t.Fatalf("LoadProfiles() before persist error = %v", err)
+	}
+	if len(cfg.Profiles) != 0 {
+		t.Fatalf("identity enrichment persisted token early: %#v", cfg.Profiles)
+	}
+	if err := authpkg.SaveTokenData(configDir, token); err != nil {
+		t.Fatalf("SaveTokenData() error = %v", err)
+	}
 
 	loaded, err := authpkg.LoadTokenDataForProfile(configDir, "ding32fff839a3e0105d")
 	if err != nil {
@@ -784,8 +1451,50 @@ func TestEnrichAuthLoginProfileFromContactPersistsCorpName(t *testing.T) {
 	if len(fake.tools) != 1 || fake.tools[0] != "get_current_user_profile" {
 		t.Fatalf("tool calls = %v, want get_current_user_profile", fake.tools)
 	}
-	if got := fake.args[0]["profile"]; got != "ding32fff839a3e0105d" {
-		t.Fatalf("contact profile arg = %#v, want ding32fff839a3e0105d", got)
+	if len(fake.args[0]) != 0 {
+		t.Fatalf("contact profile args = %#v, want no arguments", fake.args[0])
+	}
+	if len(fake.tokens) != 1 || fake.tokens[0] != "access-token" {
+		t.Fatalf("token overrides = %v, want access-token", fake.tokens)
+	}
+}
+
+func TestEnrichAuthLoginProfileLogsIdentityResolutionWithoutCredentials(t *testing.T) {
+	t.Setenv("DWS_DEBUG_AUTH", "1")
+	var logs bytes.Buffer
+	previousLogger := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(previousLogger) })
+
+	token := &authpkg.TokenData{
+		AccessToken:  "secret-access-token",
+		RefreshToken: "secret-refresh-token",
+		CorpID:       "ding_same_corp",
+	}
+	fake := &authLoginRecommendSequenceCaller{responses: []string{
+		`{"success":true,"result":[{"orgEmployeeModel":{"corpId":"ding_same_corp","orgName":"同一组织","userId":"user_two","orgUserName":"账号二"}}]}`,
+	}}
+
+	if err := enrichAuthLoginProfileFromContact(context.Background(), t.TempDir(), fake, token); err != nil {
+		t.Fatalf("enrichAuthLoginProfileFromContact() error = %v", err)
+	}
+
+	got := logs.String()
+	for _, want := range []string{
+		`"msg":"auth.login.identity.lookup.start"`,
+		`"msg":"auth.login.identity.lookup.result"`,
+		`"corp_id":"ding_same_corp"`,
+		`"user_id":"user_two"`,
+		`"user_name":"账号二"`,
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("diagnostic logs missing %q:\n%s", want, got)
+		}
+	}
+	for _, secret := range []string{"secret-access-token", "secret-refresh-token"} {
+		if strings.Contains(got, secret) {
+			t.Fatalf("diagnostic logs exposed credential %q:\n%s", secret, got)
+		}
 	}
 }
 
@@ -799,6 +1508,7 @@ type authLoginRecommendSequenceCaller struct {
 	responses  []string
 	tools      []string
 	args       []map[string]any
+	tokens     []string
 	beforeCall func(toolName string)
 }
 
@@ -820,10 +1530,19 @@ func (f *authLoginRecommendSequenceCaller) CallTool(_ context.Context, _ string,
 	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: response}}}, nil
 }
 
+func (f *authLoginRecommendSequenceCaller) CallToolWithToken(ctx context.Context, token, productID, toolName string, args map[string]any) (*edition.ToolResult, error) {
+	f.tokens = append(f.tokens, token)
+	return f.CallTool(ctx, productID, toolName, args)
+}
+
 func (f *authLoginRecommendSequenceCaller) Format() string { return "table" }
 
 func (f *authLoginRecommendSequenceCaller) DryRun() bool { return false }
 
+func (f *authLoginRecommendSequenceCaller) Fields() string { return "" }
+
+func (f *authLoginRecommendSequenceCaller) JQ() string { return "" }
+
 func stringSliceArgEqual(got any, want []string) bool {
 	if got == nil {
 		return len(want) == 0
@@ -865,9 +1584,11 @@ func setupAuthLogoutProfiles(t *testing.T, tokens ...*authpkg.TokenData) string
 	ResetRuntimeTokenCache()
 	clearCompatCache()
 	t.Cleanup(func() {
+		_ = authpkg.DeleteAllTokenData(configDir)
 		authpkg.SetRuntimeProfile("")
 		ResetRuntimeTokenCache()
 		clearCompatCache()
+		CloseFileLogger()
 	})
 
 	for _, token := range tokens {

internal/app/auth_migrate_coverage_test.go

@@ -0,0 +1,70 @@
+package app
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/spf13/cobra"
+)
+
+func TestAuthMigrateKeychainRemainingBranches(t *testing.T) {
+	originalMigrate, originalTarget := migrateKeychainToFileDEK, authMigrateTarget
+	t.Cleanup(func() {
+		migrateKeychainToFileDEK, authMigrateTarget = originalMigrate, originalTarget
+	})
+	newRoot := func(format string) (*cobra.Command, *bytes.Buffer) {
+		root := &cobra.Command{Use: "dws"}
+		root.PersistentFlags().Bool("dry-run", false, "")
+		root.PersistentFlags().Bool("yes", false, "")
+		root.PersistentFlags().String("format", format, "")
+		root.AddCommand(newAuthMigrateKeychainCommand())
+		var output bytes.Buffer
+		root.SetOut(&output)
+		root.SetErr(&output)
+		return root, &output
+	}
+	t.Setenv(keychain.DisableKeychainEnv, "")
+
+	authMigrateTarget = func(*cobra.Command) (string, error) { return "", errors.New("flag") }
+	root, _ := newRoot("text")
+	root.SetArgs([]string{"migrate-keychain", "--dry-run"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "--to") {
+		t.Fatalf("target flag error = %v", err)
+	}
+	authMigrateTarget = originalTarget
+	root, _ = newRoot("text")
+	root.SetArgs([]string{"migrate-keychain", "--to", "other", "--dry-run"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "file-dek") {
+		t.Fatalf("unsupported target error = %v", err)
+	}
+
+	migrateKeychainToFileDEK = func(string, bool) (int, error) { return 0, errors.New("backend") }
+	root, _ = newRoot("text")
+	root.SetArgs([]string{"migrate-keychain", "--dry-run"})
+	if err := root.Execute(); err == nil || !strings.Contains(err.Error(), "backend") {
+		t.Fatalf("migration backend error = %v", err)
+	}
+	migrateKeychainToFileDEK = func(string, bool) (int, error) { return 3, nil }
+	for _, test := range []struct {
+		args []string
+		want string
+	}{
+		{[]string{"migrate-keychain", "--dry-run"}, "预检通过"},
+		{[]string{"migrate-keychain", "--yes"}, "迁移完成"},
+	} {
+		root, output := newRoot("text")
+		root.SetArgs(test.args)
+		if err := root.Execute(); err != nil || !strings.Contains(output.String(), test.want) {
+			t.Fatalf("migrate %v = %v, %q", test.args, err, output.String())
+		}
+	}
+}
+
+// Keep the original test name for the focused macOS auth workflow while also
+// opting the coverage fixture into the native platform coverage gate.
+func TestCrossPlatformCoverageAuthMigrateKeychainRemainingBranches(t *testing.T) {
+	TestAuthMigrateKeychainRemainingBranches(t)
+}

internal/app/auth_refresh_retry.go

@@ -15,6 +15,15 @@ package app
 
 import (
 	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/logging"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/authretry"
 )
 
 // authRetryingKey marks a context that has already attempted one
@@ -23,8 +32,35 @@ import (
 // to the user instead.
 type authRetryingKeyType struct{}
 
+type authRefreshFailureError struct {
+	rejection error
+	refresh   error
+}
+
+func (e *authRefreshFailureError) Error() string {
+	return "automatic access token refresh failed"
+}
+
+func (e *authRefreshFailureError) Unwrap() []error {
+	if e == nil {
+		return nil
+	}
+	return []error{e.rejection, e.refresh}
+}
+
 var authRetryingKey = authRetryingKeyType{}
 
+var (
+	runnerForceRefreshRejectedAccessToken = forceRefreshRejectedAccessToken
+	runnerExecuteAuthRetry                func(*runtimeRunner, context.Context, string, executor.Invocation) (executor.Result, error)
+)
+
+func init() {
+	runnerExecuteAuthRetry = func(r *runtimeRunner, ctx context.Context, endpoint string, invocation executor.Invocation) (executor.Result, error) {
+		return r.executeInvocation(ctx, endpoint, invocation)
+	}
+}
+
 // IsAuthRetrying reports whether the current context is already inside an
 // AuthRefreshRequired retry. Mirrors IsPatRetrying.
 func IsAuthRetrying(ctx context.Context) bool {
@@ -34,3 +70,103 @@ func IsAuthRetrying(ctx context.Context) bool {
 	v, _ := ctx.Value(authRetryingKey).(bool)
 	return v
 }
+
+func withAuthRetrying(ctx context.Context) context.Context {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	return context.WithValue(ctx, authRetryingKey, true)
+}
+
+func authRefreshLogger() *slog.Logger {
+	if logger := FileLoggerInstance(); logger != nil {
+		return logger
+	}
+	return slog.Default()
+}
+
+func (r *runtimeRunner) managesRuntimeOAuth(hasPluginAuth bool) bool {
+	if r == nil || hasPluginAuth {
+		return false
+	}
+	return r.globalFlags == nil || strings.TrimSpace(r.globalFlags.Token) == ""
+}
+
+// retryAuthRefreshRequired consumes only the explicit edition marker. It does
+// not infer retryability from free text, generic auth categories, HTTP 403, or
+// ordinary business errors.
+func (r *runtimeRunner) retryAuthRefreshRequired(
+	ctx context.Context,
+	endpoint string,
+	invocation executor.Invocation,
+	rejectedAccessToken string,
+	markerErr error,
+	hasPluginAuth bool,
+) (executor.Result, error, bool) {
+	marker, marked := authretry.As(markerErr)
+	if !marked {
+		return executor.Result{}, nil, false
+	}
+	cause := marker.Cause
+	if cause == nil {
+		cause = markerErr
+	}
+
+	// Explicit --token and plugin credentials are not backed by the default
+	// OAuth refresh store. Preserve the overlay cause without mutating an
+	// unrelated persisted login.
+	if !r.managesRuntimeOAuth(hasPluginAuth) {
+		return executor.Result{}, cause, true
+	}
+	if IsAuthRetrying(ctx) {
+		authRefreshLogger().Warn("auth.runtime.refresh.retry_exhausted",
+			"product", invocation.CanonicalProduct,
+			"tool", invocation.Tool,
+		)
+		return executor.Result{}, cause, true
+	}
+
+	if _, err := runnerForceRefreshRejectedAccessToken(ctx, defaultConfigDir(), rejectedAccessToken); err != nil {
+		// Keep every log credential-safe. The returned error chain retains the
+		// complete cause for in-process diagnosis; even DWS_DEBUG_AUTH must not
+		// serialize an OAuth response body or other attacker-controlled text.
+		authRefreshLogger().Warn("auth.runtime.refresh.failed",
+			"product", invocation.CanonicalProduct,
+			"tool", invocation.Tool,
+			"stage", "force_refresh_rejected_token",
+			"error_type", fmt.Sprintf("%T", err),
+		)
+		logging.AuthDebug("auth.runtime.refresh.failed.detail",
+			"product", invocation.CanonicalProduct,
+			"tool", invocation.Tool,
+			"stage", "force_refresh_rejected_token",
+			"error_type", fmt.Sprintf("%T", err),
+		)
+		combined := &authRefreshFailureError{rejection: cause, refresh: err}
+		return executor.Result{}, apperrors.NewAuth(
+			"automatic access token refresh failed",
+			apperrors.WithOperation("auth/token/refresh"),
+			apperrors.WithReason("auth_refresh_failed"),
+			apperrors.WithHint("本地凭证已保留；可稍后重试，若持续失败请查看认证诊断日志。"),
+			apperrors.WithCause(combined),
+		), true
+	}
+
+	logging.AuthDebug("auth.runtime.refresh.succeeded",
+		"product", invocation.CanonicalProduct,
+		"tool", invocation.Tool,
+	)
+	result, err := runnerExecuteAuthRetry(r, withAuthRetrying(ctx), endpoint, invocation)
+	return result, err, true
+}
+
+// isRefreshableTransportAuthError deliberately excludes HTTP/RPC 403 and
+// generic CategoryAuth values. OnAuthError may request a refresh only for an
+// exact transport-level unauthorized signal.
+func isRefreshableTransportAuthError(err error) bool {
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Category != apperrors.CategoryAuth {
+		return false
+	}
+	return typed.Reason == "http_401" || typed.RPCCode == 401
+}

internal/app/auth_refresh_retry_runner_test.go

@@ -0,0 +1,354 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"log/slog"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/audit"
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/authretry"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+func installAuthRefreshRunnerSeams(t *testing.T) {
+	t.Helper()
+	previousHooks := edition.Get()
+	previousCall := runnerCallTool
+	previousPreflight := runnerPreflightDocDownload
+	previousRefresh := runnerForceRefreshRejectedAccessToken
+	previousRetry := runnerExecuteAuthRetry
+	previousCapture := runnerCaptureRuntimeFailure
+	previousProfile := authpkg.RuntimeProfile()
+
+	pluginAuthMu.Lock()
+	previousPlugins := pluginAuthRegistry
+	pluginAuthRegistry = make(map[string]*PluginAuth)
+	pluginAuthMu.Unlock()
+
+	runnerPreflightDocDownload = func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
+		return nil
+	}
+	runnerCaptureRuntimeFailure = func(executor.Invocation, error, error) {}
+	authpkg.SetRuntimeProfile("")
+	runtimeTokenManager.Invalidate()
+	t.Setenv("DWS_CONFIG_DIR", "")
+	t.Setenv("DWS_DEBUG_AUTH", "0")
+
+	t.Cleanup(func() {
+		edition.Override(previousHooks)
+		runnerCallTool = previousCall
+		runnerPreflightDocDownload = previousPreflight
+		runnerForceRefreshRejectedAccessToken = previousRefresh
+		runnerExecuteAuthRetry = previousRetry
+		runnerCaptureRuntimeFailure = previousCapture
+		authpkg.SetRuntimeProfile(previousProfile)
+		runtimeTokenManager.Invalidate()
+		pluginAuthMu.Lock()
+		pluginAuthRegistry = previousPlugins
+		pluginAuthMu.Unlock()
+	})
+}
+
+func authRefreshTestRunner(flags *GlobalFlags) *runtimeRunner {
+	return &runtimeRunner{
+		transport:   transport.NewClient(nil),
+		globalFlags: flags,
+		auditSink:   audit.NopSink{},
+	}
+}
+
+func authRefreshTestInvocation() executor.Invocation {
+	return executor.Invocation{
+		CanonicalProduct: "auth-retry-test-product",
+		Tool:             "test_tool",
+		Params:           map[string]any{"value": "safe"},
+	}
+}
+
+func authRefreshTokenHooks(configDir string, token *string, classify func(map[string]any) error) *edition.Hooks {
+	return &edition.Hooks{
+		ConfigDir: func() string { return configDir },
+		TokenProvider: func(context.Context, func() (string, error)) (string, error) {
+			return *token, nil
+		},
+		ClassifyToolResult: classify,
+	}
+}
+
+func TestCrossPlatformCoverageRunnerRetriesEditionAuthMarkerOnce(t *testing.T) {
+	installAuthRefreshRunnerSeams(t)
+	configDir := t.TempDir()
+	token := "old-access"
+	rejection := apperrors.NewAuth("server rejected access token", apperrors.WithReason("access_token_rejected"))
+	edition.Override(authRefreshTokenHooks(configDir, &token, func(content map[string]any) error {
+		if expired, _ := content["expired"].(bool); expired {
+			return &authretry.AuthRefreshRequired{Cause: rejection}
+		}
+		return nil
+	}))
+
+	var callTokens []string
+	runnerCallTool = func(client *transport.Client, _ context.Context, _, _ string, _ map[string]any) (transport.ToolCallResult, error) {
+		callTokens = append(callTokens, client.AuthToken)
+		if len(callTokens) == 1 {
+			return transport.ToolCallResult{Content: map[string]any{"expired": true}}, nil
+		}
+		return transport.ToolCallResult{Content: map[string]any{"value": "ok"}}, nil
+	}
+	refreshCalls := 0
+	runnerForceRefreshRejectedAccessToken = func(_ context.Context, gotDir, rejected string) (string, error) {
+		refreshCalls++
+		if gotDir != configDir || rejected != "old-access" {
+			t.Fatalf("refresh input = dir %q token %q", gotDir, rejected)
+		}
+		token = "new-access"
+		return token, nil
+	}
+
+	result, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if refreshCalls != 1 || len(callTokens) != 2 || callTokens[0] != "old-access" || callTokens[1] != "new-access" {
+		t.Fatalf("refreshes=%d call tokens=%v", refreshCalls, callTokens)
+	}
+	content, _ := result.Response["content"].(map[string]any)
+	if content["value"] != "ok" || content["success"] != true {
+		t.Fatalf("result content = %#v", content)
+	}
+}
+
+func TestCrossPlatformCoverageRunnerRefreshFailurePreservesBothCausesAndSafeLog(t *testing.T) {
+	installAuthRefreshRunnerSeams(t)
+	t.Setenv("DWS_DEBUG_AUTH", "1")
+	configDir := t.TempDir()
+	token := "old-access"
+	rejection := apperrors.NewAuth("server rejected access token", apperrors.WithReason("access_token_rejected"))
+	edition.Override(authRefreshTokenHooks(configDir, &token, func(map[string]any) error {
+		return &authretry.AuthRefreshRequired{Cause: rejection}
+	}))
+	runnerCallTool = func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+		return transport.ToolCallResult{Content: map[string]any{"expired": true}}, nil
+	}
+	refreshErr := errors.New(`oauth refresh response parse failed: body={"access_token":"access-token-secret","refresh_token":"refresh-token-secret","uid":"uid-secret-value"}`)
+	runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+		return "", refreshErr
+	}
+
+	var logs bytes.Buffer
+	previousLogger := slog.Default()
+	slog.SetDefault(slog.New(slog.NewJSONHandler(&logs, &slog.HandlerOptions{Level: slog.LevelDebug})))
+	t.Cleanup(func() { slog.SetDefault(previousLogger) })
+
+	_, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation())
+	if !errors.Is(err, rejection) || !errors.Is(err, refreshErr) {
+		t.Fatalf("error = %v, want rejection and refresh causes", err)
+	}
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Category != apperrors.CategoryAuth || typed.Reason != "auth_refresh_failed" || typed.Operation != "auth/token/refresh" {
+		t.Fatalf("refresh envelope = %#v", typed)
+	}
+	var rendered bytes.Buffer
+	if printErr := apperrors.PrintJSON(&rendered, err); printErr != nil {
+		t.Fatal(printErr)
+	}
+	for _, want := range []string{`"category": "auth"`, `"reason": "auth_refresh_failed"`, `"operation": "auth/token/refresh"`} {
+		if !strings.Contains(rendered.String(), want) {
+			t.Fatalf("structured stderr missing %s: %s", want, rendered.String())
+		}
+	}
+	for _, secret := range []string{"access-token-secret", "refresh-token-secret", "uid-secret-value"} {
+		if strings.Contains(err.Error(), secret) || strings.Contains(logs.String(), secret) || strings.Contains(rendered.String(), secret) {
+			t.Fatalf("auth output leaked %q: error=%q logs=%s stderr=%s", secret, err, logs.String(), rendered.String())
+		}
+	}
+	for _, want := range []string{"auth.runtime.refresh.failed", "auth.runtime.refresh.failed.detail", "force_refresh_rejected_token", "error_type"} {
+		if !strings.Contains(logs.String(), want) {
+			t.Fatalf("safe refresh log missing %q: %s", want, logs.String())
+		}
+	}
+}
+
+func TestCrossPlatformCoverageRunnerSecondEditionMarkerReturnsSecondCause(t *testing.T) {
+	installAuthRefreshRunnerSeams(t)
+	configDir := t.TempDir()
+	token := "old-access"
+	firstCause := errors.New("first rejection")
+	secondCause := errors.New("second rejection")
+	edition.Override(authRefreshTokenHooks(configDir, &token, func(content map[string]any) error {
+		attempt, _ := content["attempt"].(int)
+		if attempt == 1 {
+			return &authretry.AuthRefreshRequired{Cause: firstCause}
+		}
+		return &authretry.AuthRefreshRequired{Cause: secondCause}
+	}))
+	calls := 0
+	runnerCallTool = func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+		calls++
+		return transport.ToolCallResult{Content: map[string]any{"attempt": calls}}, nil
+	}
+	refreshCalls := 0
+	runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+		refreshCalls++
+		token = "new-access"
+		return token, nil
+	}
+
+	_, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation())
+	if !errors.Is(err, secondCause) || errors.Is(err, firstCause) {
+		t.Fatalf("error = %v, want only second rejection cause", err)
+	}
+	if calls != 2 || refreshCalls != 1 {
+		t.Fatalf("calls=%d refreshes=%d", calls, refreshCalls)
+	}
+}
+
+func TestCrossPlatformCoverageRunnerOnAuthErrorOnlyRetriesExactUnauthorized(t *testing.T) {
+	t.Run("http 401 marker retries once", func(t *testing.T) {
+		installAuthRefreshRunnerSeams(t)
+		configDir := t.TempDir()
+		token := "old-access"
+		rejection := errors.New("transport rejected token")
+		hookCalls := 0
+		hooks := authRefreshTokenHooks(configDir, &token, nil)
+		hooks.OnAuthError = func(string, error) error {
+			hookCalls++
+			return &authretry.AuthRefreshRequired{Cause: rejection}
+		}
+		edition.Override(hooks)
+		calls := 0
+		var callTokens []string
+		runnerCallTool = func(client *transport.Client, _ context.Context, _, _ string, _ map[string]any) (transport.ToolCallResult, error) {
+			calls++
+			callTokens = append(callTokens, client.AuthToken)
+			if calls == 1 {
+				return transport.ToolCallResult{}, apperrors.NewAuth("unauthorized", apperrors.WithReason("http_401"))
+			}
+			return transport.ToolCallResult{Content: map[string]any{"value": "ok"}}, nil
+		}
+		refreshCalls := 0
+		runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+			refreshCalls++
+			token = "new-access"
+			return token, nil
+		}
+
+		if _, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation()); err != nil {
+			t.Fatal(err)
+		}
+		if hookCalls != 1 || refreshCalls != 1 || calls != 2 || strings.Join(callTokens, ",") != "old-access,new-access" {
+			t.Fatalf("hook=%d refresh=%d calls=%d tokens=%v", hookCalls, refreshCalls, calls, callTokens)
+		}
+	})
+
+	for _, tc := range []struct {
+		name string
+		err  error
+	}{
+		{name: "http 403", err: apperrors.NewAuth("forbidden", apperrors.WithReason("http_403"))},
+		{name: "ordinary auth", err: apperrors.NewAuth("load failed", apperrors.WithReason("auth_load_failed"))},
+	} {
+		t.Run(tc.name+" does not enter hook", func(t *testing.T) {
+			installAuthRefreshRunnerSeams(t)
+			configDir := t.TempDir()
+			token := "old-access"
+			hookCalls := 0
+			hooks := authRefreshTokenHooks(configDir, &token, nil)
+			hooks.OnAuthError = func(string, error) error {
+				hookCalls++
+				return &authretry.AuthRefreshRequired{Cause: errors.New("must not run")}
+			}
+			edition.Override(hooks)
+			runnerCallTool = func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+				return transport.ToolCallResult{}, tc.err
+			}
+			refreshCalls := 0
+			runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+				refreshCalls++
+				return "", nil
+			}
+
+			_, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation())
+			if !errors.Is(err, tc.err) || hookCalls != 0 || refreshCalls != 0 {
+				t.Fatalf("error=%v hook=%d refresh=%d", err, hookCalls, refreshCalls)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageRunnerDoesNotRefreshExplicitTokenMarker(t *testing.T) {
+	installAuthRefreshRunnerSeams(t)
+	rejection := errors.New("explicit token rejected")
+	edition.Override(&edition.Hooks{ClassifyToolResult: func(map[string]any) error {
+		return &authretry.AuthRefreshRequired{Cause: rejection}
+	}})
+	calls := 0
+	runnerCallTool = func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+		calls++
+		return transport.ToolCallResult{Content: map[string]any{"expired": true}}, nil
+	}
+	refreshCalls := 0
+	runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+		refreshCalls++
+		return "", nil
+	}
+
+	_, err := authRefreshTestRunner(&GlobalFlags{Token: "explicit-token"}).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation())
+	if !errors.Is(err, rejection) || calls != 1 || refreshCalls != 0 {
+		t.Fatalf("error=%v calls=%d refresh=%d", err, calls, refreshCalls)
+	}
+}
+
+func TestCrossPlatformCoverageRunnerRetriesPreflightEditionMarkerOnce(t *testing.T) {
+	installAuthRefreshRunnerSeams(t)
+	configDir := t.TempDir()
+	token := "old-access"
+	rejection := errors.New("preflight token rejected")
+	edition.Override(authRefreshTokenHooks(configDir, &token, nil))
+	preflightCalls := 0
+	runnerPreflightDocDownload = func(*runtimeRunner, context.Context, *transport.Client, string, executor.Invocation) error {
+		preflightCalls++
+		if preflightCalls == 1 {
+			return &authretry.AuthRefreshRequired{Cause: rejection}
+		}
+		return nil
+	}
+	toolCalls := 0
+	runnerCallTool = func(*transport.Client, context.Context, string, string, map[string]any) (transport.ToolCallResult, error) {
+		toolCalls++
+		return transport.ToolCallResult{Content: map[string]any{"value": "ok"}}, nil
+	}
+	refreshCalls := 0
+	runnerForceRefreshRejectedAccessToken = func(context.Context, string, string) (string, error) {
+		refreshCalls++
+		token = "new-access"
+		return token, nil
+	}
+
+	if _, err := authRefreshTestRunner(nil).executeInvocation(context.Background(), "https://example.test", authRefreshTestInvocation()); err != nil {
+		t.Fatal(err)
+	}
+	if preflightCalls != 2 || toolCalls != 1 || refreshCalls != 1 {
+		t.Fatalf("preflights=%d tools=%d refreshes=%d", preflightCalls, toolCalls, refreshCalls)
+	}
+}

internal/app/auth_registry_test.go

@@ -1,213 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package app
-
-import (
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
-)
-
-func TestPluginAuthRegistry(t *testing.T) {
-	// Clean up after test
-	defer func() {
-		pluginAuthMu.Lock()
-		delete(pluginAuthRegistry, "test-product")
-		pluginAuthMu.Unlock()
-	}()
-
-	// Initially not found
-	if _, ok := LookupPluginAuth("test-product"); ok {
-		t.Error("expected LookupPluginAuth to return false for unregistered product")
-	}
-
-	// Register auth credentials
-	auth := &PluginAuth{
-		Token:          "sk-test-token-12345",
-		ExtraHeaders:   map[string]string{"X-Custom": "value"},
-		TrustedDomains: []string{"api.example.com", "*.example.com"},
-	}
-	RegisterPluginAuth("test-product", auth)
-
-	// Now should be found
-	got, ok := LookupPluginAuth("test-product")
-	if !ok {
-		t.Fatal("expected LookupPluginAuth to return true after registration")
-	}
-	if got != auth {
-		t.Error("LookupPluginAuth returned different auth instance")
-	}
-	if got.Token != "sk-test-token-12345" {
-		t.Errorf("Token = %q, want sk-test-token-12345", got.Token)
-	}
-	if got.ExtraHeaders["X-Custom"] != "value" {
-		t.Errorf("ExtraHeaders[X-Custom] = %q, want value", got.ExtraHeaders["X-Custom"])
-	}
-	if len(got.TrustedDomains) != 2 {
-		t.Errorf("TrustedDomains len = %d, want 2", len(got.TrustedDomains))
-	}
-}
-
-func TestPluginAuthRegistryIsolation(t *testing.T) {
-	// Clean up after test
-	defer func() {
-		pluginAuthMu.Lock()
-		delete(pluginAuthRegistry, "product-a")
-		delete(pluginAuthRegistry, "product-b")
-		pluginAuthMu.Unlock()
-	}()
-
-	authA := &PluginAuth{Token: "token-a"}
-	authB := &PluginAuth{Token: "token-b"}
-
-	RegisterPluginAuth("product-a", authA)
-	RegisterPluginAuth("product-b", authB)
-
-	gotA, okA := LookupPluginAuth("product-a")
-	gotB, okB := LookupPluginAuth("product-b")
-
-	if !okA || !okB {
-		t.Fatal("expected both products to be registered")
-	}
-	if gotA.Token != "token-a" {
-		t.Errorf("product-a Token = %q, want token-a", gotA.Token)
-	}
-	if gotB.Token != "token-b" {
-		t.Errorf("product-b Token = %q, want token-b", gotB.Token)
-	}
-}
-
-func TestDeriveToolCLIName(t *testing.T) {
-	tests := []struct {
-		input string
-		want  string
-	}{
-		{"web_search", "web-search"},
-		{"maps.search_poi", "search-poi"},
-		{"maps.geo", "geo"},
-		{"simple", "simple"},
-		{"a.b.deep_nested_name", "deep-nested-name"},
-		{"already-kebab", "already-kebab"},
-	}
-	for _, tt := range tests {
-		t.Run(tt.input, func(t *testing.T) {
-			got := deriveToolCLIName(tt.input)
-			if got != tt.want {
-				t.Errorf("deriveToolCLIName(%q) = %q, want %q", tt.input, got, tt.want)
-			}
-		})
-	}
-}
-
-func TestRegisterPluginAuthFromHeaders(t *testing.T) {
-	// Clean up after test
-	defer func() {
-		pluginAuthMu.Lock()
-		delete(pluginAuthRegistry, "test-srv")
-		pluginAuthMu.Unlock()
-	}()
-
-	srv := market.ServerDescriptor{
-		Key:      "test-srv",
-		Endpoint: "https://api.example.com/mcp/v1",
-		CLI:      market.CLIOverlay{ID: "test-srv", Command: "test-srv"},
-		AuthHeaders: map[string]string{
-			"Authorization": "Bearer sk-my-secret-key",
-			"X-Custom":      "custom-value",
-		},
-	}
-
-	registerPluginAuthFromHeaders(srv)
-
-	auth, ok := LookupPluginAuth("test-srv")
-	if !ok {
-		t.Fatal("expected auth to be registered after registerPluginAuthFromHeaders")
-	}
-	if auth.Token != "sk-my-secret-key" {
-		t.Errorf("Token = %q, want sk-my-secret-key", auth.Token)
-	}
-	if auth.ExtraHeaders["X-Custom"] != "custom-value" {
-		t.Errorf("ExtraHeaders[X-Custom] = %q, want custom-value", auth.ExtraHeaders["X-Custom"])
-	}
-	if len(auth.TrustedDomains) != 2 {
-		t.Fatalf("TrustedDomains len = %d, want 2", len(auth.TrustedDomains))
-	}
-	if auth.TrustedDomains[0] != "api.example.com" {
-		t.Errorf("TrustedDomains[0] = %q, want api.example.com", auth.TrustedDomains[0])
-	}
-}
-
-func TestRegisterPluginAuthFromHeadersNoAuth(t *testing.T) {
-	srv := market.ServerDescriptor{
-		Key:      "no-auth-srv",
-		Endpoint: "https://api.example.com/mcp/v1",
-		CLI:      market.CLIOverlay{ID: "no-auth-srv"},
-		AuthHeaders: map[string]string{
-			"X-Custom": "custom-value",
-		},
-	}
-
-	registerPluginAuthFromHeaders(srv)
-
-	// Should not register because there's no Authorization header
-	if _, ok := LookupPluginAuth("no-auth-srv"); ok {
-		t.Error("expected no auth registration when Authorization header is missing")
-	}
-}
-
-func TestBuildPluginAuthClient(t *testing.T) {
-	base := transport.NewClient(nil)
-
-	srv := market.ServerDescriptor{
-		Endpoint: "https://dashscope.aliyuncs.com/compatible-mode/v1/mcp",
-		AuthHeaders: map[string]string{
-			"Authorization": "Bearer sk-test-api-key",
-			"X-Extra":       "extra-value",
-		},
-	}
-
-	client := buildPluginAuthClient(base, srv)
-
-	// Should return a different client instance
-	if client == base {
-		t.Error("expected buildPluginAuthClient to return a new client, not the base")
-	}
-
-	// Verify trusted domains
-	if len(client.TrustedDomains) != 2 {
-		t.Fatalf("TrustedDomains len = %d, want 2", len(client.TrustedDomains))
-	}
-	if client.TrustedDomains[0] != "dashscope.aliyuncs.com" {
-		t.Errorf("TrustedDomains[0] = %q, want dashscope.aliyuncs.com", client.TrustedDomains[0])
-	}
-}
-
-func TestBuildPluginAuthClientNoAuth(t *testing.T) {
-	base := transport.NewClient(nil)
-
-	srv := market.ServerDescriptor{
-		Endpoint: "https://api.example.com/mcp/v1",
-		AuthHeaders: map[string]string{
-			"X-Custom": "custom-value",
-		},
-	}
-
-	client := buildPluginAuthClient(base, srv)
-
-	// Should return the base client when no Authorization header
-	if client != base {
-		t.Error("expected buildPluginAuthClient to return base client when no Authorization header")
-	}
-}

internal/app/cache_command.go

@@ -0,0 +1,76 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+type cacheCompatNotice struct {
+	Status      string `json:"status"`
+	Command     string `json:"command"`
+	Message     string `json:"message"`
+	Replacement string `json:"replacement,omitempty"`
+}
+
+func newCacheCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:               "cache",
+		Short:             "服务发现缓存兼容入口（静态端点模式已弃用）",
+		Hidden:            true,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return cmd.Help()
+		},
+	}
+	for _, name := range []string{"refresh", "status", "clean"} {
+		sub := &cobra.Command{
+			Use:               name,
+			Short:             "已弃用：静态端点模式无需服务发现缓存",
+			Args:              cobra.NoArgs,
+			DisableAutoGenTag: true,
+			RunE: func(cmd *cobra.Command, args []string) error {
+				return printCacheCompatNotice(cmd, name)
+			},
+		}
+		cmd.AddCommand(sub)
+	}
+	return cmd
+}
+
+func printCacheCompatNotice(cmd *cobra.Command, command string) error {
+	notice := cacheCompatNotice{
+		Status:      "deprecated",
+		Command:     "dws cache " + command,
+		Message:     "服务发现已下线，当前版本使用编译期静态端点目录；dws cache 仅保留为兼容入口，不会刷新端点。",
+		Replacement: "如遇 endpoint_not_resolved，请先执行 dws upgrade 获取包含最新 internal/syncdata 端点的版本；仍失败时检查 internal/syncdata.StaticServers() 是否覆盖目标 product/server。",
+	}
+	format, _ := cmd.Root().PersistentFlags().GetString("format")
+	switch strings.ToLower(strings.TrimSpace(format)) {
+	case "", "json":
+		return json.NewEncoder(cmd.OutOrStdout()).Encode(notice)
+	case "pretty":
+		data, _ := json.MarshalIndent(notice, "", "  ")
+		var err error
+		_, err = fmt.Fprintln(cmd.OutOrStdout(), string(data))
+		return err
+	default:
+		_, err := fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n%s\n", notice.Command, notice.Message, notice.Replacement)
+		return err
+	}
+}

internal/app/canonical_panic_fallback_test.go

@@ -1,157 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package app
-
-import (
-	"context"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cache"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/pipeline"
-	"github.com/spf13/cobra"
-)
-
-// TestNewMCPCommandPanicDegradesToStub verifies the canonical-tree guard:
-// the `dws mcp` build runs BEFORE the legacy build and used to sit outside
-// every poisoned-cache guard, so a panic there (e.g. a tool schema property
-// named after the reserved --params flag) aborted every invocation. With no
-// on-disk cache to quarantine it must degrade to an inert stub instead.
-func TestNewMCPCommandPanicDegradesToStub(t *testing.T) {
-	t.Setenv(cli.CacheDirEnv, t.TempDir())
-
-	calls := 0
-	orig := buildMCPCommandFn
-	buildMCPCommandFn = func(context.Context, cli.CatalogLoader, executor.Runner, *pipeline.Engine) *cobra.Command {
-		calls++
-		panic("chat_permission_grant flag redefined: params")
-	}
-	t.Cleanup(func() { buildMCPCommandFn = orig })
-
-	var cmd *cobra.Command
-	captured := captureStderr(t, func() {
-		cmd = newMCPCommand(context.Background(), nil, nil, nil)
-	})
-
-	if cmd == nil || cmd.Name() != "mcp" {
-		t.Fatalf("newMCPCommand() = %v after build panic, want an 'mcp' stub", cmd)
-	}
-	if err := cmd.RunE(cmd, nil); err == nil || !strings.Contains(err.Error(), "dws cache refresh") {
-		t.Errorf("stub RunE error = %v, want a 'dws cache refresh' hint", err)
-	}
-	if !strings.Contains(captured, "dws cache refresh") {
-		t.Errorf("stderr = %q, want a hint mentioning 'dws cache refresh'", captured)
-	}
-	if calls != 1 {
-		t.Errorf("canonical build attempts = %d, want 1 (no cache on disk, nothing to quarantine and retry)", calls)
-	}
-}
-
-// TestNewMCPCommandSelfHealsPoisonedCache verifies the self-heal path: when
-// the build panics AND a discovery cache exists on disk, the partition is
-// quarantined and the build retried once, so a fixed binary escapes the
-// lock-out with zero manual cache surgery.
-func TestNewMCPCommandSelfHealsPoisonedCache(t *testing.T) {
-	tmp := t.TempDir()
-	t.Setenv(cli.CacheDirEnv, tmp)
-
-	store := cache.NewStore(tmp)
-	if err := store.SaveTools(editionPartition(), "poisoned-server", cache.ToolsSnapshot{ServerKey: "poisoned-server"}); err != nil {
-		t.Fatalf("SaveTools() error = %v", err)
-	}
-
-	calls := 0
-	orig := buildMCPCommandFn
-	buildMCPCommandFn = func(context.Context, cli.CatalogLoader, executor.Runner, *pipeline.Engine) *cobra.Command {
-		calls++
-		if calls == 1 {
-			panic("chat_permission_grant flag redefined: params")
-		}
-		return &cobra.Command{Use: "mcp", Short: "rebuilt-probe"}
-	}
-	t.Cleanup(func() { buildMCPCommandFn = orig })
-
-	var cmd *cobra.Command
-	captured := captureStderr(t, func() {
-		cmd = newMCPCommand(context.Background(), nil, nil, nil)
-	})
-
-	if calls != 2 {
-		t.Fatalf("canonical build attempts = %d, want 2 (initial + retry after quarantine)", calls)
-	}
-	if cmd == nil || cmd.Short != "rebuilt-probe" {
-		t.Errorf("newMCPCommand() did not return the rebuilt tree, got %v", cmd)
-	}
-	quarantines, _ := filepath.Glob(filepath.Join(tmp, "*.quarantined"))
-	if len(quarantines) != 1 {
-		t.Fatalf("quarantine dirs = %v, want exactly 1", quarantines)
-	}
-	if !strings.Contains(captured, "rebuilding from a fresh fetch") {
-		t.Errorf("stderr = %q, want a note about rebuilding from a fresh fetch", captured)
-	}
-}
-
-// TestNewMCPCommandSecondPanicDegradesToStub verifies the final safety net:
-// if the rebuild after quarantine panics again, the stub is returned and the
-// `dws cache refresh` hint kept.
-func TestNewMCPCommandSecondPanicDegradesToStub(t *testing.T) {
-	tmp := t.TempDir()
-	t.Setenv(cli.CacheDirEnv, tmp)
-
-	store := cache.NewStore(tmp)
-	if err := store.SaveTools(editionPartition(), "poisoned-server", cache.ToolsSnapshot{ServerKey: "poisoned-server"}); err != nil {
-		t.Fatalf("SaveTools() error = %v", err)
-	}
-
-	calls := 0
-	orig := buildMCPCommandFn
-	buildMCPCommandFn = func(context.Context, cli.CatalogLoader, executor.Runner, *pipeline.Engine) *cobra.Command {
-		calls++
-		panic("chat_permission_grant flag redefined: params")
-	}
-	t.Cleanup(func() { buildMCPCommandFn = orig })
-
-	var cmd *cobra.Command
-	captured := captureStderr(t, func() {
-		cmd = newMCPCommand(context.Background(), nil, nil, nil)
-	})
-
-	if calls != 2 {
-		t.Fatalf("canonical build attempts = %d, want 2 (initial + retry after quarantine)", calls)
-	}
-	if cmd == nil || cmd.Name() != "mcp" {
-		t.Fatalf("newMCPCommand() = %v after repeated panics, want an 'mcp' stub", cmd)
-	}
-	if !strings.Contains(captured, "dws cache refresh") {
-		t.Errorf("stderr = %q, want a hint mentioning 'dws cache refresh'", captured)
-	}
-}
-
-// TestNewMCPCommandNoPanicKeepsCanonicalPath ensures the guard is transparent
-// on the happy path.
-func TestNewMCPCommandNoPanicKeepsCanonicalPath(t *testing.T) {
-	orig := buildMCPCommandFn
-	buildMCPCommandFn = func(context.Context, cli.CatalogLoader, executor.Runner, *pipeline.Engine) *cobra.Command {
-		return &cobra.Command{Use: "mcp", Short: "canonical-probe"}
-	}
-	t.Cleanup(func() { buildMCPCommandFn = orig })
-
-	cmd := newMCPCommand(context.Background(), nil, nil, nil)
-	if cmd == nil || cmd.Short != "canonical-probe" {
-		t.Errorf("newMCPCommand() lost the canonical command, got %v", cmd)
-	}
-}

internal/app/catalog_command.go

@@ -1,203 +1,19 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
 package app
 
 import (
-	"encoding/json"
-	"os"
-	"strings"
-
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/ir"
 	"github.com/spf13/cobra"
 )
 
-// toolMappingParam 描述一个 MCP 参数到 CLI flag + 中文友好名的映射。
-type toolMappingParam struct {
-	Flag  string `json:"flag"`
-	Label string `json:"label"`
-	Type  string `json:"type,omitempty"`
-}
-
-// toolMappingEntry 是单个 MCP 工具的映射条目。key 用 RPCName，对齐 SLS 日志的 tool 字段。
-type toolMappingEntry struct {
-	Product     string                      `json:"product"`
-	CLICommand  string                      `json:"cliCommand"`
-	DisplayName string                      `json:"displayName"`
-	Params      map[string]toolMappingParam `json:"params,omitempty"`
-}
-
-// toolMapping 是给开放平台日志页渲染用的全量映射契约。
-type toolMapping struct {
-	Version string                      `json:"version"`
-	Count   int                         `json:"count"`
-	Tools   map[string]toolMappingEntry `json:"tools"`
-}
-
-// newCatalogCommand 提供 `dws catalog export`：把已发现的工具目录投影成
-// tool→指令 映射 JSON，供开放平台 MCP/DWS 日志页把 tool/args 渲染成中文友好名。
-// 复用 root 注入的带 auth 的 loader（缓存优先；建议先 `dws cache refresh`）。
-func newCatalogCommand(loader cli.CatalogLoader) *cobra.Command {
-	catalogCmd := &cobra.Command{
-		Use:    "catalog",
-		Short:  "导出已发现的工具目录（内部用）",
-		Hidden: true,
-	}
-
-	var out string
-	var version string
-	exportCmd := &cobra.Command{
-		Use:   "export",
-		Short: "导出 tool→指令 映射 JSON（供开放平台日志页渲染）",
-		Args:  cobra.NoArgs,
+func newCatalogCommand(_ cli.CatalogLoader) *cobra.Command {
+	return &cobra.Command{
+		Use:               "catalog",
+		Short:             "查看服务目录 (静态端点模式)",
+		Hidden:            true,
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			catalog, err := loader.Load(cmd.Context())
-			if err != nil {
-				return err
-			}
-			mapping := projectToolMapping(catalog, version)
-			data, err := json.MarshalIndent(mapping, "", "  ")
-			if err != nil {
-				return err
-			}
-			data = append(data, '\n')
-			if strings.TrimSpace(out) == "" {
-				_, werr := os.Stdout.Write(data)
-				return werr
-			}
-			return os.WriteFile(out, data, 0o644)
+			return cmd.Help()
 		},
 	}
-	exportCmd.Flags().StringVar(&out, "out", "", "输出文件路径（默认 stdout）")
-	exportCmd.Flags().StringVar(&version, "version", "dev", "版本号标记")
-
-	catalogCmd.AddCommand(exportCmd)
-	return catalogCmd
-}
-
-// projectToolMapping 把 ir.Catalog 投影成 toolMapping 契约。
-func projectToolMapping(catalog ir.Catalog, version string) toolMapping {
-	mapping := toolMapping{Version: version, Tools: make(map[string]toolMappingEntry)}
-	for _, product := range catalog.Products {
-		command := ""
-		if product.CLI != nil {
-			command = strings.TrimSpace(product.CLI.Command)
-		}
-		if command == "" {
-			command = product.ID
-		}
-		for _, tool := range product.Tools {
-			if tool.Hidden {
-				continue
-			}
-			entry := toolMappingEntry{
-				Product:     command,
-				CLICommand:  tmBuildCLICommand(command, tool),
-				DisplayName: tmFirstNonEmpty(tool.Title, tmFirstNonEmpty(tmFirstLine(tool.Description), tool.RPCName)),
-				Params:      make(map[string]toolMappingParam),
-			}
-			for name, raw := range tmSchemaProperties(tool.InputSchema) {
-				prop, _ := raw.(map[string]any)
-				overlay, hasOverlay := tool.FlagOverlay[name]
-				if hasOverlay && overlay.Hidden {
-					continue
-				}
-				flag := tmKebab(name)
-				if hasOverlay && strings.TrimSpace(overlay.Alias) != "" {
-					flag = strings.TrimSpace(overlay.Alias)
-				}
-				label := tmMapStr(prop, "title")
-				if label == "" {
-					label = tmFirstLine(tmMapStr(prop, "description"))
-				}
-				entry.Params[name] = toolMappingParam{
-					Flag:  flag,
-					Label: label,
-					Type:  tmMapStr(prop, "type"),
-				}
-			}
-			if len(entry.Params) == 0 {
-				entry.Params = nil
-			}
-			mapping.Tools[tool.RPCName] = entry
-		}
-	}
-	mapping.Count = len(mapping.Tools)
-	return mapping
-}
-
-// tmBuildCLICommand 拼出 CLI 命令路径，如 chat + message + list -> "chat message list"。
-func tmBuildCLICommand(command string, tool ir.ToolDescriptor) string {
-	parts := make([]string, 0, 3)
-	if command != "" {
-		parts = append(parts, command)
-	}
-	if g := strings.TrimSpace(tool.Group); g != "" {
-		parts = append(parts, g)
-	}
-	name := strings.TrimSpace(tool.CLIName)
-	if name == "" {
-		name = tool.RPCName
-	}
-	parts = append(parts, name)
-	return strings.Join(parts, " ")
-}
-
-func tmSchemaProperties(schema map[string]any) map[string]any {
-	if schema == nil {
-		return nil
-	}
-	props, _ := schema["properties"].(map[string]any)
-	return props
-}
-
-func tmMapStr(m map[string]any, key string) string {
-	if m == nil {
-		return ""
-	}
-	s, _ := m[key].(string)
-	return strings.TrimSpace(s)
-}
-
-// tmFirstLine 取第一句中文/换行前的片段，作为长描述的短标签兜底。
-func tmFirstLine(s string) string {
-	s = strings.TrimSpace(s)
-	if i := strings.IndexAny(s, "\n。"); i >= 0 {
-		return strings.TrimSpace(s[:i])
-	}
-	return s
-}
-
-func tmFirstNonEmpty(a, b string) string {
-	if strings.TrimSpace(a) != "" {
-		return strings.TrimSpace(a)
-	}
-	return strings.TrimSpace(b)
-}
-
-// tmKebab 把 camelCase 参数名转 kebab-case 作为默认 flag。
-func tmKebab(s string) string {
-	var b strings.Builder
-	for i, r := range s {
-		if r >= 'A' && r <= 'Z' {
-			if i > 0 {
-				b.WriteByte('-')
-			}
-			b.WriteRune(r - 'A' + 'a')
-			continue
-		}
-		b.WriteRune(r)
-	}
-	return b.String()
 }

internal/app/config.go

@@ -33,8 +33,11 @@ func init() {
 
 // Build-time variables injected via ldflags when available.
 var (
-	buildTime = "unknown"
-	gitCommit = "unknown"
+	buildTime       = "unknown"
+	gitCommit       = "unknown"
+	userHomeDir     = os.UserHomeDir
+	executablePath  = os.Executable
+	evaluateSymlink = filepath.EvalSymlinks
 )
 
 func defaultConfigDir() string {
@@ -44,7 +47,7 @@ func defaultConfigDir() string {
 	if fn := edition.Get().ConfigDir; fn != nil {
 		return fn()
 	}
-	homeDir, err := os.UserHomeDir()
+	homeDir, err := userHomeDir()
 	if err != nil {
 		return exeRelativeConfigDir()
 	}
@@ -52,11 +55,11 @@ func defaultConfigDir() string {
 }
 
 func exeRelativeConfigDir() string {
-	exePath, err := os.Executable()
+	exePath, err := executablePath()
 	if err != nil {
 		return ".dws"
 	}
-	realPath, err := filepath.EvalSymlinks(exePath)
+	realPath, err := evaluateSymlink(exePath)
 	if err != nil {
 		realPath = exePath
 	}

internal/app/config_test.go

@@ -7,7 +7,9 @@ import (
 
 func TestDefaultConfigDirUsesHomeDirectoryInOSSMode(t *testing.T) {
 	homeDir := filepath.Join(t.TempDir(), "home")
-	t.Setenv("HOME", homeDir)
+	originalUserHomeDir := userHomeDir
+	userHomeDir = func() (string, error) { return homeDir, nil }
+	t.Cleanup(func() { userHomeDir = originalUserHomeDir })
 	t.Setenv("DWS_CONFIG_DIR", "")
 
 	got := defaultConfigDir()

internal/app/coverage_more_test.go

@@ -0,0 +1,308 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/apiclient"
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+func appRPCServer(t *testing.T, initOK, listOK bool) *httptest.Server {
+	t.Helper()
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req struct {
+			ID     int    `json:"id"`
+			Method string `json:"method"`
+		}
+		_ = json.NewDecoder(r.Body).Decode(&req)
+		w.Header().Set("Content-Type", "application/json")
+		switch req.Method {
+		case "initialize":
+			if !initOK {
+				_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": req.ID, "error": map[string]any{"code": -32601, "message": "init"}})
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": req.ID, "result": map[string]any{"protocolVersion": "2025-03-26"}})
+		case "tools/list":
+			if !listOK {
+				_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": req.ID, "error": map[string]any{"code": -1, "message": "list"}})
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"jsonrpc": "2.0",
+				"id":      req.ID,
+				"result": map[string]any{
+					"tools": []any{map[string]any{
+						"name":        "tool",
+						"description": "desc",
+						"inputSchema": map[string]any{
+							"properties": map[string]any{"id": map[string]any{"type": "string"}},
+							"required":   []any{"id", 1, ""},
+						},
+					}},
+				},
+			})
+		default:
+			_ = json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": req.ID, "result": map[string]any{}})
+		}
+	}))
+}
+
+func TestCrossPlatformCoveragePluginAuthCoverage(t *testing.T) {
+	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "fallback", Endpoint: "%", AuthHeaders: map[string]string{"Authorization": "token"}})
+	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "server", Endpoint: "https://x.test", CLI: mcptypes.CLIOverlay{ID: "cli"}, AuthHeaders: map[string]string{"Authorization": "Bearer token", "X": "Y"}})
+	registerPluginAuthFromHeaders(mcptypes.ServerDescriptor{Key: "none"})
+	if got, ok := LookupPluginAuth("cli"); !ok || got == nil || got.Token != "token" {
+		t.Fatalf("registered plugin auth = %#v, %v", got, ok)
+	}
+}
+
+func TestCrossPlatformCoverageRawAPIAndTokenCoverage(t *testing.T) {
+	oldProvider := newAccessTokenProvider
+	oldManager := newLegacyTokenManager
+	t.Cleanup(func() {
+		newAccessTokenProvider = oldProvider
+		newLegacyTokenManager = oldManager
+	})
+	cmd := &cobra.Command{Use: "api"}
+	var out, errOut bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetErr(&errOut)
+	cmd.SetContext(context.Background())
+
+	invalid := []struct {
+		args []string
+		gf   GlobalFlags
+		af   apiFlags
+	}{
+		{[]string{"GET", "/x?a=1"}, GlobalFlags{}, apiFlags{}},
+		{[]string{"TRACE", "/x"}, GlobalFlags{}, apiFlags{}},
+		{[]string{"GET", "../x"}, GlobalFlags{}, apiFlags{}},
+		{[]string{"GET", "/x"}, GlobalFlags{}, apiFlags{params: "x\x00"}},
+		{[]string{"POST", "/x"}, GlobalFlags{}, apiFlags{data: "x\x00"}},
+		{[]string{"POST", "/x"}, GlobalFlags{}, apiFlags{params: "-", data: "-"}},
+		{[]string{"GET", "/x"}, GlobalFlags{Output: "x"}, apiFlags{pageAll: true}},
+		{[]string{"GET", "/x"}, GlobalFlags{}, apiFlags{params: "{"}},
+		{[]string{"POST", "/x"}, GlobalFlags{}, apiFlags{data: "{"}},
+		{[]string{"GET", "https://evil.test/x"}, GlobalFlags{Token: "t"}, apiFlags{}},
+	}
+	for _, tc := range invalid {
+		if err := runAPI(cmd, tc.args, &tc.gf, &tc.af); err == nil {
+			t.Fatalf("invalid API %#v succeeded", tc)
+		}
+	}
+	for _, raw := range []string{"", "a=1&empty=&=x", "a=1&b=2"} {
+		if got := parseQueryStringToJSON(raw); got == "" {
+			t.Fatalf("query JSON %q empty", raw)
+		}
+	}
+	if got, err := resolveRawAPIToken(context.Background(), " token "); err != nil || got != "token" {
+		t.Fatalf("explicit raw token = %q, %v", got, err)
+	}
+	authpkg.SetClientID("")
+	authpkg.SetClientSecret("")
+	if _, err := resolveRawAPIToken(context.Background(), ""); err == nil {
+		t.Fatal("missing app credentials succeeded")
+	}
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		if strings.Contains(r.URL.Path, "fail") {
+			w.WriteHeader(http.StatusInternalServerError)
+			_, _ = io.WriteString(w, `{"error":"bad"}`)
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{"items": []any{1}, "hasMore": false})
+	}))
+	defer server.Close()
+	host := strings.TrimPrefix(server.URL, "http://")
+	host = strings.Split(host, ":")[0]
+	apiclient.AllowedHosts[host] = true
+	t.Cleanup(func() { delete(apiclient.AllowedHosts, host) })
+	gf := &GlobalFlags{Token: "token", DryRun: true, Format: "json", Timeout: 1}
+	af := &apiFlags{baseURL: server.URL}
+	if err := runAPI(cmd, []string{"GET", "/ok"}, gf, af); err != nil || out.Len() == 0 {
+		t.Fatalf("API dry run = %q, %v", out.String(), err)
+	}
+	out.Reset()
+	gf.DryRun = false
+	if err := runAPI(cmd, []string{"GET", "/ok"}, gf, af); err != nil || out.Len() == 0 {
+		t.Fatalf("API request = %q, %v", out.String(), err)
+	}
+	out.Reset()
+	af.pageAll = true
+	if err := runAPI(cmd, []string{"GET", "/ok"}, gf, af); err != nil || out.Len() == 0 {
+		t.Fatalf("API pagination = %q, %v", out.String(), err)
+	}
+	client := apiclient.NewClient("token", server.URL)
+	if err := runPaginated(context.Background(), client, apiclient.RawAPIRequest{Method: "GET", Path: "/fail"}, &apiFlags{}, apiclient.ResponseOptions{Out: io.Discard, ErrOut: io.Discard}); err == nil {
+		t.Fatal("failed pagination succeeded")
+	}
+
+	if _, err := ResolveAuxiliaryAccessToken(context.Background(), "", ""); err == nil {
+		t.Fatal("empty auxiliary config succeeded")
+	}
+	if got, err := ResolveAuxiliaryAccessToken(context.Background(), "ignored", " explicit "); err != nil || got != "explicit" {
+		t.Fatalf("explicit auxiliary token = %q, %v", got, err)
+	}
+	dir := t.TempDir()
+	newAccessTokenProvider = func(string) accessTokenGetter { return fakeAccessTokenGetter{token: "saved"} }
+	newLegacyTokenManager = func(string) legacyTokenGetter { return fakeLegacyTokenGetter{} }
+	if got, err := resolveAccessTokenFromDir(context.Background(), dir); err != nil || got != "saved" {
+		t.Fatalf("saved access token = %q, %v", got, err)
+	}
+	newAccessTokenProvider = func(string) accessTokenGetter { return fakeAccessTokenGetter{} }
+	missing := t.TempDir()
+	if got, err := resolveAccessTokenFromDir(context.Background(), missing); got != "" || !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		t.Fatalf("missing access token = %q, %v", got, err)
+	}
+	if _, err := ResolveAuxiliaryAccessToken(context.Background(), missing, ""); err == nil {
+		t.Fatal("missing auxiliary credentials succeeded")
+	}
+	if _, err := ForceRefreshAccessToken(context.Background(), ""); err == nil {
+		t.Fatal("empty force refresh config succeeded")
+	}
+	if _, err := ForceRefreshAccessToken(context.Background(), missing); err == nil {
+		t.Fatal("missing force refresh token succeeded")
+	}
+}
+
+func TestCrossPlatformCoverageRootUtilityAndTimingCoverage(t *testing.T) {
+	_ = resolveVerbosity(nil)
+	for _, flags := range []struct {
+		debug   bool
+		verbose bool
+		format  string
+		json    bool
+	}{{}, {verbose: true}, {debug: true}, {format: "json"}, {format: "table"}, {json: true}} {
+		flagCmd := &cobra.Command{Use: "flags"}
+		flagCmd.Flags().Bool("debug", flags.debug, "")
+		flagCmd.Flags().Bool("verbose", flags.verbose, "")
+		flagCmd.Flags().String("format", flags.format, "")
+		flagCmd.Flags().Bool("json", false, "")
+		if flags.json {
+			_ = flagCmd.Flags().Set("json", "true")
+		}
+		_ = resolveVerbosity(flagCmd)
+		_ = commandRequestsJSONErrors(flagCmd)
+		_ = wantsJSONErrors(flagCmd)
+	}
+	_ = commandRequestsJSONErrors(nil)
+	_ = wantsJSONErrors(nil)
+	if got, changed := normalizeProfileFlagArgs([]string{"--profile", "a,", "b"}); !changed || len(got) == 0 {
+		t.Fatalf("profile args = %#v, %v", got, changed)
+	}
+	if _, changed := normalizeProfileFlagArgs([]string{"--profile"}); changed {
+		t.Fatal("incomplete profile flag changed")
+	}
+	if preparseProfileFlag([]string{"--profile=a"}) != "a" || preparseProfileFlag([]string{"--profile", "b"}) != "b" || preparseProfileFlag(nil) != "" {
+		t.Fatal("profile preparse mismatch")
+	}
+	if !argsChanged([]string{"a"}, []string{"b"}) || argsChanged([]string{"a"}, []string{"a"}) {
+		t.Fatal("argsChanged mismatch")
+	}
+	cmd := &cobra.Command{Use: "root"}
+	cmd.SetContext(context.Background())
+	cmd.Flags().String("output", "", "")
+	if err := configureOutputSink(cmd); err != nil {
+		t.Fatal(err)
+	}
+	path := filepath.Join(t.TempDir(), "nested", "out.txt")
+	_ = cmd.Flags().Set("output", path)
+	if err := configureOutputSink(cmd); err != nil {
+		t.Fatal(err)
+	}
+	_, _ = io.WriteString(cmd.OutOrStdout(), "data")
+	if err := closeOutputSink(cmd); err != nil {
+		t.Fatal(err)
+	}
+	local := &cobra.Command{Use: "local"}
+	local.SetContext(context.Background())
+	local.SetOut(io.Discard)
+	local.Flags().String("output", "", "")
+	if err := configureOutputSink(local); err != nil {
+		t.Fatal(err)
+	}
+	if err := validateOptionalPath("--x", ""); err != nil {
+		t.Fatal(err)
+	}
+	if err := validateOptionalPath("--x", "bad\x00path"); err == nil {
+		t.Fatal("unsafe path succeeded")
+	}
+
+	root := &cobra.Command{Use: "root", Short: "root"}
+	bindPersistentFlags(root, &GlobalFlags{})
+	root.AddCommand(&cobra.Command{Use: "alpha", Short: "alpha"}, &cobra.Command{Use: "hidden", Hidden: true})
+	configureRootHelp(root)
+	var help bytes.Buffer
+	root.SetOut(&help)
+	_ = root.Help()
+	renderRootGlobalFlags(root)
+	_ = visiblePersistentFlags(root)
+	for _, command := range root.Commands() {
+		_ = commandShort(command)
+	}
+	_ = visibleMCPRootCommands(root)
+	_ = visibleUtilityRootCommands(root)
+
+	tc := NewTimingCollector()
+	tc.Record("a", time.Microsecond)
+	tc.Record("b", 2*time.Second)
+	for _, d := range []time.Duration{time.Nanosecond, time.Microsecond, time.Millisecond, time.Second} {
+		_ = formatDuration(d)
+	}
+	for _, debug := range []bool{false, true} {
+		if debug {
+			t.Setenv(PerfDebugEnv, "1")
+		} else {
+			t.Setenv(PerfDebugEnv, "")
+		}
+		tc.PrintIfEnabled()
+	}
+	var timingOut bytes.Buffer
+	tc.Print(&timingOut)
+	if timingOut.Len() == 0 {
+		t.Fatal("timing output empty")
+	}
+	t.Setenv("HOME", t.TempDir())
+	if defaultPerfReportPath() == "" {
+		t.Fatal("default perf path empty")
+	}
+	t.Setenv(PerfReportEnv, "auto")
+	tc.WriteReportIfEnabled("v", "cmd")
+	if _, err := LoadLatestReport(); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv(PerfReportEnv, "")
+	tc.WriteReportIfEnabled("v", "cmd")
+	_ = exeRelativeConfigDir()
+
+	merged := mergeTopLevelCommands([]*cobra.Command{{Use: "a"}, {Use: "a"}, {Use: "b"}, nil})
+	if len(merged) != 2 {
+		t.Fatalf("merged commands = %#v", merged)
+	}
+	dedupRoot := &cobra.Command{Use: "root"}
+	dedupRoot.AddCommand(&cobra.Command{Use: "same"}, &cobra.Command{Use: "same"})
+	deduplicateCommands(dedupRoot)
+	addPluginCommandsSafe(dedupRoot, []*cobra.Command{{Use: "same"}, {Use: "new"}})
+	_ = newCompletionCommand(dedupRoot)
+	_ = newCatalogCommand(nil)
+	_ = newConfigCommand()
+	_ = newCacheCommand()
+	_ = newVersionCommand()
+	_ = newRecoveryCommand(context.Background(), nil, &GlobalFlags{})
+	_ = newAPICommand(&GlobalFlags{})
+	_ = NewRootCommand(context.Background())
+}

internal/app/direct_runtime.go

@@ -23,8 +23,8 @@ 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/executor"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
 )
 
 var (
@@ -57,12 +57,12 @@ func devappMCPEndpoint() string {
 	return defaultPATGatewayBaseURL() + devappServerPath
 }
 
-func defaultPATServerDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
+func defaultPATServerDescriptor() mcptypes.ServerDescriptor {
+	return mcptypes.ServerDescriptor{
 		Key:         defaultPATProductID,
 		DisplayName: defaultPATDisplayName,
 		Endpoint:    defaultPATMCPEndpoint(),
-		CLI: market.CLIOverlay{
+		CLI: mcptypes.CLIOverlay{
 			ID:       defaultPATProductID,
 			Command:  defaultPATProductID,
 			Prefixes: []string{defaultPATProductID},
@@ -104,7 +104,7 @@ func defaultPATGatewayBaseURL() string {
 
 // SetDynamicServers injects server data discovered from servers.json.
 // All product endpoints are resolved dynamically from this data.
-func SetDynamicServers(servers []market.ServerDescriptor) {
+func SetDynamicServers(servers []mcptypes.ServerDescriptor) {
 	dynamicMu.Lock()
 	defer dynamicMu.Unlock()
 
@@ -167,7 +167,7 @@ func SetDynamicServers(servers []market.ServerDescriptor) {
 	dynamicToolEndpoints = toolEndpoints
 }
 
-func registerDynamicServer(server market.ServerDescriptor, endpoints map[string]string, products map[string]bool, aliases map[string]string, toolEndpoints map[string]string) {
+func registerDynamicServer(server mcptypes.ServerDescriptor, endpoints map[string]string, products map[string]bool, aliases map[string]string, toolEndpoints map[string]string) {
 	if server.CLI.Skip {
 		return
 	}
@@ -309,9 +309,6 @@ func editionServerEndpoint(productID string) (string, bool) {
 		return "", false
 	}
 	hooks := edition.Get()
-	if hooks == nil {
-		return "", false
-	}
 	if endpoint, ok := endpointFromEditionServers(productID, hooks.StaticServers); ok {
 		return endpoint, true
 	}
@@ -363,7 +360,7 @@ func DirectRuntimeProductIDs() map[string]bool {
 // dynamic server registry without replacing the current entries. This
 // is used by the plugin loader to inject plugin servers alongside
 // Market-discovered servers.
-func AppendDynamicServer(server market.ServerDescriptor) {
+func AppendDynamicServer(server mcptypes.ServerDescriptor) {
 	dynamicMu.Lock()
 	defer dynamicMu.Unlock()
 

internal/app/direct_runtime_override_test.go

@@ -1,356 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package app
-
-import (
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
-)
-
-// Regression for the chat/bot tool routing bug: when the `chat` envelope
-// declares toolOverrides with `serverOverride: "bot"` (e.g. `search_my_robots`,
-// `send_message_by_custom_robot`), those tool names must NOT be registered
-// into `dynamicToolEndpoints` pointing at chat's endpoint. Otherwise the
-// tool-level Priority 1 lookup in `directRuntimeEndpoint` returns chat's URL
-// even when the invocation's CanonicalProduct is "bot", causing the Portal to
-// respond with `PARAM_ERROR - 未找到指定工具` because chat's mcpId has no such
-// tool.
-//
-// Owner (bot envelope) still registers the tool (no serverOverride on the bot
-// side), so product-level and tool-level lookups both resolve correctly.
-
-const (
-	testBotEndpoint  = "https://pre-mcp-gw.dingtalk.com/server/4717d5cbb92ecdebd89c174e4331dc17207208a97622e2004cac49c0fbedc9d1"
-	testChatEndpoint = "https://pre-mcp-gw.dingtalk.com/server/0a1609437385696b77fc4771c3ddaf5656b487f809966c0cc8d4755e7b1d3b74"
-)
-
-// botDescriptor returns a minimal `bot` server descriptor that owns the
-// `search_my_robots` + `send_message_by_custom_robot` tools (no
-// serverOverride — bot is the real owner).
-func botDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testBotEndpoint,
-		CLI: market.CLIOverlay{
-			ID: "bot",
-			ToolOverrides: map[string]market.CLIToolOverride{
-				"search_my_robots":             {CLIName: "search"},
-				"send_message_by_custom_robot": {CLIName: "send-by-webhook"},
-				"add_robot_to_group":           {CLIName: "add-bot"},
-			},
-		},
-	}
-}
-
-// chatDescriptor returns a minimal `chat` server descriptor whose
-// toolOverrides include bot-owned tools via `serverOverride: "bot"`, plus a
-// chat-native tool (`search_groups_by_keyword`) that must remain routed to
-// chat's endpoint.
-func chatDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testChatEndpoint,
-		CLI: market.CLIOverlay{
-			ID:      "chat",
-			Command: "chat",
-			ToolOverrides: map[string]market.CLIToolOverride{
-				"search_groups_by_keyword": {CLIName: "search"},
-				"search_my_robots": {
-					CLIName:        "search",
-					ServerOverride: "bot",
-				},
-				"send_message_by_custom_robot": {
-					CLIName:        "send-by-webhook",
-					ServerOverride: "bot",
-				},
-				"add_robot_to_group": {
-					CLIName:        "add-bot",
-					ServerOverride: "bot",
-				},
-			},
-		},
-	}
-}
-
-// withCleanDynamicRegistry snapshots and restores the package-level dynamic
-// registries so parallel/other tests aren't affected by this case's mutations.
-func withCleanDynamicRegistry(t *testing.T) {
-	t.Helper()
-	dynamicMu.Lock()
-	prev := struct {
-		endpoints     map[string]string
-		products      map[string]bool
-		aliases       map[string]string
-		toolEndpoints map[string]string
-	}{dynamicEndpoints, dynamicProducts, dynamicAliases, dynamicToolEndpoints}
-	dynamicEndpoints = nil
-	dynamicProducts = nil
-	dynamicAliases = nil
-	dynamicToolEndpoints = nil
-	dynamicMu.Unlock()
-	t.Cleanup(func() {
-		dynamicMu.Lock()
-		dynamicEndpoints = prev.endpoints
-		dynamicProducts = prev.products
-		dynamicAliases = prev.aliases
-		dynamicToolEndpoints = prev.toolEndpoints
-		dynamicMu.Unlock()
-	})
-}
-
-func assertEndpoint(t *testing.T, productID, toolName, want string) {
-	t.Helper()
-	got, ok := directRuntimeEndpoint(productID, toolName)
-	if !ok {
-		t.Fatalf("directRuntimeEndpoint(%q, %q) returned ok=false", productID, toolName)
-	}
-	if got != want {
-		t.Fatalf("directRuntimeEndpoint(%q, %q) = %q, want %q", productID, toolName, got, want)
-	}
-}
-
-// TestSetDynamicServers_ServerOverrideDoesNotHijackToolEndpoint verifies that
-// chat's serverOverride entries cannot steal bot-owned tool routes, regardless
-// of registration order.
-func TestSetDynamicServers_ServerOverrideDoesNotHijackToolEndpoint(t *testing.T) {
-	tests := []struct {
-		name    string
-		servers []market.ServerDescriptor
-	}{
-		{
-			name:    "bot first, chat second",
-			servers: []market.ServerDescriptor{botDescriptor(), chatDescriptor()},
-		},
-		{
-			name:    "chat first, bot second",
-			servers: []market.ServerDescriptor{chatDescriptor(), botDescriptor()},
-		},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			withCleanDynamicRegistry(t)
-			SetDynamicServers(tc.servers)
-
-			// Bot-owned tools must route to bot's endpoint even though chat
-			// declares toolOverrides for them (with serverOverride="bot").
-			assertEndpoint(t, "bot", "search_my_robots", testBotEndpoint)
-			assertEndpoint(t, "bot", "send_message_by_custom_robot", testBotEndpoint)
-			assertEndpoint(t, "bot", "add_robot_to_group", testBotEndpoint)
-
-			// Chat-native tools must still route to chat.
-			assertEndpoint(t, "chat", "search_groups_by_keyword", testChatEndpoint)
-
-			// Product-level fallback for bot (no tool name) must also return
-			// bot's endpoint.
-			assertEndpoint(t, "bot", "", testBotEndpoint)
-		})
-	}
-}
-
-// TestAppendDynamicServer_ServerOverrideDoesNotHijackToolEndpoint exercises
-// the plugin-injection path (`AppendDynamicServer`) which has the same
-// `toolOverrides` registration loop as `SetDynamicServers`. Chat's
-// serverOverride entries must not overwrite bot's tool → endpoint mapping.
-func TestAppendDynamicServer_ServerOverrideDoesNotHijackToolEndpoint(t *testing.T) {
-	orders := [][]market.ServerDescriptor{
-		{botDescriptor(), chatDescriptor()},
-		{chatDescriptor(), botDescriptor()},
-	}
-
-	for _, servers := range orders {
-		t.Run("", func(t *testing.T) {
-			withCleanDynamicRegistry(t)
-			for _, s := range servers {
-				AppendDynamicServer(s)
-			}
-
-			assertEndpoint(t, "bot", "search_my_robots", testBotEndpoint)
-			assertEndpoint(t, "bot", "send_message_by_custom_robot", testBotEndpoint)
-			assertEndpoint(t, "chat", "search_groups_by_keyword", testChatEndpoint)
-		})
-	}
-}
-
-// --- Issue #219 regression tests: cross-product tool name collision ---
-//
-// When two different products register tools with the same name (e.g. drive
-// and doc both have "create_folder"), the product-level endpoint must win
-// when the caller already knows the productID. Otherwise the tool-level map
-// (last-writer-wins) routes the invocation to the wrong MCP server.
-
-const (
-	testDriveEndpoint = "https://mcp-gw.dingtalk.com/server/drive-hash"
-	testDocEndpoint   = "https://mcp-gw.dingtalk.com/server/doc-hash"
-)
-
-func driveDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testDriveEndpoint,
-		CLI: market.CLIOverlay{
-			ID:      "drive",
-			Command: "drive",
-			ToolOverrides: map[string]market.CLIToolOverride{
-				"create_folder":   {CLIName: "mkdir"},
-				"list_files":      {CLIName: "list"},
-				"download_file":   {CLIName: "download"},
-				"get_upload_info": {CLIName: "upload-info"},
-			},
-		},
-	}
-}
-
-func docDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testDocEndpoint,
-		CLI: market.CLIOverlay{
-			ID:      "doc",
-			Command: "doc",
-			ToolOverrides: map[string]market.CLIToolOverride{
-				"create_folder":    {CLIName: "create", Group: "folder"},
-				"download_file":    {CLIName: "download"},
-				"search_documents": {CLIName: "search"},
-				"list_nodes":       {CLIName: "list"},
-			},
-		},
-	}
-}
-
-// TestDirectRuntimeEndpoint_ProductLevelWinsOverConflictingToolLevel verifies
-// that when productID is known and has a registered endpoint, the product-level
-// endpoint is used even if the tool-level map points to a different server
-// (due to same-name tool collision). This is the core fix for issue #219.
-func TestDirectRuntimeEndpoint_ProductLevelWinsOverConflictingToolLevel(t *testing.T) {
-	tests := []struct {
-		name    string
-		servers []market.ServerDescriptor
-	}{
-		{
-			name:    "drive first, doc second",
-			servers: []market.ServerDescriptor{driveDescriptor(), docDescriptor()},
-		},
-		{
-			name:    "doc first, drive second",
-			servers: []market.ServerDescriptor{docDescriptor(), driveDescriptor()},
-		},
-	}
-
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			withCleanDynamicRegistry(t)
-			SetDynamicServers(tc.servers)
-
-			// Drive tools must always route to drive's endpoint regardless of
-			// registration order — productID "drive" is known.
-			assertEndpoint(t, "drive", "create_folder", testDriveEndpoint)
-			assertEndpoint(t, "drive", "download_file", testDriveEndpoint)
-			assertEndpoint(t, "drive", "list_files", testDriveEndpoint)
-			assertEndpoint(t, "drive", "get_upload_info", testDriveEndpoint)
-
-			// Doc tools must always route to doc's endpoint.
-			assertEndpoint(t, "doc", "create_folder", testDocEndpoint)
-			assertEndpoint(t, "doc", "download_file", testDocEndpoint)
-			assertEndpoint(t, "doc", "search_documents", testDocEndpoint)
-			assertEndpoint(t, "doc", "list_nodes", testDocEndpoint)
-
-			// Product-level fallback (no tool name) still works.
-			assertEndpoint(t, "drive", "", testDriveEndpoint)
-			assertEndpoint(t, "doc", "", testDocEndpoint)
-		})
-	}
-}
-
-// --- Command field first-writer-wins regression test ---
-//
-// When two plugins declare the same CLI.Command but different CLI.ID values,
-// AppendDynamicServer must NOT let the second registration overwrite the
-// command → endpoint mapping established by the first. The fix uses a simple
-// "if not exists" guard on dynamicEndpoints[cmd].
-
-const (
-	testFirstEndpoint  = "https://mcp-gw.dingtalk.com/server/first-plugin-hash"
-	testSecondEndpoint = "https://mcp-gw.dingtalk.com/server/second-plugin-hash"
-)
-
-func firstPluginDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testFirstEndpoint,
-		CLI: market.CLIOverlay{
-			ID:      "plugin-alpha",
-			Command: "shared-cmd",
-		},
-	}
-}
-
-func secondPluginDescriptor() market.ServerDescriptor {
-	return market.ServerDescriptor{
-		Endpoint: testSecondEndpoint,
-		CLI: market.CLIOverlay{
-			ID:      "plugin-beta",
-			Command: "shared-cmd",
-		},
-	}
-}
-
-// TestAppendDynamicServer_CommandEndpointFirstWriterWins verifies that when
-// two plugins declare the same Command (but different IDs), only the first
-// registration takes effect for the command → endpoint mapping. The second
-// plugin's own id-based endpoint is unaffected.
-func TestAppendDynamicServer_CommandEndpointFirstWriterWins(t *testing.T) {
-	withCleanDynamicRegistry(t)
-
-	AppendDynamicServer(firstPluginDescriptor())
-	AppendDynamicServer(secondPluginDescriptor())
-
-	// The command "shared-cmd" must resolve to the first plugin's endpoint.
-	assertEndpoint(t, "shared-cmd", "", testFirstEndpoint)
-
-	// Each plugin's own id-based endpoint is always unconditionally written.
-	assertEndpoint(t, "plugin-alpha", "", testFirstEndpoint)
-	assertEndpoint(t, "plugin-beta", "", testSecondEndpoint)
-
-	// Command must appear in dynamicProducts (discovery) regardless.
-	ids := DirectRuntimeProductIDs()
-	if !ids["shared-cmd"] {
-		t.Fatal("shared-cmd not found in DirectRuntimeProductIDs()")
-	}
-	if !ids["plugin-alpha"] {
-		t.Fatal("plugin-alpha not found in DirectRuntimeProductIDs()")
-	}
-	if !ids["plugin-beta"] {
-		t.Fatal("plugin-beta not found in DirectRuntimeProductIDs()")
-	}
-}
-
-// TestDirectRuntimeEndpoint_ToolLevelFallbackWhenProductUnknown verifies that
-// tool-level routing still works as a fallback when productID is empty or has
-// no registered endpoint (the original design intent for tool-level Priority 1).
-func TestDirectRuntimeEndpoint_ToolLevelFallbackWhenProductUnknown(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	SetDynamicServers([]market.ServerDescriptor{driveDescriptor(), docDescriptor()})
-
-	// When productID is empty, tool-level endpoint is the only option.
-	// The actual endpoint depends on registration order (last-writer-wins),
-	// but the lookup must succeed.
-	endpoint, ok := directRuntimeEndpoint("", "create_folder")
-	if !ok {
-		t.Fatal("directRuntimeEndpoint(\"\", \"create_folder\") returned ok=false, want ok=true")
-	}
-	if endpoint != testDriveEndpoint && endpoint != testDocEndpoint {
-		t.Fatalf("directRuntimeEndpoint(\"\", \"create_folder\") = %q, want one of drive/doc endpoints", endpoint)
-	}
-
-	// Unique tools (no collision) still resolve via tool-level.
-	assertEndpoint(t, "", "search_documents", testDocEndpoint)
-	assertEndpoint(t, "", "get_upload_info", testDriveEndpoint)
-}

internal/app/direct_runtime_test.go

@@ -1,198 +0,0 @@
-package app
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
-)
-
-func TestDefaultPATServerDescriptorUsesBehaviorAuthorizationName(t *testing.T) {
-	server := defaultPATServerDescriptor()
-	if server.CLI.ID != "pat" {
-		t.Fatalf("default PAT server id = %q, want pat", server.CLI.ID)
-	}
-	if server.DisplayName != "行为授权" {
-		t.Fatalf("default PAT server display name = %q, want 行为授权", server.DisplayName)
-	}
-	if server.Endpoint != defaultPATMCPEndpoint() {
-		t.Fatalf("default PAT server endpoint = %q, want %q", server.Endpoint, defaultPATMCPEndpoint())
-	}
-}
-
-func TestDirectRuntimeProductIDsIncludesDefaultPAT(t *testing.T) {
-	dynamicMu.Lock()
-	previousProducts := dynamicProducts
-	dynamicProducts = nil
-	dynamicMu.Unlock()
-	t.Cleanup(func() {
-		dynamicMu.Lock()
-		dynamicProducts = previousProducts
-		dynamicMu.Unlock()
-	})
-
-	ids := DirectRuntimeProductIDs()
-	if !ids["pat"] {
-		t.Fatalf("DirectRuntimeProductIDs() missing default pat product: %#v", ids)
-	}
-}
-
-func TestDirectRuntimeProductIDsIncludesDevappHelper(t *testing.T) {
-	withCleanDynamicRegistry(t)
-
-	ids := DirectRuntimeProductIDs()
-	if !ids["devapp"] {
-		t.Fatalf("DirectRuntimeProductIDs() missing devapp helper product: %#v", ids)
-	}
-}
-
-func TestDirectRuntimeEndpoint_DevappEnvOverrideWithoutRegistry(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp")
-
-	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp")
-}
-
-func TestDirectRuntimeEndpoint_DevappEnvOverridePreservesQuery(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp?key=secret")
-
-	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp?key=secret")
-}
-
-func TestDirectRuntimeEndpoint_DevappDynamicServerDoesNotOverrideHardcoded(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	SetDynamicServers([]market.ServerDescriptor{
-		{
-			Endpoint: "https://example.test/server/devapp-supplement",
-			CLI: market.CLIOverlay{
-				ID:      "devapp",
-				Command: "devapp",
-			},
-		},
-	})
-
-	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
-}
-
-func TestDirectRuntimeEndpoint_DevappEditionSupplementDoesNotOverrideHardcoded(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	prev := edition.Get()
-	edition.Override(&edition.Hooks{
-		Name: "wukong",
-		SupplementServers: func() []edition.ServerInfo {
-			return []edition.ServerInfo{
-				{
-					ID:       "devapp",
-					Name:     "开放平台应用管理",
-					Endpoint: "https://example.test/server/devapp-edition-supplement?key=secret",
-					Prefixes: []string{"devapp", "app"},
-				},
-			}
-		},
-	})
-	t.Cleanup(func() { edition.Override(prev) })
-
-	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
-}
-
-func TestDirectRuntimeEndpoint_DevappEditionStaticDoesNotOverrideHardcoded(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	prev := edition.Get()
-	edition.Override(&edition.Hooks{
-		Name: "wukong",
-		StaticServers: func() []edition.ServerInfo {
-			return []edition.ServerInfo{
-				{
-					ID:       "devapp",
-					Name:     "开放平台应用管理",
-					Endpoint: "https://example.test/server/devapp-edition-static",
-					Prefixes: []string{"devapp", "app"},
-				},
-			}
-		},
-	})
-	t.Cleanup(func() { edition.Override(prev) })
-
-	assertEndpoint(t, "devapp", "list_dev_app", devappMCPEndpoint())
-}
-
-func TestDirectRuntimeEndpoint_DevappEnvOverrideWinsOverEditionSupplement(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	t.Setenv("DINGTALK_DEVAPP_MCP_URL", "https://example.test/server/devapp-env")
-	prev := edition.Get()
-	edition.Override(&edition.Hooks{
-		Name: "wukong",
-		SupplementServers: func() []edition.ServerInfo {
-			return []edition.ServerInfo{
-				{
-					ID:       "devapp",
-					Name:     "开放平台应用管理",
-					Endpoint: "https://example.test/server/devapp-edition-supplement",
-				},
-			}
-		},
-	})
-	t.Cleanup(func() { edition.Override(prev) })
-
-	assertEndpoint(t, "devapp", "list_dev_app", "https://example.test/server/devapp-env")
-}
-
-func TestDirectRuntimeEndpoint_DefaultPATFallbackWhenRegistryMissing(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	assertEndpoint(t, "pat", "", defaultPATMCPEndpoint())
-}
-
-func TestDirectRuntimeEndpoint_DefaultPATFallbackUsesConfiguredMCPBaseURL(t *testing.T) {
-	withCleanDynamicRegistry(t)
-
-	tmpDir := t.TempDir()
-	if err := os.WriteFile(filepath.Join(tmpDir, "mcp_url"), []byte("http://127.0.0.1:54321/base"), 0o600); err != nil {
-		t.Fatalf("WriteFile(mcp_url) error = %v", err)
-	}
-	t.Setenv("DWS_CONFIG_DIR", tmpDir)
-
-	assertEndpoint(t, "pat", "", "http://127.0.0.1:54321/base/server/"+defaultPATServerID)
-}
-
-func TestDirectRuntimeEndpoint_PATDiscoveryOverrideWinsOverBuiltInFallback(t *testing.T) {
-	withCleanDynamicRegistry(t)
-	customEndpoint := "https://example.com/server/custom-pat"
-	SetDynamicServers([]market.ServerDescriptor{
-		{
-			Endpoint: customEndpoint,
-			CLI: market.CLIOverlay{
-				ID:      "pat",
-				Command: "pat",
-			},
-		},
-	})
-	assertEndpoint(t, "pat", "", customEndpoint)
-}
-
-func TestNormalizeDirectRuntimeProductIDPreservesLegacyHiddenVendorRouting(t *testing.T) {
-	dynamicMu.Lock()
-	previousAliases := dynamicAliases
-	dynamicAliases = nil
-	dynamicMu.Unlock()
-	t.Cleanup(func() {
-		dynamicMu.Lock()
-		dynamicAliases = previousAliases
-		dynamicMu.Unlock()
-	})
-
-	cases := map[string]string{
-		"tb":                       "teambition",
-		"dingtalk-discovery":       "discovery",
-		"dingtalk-oa-plus":         "oa",
-		"dingtalk-ai-sincere-hire": "ai-sincere-hire",
-	}
-
-	for input, want := range cases {
-		if got := normalizeDirectRuntimeProductID(input); got != want {
-			t.Fatalf("normalizeDirectRuntimeProductID(%q) = %q, want %q", input, got, want)
-		}
-	}
-}

internal/app/doctor_command.go

@@ -21,8 +21,7 @@ import (
 	"time"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cache"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/market"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/tui"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
@@ -31,6 +30,15 @@ import (
 	"github.com/spf13/cobra"
 )
 
+var (
+	doctorKeychainDiagnose   = keychain.Diagnose
+	doctorAuthStatus         = (*authpkg.OAuthProvider).Status
+	doctorAuthAccessToken    = (*authpkg.OAuthProvider).GetAccessToken
+	doctorHTTPDo             = (*http.Client).Do
+	doctorFetchLatestRelease = func() (*upgrade.ReleaseInfo, error) { return upgrade.NewClient().FetchLatestRelease() }
+	doctorNeedsUpgrade       = upgrade.NeedsUpgrade
+)
+
 // checkStatus represents the outcome of a single doctor check.
 type checkStatus string
 
@@ -78,6 +86,9 @@ func runDoctor(cmd *cobra.Command, _ []string) error {
 	authResult := doctorCheckAuth(cmd.Context(), w, jsonOut)
 	checks = append(checks, authResult)
 
+	keychainResult := doctorCheckKeychain(w, jsonOut)
+	checks = append(checks, keychainResult)
+
 	networkResult := doctorCheckNetwork(cmd.Context(), w, jsonOut, networkTimeout)
 	checks = append(checks, networkResult)
 
@@ -132,8 +143,21 @@ func doctorCheckAuth(ctx context.Context, w io.Writer, jsonOut bool) checkResult
 	provider := authpkg.NewOAuthProvider(configDir, nil)
 	configureOAuthProviderCompatibility(provider, configDir)
 
-	data, err := provider.Status()
+	data, err := doctorAuthStatus(provider)
 	if err != nil || data == nil {
+		if diagnostic := authStatusDiagnosticFromError(err); diagnostic != nil {
+			r := checkResult{
+				Name:    "auth",
+				Status:  statusFail,
+				Message: diagnostic.Message,
+				Hint:    diagnostic.Hint,
+				Detail:  map[string]string{"reason": diagnostic.Reason},
+			}
+			if !jsonOut {
+				printCheckResult(w, r)
+			}
+			return r
+		}
 		r := checkResult{Name: "auth", Status: statusFail, Message: "未登录"}
 		if !edition.Get().IsEmbedded {
 			r.Hint = "运行 dws auth login 进行登录"
@@ -147,7 +171,7 @@ func doctorCheckAuth(ctx context.Context, w io.Writer, jsonOut bool) checkResult
 	if data.IsAccessTokenValid() || data.IsRefreshTokenValid() {
 		if !data.IsAccessTokenValid() {
 			refreshCtx, cancel := context.WithTimeout(ctx, 15*time.Second)
-			_, refreshErr := provider.GetAccessToken(refreshCtx)
+			_, refreshErr := doctorAuthAccessToken(provider, refreshCtx)
 			cancel()
 			if refreshErr != nil {
 				r := checkResult{
@@ -184,6 +208,40 @@ func doctorCheckAuth(ctx context.Context, w io.Writer, jsonOut bool) checkResult
 	return r
 }
 
+// ── Keychain check ─────────────────────────────────────────────────────
+
+func doctorCheckKeychain(w io.Writer, jsonOut bool) checkResult {
+	if !jsonOut {
+		fmt.Fprint(w, tui.Dim("检查钥匙串状态...     "))
+	}
+
+	diagnostic := doctorKeychainDiagnose()
+	r := checkResult{
+		Name:    "keychain",
+		Status:  statusPass,
+		Message: diagnostic.Message,
+		Detail:  diagnostic.Detail,
+	}
+	if !diagnostic.OK {
+		r.Status = statusFail
+		r.Hint = diagnostic.Hint
+		if diagnostic.Detail == nil {
+			r.Detail = map[string]string{"reason": diagnostic.Reason}
+		} else if diagnostic.Reason != "" {
+			detail := make(map[string]string, len(diagnostic.Detail)+1)
+			for k, v := range diagnostic.Detail {
+				detail[k] = v
+			}
+			detail["reason"] = diagnostic.Reason
+			r.Detail = detail
+		}
+	}
+	if !jsonOut {
+		printCheckResult(w, r)
+	}
+	return r
+}
+
 // ── Network check ───────────────────────────────────────────────────────
 
 func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout time.Duration) checkResult {
@@ -193,15 +251,12 @@ func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout
 
 	baseURL := config.GetMCPBaseURL()
 	httpClient := &http.Client{Timeout: timeout}
-	client := market.NewClient(baseURL, httpClient)
 
 	start := time.Now()
 	reqCtx, cancel := context.WithTimeout(ctx, timeout)
 	defer cancel()
 
-	_, err := client.FetchServers(reqCtx, 1)
-	latency := time.Since(start)
-
+	req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, baseURL, nil)
 	if err != nil {
 		r := checkResult{
 			Name:    "network",
@@ -215,6 +270,22 @@ func doctorCheckNetwork(ctx context.Context, w io.Writer, jsonOut bool, timeout
 		return r
 	}
 
+	resp, err := doctorHTTPDo(httpClient, req)
+	latency := time.Since(start)
+	if err != nil {
+		r := checkResult{
+			Name:    "network",
+			Status:  statusFail,
+			Message: fmt.Sprintf("%s 不可达: %v", baseURL, err),
+			Hint:    "请检查网络连接或代理设置",
+		}
+		if !jsonOut {
+			printCheckResult(w, r)
+		}
+		return r
+	}
+	resp.Body.Close()
+
 	r := checkResult{
 		Name:    "network",
 		Status:  statusPass,
@@ -233,64 +304,10 @@ func doctorCheckCache(w io.Writer, jsonOut bool) checkResult {
 		fmt.Fprint(w, tui.Dim("检查缓存状态...       "))
 	}
 
-	store := cacheStoreFromEnv()
-	files, _, err := cacheDirectoryStats(store.Root)
-	if err != nil {
-		r := checkResult{
-			Name:    "cache",
-			Status:  statusFail,
-			Message: fmt.Sprintf("缓存目录不可读: %v", err),
-			Hint:    "运行 dws cache clean 清理后重试",
-		}
-		if !jsonOut {
-			printCheckResult(w, r)
-		}
-		return r
-	}
-
-	entries, _ := store.ListToolsCacheEntries(config.DefaultPartition)
-
-	if files == 0 && len(entries) == 0 {
-		r := checkResult{
-			Name:    "cache",
-			Status:  statusWarn,
-			Message: "缓存为空 (首次使用)",
-			Hint:    "运行任意 dws 命令后将自动建立缓存",
-		}
-		if !jsonOut {
-			printCheckResult(w, r)
-		}
-		return r
-	}
-
-	staleCount := 0
-	for _, e := range entries {
-		if e.Freshness == cache.FreshnessStale {
-			staleCount++
-		}
-	}
-
-	if staleCount > 0 {
-		r := checkResult{
-			Name:    "cache",
-			Status:  statusWarn,
-			Message: fmt.Sprintf("%d 个文件, %d 个工具缓存, %d 个已过期", files, len(entries), staleCount),
-			Hint:    "运行 dws cache refresh 刷新缓存",
-		}
-		if !jsonOut {
-			printCheckResult(w, r)
-		}
-		return r
-	}
-
-	msg := fmt.Sprintf("%d 个文件, %d 个工具缓存", files, len(entries))
-	if len(entries) > 0 {
-		msg += ", 全部新鲜"
-	}
 	r := checkResult{
 		Name:    "cache",
 		Status:  statusPass,
-		Message: msg,
+		Message: "静态端点模式, 无需缓存",
 	}
 	if !jsonOut {
 		printCheckResult(w, r)
@@ -307,8 +324,7 @@ func doctorCheckVersion(w io.Writer, jsonOut bool, timeout time.Duration) checkR
 
 	currentVer := version
 
-	client := upgrade.NewClient()
-	latest, err := client.FetchLatestRelease()
+	latest, err := doctorFetchLatestRelease()
 	if err != nil {
 		r := checkResult{
 			Name:    "version",
@@ -322,7 +338,7 @@ func doctorCheckVersion(w io.Writer, jsonOut bool, timeout time.Duration) checkR
 		return r
 	}
 
-	if upgrade.NeedsUpgrade(currentVer, latest.Version) {
+	if doctorNeedsUpgrade(currentVer, latest.Version) {
 		r := checkResult{
 			Name:    "version",
 			Status:  statusWarn,

internal/app/doctor_command_test.go

@@ -15,9 +15,16 @@ package app
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
+	"errors"
+	"fmt"
+	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )
 
 func TestCountResults(t *testing.T) {
@@ -108,11 +115,8 @@ func TestDoctorCheckCacheEmpty(t *testing.T) {
 	var buf bytes.Buffer
 	r := doctorCheckCache(&buf, false)
 
-	if r.Status != statusWarn {
-		t.Errorf("expected warn for empty cache, got %s", r.Status)
-	}
-	if !strings.Contains(r.Message, "缓存为空") {
-		t.Errorf("expected empty cache message, got %q", r.Message)
+	if r.Status != statusPass {
+		t.Errorf("expected pass for static endpoint mode, got %s", r.Status)
 	}
 }
 
@@ -122,14 +126,116 @@ func TestDoctorCheckCacheEmptyJSON(t *testing.T) {
 	var buf bytes.Buffer
 	r := doctorCheckCache(&buf, true)
 
-	if r.Status != statusWarn {
-		t.Errorf("expected warn for empty cache, got %s", r.Status)
+	if r.Status != statusPass {
+		t.Errorf("expected pass for static endpoint mode, got %s", r.Status)
 	}
 	if buf.Len() != 0 {
 		t.Error("expected no output in JSON mode")
 	}
 }
 
+func TestDoctorCheckAuthReportsKeychainUnavailable(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", filepath.Join(t.TempDir(), "config"))
+
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		LoadToken: func(configDir string) ([]byte, error) {
+			return nil, keychain.NewUnavailableError("read DEK from macOS Keychain", errors.New("default keychain missing"))
+		},
+	})
+	t.Cleanup(func() {
+		edition.Override(prev)
+	})
+
+	var buf bytes.Buffer
+	r := doctorCheckAuth(context.Background(), &buf, false)
+
+	if r.Name != "auth" {
+		t.Fatalf("name = %q, want auth", r.Name)
+	}
+	if r.Status != statusFail {
+		t.Fatalf("status = %q, want fail", r.Status)
+	}
+	if !strings.Contains(r.Message, "Keychain") && !strings.Contains(r.Message, "钥匙串") {
+		t.Fatalf("message should mention Keychain/钥匙串; result=%+v", r)
+	}
+	if !strings.Contains(r.Hint, keychain.DisableKeychainEnv) {
+		t.Fatalf("hint should mention %s; result=%+v", keychain.DisableKeychainEnv, r)
+	}
+}
+
+func TestDoctorCheckAuthReportsDEKMissing(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", filepath.Join(t.TempDir(), "config"))
+
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		LoadToken: func(configDir string) ([]byte, error) {
+			return nil, fmt.Errorf("load from keychain: %w", keychain.ErrDEKMissing)
+		},
+	})
+	t.Cleanup(func() {
+		edition.Override(prev)
+	})
+
+	var buf bytes.Buffer
+	r := doctorCheckAuth(context.Background(), &buf, false)
+
+	if r.Name != "auth" {
+		t.Fatalf("name = %q, want auth", r.Name)
+	}
+	if r.Status != statusFail {
+		t.Fatalf("status = %q, want fail", r.Status)
+	}
+	if !strings.Contains(r.Message, "登录密钥") {
+		t.Fatalf("message should mention 登录密钥; result=%+v", r)
+	}
+	if !strings.Contains(r.Hint, "重新登录") {
+		t.Fatalf("hint should mention 重新登录; result=%+v", r)
+	}
+	detail, ok := r.Detail.(map[string]string)
+	if !ok || detail["reason"] != "dek_missing" {
+		t.Fatalf("detail = %#v, want reason=dek_missing", r.Detail)
+	}
+}
+
+func TestDoctorCheckKeychainReportsUnavailable(t *testing.T) {
+	prev := doctorKeychainDiagnose
+	doctorKeychainDiagnose = func() keychain.Diagnostic {
+		return keychain.Diagnostic{
+			OK:      false,
+			Reason:  "keychain_unavailable",
+			Message: "macOS 默认钥匙串不存在",
+			Hint:    "恢复默认钥匙串后重试",
+			Detail: map[string]string{
+				"default_keychain": "/tmp/missing.keychain-db",
+			},
+		}
+	}
+	t.Cleanup(func() {
+		doctorKeychainDiagnose = prev
+	})
+
+	var buf bytes.Buffer
+	r := doctorCheckKeychain(&buf, false)
+
+	if r.Name != "keychain" {
+		t.Fatalf("name = %q, want keychain", r.Name)
+	}
+	if r.Status != statusFail {
+		t.Fatalf("status = %q, want fail", r.Status)
+	}
+	if r.Message != "macOS 默认钥匙串不存在" {
+		t.Fatalf("message = %q", r.Message)
+	}
+	if r.Hint == "" {
+		t.Fatalf("hint is empty; result=%+v", r)
+	}
+	detail, ok := r.Detail.(map[string]string)
+	if !ok || detail["default_keychain"] == "" {
+		t.Fatalf("detail = %#v, want default_keychain", r.Detail)
+	}
+}
+
 func TestDoctorCommandStructure(t *testing.T) {
 	cmd := newDoctorCommand()
 	if cmd.Use != "doctor" {

internal/app/doctor_full_coverage_test.go

@@ -0,0 +1,133 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/keychain"
+	upgradepkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+func TestCrossPlatformCoverageDoctorRemainingCoverage(t *testing.T) {
+	oldEdition := edition.Get()
+	oldDiagnose := doctorKeychainDiagnose
+	oldStatus := doctorAuthStatus
+	oldAccess := doctorAuthAccessToken
+	oldHTTP := doctorHTTPDo
+	oldLatest := doctorFetchLatestRelease
+	oldNeeds := doctorNeedsUpgrade
+	oldRead := timingReadFile
+	t.Cleanup(func() {
+		edition.Override(oldEdition)
+		doctorKeychainDiagnose = oldDiagnose
+		doctorAuthStatus = oldStatus
+		doctorAuthAccessToken = oldAccess
+		doctorHTTPDo = oldHTTP
+		doctorFetchLatestRelease = oldLatest
+		doctorNeedsUpgrade = oldNeeds
+		timingReadFile = oldRead
+	})
+	edition.Override(&edition.Hooks{})
+	doctorKeychainDiagnose = func() keychain.Diagnostic { return keychain.Diagnostic{OK: true, Message: "ok"} }
+	buf := &bytes.Buffer{}
+
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return nil, nil }
+	if got := doctorCheckAuth(context.Background(), buf, false); got.Status != statusFail || got.Hint == "" {
+		t.Fatalf("missing auth = %#v", got)
+	}
+	edition.Override(&edition.Hooks{IsEmbedded: true})
+	if got := doctorCheckAuth(context.Background(), io.Discard, true); got.Status != statusFail || got.Hint != "" {
+		t.Fatalf("embedded missing auth = %#v", got)
+	}
+	edition.Override(&edition.Hooks{})
+	now := time.Now()
+	valid := &authpkg.TokenData{AccessToken: "a", ExpiresAt: now.Add(time.Hour)}
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return valid, nil }
+	if got := doctorCheckAuth(context.Background(), buf, false); got.Status != statusPass {
+		t.Fatalf("valid auth = %#v", got)
+	}
+	refresh := &authpkg.TokenData{RefreshToken: "r", RefreshExpAt: now.Add(time.Hour)}
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return refresh, nil }
+	doctorAuthAccessToken = func(*authpkg.OAuthProvider, context.Context) (string, error) { return "", errors.New("refresh") }
+	if got := doctorCheckAuth(context.Background(), buf, false); got.Status != statusWarn {
+		t.Fatalf("refresh failure = %#v", got)
+	}
+	doctorAuthAccessToken = func(*authpkg.OAuthProvider, context.Context) (string, error) { return "a", nil }
+	if got := doctorCheckAuth(context.Background(), buf, false); got.Status != statusPass {
+		t.Fatalf("refresh success = %#v", got)
+	}
+	expired := &authpkg.TokenData{AccessToken: "a", ExpiresAt: now.Add(-time.Hour)}
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return expired, nil }
+	if got := doctorCheckAuth(context.Background(), buf, false); got.Status != statusFail || got.Hint == "" {
+		t.Fatalf("expired auth = %#v", got)
+	}
+
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte(":"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if got := doctorCheckNetwork(context.Background(), buf, false, time.Second); got.Status != statusFail {
+		t.Fatalf("invalid network URL = %#v", got)
+	}
+	if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://example.test"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	doctorHTTPDo = func(*http.Client, *http.Request) (*http.Response, error) { return nil, errors.New("network") }
+	if got := doctorCheckNetwork(context.Background(), buf, false, time.Second); got.Status != statusFail {
+		t.Fatalf("network failure = %#v", got)
+	}
+	doctorHTTPDo = func(*http.Client, *http.Request) (*http.Response, error) {
+		return &http.Response{StatusCode: http.StatusOK, Body: io.NopCloser(strings.NewReader("ok"))}, nil
+	}
+	if got := doctorCheckNetwork(context.Background(), buf, false, time.Second); got.Status != statusPass {
+		t.Fatalf("network success = %#v", got)
+	}
+
+	doctorFetchLatestRelease = func() (*upgradepkg.ReleaseInfo, error) { return nil, errors.New("latest") }
+	if got := doctorCheckVersion(buf, false, time.Second); got.Status != statusFail {
+		t.Fatalf("version failure = %#v", got)
+	}
+	doctorFetchLatestRelease = func() (*upgradepkg.ReleaseInfo, error) { return &upgradepkg.ReleaseInfo{Version: "99.0.0"}, nil }
+	doctorNeedsUpgrade = func(string, string) bool { return true }
+	if got := doctorCheckVersion(buf, false, time.Second); got.Status != statusWarn {
+		t.Fatalf("version warning = %#v", got)
+	}
+	doctorNeedsUpgrade = func(string, string) bool { return false }
+	if got := doctorCheckVersion(buf, false, time.Second); got.Status != statusPass {
+		t.Fatalf("version pass = %#v", got)
+	}
+
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return valid, nil }
+	doctorFetchLatestRelease = func() (*upgradepkg.ReleaseInfo, error) { return &upgradepkg.ReleaseInfo{Version: version}, nil }
+	timingReadFile = func(string) ([]byte, error) {
+		return []byte(`{"command":"test","timestamp":"2026-01-01T00:00:00Z","phases":[]}`), nil
+	}
+	doctor := newDoctorCommand()
+	doctor.SetContext(context.Background())
+	doctor.SetOut(io.Discard)
+	_ = doctor.Flags().Set("json", "true")
+	_ = doctor.Flags().Set("perf", "true")
+	_ = doctor.Flags().Set("timeout", "0")
+	if err := doctor.RunE(doctor, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	doctorAuthStatus = func(*authpkg.OAuthProvider) (*authpkg.TokenData, error) { return nil, errors.New("not logged in") }
+	doctor = newDoctorCommand()
+	doctor.SetContext(context.Background())
+	doctor.SetOut(io.Discard)
+	if err := doctor.RunE(doctor, nil); err == nil {
+		t.Fatal("doctor failures should return an error")
+	}
+}

internal/app/dry_run_guards_test.go

@@ -0,0 +1,66 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+)
+
+func TestToolCallerAdapterDryRunNeverInvokesRunner(t *testing.T) {
+	runner := &countingErrorRunner{}
+	caller := newToolCallerAdapter(runner, &GlobalFlags{DryRun: true, Format: "json"})
+	result, err := caller.CallTool(context.Background(), "aitable-helper", "set_advanced_permission", map[string]any{"enabled": false})
+	if err != nil {
+		t.Fatalf("CallTool() error = %v", err)
+	}
+	if got := runner.calls.Load(); got != 0 {
+		t.Fatalf("runner calls = %d, want 0", got)
+	}
+	if result == nil || len(result.Content) != 1 || !strings.Contains(result.Content[0].Text, `"dry_run":true`) {
+		t.Fatalf("dry-run result = %#v", result)
+	}
+
+	var nilAdapter *toolCallerAdapter
+	if nilAdapter.DryRun() || nilAdapter.Format() != "json" {
+		t.Fatal("nil adapter accessors are not safe")
+	}
+	if _, err := nilAdapter.CallTool(context.Background(), "x", "y", nil); err == nil {
+		t.Fatal("nil adapter accepted a tool call")
+	}
+}
+
+func TestRuntimeRunnerGlobalDryRunStopsBeforeInjectedFallback(t *testing.T) {
+	fallback := &countingErrorRunner{}
+	runner := &runtimeRunner{globalFlags: &GlobalFlags{DryRun: true}, fallback: fallback}
+	result, err := runner.Run(context.Background(), executor.NewHelperInvocation(
+		"test",
+		"aitable",
+		"tool",
+		map[string]any{"id": "x"},
+	))
+	if err != nil {
+		t.Fatalf("Run() error = %v", err)
+	}
+	if !result.Invocation.DryRun || result.Response["dry_run"] != true {
+		t.Fatalf("dry-run result = %#v", result)
+	}
+	if got := fallback.calls.Load(); got != 0 {
+		t.Fatalf("fallback calls = %d, want 0", got)
+	}
+}
+
+type countingErrorRunner struct {
+	calls atomic.Int64
+}
+
+func (r *countingErrorRunner) Run(context.Context, executor.Invocation) (executor.Result, error) {
+	r.calls.Add(1)
+	return executor.Result{}, errors.New("runner must not be called")
+}

internal/app/event_command_full_coverage_test.go

@@ -0,0 +1,562 @@
+package app
+
+import (
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
+	eventtransport "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageEventConsumeCommandAllBranchesCoverage(t *testing.T) {
+	oldPersonal := eventRunPersonalConsume
+	oldCreds, oldConsume, oldForeground := eventResolveCredentials, eventConsumeRun, eventRunForeground
+	oldNormalize := eventNormalizeAs
+	t.Cleanup(func() {
+		eventRunPersonalConsume = oldPersonal
+		eventResolveCredentials, eventConsumeRun, eventRunForeground = oldCreds, oldConsume, oldForeground
+		eventNormalizeAs = oldNormalize
+	})
+	eventNormalizeAs = func(value string) (string, error) {
+		if strings.EqualFold(strings.TrimSpace(value), "app") {
+			return "app", nil
+		}
+		return normalizeEventAs(value)
+	}
+	fail := errors.New("failure")
+	personalCalled := false
+	eventRunPersonalConsume = func(*cobra.Command, personalConsumeOptions) error { personalCalled = true; return nil }
+	cmd := newEventConsumeCommand()
+	cmd.SetContext(context.Background())
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	if err := cmd.RunE(cmd, []string{"event.key"}); err != nil || !personalCalled {
+		t.Fatalf("personal consume = %v, called=%v", err, personalCalled)
+	}
+
+	makeApp := func() *cobra.Command {
+		command := newEventConsumeCommand()
+		command.SetContext(context.Background())
+		command.SetOut(io.Discard)
+		command.SetErr(io.Discard)
+		_ = command.Flags().Set("as", "app")
+		return command
+	}
+	invalid := newEventConsumeCommand()
+	_ = invalid.Flags().Set("as", "invalid")
+	if err := invalid.RunE(invalid, nil); err == nil {
+		t.Fatal("invalid event identity succeeded")
+	}
+	debug := makeApp()
+	_ = debug.Flags().Set("debug-raw-events", "true")
+	if err := debug.RunE(debug, nil); err == nil {
+		t.Fatal("app debug-raw-events succeeded")
+	}
+	userFlag := makeApp()
+	_ = userFlag.Flags().Set("subscribe-id", "sub")
+	if err := userFlag.RunE(userFlag, nil); err == nil {
+		t.Fatal("app personal flag succeeded")
+	}
+	if err := makeApp().RunE(makeApp(), []string{"event.key"}); err == nil {
+		t.Fatal("app event key succeeded")
+	}
+	eventResolveCredentials = func(string, eventStreamTicketOptions) (string, string, error) { return "", "", fail }
+	if err := makeApp().RunE(makeApp(), nil); !errors.Is(err, fail) {
+		t.Fatalf("event credentials error = %v", err)
+	}
+	eventResolveCredentials = func(string, eventStreamTicketOptions) (string, string, error) { return "client", "secret", nil }
+	badRoute := makeApp()
+	_ = badRoute.Flags().Set("route", "bad")
+	if err := badRoute.RunE(badRoute, nil); err == nil {
+		t.Fatal("invalid event route succeeded")
+	}
+	invalidConfig := makeApp()
+	_ = invalidConfig.Flags().Set("format", "json")
+	if err := invalidConfig.RunE(invalidConfig, nil); err == nil {
+		t.Fatal("unbounded JSON event stream succeeded")
+	}
+	conflict := makeApp()
+	conflict.Flags().String("output", "", "")
+	_ = conflict.Flags().Set("output-dir", t.TempDir())
+	_ = conflict.Flags().Set("output", filepath.Join(t.TempDir(), "out"))
+	if err := conflict.RunE(conflict, nil); err == nil {
+		t.Fatal("event output conflict succeeded")
+	}
+	eventConsumeRun = func(context.Context, consume.Config) error { return fail }
+	t.Setenv(authpkg.EnvClientID, "half-set")
+	t.Setenv(authpkg.EnvClientSecret, "")
+	valid := makeApp()
+	_ = valid.Flags().Set("format", "table")
+	_ = valid.Flags().Set("max-events", "1")
+	if err := valid.RunE(valid, nil); !errors.Is(err, fail) {
+		t.Fatalf("event consume run error = %v", err)
+	}
+	eventRunForeground = func(context.Context, consume.Config, string, string, eventStreamTicketOptions) error { return fail }
+	foreground := makeApp()
+	_ = foreground.Flags().Set("foreground", "true")
+	if err := foreground.RunE(foreground, nil); !errors.Is(err, fail) {
+		t.Fatalf("foreground event error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventSourcesAndForegroundCoverage(t *testing.T) {
+	oldNew, oldToken, oldEventSource, oldBus := eventNewDingtalkSource, eventResolveAccessToken, eventNewEventSource, eventBusRun
+	oldEdition := edition.Get()
+	t.Cleanup(func() {
+		eventNewDingtalkSource, eventResolveAccessToken = oldNew, oldToken
+		eventNewEventSource, eventBusRun = oldEventSource, oldBus
+		edition.Override(oldEdition)
+	})
+	fail := errors.New("failure")
+	eventNewDingtalkSource = func(source.Config, ...source.SourceOption) (*source.DingtalkSource, error) { return nil, fail }
+	if _, err := newEventSource(context.Background(), "config", "client", "secret", eventStreamTicketOptions{}); !errors.Is(err, fail) {
+		t.Fatalf("SDK event source error = %v", err)
+	}
+	eventNewDingtalkSource = func(source.Config, ...source.SourceOption) (*source.DingtalkSource, error) {
+		return &source.DingtalkSource{}, nil
+	}
+	if _, err := newEventSource(context.Background(), "config", "client", "secret", eventStreamTicketOptions{}); err != nil {
+		t.Fatal(err)
+	}
+	stream := eventStreamTicketOptions{Mode: "custom"}
+	var captured source.Config
+	eventNewDingtalkSource = func(cfg source.Config, _ ...source.SourceOption) (*source.DingtalkSource, error) {
+		captured = cfg
+		return &source.DingtalkSource{}, nil
+	}
+	eventResolveAccessToken = func(context.Context, string, string) (string, error) { return "", fail }
+	if _, err := newEventSource(context.Background(), "config", "client", "secret", stream); err != nil {
+		t.Fatalf("stream source construction = %v", err)
+	}
+	if _, err := captured.PortalTicket.AccessTokenProvider(context.Background()); !errors.Is(err, fail) {
+		t.Fatalf("stream token provider error = %v", err)
+	}
+	eventResolveAccessToken = func(context.Context, string, string) (string, error) { return "token", nil }
+	for _, mode := range []string{"custom", "normal"} {
+		if _, err := newEventSource(context.Background(), "config", "client", "secret", eventStreamTicketOptions{Mode: mode}); err != nil {
+			t.Fatalf("stream source %s = %v", mode, err)
+		}
+	}
+
+	edition.Override(&edition.Hooks{Name: "test"})
+	eventNewEventSource = func(context.Context, string, string, string, eventStreamTicketOptions) (*source.DingtalkSource, error) {
+		return nil, fail
+	}
+	if err := runForegroundBus(context.Background(), consume.Config{}, "config", "secret", eventStreamTicketOptions{}); !errors.Is(err, fail) {
+		t.Fatalf("foreground source error = %v", err)
+	}
+	eventNewEventSource = func(context.Context, string, string, string, eventStreamTicketOptions) (*source.DingtalkSource, error) {
+		return &source.DingtalkSource{}, nil
+	}
+	eventBusRun = func(context.Context, bus.Config) error { return fail }
+	cfg := consume.Config{WorkDir: t.TempDir(), IPCEndpoint: filepath.Join(t.TempDir(), "bus.sock"), ClientID: "client"}
+	if err := runForegroundBus(context.Background(), cfg, "config", "secret", eventStreamTicketOptions{}); !errors.Is(err, fail) {
+		t.Fatalf("foreground bus error = %v", err)
+	}
+
+	configDir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+	if err := os.WriteFile(filepath.Join(configDir, "mcp_url"), []byte("https://pre-mcp.example.test"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DWS_STREAM_SOURCE_ID", "")
+	if got := defaultEventStreamSourceID(); got != "pre_open_source" {
+		t.Fatalf("pre stream source ID = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageEventBusCommandAllBranchesCoverage(t *testing.T) {
+	oldReady, oldPersonal, oldPersonalSource := eventReadyFDFromEnv, eventResolvePersonal, eventNewPersonalSource
+	oldCreds, oldSource, oldRun := eventResolveCredentials, eventNewEventSource, eventBusRun
+	oldMkdir, oldOpen := eventMkdirAll, eventOpenFile
+	t.Cleanup(func() {
+		eventReadyFDFromEnv, eventResolvePersonal, eventNewPersonalSource = oldReady, oldPersonal, oldPersonalSource
+		eventResolveCredentials, eventNewEventSource, eventBusRun = oldCreds, oldSource, oldRun
+		eventMkdirAll, eventOpenFile = oldMkdir, oldOpen
+	})
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	fail := errors.New("failure")
+	makeBus := func(kind string) *cobra.Command {
+		cmd := newEventBusCommand()
+		cmd.SetContext(context.Background())
+		_ = cmd.Flags().Set("source-kind", kind)
+		return cmd
+	}
+	read, write, err := os.Pipe()
+	if err != nil {
+		t.Fatal(err)
+	}
+	eventReadyFDFromEnv = func() *os.File { return write }
+	eventResolvePersonal = func(context.Context, string, string) (personal.Identity, error) { return personal.Identity{}, fail }
+	if err := makeBus(string(dwsevent.SourceKindPersonalStream)).RunE(makeBus(string(dwsevent.SourceKindPersonalStream)), nil); !errors.Is(err, fail) {
+		t.Fatalf("personal identity error = %v", err)
+	}
+	marker := make([]byte, 1)
+	_, _ = read.Read(marker)
+	_ = read.Close()
+	if marker[0] != 'E' {
+		t.Fatalf("ready failure marker = %q", marker)
+	}
+	eventReadyFDFromEnv = func() *os.File { return nil }
+	eventResolvePersonal = func(context.Context, string, string) (personal.Identity, error) {
+		return personal.Identity{AccessToken: "token", ClientID: "client", SourceID: "open"}, nil
+	}
+	eventNewPersonalSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) { return nil, fail }
+	personalCmd := makeBus(string(dwsevent.SourceKindPersonalStream))
+	_ = personalCmd.Flags().Set("client-id", "override")
+	if err := personalCmd.RunE(personalCmd, nil); !errors.Is(err, fail) {
+		t.Fatalf("personal stream source error = %v", err)
+	}
+	eventNewPersonalSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) {
+		return &source.PersonalSource{}, nil
+	}
+	eventMkdirAll = func(string, os.FileMode) error { return nil }
+	eventOpenFile = func(string, int, os.FileMode) (*os.File, error) { return os.CreateTemp(t.TempDir(), "bus-log") }
+	eventBusRun = func(context.Context, bus.Config) error { return fail }
+	if err := personalCmd.RunE(personalCmd, nil); !errors.Is(err, fail) {
+		t.Fatalf("personal bus run error = %v", err)
+	}
+
+	eventResolveCredentials = func(string, eventStreamTicketOptions) (string, string, error) { return "", "", fail }
+	if err := makeBus(string(dwsevent.SourceKindAppStream)).RunE(makeBus(string(dwsevent.SourceKindAppStream)), nil); !errors.Is(err, fail) {
+		t.Fatalf("app bus credentials error = %v", err)
+	}
+	eventResolveCredentials = func(string, eventStreamTicketOptions) (string, string, error) { return "client", "secret", nil }
+	eventNewEventSource = func(context.Context, string, string, string, eventStreamTicketOptions) (*source.DingtalkSource, error) {
+		return nil, fail
+	}
+	appCmd := makeBus("")
+	_ = appCmd.Flags().Set("client-id", "override")
+	if err := appCmd.RunE(appCmd, nil); !errors.Is(err, fail) {
+		t.Fatalf("app event source error = %v", err)
+	}
+	eventNewEventSource = func(context.Context, string, string, string, eventStreamTicketOptions) (*source.DingtalkSource, error) {
+		return &source.DingtalkSource{}, nil
+	}
+	if err := appCmd.RunE(appCmd, nil); !errors.Is(err, fail) {
+		t.Fatalf("app bus run error = %v", err)
+	}
+	eventMkdirAll = func(string, os.FileMode) error { return fail }
+	if err := appCmd.RunE(appCmd, nil); !errors.Is(err, fail) {
+		t.Fatalf("app bus run after log mkdir failure = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventListStatusCollectAndStopCoverage(t *testing.T) {
+	oldList, oldStatus, oldStopPersonal := eventRunPersonalList, eventRunPersonalStatus, eventRunPersonalStop
+	oldEnum, oldFind, oldQuery, oldStop := eventEnumerateBuses, eventFindBus, eventQueryEntry, eventStopBus
+	oldCreds := eventResolveAppCredentials
+	oldNormalize := eventNormalizeAs
+	t.Cleanup(func() {
+		eventRunPersonalList, eventRunPersonalStatus, eventRunPersonalStop = oldList, oldStatus, oldStopPersonal
+		eventEnumerateBuses, eventFindBus, eventQueryEntry, eventStopBus = oldEnum, oldFind, oldQuery, oldStop
+		eventResolveAppCredentials = oldCreds
+		eventNormalizeAs = oldNormalize
+	})
+	eventNormalizeAs = func(value string) (string, error) {
+		if strings.EqualFold(strings.TrimSpace(value), "app") {
+			return "app", nil
+		}
+		return normalizeEventAs(value)
+	}
+	fail := errors.New("failure")
+	eventRunPersonalList = func(*cobra.Command, personalListOptions) error { return fail }
+	list := newEventListCommand()
+	list.SetOut(io.Discard)
+	if err := list.RunE(list, nil); !errors.Is(err, fail) {
+		t.Fatalf("personal list error = %v", err)
+	}
+	eventRunPersonalStatus = func(*cobra.Command, personalStatusOptions) error { return fail }
+	status := newEventStatusCommand()
+	status.SetOut(io.Discard)
+	if err := status.RunE(status, nil); !errors.Is(err, fail) {
+		t.Fatalf("personal status error = %v", err)
+	}
+	eventRunPersonalStop = func(*cobra.Command, personalStopOptions) error { return fail }
+	stop := newEventStopCommand()
+	stop.SetOut(io.Discard)
+	stop.Flags().Bool("yes", false, "")
+	_ = stop.Flags().Set("yes", "true")
+	if err := stop.RunE(stop, []string{"sub"}); !errors.Is(err, fail) {
+		t.Fatalf("personal stop error = %v", err)
+	}
+
+	eventEnumerateBuses = func(string, string) ([]busctl.BusEntry, error) { return nil, fail }
+	if _, err := collectEntries(&cobra.Command{}, "client", false, true); !errors.Is(err, fail) {
+		t.Fatalf("all-editions collect error = %v", err)
+	}
+	if _, err := collectEntries(&cobra.Command{}, "client", true, false); !errors.Is(err, fail) {
+		t.Fatalf("all collect error = %v", err)
+	}
+	eventEnumerateBuses = func(string, string) ([]busctl.BusEntry, error) {
+		return []busctl.BusEntry{{ClientIDHash: "hash"}}, nil
+	}
+	eventQueryEntry = func(entry busctl.BusEntry) busctl.EntryStatus { return busctl.EntryStatus{Entry: entry} }
+	if got, err := collectEntries(&cobra.Command{}, "client", false, true); err != nil || len(got) != 1 {
+		t.Fatalf("all-editions entries = %#v, %v", got, err)
+	}
+	if got, err := collectEntries(&cobra.Command{}, "client", true, false); err != nil || len(got) != 1 {
+		t.Fatalf("all entries = %#v, %v", got, err)
+	}
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "", "", authpkg.CredentialSourceUnknown, authpkg.CredentialSourceUnknown, fail
+	}
+	if _, err := collectEntries(&cobra.Command{}, "", false, false); !errors.Is(err, fail) {
+		t.Fatalf("single credentials error = %v", err)
+	}
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "client", "secret", authpkg.CredentialSourceEnv, authpkg.CredentialSourceEnv, nil
+	}
+	eventFindBus = func(string, string, string) *busctl.BusEntry { return nil }
+	if got, err := collectEntries(&cobra.Command{}, "", false, false); err != nil || len(got) != 1 || got[0].Entry.State != busctl.BusStateNotRunning {
+		t.Fatalf("missing bus entry = %#v, %v", got, err)
+	}
+	eventFindBus = func(string, string, string) *busctl.BusEntry { return &busctl.BusEntry{} }
+	if got, err := collectEntries(&cobra.Command{}, "client", false, false); err != nil || len(got) != 1 || got[0].Entry.Meta == nil {
+		t.Fatalf("found bus entry = %#v, %v", got, err)
+	}
+
+	appList := newEventListCommand()
+	appList.SetOut(io.Discard)
+	_ = appList.Flags().Set("as", "app")
+	_ = appList.Flags().Set("client-id", "client")
+	if err := appList.RunE(appList, nil); err != nil {
+		t.Fatal(err)
+	}
+	rejectedList := newEventListCommand()
+	_ = rejectedList.Flags().Set("as", "app")
+	_ = rejectedList.Flags().Set("category", "chat")
+	if err := rejectedList.RunE(rejectedList, nil); err == nil {
+		t.Fatal("app list personal flag succeeded")
+	}
+	eventFindBus = func(string, string, string) *busctl.BusEntry {
+		return &busctl.BusEntry{State: busctl.BusStateOrphan, Meta: &bus.Meta{ClientID: "client"}}
+	}
+	eventQueryEntry = func(entry busctl.BusEntry) busctl.EntryStatus { return busctl.EntryStatus{Entry: entry} }
+	appStatus := newEventStatusCommand()
+	appStatus.SetOut(io.Discard)
+	_ = appStatus.Flags().Set("as", "app")
+	_ = appStatus.Flags().Set("client-id", "client")
+	_ = appStatus.Flags().Set("fail-on-orphan", "true")
+	if err := appStatus.RunE(appStatus, nil); err == nil {
+		t.Fatal("orphan event status succeeded")
+	}
+	rejectedStatus := newEventStatusCommand()
+	_ = rejectedStatus.Flags().Set("as", "app")
+	_ = rejectedStatus.Flags().Set("event", "key")
+	if err := rejectedStatus.RunE(rejectedStatus, nil); err == nil {
+		t.Fatal("app status personal flag succeeded")
+	}
+
+	appStop := func() *cobra.Command {
+		cmd := newEventStopCommand()
+		cmd.SetOut(io.Discard)
+		cmd.Flags().Bool("yes", true, "")
+		_ = cmd.Flags().Set("as", "app")
+		return cmd
+	}
+	changedStop := appStop()
+	_ = changedStop.Flags().Set("all", "true")
+	if err := changedStop.RunE(changedStop, nil); err == nil {
+		t.Fatal("app stop personal flag succeeded")
+	}
+	if err := appStop().RunE(appStop(), []string{"sub"}); err == nil {
+		t.Fatal("app subscribe ID succeeded")
+	}
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "", "", authpkg.CredentialSourceUnknown, authpkg.CredentialSourceUnknown, fail
+	}
+	if err := appStop().RunE(appStop(), nil); !errors.Is(err, fail) {
+		t.Fatalf("app stop credentials error = %v", err)
+	}
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "client", "secret", authpkg.CredentialSourceEnv, authpkg.CredentialSourceEnv, nil
+	}
+	eventStopBus = func(busctl.StopConfig) error { return busctl.ErrNotRunning }
+	if err := appStop().RunE(appStop(), nil); err != nil {
+		t.Fatalf("already stopped bus = %v", err)
+	}
+	eventStopBus = func(busctl.StopConfig) error { return fail }
+	if err := appStop().RunE(appStop(), nil); !errors.Is(err, fail) {
+		t.Fatalf("stop bus error = %v", err)
+	}
+	eventStopBus = func(busctl.StopConfig) error { return nil }
+	if err := appStop().RunE(appStop(), nil); err != nil {
+		t.Fatalf("stop bus success = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventCommandParentCoverage(t *testing.T) {
+	cmd := newEventCommand()
+	cmd.SetOut(io.Discard)
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(cmd.Use, "event") {
+		t.Fatal("event command use changed")
+	}
+}
+
+func TestCrossPlatformCoverageEventCommandPureAndRenderBranchesCoverage(t *testing.T) {
+	t.Setenv(authpkg.EnvClientID, "client")
+	t.Setenv(authpkg.EnvClientSecret, "secret")
+	if got := (eventStreamTicketOptions{Mode: "custom", SourceID: " source ", TicketURL: " https://ticket "}).spawnArgs(); len(got) != 6 {
+		t.Fatalf("stream spawn args = %#v", got)
+	}
+	if id, secret, err := resolveEventCredentials(t.TempDir(), eventStreamTicketOptions{}); err != nil || id != "client" || secret != "secret" {
+		t.Fatalf("app credentials = %q, %q, %v", id, secret, err)
+	}
+	if id, secret, err := resolveEventCredentials(t.TempDir(), eventStreamTicketOptions{Mode: "normal", SourceID: "source"}); err != nil || id != "portal-ticket-normal:source" || secret != "" {
+		t.Fatalf("portal credentials = %q, %q, %v", id, secret, err)
+	}
+	if eventStreamTicketURL(" https://ticket ") != "https://ticket" || eventStreamSourceID(" source ") != "source" {
+		t.Fatal("explicit event stream routing changed")
+	}
+	t.Setenv("DWS_STREAM_SOURCE_ID", "environment")
+	if defaultEventStreamSourceID() != "environment" {
+		t.Fatal("environment stream source ID ignored")
+	}
+
+	oldEdition := edition.Get()
+	edition.Override(&edition.Hooks{})
+	t.Cleanup(func() { edition.Override(oldEdition) })
+	if editionNameOrDefault() != "open" || sourceKindLabel("") != string(dwsevent.SourceKindAppStream) {
+		t.Fatal("default event labels changed")
+	}
+	if !strings.Contains(eventWorkDir("config", "open", "", "hash"), string(dwsevent.SourceKindAppStream)) {
+		t.Fatal("default event workdir changed")
+	}
+	if _, err := normalizeEventAs("bot"); err == nil {
+		t.Fatal("bot events became public unexpectedly")
+	}
+	flags := &cobra.Command{}
+	flags.Flags().Bool("all", false, "")
+	if err := rejectPersonalEventUnsupportedFlags(flags, "all"); err != nil {
+		t.Fatal(err)
+	}
+	_ = flags.Flags().Set("all", "true")
+	if err := rejectPersonalEventUnsupportedFlags(flags, "all"); err == nil {
+		t.Fatal("personal unsupported flag accepted")
+	}
+	if firstArg(nil) != "" || firstArg([]string{"value"}) != "value" || len(eventTypesWithDefault([]string{"type"})) != 1 {
+		t.Fatal("event helper defaults changed")
+	}
+	_ = eventTypesWithDefault(nil)
+
+	live := &eventtransport.StatusResp{
+		Bus:         eventtransport.StatusBus{UptimeSecs: 12},
+		SourceState: eventtransport.StatusSource{State: "connected", Source: "hook", ReconnectCount: 1},
+		Consumers: []eventtransport.StatusConsumer{
+			{PID: 1, Received: 2, Dropped: 3},
+			{PID: 2, EventTypes: []string{"chat"}, SubscribeID: "sub"},
+		},
+		PerEventTypeCounters: map[string]eventtransport.Counters{"chat": {Received: 2, Dropped: 1}},
+	}
+	entries := []busctl.EntryStatus{
+		{Entry: busctl.BusEntry{State: busctl.BusStateNotRunning, ClientIDHash: "not-running"}},
+		{Entry: busctl.BusEntry{State: busctl.BusStateOrphan, HolderPID: 3, Meta: &bus.Meta{ClientID: "orphan", SourceID: "source", StartedAt: time.Now()}}},
+		{Entry: busctl.BusEntry{State: busctl.BusStateRunning, HolderPID: 4, Meta: &bus.Meta{ClientID: "offline", StartedAt: time.Now().Add(-time.Minute)}}},
+		{Entry: busctl.BusEntry{State: busctl.BusStateRunning, HolderPID: 5, Meta: &bus.Meta{ClientID: "live"}}, Live: live},
+	}
+	if err := renderStatus(io.Discard, entries, "text"); err != nil {
+		t.Fatal(err)
+	}
+	if err := renderStatus(io.Discard, entries, "json"); err != nil {
+		t.Fatal(err)
+	}
+	if err := renderStatus(appFailWriter{err: errors.New("write")}, entries, "json"); err == nil {
+		t.Fatal("status JSON write failure succeeded")
+	}
+	listEntries := []listEntry{
+		{ClientIDHash: "hash", BusState: busctl.BusStateNotRunning},
+		{ClientID: "client", SourceKind: dwsevent.SourceKindPersonalStream, BusState: busctl.BusStateRunning, BusPID: 2, Consumers: live.Consumers},
+	}
+	if err := renderList(io.Discard, listEntries, "table"); err != nil {
+		t.Fatal(err)
+	}
+	if err := renderList(io.Discard, listEntries, "json"); err != nil {
+		t.Fatal(err)
+	}
+	if err := renderList(appFailWriter{err: errors.New("write")}, listEntries, "json"); err == nil {
+		t.Fatal("list JSON write failure succeeded")
+	}
+	if got := buildListEntry(busctl.EntryStatus{Entry: busctl.BusEntry{Meta: &bus.Meta{ClientID: "client"}}, Live: live}); len(got.Consumers) != 2 {
+		t.Fatalf("live list entry = %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageEventCommandClosureErrorBranchesCoverage(t *testing.T) {
+	oldNormalize := eventNormalizeAs
+	oldList, oldStatus := eventRunPersonalList, eventRunPersonalStatus
+	oldCreds, oldFind, oldQuery := eventResolveAppCredentials, eventFindBus, eventQueryEntry
+	t.Cleanup(func() {
+		eventNormalizeAs = oldNormalize
+		eventRunPersonalList, eventRunPersonalStatus = oldList, oldStatus
+		eventResolveAppCredentials, eventFindBus, eventQueryEntry = oldCreds, oldFind, oldQuery
+	})
+	eventNormalizeAs = func(value string) (string, error) {
+		if strings.TrimSpace(value) == "app" {
+			return "app", nil
+		}
+		return normalizeEventAs(value)
+	}
+	personalList := newEventListCommand()
+	_ = personalList.Flags().Set("all", "true")
+	if err := personalList.RunE(personalList, nil); err == nil {
+		t.Fatal("personal list app flag succeeded")
+	}
+	personalStatus := newEventStatusCommand()
+	_ = personalStatus.Flags().Set("fail-on-orphan", "true")
+	if err := personalStatus.RunE(personalStatus, nil); err == nil {
+		t.Fatal("personal status app flag succeeded")
+	}
+	fail := errors.New("failure")
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "", "", authpkg.CredentialSourceUnknown, authpkg.CredentialSourceUnknown, fail
+	}
+	appList := newEventListCommand()
+	_ = appList.Flags().Set("as", "app")
+	if err := appList.RunE(appList, nil); !errors.Is(err, fail) {
+		t.Fatalf("app list collect error = %v", err)
+	}
+	appStatus := newEventStatusCommand()
+	_ = appStatus.Flags().Set("as", "app")
+	if err := appStatus.RunE(appStatus, nil); !errors.Is(err, fail) {
+		t.Fatalf("app status collect error = %v", err)
+	}
+	eventResolveAppCredentials = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "client", "secret", authpkg.CredentialSourceEnv, authpkg.CredentialSourceEnv, nil
+	}
+	eventFindBus = func(string, string, string) *busctl.BusEntry {
+		return &busctl.BusEntry{State: busctl.BusStateRunning, Meta: &bus.Meta{ClientID: "client"}}
+	}
+	eventQueryEntry = func(entry busctl.BusEntry) busctl.EntryStatus { return busctl.EntryStatus{Entry: entry} }
+	appStatus = newEventStatusCommand()
+	appStatus.SetOut(io.Discard)
+	_ = appStatus.Flags().Set("as", "app")
+	_ = appStatus.Flags().Set("fail-on-orphan", "true")
+	if err := appStatus.RunE(appStatus, nil); err != nil {
+		t.Fatalf("healthy status with orphan gate = %v", err)
+	}
+	appStatus = newEventStatusCommand()
+	appStatus.SetOut(appFailWriter{err: errors.New("write")})
+	_ = appStatus.Flags().Set("as", "app")
+	_ = appStatus.Flags().Set("format", "json")
+	if err := appStatus.RunE(appStatus, nil); err == nil {
+		t.Fatal("status render failure should propagate")
+	}
+}

internal/app/event_command_test.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"testing"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
+)
+
+func writeEventTestAppConfig(t *testing.T, dir string, cfg authpkg.AppConfig) {
+	t.Helper()
+	raw, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal app config: %v", err)
+	}
+	if err := os.WriteFile(authpkg.GetAppConfigPath(dir), raw, 0o600); err != nil {
+		t.Fatalf("write app config: %v", err)
+	}
+}
+
+func TestResolveEventCredentials_PortalNormalAllowsMissingClientSecret(t *testing.T) {
+	t.Setenv(authpkg.EnvClientID, "")
+	t.Setenv(authpkg.EnvClientSecret, "")
+	dir := t.TempDir()
+
+	clientID, clientSecret, err := resolveEventCredentials(dir, eventStreamTicketOptions{
+		Mode:     source.PortalTicketModeNormal,
+		SourceID: "pre_open_source",
+	})
+	if err != nil {
+		t.Fatalf("resolveEventCredentials: %v", err)
+	}
+	if clientID != "portal-ticket-normal:pre_open_source" {
+		t.Fatalf("clientID = %q, want portal-ticket-normal:pre_open_source", clientID)
+	}
+	if clientSecret != "" {
+		t.Fatalf("clientSecret = %q, want empty", clientSecret)
+	}
+}
+
+func TestResolveEventCredentials_PortalCustomStillRequiresClientSecret(t *testing.T) {
+	t.Setenv(authpkg.EnvClientID, "")
+	t.Setenv(authpkg.EnvClientSecret, "")
+	dir := t.TempDir()
+	writeEventTestAppConfig(t, dir, authpkg.AppConfig{ClientID: "ding-custom"})
+
+	_, _, err := resolveEventCredentials(dir, eventStreamTicketOptions{
+		Mode: source.PortalTicketModeCustom,
+	})
+	if !errors.Is(err, authpkg.ErrClientSecretEmpty) {
+		t.Fatalf("err = %v, want ErrClientSecretEmpty", err)
+	}
+}

internal/app/event_personal_command.go

@@ -0,0 +1,941 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"text/tabwriter"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type commonConsumeOptions struct {
+	EventTypes []string
+	Filter     string
+	Compact    bool
+	FormatRaw  string
+	OutputDir  string
+	RoutesRaw  []string
+	MaxEvents  int
+	Duration   time.Duration
+	Quiet      bool
+	Force      bool
+	DryRun     bool
+	Foreground bool
+}
+
+type personalConsumeOptions struct {
+	Common           commonConsumeOptions
+	EventKey         string
+	DebugRawEvents   bool
+	SubscribeID      string
+	Rule             string
+	Name             string
+	FilterJSON       string
+	QueryCSV         string
+	TTL              time.Duration
+	Ephemeral        bool
+	UserID           string
+	OpenDingTalkID   string
+	GroupID          string
+	ControlBaseURL   string
+	StreamTicketMode string
+	StreamTicketURL  string
+	StreamSourceID   string
+}
+
+type personalListOptions struct {
+	Category       string
+	EnabledOnly    bool
+	IncludePending bool
+	Format         string
+}
+
+type personalStatusOptions struct {
+	EventKey       string
+	Status         string
+	SubscribeID    string
+	Format         string
+	ControlBaseURL string
+	StreamSourceID string
+}
+
+type personalStopOptions struct {
+	SubscribeID    string
+	All            bool
+	ControlBaseURL string
+	StreamSourceID string
+}
+
+type personalStreamSourceOptions struct {
+	ConfigDir        string
+	Identity         personal.Identity
+	TicketMode       string
+	TicketURL        string
+	ClientIDOverride string
+}
+
+var (
+	personalResolveEventIdentity        = resolvePersonalEventIdentity
+	personalEnsureSubscription          = ensurePersonalSubscription
+	personalGetSubscription             = (*personal.Client).GetSubscription
+	personalCreateSubscription          = (*personal.Client).CreateSubscription
+	personalDeleteSubscription          = (*personal.Client).DeleteSubscription
+	personalListSubscriptions           = (*personal.Client).ListSubscriptions
+	personalUpsertRunState              = personal.UpsertRunState
+	personalRemoveRunStates             = personal.RemoveRunStates
+	personalLoadRunStates               = personal.LoadRunStates
+	personalConsumeRun                  = consume.Run
+	personalValidateConsumeConfig       = consume.ValidateConfig
+	personalValidateNoOutputConflict    = consume.ValidateNoOutputConflict
+	personalNewStreamSource             = newPersonalStreamSource
+	personalBusRun                      = bus.Run
+	personalFindBusByIdentity           = busctl.FindBusByIdentity
+	personalQueryEntry                  = busctl.QueryEntry
+	personalQueryStatus                 = busctl.QueryStatus
+	personalStopBus                     = busctl.Stop
+	personalFindProcess                 = os.FindProcess
+	personalSignalProcess               = (*os.Process).Signal
+	personalResolveAuxiliaryAccessToken = ResolveAuxiliaryAccessToken
+	personalLoadTokenData               = authpkg.LoadTokenData
+	personalClientID                    = authpkg.ClientID
+	personalResolveAppCredentialsStrict = authpkg.ResolveAppCredentialsStrict
+)
+
+func newEventSchemaCommand() *cobra.Command {
+	var asIdentity string
+	var formatRaw string
+	cmd := &cobra.Command{
+		Use:               "schema <event_key>",
+		Short:             "显示事件 schema",
+		Args:              cobra.ExactArgs(1),
+		DisableAutoGenTag: true,
+		RunE: func(c *cobra.Command, args []string) error {
+			_, err := normalizeEventAs(asIdentity)
+			if err != nil {
+				return err
+			}
+			def, ok := personal.Lookup(args[0])
+			if !ok {
+				return fmt.Errorf("unknown personal event key %q", args[0])
+			}
+			if !def.Public {
+				return personal.PublicAvailabilityError(args[0])
+			}
+			return renderPersonalSchema(c.OutOrStdout(), def, formatRaw)
+		},
+	}
+	cmd.Flags().StringVar(&asIdentity, "as", "user", "事件身份: user")
+	cmd.Flags().StringVarP(&formatRaw, "format", "f", "json", "输出格式: json")
+	hideEventInternalFlags(cmd, "as")
+	cli.AnnotateRuntimePositionals(cmd, cli.RuntimeSchemaPositional{
+		Name:        "event_key",
+		Type:        "string",
+		Description: "要查询 payload 字段定义的个人事件码",
+		Required:    true,
+		Index:       0,
+	})
+	return cmd
+}
+
+func runPersonalEventList(c *cobra.Command, opts personalListOptions) error {
+	items := personal.Catalog(opts.Category, opts.EnabledOnly, opts.IncludePending)
+	if opts.Format == "json" {
+		enc := json.NewEncoder(c.OutOrStdout())
+		enc.SetIndent("", "  ")
+		return enc.Encode(items)
+	}
+	tw := tabwriter.NewWriter(c.OutOrStdout(), 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "EVENT_KEY\tRULE\tSTATUS\tDESCRIPTION")
+	for _, it := range items {
+		fmt.Fprintf(tw, "%s\t%s\t%s\t%s\n",
+			it.EventKey, it.RuleType, it.Status, it.Description)
+	}
+	return tw.Flush()
+}
+
+func renderPersonalSchema(w io.Writer, def personal.Definition, format string) error {
+	format = strings.ToLower(strings.TrimSpace(format))
+	if format == "" {
+		format = "json"
+	}
+	if format != "json" {
+		return fmt.Errorf("event schema only supports json output")
+	}
+	enc := json.NewEncoder(w)
+	enc.SetIndent("", "  ")
+	return enc.Encode(personal.BuildSchemaDocument(def))
+}
+
+func runPersonalEventConsume(c *cobra.Command, opts personalConsumeOptions) error {
+	ctx := c.Context()
+	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
+		return err
+	}
+	configDir := defaultConfigDir()
+	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	if err != nil {
+		return fmt.Errorf("event consume --as user: %w", err)
+	}
+	identityHash := dwsevent.IdentityHash(identity.Key())
+	editionName := editionNameOrDefault()
+	workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+	ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+
+	routes, err := consume.ParseRoutes(opts.Common.RoutesRaw)
+	if err != nil {
+		return fmt.Errorf("event consume --as user: %w", err)
+	}
+	rawFormat := ""
+	if f := c.Flags().Lookup("format"); f != nil && f.Changed {
+		rawFormat = opts.Common.FormatRaw
+	}
+	normalised, fellback := consume.NormalizeFormat(rawFormat)
+	if fellback && !opts.Common.Quiet {
+		fmt.Fprintf(c.ErrOrStderr(), "WARN: --format %q has no meaning for event stream; using ndjson\n", rawFormat)
+	}
+	projector := personalEventProjector(opts.DebugRawEvents)
+
+	if opts.Common.DryRun {
+		if strings.TrimSpace(opts.SubscribeID) == "" {
+			if err := validatePersonalSubscriptionOptions(opts); err != nil {
+				return fmt.Errorf("event consume --as user: %w", err)
+			}
+		}
+		cfg := consume.Config{
+			WorkDir:        workDir,
+			IPCEndpoint:    ipcEndpoint,
+			ClientID:       identity.ClientID,
+			SpawnExtraArgs: personalBusSpawnArgs(identity, opts.StreamTicketMode, personalEventStreamTicketURL(opts.StreamTicketURL, configDir)),
+			Compact:        opts.Common.Compact,
+			MaxEvents:      opts.Common.MaxEvents,
+			Duration:       opts.Common.Duration,
+			EventKey:       opts.EventKey,
+			Format:         normalised,
+			OutputDir:      opts.Common.OutputDir,
+			Routes:         routes,
+			Projector:      projector,
+			Stderr:         c.ErrOrStderr(),
+			Quiet:          opts.Common.Quiet,
+			Foreground:     opts.Common.Foreground,
+			Force:          opts.Common.Force,
+			DryRun:         true,
+		}
+		applyPersonalConsumeFilters(&cfg, opts, strings.TrimSpace(opts.SubscribeID), opts.EventKey)
+		return personalConsumeRun(ctx, cfg)
+	}
+
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
+	sub, eventKey, ruleType, err := personalEnsureSubscription(ctx, client, identity, opts)
+	if err != nil {
+		return fmt.Errorf("event consume --as user: %w", err)
+	}
+	if sub.SubscribeID == "" {
+		return fmt.Errorf("event consume --as user: server returned empty subscribe_id")
+	}
+	if err := personalUpsertRunState(workDir, personal.RunState{
+		SubscribeID:  sub.SubscribeID,
+		EventKey:     eventKey,
+		RuleType:     ruleType,
+		ClientID:     identity.ClientID,
+		SourceID:     identity.SourceID,
+		IdentityHash: identityHash,
+	}); err != nil {
+		return fmt.Errorf("event consume --as user: save run state: %w", err)
+	}
+	cleanup := func() {
+		_ = personalDeleteSubscription(client, context.Background(), sub.SubscribeID)
+		_ = personalRemoveRunStates(workDir, []string{sub.SubscribeID})
+	}
+	// Ownership-based cleanup: a subscription this run CREATED is
+	// unsubscribed on exit
+	// (any exit — SIGTERM / stdin-EOF / limit / timeout / error), so nothing
+	// leaks server-side. A subscription REUSED via --subscribe-id is left
+	// intact — the caller owns its lifecycle. --ephemeral forces cleanup
+	// either way.
+	selfCreated := strings.TrimSpace(opts.SubscribeID) == ""
+	if opts.Ephemeral || selfCreated {
+		defer cleanup()
+	}
+
+	cfg := consume.Config{
+		WorkDir:          workDir,
+		IPCEndpoint:      ipcEndpoint,
+		ClientID:         identity.ClientID,
+		SpawnExtraArgs:   personalBusSpawnArgs(identity, opts.StreamTicketMode, opts.StreamTicketURL),
+		Compact:          opts.Common.Compact,
+		MaxEvents:        opts.Common.MaxEvents,
+		Duration:         opts.Common.Duration,
+		EventKey:         eventKey,
+		Format:           normalised,
+		OutputDir:        opts.Common.OutputDir,
+		Routes:           routes,
+		Projector:        projector,
+		ReadySubscribeID: sub.SubscribeID,
+		Stdout:           c.OutOrStdout(),
+		Stderr:           c.ErrOrStderr(),
+		Quiet:            opts.Common.Quiet,
+		Foreground:       opts.Common.Foreground,
+		Force:            opts.Common.Force,
+	}
+	// Arm the stdin-EOF shutdown watcher only for a pipe-style, unbounded
+	// run (see shouldWatchStdinEOF).
+	applyEventConsumeStdin(&cfg, opts.Common.MaxEvents, opts.Common.Duration, c.InOrStdin())
+	applyPersonalConsumeFilters(&cfg, opts, sub.SubscribeID, eventKey)
+	if opts.DebugRawEvents && !opts.Common.Quiet {
+		fmt.Fprintf(c.ErrOrStderr(), "debug raw events enabled: local event filters disabled\nworkdir: %s\nbus_log: %s\n",
+			workDir, filepath.Join(workDir, "bus.log"))
+	}
+	if err := personalValidateConsumeConfig(cfg); err != nil {
+		return err
+	}
+	if o := c.Flags().Lookup("output"); o != nil && o.Changed {
+		if err := personalValidateNoOutputConflict(cfg, o.Value.String()); err != nil {
+			return err
+		}
+	}
+	if opts.Common.Foreground {
+		src, err := personalNewStreamSource(ctx, personalStreamSourceOptions{
+			ConfigDir:  configDir,
+			Identity:   identity,
+			TicketMode: opts.StreamTicketMode,
+			TicketURL:  opts.StreamTicketURL,
+		})
+		if err != nil {
+			if !opts.Ephemeral {
+				cleanup()
+			}
+			return err
+		}
+		busCfg := bus.Config{
+			WorkDir:      workDir,
+			IPCEndpoint:  ipcEndpoint,
+			ClientID:     identity.ClientID,
+			Edition:      editionName,
+			SourceKind:   dwsevent.SourceKindPersonalStream,
+			IdentityHash: identityHash,
+			SourceID:     identity.SourceID,
+			Source:       src,
+		}
+		bus.ApplyEnvTuning(&busCfg)
+		err = personalBusRun(ctx, busCfg)
+		if err != nil && !opts.Ephemeral {
+			cleanup()
+		}
+		return err
+	}
+	err = personalConsumeRun(ctx, cfg)
+	if err != nil && !opts.Ephemeral {
+		cleanup()
+	}
+	return err
+}
+
+func personalEventProjector(debugRawEvents bool) consume.Projector {
+	if debugRawEvents {
+		return func(ev transport.Event) (any, error) { return ev, nil }
+	}
+	return personal.ProjectOutput
+}
+
+func applyPersonalConsumeFilters(cfg *consume.Config, opts personalConsumeOptions, subscribeID, eventKey string) {
+	if cfg == nil {
+		return
+	}
+	if opts.DebugRawEvents {
+		cfg.EventTypes = nil
+		cfg.Filter = ""
+		cfg.SubscribeID = ""
+		return
+	}
+	cfg.EventTypes = personalEventTypes(eventKey, opts.Common.EventTypes)
+	cfg.Filter = opts.Common.Filter
+	cfg.SubscribeID = strings.TrimSpace(subscribeID)
+}
+
+func validatePersonalSubscriptionOptions(opts personalConsumeOptions) error {
+	if _, _, err := personal.BuildRuleParam(opts.EventKey, personal.RuleOptions{
+		RuleType:       opts.Rule,
+		UserID:         opts.UserID,
+		OpenDingTalkID: opts.OpenDingTalkID,
+		GroupID:        opts.GroupID,
+	}); err != nil {
+		return err
+	}
+	_, _, err := personal.BuildFilter(opts.FilterJSON, opts.QueryCSV)
+	return err
+}
+
+func ensurePersonalSubscription(ctx context.Context, client *personal.Client, identity personal.Identity, opts personalConsumeOptions) (*personal.Subscription, string, string, error) {
+	if strings.TrimSpace(opts.SubscribeID) != "" {
+		sub, err := personalGetSubscription(client, ctx, opts.SubscribeID)
+		if err != nil {
+			return nil, "", "", err
+		}
+		eventKey := firstNonEmptyPersonalString(opts.EventKey, sub.EventKey)
+		if eventKey == "" {
+			return nil, "", "", fmt.Errorf("event_key is required when --subscribe-id lookup returns no event_key")
+		}
+		if err := ensurePublicPersonalEvent(eventKey); err != nil {
+			return nil, "", "", err
+		}
+		ruleType := firstNonEmptyPersonalString(sub.RuleType, opts.Rule)
+		if ruleType == "" {
+			if def, ok := personal.Lookup(eventKey); ok {
+				ruleType = def.RuleType
+			}
+		}
+		sub.SubscribeID = strings.TrimSpace(opts.SubscribeID)
+		return sub, eventKey, ruleType, nil
+	}
+	if strings.TrimSpace(opts.EventKey) == "" {
+		return nil, "", "", fmt.Errorf("event_key is required unless --subscribe-id is provided")
+	}
+	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
+		return nil, "", "", err
+	}
+	ruleType, ruleParam, err := personal.BuildRuleParam(opts.EventKey, personal.RuleOptions{
+		RuleType:       opts.Rule,
+		UserID:         opts.UserID,
+		OpenDingTalkID: opts.OpenDingTalkID,
+		GroupID:        opts.GroupID,
+	})
+	if err != nil {
+		return nil, "", "", err
+	}
+	filter, filterCanonical, err := personal.BuildFilter(opts.FilterJSON, opts.QueryCSV)
+	if err != nil {
+		return nil, "", "", err
+	}
+	req := personal.CreateSubscriptionRequest{
+		EventKey:       opts.EventKey,
+		RuleType:       ruleType,
+		Name:           opts.Name,
+		RuleParam:      ruleParam,
+		Filter:         filter,
+		Delivery:       map[string]any{"mode": "stream"},
+		IdempotencyKey: personal.IdempotencyKey(identity, opts.EventKey, ruleType, ruleParam, filterCanonical),
+	}
+	if opts.TTL > 0 {
+		req.TTLSeconds = int64(opts.TTL.Seconds())
+	}
+	sub, err := personalCreateSubscription(client, ctx, req)
+	if err != nil {
+		return nil, "", "", err
+	}
+	return sub, opts.EventKey, ruleType, nil
+}
+
+func runPersonalEventStatus(c *cobra.Command, opts personalStatusOptions) error {
+	ctx := c.Context()
+	if err := ensurePublicPersonalEvent(opts.EventKey); err != nil {
+		return err
+	}
+	configDir := defaultConfigDir()
+	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	if err != nil {
+		return fmt.Errorf("event status --as user: %w", err)
+	}
+	identityHash := dwsevent.IdentityHash(identity.Key())
+	editionName := editionNameOrDefault()
+	workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+	entry := personalFindBusByIdentity(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+	var qs busctl.EntryStatus
+	if entry != nil {
+		qs = personalQueryEntry(*entry)
+	} else {
+		qs = busctl.EntryStatus{Entry: busctl.BusEntry{
+			WorkDir:      workDir,
+			Edition:      editionName,
+			SourceKind:   dwsevent.SourceKindPersonalStream,
+			ClientIDHash: identityHash,
+			IdentityHash: identityHash,
+			State:        busctl.BusStateNotRunning,
+			Meta: &bus.Meta{
+				ClientID:     identity.ClientID,
+				Edition:      editionName,
+				SourceKind:   dwsevent.SourceKindPersonalStream,
+				IdentityHash: identityHash,
+				SourceID:     identity.SourceID,
+			},
+		}}
+	}
+	status := opts.Status
+	if status == "" || status == "all" {
+		status = ""
+	}
+	subs, err := personalListSubscriptions(newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity), ctx, personal.ListOptions{
+		Status:      status,
+		EventKey:    opts.EventKey,
+		SubscribeID: opts.SubscribeID,
+	})
+	if err != nil {
+		return fmt.Errorf("event status --as user: %w", err)
+	}
+	if opts.Format == "json" {
+		enc := json.NewEncoder(c.OutOrStdout())
+		enc.SetIndent("", "  ")
+		return enc.Encode(map[string]any{
+			"identity":      redactedPersonalIdentity(identity, identityHash),
+			"subscriptions": subs,
+			"bus":           qs,
+		})
+	}
+	renderPersonalStatusText(c.OutOrStdout(), identity, identityHash, subs, qs)
+	return nil
+}
+
+func ensurePublicPersonalEvent(eventKey string) error {
+	eventKey = strings.TrimSpace(eventKey)
+	if eventKey == "" {
+		return nil
+	}
+	if def, ok := personal.Lookup(eventKey); ok && !def.Public {
+		return personal.PublicAvailabilityError(eventKey)
+	}
+	return nil
+}
+
+func renderPersonalStatusText(w io.Writer, identity personal.Identity, identityHash string, subs []personal.Subscription, qs busctl.EntryStatus) {
+	fmt.Fprintf(w, "Personal identity: corp=%s user=%s client=%s source=%s hash=%s\n",
+		displayIdentityPart(identity.CorpID), displayIdentityPart(identity.UserID), identity.ClientID, identity.SourceID, identityHash)
+	fmt.Fprintf(w, "Bus: %s", qs.Entry.State)
+	if qs.Entry.HolderPID > 0 {
+		fmt.Fprintf(w, " pid=%d", qs.Entry.HolderPID)
+	}
+	fmt.Fprintf(w, "\nWorkdir: %s\n", qs.Entry.WorkDir)
+	if len(subs) == 0 {
+		fmt.Fprintln(w, "Subscriptions: none")
+	} else {
+		tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+		fmt.Fprintln(tw, "SUBSCRIBE_ID\tEVENT_KEY\tRULE\tSTATUS\tSOURCE")
+		for _, sub := range subs {
+			fmt.Fprintf(tw, "%s\t%s\t%s\t%s\t%s\n",
+				sub.SubscribeID, sub.EventKey, sub.RuleType, sub.Status, sub.SourceID)
+		}
+		_ = tw.Flush()
+	}
+	renderPersonalConsumers(w, qs)
+}
+
+func renderPersonalConsumers(w io.Writer, qs busctl.EntryStatus) {
+	if qs.Entry.State != busctl.BusStateRunning {
+		fmt.Fprintln(w, "Consumers: none")
+		return
+	}
+	if qs.Live == nil {
+		fmt.Fprintln(w, "Consumers: unavailable (status RPC failed)")
+		return
+	}
+	if len(qs.Live.Consumers) == 0 {
+		fmt.Fprintln(w, "Consumers: none")
+		return
+	}
+	fmt.Fprintln(w, "Consumers:")
+	tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
+	fmt.Fprintln(tw, "PID\tEVENT_KEYS\tSUBSCRIBE_ID\tFILTER\tRECEIVED\tDROPPED")
+	for _, cs := range qs.Live.Consumers {
+		eventKeys := strings.Join(cs.EventTypes, ",")
+		if eventKeys == "" {
+			eventKeys = "(catch-all)"
+		}
+		subscribeID := displayPersonalStatusValue(cs.SubscribeID)
+		filter := displayPersonalStatusValue(cs.Filter)
+		fmt.Fprintf(tw, "%d\t%s\t%s\t%s\t%d\t%d\n",
+			cs.PID, eventKeys, subscribeID, filter, cs.Received, cs.Dropped)
+	}
+	_ = tw.Flush()
+}
+
+func displayPersonalStatusValue(v string) string {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return "-"
+	}
+	return v
+}
+
+func runPersonalEventStop(c *cobra.Command, opts personalStopOptions) error {
+	ctx := c.Context()
+	explicitSubscribeID := strings.TrimSpace(opts.SubscribeID)
+	isSingleTarget := explicitSubscribeID != ""
+	if explicitSubscribeID != "" && opts.All {
+		return fmt.Errorf("event stop --as user: subscribe_id and --all are mutually exclusive")
+	}
+	if explicitSubscribeID == "" && !opts.All {
+		return fmt.Errorf("event stop --as user: subscribe_id is required unless --all is set")
+	}
+
+	configDir := defaultConfigDir()
+	identity, err := personalResolveEventIdentity(ctx, configDir, opts.StreamSourceID)
+	if err != nil {
+		return fmt.Errorf("event stop --as user: %w", err)
+	}
+	identityHash := dwsevent.IdentityHash(identity.Key())
+	editionName := editionNameOrDefault()
+	workDir := eventWorkDir(configDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+	ipcEndpoint := defaultIPCEndpoint(workDir, editionName, dwsevent.SourceKindPersonalStream, identityHash)
+	subscribeIDs, err := personalStopTargets(workDir, explicitSubscribeID, opts.All)
+	if err != nil {
+		return fmt.Errorf("event stop --as user: %w", err)
+	}
+	client := newPersonalEventControlClient(configDir, personalEventControlBaseURL(opts.ControlBaseURL, configDir), identity)
+	for _, id := range subscribeIDs {
+		if err := personalDeleteSubscription(client, ctx, id); err != nil {
+			return fmt.Errorf("event stop --as user: cancel subscription %s: %w", id, err)
+		}
+	}
+	if err := personalRemoveRunStates(workDir, subscribeIDs); err != nil {
+		return fmt.Errorf("event stop --as user: update local state: %w", err)
+	}
+	if err := interruptPersonalConsumers(ipcEndpoint, subscribeIDs); err != nil {
+		fmt.Fprintf(c.ErrOrStderr(), "WARN: failed to stop matching local consume process: %v\n", err)
+	}
+
+	remaining, err := personalLoadRunStates(workDir)
+	if err != nil {
+		return fmt.Errorf("event stop --as user: load remaining local state: %w", err)
+	}
+	if len(remaining) > 0 {
+		printPersonalStopResult(c.OutOrStdout(), subscribeIDs, isSingleTarget, "personal bus still running")
+		return nil
+	}
+
+	busState := "personal bus stopped"
+	if err := personalStopBus(busctl.StopConfig{WorkDir: workDir}); err != nil {
+		if errors.Is(err, busctl.ErrNotRunning) {
+			busState = "personal bus is not running"
+		} else {
+			return err
+		}
+	}
+	printPersonalStopResult(c.OutOrStdout(), subscribeIDs, isSingleTarget, busState)
+	return nil
+}
+
+func personalStopTargets(workDir, explicit string, all bool) ([]string, error) {
+	explicit = strings.TrimSpace(explicit)
+	if explicit != "" && all {
+		return nil, fmt.Errorf("subscribe_id and --all are mutually exclusive")
+	}
+	if explicit != "" {
+		return []string{explicit}, nil
+	}
+	if !all {
+		return nil, fmt.Errorf("subscribe_id is required unless --all is set")
+	}
+	states, err := personalLoadRunStates(workDir)
+	if err != nil {
+		return nil, err
+	}
+	ids := make([]string, 0, len(states))
+	for _, st := range states {
+		if st.SubscribeID != "" {
+			ids = append(ids, st.SubscribeID)
+		}
+	}
+	sort.Strings(ids)
+	return ids, nil
+}
+
+func interruptPersonalConsumers(ipcEndpoint string, subscribeIDs []string) error {
+	targets := make(map[string]struct{}, len(subscribeIDs))
+	for _, id := range subscribeIDs {
+		id = strings.TrimSpace(id)
+		if id != "" {
+			targets[id] = struct{}{}
+		}
+	}
+	if ipcEndpoint == "" || len(targets) == 0 {
+		return nil
+	}
+	status, err := personalQueryStatus(ipcEndpoint)
+	if err != nil {
+		return nil
+	}
+	signalled := make(map[int]struct{})
+	for _, consumer := range status.Consumers {
+		if _, ok := targets[strings.TrimSpace(consumer.SubscribeID)]; !ok {
+			continue
+		}
+		if consumer.PID <= 0 || consumer.PID == os.Getpid() {
+			continue
+		}
+		if _, ok := signalled[consumer.PID]; ok {
+			continue
+		}
+		proc, err := personalFindProcess(consumer.PID)
+		if err != nil {
+			return fmt.Errorf("find consume pid=%d: %w", consumer.PID, err)
+		}
+		if err := personalSignalProcess(proc, os.Interrupt); err != nil && !errors.Is(err, os.ErrProcessDone) {
+			return fmt.Errorf("signal consume pid=%d: %w", consumer.PID, err)
+		}
+		signalled[consumer.PID] = struct{}{}
+	}
+	return nil
+}
+
+func printPersonalStopResult(w io.Writer, subscribeIDs []string, single bool, busState string) {
+	if single && len(subscribeIDs) == 1 {
+		fmt.Fprintf(w, "cancelled personal subscription %s; %s\n", subscribeIDs[0], busState)
+		return
+	}
+	fmt.Fprintf(w, "cancelled %d personal subscription(s); %s\n", len(subscribeIDs), busState)
+}
+
+func resolvePersonalEventIdentity(ctx context.Context, configDir string, sourceIDOverride string) (personal.Identity, error) {
+	accessToken, err := personalResolveAuxiliaryAccessToken(ctx, configDir, "")
+	if err != nil {
+		return personal.Identity{}, err
+	}
+	tokenData, err := personalLoadTokenData(configDir)
+	if err != nil && !errors.Is(err, authpkg.ErrTokenDataNotFound) {
+		return personal.Identity{}, fmt.Errorf("load OAuth identity metadata: %w", err)
+	}
+	var corpID, userID, clientID, refreshToken string
+	if tokenData != nil {
+		corpID = tokenData.CorpID
+		userID = tokenData.UserID
+		clientID = tokenData.ClientID
+		refreshToken = tokenData.RefreshToken
+	}
+	if corpID == "" {
+		corpID = resolveRuntimeDefault(ctx, "$corpId")
+	}
+	if userID == "" {
+		userID = resolveRuntimeDefault(ctx, "$currentUserId")
+	}
+	if clientID == "" {
+		clientID = personalClientID()
+	}
+	if clientID == "" {
+		if id, _, _, _, err := personalResolveAppCredentialsStrict(configDir); err == nil {
+			clientID = id
+		}
+	}
+	if clientID == "" {
+		return personal.Identity{}, fmt.Errorf("cannot resolve OAuth client_id for personal events")
+	}
+	sourceID := strings.TrimSpace(sourceIDOverride)
+	if sourceID == "" {
+		sourceID = personalEventStreamSourceID("")
+	}
+	localSubject := ""
+	if strings.TrimSpace(corpID) == "" || strings.TrimSpace(userID) == "" {
+		localSubject = personalTokenSubject("refresh", refreshToken)
+		if localSubject == "" {
+			localSubject = personalTokenSubject("access", accessToken)
+		}
+	}
+	return personal.Identity{
+		AccessToken:  accessToken,
+		LocalSubject: localSubject,
+		CorpID:       corpID,
+		UserID:       userID,
+		ClientID:     clientID,
+		SourceID:     sourceID,
+	}, nil
+}
+
+func newPersonalEventControlClient(configDir, baseURL string, identity personal.Identity) *personal.Client {
+	identity.AccessToken = ""
+	client := personal.NewClient(baseURL, identity)
+	client.AccessTokenProvider = func(ctx context.Context) (string, error) {
+		return personalResolveAuxiliaryAccessToken(ctx, configDir, "")
+	}
+	return client
+}
+
+func personalTokenSubject(kind, token string) string {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(token))
+	return strings.TrimSpace(kind) + ":" + hex.EncodeToString(sum[:])
+}
+
+func resolveRuntimeDefault(ctx context.Context, key string) string {
+	if fnMap := edition.Get().RuntimeDefaults; fnMap != nil {
+		if fn := fnMap()[key]; fn != nil {
+			if v, ok := fn(ctx); ok {
+				return strings.TrimSpace(v)
+			}
+		}
+	}
+	return ""
+}
+
+func newPersonalStreamSource(ctx context.Context, opts personalStreamSourceOptions) (*source.PersonalSource, error) {
+	mode := strings.TrimSpace(opts.TicketMode)
+	if mode == "" {
+		mode = "normal"
+	}
+	if mode != "normal" && mode != "custom" {
+		return nil, fmt.Errorf("stream ticket mode must be normal or custom")
+	}
+	ticketURL := strings.TrimSpace(opts.TicketURL)
+	if ticketURL == "" {
+		ticketURL = personalEventStreamTicketURL("", opts.ConfigDir)
+	}
+	clientID := opts.Identity.ClientID
+	clientSecret := ""
+	if mode == "custom" {
+		resolvedID, secret, _, _, err := personalResolveAppCredentialsStrict(opts.ConfigDir)
+		if err != nil {
+			return nil, err
+		}
+		if opts.ClientIDOverride != "" {
+			clientID = opts.ClientIDOverride
+		} else if clientID == "" {
+			clientID = resolvedID
+		}
+		clientSecret = secret
+	}
+	_ = ctx
+	return source.NewPersonal(source.PersonalConfig{
+		AccessTokenProvider: func(ctx context.Context) (string, error) {
+			return personalResolveAuxiliaryAccessToken(ctx, opts.ConfigDir, "")
+		},
+		ClientID:     clientID,
+		ClientSecret: clientSecret,
+		SourceID:     opts.Identity.SourceID,
+		TicketURL:    ticketURL,
+		TicketMode:   mode,
+		HTTPClient:   &http.Client{Timeout: 30 * time.Second},
+	})
+}
+
+func personalBusSpawnArgs(identity personal.Identity, ticketMode, ticketURL string) []string {
+	args := []string{
+		"--source-kind", string(dwsevent.SourceKindPersonalStream),
+		"--stream-source-id", identity.SourceID,
+	}
+	// Forward the exact account so the detached _bus child resolves the same
+	// credentials as the parent, including when one organization has multiple
+	// logged-in users.
+	if cid := strings.TrimSpace(identity.CorpID); cid != "" {
+		args = append(args, "--profile", authpkg.ProfileSelector(authpkg.Profile{
+			CorpID: identity.CorpID,
+			UserID: identity.UserID,
+		}))
+	}
+	if strings.TrimSpace(ticketMode) != "" {
+		args = append(args, "--stream-ticket-mode", ticketMode)
+	}
+	if strings.TrimSpace(ticketURL) != "" {
+		args = append(args, "--stream-ticket-url", ticketURL)
+	}
+	return args
+}
+
+func personalEventTypes(eventKey string, explicit []string) []string {
+	if len(explicit) > 0 {
+		return explicit
+	}
+	if strings.TrimSpace(eventKey) == "" {
+		return nil
+	}
+	return []string{eventKey}
+}
+
+func redactedPersonalIdentity(identity personal.Identity, identityHash string) map[string]string {
+	return map[string]string{
+		"corp_id":       displayIdentityPart(identity.CorpID),
+		"user_id":       displayIdentityPart(identity.UserID),
+		"client_id":     identity.ClientID,
+		"source_id":     identity.SourceID,
+		"identity_hash": identityHash,
+	}
+}
+
+func displayIdentityPart(v string) string {
+	v = strings.TrimSpace(v)
+	if v == "" {
+		return "unknown"
+	}
+	return v
+}
+
+func firstNonEmptyPersonalString(values ...string) string {
+	for _, v := range values {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+func personalEventControlBaseURL(raw, configDir string) string {
+	if v := strings.TrimSpace(raw); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return personalEventMCPBaseURL(configDir) + personal.DefaultBasePath
+}
+
+func personalEventStreamTicketURL(raw, configDir string) string {
+	if v := strings.TrimSpace(raw); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return personalEventMCPBaseURL(configDir) + "/stream/connections/ticket"
+}
+
+func personalEventStreamSourceID(raw string) string {
+	if v := strings.TrimSpace(raw); v != "" {
+		return v
+	}
+	return strings.TrimSpace(edition.PersonalEventSourceID())
+}
+
+func personalEventMCPBaseURL(configDir string) string {
+	if v := configuredMCPBaseURL(configDir); v != "" {
+		return strings.TrimRight(v, "/")
+	}
+	return config.DefaultMCPBaseURL
+}
+
+func configuredMCPBaseURL(configDir string) string {
+	if strings.TrimSpace(configDir) == "" {
+		configDir = defaultConfigDir()
+	}
+	data, err := os.ReadFile(filepath.Join(configDir, "mcp_url"))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(data))
+}

internal/app/event_personal_debug_test.go

@@ -0,0 +1,160 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+func TestApplyPersonalConsumeFiltersDebugRawEvents(t *testing.T) {
+	cfg := consume.Config{EventKey: personal.EventSingleChat, ReadySubscribeID: "sub-1"}
+	opts := personalConsumeOptions{
+		DebugRawEvents: true,
+		Common: commonConsumeOptions{
+			EventTypes: []string{"should-not-survive"},
+			Filter:     "^should-not-survive$",
+		},
+	}
+	applyPersonalConsumeFilters(&cfg, opts, "sub-1", "user_im_message_receive_o2o")
+	if cfg.EventTypes != nil || cfg.Filter != "" || cfg.SubscribeID != "" {
+		t.Fatalf("raw debug filters = eventTypes=%#v filter=%q subscribeID=%q, want catch-all", cfg.EventTypes, cfg.Filter, cfg.SubscribeID)
+	}
+	if cfg.EventKey != personal.EventSingleChat || cfg.ReadySubscribeID != "sub-1" {
+		t.Fatalf("raw debug cleared ready identity: eventKey=%q subscribeID=%q", cfg.EventKey, cfg.ReadySubscribeID)
+	}
+}
+
+func TestApplyPersonalConsumeFiltersDefault(t *testing.T) {
+	cfg := consume.Config{}
+	opts := personalConsumeOptions{Common: commonConsumeOptions{Filter: "^user_im_"}}
+	applyPersonalConsumeFilters(&cfg, opts, "sub-1", "user_im_message_receive_o2o")
+	if len(cfg.EventTypes) != 1 || cfg.EventTypes[0] != "user_im_message_receive_o2o" {
+		t.Fatalf("eventTypes = %#v", cfg.EventTypes)
+	}
+	if cfg.Filter != "^user_im_" || cfg.SubscribeID != "sub-1" {
+		t.Fatalf("filter=%q subscribeID=%q", cfg.Filter, cfg.SubscribeID)
+	}
+}
+
+func TestPersonalEventProjectorUsesRawEnvelopeForDebug(t *testing.T) {
+	if personalEventProjector(false) == nil {
+		t.Fatal("normal personal consume projector = nil")
+	}
+	projector := personalEventProjector(true)
+	if projector == nil {
+		t.Fatal("debug raw personal consume projector = nil")
+	}
+	ev := transport.Event{
+		EventID: "raw-event",
+		Data:    `{"payload":{"uid":100001,"bizid":"internal-bizid"}}`,
+		Headers: map[string]string{"TOPIC": "raw"},
+	}
+	projected, err := projector(ev)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, ok := projected.(transport.Event); !ok || got.EventID != ev.EventID || got.Data != ev.Data || got.Headers["TOPIC"] != "raw" {
+		t.Fatalf("debug raw projection = %#v", projected)
+	}
+}
+
+func TestEventConsumeDebugRawEventsRequiresUserMode(t *testing.T) {
+	cmd := newEventConsumeCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--as", "app", "--debug-raw-events"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+		t.Fatalf("Execute() error = %v, want public availability guard", err)
+	}
+}
+
+func TestEventConsumeAsAppRejectedBeforeEventKeyValidation(t *testing.T) {
+	cmd := newEventConsumeCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--as", "app", personal.EventSingleChat})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+		t.Fatalf("Execute() error = %v, want public availability guard", err)
+	}
+}
+
+func TestEventConsumePersonalParamSpecFlags(t *testing.T) {
+	cmd := newEventConsumeCommand()
+	for _, name := range []string{"user", "open-dingtalk-id", "group", "query"} {
+		if cmd.Flags().Lookup(name) == nil {
+			t.Fatalf("flag --%s is not registered", name)
+		}
+	}
+	for _, name := range []string{
+		"peer-user-id",
+		"peer-union-id",
+		"sender-user-id",
+		"sender-union-id",
+		"open-conversation-id",
+		"keyword",
+		"odid",
+	} {
+		if cmd.Flags().Lookup(name) != nil {
+			t.Fatalf("retired flag --%s is still registered", name)
+		}
+	}
+}
+
+func TestEventConsumeRetiredPersonalFlagsAreUnknown(t *testing.T) {
+	for _, name := range []string{
+		"peer-user-id",
+		"peer-union-id",
+		"sender-user-id",
+		"sender-union-id",
+		"open-conversation-id",
+		"keyword",
+		"odid",
+	} {
+		t.Run(name, func(t *testing.T) {
+			cmd := newEventConsumeCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			cmd.SetArgs([]string{personal.EventSingleChat, "--" + name, "x"})
+			err := cmd.Execute()
+			if err == nil || !strings.Contains(err.Error(), "unknown flag: --"+name) {
+				t.Fatalf("Execute() error = %v, want unknown flag", err)
+			}
+		})
+	}
+}
+
+func TestEventConsumeAsAppRejectedBeforePersonalParamSpecFlags(t *testing.T) {
+	for _, args := range [][]string{
+		{"--as", "app", "--user", "test-user-001"},
+		{"--as", "app", "--open-dingtalk-id", "open-user-1"},
+		{"--as", "app", "--group", "cid"},
+		{"--as", "app", "--query", "报警"},
+	} {
+		cmd := newEventConsumeCommand()
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		cmd.SetArgs(args)
+		err := cmd.Execute()
+		if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+			t.Fatalf("Execute(%v) error = %v, want public availability guard", args, err)
+		}
+	}
+}

internal/app/event_personal_full_coverage_test.go

@@ -0,0 +1,370 @@
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	dwsevent "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/bus"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/source"
+	eventtransport "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoveragePersonalEventRemainingSchemaAndSubscriptionCoverage(t *testing.T) {
+	for _, args := range [][]string{
+		{"known", "--as", "app"},
+		{"not-a-real-event"},
+	} {
+		cmd := newEventSchemaCommand()
+		cmd.SetOut(io.Discard)
+		cmd.SetErr(io.Discard)
+		cmd.SetArgs(args)
+		if err := cmd.Execute(); err == nil {
+			t.Fatalf("schema args %#v succeeded", args)
+		}
+	}
+
+	oldGet := personalGetSubscription
+	oldCreate := personalCreateSubscription
+	t.Cleanup(func() {
+		personalGetSubscription = oldGet
+		personalCreateSubscription = oldCreate
+	})
+	client := personal.NewClient("https://example.test", personal.Identity{})
+	wantErr := errors.New("subscription")
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) { return nil, wantErr }
+	if _, _, _, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("get subscription error = %v", err)
+	}
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return &personal.Subscription{}, nil
+	}
+	if _, _, _, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); err == nil {
+		t.Fatal("empty subscription event key succeeded")
+	}
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return &personal.Subscription{EventKey: personal.EventFromUser}, nil
+	}
+	if _, key, rule, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); err != nil || key != personal.EventFromUser || rule != "sender" {
+		t.Fatalf("sender subscription = %q %q, %v", key, rule, err)
+	}
+	personalGetSubscription = func(*personal.Client, context.Context, string) (*personal.Subscription, error) {
+		return &personal.Subscription{EventKey: personal.EventMention}, nil
+	}
+	if _, _, rule, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{SubscribeID: "sub"}); err != nil || rule == "" {
+		t.Fatalf("default subscription rule = %q, %v", rule, err)
+	}
+	personalCreateSubscription = func(*personal.Client, context.Context, personal.CreateSubscriptionRequest) (*personal.Subscription, error) {
+		return nil, wantErr
+	}
+	if _, _, _, err := ensurePersonalSubscription(context.Background(), client, personal.Identity{}, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("create subscription error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoveragePersonalEventRemainingConsumeCoverage(t *testing.T) {
+	oldIdentity := personalResolveEventIdentity
+	oldEnsure := personalEnsureSubscription
+	oldUpsert := personalUpsertRunState
+	oldDelete := personalDeleteSubscription
+	oldRemove := personalRemoveRunStates
+	oldConsume := personalConsumeRun
+	oldValidate := personalValidateConsumeConfig
+	oldConflict := personalValidateNoOutputConflict
+	oldNewSource := personalNewStreamSource
+	oldBusRun := personalBusRun
+	t.Cleanup(func() {
+		personalResolveEventIdentity = oldIdentity
+		personalEnsureSubscription = oldEnsure
+		personalUpsertRunState = oldUpsert
+		personalDeleteSubscription = oldDelete
+		personalRemoveRunStates = oldRemove
+		personalConsumeRun = oldConsume
+		personalValidateConsumeConfig = oldValidate
+		personalValidateNoOutputConflict = oldConflict
+		personalNewStreamSource = oldNewSource
+		personalBusRun = oldBusRun
+	})
+
+	wantErr := errors.New("consume")
+	cmd := newPersonalCoverageCommand()
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) { return personal.Identity{}, wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("identity error = %v", err)
+	}
+	identity := personal.Identity{AccessToken: "token", CorpID: "corp", UserID: "user", ClientID: "client", SourceID: "source"}
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) { return identity, nil }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, Common: commonConsumeOptions{RoutesRaw: []string{"bad-route"}}}); err == nil {
+		t.Fatal("invalid route succeeded")
+	}
+	personalConsumeRun = func(context.Context, consume.Config) error { return wantErr }
+	_ = cmd.Flags().Set("format", "table")
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, Common: commonConsumeOptions{DryRun: true, FormatRaw: "bogus"}}); !errors.Is(err, wantErr) {
+		t.Fatalf("dry-run consume error = %v", err)
+	}
+
+	personalEnsureSubscription = func(context.Context, *personal.Client, personal.Identity, personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		return nil, "", "", wantErr
+	}
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("ensure subscription error = %v", err)
+	}
+	personalEnsureSubscription = func(context.Context, *personal.Client, personal.Identity, personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		return &personal.Subscription{}, personal.EventMention, "at", nil
+	}
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); err == nil || !strings.Contains(err.Error(), "empty subscribe_id") {
+		t.Fatalf("empty subscription = %v", err)
+	}
+	personalEnsureSubscription = func(context.Context, *personal.Client, personal.Identity, personalConsumeOptions) (*personal.Subscription, string, string, error) {
+		return &personal.Subscription{SubscribeID: "sub"}, personal.EventMention, "at", nil
+	}
+	personalUpsertRunState = func(string, personal.RunState) error { return wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("state upsert error = %v", err)
+	}
+
+	deletes := 0
+	personalUpsertRunState = func(string, personal.RunState) error { return nil }
+	personalDeleteSubscription = func(*personal.Client, context.Context, string) error { deletes++; return nil }
+	personalRemoveRunStates = func(string, []string) error { return nil }
+	personalValidateConsumeConfig = func(consume.Config) error { return wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, DebugRawEvents: true}); !errors.Is(err, wantErr) {
+		t.Fatalf("validate error = %v", err)
+	}
+	personalValidateConsumeConfig = func(consume.Config) error { return nil }
+	_ = cmd.Flags().Set("output", "file")
+	personalValidateNoOutputConflict = func(consume.Config, string) error { return wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("output conflict = %v", err)
+	}
+	personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+
+	personalNewStreamSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) {
+		return nil, wantErr
+	}
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, Common: commonConsumeOptions{Foreground: true}}); !errors.Is(err, wantErr) || deletes == 0 {
+		t.Fatalf("foreground source error = %v deletes=%d", err, deletes)
+	}
+	before := deletes
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, Ephemeral: true, Common: commonConsumeOptions{Foreground: true}}); !errors.Is(err, wantErr) || deletes == before {
+		t.Fatalf("ephemeral source error = %v deletes=%d", err, deletes)
+	}
+	personalNewStreamSource = func(context.Context, personalStreamSourceOptions) (*source.PersonalSource, error) { return nil, nil }
+	personalBusRun = func(context.Context, bus.Config) error { return wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention, Common: commonConsumeOptions{Foreground: true}}); !errors.Is(err, wantErr) {
+		t.Fatalf("bus run error = %v", err)
+	}
+	personalConsumeRun = func(context.Context, consume.Config) error { return wantErr }
+	if err := runPersonalEventConsume(cmd, personalConsumeOptions{EventKey: personal.EventMention}); !errors.Is(err, wantErr) {
+		t.Fatalf("background consume error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoveragePersonalEventRemainingStatusStopAndInterruptCoverage(t *testing.T) {
+	oldIdentity := personalResolveEventIdentity
+	oldFindBus := personalFindBusByIdentity
+	oldQueryEntry := personalQueryEntry
+	oldList := personalListSubscriptions
+	oldDelete := personalDeleteSubscription
+	oldRemove := personalRemoveRunStates
+	oldLoad := personalLoadRunStates
+	oldStop := personalStopBus
+	oldQueryStatus := personalQueryStatus
+	oldFindProcess := personalFindProcess
+	oldSignal := personalSignalProcess
+	t.Cleanup(func() {
+		personalResolveEventIdentity = oldIdentity
+		personalFindBusByIdentity = oldFindBus
+		personalQueryEntry = oldQueryEntry
+		personalListSubscriptions = oldList
+		personalDeleteSubscription = oldDelete
+		personalRemoveRunStates = oldRemove
+		personalLoadRunStates = oldLoad
+		personalStopBus = oldStop
+		personalQueryStatus = oldQueryStatus
+		personalFindProcess = oldFindProcess
+		personalSignalProcess = oldSignal
+	})
+
+	wantErr := errors.New("status-stop")
+	cmd := newPersonalCoverageCommand()
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) { return personal.Identity{}, wantErr }
+	if err := runPersonalEventStatus(cmd, personalStatusOptions{}); !errors.Is(err, wantErr) {
+		t.Fatalf("status identity error = %v", err)
+	}
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("stop identity error = %v", err)
+	}
+	identity := personal.Identity{ClientID: "client", SourceID: "source"}
+	personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) { return identity, nil }
+	entry := &busctl.BusEntry{State: busctl.BusStateRunning}
+	personalFindBusByIdentity = func(string, string, dwsevent.SourceKind, string) *busctl.BusEntry { return entry }
+	personalQueryEntry = func(busctl.BusEntry) busctl.EntryStatus { return busctl.EntryStatus{Entry: *entry} }
+	personalListSubscriptions = func(*personal.Client, context.Context, personal.ListOptions) ([]personal.Subscription, error) {
+		return nil, wantErr
+	}
+	if err := runPersonalEventStatus(cmd, personalStatusOptions{}); !errors.Is(err, wantErr) {
+		t.Fatalf("status list error = %v", err)
+	}
+	personalListSubscriptions = func(*personal.Client, context.Context, personal.ListOptions) ([]personal.Subscription, error) {
+		return nil, nil
+	}
+	if err := runPersonalEventStatus(cmd, personalStatusOptions{Status: "all", Format: "json"}); err != nil {
+		t.Fatalf("status entry JSON = %v", err)
+	}
+
+	personalLoadRunStates = func(string) ([]personal.RunState, error) { return nil, wantErr }
+	if err := runPersonalEventStop(cmd, personalStopOptions{All: true}); !errors.Is(err, wantErr) {
+		t.Fatalf("stop targets error = %v", err)
+	}
+	personalDeleteSubscription = func(*personal.Client, context.Context, string) error { return wantErr }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("delete error = %v", err)
+	}
+	personalDeleteSubscription = func(*personal.Client, context.Context, string) error { return nil }
+	personalRemoveRunStates = func(string, []string) error { return wantErr }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("remove error = %v", err)
+	}
+	personalRemoveRunStates = func(string, []string) error { return nil }
+	personalQueryStatus = func(string) (*eventtransport.StatusResp, error) { return nil, wantErr }
+	personalLoadRunStates = func(string) ([]personal.RunState, error) { return nil, wantErr }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("remaining state error = %v", err)
+	}
+	personalQueryStatus = func(string) (*eventtransport.StatusResp, error) {
+		return &eventtransport.StatusResp{Consumers: []eventtransport.StatusConsumer{{SubscribeID: "sub", PID: 123}}}, nil
+	}
+	personalFindProcess = func(int) (*os.Process, error) { return nil, wantErr }
+	personalLoadRunStates = func(string) ([]personal.RunState, error) { return []personal.RunState{{SubscribeID: "other"}}, nil }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); err != nil {
+		t.Fatalf("interrupt warning stop = %v", err)
+	}
+	personalLoadRunStates = func(string) ([]personal.RunState, error) { return []personal.RunState{{SubscribeID: "other"}}, nil }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); err != nil {
+		t.Fatalf("remaining bus stop = %v", err)
+	}
+	personalLoadRunStates = func(string) ([]personal.RunState, error) { return nil, nil }
+	personalStopBus = func(busctl.StopConfig) error { return busctl.ErrNotRunning }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); err != nil {
+		t.Fatalf("not running stop = %v", err)
+	}
+	personalStopBus = func(busctl.StopConfig) error { return wantErr }
+	if err := runPersonalEventStop(cmd, personalStopOptions{SubscribeID: "sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("bus stop error = %v", err)
+	}
+
+	personalLoadRunStates = func(string) ([]personal.RunState, error) {
+		return []personal.RunState{{}, {SubscribeID: "b"}, {SubscribeID: "a"}}, nil
+	}
+	if got, err := personalStopTargets("", "", true); err != nil || strings.Join(got, ",") != "a,b" {
+		t.Fatalf("stop target filtering = %#v, %v", got, err)
+	}
+	status := &eventtransport.StatusResp{Consumers: []eventtransport.StatusConsumer{
+		{SubscribeID: "other", PID: 1},
+		{SubscribeID: "sub", PID: 0},
+		{SubscribeID: "sub", PID: os.Getpid()},
+		{SubscribeID: "sub", PID: 123},
+		{SubscribeID: "sub", PID: 123},
+	}}
+	personalQueryStatus = func(string) (*eventtransport.StatusResp, error) { return status, nil }
+	personalFindProcess = func(int) (*os.Process, error) { return nil, wantErr }
+	if err := interruptPersonalConsumers("ipc", []string{" sub ", ""}); !errors.Is(err, wantErr) {
+		t.Fatalf("find process error = %v", err)
+	}
+	proc := &os.Process{}
+	personalFindProcess = func(int) (*os.Process, error) { return proc, nil }
+	personalSignalProcess = func(*os.Process, os.Signal) error { return wantErr }
+	if err := interruptPersonalConsumers("ipc", []string{"sub"}); !errors.Is(err, wantErr) {
+		t.Fatalf("signal process error = %v", err)
+	}
+	personalSignalProcess = func(*os.Process, os.Signal) error { return os.ErrProcessDone }
+	if err := interruptPersonalConsumers("ipc", []string{"sub"}); err != nil {
+		t.Fatalf("completed process signal = %v", err)
+	}
+}
+
+func TestCrossPlatformCoveragePersonalEventRemainingIdentityAndSourceCoverage(t *testing.T) {
+	oldAux := personalResolveAuxiliaryAccessToken
+	oldLoad := personalLoadTokenData
+	oldClientID := personalClientID
+	oldCredentials := personalResolveAppCredentialsStrict
+	oldEdition := edition.Get()
+	t.Cleanup(func() {
+		personalResolveAuxiliaryAccessToken = oldAux
+		personalLoadTokenData = oldLoad
+		personalClientID = oldClientID
+		personalResolveAppCredentialsStrict = oldCredentials
+		edition.Override(oldEdition)
+	})
+	wantErr := errors.New("identity")
+	personalResolveAuxiliaryAccessToken = func(context.Context, string, string) (string, error) { return "", wantErr }
+	if _, err := resolvePersonalEventIdentity(context.Background(), "", ""); !errors.Is(err, wantErr) {
+		t.Fatalf("aux token error = %v", err)
+	}
+	personalResolveAuxiliaryAccessToken = func(context.Context, string, string) (string, error) { return "access", nil }
+	personalLoadTokenData = func(string) (*authpkg.TokenData, error) { return nil, nil }
+	personalClientID = func() string { return "" }
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "resolved", "secret", "", "", nil
+	}
+	edition.Override(&edition.Hooks{RuntimeDefaults: func() map[string]edition.RuntimeDefaultFn {
+		return map[string]edition.RuntimeDefaultFn{
+			"$corpId":        func(context.Context) (string, bool) { return " corp ", true },
+			"$currentUserId": func(context.Context) (string, bool) { return " user ", true },
+		}
+	}})
+	if got, err := resolvePersonalEventIdentity(context.Background(), "", "source"); err != nil || got.ClientID != "resolved" || got.CorpID != "corp" {
+		t.Fatalf("resolved identity = %#v, %v", got, err)
+	}
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "", "", "", "", wantErr
+	}
+	edition.Override(&edition.Hooks{})
+	if _, err := resolvePersonalEventIdentity(context.Background(), "", ""); err == nil {
+		t.Fatal("missing client ID succeeded")
+	}
+	if got := resolveRuntimeDefault(context.Background(), "missing"); got != "" {
+		t.Fatalf("missing runtime default = %q", got)
+	}
+
+	if _, err := newPersonalStreamSource(context.Background(), personalStreamSourceOptions{ConfigDir: "", Identity: personal.Identity{}, TicketMode: "custom"}); !errors.Is(err, wantErr) {
+		t.Fatalf("custom credential error = %v", err)
+	}
+	personalResolveAppCredentialsStrict = func(string) (string, string, authpkg.CredentialSource, authpkg.CredentialSource, error) {
+		return "resolved", "secret", "", "", nil
+	}
+	if src, err := newPersonalStreamSource(context.Background(), personalStreamSourceOptions{Identity: personal.Identity{AccessToken: "token", SourceID: "source"}, TicketMode: "custom"}); err != nil || src == nil {
+		t.Fatalf("custom resolved source = %#v, %v", src, err)
+	}
+	if got := personalEventStreamSourceID(""); got != "open" {
+		t.Fatalf("default stream source = %q", got)
+	}
+	if got := configuredMCPBaseURL(""); got != "" {
+		t.Fatalf("default missing configured MCP = %q", got)
+	}
+}
+
+func newPersonalCoverageCommand() *cobra.Command {
+	cmd := &cobra.Command{Use: "event"}
+	cmd.SetContext(context.Background())
+	cmd.SetOut(&bytes.Buffer{})
+	cmd.SetErr(&bytes.Buffer{})
+	cmd.Flags().String("format", "table", "")
+	cmd.Flags().String("output", "", "")
+	return cmd
+}
+
+var _ = time.Second

internal/app/event_personal_identity_test.go

@@ -0,0 +1,211 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+func TestResolvePersonalEventIdentityUsesCorpUserWhenAvailable(t *testing.T) {
+	configDir := setupPersonalIdentityToken(t, &authpkg.TokenData{
+		AccessToken:  "access-1",
+		RefreshToken: "refresh-1",
+		ExpiresAt:    time.Now().Add(time.Hour),
+		RefreshExpAt: time.Now().Add(24 * time.Hour),
+		CorpID:       "corp-1",
+		UserID:       "user-1",
+		ClientID:     "client-1",
+	})
+
+	identity, err := resolvePersonalEventIdentity(context.Background(), configDir, "pre_open_source")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentity() error = %v", err)
+	}
+	if identity.LocalSubject != "" {
+		t.Fatalf("LocalSubject = %q, want empty when corp/user are available", identity.LocalSubject)
+	}
+	wantKey := "corp_user\x00corp-1\x00user-1\x00client-1\x00pre_open_source"
+	if got := identity.Key(); got != wantKey {
+		t.Fatalf("identity key = %q, want %q", got, wantKey)
+	}
+}
+
+func TestResolvePersonalEventIdentityFallsBackToRefreshTokenSubject(t *testing.T) {
+	configDir := setupPersonalIdentityToken(t, &authpkg.TokenData{
+		AccessToken:  "access-1",
+		RefreshToken: "refresh-1",
+		ExpiresAt:    time.Now().Add(time.Hour),
+		RefreshExpAt: time.Now().Add(24 * time.Hour),
+		ClientID:     "client-1",
+	})
+
+	identity, err := resolvePersonalEventIdentity(context.Background(), configDir, "pre_open_source")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentity() error = %v", err)
+	}
+	wantSubject := personalTokenSubject("refresh", "refresh-1")
+	if identity.LocalSubject != wantSubject {
+		t.Fatalf("LocalSubject = %q, want %q", identity.LocalSubject, wantSubject)
+	}
+	if strings.Contains(identity.Key(), "refresh-1") || strings.Contains(identity.Key(), "access-1") {
+		t.Fatalf("identity key leaked raw token: %q", identity.Key())
+	}
+
+	body, err := json.Marshal(redactedPersonalIdentity(identity, "identity-hash-1"))
+	if err != nil {
+		t.Fatalf("marshal redacted identity: %v", err)
+	}
+	if strings.Contains(string(body), wantSubject) || strings.Contains(string(body), "refresh-1") || strings.Contains(string(body), "access-1") {
+		t.Fatalf("redacted identity leaked local subject/token: %s", string(body))
+	}
+	if !strings.Contains(string(body), "unknown") {
+		t.Fatalf("redacted identity should mark missing corp/user as unknown: %s", string(body))
+	}
+}
+
+func TestResolvePersonalEventIdentityFallsBackToAccessTokenSubject(t *testing.T) {
+	configDir := setupPersonalIdentityToken(t, &authpkg.TokenData{
+		AccessToken: "access-1",
+		ExpiresAt:   time.Now().Add(time.Hour),
+		ClientID:    "client-1",
+	})
+
+	identity, err := resolvePersonalEventIdentity(context.Background(), configDir, "pre_open_source")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentity() error = %v", err)
+	}
+	wantSubject := personalTokenSubject("access", "access-1")
+	if identity.LocalSubject != wantSubject {
+		t.Fatalf("LocalSubject = %q, want %q", identity.LocalSubject, wantSubject)
+	}
+
+	var out bytes.Buffer
+	renderPersonalStatusText(&out, identity, "identity-hash-1", nil, busctl.EntryStatus{
+		Entry: busctl.BusEntry{WorkDir: "wd", State: busctl.BusStateNotRunning},
+	})
+	rendered := out.String()
+	if !strings.Contains(rendered, "corp=unknown user=unknown") {
+		t.Fatalf("status output = %q, want unknown corp/user", rendered)
+	}
+	if strings.Contains(rendered, wantSubject) || strings.Contains(rendered, "access-1") {
+		t.Fatalf("status output leaked local subject/token: %q", rendered)
+	}
+}
+
+func TestResolvePersonalEventIdentityDefaultsSourceIDToOpen(t *testing.T) {
+	configDir := setupPersonalIdentityToken(t, &authpkg.TokenData{
+		AccessToken: "access-1",
+		ExpiresAt:   time.Now().Add(time.Hour),
+		CorpID:      "corp-1",
+		UserID:      "user-1",
+		ClientID:    "client-1",
+	})
+
+	identity, err := resolvePersonalEventIdentity(context.Background(), configDir, "")
+	if err != nil {
+		t.Fatalf("resolvePersonalEventIdentity() error = %v", err)
+	}
+	if identity.SourceID != "open" {
+		t.Fatalf("SourceID = %q, want open", identity.SourceID)
+	}
+}
+
+func TestPersonalEventDefaultsUseProductionWithoutMCPConfig(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("DWS_CONFIG_DIR", dir)
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{})
+	t.Cleanup(func() { edition.Override(prev) })
+
+	if got := personalEventControlBaseURL("", dir); got != "https://mcp.dingtalk.com/dws" {
+		t.Fatalf("personalEventControlBaseURL() = %q, want production control URL", got)
+	}
+	if got := personalEventStreamTicketURL("", dir); got != "https://mcp.dingtalk.com/stream/connections/ticket" {
+		t.Fatalf("personalEventStreamTicketURL() = %q, want production ticket URL", got)
+	}
+	if got := personalEventStreamSourceID(""); got != "open" {
+		t.Fatalf("personalEventStreamSourceID() = %q, want open", got)
+	}
+	if got := config.GetMCPBaseURL(); got != "https://mcp.dingtalk.com" {
+		t.Fatalf("config.GetMCPBaseURL() = %q, want production MCP URL", got)
+	}
+}
+
+func TestPersonalEventDefaultsRespectExplicitAndMCPConfig(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "mcp_url"), []byte("https://custom-mcp.example.com\n"), 0o600); err != nil {
+		t.Fatalf("write mcp_url: %v", err)
+	}
+
+	if got := personalEventControlBaseURL("", dir); got != "https://custom-mcp.example.com/dws" {
+		t.Fatalf("personalEventControlBaseURL() = %q, want configured control URL", got)
+	}
+	if got := personalEventStreamTicketURL("", dir); got != "https://custom-mcp.example.com/stream/connections/ticket" {
+		t.Fatalf("personalEventStreamTicketURL() = %q, want configured ticket URL", got)
+	}
+	if got := personalEventControlBaseURL(" https://override.example.com/dws/ ", dir); got != "https://override.example.com/dws" {
+		t.Fatalf("explicit control URL = %q, want trimmed override", got)
+	}
+	if got := personalEventStreamTicketURL(" https://override.example.com/ticket/ ", dir); got != "https://override.example.com/ticket" {
+		t.Fatalf("explicit ticket URL = %q, want trimmed override", got)
+	}
+	if got := personalEventStreamSourceID("flag_source"); got != "flag_source" {
+		t.Fatalf("explicit sourceID = %q, want flag_source", got)
+	}
+}
+
+func TestPersonalEventSourceIDPrefersEditionOverride(t *testing.T) {
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{PersonalEventSourceID: "edition_source"})
+	t.Cleanup(func() { edition.Override(prev) })
+
+	if got := personalEventStreamSourceID(""); got != "edition_source" {
+		t.Fatalf("personalEventStreamSourceID() = %q, want edition_source", got)
+	}
+	if got := personalEventStreamSourceID("flag_source"); got != "flag_source" {
+		t.Fatalf("explicit sourceID = %q, want flag_source", got)
+	}
+}
+
+func setupPersonalIdentityToken(t *testing.T, data *authpkg.TokenData) string {
+	t.Helper()
+	configDir := t.TempDir()
+	raw, err := json.Marshal(data)
+	if err != nil {
+		t.Fatalf("marshal token data: %v", err)
+	}
+	prev := edition.Get()
+	edition.Override(&edition.Hooks{
+		LoadToken: func(dir string) ([]byte, error) {
+			if filepath.Clean(dir) != filepath.Clean(configDir) {
+				t.Fatalf("LoadToken dir = %q, want %q", dir, configDir)
+			}
+			return raw, nil
+		},
+	})
+	t.Cleanup(func() { edition.Override(prev) })
+	return configDir
+}

internal/app/event_personal_output_test.go

@@ -0,0 +1,541 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/spf13/cobra"
+)
+
+func TestPersonalEventListHidesSchemaIDs(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{name: "table", args: []string{"--as", "user"}},
+		{name: "json", args: []string{"--as", "user", "--format", "json"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := newEventListCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetArgs(tc.args)
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			got := out.String()
+			assertPersonalOutputHidesSchemaIDs(t, got)
+			for _, eventKey := range []string{
+				personal.EventFromUser,
+				personal.EventReadO2O,
+				personal.EventReadGroup,
+				personal.EventRecallO2O,
+				personal.EventRecallGroup,
+				personal.EventReactionO2O,
+				personal.EventReactionGroup,
+			} {
+				if !strings.Contains(got, eventKey) {
+					t.Fatalf("list output missing %s: %s", eventKey, got)
+				}
+			}
+		})
+	}
+}
+
+func TestEventListDefaultsToUser(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	cmd := newEventListCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	got := out.String()
+	if !strings.Contains(got, personal.EventSingleChat) || !strings.Contains(got, "EVENT_KEY") {
+		t.Fatalf("list output = %s, want personal event catalog", got)
+	}
+	if !strings.Contains(got, personal.EventFromUser) {
+		t.Fatalf("list output missing public event %s: %s", personal.EventFromUser, got)
+	}
+	if strings.Contains(got, "CLIENT_ID") || strings.Contains(got, "ClientSecret") {
+		t.Fatalf("list default appears to use legacy application output: %s", got)
+	}
+}
+
+func TestEventPublicHelpHidesAppMode(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		cmd  *cobra.Command
+	}{
+		{name: "consume", cmd: newEventConsumeCommand()},
+		{name: "list", cmd: newEventListCommand()},
+		{name: "schema", cmd: newEventSchemaCommand()},
+		{name: "status", cmd: newEventStatusCommand()},
+		{name: "stop", cmd: newEventStopCommand()},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var out bytes.Buffer
+			tc.cmd.SetOut(&out)
+			tc.cmd.SetArgs([]string{"--help"})
+			if tc.name == "schema" {
+				tc.cmd.SetArgs([]string{personal.EventSingleChat, "--help"})
+			}
+			if err := tc.cmd.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			got := out.String()
+			for _, hidden := range []string{"--as", "user|app", "应用事件" + " Stream"} {
+				if strings.Contains(got, hidden) {
+					t.Fatalf("%s help leaked %q:\n%s", tc.name, hidden, got)
+				}
+			}
+		})
+	}
+}
+
+func TestEventListAppOnlyFlagsRejectedForPersonalEvents(t *testing.T) {
+	cmd := newEventListCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--all"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "--all are not supported for personal events") {
+		t.Fatalf("Execute() error = %v, want unsupported flag validation", err)
+	}
+}
+
+func TestEventAsAppRejected(t *testing.T) {
+	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+	for _, cmd := range []*cobra.Command{
+		newEventListCommand(),
+		newEventStatusCommand(),
+		newEventConsumeCommand(),
+		newEventStopCommand(),
+		newEventSchemaCommand(),
+	} {
+		cmd.SilenceUsage = true
+		cmd.SilenceErrors = true
+		cmd.SetArgs([]string{"--as", "app"})
+		if cmd.Use == "schema <event_key>" {
+			cmd.SetArgs([]string{personal.EventSingleChat, "--as", "app"})
+		}
+		err := cmd.Execute()
+		if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+			t.Fatalf("%s Execute() error = %v, want public availability guard", cmd.Use, err)
+		}
+	}
+}
+
+func TestEventStatusAppOnlyFlagsRejectedForPersonalEvents(t *testing.T) {
+	cmd := newEventStatusCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--all", "--fail-on-orphan"})
+	err := cmd.Execute()
+	if err == nil ||
+		!strings.Contains(err.Error(), "--all") ||
+		!strings.Contains(err.Error(), "--fail-on-orphan") ||
+		!strings.Contains(err.Error(), "not supported for personal events") {
+		t.Fatalf("Execute() error = %v, want unsupported flag validation", err)
+	}
+}
+
+func TestPersonalEventSchemaHidesSchemaIDs(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{name: "default", args: []string{personal.EventSingleChat, "--as", "user"}},
+		{name: "json", args: []string{personal.EventSingleChat, "--as", "user", "--format", "json"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			cmd := newEventSchemaCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetArgs(tc.args)
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			assertPersonalOutputHidesSchemaIDs(t, out.String())
+			if strings.Contains(out.String(), "Schemas") {
+				t.Fatalf("schema output contains Schemas line: %s", out.String())
+			}
+		})
+	}
+}
+
+func TestPersonalEventSchemaUsesSingleJSONSchema(t *testing.T) {
+	for _, eventKey := range []string{
+		personal.EventMention,
+		personal.EventSingleChat,
+		personal.EventInChat,
+	} {
+		t.Run(eventKey, func(t *testing.T) {
+			cmd := newEventSchemaCommand()
+			cmd.SilenceUsage = true
+			cmd.SilenceErrors = true
+			var out bytes.Buffer
+			cmd.SetOut(&out)
+			cmd.SetArgs([]string{eventKey})
+			if err := cmd.Execute(); err != nil {
+				t.Fatalf("Execute() error = %v", err)
+			}
+			got := out.String()
+			var doc map[string]any
+			if err := json.Unmarshal(out.Bytes(), &doc); err != nil {
+				t.Fatalf("schema output for %s is not JSON: %v\n%s", eventKey, err, got)
+			}
+			for _, want := range []string{
+				"event_key",
+				"display_name",
+				"description",
+				"category",
+				"rule_type",
+				"required_params",
+				"jq_root_path",
+				"schema",
+				"event_id",
+				"timestamp",
+				"subscribe_id",
+				"content",
+				"sender",
+				"sender_open_dingtalk_id",
+				"conversation_id",
+				"message_id",
+				"create_time",
+				"event_time",
+			} {
+				if !strings.Contains(got, want) {
+					t.Fatalf("schema output for %s missing %q: %s", eventKey, want, got)
+				}
+			}
+			for _, leaked := range []string{
+				"message.text",
+				"chat.openConversationId",
+				"sender.userId",
+				"sender.unionId",
+				"auth",
+				"resolved_output_schema",
+				"decoded_data_schema",
+				"filter_schema",
+				"payload_schema",
+				"output_schema",
+				"data_json_path",
+				"headers",
+				"audit",
+				"tenant",
+				"subject",
+				"traceId",
+				"msgIdMetaq",
+				"at_users",
+				"sender_user_id",
+			} {
+				if strings.Contains(got, leaked) {
+					t.Fatalf("schema output for %s leaked %q: %s", eventKey, leaked, got)
+				}
+			}
+			if doc["jq_root_path"] != "." {
+				t.Fatalf("jq_root_path = %#v, want .", doc["jq_root_path"])
+			}
+			schema, ok := doc["schema"].(map[string]any)
+			if !ok {
+				t.Fatalf("schema = %#v, want object", doc["schema"])
+			}
+			props, ok := schema["properties"].(map[string]any)
+			if !ok {
+				t.Fatalf("schema.properties = %#v, want object", schema["properties"])
+			}
+			if _, ok := props["content"].(map[string]any); !ok {
+				t.Fatalf("schema.properties.content = %#v, want object", props["content"])
+			}
+		})
+	}
+}
+
+func TestPersonalActionEventSchemaMatchesFlatOutput(t *testing.T) {
+	tests := []struct {
+		eventKeys  []string
+		properties []string
+	}{
+		{
+			eventKeys: []string{personal.EventReadO2O, personal.EventReadGroup},
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "message_id",
+				"conversation_id", "reader", "reader_open_dingtalk_id", "sender",
+				"sender_open_dingtalk_id", "read_time", "event_time",
+			},
+		},
+		{
+			eventKeys: []string{personal.EventRecallO2O, personal.EventRecallGroup},
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "message_id",
+				"conversation_id", "recaller", "recaller_open_dingtalk_id", "sender",
+				"sender_open_dingtalk_id", "recall_time", "event_time",
+			},
+		},
+		{
+			eventKeys: []string{personal.EventReactionO2O, personal.EventReactionGroup},
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "message_id",
+				"conversation_id", "operator", "operator_open_dingtalk_id", "reaction_name",
+				"reaction_text", "operation_type", "operation_time", "sender",
+				"sender_open_dingtalk_id", "event_time",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		for _, eventKey := range tt.eventKeys {
+			t.Run(eventKey, func(t *testing.T) {
+				cmd := newEventSchemaCommand()
+				cmd.SilenceUsage = true
+				cmd.SilenceErrors = true
+				var out bytes.Buffer
+				cmd.SetOut(&out)
+				cmd.SetArgs([]string{eventKey})
+				if err := cmd.Execute(); err != nil {
+					t.Fatal(err)
+				}
+				var doc map[string]any
+				if err := json.Unmarshal(out.Bytes(), &doc); err != nil {
+					t.Fatalf("schema output is not JSON: %v\n%s", err, out.String())
+				}
+				if doc["event_key"] != eventKey || doc["jq_root_path"] != "." {
+					t.Fatalf("schema metadata = %#v", doc)
+				}
+				schema, ok := doc["schema"].(map[string]any)
+				if !ok {
+					t.Fatalf("schema = %#v", doc["schema"])
+				}
+				properties, ok := schema["properties"].(map[string]any)
+				if !ok || len(properties) != len(tt.properties) {
+					t.Fatalf("schema.properties = %#v, want exactly %d flat fields", schema["properties"], len(tt.properties))
+				}
+				for _, field := range tt.properties {
+					if _, ok := properties[field]; !ok {
+						t.Fatalf("schema missing %q: %#v", field, properties)
+					}
+				}
+				for _, internal := range []string{"payload", "uid", "corpid", "clientId", "filterSubId", "bizid"} {
+					if _, ok := properties[internal]; ok {
+						t.Fatalf("schema exposed internal property %q", internal)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestEventSchemaDefaultsToUser(t *testing.T) {
+	cmd := newEventSchemaCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetArgs([]string{personal.EventSingleChat})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(out.Bytes(), &doc); err != nil {
+		t.Fatalf("schema output is not JSON: %v\n%s", err, out.String())
+	}
+	if doc["event_key"] != personal.EventSingleChat {
+		t.Fatalf("event_key = %#v, want %s", doc["event_key"], personal.EventSingleChat)
+	}
+}
+
+func TestPersonalEventFromUserIsPubliclyAvailable(t *testing.T) {
+	if err := ensurePublicPersonalEvent(personal.EventFromUser); err != nil {
+		t.Fatalf("ensurePublicPersonalEvent() error = %v", err)
+	}
+
+	schemaCmd := newEventSchemaCommand()
+	schemaCmd.SilenceUsage = true
+	schemaCmd.SilenceErrors = true
+	var schemaOut bytes.Buffer
+	schemaCmd.SetOut(&schemaOut)
+	schemaCmd.SetArgs([]string{personal.EventFromUser})
+	if err := schemaCmd.Execute(); err != nil {
+		t.Fatalf("schema Execute() error = %v", err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(schemaOut.Bytes(), &doc); err != nil {
+		t.Fatalf("schema output is not JSON: %v\n%s", err, schemaOut.String())
+	}
+	if doc["event_key"] != personal.EventFromUser || doc["rule_type"] != "sender" {
+		t.Fatalf("schema document = %#v", doc)
+	}
+
+	configDir := setupPersonalIdentityToken(t, &authpkg.TokenData{
+		AccessToken:  "access-1",
+		RefreshToken: "refresh-1",
+		ExpiresAt:    time.Now().Add(time.Hour),
+		RefreshExpAt: time.Now().Add(24 * time.Hour),
+		CorpID:       "corp-1",
+		UserID:       "user-1",
+		ClientID:     "client-1",
+	})
+	t.Setenv("DWS_CONFIG_DIR", configDir)
+
+	consumeCmd := newEventConsumeCommand()
+	consumeCmd.SilenceUsage = true
+	consumeCmd.SilenceErrors = true
+	consumeCmd.SetArgs([]string{personal.EventFromUser, "--user", "test-user-001", "--dry-run"})
+	if err := consumeCmd.Execute(); err != nil {
+		t.Fatalf("consume dry-run Execute() error = %v", err)
+	}
+	openIDConsumeCmd := newEventConsumeCommand()
+	openIDConsumeCmd.SilenceUsage = true
+	openIDConsumeCmd.SilenceErrors = true
+	openIDConsumeCmd.SetArgs([]string{personal.EventFromUser, "--open-dingtalk-id", "open-user-1", "--dry-run"})
+	if err := openIDConsumeCmd.Execute(); err != nil {
+		t.Fatalf("consume openDingtalkId dry-run Execute() error = %v", err)
+	}
+
+	conflictingTargetCmd := newEventConsumeCommand()
+	conflictingTargetCmd.SilenceUsage = true
+	conflictingTargetCmd.SilenceErrors = true
+	conflictingTargetCmd.SetArgs([]string{personal.EventFromUser, "--user", "test-user-001", "--open-dingtalk-id", "open-user-1", "--dry-run"})
+	err := conflictingTargetCmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "--user and --open-dingtalk-id are mutually exclusive for "+personal.EventFromUser) {
+		t.Fatalf("conflicting target identity error = %v", err)
+	}
+
+	groupOpenIDCmd := newEventConsumeCommand()
+	groupOpenIDCmd.SilenceUsage = true
+	groupOpenIDCmd.SilenceErrors = true
+	groupOpenIDCmd.SetArgs([]string{personal.EventInChat, "--group", "cid-1", "--open-dingtalk-id", "open-user-1", "--dry-run"})
+	err = groupOpenIDCmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "--open-dingtalk-id is not supported for "+personal.EventInChat+"; use --group") {
+		t.Fatalf("group openDingtalkId error = %v", err)
+	}
+
+	missingUserCmd := newEventConsumeCommand()
+	missingUserCmd.SilenceUsage = true
+	missingUserCmd.SilenceErrors = true
+	missingUserCmd.SetArgs([]string{personal.EventFromUser})
+	err = missingUserCmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "one of --user or --open-dingtalk-id is required for "+personal.EventFromUser) {
+		t.Fatalf("missing target identity error = %v", err)
+	}
+}
+
+func TestEventConsumeCobraSchemaIncludesOpenDingTalkID(t *testing.T) {
+	root := NewRootCommand()
+	root.SilenceUsage = true
+	root.SilenceErrors = true
+	var out bytes.Buffer
+	root.SetOut(&out)
+	root.SetArgs([]string{"schema", "event consume"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("schema event consume Execute() error = %v", err)
+	}
+	var doc map[string]any
+	if err := json.Unmarshal(out.Bytes(), &doc); err != nil {
+		t.Fatalf("schema output is not JSON: %v\n%s", err, out.String())
+	}
+	params, ok := doc["parameters"].(map[string]any)
+	if !ok {
+		t.Fatalf("schema parameters = %#v", doc["parameters"])
+	}
+	if _, ok := params["open-dingtalk-id"]; !ok {
+		t.Fatalf("schema parameters missing open-dingtalk-id: %#v", params)
+	}
+	if _, ok := params["odid"]; ok {
+		t.Fatalf("schema parameters unexpectedly include odid alias: %#v", params)
+	}
+	for _, name := range []string{"user", "open-dingtalk-id", "group"} {
+		param, ok := params[name].(map[string]any)
+		if !ok {
+			t.Fatalf("schema parameter %s = %#v", name, params[name])
+		}
+		if got, exists := param["required_when"]; exists {
+			t.Fatalf("schema parameter %s unexpectedly declares required_when = %#v", name, got)
+		}
+	}
+	constraints, ok := doc["constraints"].(map[string]any)
+	if !ok {
+		t.Fatalf("schema constraints = %#v", doc["constraints"])
+	}
+	assertJSONConstraintGroup := func(field string, want []string) {
+		t.Helper()
+		groups, ok := constraints[field].([]any)
+		if !ok {
+			t.Fatalf("schema constraint %s = %#v", field, constraints[field])
+		}
+		for _, rawGroup := range groups {
+			group, ok := rawGroup.([]any)
+			if !ok || len(group) != len(want) {
+				continue
+			}
+			matched := true
+			for i := range want {
+				if group[i] != want[i] {
+					matched = false
+					break
+				}
+			}
+			if matched {
+				return
+			}
+		}
+		t.Fatalf("schema constraint %s = %#v, missing %#v", field, groups, want)
+	}
+	assertJSONConstraintGroup("require_one_of", []string{"event_key", "subscribe-id"})
+}
+
+func TestPersonalEventSchemaRejectsTableFormat(t *testing.T) {
+	cmd := newEventSchemaCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{personal.EventSingleChat, "--format", "table"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "event schema only supports json output") {
+		t.Fatalf("Execute() error = %v, want json-only format validation", err)
+	}
+}
+
+func TestEventAsBotRejected(t *testing.T) {
+	cmd := newEventListCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--as", "bot"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+		t.Fatalf("Execute() error = %v, want public availability guard", err)
+	}
+}
+
+func assertPersonalOutputHidesSchemaIDs(t *testing.T, out string) {
+	t.Helper()
+	for _, leaked := range []string{"SCHEMA_IDS", "schema_ids", "im_msg_23", "im_msg_29"} {
+		if strings.Contains(out, leaked) {
+			t.Fatalf("output leaked %q: %s", leaked, out)
+		}
+	}
+}

internal/app/event_personal_status_test.go

@@ -0,0 +1,105 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/busctl"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/transport"
+)
+
+func TestRenderPersonalStatusTextShowsConsumersWithoutSubscriptions(t *testing.T) {
+	var out bytes.Buffer
+	renderPersonalStatusText(&out, personal.Identity{
+		CorpID:   "corp-1",
+		UserID:   "user-1",
+		ClientID: "client-1",
+		SourceID: "source-1",
+	}, "identity-hash-1", nil, busctl.EntryStatus{
+		Entry: busctl.BusEntry{
+			WorkDir:   "wd",
+			State:     busctl.BusStateRunning,
+			HolderPID: 100,
+		},
+		Live: &transport.StatusResp{
+			Consumers: []transport.StatusConsumer{
+				{
+					PID:         12345,
+					EventTypes:  []string{"user_im_message_receive_o2o"},
+					SubscribeID: "subId-1",
+					Filter:      "content",
+					Received:    3,
+					Dropped:     1,
+				},
+				{
+					PID:      12346,
+					Received: 5,
+				},
+			},
+		},
+	})
+	got := out.String()
+	for _, want := range []string{
+		"Subscriptions: none",
+		"Consumers:",
+		"PID",
+		"EVENT_KEYS",
+		"SUBSCRIBE_ID",
+		"RECEIVED",
+		"DROPPED",
+		"12345",
+		"user_im_message_receive_o2o",
+		"subId-1",
+		"content",
+		"3",
+		"1",
+		"(catch-all)",
+		"-",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("status output missing %q:\n%s", want, got)
+		}
+	}
+}
+
+func TestRenderPersonalStatusTextConsumersUnavailableWhenRPCFails(t *testing.T) {
+	var out bytes.Buffer
+	renderPersonalStatusText(&out, personal.Identity{ClientID: "client-1", SourceID: "source-1"}, "identity-hash-1", nil, busctl.EntryStatus{
+		Entry: busctl.BusEntry{
+			WorkDir:   "wd",
+			State:     busctl.BusStateRunning,
+			HolderPID: 100,
+		},
+	})
+	if got := out.String(); !strings.Contains(got, "Consumers: unavailable (status RPC failed)") {
+		t.Fatalf("status output = %q, want unavailable consumers", got)
+	}
+}
+
+func TestRenderPersonalStatusTextConsumersNoneWhenBusNotRunning(t *testing.T) {
+	var out bytes.Buffer
+	renderPersonalStatusText(&out, personal.Identity{ClientID: "client-1", SourceID: "source-1"}, "identity-hash-1", nil, busctl.EntryStatus{
+		Entry: busctl.BusEntry{
+			WorkDir: "wd",
+			State:   busctl.BusStateNotRunning,
+		},
+	})
+	if got := out.String(); !strings.Contains(got, "Consumers: none") {
+		t.Fatalf("status output = %q, want no consumers", got)
+	}
+}

internal/app/event_registration_test.go

@@ -0,0 +1,74 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestEventCommandRemainsVisibleAsBuiltInPublicGroup(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	event := newEventCommand()
+	unregistered := &cobra.Command{Use: "unregistered", Run: func(*cobra.Command, []string) {}}
+	root.AddCommand(event, unregistered)
+
+	hideNonDirectRuntimeCommands(root)
+
+	if event.Hidden {
+		t.Fatal("built-in event command was hidden by the direct-runtime visibility filter")
+	}
+	if !unregistered.Hidden {
+		t.Fatal("control command outside the built-in/direct-runtime sets remained visible")
+	}
+
+	var leaves []string
+	for _, command := range event.Commands() {
+		if command.Hidden || !command.Runnable() {
+			continue
+		}
+		leaves = append(leaves, command.Name())
+	}
+	sort.Strings(leaves)
+	want := []string{"consume", "list", "schema", "status", "stop"}
+	if len(leaves) != len(want) {
+		t.Fatalf("public event leaves = %v, want %v", leaves, want)
+	}
+	for index := range want {
+		if leaves[index] != want[index] {
+			t.Fatalf("public event leaves = %v, want %v", leaves, want)
+		}
+	}
+}
+
+func TestPluginCannotReplaceBuiltInEventCommand(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	builtIn := newEventCommand()
+	root.AddCommand(builtIn)
+
+	pluginEvent := &cobra.Command{Use: "event", Run: func(*cobra.Command, []string) {}}
+	addPluginCommandsSafe(root, []*cobra.Command{pluginEvent})
+
+	var eventCommands []*cobra.Command
+	for _, command := range root.Commands() {
+		if command.Name() == "event" {
+			eventCommands = append(eventCommands, command)
+		}
+	}
+	if len(eventCommands) != 1 || eventCommands[0] != builtIn {
+		t.Fatalf("event command after plugin registration = %p (%d matches), want built-in %p", firstEventCommand(eventCommands), len(eventCommands), builtIn)
+	}
+	if pluginEvent.Parent() != nil {
+		t.Fatal("conflicting plugin event command was attached to the root")
+	}
+}
+
+func firstEventCommand(commands []*cobra.Command) *cobra.Command {
+	if len(commands) == 0 {
+		return nil
+	}
+	return commands[0]
+}

internal/app/event_stdin_gate_test.go

@@ -0,0 +1,65 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+)
+
+// A bounded run never arms the stdin-EOF watcher, regardless of stdin
+// shape: --max-events / --duration are the lifecycle control.
+func TestShouldWatchStdinEOF_BoundedIsNeverArmed(t *testing.T) {
+	if shouldWatchStdinEOF(1, 0) {
+		t.Error("--max-events set should not arm stdin watcher")
+	}
+	if shouldWatchStdinEOF(0, 5*time.Second) {
+		t.Error("--duration set should not arm stdin watcher")
+	}
+	if shouldWatchStdinEOF(3, 2*time.Second) {
+		t.Error("both bounds set should not arm stdin watcher")
+	}
+}
+
+// Regression: the detached _bus child must receive --profile so it resolves
+// credentials for the same organization as the parent. Missing it made a
+// non-default `--profile` consume fail with "bus child reported startup
+// failure on ready pipe" (no bus.log).
+func TestPersonalBusSpawnArgs_ForwardsProfile(t *testing.T) {
+	args := personalBusSpawnArgs(personal.Identity{
+		CorpID:   "dinga626d60c1128d449",
+		UserID:   "user_123",
+		SourceID: "open",
+	}, "", "")
+	found := false
+	for i := 0; i+1 < len(args); i++ {
+		if args[i] == "--profile" && args[i+1] == "dinga626d60c1128d449:user_123" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Errorf("spawn args must forward --profile <corpId>:<userId>; got %v", args)
+	}
+
+	// No CorpID → no --profile appended (avoid an empty flag value).
+	bare := personalBusSpawnArgs(personal.Identity{SourceID: "open"}, "", "")
+	for _, a := range bare {
+		if a == "--profile" {
+			t.Errorf("must not append --profile when CorpID is empty; got %v", bare)
+		}
+	}
+}

internal/app/event_stop_safety_test.go

@@ -0,0 +1,109 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/spf13/cobra"
+)
+
+func TestEventStopRequiresTypedConfirmationBeforeMutation(t *testing.T) {
+	root, _ := newEventStopSafetyRoot()
+	root.SetArgs([]string{"event", "stop", "sub-1"})
+
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("event stop without --yes or --dry-run unexpectedly succeeded")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Category != apperrors.CategoryValidation {
+		t.Fatalf("event stop confirmation error = %T %v, want typed validation error", err, err)
+	}
+	if appErr.Reason != "confirmation_required" {
+		t.Fatalf("event stop confirmation reason = %q, want confirmation_required", appErr.Reason)
+	}
+	for _, recoveryFlag := range []string{"--dry-run", "--yes"} {
+		if !strings.Contains(err.Error(), recoveryFlag) {
+			t.Fatalf("event stop confirmation error %q does not explain %s", err, recoveryFlag)
+		}
+	}
+}
+
+func TestEventStopDryRunPrecedesConfirmationAndReturnsPreview(t *testing.T) {
+	tests := []struct {
+		name            string
+		args            []string
+		wantAll         bool
+		wantSubscribeID string
+	}{
+		{name: "single subscription", args: []string{"event", "stop", "sub-1", "--dry-run"}, wantSubscribeID: "sub-1"},
+		{name: "all subscriptions", args: []string{"--dry-run", "event", "stop", "--all"}, wantAll: true},
+		{name: "dry run wins over yes", args: []string{"event", "stop", "sub-2", "--yes", "--dry-run"}, wantSubscribeID: "sub-2"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			root, stdout := newEventStopSafetyRoot()
+			root.SetArgs(test.args)
+			if err := root.Execute(); err != nil {
+				t.Fatalf("event stop dry-run error = %v", err)
+			}
+			var preview map[string]any
+			if err := json.Unmarshal(stdout.Bytes(), &preview); err != nil {
+				t.Fatalf("decode event stop dry-run preview: %v\n%s", err, stdout.String())
+			}
+			if preview["dry_run"] != true || preview["action"] != "event.stop" || preview["identity"] != "user" {
+				t.Fatalf("event stop dry-run preview = %#v", preview)
+			}
+			if got, _ := preview["all"].(bool); got != test.wantAll {
+				t.Fatalf("event stop dry-run all = %v, want %v", got, test.wantAll)
+			}
+			if got, _ := preview["subscribe_id"].(string); got != test.wantSubscribeID {
+				t.Fatalf("event stop dry-run subscribe_id = %q, want %q", got, test.wantSubscribeID)
+			}
+		})
+	}
+}
+
+func TestEventStopDryRunDoesNotBypassTargetValidation(t *testing.T) {
+	for _, test := range []struct {
+		name string
+		args []string
+		want string
+	}{
+		{name: "missing target", args: []string{"event", "stop", "--dry-run"}, want: "subscribe_id is required unless --all is set"},
+		{name: "conflicting targets", args: []string{"event", "stop", "sub-1", "--all", "--dry-run"}, want: "subscribe_id and --all are mutually exclusive"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			root, _ := newEventStopSafetyRoot()
+			root.SetArgs(test.args)
+			err := root.Execute()
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("event stop dry-run validation error = %v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func newEventStopSafetyRoot() (*cobra.Command, *bytes.Buffer) {
+	stdout := &bytes.Buffer{}
+	root := &cobra.Command{
+		Use:           "dws",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+	}
+	root.SetOut(stdout)
+	root.SetErr(&bytes.Buffer{})
+	root.PersistentFlags().Bool("dry-run", false, "preview without executing")
+	root.PersistentFlags().Bool("yes", false, "confirm execution")
+	event := &cobra.Command{Use: "event"}
+	event.AddCommand(newEventStopCommand())
+	root.AddCommand(event)
+	return root, stdout
+}

internal/app/event_stop_test.go

@@ -0,0 +1,127 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"bytes"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+)
+
+func TestEventStopHelpDescribesPersonalSubscription(t *testing.T) {
+	cmd := newEventStopCommand()
+	var out bytes.Buffer
+	cmd.SetOut(&out)
+	cmd.SetArgs([]string{"--help"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("Execute() error = %v", err)
+	}
+	got := out.String()
+	for _, want := range []string{
+		"stop [subscribe_id]",
+		"取消个人事件订阅并停止本地消费",
+		"取消个人事件订阅并停止本地消费，清理对应本地消费状态",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("help missing %q:\n%s", want, got)
+		}
+	}
+	for _, stale := range []string{"优雅停止 bus 守护进程", strings.Join([]string{"--as", "app"}, " "), "应用事件"} {
+		if strings.Contains(got, stale) {
+			t.Fatalf("help still contains stale public app wording %q:\n%s", stale, got)
+		}
+	}
+}
+
+func TestEventStopRequiresSubscribeIDOrAll(t *testing.T) {
+	cmd := newEventStopCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "subscribe_id is required unless --all is set") {
+		t.Fatalf("Execute() error = %v, want subscribe_id requirement", err)
+	}
+}
+
+func TestEventStopSubscribeIDAndAllAreMutuallyExclusive(t *testing.T) {
+	cmd := newEventStopCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"subId-1", "--all"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "subscribe_id and --all are mutually exclusive") {
+		t.Fatalf("Execute() error = %v, want mutual exclusion", err)
+	}
+}
+
+func TestEventStopAsAppRejectsSubscribeID(t *testing.T) {
+	cmd := newEventStopCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--as", "app", "subId-1"})
+	err := cmd.Execute()
+	if err == nil || !strings.Contains(err.Error(), "app event is not publicly available yet") {
+		t.Fatalf("Execute() error = %v, want public availability guard", err)
+	}
+}
+
+func TestPersonalStopTargets(t *testing.T) {
+	workDir := t.TempDir()
+	if err := personal.UpsertRunState(workDir, personal.RunState{SubscribeID: "sub-b"}); err != nil {
+		t.Fatalf("UpsertRunState() error = %v", err)
+	}
+	if err := personal.UpsertRunState(workDir, personal.RunState{SubscribeID: "sub-a"}); err != nil {
+		t.Fatalf("UpsertRunState() error = %v", err)
+	}
+
+	got, err := personalStopTargets(workDir, "sub-explicit", false)
+	if err != nil {
+		t.Fatalf("personalStopTargets(explicit) error = %v", err)
+	}
+	if want := []string{"sub-explicit"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("explicit targets = %#v, want %#v", got, want)
+	}
+
+	got, err = personalStopTargets(workDir, "", true)
+	if err != nil {
+		t.Fatalf("personalStopTargets(all) error = %v", err)
+	}
+	if want := []string{"sub-a", "sub-b"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("all targets = %#v, want %#v", got, want)
+	}
+
+	if _, err := personalStopTargets(workDir, "", false); err == nil || !strings.Contains(err.Error(), "subscribe_id is required unless --all is set") {
+		t.Fatalf("personalStopTargets(no target) error = %v, want required error", err)
+	}
+	if _, err := personalStopTargets(workDir, "sub-explicit", true); err == nil || !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Fatalf("personalStopTargets(explicit+all) error = %v, want mutual exclusion", err)
+	}
+}
+
+func TestPrintPersonalStopResult(t *testing.T) {
+	var out bytes.Buffer
+	printPersonalStopResult(&out, []string{"sub-1"}, true, "personal bus stopped")
+	if got := out.String(); got != "cancelled personal subscription sub-1; personal bus stopped\n" {
+		t.Fatalf("single output = %q", got)
+	}
+
+	out.Reset()
+	printPersonalStopResult(&out, []string{"sub-1", "sub-2"}, false, "personal bus still running")
+	if got := out.String(); got != "cancelled 2 personal subscription(s); personal bus still running\n" {
+		t.Fatalf("multi output = %q", got)
+	}
+}