fix(cli): route Chinese product-name queries to the named product

Natural-language queries that name a product in Chinese (e.g. 「帮我搜一下「评测项目管理」钉钉AI表格」) lost the named product's candidates to a sibling product whose summaries repeat a shared bigram (92 sheet tools repeat 「表格」), crowding aitable out of the Top-K cut entirely. Two-part fix in the lexical layer, deterministic and no new dependencies: - Fold the product display name into each tool's identity field at index build (runtime assembly carries the display name in Description). - Query-side named-product guarantee: when the query contains a product's display-name core (NFKC-folded, generic suffixes like 「操作」「管理」 trimmed, longest core wins on overlap), fetch that product's best candidate over its own eligible subset and merge it just above the global top hit. A post-hoc multiplier alone cannot rescue candidates truncated inside Retrieve's CandidateLimit cut. Eval evidence (core120 first-turn coverage): 101→103/120; all four measured 「钉钉AI表格」 misses fixed, zero regressions across the battery.
Merge remote-tracking branch 'upstream/main' into pr984
2026-08-19 14:31:48 +08:00 · 2026-08-17 21:55:45 +08:00 · 2026-08-17 19:10:18 +08:00 · 2026-08-17 17:21:28 +08:00 · 2026-08-17 17:21:10 +08:00 · 2026-08-17 17:20:41 +08:00
316 changed files with 15231 additions and 20605 deletions
@@ -1,5 +0,0 @@
---
-category: Changed
---
-
- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked.
@@ -1,9 +0,0 @@
---
-category: Added
---
-
- **AI Table server-side statistics** — adds `dws aitable record stats` for
-  ungrouped record-set metrics through `query_records_stats`, plus `dws aitable
-  record group-stats` for grouped, distinct, and advanced aggregation through
-  `query_stats`; both commands validate their JSON aggregation contracts before
-  dispatch.
@@ -1,11 +0,0 @@
---
-category: Added
---
-
- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented
-  entries with lark-cli where the DingTalk backend supports equivalent
-  semantics, rejects malformed or missing collections instead of returning
-  false empty success, preserves truthful pagination, and requires stable
-  identifiers plus read-back or explicit terminal receipts for writes. Adds
-  deterministic contract coverage, a PII-safe live E2E runner, and a sanitized
-  capability review with documented platform boundaries.
@@ -1,10 +0,0 @@
---
-category: Added
---
-
- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`,
-  `comment resolve`, `comment restore`, and the lightweight
-  `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share
-  the same `doc-comment` MCP capabilities; batch queries preserve input order
-  for repeated `topicId:commentKey` references, while reaction replies require
-  DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji.
@@ -6,61 +6,6 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/) and th

 ## [Unreleased]

-## [1.0.59-beta.3] - 2026-08-19
-
-### Added
-
- **Robot group reference replies** (#928) — `chat message send-by-bot` supports paired `--reply` and `--ref-sender` flags for Markdown replies that quote an existing group message.
-
- **AI Table server-side statistics** — adds `dws aitable record stats` for
-  ungrouped record-set metrics through `query_records_stats`, plus `dws aitable
-  record group-stats` for grouped, distinct, and advanced aggregation through
-  `query_stats`; both commands validate their JSON aggregation contracts before
-  dispatch.
-
- **Calendar event share-info** (#980) — adds `dws calendar event share-info` to fetch a calendar event's share info (title, organizer, location, join info) for sharing with others; supports `--calendar-id` and `--language`.
-
- **Calendar and To-do Shortcut workflows** — aligns 47 public task-oriented
-  entries with lark-cli where the DingTalk backend supports equivalent
-  semantics, rejects malformed or missing collections instead of returning
-  false empty success, preserves truthful pagination, and requires stable
-  identifiers plus read-back or explicit terminal receipts for writes. Adds
-  deterministic contract coverage, a PII-safe live E2E runner, and a sanitized
-  capability review with documented platform boundaries.
-
- **Doc and Sheet comment lifecycle commands** — adds `comment batch-query`,
-  `comment resolve`, `comment restore`, and the lightweight
-  `comment react-reply` to both `dws doc` and `dws sheet`. The two domains share
-  the same `doc-comment` MCP capabilities; batch queries preserve input order
-  for repeated `topicId:commentKey` references, while reaction replies require
-  DingTalk reaction names such as `憨笑` or `鼓掌` rather than raw Unicode emoji.
-
- **Sheet SourceRange dropdowns** — supports range-backed dropdowns across direct, cell, and batch write paths, with structured readback for valid and invalid references. Batch `set-dropdown` now rejects unsupported top-level `colors` / `source-colors`; Inline colors belong in `options[].color`, while SourceRange color writes remain unsupported.
- **Sheet read completion metadata** — documents and preserves returned ranges, truncation reasons, and partial-read status for large range and CSV reads.
-
-### Changed
-
- **AI Table parameter aliases** — accepts reviewed equivalent spellings for Base, table, workflow, search, pagination, and description parameters while keeping role-changing or semantically ambiguous inputs blocked.
-
- **Doc/drive description scope** — restates the `dingtalk-doc` description as document-entity-and-content operations with an explicit exclusion list, and narrows `dingtalk-drive` to file-level management of DingTalk documents, so first-round Agent selection separates content work from file management without changing CLI behavior.
-
-### Fixed
-
- **Aitable pagination and Minutes unshare verification** (#1006) — keeps
-  record queries on the service's 20-record page boundary so multi-page reads
-  and mutation readbacks no longer report false retryable failures, preserves
-  `totalCount` when supplied, validates `--dry-run` plans before transport,
-  follows active deletion readback continuations before proving absence, and
-  rejects Minutes unshare success until the listening note exists and the
-  service acknowledges the exact task and member targets.
-
- **Document write verification** (#960) — avoids false partial-success results when normalized Markdown, paginated blocks, inline images, or version reverts are confirmed by server readback. Document reverts and media inserts now require explicit readback evidence and report partial success when the server cannot prove the requested result.
-
- **Chat sender identity guards** — preserves unverified mixed sender inputs after exact message `senderId` matches and aligns `--sender-query` Skill guidance with fail-closed Runtime behavior.
-
- **Windows event bus lifecycle** — start event consumers without unsupported inherited file descriptors, stop buses through local IPC with a termination fallback, and preserve subscription cleanup when startup fails.
-
-
 ## [1.0.59-beta.2] - 2026-08-17

 ### Added
@@ -1,33 +1,33 @@
 class DingtalkWorkspaceCliBeta < Formula
  desc "Automate DingTalk workspace tasks from the terminal (beta channel)"
  homepage "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli"
-  version "1.0.59-beta.3"
+  version "1.0.59-beta.2"
  license "Apache-2.0"
  keg_only "it is the beta channel and conflicts with dingtalk-workspace-cli"

  on_macos do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-arm64.tar.gz"
-      sha256 "9c99adcefd9104368eb443f0a1b4af8e7aceaa1ffdd4462e486854c1692bb6ce"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-arm64.tar.gz"
+      sha256 "7f11218d3222f3e93c3b1e94b3a004c061eb0a297b206447ea95fe6b2b1ec674"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-darwin-amd64.tar.gz"
-      sha256 "f5cc8efb1f982d68ae549190fd683292359c2ab542b532fa52bb35e6b5c049af"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-darwin-amd64.tar.gz"
+      sha256 "72f06a334cf29d23123639fabe13bf2951765066136e47ccc6453667c382f8c2"
    end
  end

  on_linux do
    if Hardware::CPU.arm?
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-arm64.tar.gz"
-      sha256 "7a4efd04b417ce8013b1e431274b396179958da244164f59974358ba327ff093"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-arm64.tar.gz"
+      sha256 "3edbfabb7718b53914a2d9efe7b1152e9ebd70765ff0b6f19ad3125e4a2458ed"
    else
-      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-linux-amd64.tar.gz"
-      sha256 "90181e8f2e9010c1943a5773c3d45d7d3ac85d6bc93e18a9aaa7c69909e553d7"
+      url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-linux-amd64.tar.gz"
+      sha256 "e1c610070a9c1b3763656cbd53c818290f199097adc07cb9fe629ed765c5e1e0"
    end
  end

  resource "skills" do
-    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.3/dws-skills.zip"
-    sha256 "e7028914a4a826af9b18ed4922d68fa8f279473817fed4f305465bc8a7aad363"
+    url "https://github.com/DingTalk-Real-AI/dingtalk-workspace-cli/releases/download/v1.0.59-beta.2/dws-skills.zip"
+    sha256 "aa2854651eaa2c857b526aaec73fd1358d31b11999fe7fd3e99e5060b2522a1f"
  end

  def install
@@ -10,7 +10,7 @@ SCHEMA_META_INDEX_OUTPUT ?= artifacts/schema_meta_index.gob
 POLICY_ENV = DWS_POLICY_TMPDIR="$(DWS_POLICY_TMPDIR)" GOTMPDIR="$(POLICY_GOTMPDIR)"
 GO_SOURCE_LIST = git ls-files -z --cached --others --exclude-standard -- '*.go'

-.PHONY: all help build check-safechat test-safechat rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples tool-search-evaluation-harness generate-tool-search-comparison generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks

 all: setup-hooks fmt lint build test rebuild

@@ -18,8 +18,6 @@ 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 check-safechat - Compile and vet the SafeChat message-crypto backend (needs CGO)\n"
-	@printf "  make test-safechat - Run the message-crypto tests against the SafeChat backend\n"
 	@printf "  make test-plan     - Verify CI test and full-suite coverage package plans cover their scopes exactly once\n"
 	@printf "  make test-auth-legacy-compat - Run stable legacy authentication compatibility regressions\n"
 	@printf "  make lint          - Run formatting checks, go vet, and staticcheck\n"
@@ -39,6 +37,8 @@ help:
 	@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 tool-search-evaluation-harness - Verify Go retrieval, trust metrics, frozen fixtures, and build-time report generation\n"
+	@printf "  make generate-tool-search-comparison - Generate the declaration-assembled comparison under .worktrees/policy-tmp\n"
 	@printf "  make generate-schema - Refresh param_aliases + verify Schema assembly determinism\n"
 	@printf "  make generate-schema-catalog - Optional assembled Catalog dump under artifacts/ (not a delivery step)\n"
 	@printf "  make package       - Build all release artifacts locally\n"
@@ -54,16 +54,6 @@ build:
 rebuild:
 	@./scripts/dev/build.sh

-# No dws command imports internal/msgcrypto yet, so a tagged CLI build would
-# link nothing extra and look identical to the default binary. Gate the package
-# itself until a caller wires it in.
-check-safechat:
-	@CGO_ENABLED=1 $(GO) build -tags safechat ./internal/msgcrypto/...
-	@CGO_ENABLED=1 $(GO) vet -tags safechat ./internal/msgcrypto/...
-
-test-safechat:
-	@CGO_ENABLED=1 $(GO) test -count=1 -tags safechat ./internal/msgcrypto/...
-
 test:
 	@DWS_PACKAGE_VERSION="$(DWS_PACKAGE_VERSION)" $(GO) test -count=1 -timeout=10m ./...

@@ -96,7 +86,7 @@ fmt:
 	$(GO_SOURCE_LIST) > "$$go_files"; \
 	xargs -0 sh -c 'if [ "$$#" -gt 0 ]; then exec gofmt -w -- "$$@"; fi' sh < "$$go_files"

-policy: test-auth-legacy-compat
+policy: test-auth-legacy-compat tool-search-evaluation-harness skill-mono-multi-content
 	@mkdir -p "$(POLICY_GOTMPDIR)"
 	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
 	@$(POLICY_ENV) ./scripts/policy/check-skill-context-budget.sh
@@ -173,6 +163,25 @@ mock-mcp-smoke:
 test-schema-agent-examples:
 	DWS_AGENT_EXAMPLES_DRY_RUN=1 $(GO) test -v -count=1 ./internal/app -run '^TestAgentExamplesDryRun$$'

+tool-search-evaluation-harness:
+	python3 -m unittest \
+		scripts/dev/eval_tool_search_ranking_test.py \
+		scripts/dev/verify_tool_search_eval_manifest_test.py
+	@mkdir -p "$(DWS_POLICY_TMPDIR)"
+	$(GO) run ./internal/generator/cmd_schema_catalog \
+		-root . \
+		-output "$(DWS_POLICY_TMPDIR)/tool-search-schema-catalog" \
+		-meta-index "$(DWS_POLICY_TMPDIR)/tool-search-schema-meta-index.gob"
+	python3 scripts/dev/verify_tool_search_eval_manifest.py \
+		--catalog-dir "$(DWS_POLICY_TMPDIR)/tool-search-schema-catalog"
+	$(GO) test ./internal/cli -run '^TestToolSearch|^TestSchemaSearch|^TestDefaultToolSearch|^TestAggregateToolSearch|^TestScoreToolSearch' -count=1
+	$(GO) test ./internal/app -run '^TestToolSearchDelivery|^TestSchemaSearchInspectCatalogVersionContract$$' -count=1
+	$(GO) run ./internal/generator/cmd_tool_search_comparison -output "$(DWS_POLICY_TMPDIR)/tool-search-comparison.json"
+
+generate-tool-search-comparison:
+	@mkdir -p "$(DWS_POLICY_TMPDIR)"
+	$(GO) run ./internal/generator/cmd_tool_search_comparison -output "$(DWS_POLICY_TMPDIR)/tool-search-comparison.json"
+
 # generate-schema refreshes param_aliases_generated.go and verifies that
 # ResolveSchemaBuild assembly is deterministic. Catalog is runtime-assembled
 # (声明即 Catalog); cmd_schema_catalog is not a committed delivery step.
@@ -41,7 +41,7 @@ PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁
 scripts/policy/interface-migrations/approved-flag-migrations-v1.json
 ```

-清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。清单中的 `pending` 记录只记录已评审计划，并授权其精确列出的后续产品迁移；候选与 merge-base 仍必须精确匹配 `before`，不能授权同一个提交中的接口变化，也不能作为其他命令或参数的通配豁免。
+清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。当前清单登记了 IM ID rename 的 `pending` 记录；`pending` 只记录已评审计划，候选与 merge-base 仍必须精确匹配 `before`，因此本治理 PR **不授权 PR #904 或任何产品接口变化**。

 ## 两阶段迁移与回执清理

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-08-18T17:38:50.904696",
-  "count": 436,
+  "generated_at": "2026-08-14T13:50:36.324505",
+  "count": 418,
  "results": [
    {
      "suite": "semantic",
@@ -489,7 +489,7 @@
      "risk": "read",
      "status": "reviewed_available",
      "disposition": "semantic_adapter",
-      "semantic_delta": "统一 ID、筛选、关键词、字段投影和分页查询；fieldIds 只返回用户要求的列，并投影稳定的 records/count/cursor 结果。",
+      "semantic_delta": "统一 ID、筛选、关键词和分页查询，并投影稳定的 records/count/cursor 结果。",
      "availability": "available"
    },
    {
@@ -692,16 +692,6 @@
      "semantic_delta": "按当前父目录语义调整文件夹展示顺序。",
      "availability": "available"
    },
-    {
-      "suite": "semantic",
-      "service": "aitable",
-      "command": "+table-bootstrap",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "在已有 Base 中声明式创建一张表和字段，字段自动分片，逐层读回验证并发布可恢复检查点。",
-      "availability": "available"
-    },
    {
      "suite": "semantic",
      "service": "aitable",
@@ -1066,274 +1056,144 @@
      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+agenda",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格验证 result.events 与分页证据，稳定投影 id 为 eventId；显式空数组才是空日程。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+attendee-list",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格验证参会人数组并投影显示名、响应状态和 self；真实后端不返回稳定参会人 userId，因此不伪造身份字段。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "calendar",
      "command": "+book",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "按参会人姓名解析后创建日程，并在多步骤路径提供失败回滚与详情读回。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+book-list",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格验证日历本数组并稳定投影 calendarId，缺失数组不再误报为空。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+book-search",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "按日历本名称搜索并严格区分零命中与协议错误。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "calendar",
      "command": "+cancel-event",
      "risk": "high-risk-write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "删除前读取并展示目标，经高风险确认后取消指定日程。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+conflicts",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "在指定范围分析重叠日程并输出冲突对，避免人工逐项比对。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+create",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "创建响应必须给出 eventId/id，且标题和起止时间通过详情读回后才成功。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+free",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "按姓名解析参与者后查询闲忙，省去手工 userId 解析。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+free-slots",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "从已有日程计算工作时段内空档，并显式输出满足时长的候选区间。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+freebusy",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "统一按用户或会议室 ID 查询指定范围闲忙，并声明至少一类目标约束。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+get",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "schema_leaf",
-      "semantic_delta": "严格读取日程对象并把稳定 id 规范化为 eventId，拒绝空响应和对象漂移。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "calendar",
      "command": "+invite",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "按姓名唯一解析用户后邀请到已有日程。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+my-free",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "以当前用户身份查询一个时间段是否空闲。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+next-event",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "在未来时间窗内定位最近的下一场日程。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "calendar",
      "command": "+reschedule",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "修改前读取目标日程，再更新完整起止时间。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+room-find",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "按单个未来时间段严格查询可用会议室，公开真实 page/pageSize/hasMore 证据和后端筛选边界。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+room-groups",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格读取 result.groupList，避免会议室分组被响应 wrapper 漂移静默清空。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+room-search",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "按名称查询会议室但不声称检查时间可用性；缺失会议室数组直接失败。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+rsvp",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "把直白 RSVP 动作映射为 responseStatus，拒绝空 ack，并在写后读取日程终态。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+search-event",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "在服务端日程当前页按标题、描述和地点过滤，同时保留 hasMore/nextCursor，绝不把单页零命中当全局未找到。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+suggest-time",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "按姓名逐个唯一解析参与者，再查询大家共同可用的建议时间。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+suggestion",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "schema_leaf",
-      "semantic_delta": "直接按 userId 查询建议时段，严格区分显式空 recommendEventTimes 与缺失或畸形响应。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+today",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "查询并整理今天的日程视图。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+tomorrow",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "查询并整理明天的日程视图。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "calendar",
-      "command": "+update",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "组合字段与参会人分阶段更新，明确非事务步骤并以详情和参会人列表读回验证。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "calendar",
      "command": "+week",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "查询并按日期整理本周日程。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
      "suite": "semantic",
@@ -3722,214 +3582,81 @@
      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "todo",
      "command": "+assign",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "保留历史按姓名解析后创建并指派的新任务语义，避免同名破坏性变更。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "todo",
      "command": "+assign-multi",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "全部姓名唯一解析后才创建一次，并以单一统一结果输出稳定 taskId。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+comment",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "新增评论必须取得稳定 commentId，并分页读回验证内容。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+complete",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "先读当前状态避免重复写，必要时完成后再读回核验。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+create",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "创建后要求稳定 taskId，并读取 todoDetailModel 验证标题。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+created-todos",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "遍历创建者角色的全部分页后投影。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+due-today",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "按本地日历日构造服务端截止窗口并遍历全部分页。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+get",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格绑定 todoDetailModel.taskId，缺失或错绑均失败。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+get-my-tasks",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格识别 todoCards/hasMore/page/size；显式空数组才是空结果，并支持有界全量分页。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+get-related-tasks",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "遍历与我相关三种角色的全部分页并按 taskId 去重。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+list-attachment",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格区分显式空附件与缺失容器，并要求每项稳定附件 ID。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+list-comment",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格区分显式空评论与缺失容器，并要求每项稳定 commentId。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+list-sub",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格校验子待办容器、对象元素和稳定 taskId。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
+      "suite": "read",
      "service": "todo",
      "command": "+overdue",
      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "遍历执行者角色的全部分页并按当前时间筛选逾期项。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+related-tasks",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "alias_internal",
-      "semantic_delta": "保留旧命令拼写，新的 Agent 路由统一使用 +get-related-tasks。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "todo",
      "command": "+remind",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "解析当前用户后创建给自己的待办；该命令不是独立提醒规则。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+reminder",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "semantic_adapter",
-      "semantic_delta": "严格验证提醒参数和 success=true 终端回执；上游不能读回规则，固定 verified=false。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+reopen",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "先读当前状态避免重复写，必要时重开后再读回核验。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+search",
-      "risk": "read",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "遍历全部 hasMore 分页并按标题匹配；达到页上限仍未耗尽时失败。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
+      "suite": "write",
      "service": "todo",
      "command": "+todo-done",
      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "跨全部分页按标题唯一定位后完成任务。",
-      "availability": "available"
-    },
-    {
-      "suite": "semantic",
-      "service": "todo",
-      "command": "+update",
-      "risk": "write",
-      "status": "reviewed_available",
-      "disposition": "primary_smart",
-      "semantic_delta": "更新指定字段后读取详情逐字段核验。",
-      "availability": "available"
+      "status": "real-ok"
    },
    {
      "suite": "semantic",
@@ -102,7 +102,7 @@
      <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 --content</code></td><td>文档末尾追加文本</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>
@@ -56,13 +56,13 @@

 | shortcut | 多步/智能逻辑 | 验证 |
 |----------|--------------|------|
-| `chat +dm --to <姓名> --content` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 |
+| `chat +dm --to <姓名> --text` | 搜人→解析唯一 userId→发单聊；多人消歧 | ✅ dry-run 真机 |
 | `contact +lookup --name <姓名>` | 搜人→解析 userId→取完整资料 | ✅ **真机端到端** |
 | `todo +assign --to <姓名> --task` | 解析人→建待办并把 TA 设为执行人 | ✅ dry-run 真机 |
-| `chat +send-to-group --group <群名> --content` | 按群名搜群(search_groups)→消歧→发消息 | ✅ 编译/挂载 |
+| `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> --content` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 |
+| `chat +broadcast --to <姓名CSV> --text` | 多名逐一解析→群发单聊，失败汇总不中断 | ✅ 编译/挂载 |
 | `minutes +latest-minutes` | 列妙记→取最新一条详情 | ✅ 编译/挂载 |
 | `chat +group-members --group <群名>` | 按群名搜群→列群成员 | ✅ 编译/挂载 |
 | `contact +org --name <姓名>` | 解析人→取详情拿 deptId→查部门详情 | ✅ **真机端到端**（3 步：董鑫阳→模型算法/16人） |
@@ -76,7 +76,7 @@
 | `todo +todo-done --task <关键词>` | 列我的待办→按标题匹配→标记完成 | ✅ 编译/挂载 |
 | `calendar +reschedule --event <id>` | 查日程详情→改时间（查→改机械多步） | ✅ 编译/挂载 |
 | `wiki +wiki-new-doc --space <名>` | 按名搜知识空间→在其下建文档（跨 doc server 路由） | ✅ 编译/挂载 |
-| `doc +doc-append --doc --content` | 文档末尾追加文本（update_document append 模式） | ✅ 编译/挂载 |
+| `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 "原文=>替换"…` | 多组批量替换文字，去重校验+逐组结果聚合 | ✅ 全量测试 |
@@ -1,55 +0,0 @@
-# OA Attachment Download URL Output Design
-
-## Goal
-
-Keep the existing command and MCP request unchanged while making the returned
-OSS signed URL directly copyable from JSON output:
-
-```text
-dws oa approval attachment download-url
-```
-
-## Scope
-
-Only `oa approval attachment download-url` changes. The other OA attachment
-commands and the global JSON formatter retain their current behavior.
-
-## Design
-
-The command continues to invoke MCP server `oa`, tool
-`get_attachment_download_url`, with the same arguments. Its leaf declaration
-provides a command-specific `Call` callback that invokes the existing MCP
-dispatcher with HTML escaping disabled when the selected output format is
-JSON. This preserves literal `&` separators in `result.downloadUri` instead of
-rendering them as `\u0026`.
-
-For `raw`, `table`, and other non-JSON formats, the callback uses the existing
-escaped dispatcher behavior so their current rendering remains unchanged.
-
-The change does not alter the URL, decode or re-sign it, download the file, or
-change global JSON serialization.
-
-## Error Handling
-
-Authentication, MCP transport, gateway, PAT, and business errors continue
-through the existing dispatcher and retain their current classification and
-output behavior.
-
-## Verification
-
-Add a `TestCrossPlatformCoverage*` regression test that executes the real Cobra
-leaf in explicit JSON mode with a fake MCP result containing a signed URL. It
-must verify:
-
- the request still targets `oa/get_attachment_download_url`;
- the exact request arguments remain unchanged, including omission of the
-  optional boolean when the flag was not supplied;
- stdout contains literal `&OSSAccessKeyId=` and `&Signature=`;
- stdout contains no `\u0026` escape.
-
-The fake caller must report JSON format (or the command must be executed with
-`--format json`) so the test fails against the current escaped JSON path rather
-than accidentally exercising raw MCP text output.
-
-Run the focused OA attachment tests, format modified Go files, and rebuild the
-CLI. No commit is created.
@@ -4,8 +4,6 @@ go 1.25.9

 replace gitlab.alibaba-inc.com/aes/aem-go-sdk => ./third_party/aem-go-sdk

-replace safechat-go-sdk => ./third_party/safechat-go-sdk
-
 require (
 	github.com/Microsoft/go-winio v0.6.2
 	github.com/RealAlexandreAI/json-repair v0.0.15
@@ -26,7 +24,6 @@ require (
 	golang.org/x/crypto v0.49.0
 	golang.org/x/sys v0.42.0
 	golang.org/x/text v0.35.0
-	safechat-go-sdk v0.0.0
 )

 require (
@@ -68,8 +68,6 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string
 		return `{"revertedToVersion":3}`
 	case "search_doc_templates":
 		return `{"result":[{"templateId":"fixture-template-id"}]}`
-	case "list_workflows":
-		return `{"workflows":[]}`
 	case "create_document":
 		return `{"nodeId":"fixture-node"}`
 	case "list_files":
@@ -27,23 +27,12 @@ const (
 // its spelling while holding every other input constant.
 var paramAliasCompleteCommands = map[string][]string{
 	"aitable +base-search":                     {"aitable", "+base-search", "--query", "fixture"},
-	"aitable +export-data":                     {"aitable", "+export-data", "--base-id", "base-1", "--scope", "all", "--format", "excel"},
 	"aitable +field-get":                       {"aitable", "+field-get", "--base-id", "base-1", "--table-id", "table-1"},
-	"aitable +find-record":                     {"aitable", "+find-record", "--base", "base-1", "--table", "table-1", "--query", "fixture"},
 	"aitable +list-tables":                     {"aitable", "+list-tables", "--base", "base-1"},
 	"aitable +record-query":                    {"aitable", "+record-query", "--base-id", "base-1", "--table-id", "table-1", "--query", "fixture"},
-	"aitable +record-share-links":              {"aitable", "+record-share-links", "--base", "base-1", "--table", "table-1", "--record-ids", "record-1"},
 	"aitable +record-share-url":                {"aitable", "+record-share-url", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1"},
 	"aitable +table-get":                       {"aitable", "+table-get", "--base-id", "base-1"},
-	"aitable +workflow-list":                   {"aitable", "+workflow-list", "--base-id", "base-1", "--limit", "7"},
-	"aitable attachment upload":                {"aitable", "attachment", "upload", "--base-id", "base-1", "--file-name", "fixture.txt", "--size", "7"},
-	"aitable base list":                        {"aitable", "base", "list", "--cursor", "cursor-1", "--limit", "7"},
-	"aitable base update":                      {"aitable", "base", "update", "--base-id", "base-1", "--name", "Fixture Base", "--desc", "fixture description"},
-	"aitable field search-options":             {"aitable", "field", "search-options", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--keyword", "fixture", "--limit", "7"},
 	"aitable record query":                     {"aitable", "record", "query", "--base-id", "base-1", "--table-id", "table-1", "--limit", "7"},
-	"aitable workflow get":                     {"aitable", "workflow", "get", "--base-id", "base-1", "--workflow-id", "workflow-1"},
-	"aitable workflow history":                 {"aitable", "workflow", "history", "--base-id", "base-1", "--workflow-id", "workflow-1", "--after-time", "1000", "--before-time", "2000", "--page", "2", "--size", "25"},
-	"aitable workflow run":                     {"aitable", "workflow", "run", "--base-id", "base-1", "--workflow-id", "workflow-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
 	"attendance check result":                  {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"attendance +check-result":                 {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"calendar event list":                      {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
@@ -73,12 +62,12 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat +messages-list":                      {"chat", "+messages-list", "--group", "fixture-conversation", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-direct":               {"chat", "+messages-list-direct", "--user", "user-1", "--time", "2026-03-10 00:00:00", "--limit", "7"},
 	"chat +messages-list-unread-conversations": {"chat", "+messages-list-unread-conversations", "--count", "7", "--exclude-muted"},
-	"chat +messages-reply":                     {"chat", "+messages-reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"},
+	"chat +messages-reply":                     {"chat", "+messages-reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
 	"chat +messages-resource-download":         {"chat", "+messages-resource-download", "--resource-id", "resource-1", "--message-id", "message-1", "--open-conversation-id", "fixture-conversation", "--output", "downloads/fixture.bin"},
 	"chat +messages-set-pin":                   {"chat", "+messages-set-pin", "--open-conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
-	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat +messages-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
 	"chat +search-msg":                         {"chat", "+search-msg", "--group", "fixture-conversation", "--query", "fixture", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--no-enrich"},
-	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--content", "hello fixture", "--yes"},
+	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--text", "hello fixture", "--yes"},
 	"chat +unread-chats":                       {"chat", "+unread-chats", "--count", "7", "--exclude-muted"},
 	"chat bot find":                            {"chat", "bot", "find", "--query", "fixture", "--limit", "7"},
 	"chat bot search":                          {"chat", "bot", "search", "--name", "Fixture Bot", "--page", "2", "--size", "7"},
@@ -104,11 +93,11 @@ var paramAliasCompleteCommands = map[string][]string{
 	"chat message list-by-ids":                 {"chat", "message", "list-by-ids", "--msg-ids", "message-1,message-2"},
 	"chat message list-unread-conversations":   {"chat", "message", "list-unread-conversations", "--count", "7", "--exclude-muted"},
 	"chat message recall":                      {"chat", "message", "recall", "--conversation-id", "fixture-conversation", "--msg-id", "message-1", "--yes"},
-	"chat message reply":                       {"chat", "message", "reply", "--group", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--content", "hello fixture", "--yes"},
+	"chat message reply":                       {"chat", "message", "reply", "--conversation-id", "fixture-conversation", "--ref-msg-id", "message-1", "--ref-sender", appFixtureCurrentDOpenID, "--text", "hello fixture", "--yes"},
 	"chat message search-advanced":             {"chat", "message", "search-advanced", "--conversation-ids", "fixture-conversation", "--query", "fixture"},
-	"chat message send":                        {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"},
+	"chat message send":                        {"chat", "message", "send", "--user", appFixtureCurrentDOpenID, "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence", "--yes"},
 	"chat message send-by-bot":                 {"chat", "message", "send-by-bot", "--robot-code", "robot-1", "--group", "fixture-conversation", "--title", "Fixture Alert", "--text", "@user-1 @user-2 fixture", "--at-user-ids", "user-1,user-2", "--yes"},
-	"chat message send-by-webhook":             {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--content", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat message send-by-webhook":             {"chat", "message", "send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
 	"contact +dept-members":                    {"contact", "+dept-members", "--dept", "Fixture Dept"},
 	"contact +list-sub-depts":                  {"contact", "+list-sub-depts", "--dept", "1"},
 	"contact +resolve-dept":                    {"contact", "+resolve-dept", "--name", "Fixture Dept"},
@@ -127,7 +116,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc +copy":                                {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
 	"doc +create":                              {"doc", "+create", "--name", "Fixture Document", "--content", "fixture body", "--doc-format", "markdown"},
 	"doc +create-from-template":                {"doc", "+create-from-template", "--query", "fixture template", "--name", "Fixture From Template", "--folder", "folder-1", "--workspace", "workspace-1"},
-	"doc +doc-append":                          {"doc", "+doc-append", "--doc", "node-1", "--content", "fixture appendix", "--yes"},
+	"doc +doc-append":                          {"doc", "+doc-append", "--doc", "node-1", "--text", "fixture appendix", "--yes"},
 	"doc +export-submit":                       {"doc", "+export-submit", "--node", "node-1", "--export-format", "docx"},
 	"doc +fetch":                               {"doc", "+fetch", "--node", "node-1", "--scope", "section", "--start-block-id", "block-1"},
 	"doc +find-doc":                            {"doc", "+find-doc", "--query", "fixture", "--limit", "7"},
@@ -143,8 +132,8 @@ var paramAliasCompleteCommands = map[string][]string{
 	"doc +version-save":                        {"doc", "+version-save", "--node", "node-1", "--yes"},
 	"doc +update":                              {"doc", "+update", "--node", "node-1", "--command", "overwrite", "--content", `["root",{}]`, "--doc-format", "jsonml", "--expected-revision", "1", "--yes"},
 	"doc +export":                              {"doc", "+export", "--node", "node-1", "--export-format", "docx", "--output", "exports/fixture.docx"},
-	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--content", "fixture paragraph", "--yes"},
-	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--content", "fixture paragraph", "--yes"},
+	"doc block insert":                         {"doc", "block", "insert", "--node", "node-1", "--text", "fixture paragraph", "--yes"},
+	"doc block update":                         {"doc", "block", "update", "--node", "node-1", "--block-id", "block-1", "--text", "fixture paragraph", "--yes"},
 	"doc comment create":                       {"doc", "comment", "create", "--node", "node-1", "--content", "fixture comment", "--yes"},
 	"doc comment create-inline":                {"doc", "comment", "create-inline", "--node", "node-1", "--block-id", "block-1", "--start", "0", "--end", "7", "--content", "fixture comment", "--yes"},
 	"doc comment delete":                       {"doc", "comment", "delete", "--node", "node-1", "--comment-key", "comment-1", "--yes"},
@@ -207,7 +196,7 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 		"workspace": {"doc", "+copy", "--node", "node-1", "--workspace", "workspace-1", "--yes"},
 	},
 	"doc block insert": {
-		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--content", "fixture paragraph", "--yes"},
+		"parent-block": {"doc", "block", "insert", "--node", "node-1", "--parent-block", "parent-block-1", "--index", "0", "--text", "fixture paragraph", "--yes"},
 	},
 	"doc +inspect": {
 		"include-permissions": {"doc", "+inspect", "--node", "node-1", "--include-permissions"},
@@ -230,8 +219,8 @@ var paramAliasCompleteCommandVariants = map[string]map[string][]string{
 		"sender-open-dingtalk-id": {"chat", "message", "list-by-sender", "--sender-open-dingtalk-id", appFixtureCurrentDOpenID, "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--limit", "7", "--cursor", "0"},
 	},
 	"chat message send": {
-		"group": {"chat", "message", "send", "--group", "fixture-conversation", "--content", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"},
-		"file":  {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"},
+		"group":     {"chat", "message", "send", "--group", "fixture-conversation", "--text", "hello fixture", "--idempotency-key", "param-alias-equivalence-group", "--yes"},
+		"file-path": {"chat", "message", "send", "--group", "fixture-conversation", "--msg-type", "file", "--file-path", "../../go.mod", "--dentry-id", "1", "--space-id", "2", "--idempotency-key", "param-alias-equivalence-file", "--yes"},
 	},
 	"chat +conversation-set-top": {
 		"conversation-ids": {"chat", "+conversation-set-top", "--conversation-ids", "fixture-conversation-1,fixture-conversation-2", "--yes"},
@@ -271,6 +260,7 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat message list-favorites", emitted: "limit", canonical: "size"},
 	{command: "chat message list-unread-conversations", emitted: "limit", canonical: "count"},
 	{command: "chat message list-unread-conversations", emitted: "size", canonical: "count"},
+	{command: "chat message send", emitted: "file", canonical: "file-path"},
 	{command: "chat message send-by-bot", emitted: "at-users", canonical: "at-user-ids"},
 	{command: "chat message send-by-webhook", emitted: "at-user-ids", canonical: "at-users"},
 	{command: "chat +chat-update", emitted: "chat-id", canonical: "group"},
@@ -288,7 +278,7 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat +chat-members-get", emitted: "chat", canonical: "id"},
 	{command: "chat +messages-list", emitted: "start", canonical: "time"},
 	{command: "chat +messages-reply", emitted: "msg-id", canonical: "ref-msg-id"},
-	{command: "chat +messages-reply", emitted: "chat", canonical: "group"},
+	{command: "chat +messages-reply", emitted: "chat", canonical: "conversation-id"},
 	{command: "chat +flag-cancel", emitted: "group", canonical: "conversation-id"},
 	{command: "chat +flag-cancel", emitted: "chat", canonical: "conversation-id"},
 	{command: "chat +flag-create", emitted: "group", canonical: "conversation-id"},
@@ -382,113 +372,16 @@ var paramAliasNewDriveCases = []struct {
 	{command: "drive +upload", emitted: "file-id", canonical: "node"},
 }

-// paramAliasAITableDeleteDisableCompleteCommands contains complete invocations
-// for every AITable delete/disable command whose confirmation boundary is
-// reached by aliases introduced in the AITable expansion. These templates are
-// intentionally separate from paramAliasCompleteCommands: that map mirrors
-// the reviewed validation fixture one-for-one, while this matrix exhaustively
-// proves the safety boundary for generated aliases beyond the fixture sample.
-var paramAliasAITableDeleteDisableCompleteCommands = map[string][]string{
-	"aitable +advperm-disable":      {"aitable", "+advperm-disable", "--base-id", "base-1", "--yes"},
-	"aitable +base-delete":          {"aitable", "+base-delete", "--base-id", "base-1", "--yes"},
-	"aitable +chart-delete":         {"aitable", "+chart-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"},
-	"aitable +dashboard-delete":     {"aitable", "+dashboard-delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"},
-	"aitable +field-delete":         {"aitable", "+field-delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
-	"aitable +form-delete":          {"aitable", "+form-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
-	"aitable +record-delete":        {"aitable", "+record-delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
-	"aitable +role-delete":          {"aitable", "+role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"},
-	"aitable +section-delete":       {"aitable", "+section-delete", "--base-id", "base-1", "--section-id", "section-1", "--yes"},
-	"aitable +table-delete":         {"aitable", "+table-delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"},
-	"aitable +view-delete":          {"aitable", "+view-delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
-	"aitable +workflow-disable":     {"aitable", "+workflow-disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"},
-	"aitable advperm disable":       {"aitable", "advperm", "disable", "--base-id", "base-1", "--yes"},
-	"aitable advperm role-delete":   {"aitable", "advperm", "role-delete", "--base-id", "base-1", "--role-id", "role-1", "--yes"},
-	"aitable base delete":           {"aitable", "base", "delete", "--base-id", "base-1", "--yes"},
-	"aitable chart delete":          {"aitable", "chart", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--chart-id", "chart-1", "--yes"},
-	"aitable dashboard delete":      {"aitable", "dashboard", "delete", "--base-id", "base-1", "--dashboard-id", "dashboard-1", "--yes"},
-	"aitable field delete":          {"aitable", "field", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
-	"aitable form delete":           {"aitable", "form", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
-	"aitable form questions delete": {"aitable", "form", "questions", "delete", "--base-id", "base-1", "--table-id", "table-1", "--field-id", "field-1", "--yes"},
-	"aitable record delete":         {"aitable", "record", "delete", "--base-id", "base-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
-	"aitable table delete":          {"aitable", "table", "delete", "--base-id", "base-1", "--table-id", "table-1", "--yes"},
-	"aitable view delete":           {"aitable", "view", "delete", "--base-id", "base-1", "--table-id", "table-1", "--view-id", "view-1", "--yes"},
-	"aitable workflow disable":      {"aitable", "workflow", "disable", "--base-id", "base-1", "--workflow-id", "workflow-1", "--yes"},
-}
-
-// paramAliasNewAITableDeleteDisableCases is the exhaustive set of alias
-// tuples newly introduced by this change on AITable delete/disable commands
-// that require confirmation. Every tuple must remain on both sides of the
-// confirmation gate: rejected with zero calls before --yes, and exactly
-// payload-equivalent to its canonical spelling after --yes.
-var paramAliasNewAITableDeleteDisableCases = []struct {
+// paramAliasNewDriveConfirmationCases selects one newly reviewed alias for
+// every Drive command in the expansion whose declared runtime safety requires
+// confirmation. The full matrix below proves all spellings preserve the
+// confirmed payload; this smaller matrix proves aliases cannot cross the
+// confirmation boundary before any transport call is made.
+var paramAliasNewDriveConfirmationCases = []struct {
 	command   string
 	emitted   string
 	canonical string
 }{
-	{command: "aitable +advperm-disable", emitted: "base", canonical: "base-id"},
-	{command: "aitable +advperm-disable", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +base-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +base-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +chart-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +chart-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +dashboard-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +dashboard-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +field-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +field-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +field-delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable +form-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +form-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +form-delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable +record-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +record-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +record-delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable +role-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +role-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +section-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +section-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +table-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +table-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +table-delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable +view-delete", emitted: "base", canonical: "base-id"},
-	{command: "aitable +view-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +view-delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable +workflow-disable", emitted: "base", canonical: "base-id"},
-	{command: "aitable +workflow-disable", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable +workflow-disable", emitted: "flow-id", canonical: "workflow-id"},
-	{command: "aitable advperm disable", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable advperm role-delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable base delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable chart delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable dashboard delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable field delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable field delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable form delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable form delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable form questions delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable form questions delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable record delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable record delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable table delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable table delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable view delete", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable view delete", emitted: "table", canonical: "table-id"},
-	{command: "aitable workflow disable", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable workflow disable", emitted: "flow-id", canonical: "workflow-id"},
-}
-
-// paramAliasNewConfirmationCases selects newly reviewed aliases for commands
-// whose declared runtime safety requires confirmation. The full matrix below
-// proves all spellings preserve the confirmed payload; this smaller matrix
-// proves aliases cannot cross the confirmation boundary before any transport
-// call is made.
-var paramAliasNewConfirmationCases = []struct {
-	command   string
-	emitted   string
-	canonical string
-}{
-	{command: "aitable workflow run", emitted: "base-token", canonical: "base-id"},
-	{command: "aitable workflow run", emitted: "flow-id", canonical: "workflow-id"},
-	{command: "aitable workflow run", emitted: "table", canonical: "table-id"},
 	{command: "drive +delete", emitted: "file-id", canonical: "node"},
 	{command: "drive +publish-unset", emitted: "document-url", canonical: "node"},
 	{command: "drive +recycle-restore", emitted: "recycle-item-id", canonical: "id"},
@@ -509,27 +402,7 @@ var paramAliasNewConfirmationCases = []struct {
 // That duplicated command construction was enough to push the pre-existing
 // macOS app suite beyond its package-level 10-minute timeout.
 var paramAliasRepresentativePayloadCases = map[string]bool{
-	paramAliasPayloadCaseKey("aitable +export-data", "export-format"):                true, // shortcut-local export format keeps the final payload
-	paramAliasPayloadCaseKey("aitable +find-record", "base-id"):                      true, // shortcut Base ID compatibility
-	paramAliasPayloadCaseKey("aitable +find-record", "table-id"):                     true, // shortcut Table ID compatibility
 	paramAliasPayloadCaseKey("aitable +record-query", "base"):                        true, // concept alias on a shortcut read
-	paramAliasPayloadCaseKey("aitable +record-share-links", "base-id"):               true, // observed experiment Base ID spelling
-	paramAliasPayloadCaseKey("aitable +record-share-links", "table-id"):              true, // observed experiment Table ID spelling
-	paramAliasPayloadCaseKey("aitable +workflow-list", "max-results"):                true, // shortcut pagination-size alias
-	paramAliasPayloadCaseKey("aitable attachment upload", "file-size"):               true, // byte-size command override
-	paramAliasPayloadCaseKey("aitable base list", "next-cursor"):                     true, // cursor concept alias
-	paramAliasPayloadCaseKey("aitable base update", "description"):                   true, // plain description alias on a write command
-	paramAliasPayloadCaseKey("aitable field search-options", "query"):                true, // search keyword concept alias
-	paramAliasPayloadCaseKey("aitable workflow get", "flow-id"):                      true, // workflow ID concept alias
-	paramAliasPayloadCaseKey("aitable workflow history", "base-token"):               true, // Base ID concept alias
-	paramAliasPayloadCaseKey("aitable workflow history", "end-time"):                 true, // upper time-bound override
-	paramAliasPayloadCaseKey("aitable workflow history", "flow-id"):                  true, // workflow ID concept alias
-	paramAliasPayloadCaseKey("aitable workflow history", "page-index"):               true, // zero-based page override
-	paramAliasPayloadCaseKey("aitable workflow history", "page-size"):                true, // page-size concept alias
-	paramAliasPayloadCaseKey("aitable workflow history", "start-time"):               true, // lower time-bound override
-	paramAliasPayloadCaseKey("aitable workflow run", "base-token"):                   true, // Base ID concept alias on a confirmed write
-	paramAliasPayloadCaseKey("aitable workflow run", "flow-id"):                      true, // workflow ID concept alias on a confirmed write
-	paramAliasPayloadCaseKey("aitable workflow run", "table"):                        true, // Table ID concept alias on a confirmed write
 	paramAliasPayloadCaseKey("attendance check result", "user-ids"):                  true, // list-valued concept alias
 	paramAliasPayloadCaseKey("calendar event list", "date"):                          true, // time concept alias
 	paramAliasPayloadCaseKey("chat message add-favorite", "msg-id"):                  true, // scoped IM identifier alias
@@ -553,11 +426,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("doc +update", "revision"):                              true, // optimistic edit revision alias
 	paramAliasPayloadCaseKey("doc +access-grant", "doc-id"):                          true, // permission write keeps document identity
 	paramAliasPayloadCaseKey("doc +version-revert", "version-number"):                true, // high-write version role with canonical confirmation
-	paramAliasPayloadCaseKey("chat +messages-reply", "conversation-id"):              true, // renamed conversation Primary keeps final reply payload
-	paramAliasPayloadCaseKey("chat message send", "file-path"):                       true, // renamed local-file Primary reaches the same final payload
-	paramAliasPayloadCaseKey("doc +doc-append", "text"):                              true, // shortcut content rename keeps append payload
-	paramAliasPayloadCaseKey("doc block insert", "text"):                             true, // block write content compatibility alias
-	paramAliasPayloadCaseKey("doc block update", "text"):                             true, // update uses the same typed compatibility path
+	paramAliasPayloadCaseKey("doc block insert", "content"):                          true, // block write content alias
 	paramAliasPayloadCaseKey("doc block insert", "parent-block-id"):                  true, // scoped block-role alias
 	paramAliasPayloadCaseKey("doc comment delete", "comment-id"):                     true, // destructive comment-key alias
 	paramAliasPayloadCaseKey("doc comment reply", "mentioned-open-conversation-ids"): true, // list-valued group mention role
@@ -760,116 +629,13 @@ func TestCrossPlatformCoverageNewDriveParamAliasesReachCanonicalEquivalentFinalP
 	}
 }

-func TestCrossPlatformCoverageNewAITableDeleteDisableAliasesPreserveConfirmationAndPayload(t *testing.T) {
-	coveredCommands := make(map[string]bool)
-	reviewedAliases := make(map[string]string, len(paramAliasNewAITableDeleteDisableCases))
-	for _, test := range paramAliasNewAITableDeleteDisableCases {
-		test := test
-		caseKey := paramAliasPayloadCaseKey(test.command, test.emitted)
-		if previous, duplicate := reviewedAliases[caseKey]; duplicate {
-			t.Fatalf("duplicate AITable delete/disable alias case %q: --%s and --%s", caseKey, previous, test.canonical)
-		}
-		reviewedAliases[caseKey] = test.canonical
-		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
-			complete, ok := paramAliasAITableDeleteDisableCompleteCommands[test.command]
-			if !ok {
-				t.Fatal("reviewed AITable delete/disable alias has no complete safety template")
-			}
-			coveredCommands[test.command] = true
-
-			canonicalArgs := append([]string(nil), complete...)
-			aliasArgs, replacements := replaceLongFlag(canonicalArgs, test.canonical, test.emitted)
-			if replacements != 1 {
-				t.Fatalf("complete command must contain canonical --%s exactly once; replacements=%d args=%v", test.canonical, replacements, canonicalArgs)
-			}
-			unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes")
-			if removals != 1 {
-				t.Fatalf("safety template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs)
-			}
-
-			entry, exists := cli.LookupParamAlias(test.command)
-			target, active := entry.ResolveAlias(test.emitted)
-			if !exists || !active || target != test.canonical {
-				t.Fatalf("reviewed AITable alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
-			}
-
-			unconfirmedCaller := &paramAliasCaptureCaller{}
-			ctx, unconfirmedErr := executeParamAliasPayloadE2E(t, unconfirmedCaller, unconfirmedArgs...)
-			if ctx == nil {
-				t.Fatal("unconfirmed AITable alias command skipped PreParse")
-			}
-			var appErr *apperrors.Error
-			if !errors.As(unconfirmedErr, &appErr) || appErr.Reason != "confirmation_required" {
-				t.Fatalf("unconfirmed AITable alias command error = %#v, want confirmation_required\nargs=%v", unconfirmedErr, unconfirmedArgs)
-			}
-			if len(unconfirmedCaller.calls) != 0 {
-				t.Fatalf("unconfirmed AITable alias crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, unconfirmedCaller.calls)
-			}
-
-			canonicalCaller := &paramAliasCaptureCaller{}
-			_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
-			if canonicalErr != nil {
-				t.Fatalf("confirmed canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
-			}
-			if len(canonicalCaller.calls) == 0 {
-				t.Fatalf("confirmed canonical command reached no final transport payload: args=%v", canonicalArgs)
-			}
-
-			aliasCaller := &paramAliasCaptureCaller{}
-			aliasCtx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
-			if aliasErr != nil {
-				t.Fatalf("confirmed alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
-			}
-			if aliasCtx == nil {
-				t.Fatal("confirmed AITable alias command skipped PreParse")
-			}
-			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
-				t.Fatalf("confirmed final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
-			}
-		})
-	}
-
-	for command := range paramAliasAITableDeleteDisableCompleteCommands {
-		if !coveredCommands[command] {
-			t.Errorf("AITable delete/disable safety template %q has no reviewed alias case", command)
-		}
-	}
-	if len(coveredCommands) != len(paramAliasAITableDeleteDisableCompleteCommands) {
-		t.Fatalf("AITable delete/disable safety coverage = %d commands, want %d", len(coveredCommands), len(paramAliasAITableDeleteDisableCompleteCommands))
-	}
-
-	activeAliases := 0
-	for command := range paramAliasAITableDeleteDisableCompleteCommands {
-		entry, exists := cli.LookupParamAlias(command)
-		if !exists {
-			t.Errorf("AITable delete/disable safety command %q has no generated alias entry", command)
-			continue
-		}
-		for emitted, canonical := range entry.Aliases {
-			activeAliases++
-			caseKey := paramAliasPayloadCaseKey(command, emitted)
-			reviewedCanonical, reviewed := reviewedAliases[caseKey]
-			if !reviewed {
-				t.Errorf("active AITable delete/disable alias %q --%s -> --%s has no confirmation/payload case", command, emitted, canonical)
-				continue
-			}
-			if reviewedCanonical != canonical {
-				t.Errorf("reviewed AITable delete/disable alias %q --%s target = --%s, generated --%s", command, emitted, reviewedCanonical, canonical)
-			}
-		}
-	}
-	if activeAliases != len(reviewedAliases) {
-		t.Fatalf("AITable delete/disable generated alias coverage = %d, want %d reviewed cases", activeAliases, len(reviewedAliases))
-	}
-}
-
-func TestCrossPlatformCoverageNewParamAliasesCannotBypassConfirmation(t *testing.T) {
-	for _, test := range paramAliasNewConfirmationCases {
+func TestCrossPlatformCoverageNewDriveParamAliasesCannotBypassConfirmation(t *testing.T) {
+	for _, test := range paramAliasNewDriveConfirmationCases {
 		test := test
 		t.Run(test.command+"/"+test.emitted, func(t *testing.T) {
 			complete, ok := paramAliasCompleteCommand(test.command, test.canonical)
 			if !ok {
-				t.Fatal("reviewed confirmation alias has no complete-command E2E template")
+				t.Fatal("reviewed Drive confirmation alias has no complete-command E2E template")
 			}
 			aliasArgs, replacements := replaceLongFlag(complete, test.canonical, test.emitted)
 			if replacements != 1 {
@@ -883,7 +649,7 @@ func TestCrossPlatformCoverageNewParamAliasesCannotBypassConfirmation(t *testing
 			entry, exists := cli.LookupParamAlias(test.command)
 			target, active := entry.ResolveAlias(test.emitted)
 			if !exists || !active || target != test.canonical {
-				t.Fatalf("reviewed confirmation alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
+				t.Fatalf("reviewed Drive alias --%s resolution = exists:%v active:%v target:%q, want --%s", test.emitted, exists, active, target, test.canonical)
 			}

 			caller := &paramAliasCaptureCaller{}
@@ -264,7 +264,7 @@ func TestRootChatMediaUploadWithoutAppCredentialsReturnsMigrationValidation(t *t
 	}

 	got := output.String() + "\n" + err.Error()
-	for _, want := range []string{"已下线", "chat message send --msg-type file --file"} {
+	for _, want := range []string{"已下线", "chat message send --msg-type file --file-path"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("chat media upload migration output missing %q:\n%s", want, got)
 		}
@@ -439,7 +439,7 @@ func TestChatFileUploadDownlinedButMessageFileSendStays(t *testing.T) {
 		t.Fatalf("chat file upload error = nil, want downline error\n%s", got)
 	}
 	got = got + "\n" + err.Error()
-	for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file"} {
+	for _, want := range []string{"已下线", "upload_conversation_file_by_url", "chat message send --msg-type file --file-path"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("chat file upload output missing %q:\n%s", want, got)
 		}
@@ -1,49 +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.
-
-package app
-
-import "testing"
-
-func TestCrossPlatformCoverageCalendarAgendaFinalSchemaPreservesCompositeProperties(t *testing.T) {
-	snapshot := fullSchemaSnapshotForTest(t)
-	tool := snapshot.Tools["calendar.shortcut_agenda"]
-	if tool == nil {
-		t.Fatal("calendar.shortcut_agenda is missing from final Schema")
-	}
-	parameters := schemaContractMap(tool["parameters"])
-	for flag, want := range map[string]string{
-		"start": "start",
-		"end":   "end",
-	} {
-		parameter := parameters[flag]
-		if parameter == nil {
-			t.Fatalf("calendar.shortcut_agenda --%s is missing from final Schema", flag)
-		}
-		if got := schemaContractString(parameter["property"]); got != want {
-			t.Errorf("calendar.shortcut_agenda --%s property=%q, want %q", flag, got, want)
-		}
-	}
-	if got := schemaContractString(tool["interface_mode"]); got != "composite" {
-		t.Fatalf("calendar.shortcut_agenda interface_mode=%q, want composite", got)
-	}
-	result := schemaContractMap(tool["result"])
-	dataSchema := schemaContractMap(result["data_schema"])
-	properties := schemaContractMap(dataSchema["properties"])
-	for _, field := range []string{"hasMore", "nextCursor"} {
-		if _, exists := properties[field]; exists {
-			t.Fatalf("calendar.shortcut_agenda Result data_schema leaked pagination field %q", field)
-		}
-	}
-	if properties["complete"] == nil {
-		t.Fatal("calendar.shortcut_agenda Result data_schema is missing complete")
-	}
-	pagination, ok := tool["pagination"].(map[string]any)
-	if !ok {
-		t.Fatalf("calendar.shortcut_agenda pagination=%T, want object", tool["pagination"])
-	}
-	if got := schemaContractString(pagination["meta_path"]); got != "meta.pagination" {
-		t.Fatalf("calendar.shortcut_agenda pagination meta_path=%q, want meta.pagination", got)
-	}
-}
@@ -1,166 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package app
-
-import (
-	"bytes"
-	"encoding/json"
-	"reflect"
-	"strings"
-	"testing"
-)
-
-func TestCrossPlatformCoverageOAAttachmentDeliveredSchemaMatchesExecutableHelp(t *testing.T) {
-	tests := []struct {
-		cliPath        string
-		canonical      string
-		rpc            string
-		description    string
-		effect         string
-		resultType     string
-		resultFields   map[string]string
-		sensitivePaths []string
-	}{
-		{
-			cliPath:     "oa approval attachment download-url",
-			canonical:   "oa.get_attachment_download_url",
-			rpc:         "get_attachment_download_url",
-			description: "获取审批附件下载授权并生成临时下载链接",
-			effect:      "read",
-			resultType:  "object",
-			resultFields: map[string]string{
-				"spaceId": "integer", "agentId": "integer", "downloadUri": "string",
-				"class": "string", "fileId": "string",
-			},
-			sensitivePaths: []string{"downloadUri"},
-		},
-		{
-			cliPath:     "oa approval attachment authorize-download",
-			canonical:   "oa.auth_download_file",
-			rpc:         "auth_download_file",
-			description: "批量授权当前用户下载指定的审批钉盘文件",
-			effect:      "write",
-			resultType:  "boolean",
-		},
-		{
-			cliPath:     "oa approval attachment authorize-preview",
-			canonical:   "oa.auth_preview_attachment",
-			rpc:         "auth_preview_attachment",
-			description: "批量授权当前用户预览审批单中的附件",
-			effect:      "write",
-			resultType:  "object",
-			resultFields: map[string]string{
-				"spaceId": "integer", "agentId": "integer", "class": "string",
-			},
-		},
-	}
-
-	for _, test := range tests {
-		t.Run(test.rpc, func(t *testing.T) {
-			root := NewRootCommand()
-			command := exactCommandForTest(root, test.cliPath)
-			if command == nil {
-				t.Fatalf("executable command %q is missing", test.cliPath)
-			}
-
-			var stdout, stderr bytes.Buffer
-			root.SetOut(&stdout)
-			root.SetErr(&stderr)
-			root.SetArgs([]string{"schema", test.cliPath, "--format", "json"})
-			if err := root.Execute(); err != nil {
-				t.Fatalf("execute delivery schema leaf: %v; stderr=%s", err, stderr.String())
-			}
-
-			var tool map[string]any
-			if err := json.Unmarshal(stdout.Bytes(), &tool); err != nil {
-				t.Fatalf("decode delivery schema leaf: %v", err)
-			}
-			if got := schemaContractString(tool["canonical_path"]); got != test.canonical {
-				t.Fatalf("canonical_path = %q, want %q", got, test.canonical)
-			}
-			if got := schemaContractString(tool["primary_cli_path"]); got != test.cliPath {
-				t.Fatalf("primary_cli_path = %q, want %q", got, test.cliPath)
-			}
-			if got := schemaContractString(tool["description"]); !strings.HasPrefix(got, test.description) {
-				t.Fatalf("description = %q, want prefix %q", got, test.description)
-			}
-			if got := schemaContractString(tool["interface_mode"]); got != "mcp" {
-				t.Fatalf("interface_mode = %q, want mcp", got)
-			}
-			if got := schemaContractString(tool["availability"]); got != "available" {
-				t.Fatalf("availability = %q, want available", got)
-			}
-			interfaceRef := schemaInterfaceObject(tool["interface_ref"])
-			if got := schemaContractString(interfaceRef["product_id"]); got != "oa" {
-				t.Fatalf("interface_ref.product_id = %q, want oa", got)
-			}
-			if got := schemaContractString(interfaceRef["rpc_name"]); got != test.rpc {
-				t.Fatalf("interface_ref.rpc_name = %q, want %q", got, test.rpc)
-			}
-			if got := schemaContractString(tool["effect"]); got != test.effect {
-				t.Fatalf("effect = %q, want %q", got, test.effect)
-			}
-			if got := schemaContractString(tool["risk"]); got != "low" {
-				t.Fatalf("risk = %q, want low", got)
-			}
-			if got := schemaContractString(tool["confirmation"]); got != "not_required" {
-				t.Fatalf("confirmation = %q, want not_required", got)
-			}
-			if got := schemaContractString(tool["idempotency"]); got != "idempotent" {
-				t.Fatalf("idempotency = %q, want idempotent", got)
-			}
-			fullResult := oaAttachmentResultContract(t, tool, test.resultType, test.resultFields, test.sensitivePaths)
-
-			stdout.Reset()
-			stderr.Reset()
-			root.SetArgs([]string{"schema", test.cliPath, "--compact", "--format", "json"})
-			if err := root.Execute(); err != nil {
-				t.Fatalf("execute compact delivery schema leaf: %v; stderr=%s", err, stderr.String())
-			}
-			var compactTool map[string]any
-			if err := json.Unmarshal(stdout.Bytes(), &compactTool); err != nil {
-				t.Fatalf("decode compact delivery schema leaf: %v", err)
-			}
-			compactResult, ok := compactTool["result"].(map[string]any)
-			if !ok {
-				t.Fatalf("compact result = %#v, want object", compactTool["result"])
-			}
-			if !reflect.DeepEqual(compactResult, fullResult) {
-				t.Fatalf("compact/full result projection differs\ncompact: %#v\nfull: %#v", compactResult, fullResult)
-			}
-			if problem := schemaHelpFlagCompletenessProblem(test.canonical, test.cliPath, command, tool); problem != "" {
-				t.Fatal(problem)
-			}
-		})
-	}
-}
-
-func oaAttachmentResultContract(t *testing.T, tool map[string]any, resultType string, fields map[string]string, sensitivePaths []string) map[string]any {
-	t.Helper()
-	result, ok := tool["result"].(map[string]any)
-	if !ok {
-		t.Fatalf("full result = %#v, want object", tool["result"])
-	}
-	if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !reflect.DeepEqual(got, want) {
-		t.Fatalf("result.outcomes = %#v, want %#v", got, want)
-	}
-	if got := schemaContractStringSlice(result["sensitive_paths"]); !reflect.DeepEqual(got, sensitivePaths) {
-		t.Fatalf("result.sensitive_paths = %#v, want %#v", got, sensitivePaths)
-	}
-	dataSchema, ok := result["data_schema"].(map[string]any)
-	if !ok || schemaContractString(dataSchema["type"]) != resultType {
-		t.Fatalf("result.data_schema = %#v, want type %q", result["data_schema"], resultType)
-	}
-	properties, _ := dataSchema["properties"].(map[string]any)
-	if len(properties) != len(fields) {
-		t.Fatalf("result.data_schema.properties = %#v, want fields %#v", properties, fields)
-	}
-	for name, fieldType := range fields {
-		property, ok := properties[name].(map[string]any)
-		if !ok || schemaContractString(property["type"]) != fieldType {
-			t.Fatalf("result.data_schema.properties.%s = %#v, want type %q", name, properties[name], fieldType)
-		}
-	}
-	return result
-}
@@ -16,12 +16,12 @@ import (
 )

 const (
-	publicShortcutCount = 435
+	publicShortcutCount = 418
 	// schemaPublishedShortcutCount counts every delivered *.shortcut_* tool,
 	// including the hidden historical minutes.shortcut_minutes_search contract.
-	schemaPublishedShortcutCount = 438
+	schemaPublishedShortcutCount = 420
 	// publiclyDeliveredShortcutCount is the public-catalog subset of that surface.
-	publiclyDeliveredShortcutCount = 435
+	publiclyDeliveredShortcutCount = 418
 )

 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -140,25 +140,6 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 	assertChatCatalogCompleteLeafContracts(t)
 }

-func TestCrossPlatformCoverageAITableTableBootstrapPublishesResultContract(t *testing.T) {
-	leaf := executeShortcutSchemaQuery(t, "--cli-path", "aitable +table-bootstrap")
-	result, _ := leaf["result"].(map[string]any)
-	if got, want := schemaContractStringSlice(result["outcomes"]), []string{"success", "failure"}; !schemaContractJSONEqual(got, want) {
-		t.Fatalf("aitable +table-bootstrap outcomes = %#v, want %#v", got, want)
-	}
-	dataSchema, _ := result["data_schema"].(map[string]any)
-	properties := schemaContractMap(dataSchema["properties"])
-	status := properties["status"]
-	if got, want := schemaContractStringSlice(status["enum"]), []string{"success", "planned", "partial_success", "unknown"}; !schemaContractJSONEqual(got, want) {
-		t.Fatalf("aitable +table-bootstrap status enum = %#v, want %#v", got, want)
-	}
-	for _, property := range []string{"contractVersion", "operation", "executed", "retryable", "plan", "completedSteps", "verification", "checkpoint", "knownSideEffects", "result"} {
-		if properties[property] == nil {
-			t.Errorf("aitable +table-bootstrap final Result data_schema is missing %q", property)
-		}
-	}
-}
-
 func TestDeliveryWikiSpaceSearchDeclaresCompatibilityAdapter(t *testing.T) {
 	leaf := executeShortcutSchemaQuery(t, "--cli-path", "wiki +space-search")
 	if got := schemaContractString(leaf["interface_mode"]); got != "composite" {
@@ -0,0 +1,249 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+func TestToolSearchDeliveryActionSiblingRouting(t *testing.T) {
+	registerSchemaRuntimeDelivery()
+	// This test pins the action_v1 structured sibling routing itself, decoupled
+	// from the production default (now the fielded BM25 ensemble, which has no
+	// structured multiplier and cannot right-size these sibling queries).
+	config := cli.DefaultToolSearchConfig()
+	config.LexicalAlgorithm = cli.ToolSearchLexicalBM25Action
+	engine, err := cli.NewDeliveryToolSearchEngineWithConfig(config)
+	if err != nil {
+		t.Fatalf("NewDeliveryToolSearchEngineWithConfig() error = %v", err)
+	}
+	tests := []struct {
+		query string
+		gold  string
+	}{
+		{query: "创建一场新的会议日程", gold: "calendar.create_calendar_event"},
+		{query: "给钉盘文件添加同事阅读权限", gold: "drive.add_permission"},
+		// The new main Catalog declares shortcut_fetch as a reviewed equivalent
+		// read surface, so this query has graded-equivalent Top-1 answers.
+		{query: "读取钉钉在线文字文档正文", gold: "doc.shortcut_fetch|doc.get_document_content"},
+		{query: "查询当前用户待审批任务 ID", gold: "oa.list_pending_tasks"},
+		{query: "同意指定审批任务", gold: "oa.approve_processInstance"},
+		{query: "按群名关键词搜索群聊", gold: "chat.search_groups"},
+	}
+	for _, test := range tests {
+		t.Run(test.gold, func(t *testing.T) {
+			response, searchErr := engine.Search(context.Background(), cli.ToolSearchRequest{Query: test.query, Limit: 5})
+			if searchErr != nil {
+				t.Fatalf("Search() error = %v", searchErr)
+			}
+			if len(response.Candidates) == 0 || !containsCanonicalAlternative(test.gold, response.Candidates[0].CanonicalPath) {
+				t.Fatalf("Search(%q) candidates = %#v, want %s first", test.query, response.Candidates, test.gold)
+			}
+		})
+	}
+}
+
+func containsCanonicalAlternative(alternatives, candidate string) bool {
+	for _, alternative := range strings.Split(alternatives, "|") {
+		if candidate == alternative {
+			return true
+		}
+	}
+	return false
+}
+
+func TestToolSearchDeliveryDiagnosticTrustAndChineseSlices(t *testing.T) {
+	registerSchemaRuntimeDelivery()
+	workflows := []cli.ToolSearchWorkflowEvaluationCase{{
+		ID:         "chat-send-file-and-check-read",
+		Query:      "给群里发文件，并确认群成员是否已读",
+		Subqueries: []string{"以当前用户身份给群聊发送本地文件", "查询指定消息的已读状态和人员"},
+		Required:   []string{"chat.send_personal_message", "chat.query_msg_read_status"},
+	}}
+	report, err := cli.BuildDeliveryToolSearchDiagnosticComparison(context.Background(), workflows)
+	if err != nil {
+		t.Fatalf("BuildDeliveryToolSearchDiagnosticComparison() error = %v", err)
+	}
+	// Do not pin absolute Catalog-size counts here: they go stale when main
+	// adds tools. Enforce the size-independent trust contract below; observed
+	// counts are logged for CI forensics and live in the generated comparison
+	// JSON (make generate-tool-search-comparison).
+	t.Logf("intent proxy = %+v excluded_over_budget=%d", report.IntentProxy, report.IntentExcludedOverBudget)
+	t.Logf("language slices = %+v", report.IntentLanguageSlices)
+	t.Logf("context comparison = %+v", report.Context)
+	if report.IntentProxy.Cases == 0 {
+		t.Fatal("intent proxy population is empty; the diagnostic set did not build")
+	}
+	if report.IntentProxy.ZeroResultRate != 0 {
+		t.Fatalf("intent proxy zero-result rate = %v, want every reviewed intent to retrieve something", report.IntentProxy.ZeroResultRate)
+	}
+	for _, slice := range []string{"chinese_only", "mixed_chinese_ascii"} {
+		if report.IntentLanguageSlices[slice].Cases == 0 {
+			t.Fatalf("language slice %q is empty: %+v", slice, report.IntentLanguageSlices)
+		}
+	}
+	identity := report.Trust.Identity
+	// Identity coverage must stay exhaustive over the whole Catalog. Deriving the
+	// expected count from the same report keeps that contract enforced without
+	// hardcoding a tool count.
+	if identity.CanonicalCases != report.Context.ToolCount || identity.NFKCCases != report.Context.ToolCount {
+		t.Fatalf("identity coverage = %+v, want one case per %d Catalog tools", identity, report.Context.ToolCount)
+	}
+	if identity.CanonicalPassRate != 1 || identity.PrimaryCLIPassRate != 1 ||
+		identity.AliasCases == 0 || identity.AliasPassRate != 1 || identity.NFKCPassRate != 1 ||
+		identity.ExactFilteredPassRate != 1 {
+		t.Fatalf("identity trust = %+v", identity)
+	}
+	integrity := report.Trust.Integrity
+	if integrity.CatalogBindingFailures != 0 || integrity.UnknownCandidateCount != 0 || integrity.IneligibleCandidateCount != 0 || integrity.ResponseBudgetViolations != 0 {
+		t.Fatalf("integrity violations = %+v", integrity)
+	}
+	if report.Context.ToolCount == 0 || report.Context.ReductionVsFullSchema < 0.99 {
+		t.Fatalf("context comparison = %+v", report.Context)
+	}
+}
+
+func TestSchemaSearchInspectCatalogVersionContract(t *testing.T) {
+	registerSchemaRuntimeDelivery()
+	search := cli.NewSchemaCommand()
+	var searchOutput bytes.Buffer
+	search.SetOut(&searchOutput)
+	search.SetArgs([]string{"search", "--query", "chat.query_msg_read_status"})
+	if err := search.Execute(); err != nil {
+		t.Fatalf("schema search execute: %v", err)
+	}
+	var response cli.ToolSearchResponse
+	if err := json.Unmarshal(searchOutput.Bytes(), &response); err != nil {
+		t.Fatalf("decode search response: %v", err)
+	}
+	if response.Strategy != "exact_guard" || len(response.Candidates) != 1 || response.Candidates[0].CanonicalPath != "chat.query_msg_read_status" {
+		t.Fatalf("search response = %#v", response)
+	}
+
+	inspect := cli.NewSchemaCommand()
+	var inspectOutput bytes.Buffer
+	inspect.SetOut(&inspectOutput)
+	inspect.SetArgs([]string{
+		"chat.query_msg_read_status", "--compact",
+		"--expected-source-hash", response.Catalog.SourceHash,
+		"--expected-surface-hash", response.Catalog.SurfaceHash,
+	})
+	if err := inspect.Execute(); err != nil {
+		t.Fatalf("schema inspect execute: %v", err)
+	}
+	var payload cli.SchemaInspectV1Response
+	if err := json.Unmarshal(inspectOutput.Bytes(), &payload); err != nil {
+		t.Fatalf("decode inspect response: %v", err)
+	}
+	if payload.Version != "schema-inspect.v1" || payload.Catalog != response.Catalog || payload.ToolSpec["canonical_path"] != "chat.query_msg_read_status" {
+		t.Fatalf("inspect envelope = %#v", payload)
+	}
+
+	stale := cli.NewSchemaCommand()
+	stale.SilenceErrors = true
+	stale.SilenceUsage = true
+	stale.SetArgs([]string{
+		"chat.query_msg_read_status", "--compact",
+		"--expected-source-hash", "sha256:stale",
+		"--expected-surface-hash", response.Catalog.SurfaceHash,
+	})
+	err := stale.Execute()
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Reason != "catalog_changed" || typed.Category != apperrors.CategoryDiscovery {
+		t.Fatalf("stale inspect error = %#v", err)
+	}
+
+	incomplete := cli.NewSchemaCommand()
+	incomplete.SilenceErrors = true
+	incomplete.SilenceUsage = true
+	incomplete.SetArgs([]string{
+		"chat.query_msg_read_status",
+		"--expected-source-hash", response.Catalog.SourceHash,
+	})
+	err = incomplete.Execute()
+	if !errors.As(err, &typed) || typed.Category != apperrors.CategoryValidation {
+		t.Fatalf("incomplete inspect version error = %#v", err)
+	}
+}
+
+func TestSchemaSearchRejectsIgnoredGlobalOutputFlags(t *testing.T) {
+	for _, args := range [][]string{
+		{"schema", "search", "--query", "查询群消息已读状态", "--fields", "canonical_path"},
+		{"schema", "search", "--query", "查询群消息已读状态", "--jq", ".candidates"},
+		{"schema", "search", "--query", "查询群消息已读状态", "--format", "pretty"},
+	} {
+		root := NewRootCommand()
+		root.SilenceErrors = true
+		root.SilenceUsage = true
+		root.SetArgs(args)
+		err := root.Execute()
+		var typed *apperrors.Error
+		if !errors.As(err, &typed) || typed.Category != apperrors.CategoryValidation {
+			t.Fatalf("args %v error = %#v, want validation", args, err)
+		}
+	}
+}
+
+// BenchmarkToolSearchDeliveryChineseQuery measures the shipped search path
+// against the complete declaration-assembled Catalog. The smaller benchmark
+// in internal/cli intentionally uses a four-tool fixture and must not be used
+// as the release-scale latency or allocation number.
+func BenchmarkToolSearchDeliveryChineseQuery(b *testing.B) {
+	registerSchemaRuntimeDelivery()
+	engine, err := cli.NewDeliveryToolSearchEngineWithConfig(cli.DefaultToolSearchConfig())
+	if err != nil {
+		b.Fatalf("NewDeliveryToolSearchEngineWithConfig() error = %v", err)
+	}
+	request := cli.ToolSearchRequest{Query: "给群里发文件并确认消息已读", Limit: 5, CandidateLimit: 20}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for index := 0; index < b.N; index++ {
+		if _, searchErr := engine.Search(context.Background(), request); searchErr != nil {
+			b.Fatalf("Search() error = %v", searchErr)
+		}
+	}
+}
+
+func BenchmarkToolSearchDeliveryDecomposedWorkflow(b *testing.B) {
+	registerSchemaRuntimeDelivery()
+	engine, err := cli.NewDeliveryToolSearchEngineWithConfig(cli.DefaultToolSearchConfig())
+	if err != nil {
+		b.Fatalf("NewDeliveryToolSearchEngineWithConfig() error = %v", err)
+	}
+	request := cli.ToolSearchRequest{Query: "给群里发文件，并确认群成员是否已读", Limit: 5, CandidateLimit: 20}
+	subqueries := []string{"以当前用户身份给群聊发送本地文件", "查询指定消息的已读状态和人员"}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for index := 0; index < b.N; index++ {
+		if _, searchErr := engine.SearchSubqueries(context.Background(), subqueries, request); searchErr != nil {
+			b.Fatalf("SearchSubqueries() error = %v", searchErr)
+		}
+	}
+}
+
+func BenchmarkToolSearchDeliveryIndexBuild(b *testing.B) {
+	registerSchemaRuntimeDelivery()
+	config := cli.DefaultToolSearchConfig()
+	// Prime and cache declaration assembly so this benchmark isolates building
+	// the Tool Search projection/index. Cold process startup is measured at the
+	// release-binary boundary and reported separately.
+	if _, err := cli.NewDeliveryToolSearchEngineWithConfig(config); err != nil {
+		b.Fatalf("prime delivery Catalog: %v", err)
+	}
+	b.ReportAllocs()
+	b.ResetTimer()
+	for index := 0; index < b.N; index++ {
+		if _, err := cli.NewDeliveryToolSearchEngineWithConfig(config); err != nil {
+			b.Fatalf("NewDeliveryToolSearchEngineWithConfig() error = %v", err)
+		}
+	}
+}
@@ -113,10 +113,9 @@ const (
 	ClientIDPath            = "/cli/clientId"

 	// MCP OAuth endpoints (used when clientId is fetched from MCP).
-	MCPOAuthTokenPath     = "/oauth2/getToken"
-	MCPRefreshTokenPath   = "/oauth2/refreshToken"
-	MCPRevokeTokenPath    = "/oauth2/revokeToken"
-	MCPVendorAuthCodePath = "/oauth2/vendorAuthCode"
+	MCPOAuthTokenPath   = "/oauth2/getToken"
+	MCPRefreshTokenPath = "/oauth2/refreshToken"
+	MCPRevokeTokenPath  = "/oauth2/revokeToken"

 	// App-level access token endpoints (for dws api raw calls).

@@ -1,192 +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 auth
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
-)
-
-const (
-	headerUserAccessToken = "x-user-access-token"
-	headerDWSClientID     = "x-dws-client-id"
-	headerDWSCLIVersion   = "x-dws-cli-version"
-
-	// VendorAuthCode default / documented portal expiresIn, used only when
-	// the success body omits a positive value. Callers must still prefer
-	// the response field.
-	DefaultVendorAuthCodeExpiresIn = 120
-
-	VendorAuthCodeParamError        = "PARAM_ERROR"
-	VendorAuthCodeVendorUnsupported = "VENDOR_UNSUPPORTED"
-	VendorAuthCodeTokenInvalid      = "TOKEN_INVALID"
-	VendorAuthCodeOrgMismatch       = "ORG_MISMATCH"
-	VendorAuthCodeUserNotInOrg      = "USER_NOT_IN_ORG"
-	VendorAuthCodeVendorNotEnabled  = "VENDOR_NOT_ENABLED"
-	VendorAuthCodeRateLimited       = "RATE_LIMITED"
-	VendorAuthCodeInternalError     = "INTERNAL_ERROR"
-)
-
-// VendorAuthCodeInput is a POST /oauth2/vendorAuthCode call. The body is
-// only vendor + corpId; redirectURI and domain must not be sent.
-type VendorAuthCodeInput struct {
-	AccessToken string
-	ClientID    string
-	CLIVersion  string
-	LoginRegion LoginRegion
-	Vendor      string
-	CorpID      string
-	HTTPClient  *http.Client
-	// BaseURL overrides MCPBaseURLForLoginRegion. Tests use it; production
-	// callers leave it empty.
-	BaseURL string
-}
-
-// VendorAuthCodeResult is the success VO from portal.
-type VendorAuthCodeResult struct {
-	AuthCode  string
-	ExpiresIn int
-}
-
-// VendorAuthCodeError is a portal business error carried in an HTTP 200
-// ServiceResult body (same envelope as /oauth2/getToken).
-type VendorAuthCodeError struct {
-	Code    string
-	Message string
-}
-
-func (e *VendorAuthCodeError) Error() string {
-	if e == nil {
-		return "vendorAuthCode failed"
-	}
-	if strings.TrimSpace(e.Message) != "" {
-		return fmt.Sprintf("vendorAuthCode %s: %s", e.Code, e.Message)
-	}
-	return fmt.Sprintf("vendorAuthCode %s", e.Code)
-}
-
-// Retryable reports whether DWS should retry this portal error once.
-func (e *VendorAuthCodeError) Retryable() bool {
-	if e == nil {
-		return false
-	}
-	switch e.Code {
-	case VendorAuthCodeTokenInvalid, VendorAuthCodeRateLimited, VendorAuthCodeInternalError:
-		return true
-	default:
-		return false
-	}
-}
-
-// FetchVendorAuthCode POSTs {vendor, corpId} to /oauth2/vendorAuthCode.
-// HTTP is expected to be 200; errors are read from body.errorCode.
-func FetchVendorAuthCode(ctx context.Context, in VendorAuthCodeInput) (*VendorAuthCodeResult, error) {
-	vendor := strings.ToLower(strings.TrimSpace(in.Vendor))
-	corpID := strings.TrimSpace(in.CorpID)
-	token := strings.TrimSpace(in.AccessToken)
-	clientID := strings.TrimSpace(in.ClientID)
-	if token == "" || clientID == "" || vendor == "" || corpID == "" {
-		return nil, &VendorAuthCodeError{
-			Code:    VendorAuthCodeParamError,
-			Message: "token, clientId, vendor and corpId are required",
-		}
-	}
-
-	base := strings.TrimRight(strings.TrimSpace(in.BaseURL), "/")
-	if base == "" {
-		base = strings.TrimRight(MCPBaseURLForLoginRegion(in.LoginRegion), "/")
-	}
-	endpoint := base + MCPVendorAuthCodePath
-
-	payload, err := json.Marshal(struct {
-		Vendor string `json:"vendor"`
-		CorpID string `json:"corpId"`
-	}{Vendor: vendor, CorpID: corpID})
-	if err != nil {
-		return nil, fmt.Errorf("marshaling vendorAuthCode request: %w", err)
-	}
-
-	req, err := oauthNewRequest(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
-	if err != nil {
-		return nil, fmt.Errorf("creating vendorAuthCode request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set(headerUserAccessToken, token)
-	req.Header.Set(headerDWSClientID, clientID)
-	if ver := strings.TrimSpace(in.CLIVersion); ver != "" {
-		req.Header.Set(headerDWSCLIVersion, ver)
-	}
-	applyEditionEnterpriseCredentialHeaders(req)
-
-	client := in.HTTPClient
-	if client == nil {
-		client = oauthHTTPClient
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("sending vendorAuthCode request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	data, readErr := io.ReadAll(io.LimitReader(resp.Body, config.MaxResponseBodySize))
-	if resp.StatusCode != http.StatusOK {
-		if readErr != nil {
-			data = nil
-		}
-		return nil, &HTTPStatusError{
-			StatusCode:   resp.StatusCode,
-			responseBody: truncateBody(data, 200),
-		}
-	}
-	if readErr != nil {
-		return nil, fmt.Errorf("reading vendorAuthCode response: %w", readErr)
-	}
-	return parseVendorAuthCodeResponse(data)
-}
-
-func parseVendorAuthCodeResponse(body []byte) (*VendorAuthCodeResult, error) {
-	var resp struct {
-		AuthCode  string `json:"authCode"`
-		ExpiresIn int    `json:"expiresIn"`
-		Success   *bool  `json:"success"`
-		ErrorCode string `json:"errorCode"`
-		ErrorMsg  string `json:"errorMsg"`
-	}
-	if err := json.Unmarshal(body, &resp); err != nil {
-		return nil, fmt.Errorf("parsing vendorAuthCode response: %w", err)
-	}
-	if resp.ErrorCode != "" || resp.ErrorMsg != "" || (resp.Success != nil && !*resp.Success) {
-		code := strings.TrimSpace(resp.ErrorCode)
-		if code == "" {
-			code = VendorAuthCodeInternalError
-		}
-		return nil, &VendorAuthCodeError{Code: code, Message: resp.ErrorMsg}
-	}
-	authCode := strings.TrimSpace(resp.AuthCode)
-	if authCode == "" {
-		return nil, fmt.Errorf("vendorAuthCode response missing authCode")
-	}
-	expiresIn := resp.ExpiresIn
-	if expiresIn <= 0 {
-		expiresIn = DefaultVendorAuthCodeExpiresIn
-	}
-	return &VendorAuthCodeResult{AuthCode: authCode, ExpiresIn: expiresIn}, nil
-}
@@ -1,178 +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 auth
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-)
-
-func TestFetchVendorAuthCodeSuccessEnvelope(t *testing.T) {
-	var gotBody map[string]string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != MCPVendorAuthCodePath {
-			t.Fatalf("path = %q, want %s", r.URL.Path, MCPVendorAuthCodePath)
-		}
-		if r.Method != http.MethodPost {
-			t.Fatalf("method = %s, want POST", r.Method)
-		}
-		if got := r.Header.Get("x-user-access-token"); got != "user-token" {
-			t.Fatalf("x-user-access-token = %q", got)
-		}
-		if got := r.Header.Get("x-dws-client-id"); got != "dws-client" {
-			t.Fatalf("x-dws-client-id = %q", got)
-		}
-		if got := r.Header.Get("x-dws-cli-version"); got != "1.2.3" {
-			t.Fatalf("x-dws-cli-version = %q", got)
-		}
-		if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
-			t.Fatalf("decode body: %v", err)
-		}
-		w.Header().Set("Cache-Control", "no-store")
-		_, _ = io.WriteString(w, `{"authCode":"tmp-code","expiresIn":120}`)
-	}))
-	defer srv.Close()
-
-	got, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		CLIVersion:  "1.2.3",
-		Vendor:      "SafeChat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	if err != nil {
-		t.Fatalf("FetchVendorAuthCode() = %v", err)
-	}
-	if got.AuthCode != "tmp-code" || got.ExpiresIn != 120 {
-		t.Fatalf("result = %+v", got)
-	}
-	if gotBody["vendor"] != "safechat" || gotBody["corpId"] != "dingxxxxxxxxxxxx" {
-		t.Fatalf("posted body = %v", gotBody)
-	}
-	if _, ok := gotBody["redirectURI"]; ok {
-		t.Fatalf("posted redirectURI, body = %v", gotBody)
-	}
-	if _, ok := gotBody["domain"]; ok {
-		t.Fatalf("posted domain, body = %v", gotBody)
-	}
-}
-
-func TestFetchVendorAuthCodeParsesAlways200ServiceResult(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		_, _ = io.WriteString(w, `{"success":false,"errorCode":"VENDOR_NOT_ENABLED","errorMsg":"not installed"}`)
-	}))
-	defer srv.Close()
-
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	var verr *VendorAuthCodeError
-	if !errors.As(err, &verr) || verr.Code != VendorAuthCodeVendorNotEnabled {
-		t.Fatalf("error = %v, want VENDOR_NOT_ENABLED", err)
-	}
-	if verr.Retryable() {
-		t.Fatal("VENDOR_NOT_ENABLED must not be retryable")
-	}
-}
-
-func TestFetchVendorAuthCodeRequiresLocalFields(t *testing.T) {
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{Vendor: "safechat", CorpID: "ding"})
-	var verr *VendorAuthCodeError
-	if !errors.As(err, &verr) || verr.Code != VendorAuthCodeParamError {
-		t.Fatalf("error = %v, want PARAM_ERROR", err)
-	}
-}
-
-func TestFetchVendorAuthCodeKeepsHTTPStatusOnNon200(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Error(w, "oops", http.StatusBadGateway)
-	}))
-	defer srv.Close()
-
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	var statusErr *HTTPStatusError
-	if !errors.As(err, &statusErr) || statusErr.StatusCode != http.StatusBadGateway {
-		t.Fatalf("error = %v, want HTTP 502", err)
-	}
-}
-
-func TestParseVendorAuthCodeResponseDefaultsExpiresIn(t *testing.T) {
-	got, err := parseVendorAuthCodeResponse([]byte(`{"authCode":"x"}`))
-	if err != nil {
-		t.Fatalf("parse: %v", err)
-	}
-	if got.ExpiresIn != DefaultVendorAuthCodeExpiresIn {
-		t.Fatalf("expiresIn = %d, want %d", got.ExpiresIn, DefaultVendorAuthCodeExpiresIn)
-	}
-}
-
-func TestVendorAuthCodeErrorRetryable(t *testing.T) {
-	for _, code := range []string{VendorAuthCodeTokenInvalid, VendorAuthCodeRateLimited, VendorAuthCodeInternalError} {
-		if !(&VendorAuthCodeError{Code: code}).Retryable() {
-			t.Fatalf("%s should be retryable", code)
-		}
-	}
-	if (&VendorAuthCodeError{Code: VendorAuthCodeOrgMismatch}).Retryable() {
-		t.Fatal("ORG_MISMATCH must not be retryable")
-	}
-}
-
-func TestFetchVendorAuthCodeDoesNotSendBlankCLIVersionHeader(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if got := r.Header.Get("x-dws-cli-version"); got != "" {
-			t.Fatalf("x-dws-cli-version = %q, want empty", got)
-		}
-		_, _ = io.WriteString(w, `{"authCode":"tmp-code","expiresIn":90}`)
-	}))
-	defer srv.Close()
-
-	got, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	if err != nil {
-		t.Fatalf("FetchVendorAuthCode() = %v", err)
-	}
-	if got.ExpiresIn != 90 {
-		t.Fatalf("expiresIn = %d, want 90 from response", got.ExpiresIn)
-	}
-	if strings.Contains(got.AuthCode, "redirect") {
-		t.Fatalf("unexpected code %q", got.AuthCode)
-	}
-}
@@ -23,6 +23,15 @@ import (
 	"github.com/spf13/cobra"
 )

+// SchemaInspectV1Response is the versioned Search -> Inspect wire contract.
+// Legacy schema queries without expected hashes keep their historical flat
+// payload for human and script compatibility.
+type SchemaInspectV1Response struct {
+	Version  string            `json:"version"`
+	Catalog  CatalogVersionRef `json:"catalog"`
+	ToolSpec map[string]any    `json:"tool_spec"`
+}
+
 // schemaCommandCatalogError / payloads use deliverySchemaCatalog
 // (RegisterSchemaSourceRoot → ResolveSchemaBuild). There is no committed
 // Schema Catalog embed fallback.
@@ -71,12 +80,20 @@ func NewSchemaCommand() *cobra.Command {
 		Short: "渐进查看命令 Schema (产品 / 分组 / 工具参数)",
 		Long: `查看当前可运行命令的 Schema 元数据。

-不带参数时列出产品和工具数量；传产品或分组路径逐层展开；传具体工具路径输出扁平参数 Schema（对齐 GWS：parameters 内联 required，键为 CLI flag）。普通 Agent 查询应使用 --compact：它按稳定字段白名单输出选参、约束、安全语义和已评审的返回契约。省略 --compact 的 full leaf 保留参数映射、接口绑定和 provenance，仅用于定向审计；--all 输出全部工具的完整 leaf Schema，用于审计/CI。helper、MCP 与本地 Cobra 命令均须通过 ContractFinal.Identity 声明进入收集的身份集，并从同一声明装配的 ToolSpec 投影；查询不执行服务发现或临时合成第二份 Schema。`,
-		Args:              cobra.MaximumNArgs(1),
+不带参数时列出产品和工具数量；传产品或分组路径逐层展开；传具体工具路径输出扁平参数 Schema（对齐 GWS：parameters 内联 required，键为 CLI flag）。普通 Agent 查询应使用 --compact：它按稳定字段白名单输出选参、约束、安全语义和已评审的返回契约。省略 --compact 的 full leaf 保留参数映射、接口绑定和 provenance，仅用于定向审计；--all 输出全部工具的完整 leaf Schema，用于审计/CI。helper、MCP 与本地 Cobra 命令均须通过 ContractFinal.Identity 声明进入收集的身份集，并从同一声明装配的 ToolSpec 投影；查询不执行服务发现或临时合成第二份 Schema。
+
+路径形态：多个位置参数会按空格拼接并作为 CLI path 解析，等价于加引号的形式和 --cli-path，例如 dws schema chat message read-status 与 dws schema "chat message read-status" 相同。canonical path 含点号，必须作为单个参数整体传入（dws schema chat.query_msg_read_status）；把 canonical 拆成多个 token 会被当作 CLI path 而解析失败。`,
+		Args:              cobra.MaximumNArgs(16),
 		DisableAutoGenTag: true,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			all, _ := cmd.Flags().GetBool("all")
 			compact, _ := cmd.Flags().GetBool("compact")
+			expectedSourceHash, _ := cmd.Flags().GetString("expected-source-hash")
+			expectedSurfaceHash, _ := cmd.Flags().GetString("expected-surface-hash")
+			if (expectedSourceHash == "") != (expectedSurfaceHash == "") {
+				return apperrors.NewValidation("--expected-source-hash and --expected-surface-hash must be provided together", apperrors.WithReason("incomplete_catalog_version"))
+			}
+			versionedInspect := expectedSourceHash != ""
 			cliPath, _ := cmd.Flags().GetString("cli-path")
 			cliPath = strings.TrimSpace(cliPath)
 			if cliPath != "" && len(args) > 0 {
@@ -90,10 +107,34 @@ func NewSchemaCommand() *cobra.Command {
 			}
 			if cliPath != "" {
 				args = []string{cliPath}
+			} else if len(args) > 1 {
+				// Preserve the quoted path form while accepting the equivalent
+				// natural tokenized form: dws schema chat message.
+				args = []string{strings.Join(args, " ")}
+			}
+			if versionedInspect {
+				if all || len(args) == 0 || !compact {
+					return apperrors.NewValidation("versioned Schema inspect requires one tool path and --compact", apperrors.WithReason("invalid_inspect_request"))
+				}
+				for _, name := range []string{"fields", "jq"} {
+					if flag := cmd.Flag(name); flag != nil && flag.Changed {
+						return apperrors.NewValidation("schema-inspect.v1 does not support --"+name, apperrors.WithReason("unsupported_output_filter"))
+					}
+				}
+				if flag := cmd.Flag("format"); flag != nil && flag.Changed && strings.TrimSpace(flag.Value.String()) != "json" {
+					return apperrors.NewValidation("schema-inspect.v1 only supports --format json", apperrors.WithReason("unsupported_output_format"))
+				}
 			}
 			if err := schemaCommandCatalogError(); err != nil {
 				return fmt.Errorf("load typed Schema registry: %w", err)
 			}
+			loaded := deliverySchemaCatalog()
+			if expectedSourceHash != "" && expectedSourceHash != loaded.Snapshot.SourceHash {
+				return apperrors.NewDiscovery("Catalog changed before Schema inspect", apperrors.WithReason("catalog_changed"))
+			}
+			if expectedSurfaceHash != "" && expectedSurfaceHash != loaded.Snapshot.SurfaceHash {
+				return apperrors.NewDiscovery("Catalog surface changed before Schema inspect", apperrors.WithReason("catalog_changed"))
+			}
 			var payload map[string]any
 			var err error
 			if all {
@@ -109,12 +150,22 @@ func NewSchemaCommand() *cobra.Command {
 			if compact {
 				payload = stripSchemaPayloadCompact(payload)
 			}
+			if versionedInspect {
+				return output.WriteFiltered(cmd.OutOrStdout(), output.FormatJSON, SchemaInspectV1Response{
+					Version:  "schema-inspect.v1",
+					Catalog:  CatalogVersionRef{SourceHash: loaded.Snapshot.SourceHash, SurfaceHash: loaded.Snapshot.SurfaceHash},
+					ToolSpec: payload,
+				}, "", "")
+			}
 			return output.WriteFiltered(cmd.OutOrStdout(), output.ResolveFormat(cmd, output.FormatJSON), payload, output.ResolveFields(cmd), output.ResolveJQ(cmd))
 		},
 	}
 	cmd.Flags().Bool("all", false, "输出全部工具的完整 leaf Schema（包括参数和约束，用于审计/CI）")
 	cmd.Flags().Bool("compact", false, "按稳定字段白名单输出 Agent 选参、约束、安全语义和返回契约")
 	cmd.Flags().String("cli-path", "", "按 CLI 命令路径查询")
+	cmd.Flags().String("expected-source-hash", "", "要求 Inspect 使用指定 Catalog source hash")
+	cmd.Flags().String("expected-surface-hash", "", "要求 Inspect 使用指定 Catalog surface hash")
+	cmd.AddCommand(newSchemaSearchCommand())
 	return cmd
 }

@@ -35,6 +35,12 @@ func resetSchemaSourceRootAtomicForTest() {
 	schemaSourceRoot = atomic.Value{}
 }

+// resetDeliveryToolSearchEngineStateForTest drops the memoized default Tool
+// Search engine so a test can rebuild it against a freshly installed Catalog.
+func resetDeliveryToolSearchEngineStateForTest() {
+	resetDeliveryToolSearchEngineState()
+}
+
 // clearDeclaredDryRunCapabilitiesForTest resets the declared index (tests only).
 func clearDeclaredDryRunCapabilitiesForTest() {
 	declaredDryRunCapabilities.Range(func(key, _ any) bool {
@@ -1,242 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package cli
-
-import "testing"
-
-func TestPrimaryParamMigrationKeepsConceptDirectionCommandScoped(t *testing.T) {
-	concepts, err := LoadParamConcepts()
-	if err != nil {
-		t.Fatalf("LoadParamConcepts() error = %v", err)
-	}
-	if got := concepts.ByConcept["content_text"].CanonicalHint; got != "text" {
-		t.Fatalf("content_text canonical hint = %q, want unchanged global hint text", got)
-	}
-	if got := concepts.ByConcept["open_conversation_id"].CanonicalHint; got != "conversation-id" {
-		t.Fatalf("open_conversation_id canonical hint = %q, want unchanged global hint conversation-id", got)
-	}
-
-	content := concepts.ByConcept["content_text"]
-	docNode := concepts.ByConcept["doc_node_id"]
-	docAppend, problems := reduceLeafParamAliases(
-		"doc +doc-append",
-		realMap(
-			realFlag{name: "content"},
-			realFlag{name: "text", hidden: true},
-			realFlag{name: "doc"},
-		),
-		[]Concept{content, docNode},
-		CommandOverride{},
-	)
-	if len(problems) != 0 {
-		t.Fatalf("doc +doc-append reduction problems = %v", problems)
-	}
-	assertPrimaryParamAlias(t, docAppend, "body", "content")
-	assertPrimaryParamAlias(t, docAppend, "node", "doc")
-
-	insertOverride := primaryParamOverride(t, concepts, "doc block insert")
-	docInsert, problems := reduceLeafParamAliases(
-		"doc block insert",
-		realMap(
-			realFlag{name: "content"},
-			realFlag{name: "text", hidden: true},
-			realFlag{name: "parent-block"},
-			realFlag{name: "ref-block"},
-		),
-		[]Concept{content},
-		insertOverride,
-	)
-	if len(problems) != 0 {
-		t.Fatalf("doc block insert reduction problems = %v", problems)
-	}
-	assertPrimaryParamAlias(t, docInsert, "body", "content")
-
-	docUpdate, problems := reduceLeafParamAliases(
-		"doc block update",
-		realMap(realFlag{name: "content"}, realFlag{name: "text", hidden: true}),
-		[]Concept{content},
-		CommandOverride{},
-	)
-	if len(problems) != 0 {
-		t.Fatalf("doc block update reduction problems = %v", problems)
-	}
-	assertPrimaryParamAlias(t, docUpdate, "body", "content")
-
-	replyOverride := primaryParamOverride(t, concepts, "chat +messages-reply")
-	chatReply, problems := reduceLeafParamAliases(
-		"chat +messages-reply",
-		realMap(
-			realFlag{name: "group"},
-			realFlag{name: "conversation-id", hidden: true},
-			realFlag{name: "ref-msg-id"},
-		),
-		[]Concept{concepts.ByConcept["open_conversation_id"]},
-		replyOverride,
-	)
-	if len(problems) != 0 {
-		t.Fatalf("chat +messages-reply reduction problems = %v", problems)
-	}
-	for _, emitted := range []string{"chat", "chat-id", "open-conversation-id"} {
-		assertPrimaryParamAlias(t, chatReply, emitted, "group")
-	}
-	assertPrimaryParamAlias(t, chatReply, "msg-id", "ref-msg-id")
-	if chatReply.IsBlocked("group") {
-		t.Fatal("chat +messages-reply canonical --group must not remain blocked")
-	}
-}
-
-func TestPrimaryParamMigrationUpdatesReviewedFixturesAndMappingKeys(t *testing.T) {
-	concepts, err := LoadParamConcepts()
-	if err != nil {
-		t.Fatalf("LoadParamConcepts() error = %v", err)
-	}
-	fixtures := []ParamFixtureCase{
-		{Command: "doc +doc-append", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias"},
-		{Command: "doc +doc-append", Emitted: "node", Expect: "doc", Via: "concept:doc_node_id"},
-		{Command: "doc block insert", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 2},
-		{Command: "doc block update", Emitted: "text", Expect: "content", Via: "native:reviewed-compatibility-alias", Occ: 6},
-		{Command: "chat message send", Emitted: "file-path", Expect: "file", Via: "native:reviewed-compatibility-alias"},
-		{Command: "chat +messages-reply", Emitted: "conversation-id", Expect: "group", Via: "native:reviewed-compatibility-alias"},
-		{Command: "chat +messages-reply", Emitted: "chat", Expect: "group", Via: "concept:open_conversation_id"},
-		{Command: "chat +messages-reply", Emitted: "open-conversation-id", Expect: "group", Via: "concept:open_conversation_id"},
-	}
-	for _, want := range fixtures {
-		found := false
-		for _, got := range concepts.Fixture {
-			if got == want {
-				found = true
-				break
-			}
-		}
-		if !found {
-			t.Errorf("reviewed fixture missing %#v", want)
-		}
-	}
-
-	tests := []struct {
-		oldKey string
-		newKey string
-		reason string
-	}{
-		{"chat.reply_personal_message --text", "chat.reply_personal_message --content", "serialized into the aggregate content JSON string"},
-		{"chat.send_personal_message --file-path", "chat.send_personal_message --file", "local upload/preprocessing input"},
-		{"chat.send_personal_message --text", "chat.send_personal_message --content", "serialized into the aggregate content payload"},
-		{"doc.insert_document_block --text", "doc.insert_document_block --content", "aggregate convenience input used to build element"},
-		{"doc.update_document_block --text", "doc.update_document_block --content", "aggregate convenience input used to build element"},
-		{"todo.add_todo_attachment --file-path", "todo.add_todo_attachment --file", "local upload input used to construct attachmentList"},
-	}
-	for _, test := range tests {
-		if _, exists := reviewedSchemaParameterMappingExclusions[test.oldKey]; exists {
-			t.Errorf("stale mapping exclusion remains at %q", test.oldKey)
-		}
-		if got := reviewedSchemaParameterMappingExclusions[test.newKey]; got != test.reason {
-			t.Errorf("mapping exclusion %q reason = %q, want %q", test.newKey, got, test.reason)
-		}
-	}
-}
-
-func TestPrimaryParamMigrationPreservesDeliverySchemaSignatures(t *testing.T) {
-	tests := []struct {
-		path             string
-		primary          string
-		legacy           string
-		required         bool
-		cliRequired      bool
-		property         string
-		propertyFrom     string
-		format           string
-		requiredWhen     string
-		requiredWhenFrom string
-	}{
-		{path: "aisearch person", primary: "query", legacy: "keyword", required: true, property: "keyword", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat message reply", primary: "content", legacy: "text", required: true, cliRequired: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
-		{path: "chat message send", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
-		{path: "chat message send", primary: "file", legacy: "file-path", propertyFrom: "reviewed_mapping_exclusion", format: "file-path", requiredWhen: "msg-type is file or audio or video", requiredWhenFrom: "typed_parameter_metadata"},
-		{path: "chat message send-by-webhook", primary: "content", legacy: "text", required: true, cliRequired: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +broadcast", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +dm", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +send-to-group", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +messages-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +messages-batch-send-by-bot", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +messages-send-by-webhook", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +messages-reply", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "chat +messages-reply", primary: "group", legacy: "conversation-id", required: true, property: "conversationId", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "doc +doc-append", primary: "content", legacy: "text", required: true, property: "text", propertyFrom: "native_annotation", requiredWhenFrom: "default"},
-		{path: "doc block insert", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
-		{path: "doc block update", primary: "content", legacy: "text", propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
-		{path: "todo task add-attachment", primary: "file", legacy: "file-path", required: true, propertyFrom: "reviewed_mapping_exclusion", requiredWhenFrom: "default"},
-	}
-	for _, test := range tests {
-		t.Run(test.path+"/"+test.primary, func(t *testing.T) {
-			leaf, err := queryDeliverySchemaPayload([]string{test.path})
-			if err != nil {
-				t.Fatal(err)
-			}
-			parameters := schemaMap(leaf["parameters"])
-			parameter, exists := parameters[test.primary]
-			if !exists {
-				t.Fatalf("%s missing visible Primary --%s", test.path, test.primary)
-			}
-			if _, exists := parameters[test.legacy]; exists {
-				t.Fatalf("%s unexpectedly publishes hidden legacy --%s", test.path, test.legacy)
-			}
-			if got := parameter["type"]; got != "string" {
-				t.Errorf("%s --%s type = %#v, want string", test.path, test.primary, got)
-			}
-			if got := parameter["required"]; got != test.required {
-				t.Errorf("%s --%s required = %#v, want %v", test.path, test.primary, got, test.required)
-			}
-			if got, _ := parameter["cli_required"].(bool); got != test.cliRequired {
-				t.Errorf("%s --%s cli_required = %#v, want %v", test.path, test.primary, parameter["cli_required"], test.cliRequired)
-			}
-			if got, _ := parameter["property"].(string); got != test.property {
-				t.Errorf("%s --%s property = %q, want %q", test.path, test.primary, got, test.property)
-			}
-			if got := parameter["interface_type"]; got != nil && got != "" {
-				t.Errorf("%s --%s interface_type = %#v, want omitted/empty", test.path, test.primary, got)
-			}
-			if got, _ := parameter["format"].(string); got != test.format {
-				t.Errorf("%s --%s format = %q, want %q", test.path, test.primary, got, test.format)
-			}
-			if got, _ := parameter["required_when"].(string); got != test.requiredWhen {
-				t.Errorf("%s --%s required_when = %q, want %q", test.path, test.primary, got, test.requiredWhen)
-			}
-
-			provenance := schemaMap(parameter["field_provenance"])
-			propertyProvenance := provenance["property"]
-			if got := propertyProvenance["source"]; got != test.propertyFrom {
-				t.Errorf("%s --%s property source = %#v, want %s", test.path, test.primary, got, test.propertyFrom)
-			}
-			typeProvenance := provenance["type"]
-			if got := typeProvenance["source"]; got != "cobra_flag_type" {
-				t.Errorf("%s --%s type source = %#v, want cobra_flag_type", test.path, test.primary, got)
-			}
-			requiredWhenProvenance := provenance["required_when"]
-			if got := requiredWhenProvenance["source"]; got != test.requiredWhenFrom {
-				t.Errorf("%s --%s required_when source = %#v, want %s", test.path, test.primary, got, test.requiredWhenFrom)
-			}
-		})
-	}
-}
-
-func primaryParamOverride(t *testing.T, concepts ParamConcepts, path string) CommandOverride {
-	t.Helper()
-	for _, override := range concepts.Overrides {
-		if override.CommandPath == path {
-			return override
-		}
-	}
-	t.Fatalf("command override %q not found", path)
-	return CommandOverride{}
-}
-
-func assertPrimaryParamAlias(t *testing.T, entry *ParamAliasEntry, emitted, want string) {
-	t.Helper()
-	if entry == nil {
-		t.Fatalf("alias entry is nil; want %s -> %s", emitted, want)
-	}
-	if got, ok := entry.ResolveAlias(emitted); !ok || got != want {
-		t.Fatalf("ResolveAlias(%q) = %q (ok=%v), want %q", emitted, got, ok, want)
-	}
-}
@@ -325,7 +325,10 @@ func schemaPayloadFromLoadedCatalog(loaded loadedSchemaCatalog, args []string) (
 			}
 		}
 	}
-	return nil, apperrors.NewValidation("unknown runtime schema path " + strconvQuote(raw))
+	// The message carries the path-form boundary because it is the one surface
+	// an Agent is guaranteed to see at failure time.
+	return nil, apperrors.NewValidation("unknown runtime schema path " + strconvQuote(raw) +
+		": canonical paths contain dots and must be a single argument (e.g. dws schema chat.query_msg_read_status), while space-separated tokens resolve as a CLI path")
 }

 func schemaCatalogSnapshotHash(snapshot SchemaCatalogSnapshot) string {
@@ -51,7 +51,7 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{
 			"profile list",
 			"profile switch",
 			"profile use",
-			"schema",
+			"schema search",
 			"skill get",
 			"skill install",
 			"skill search",
@@ -68,9 +68,9 @@ func init() {
 	registerRequireOneOf("devdoc.search_open_platform_docs_rag", "query", "keyword")
 	registerRequireOneOf("event.consume", "event_key", "subscribe-id")
 	registerExclusiveOneOf("event.stop", "all", "subscribe_id")
-	registerRequireOneOf("doc.insert_document_block", "content", "heading", "element")
+	registerRequireOneOf("doc.insert_document_block", "text", "heading", "element")
 	registerExclusiveOneOf("doc.update_document", "content", "content-file")
-	registerRequireOneOf("doc.update_document_block", "content", "heading", "element")
+	registerRequireOneOf("doc.update_document_block", "text", "heading", "element")
 	registerRequireOneOf("pat.batch_grant", "scope", "product", "products", "domain", "domains", "recommend")
 	registerRequireOneOf("mail.search_mail_users", "keyword", "employee-no")
 	// --body is a hidden compatibility alias for the public --content flag.
@@ -269,20 +269,20 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"chat.update_text_emotion --conversation-id":                         "Reviewed unpinned adapter: chat.update_text_emotion has no singular pinned interface_ref; --conversation-id is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.reply_personal_message --ref-msg-id":                           "serialized into the aggregate content JSON string",
 	"chat.reply_personal_message --ref-sender":                           "resolved then serialized into the aggregate content JSON string",
-	"chat.reply_personal_message --content":                              "serialized into the aggregate content JSON string",
+	"chat.reply_personal_message --text":                                 "serialized into the aggregate content JSON string",
 	"chat.search_groups --cursor":                                        "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_groups --exclude-muted":                                 "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --exclude-muted is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_groups --limit":                                         "Reviewed unpinned adapter: chat.search_groups has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.",
 	"chat.search_messages --user":                                        "conditional wrapper: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.search_messages --users":                                       "conditional wrapper/alias of --user: parseCSVValues + appendChatIDArgs routes each supplied identifier to senderUserIds or senderOpenDingTakIds according to its runtime ID shape; there is no single RPC property for this flag",
 	"chat.send_personal_message --contact-id":                            "serialized into the aggregate content payload",
-	"chat.send_personal_message --file":                                  "local upload/preprocessing input",
+	"chat.send_personal_message --file-path":                             "local upload/preprocessing input",
 	"chat.send_personal_message --latitude":                              "serialized into the aggregate content payload",
 	"chat.send_personal_message --location-name":                         "serialized into the aggregate content payload",
 	"chat.send_personal_message --longitude":                             "serialized into the aggregate content payload",
 	"chat.send_personal_message --map-thumbnail-url":                     "serialized into the aggregate content payload",
 	"chat.send_personal_message --media-id":                              "serialized into the aggregate content payload",
-	"chat.send_personal_message --content":                               "serialized into the aggregate content payload",
+	"chat.send_personal_message --text":                                  "serialized into the aggregate content payload",
 	"chat.send_personal_message --title":                                 "serialized into the aggregate content payload",
 	"chat.send_personal_message --user":                                  "resolves a userId to receiverOpenDingTalkId when possible and otherwise uses the unpinned receiverUserId compatibility property",
 	"chat.set_group_member_mute_list --user":                             "conditional wrapper/alias of --users: userIds are remotely resolved to openDingTalkIds outside dry-run and otherwise may be sent as uids; openDingTalkId inputs are sent as openDingTalkIds, so one exact property would misdescribe execution",
@@ -406,7 +406,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"doc.insert_document_block --fix-jsonml":                             "local JSONML normalization control",
 	"doc.insert_document_block --heading":                                "aggregate convenience input used to build element",
 	"doc.insert_document_block --level":                                  "aggregate convenience input used to build element",
-	"doc.insert_document_block --content":                                "aggregate convenience input used to build element",
+	"doc.insert_document_block --text":                                   "aggregate convenience input used to build element",
 	"doc.list_document_blocks --block-id":                                "runtime extension sends blockId, which is absent from the pinned list_document_blocks metadata",
 	"doc.reply_comment --mentioned-open-conversation-id":                 "Runtime extension sends mentionedOpenConversationIds, which is absent from the immutable pinned reply_comment metadata at its declared source revision.",
 	"doc.style_background_clear --node":                                  "Reviewed unpinned adapter: doc.style_background_clear has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
@@ -438,7 +438,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"doc.update_document_block --fix-jsonml":                             "local JSONML normalization control",
 	"doc.update_document_block --heading":                                "aggregate convenience input used to build element",
 	"doc.update_document_block --level":                                  "aggregate convenience input used to build element",
-	"doc.update_document_block --content":                                "aggregate convenience input used to build element",
+	"doc.update_document_block --text":                                   "aggregate convenience input used to build element",
 	"doc.version_list --cursor":                                          "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --cursor is a CLI wrapper input and does not publish a direct interface property.",
 	"doc.version_list --limit":                                           "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --limit is a CLI wrapper input and does not publish a direct interface property.",
 	"doc.version_list --node":                                            "Reviewed unpinned adapter: doc.version_list has no singular pinned interface_ref; --node is a CLI wrapper input and does not publish a direct interface property.",
@@ -659,7 +659,7 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"sheet.write_image --file":                                           "local upload input used to obtain resourceId/resourceUrl",
 	"sheet.write_image --mime-type":                                      "local upload metadata",
 	"sheet.write_image --name":                                           "local upload metadata",
-	"todo.add_todo_attachment --file":                                    "local upload input used to construct attachmentList",
+	"todo.add_todo_attachment --file-path":                               "local upload input used to construct attachmentList",
 	"todo.get_user_todos_in_current_org --query-all":                     "Local route selector: the default path calls get_user_todos_in_current_org, while --query-all switches to get_user_todos; it is not a property of the pinned default RPC.",
 	"todo.list_todo_attachment --task-id":                                "Reviewed unpinned adapter: --task-id is nested under todoAttachmentListRequest at runtime, while the immutable pinned MCP snapshot has no interface_ref for todo.list_todo_attachment.",
 	"wiki.create_wikiSpace --icon":                                       "runtime extension sends icon, which is absent from the pinned create_wikiSpace metadata",
@@ -77,7 +77,7 @@ func cloneRuntimeSchemaStringMap(source map[string]string) map[string]string {

 func init() {
 	RegisterRuntimeSchemaParameterMetadata("aisearch.enterprise_person_search", RuntimeSchemaParameterMetadata{
-		Required: []string{"query"},
+		Required: []string{"keyword"},
 	})
 	RegisterRuntimeSchemaParameterMetadata("aitable.export_data", RuntimeSchemaParameterMetadata{
 		RequiredWhen: map[string]string{
@@ -146,8 +146,8 @@ func init() {
 	})
 	RegisterRuntimeSchemaParameterMetadata("chat.send_personal_message", RuntimeSchemaParameterMetadata{
 		RequiredWhen: map[string]string{
-			"media-id": "msg-type is image",
-			"file":     "msg-type is file or audio or video",
+			"media-id":  "msg-type is image",
+			"file-path": "msg-type is file or audio or video",
 		},
 		Examples: map[string]string{"media-id": "@lADP_schema_smoke"},
 	})
@@ -0,0 +1,203 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/spf13/cobra"
+)
+
+// ToolSearchV1Request is the stable stdin transport used by Agent hosts.
+type ToolSearchV1Request struct {
+	Version          string   `json:"version"`
+	Query            string   `json:"query"`
+	Subqueries       []string `json:"subqueries,omitempty"`
+	Limit            int      `json:"limit,omitempty"`
+	CandidateLimit   int      `json:"candidate_limit,omitempty"`
+	ProductIDs       []string `json:"product_ids,omitempty"`
+	Effects          []string `json:"effects,omitempty"`
+	ExcludeCanonical []string `json:"exclude_canonical,omitempty"`
+}
+
+var schemaSearchNewEngine = NewDeliveryToolSearchEngineWithConfig
+
+// schemaSearchEngineConfig resolves the search config the same way
+// NewDeliveryToolSearchEngine does (defaults + DWS_TOOL_SEARCH_* env
+// overrides), then lets an explicit --explain flag win over the env value.
+func schemaSearchEngineConfig(cmd *cobra.Command) ToolSearchConfig {
+	config := ResolveToolSearchConfigFromEnv(DefaultToolSearchConfig())
+	if explain, _ := cmd.Flags().GetBool("explain"); explain {
+		config.Explain = true
+	}
+	return config
+}
+
+func newSchemaSearchCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "search",
+		Short: "按自然语言搜索可用命令 Schema",
+		Long: `按自然语言或精确身份检索 ToolReference。
+
+输出固定为完整、紧凑的 tool-search.v1 JSON envelope。为保证版本、Catalog
+绑定和响应字节预算可验证，本命令不支持 --fields、--jq 或非 JSON --format。
+
+DWS 对 Agent 是一个元工具：已知子命令直接执行，未知子命令才使用 search。
+选中候选后，必须使用 response catalog 的 source/surface hash Inspect canonical_path，
+再按 primary_cli_path 执行；Search 结果本身不授权、不执行。`,
+		Example: `  dws schema search --query "查询群消息已读状态"
+  dws schema chat.query_msg_read_status --compact --format json \
+    --expected-source-hash "<search.catalog.source_hash>" \
+    --expected-surface-hash "<search.catalog.surface_hash>"
+  printf '%s' '{"version":"tool-search.v1","query":"发群文件并确认已读","subqueries":["给群里发送文件消息","查询群消息已读状态"]}' |
+    dws schema search --request-json -`,
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			if err := validateSchemaSearchOutputFlags(cmd); err != nil {
+				return err
+			}
+			request, err := schemaSearchRequest(cmd)
+			if err != nil {
+				return err
+			}
+			engine, err := schemaSearchNewEngine(schemaSearchEngineConfig(cmd))
+			if err != nil {
+				return err
+			}
+			internal := ToolSearchRequest{
+				Query:                 request.Query,
+				Limit:                 request.Limit,
+				CandidateLimit:        request.CandidateLimit,
+				ProductIDs:            request.ProductIDs,
+				Effects:               request.Effects,
+				ExcludeCanonicalPaths: request.ExcludeCanonical,
+			}
+			var response ToolSearchResponse
+			if len(request.Subqueries) > 0 {
+				response, err = engine.SearchSubqueries(cmd.Context(), request.Subqueries, internal)
+			} else {
+				response, err = engine.Search(cmd.Context(), internal)
+			}
+			if err != nil {
+				return err
+			}
+			// The response budget is defined over this compact wire encoding. Do
+			// not run it through pretty/table formatting or post-filtering because
+			// Agent hosts require one complete versioned envelope.
+			if err := json.NewEncoder(cmd.OutOrStdout()).Encode(response); err != nil {
+				return fmt.Errorf("encode tool-search.v1 response: %w", err)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().String("query", "", "自然语言意图或 canonical/CLI path")
+	cmd.Flags().Int("limit", defaultToolSearchLimit, fmt.Sprintf("返回引用数量（1-%d；0 表示沿用默认值 %d）", maxToolSearchLimit, defaultToolSearchLimit))
+	cmd.Flags().Int("candidate-limit", defaultToolSearchCandidateLimit, fmt.Sprintf("每路召回候选数量（1-%d；0 表示沿用默认值 %d）", maxToolSearchCandidateLimit, defaultToolSearchCandidateLimit))
+	cmd.Flags().StringSlice("product", nil, "限制产品 ID，可重复或逗号分隔")
+	cmd.Flags().StringSlice("effect", nil, "限制 effect，可重复或逗号分隔")
+	cmd.Flags().StringSlice("exclude", nil, "排除 canonical path，可重复或逗号分隔")
+	cmd.Flags().String("request-json", "", `从 stdin 读取 JSON；值必须为 -；必含 version="tool-search.v1"，动作分解字段为 subqueries`)
+	cmd.Flags().Bool("explain", false, "开发诊断：输出 score_breakdown 含原始排序分（公开默认响应不含分数；仅用于离线调参，不建议线上 Agent 使用；会增大响应体积，建议配合 --limit 3）。score_breakdown.score 是未量化的原始分，排序键使用量化到 1e-9 的值，两者末位可能不同，不要用它复算候选顺序")
+	return cmd
+}
+
+func validateSchemaSearchOutputFlags(cmd *cobra.Command) error {
+	for _, name := range []string{"fields", "jq"} {
+		if flag := cmd.Flag(name); flag != nil && flag.Changed {
+			return apperrors.NewValidation(
+				"schema search returns one complete tool-search.v1 envelope and does not support --"+name,
+				apperrors.WithReason("unsupported_output_filter"),
+			)
+		}
+	}
+	if flag := cmd.Flag("format"); flag != nil && flag.Changed && strings.TrimSpace(flag.Value.String()) != "json" {
+		return apperrors.NewValidation(
+			"schema search only supports --format json",
+			apperrors.WithReason("unsupported_output_format"),
+		)
+	}
+	return nil
+}
+
+func schemaSearchRequest(cmd *cobra.Command) (ToolSearchV1Request, error) {
+	requestJSON, _ := cmd.Flags().GetString("request-json")
+	requestJSON = strings.TrimSpace(requestJSON)
+	if requestJSON != "" {
+		if requestJSON != "-" {
+			return ToolSearchV1Request{}, apperrors.NewValidation("--request-json only accepts - (stdin)", apperrors.WithReason("invalid_transport"))
+		}
+		for _, name := range []string{"query", "limit", "candidate-limit", "product", "effect", "exclude"} {
+			if cmd.Flags().Changed(name) {
+				return ToolSearchV1Request{}, apperrors.NewValidation("--request-json cannot be combined with --"+name, apperrors.WithReason("ambiguous_input"))
+			}
+		}
+		request, err := decodeToolSearchV1Request(cmd.InOrStdin())
+		if err != nil {
+			return ToolSearchV1Request{}, err
+		}
+		return validateToolSearchV1Request(request)
+	}
+	query, _ := cmd.Flags().GetString("query")
+	limit, _ := cmd.Flags().GetInt("limit")
+	candidateLimit, _ := cmd.Flags().GetInt("candidate-limit")
+	products, _ := cmd.Flags().GetStringSlice("product")
+	effects, _ := cmd.Flags().GetStringSlice("effect")
+	excluded, _ := cmd.Flags().GetStringSlice("exclude")
+	return validateToolSearchV1Request(ToolSearchV1Request{
+		Version:          "tool-search.v1",
+		Query:            query,
+		Limit:            limit,
+		CandidateLimit:   candidateLimit,
+		ProductIDs:       products,
+		Effects:          effects,
+		ExcludeCanonical: excluded,
+	})
+}
+
+func decodeToolSearchV1Request(reader io.Reader) (ToolSearchV1Request, error) {
+	payload, err := io.ReadAll(io.LimitReader(reader, maxToolSearchRequestBytes+1))
+	if err != nil {
+		return ToolSearchV1Request{}, apperrors.NewValidation("read tool search request: "+err.Error(), apperrors.WithReason("read_request_failed"))
+	}
+	if len(payload) > maxToolSearchRequestBytes {
+		return ToolSearchV1Request{}, apperrors.NewValidation(fmt.Sprintf("tool search request exceeds %d bytes", maxToolSearchRequestBytes), apperrors.WithReason("request_too_large"))
+	}
+	decoder := json.NewDecoder(bytes.NewReader(payload))
+	decoder.DisallowUnknownFields()
+	var request ToolSearchV1Request
+	if err := decoder.Decode(&request); err != nil {
+		return ToolSearchV1Request{}, apperrors.NewValidation("decode tool-search.v1 request: "+err.Error(), apperrors.WithReason("invalid_request_json"))
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		if err == nil {
+			return ToolSearchV1Request{}, apperrors.NewValidation("tool search request must contain exactly one JSON object", apperrors.WithReason("invalid_request_json"))
+		}
+		return ToolSearchV1Request{}, apperrors.NewValidation("decode trailing tool search input: "+err.Error(), apperrors.WithReason("invalid_request_json"))
+	}
+	return request, nil
+}
+
+func validateToolSearchV1Request(request ToolSearchV1Request) (ToolSearchV1Request, error) {
+	if request.Version != "tool-search.v1" {
+		return ToolSearchV1Request{}, apperrors.NewValidation(`tool search request must include "version":"tool-search.v1"; action decomposition uses the "subqueries" array`, apperrors.WithReason("unsupported_version"))
+	}
+	return request, nil
+}
@@ -0,0 +1,95 @@
+// 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 cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/spf13/cobra"
+)
+
+func TestSchemaSearchCommandExactAndVersioned(t *testing.T) {
+	installSchemaSearchTestEngine(t)
+	root := &cobra.Command{Use: "dws"}
+	root.AddCommand(NewSchemaCommand())
+	var stdout bytes.Buffer
+	root.SetOut(&stdout)
+	root.SetArgs([]string{"schema", "search", "--query", "chat.read_status"})
+	if err := root.Execute(); err != nil {
+		t.Fatalf("schema search execute: %v", err)
+	}
+	var response ToolSearchResponse
+	if err := json.Unmarshal(stdout.Bytes(), &response); err != nil {
+		t.Fatalf("decode response: %v\n%s", err, stdout.String())
+	}
+	if response.Version != "tool-search.v1" || response.Strategy != "exact_guard" {
+		t.Fatalf("response = %#v", response)
+	}
+	if len(response.Candidates) != 1 || response.Candidates[0].CanonicalPath != "chat.read_status" {
+		t.Fatalf("candidates = %#v", response.Candidates)
+	}
+	wantCatalog := CatalogVersionRef{SourceHash: "source-test", SurfaceHash: "surface-test"}
+	if response.Catalog != wantCatalog {
+		t.Fatalf("Catalog = %#v, want %#v", response.Catalog, wantCatalog)
+	}
+	for _, removed := range []string{"external_ranking", "degraded", "degraded_reason_code", "warning_codes", "_fallback"} {
+		if strings.Contains(stdout.String(), removed) {
+			t.Fatalf("removed fallback field %q leaked into response: %s", removed, stdout.String())
+		}
+	}
+}
+
+func TestSchemaSearchRequestRejectsUnboundedOrAmbiguousInput(t *testing.T) {
+	if _, err := decodeToolSearchV1Request(strings.NewReader(`{"version":"tool-search.v1","query":"x","unknown":true}`)); validationReason(err) != "invalid_request_json" {
+		t.Fatal("unknown field was accepted")
+	}
+	if _, err := decodeToolSearchV1Request(strings.NewReader(`{"version":"tool-search.v1","query":"x","external_ranking":{}}`)); validationReason(err) != "invalid_request_json" {
+		t.Fatal("removed external_ranking field was accepted")
+	}
+	oversized := strings.NewReader(strings.Repeat("x", maxToolSearchRequestBytes+1))
+	if _, err := decodeToolSearchV1Request(oversized); validationReason(err) != "request_too_large" {
+		t.Fatal("oversized request was accepted")
+	}
+	_, err := validateToolSearchV1Request(ToolSearchV1Request{Query: "x", Subqueries: []string{"x"}})
+	if validationReason(err) != "unsupported_version" || !strings.Contains(err.Error(), `"version":"tool-search.v1"`) || !strings.Contains(err.Error(), "subqueries") {
+		t.Fatalf("missing-version guidance = %v", err)
+	}
+}
+
+func TestSchemaSearchHelpDocumentsStructuredRequest(t *testing.T) {
+	command := newSchemaSearchCommand()
+	var output bytes.Buffer
+	command.SetOut(&output)
+	command.SetArgs([]string{"--help"})
+	if err := command.Execute(); err != nil {
+		t.Fatalf("schema search help: %v", err)
+	}
+	for _, required := range []string{`"version":"tool-search.v1"`, `"subqueries"`, "--request-json -", "不支持 --fields、--jq", "非 JSON --format"} {
+		if !strings.Contains(output.String(), required) {
+			t.Fatalf("schema search help omits %q:\n%s", required, output.String())
+		}
+	}
+}
+
+func installSchemaSearchTestEngine(t *testing.T) {
+	t.Helper()
+	testseam.Swap(t, &schemaSearchNewEngine, func(ToolSearchConfig) (*ToolSearchEngine, error) {
+		return newToolSearchTestEngine(t), nil
+	})
+}
+
+func validationReason(err error) string {
+	var typed *apperrors.Error
+	if errors.As(err, &typed) && typed.Category == apperrors.CategoryValidation {
+		return typed.Reason
+	}
+	return ""
+}
@@ -63,12 +63,15 @@ func storeSchemaSourceRootFn(fn func() *cobra.Command) {
 }

 // resetDeliverySchemaCatalogState clears the lazy Catalog delivery Once/caches
-// so the next deliverySchemaCatalog() reassembles.
+// so the next deliverySchemaCatalog() reassembles. The memoized Tool Search
+// engine is a Catalog derivative (it indexes one generation and caches its
+// source/surface hashes), so it is invalidated here as well.
 func resetDeliverySchemaCatalogState() {
 	runtimeDeliverySchemaCatalogOnce = sync.Once{}
 	runtimeDeliverySchemaCatalog = loadedSchemaCatalog{}
 	runtimeDeliverySchemaCatalogErr = nil
 	runtimeDeliverySchemaCatalogLazyCount.Store(0)
+	resetDeliveryToolSearchEngineState()
 }

 // resetSchemaDeliveryState clears ResolveMeta lookup state and Catalog delivery
@@ -7,11 +7,30 @@ package cli
 import (
 	"bytes"
 	"encoding/json"
+	"strings"
 	"testing"

 	"github.com/spf13/cobra"
 )

+func TestSchemaHelpDocumentsCanonicalAndCLIPathForms(t *testing.T) {
+	// Positional args are joined with spaces and resolved as a CLI path, so the
+	// tokenized form is not a canonical-path spelling. Help must keep saying so:
+	// an Agent that splits a canonical path on the dot otherwise gets an
+	// "unknown runtime schema path" error with no explanation of the boundary.
+	long := NewSchemaCommand().Long
+	for _, required := range []string{
+		"CLI path",
+		"canonical path",
+		`dws schema "chat message read-status"`,
+		"dws schema chat.query_msg_read_status",
+	} {
+		if !strings.Contains(long, required) {
+			t.Fatalf("schema long help omits the path-form boundary %q:\n%s", required, long)
+		}
+	}
+}
+
 func TestSchemaUsesDeliveryCatalogWithoutRuntimeLoad(t *testing.T) {
 	root := &cobra.Command{Use: "dws"}
 	root.AddCommand(NewSchemaCommand())
@@ -0,0 +1,490 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"fmt"
+	"math/rand"
+	"sort"
+	"strings"
+)
+
+const (
+	ToolSearchAgentArmDirectSchema  = "direct_schema"
+	ToolSearchAgentArmSearchInspect = "search_inspect"
+)
+
+// Bootstrap resampling uses fixed seeds so a report can be re-derived from the
+// same paired runs. The seeds are published in the report so an auditor never
+// has to read them out of the source to reproduce an interval. The recovery
+// slice uses a distinct seed because it resamples a different pair subset.
+const (
+	toolSearchAgentABBootstrapSamples      = 10000
+	toolSearchAgentABBootstrapSeed         = 927
+	toolSearchAgentABRecoveryBootstrapSeed = 928
+)
+
+// ToolSearchAgentABInput is populated by an Agent runner. Every case/trial
+// must have both arms so the comparison remains paired.
+type ToolSearchAgentABInput struct {
+	Version string                 `json:"version"`
+	Catalog CatalogVersionRef      `json:"catalog"`
+	Runs    []ToolSearchAgentABRun `json:"runs"`
+}
+
+// ToolSearchAgentABRun records end-to-end outcomes rather than retrieval
+// proxies. ContextTokens must come from the selected model's tokenizer.
+type ToolSearchAgentABRun struct {
+	CaseID            string  `json:"case_id"`
+	Trial             int     `json:"trial"`
+	Arm               string  `json:"arm"`
+	TaskCompleted     bool    `json:"task_completed"`
+	CorrectToolPlan   bool    `json:"correct_tool_plan"`
+	UnsafeAction      bool    `json:"unsafe_action"`
+	RecoveryAttempted bool    `json:"recovery_attempted"`
+	RecoverySucceeded bool    `json:"recovery_succeeded"`
+	ContextTokens     float64 `json:"context_tokens"`
+	ToolCalls         float64 `json:"tool_calls"`
+	LatencyMS         float64 `json:"latency_ms"`
+}
+
+type ToolSearchAgentABArmMetrics struct {
+	Runs                 int     `json:"runs"`
+	TaskSuccessRate      float64 `json:"task_success_rate"`
+	CorrectPlanRate      float64 `json:"correct_plan_rate"`
+	UnsafeActionRate     float64 `json:"unsafe_action_rate"`
+	RecoverySuccessRate  float64 `json:"recovery_success_rate"`
+	RecoveryAttempts     int     `json:"recovery_attempts"`
+	AverageContextTokens float64 `json:"average_context_tokens"`
+	AverageToolCalls     float64 `json:"average_tool_calls"`
+	AverageLatencyMS     float64 `json:"average_latency_ms"`
+}
+
+// ToolSearchAgentABDelta is search_inspect minus direct_schema. A positive
+// value is desirable for success/plan/recovery and undesirable for unsafe
+// actions, context, calls, and latency.
+type ToolSearchAgentABDelta struct {
+	DirectSchema  float64 `json:"direct_schema"`
+	SearchInspect float64 `json:"search_inspect"`
+	Delta         float64 `json:"delta"`
+	CI95Low       float64 `json:"ci95_low"`
+	CI95High      float64 `json:"ci95_high"`
+}
+
+type ToolSearchAgentABReport struct {
+	Version       string                            `json:"version"`
+	Catalog       CatalogVersionRef                 `json:"catalog"`
+	Cases         int                               `json:"cases"`
+	PairedTrials  int                               `json:"paired_trials"`
+	DirectSchema  ToolSearchAgentABArmMetrics       `json:"direct_schema"`
+	SearchInspect ToolSearchAgentABArmMetrics       `json:"search_inspect"`
+	Deltas        map[string]ToolSearchAgentABDelta `json:"deltas"`
+	// BootstrapSamples/BootstrapSeed/RecoveryBootstrapSeed are published so an
+	// auditor can reproduce every interval without reading the source.
+	BootstrapSamples      int    `json:"bootstrap_samples"`
+	BootstrapSeed         int64  `json:"bootstrap_seed"`
+	RecoveryBootstrapSeed int64  `json:"recovery_bootstrap_seed"`
+	Method                string `json:"method"`
+}
+
+// ToolSearchAgentPlanOutput is the strict final response of a non-executing
+// Agent planning run. Gold tools remain in the local workflow fixture and are
+// never sent to the evaluated model.
+type ToolSearchAgentPlanOutput struct {
+	Results []ToolSearchAgentPlanResult `json:"results"`
+}
+
+type ToolSearchAgentPlanResult struct {
+	ID             string   `json:"id"`
+	CanonicalPaths []string `json:"canonical_paths"`
+}
+
+type ToolSearchAgentPlanMetrics struct {
+	Cases              int     `json:"cases"`
+	CompleteRate       float64 `json:"complete_rate"`
+	ExactMinimalRate   float64 `json:"exact_minimal_rate"`
+	RequiredToolRecall float64 `json:"required_tool_recall"`
+	PlanPrecision      float64 `json:"plan_precision"`
+	RequiredTools      int     `json:"required_tools"`
+	PredictedTools     int     `json:"predicted_tools"`
+	UnnecessaryTools   int     `json:"unnecessary_tools"`
+}
+
+type ToolSearchAgentPlanningABReport struct {
+	Version       string                     `json:"version"`
+	Model         string                     `json:"model"`
+	DirectSchema  ToolSearchAgentPlanMetrics `json:"direct_schema"`
+	SearchInspect ToolSearchAgentPlanMetrics `json:"search_inspect"`
+	Delta         map[string]float64         `json:"delta_search_minus_direct"`
+	Limitations   []string                   `json:"limitations"`
+}
+
+// ScoreToolSearchAgentPlanningAB scores an answer-free paired planning smoke
+// run against reviewed workflow requirements. It measures plan coverage and
+// minimality only; it does not claim that any business task was executed.
+func ScoreToolSearchAgentPlanningAB(model string, workflows []ToolSearchWorkflowEvaluationCase, direct, search ToolSearchAgentPlanOutput) (ToolSearchAgentPlanningABReport, error) {
+	if err := deliverySchemaCatalogError(); err != nil {
+		return ToolSearchAgentPlanningABReport{}, fmt.Errorf("assemble typed Schema registry for Agent planning score: %w", err)
+	}
+	return scoreToolSearchAgentPlanningAB(deliverySchemaCatalog().Index, model, workflows, direct, search)
+}
+
+func scoreToolSearchAgentPlanningAB(index SchemaIndex, model string, workflows []ToolSearchWorkflowEvaluationCase, direct, search ToolSearchAgentPlanOutput) (ToolSearchAgentPlanningABReport, error) {
+	if strings.TrimSpace(model) == "" {
+		return ToolSearchAgentPlanningABReport{}, fmt.Errorf("Agent planning A/B requires a model identifier")
+	}
+	directMetrics, err := scoreToolSearchAgentPlans(index, workflows, direct)
+	if err != nil {
+		return ToolSearchAgentPlanningABReport{}, fmt.Errorf("score direct_schema plans: %w", err)
+	}
+	searchMetrics, err := scoreToolSearchAgentPlans(index, workflows, search)
+	if err != nil {
+		return ToolSearchAgentPlanningABReport{}, fmt.Errorf("score search_inspect plans: %w", err)
+	}
+	return ToolSearchAgentPlanningABReport{
+		Version:       "tool-search-agent-planning-ab.v1",
+		Model:         strings.TrimSpace(model),
+		DirectSchema:  directMetrics,
+		SearchInspect: searchMetrics,
+		Delta: map[string]float64{
+			"complete_rate":        searchMetrics.CompleteRate - directMetrics.CompleteRate,
+			"exact_minimal_rate":   searchMetrics.ExactMinimalRate - directMetrics.ExactMinimalRate,
+			"required_tool_recall": searchMetrics.RequiredToolRecall - directMetrics.RequiredToolRecall,
+			"plan_precision":       searchMetrics.PlanPrecision - directMetrics.PlanPrecision,
+			"unnecessary_tools":    float64(searchMetrics.UnnecessaryTools - directMetrics.UnnecessaryTools),
+		},
+		Limitations: []string{
+			"one batch and one model trial per arm; no confidence interval",
+			"reviewed ten-workflow diagnostic fixture is not an independent release test",
+			"planning only: no parameters, business execution, recovery, latency, or tokenizer usage is scored",
+			"extra prerequisites can be operationally valid even when absent from the minimal reviewed gold",
+		},
+	}, nil
+}
+
+func scoreToolSearchAgentPlans(index SchemaIndex, workflows []ToolSearchWorkflowEvaluationCase, output ToolSearchAgentPlanOutput) (ToolSearchAgentPlanMetrics, error) {
+	byID := make(map[string]ToolSearchAgentPlanResult, len(output.Results))
+	for _, result := range output.Results {
+		if strings.TrimSpace(result.ID) == "" || len(result.CanonicalPaths) == 0 {
+			return ToolSearchAgentPlanMetrics{}, fmt.Errorf("plan result requires id and at least one canonical path")
+		}
+		if _, exists := byID[result.ID]; exists {
+			return ToolSearchAgentPlanMetrics{}, fmt.Errorf("duplicate plan result %q", result.ID)
+		}
+		seen := make(map[string]bool, len(result.CanonicalPaths))
+		for _, canonical := range result.CanonicalPaths {
+			if _, ok := index.Resolve(canonical); !ok {
+				return ToolSearchAgentPlanMetrics{}, fmt.Errorf("plan result %q contains unknown canonical %q", result.ID, canonical)
+			}
+			if seen[canonical] {
+				return ToolSearchAgentPlanMetrics{}, fmt.Errorf("plan result %q repeats canonical %q", result.ID, canonical)
+			}
+			seen[canonical] = true
+		}
+		byID[result.ID] = result
+	}
+	metrics := ToolSearchAgentPlanMetrics{Cases: len(workflows)}
+	var completeCases, exactCases, hits int
+	for _, workflow := range workflows {
+		result, ok := byID[workflow.ID]
+		if !ok {
+			return ToolSearchAgentPlanMetrics{}, fmt.Errorf("missing plan result %q", workflow.ID)
+		}
+		delete(byID, workflow.ID)
+		gold := stringSet(workflow.Required)
+		caseHits := 0
+		for _, canonical := range result.CanonicalPaths {
+			if gold[canonical] {
+				caseHits++
+			}
+		}
+		hits += caseHits
+		metrics.RequiredTools += len(workflow.Required)
+		metrics.PredictedTools += len(result.CanonicalPaths)
+		if caseHits == len(workflow.Required) {
+			completeCases++
+		}
+		if stringSlicesEqual(result.CanonicalPaths, workflow.Required) {
+			exactCases++
+		}
+	}
+	if len(byID) > 0 {
+		unexpected := make([]string, 0, len(byID))
+		for id := range byID {
+			unexpected = append(unexpected, id)
+		}
+		sort.Strings(unexpected)
+		return ToolSearchAgentPlanMetrics{}, fmt.Errorf("unexpected plan results: %s", strings.Join(unexpected, ", "))
+	}
+	if metrics.Cases > 0 {
+		metrics.CompleteRate = float64(completeCases) / float64(metrics.Cases)
+		metrics.ExactMinimalRate = float64(exactCases) / float64(metrics.Cases)
+	}
+	if metrics.RequiredTools > 0 {
+		metrics.RequiredToolRecall = float64(hits) / float64(metrics.RequiredTools)
+	}
+	if metrics.PredictedTools > 0 {
+		metrics.PlanPrecision = float64(hits) / float64(metrics.PredictedTools)
+	}
+	metrics.UnnecessaryTools = metrics.PredictedTools - hits
+	return metrics, nil
+}
+
+func stringSlicesEqual(left, right []string) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for index := range left {
+		if left[index] != right[index] {
+			return false
+		}
+	}
+	return true
+}
+
+type toolSearchAgentPair struct {
+	caseID string
+	direct ToolSearchAgentABRun
+	search ToolSearchAgentABRun
+}
+
+// AggregateToolSearchAgentAB validates a paired experiment and computes
+// case-cluster bootstrap confidence intervals with a fixed seed. Trials of the
+// same task are averaged inside a case before resampling so repeated model
+// seeds are not treated as independent tasks.
+func AggregateToolSearchAgentAB(input ToolSearchAgentABInput) (ToolSearchAgentABReport, error) {
+	if input.Version != "tool-search-agent-ab.v1" {
+		return ToolSearchAgentABReport{}, fmt.Errorf("unsupported Agent A/B input version %q", input.Version)
+	}
+	if strings.TrimSpace(input.Catalog.SourceHash) == "" || strings.TrimSpace(input.Catalog.SurfaceHash) == "" {
+		return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B input requires both Catalog hashes")
+	}
+	type key struct {
+		caseID string
+		trial  int
+	}
+	paired := make(map[key]*toolSearchAgentPair)
+	for _, run := range input.Runs {
+		if strings.TrimSpace(run.CaseID) == "" || run.Trial < 0 {
+			return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B run requires case_id and non-negative trial")
+		}
+		if run.ContextTokens < 0 || run.ToolCalls < 0 || run.LatencyMS < 0 {
+			return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B run %s/%d has a negative cost", run.CaseID, run.Trial)
+		}
+		if run.RecoverySucceeded && !run.RecoveryAttempted {
+			return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B run %s/%d marks recovery success without an attempt", run.CaseID, run.Trial)
+		}
+		itemKey := key{caseID: run.CaseID, trial: run.Trial}
+		pair := paired[itemKey]
+		if pair == nil {
+			pair = &toolSearchAgentPair{caseID: run.CaseID}
+			paired[itemKey] = pair
+		}
+		switch run.Arm {
+		case ToolSearchAgentArmDirectSchema:
+			if pair.direct.Arm != "" {
+				return ToolSearchAgentABReport{}, fmt.Errorf("duplicate direct_schema run for %s/%d", run.CaseID, run.Trial)
+			}
+			pair.direct = run
+		case ToolSearchAgentArmSearchInspect:
+			if pair.search.Arm != "" {
+				return ToolSearchAgentABReport{}, fmt.Errorf("duplicate search_inspect run for %s/%d", run.CaseID, run.Trial)
+			}
+			pair.search = run
+		default:
+			return ToolSearchAgentABReport{}, fmt.Errorf("unknown Agent A/B arm %q", run.Arm)
+		}
+	}
+	if len(paired) == 0 {
+		return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B input contains no runs")
+	}
+	pairs := make([]toolSearchAgentPair, 0, len(paired))
+	caseSet := make(map[string]bool)
+	for itemKey, pair := range paired {
+		if pair.direct.Arm == "" || pair.search.Arm == "" {
+			return ToolSearchAgentABReport{}, fmt.Errorf("Agent A/B case %s/%d is not paired", itemKey.caseID, itemKey.trial)
+		}
+		pairs = append(pairs, *pair)
+		caseSet[itemKey.caseID] = true
+	}
+	sort.Slice(pairs, func(i, j int) bool {
+		if pairs[i].caseID == pairs[j].caseID {
+			return pairs[i].direct.Trial < pairs[j].direct.Trial
+		}
+		return pairs[i].caseID < pairs[j].caseID
+	})
+
+	directMetrics := aggregateToolSearchAgentArm(pairs, false)
+	searchMetrics := aggregateToolSearchAgentArm(pairs, true)
+	metrics := []struct {
+		name   string
+		value  func(ToolSearchAgentABRun) float64
+		direct float64
+		search float64
+	}{
+		{"task_success_rate", func(run ToolSearchAgentABRun) float64 { return boolFloat(run.TaskCompleted) }, directMetrics.TaskSuccessRate, searchMetrics.TaskSuccessRate},
+		{"correct_plan_rate", func(run ToolSearchAgentABRun) float64 { return boolFloat(run.CorrectToolPlan) }, directMetrics.CorrectPlanRate, searchMetrics.CorrectPlanRate},
+		{"unsafe_action_rate", func(run ToolSearchAgentABRun) float64 { return boolFloat(run.UnsafeAction) }, directMetrics.UnsafeActionRate, searchMetrics.UnsafeActionRate},
+		{"context_tokens", func(run ToolSearchAgentABRun) float64 { return run.ContextTokens }, directMetrics.AverageContextTokens, searchMetrics.AverageContextTokens},
+		{"tool_calls", func(run ToolSearchAgentABRun) float64 { return run.ToolCalls }, directMetrics.AverageToolCalls, searchMetrics.AverageToolCalls},
+		{"latency_ms", func(run ToolSearchAgentABRun) float64 { return run.LatencyMS }, directMetrics.AverageLatencyMS, searchMetrics.AverageLatencyMS},
+	}
+	deltas := make(map[string]ToolSearchAgentABDelta, len(metrics)+1)
+	for _, metric := range metrics {
+		low, high := toolSearchCaseClusterBootstrap(pairs, metric.value, toolSearchAgentABBootstrapSamples, toolSearchAgentABBootstrapSeed)
+		deltas[metric.name] = ToolSearchAgentABDelta{
+			DirectSchema:  metric.direct,
+			SearchInspect: metric.search,
+			Delta:         metric.search - metric.direct,
+			CI95Low:       low,
+			CI95High:      high,
+		}
+	}
+	if directMetrics.RecoveryAttempts > 0 && searchMetrics.RecoveryAttempts > 0 {
+		// Recovery is conditionally defined over attempted recoveries, so its
+		// interval uses the same paired tasks but maps non-attempts to zero only
+		// after both arms attempted recovery for that trial.
+		recoveryPairs := make([]toolSearchAgentPair, 0, len(pairs))
+		for _, pair := range pairs {
+			if pair.direct.RecoveryAttempted && pair.search.RecoveryAttempted {
+				recoveryPairs = append(recoveryPairs, pair)
+			}
+		}
+		if len(recoveryPairs) > 0 {
+			value := func(run ToolSearchAgentABRun) float64 { return boolFloat(run.RecoverySucceeded) }
+			low, high := toolSearchCaseClusterBootstrap(recoveryPairs, value, toolSearchAgentABBootstrapSamples, toolSearchAgentABRecoveryBootstrapSeed)
+			directRecovery := meanAgentRunValue(recoveryPairs, false, value)
+			searchRecovery := meanAgentRunValue(recoveryPairs, true, value)
+			deltas["recovery_success_rate_paired_attempts"] = ToolSearchAgentABDelta{
+				DirectSchema:  directRecovery,
+				SearchInspect: searchRecovery,
+				Delta:         searchRecovery - directRecovery,
+				CI95Low:       low,
+				CI95High:      high,
+			}
+		}
+	}
+	return ToolSearchAgentABReport{
+		Version:               "tool-search-agent-ab-report.v1",
+		Catalog:               input.Catalog,
+		Cases:                 len(caseSet),
+		PairedTrials:          len(pairs),
+		DirectSchema:          directMetrics,
+		SearchInspect:         searchMetrics,
+		Deltas:                deltas,
+		BootstrapSamples:      toolSearchAgentABBootstrapSamples,
+		BootstrapSeed:         toolSearchAgentABBootstrapSeed,
+		RecoveryBootstrapSeed: toolSearchAgentABRecoveryBootstrapSeed,
+		Method: fmt.Sprintf(
+			"paired by case_id/trial; 95%% percentile bootstrap clustered by case_id; %d resamples; fixed seed %d (recovery slice seed %d)",
+			toolSearchAgentABBootstrapSamples,
+			toolSearchAgentABBootstrapSeed,
+			toolSearchAgentABRecoveryBootstrapSeed,
+		),
+	}, nil
+}
+
+func aggregateToolSearchAgentArm(pairs []toolSearchAgentPair, search bool) ToolSearchAgentABArmMetrics {
+	metrics := ToolSearchAgentABArmMetrics{Runs: len(pairs)}
+	for _, pair := range pairs {
+		run := pair.direct
+		if search {
+			run = pair.search
+		}
+		metrics.TaskSuccessRate += boolFloat(run.TaskCompleted)
+		metrics.CorrectPlanRate += boolFloat(run.CorrectToolPlan)
+		metrics.UnsafeActionRate += boolFloat(run.UnsafeAction)
+		metrics.AverageContextTokens += run.ContextTokens
+		metrics.AverageToolCalls += run.ToolCalls
+		metrics.AverageLatencyMS += run.LatencyMS
+		if run.RecoveryAttempted {
+			metrics.RecoveryAttempts++
+			metrics.RecoverySuccessRate += boolFloat(run.RecoverySucceeded)
+		}
+	}
+	if metrics.Runs > 0 {
+		denominator := float64(metrics.Runs)
+		metrics.TaskSuccessRate /= denominator
+		metrics.CorrectPlanRate /= denominator
+		metrics.UnsafeActionRate /= denominator
+		metrics.AverageContextTokens /= denominator
+		metrics.AverageToolCalls /= denominator
+		metrics.AverageLatencyMS /= denominator
+	}
+	if metrics.RecoveryAttempts > 0 {
+		metrics.RecoverySuccessRate /= float64(metrics.RecoveryAttempts)
+	}
+	return metrics
+}
+
+func toolSearchCaseClusterBootstrap(pairs []toolSearchAgentPair, value func(ToolSearchAgentABRun) float64, samples int, seed int64) (float64, float64) {
+	byCase := make(map[string][]float64)
+	for _, pair := range pairs {
+		byCase[pair.caseID] = append(byCase[pair.caseID], value(pair.search)-value(pair.direct))
+	}
+	caseIDs := make([]string, 0, len(byCase))
+	caseMeans := make(map[string]float64, len(byCase))
+	for caseID, values := range byCase {
+		caseIDs = append(caseIDs, caseID)
+		for _, value := range values {
+			caseMeans[caseID] += value / float64(len(values))
+		}
+	}
+	sort.Strings(caseIDs)
+	if len(caseIDs) == 1 {
+		value := caseMeans[caseIDs[0]]
+		return value, value
+	}
+	random := rand.New(rand.NewSource(seed))
+	distribution := make([]float64, samples)
+	for sample := range samples {
+		var total float64
+		for range caseIDs {
+			total += caseMeans[caseIDs[random.Intn(len(caseIDs))]]
+		}
+		distribution[sample] = total / float64(len(caseIDs))
+	}
+	sort.Float64s(distribution)
+	return percentile(distribution, 0.025), percentile(distribution, 0.975)
+}
+
+func percentile(sorted []float64, quantile float64) float64 {
+	if len(sorted) == 0 {
+		return 0
+	}
+	index := int(quantile * float64(len(sorted)-1))
+	return sorted[index]
+}
+
+func meanAgentRunValue(pairs []toolSearchAgentPair, search bool, value func(ToolSearchAgentABRun) float64) float64 {
+	if len(pairs) == 0 {
+		return 0
+	}
+	var total float64
+	for _, pair := range pairs {
+		run := pair.direct
+		if search {
+			run = pair.search
+		}
+		total += value(run)
+	}
+	return total / float64(len(pairs))
+}
+
+func boolFloat(value bool) float64 {
+	if value {
+		return 1
+	}
+	return 0
+}
@@ -0,0 +1,587 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"math"
+	"sort"
+	"unicode"
+	"unicode/utf8"
+)
+
+// ToolSearchWorkflowEvaluationCase is a reviewed diagnostic workflow. It is
+// intentionally separate from release qrels: the small in-repository fixture
+// measures mechanics and cannot approve a ranking configuration.
+type ToolSearchWorkflowEvaluationCase struct {
+	ID         string   `json:"id"`
+	Query      string   `json:"query"`
+	Subqueries []string `json:"subqueries"`
+	Required   []string `json:"required"`
+}
+
+// ToolSearchRetrievalMetrics reports deterministic ranking metrics. Values are
+// fractions in [0,1], not percentages.
+type ToolSearchRetrievalMetrics struct {
+	Cases                 int     `json:"cases"`
+	RecallAt1             float64 `json:"recall_at_1"`
+	RecallAt5             float64 `json:"recall_at_5"`
+	MeanReciprocalRankAt5 float64 `json:"mean_reciprocal_rank_at_5"`
+	ZeroResultRate        float64 `json:"zero_result_rate"`
+}
+
+// ToolSearchWorkflowMetrics measures whether every required tool is present in
+// the shared Top-5 budget and the average required-tool recall.
+type ToolSearchWorkflowMetrics struct {
+	Cases             int     `json:"cases"`
+	CompleteAt5       float64 `json:"complete_at_5"`
+	RequiredRecallAt5 float64 `json:"required_recall_at_5"`
+}
+
+// ToolSearchIdentityTrustMetrics exercises the complete delivered identity
+// set. Exact filtered checks deliberately exclude each canonical path and
+// verify that search abstains instead of falling through to a fuzzy sibling.
+type ToolSearchIdentityTrustMetrics struct {
+	CanonicalCases        int     `json:"canonical_cases"`
+	CanonicalPassRate     float64 `json:"canonical_pass_rate"`
+	PrimaryCLICases       int     `json:"primary_cli_cases"`
+	PrimaryCLIPassRate    float64 `json:"primary_cli_pass_rate"`
+	AliasCases            int     `json:"alias_cases"`
+	AliasPassRate         float64 `json:"alias_pass_rate"`
+	NFKCCases             int     `json:"nfkc_cases"`
+	NFKCPassRate          float64 `json:"nfkc_pass_rate"`
+	ExactFilteredCases    int     `json:"exact_filtered_cases"`
+	ExactFilteredPassRate float64 `json:"exact_filtered_pass_rate"`
+}
+
+// ToolSearchNegativeTrustMetrics is a same-source diagnostic only. A
+// forbidden exposure means the tool that owns an avoid_when sentence appears
+// in the ranking; it does not prove that a model would call that tool.
+type ToolSearchNegativeTrustMetrics struct {
+	Cases              int     `json:"cases"`
+	ExcludedOverBudget int     `json:"excluded_over_budget"`
+	ForbiddenAt1       float64 `json:"forbidden_at_1"`
+	ForbiddenAt5       float64 `json:"forbidden_at_5"`
+}
+
+// ToolSearchIntegrityMetrics verifies invariants that do not depend on
+// relevance labels.
+type ToolSearchIntegrityMetrics struct {
+	ResponsesEvaluated       int `json:"responses_evaluated"`
+	CatalogBindingFailures   int `json:"catalog_binding_failures"`
+	UnknownCandidateCount    int `json:"unknown_candidate_count"`
+	IneligibleCandidateCount int `json:"ineligible_candidate_count"`
+	ResponseBudgetViolations int `json:"response_budget_violations"`
+}
+
+// ToolSearchTrustMetrics keeps contract integrity separate from ranking
+// relevance. Search rank is never presented as a probability of safe use.
+type ToolSearchTrustMetrics struct {
+	Identity  ToolSearchIdentityTrustMetrics `json:"identity"`
+	Negative  ToolSearchNegativeTrustMetrics `json:"negative"`
+	Integrity ToolSearchIntegrityMetrics     `json:"integrity"`
+}
+
+// ToolSearchContextComparison compares byte-level JSON envelopes, not model
+// tokens. The ideal navigation path assumes an oracle already knows the right
+// product; its selection success is therefore deliberately not estimated.
+type ToolSearchContextComparison struct {
+	ToolCount                         int     `json:"tool_count"`
+	FullSchemaAllBytes                int     `json:"full_schema_all_bytes"`
+	OverviewBytes                     int     `json:"overview_bytes"`
+	AverageProductBytes               float64 `json:"average_product_bytes"`
+	AverageInspectBytes               float64 `json:"average_inspect_bytes"`
+	AverageIdealSchemaNavigationBytes float64 `json:"average_ideal_schema_navigation_bytes"`
+	AverageSearchInspectBytes         float64 `json:"average_search_inspect_bytes"`
+	ReductionVsFullSchema             float64 `json:"reduction_vs_full_schema"`
+	ReductionVsIdealNavigation        float64 `json:"reduction_vs_ideal_navigation"`
+}
+
+// ToolSearchDiagnosticComparison is generated from the exact typed Catalog
+// embedded in the binary. It is a diagnostic proxy, not an Agent completion
+// benchmark: its intent queries come from reviewed use_when prose and therefore
+// are not independently authored qrels.
+type ToolSearchDiagnosticComparison struct {
+	Version                  string                                `json:"version"`
+	Catalog                  CatalogVersionRef                     `json:"catalog"`
+	Algorithm                string                                `json:"algorithm"`
+	TopK                     int                                   `json:"top_k"`
+	IntentProxy              ToolSearchRetrievalMetrics            `json:"intent_proxy"`
+	IntentExcludedOverBudget int                                   `json:"intent_excluded_over_budget"`
+	IntentLanguageSlices     map[string]ToolSearchRetrievalMetrics `json:"intent_language_slices"`
+	WorkflowRaw              ToolSearchWorkflowMetrics             `json:"workflow_raw"`
+	WorkflowDecomposed       ToolSearchWorkflowMetrics             `json:"workflow_decomposed"`
+	Trust                    ToolSearchTrustMetrics                `json:"trust"`
+	Context                  ToolSearchContextComparison           `json:"context"`
+	AgentABStatus            string                                `json:"agent_ab_status"`
+	Limitations              []string                              `json:"limitations"`
+}
+
+// BuildDeliveryToolSearchDiagnosticComparison evaluates the shipped Go
+// retriever against the declaration-assembled Catalog without reading a
+// generated repository JSON artifact. Results belong under policy-tmp.
+func BuildDeliveryToolSearchDiagnosticComparison(ctx context.Context, workflows []ToolSearchWorkflowEvaluationCase) (ToolSearchDiagnosticComparison, error) {
+	return BuildDeliveryToolSearchDiagnosticComparisonForAlgorithm(ctx, workflows, DefaultToolSearchConfig().LexicalAlgorithm)
+}
+
+// BuildDeliveryToolSearchDiagnosticComparisonForAlgorithm runs one shipped Go
+// lexical implementation over exactly the same typed Catalog and fixtures.
+// This keeps shadow algorithm comparison out of the production default.
+func BuildDeliveryToolSearchDiagnosticComparisonForAlgorithm(ctx context.Context, workflows []ToolSearchWorkflowEvaluationCase, algorithm string) (ToolSearchDiagnosticComparison, error) {
+	if err := deliverySchemaCatalogError(); err != nil {
+		return ToolSearchDiagnosticComparison{}, fmt.Errorf("assemble typed Schema registry for evaluation: %w", err)
+	}
+	loaded := deliverySchemaCatalog()
+	config := DefaultToolSearchConfig()
+	config.LexicalAlgorithm = algorithm
+	config.CatalogSourceHash = loaded.Snapshot.SourceHash
+	config.CatalogSurfaceHash = loaded.Snapshot.SurfaceHash
+	engine, err := NewToolSearchEngine(loaded.Registry, config)
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, err
+	}
+	allPayload, err := deliverySchemaAllPayload()
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, fmt.Errorf("render full Schema: %w", err)
+	}
+	overviewPayload, err := deliverySchemaOverviewPayload()
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, fmt.Errorf("render Schema overview: %w", err)
+	}
+	allBytes, err := compactJSONSize(allPayload)
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, err
+	}
+	overviewBytes, err := compactJSONSize(stripSchemaPayloadCompact(overviewPayload))
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, err
+	}
+
+	type proxyCase struct {
+		query   string
+		gold    string
+		product string
+	}
+	proxyCases := make([]proxyCase, 0)
+	intentExcludedOverBudget := 0
+	for _, product := range loaded.Registry.Products {
+		for _, tool := range product.Tools {
+			for _, query := range tool.Selection.UseWhen {
+				if query != "" && toolSearchQueryWithinBudget(query) {
+					proxyCases = append(proxyCases, proxyCase{query: query, gold: tool.Identity.CanonicalPath, product: product.ID})
+				} else if query != "" {
+					intentExcludedOverBudget++
+				}
+			}
+		}
+	}
+	sort.Slice(proxyCases, func(i, j int) bool {
+		if proxyCases[i].gold == proxyCases[j].gold {
+			return proxyCases[i].query < proxyCases[j].query
+		}
+		return proxyCases[i].gold < proxyCases[j].gold
+	})
+
+	intentAccumulator := &toolSearchRetrievalAccumulator{}
+	languageAccumulators := map[string]*toolSearchRetrievalAccumulator{}
+	var totalProductBytes, totalInspectBytes, totalSearchBytes float64
+	productSizes := make(map[string]int)
+	inspectSizes := make(map[string]int)
+	for _, item := range proxyCases {
+		if err := ctx.Err(); err != nil {
+			return ToolSearchDiagnosticComparison{}, err
+		}
+		response, searchErr := engine.Search(ctx, ToolSearchRequest{Query: item.query, Limit: 5, CandidateLimit: 20})
+		if searchErr != nil {
+			return ToolSearchDiagnosticComparison{}, fmt.Errorf("search proxy case %s: %w", item.gold, searchErr)
+		}
+		rank := 0
+		for index, candidate := range response.Candidates {
+			if candidate.CanonicalPath != item.gold {
+				continue
+			}
+			rank = index + 1
+			break
+		}
+		intentAccumulator.observe(rank, len(response.Candidates) == 0)
+		slice := toolSearchQueryLanguageSlice(item.query)
+		if languageAccumulators[slice] == nil {
+			languageAccumulators[slice] = &toolSearchRetrievalAccumulator{}
+		}
+		languageAccumulators[slice].observe(rank, len(response.Candidates) == 0)
+		encodedResponse, marshalErr := json.Marshal(response)
+		if marshalErr != nil {
+			return ToolSearchDiagnosticComparison{}, marshalErr
+		}
+		totalSearchBytes += float64(len(encodedResponse))
+
+		productBytes, ok := productSizes[item.product]
+		if !ok {
+			payload, payloadErr := queryDeliverySchemaPayload([]string{item.product})
+			if payloadErr != nil {
+				return ToolSearchDiagnosticComparison{}, payloadErr
+			}
+			productBytes, payloadErr = compactJSONSize(stripSchemaPayloadCompact(payload))
+			if payloadErr != nil {
+				return ToolSearchDiagnosticComparison{}, payloadErr
+			}
+			productSizes[item.product] = productBytes
+		}
+		totalProductBytes += float64(productBytes)
+
+		inspectBytes, ok := inspectSizes[item.gold]
+		if !ok {
+			payload, payloadErr := queryDeliverySchemaPayload([]string{item.gold})
+			if payloadErr != nil {
+				return ToolSearchDiagnosticComparison{}, payloadErr
+			}
+			payload = stripSchemaPayloadCompact(payload)
+			inspectBytes, payloadErr = compactJSONSize(SchemaInspectV1Response{
+				Version:  "schema-inspect.v1",
+				Catalog:  CatalogVersionRef{SourceHash: loaded.Snapshot.SourceHash, SurfaceHash: loaded.Snapshot.SurfaceHash},
+				ToolSpec: payload,
+			})
+			if payloadErr != nil {
+				return ToolSearchDiagnosticComparison{}, payloadErr
+			}
+			inspectSizes[item.gold] = inspectBytes
+		}
+		totalInspectBytes += float64(inspectBytes)
+	}
+
+	count := float64(len(proxyCases))
+	intent := intentAccumulator.metrics()
+	languageSlices := make(map[string]ToolSearchRetrievalMetrics, len(languageAccumulators))
+	for slice, accumulator := range languageAccumulators {
+		languageSlices[slice] = accumulator.metrics()
+	}
+	contextComparison := ToolSearchContextComparison{
+		ToolCount:          len(loaded.Index.CanonicalPaths()),
+		FullSchemaAllBytes: allBytes,
+		OverviewBytes:      overviewBytes,
+	}
+	if count > 0 {
+		contextComparison.AverageProductBytes = totalProductBytes / count
+		contextComparison.AverageInspectBytes = totalInspectBytes / count
+		contextComparison.AverageIdealSchemaNavigationBytes = float64(overviewBytes) + contextComparison.AverageProductBytes + contextComparison.AverageInspectBytes
+		contextComparison.AverageSearchInspectBytes = totalSearchBytes/count + contextComparison.AverageInspectBytes
+		contextComparison.ReductionVsFullSchema = reduction(float64(allBytes), contextComparison.AverageSearchInspectBytes)
+		contextComparison.ReductionVsIdealNavigation = reduction(contextComparison.AverageIdealSchemaNavigationBytes, contextComparison.AverageSearchInspectBytes)
+	}
+
+	rawWorkflow, decomposedWorkflow, err := evaluateToolSearchWorkflows(ctx, engine, workflows)
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, err
+	}
+	trust, err := evaluateToolSearchTrust(ctx, engine, loaded.Registry)
+	if err != nil {
+		return ToolSearchDiagnosticComparison{}, err
+	}
+	return ToolSearchDiagnosticComparison{
+		Version:                  "tool-search-diagnostic-comparison.v1",
+		Catalog:                  engine.catalogVersion(),
+		Algorithm:                engine.lexical.Name(),
+		TopK:                     5,
+		IntentProxy:              intent,
+		IntentExcludedOverBudget: intentExcludedOverBudget,
+		IntentLanguageSlices:     languageSlices,
+		WorkflowRaw:              rawWorkflow,
+		WorkflowDecomposed:       decomposedWorkflow,
+		Trust:                    trust,
+		Context:                  contextComparison,
+		AgentABStatus:            "not_run_requires_independent_tasks_and_model_runs",
+		Limitations: []string{
+			"intent_proxy queries are reviewed use_when prose from the same Catalog and are not independent qrels",
+			"selection prose that exceeds the production query byte or rune budget is counted and excluded rather than weakening runtime limits",
+			"direct Schema navigation bytes assume an oracle selects the correct product and do not estimate model selection success",
+			"search plus inspect bytes also inspect the gold leaf even when retrieval misses and are an oracle-assisted capacity upper bound, not observed Agent cost",
+			"workflow decomposition uses reviewed fixture subqueries and is an upper-bound diagnostic",
+			"negative queries are same-source avoid_when prose without alternative gold and measure candidate exposure rather than Agent calls",
+			"byte counts are compact JSON bytes rather than provider-specific tokenizer counts",
+			"true Agent task success, unsafe action rate, recovery success, latency, and token cost require paired Agent A/B runs",
+		},
+	}, nil
+}
+
+type toolSearchRetrievalAccumulator struct {
+	cases       int
+	hitAt1      int
+	hitAt5      int
+	reciprocal  float64
+	zeroResults int
+}
+
+func (a *toolSearchRetrievalAccumulator) observe(rank int, zeroResults bool) {
+	a.cases++
+	if zeroResults {
+		a.zeroResults++
+	}
+	if rank == 1 {
+		a.hitAt1++
+	}
+	if rank > 0 && rank <= 5 {
+		a.hitAt5++
+		a.reciprocal += 1 / float64(rank)
+	}
+}
+
+func (a *toolSearchRetrievalAccumulator) metrics() ToolSearchRetrievalMetrics {
+	result := ToolSearchRetrievalMetrics{Cases: a.cases}
+	if a.cases == 0 {
+		return result
+	}
+	denominator := float64(a.cases)
+	result.RecallAt1 = float64(a.hitAt1) / denominator
+	result.RecallAt5 = float64(a.hitAt5) / denominator
+	result.MeanReciprocalRankAt5 = a.reciprocal / denominator
+	result.ZeroResultRate = float64(a.zeroResults) / denominator
+	return result
+}
+
+func toolSearchQueryLanguageSlice(query string) string {
+	hasChinese := false
+	hasASCIIWord := false
+	for _, character := range query {
+		if unicode.Is(unicode.Han, character) {
+			hasChinese = true
+		}
+		if character <= unicode.MaxASCII && (unicode.IsLetter(character) || unicode.IsDigit(character)) {
+			hasASCIIWord = true
+		}
+	}
+	if hasChinese && hasASCIIWord {
+		return "mixed_chinese_ascii"
+	}
+	if hasChinese {
+		return "chinese_only"
+	}
+	return "non_chinese"
+}
+
+func evaluateToolSearchTrust(ctx context.Context, engine *ToolSearchEngine, registry SchemaRegistry) (ToolSearchTrustMetrics, error) {
+	result := ToolSearchTrustMetrics{}
+	var canonicalPassed, cliPassed, aliasPassed, nfkcPassed, filteredPassed int
+	var forbiddenAt1, forbiddenAt5 int
+	for _, product := range registry.Products {
+		for _, tool := range product.Tools {
+			if err := ctx.Err(); err != nil {
+				return result, err
+			}
+			result.Identity.CanonicalCases++
+			response, err := engine.Search(ctx, ToolSearchRequest{Query: tool.Identity.CanonicalPath})
+			if err != nil {
+				return result, fmt.Errorf("audit exact canonical %s: %w", tool.Identity.CanonicalPath, err)
+			}
+			observeToolSearchIntegrity(&result.Integrity, engine, response)
+			if exactSearchMatches(response, tool.Identity.CanonicalPath) {
+				canonicalPassed++
+			}
+
+			if cliPath := tool.Identity.PrimaryCLIPath; cliPath != "" {
+				result.Identity.PrimaryCLICases++
+				response, err = engine.Search(ctx, ToolSearchRequest{Query: cliPath})
+				if err != nil {
+					return result, fmt.Errorf("audit exact CLI %s: %w", cliPath, err)
+				}
+				observeToolSearchIntegrity(&result.Integrity, engine, response)
+				if exactSearchMatches(response, tool.Identity.CanonicalPath) {
+					cliPassed++
+				}
+			}
+			for _, alias := range tool.Identity.Aliases {
+				result.Identity.AliasCases++
+				response, err = engine.Search(ctx, ToolSearchRequest{Query: alias})
+				if err != nil {
+					return result, fmt.Errorf("audit exact alias %s: %w", alias, err)
+				}
+				observeToolSearchIntegrity(&result.Integrity, engine, response)
+				if exactSearchMatches(response, tool.Identity.CanonicalPath) {
+					aliasPassed++
+				}
+			}
+			nfkcQuery := toolSearchFullwidthASCII(tool.Identity.CanonicalPath)
+			if nfkcQuery != tool.Identity.CanonicalPath {
+				result.Identity.NFKCCases++
+				response, err = engine.Search(ctx, ToolSearchRequest{Query: nfkcQuery})
+				if err != nil {
+					return result, fmt.Errorf("audit NFKC identity %s: %w", tool.Identity.CanonicalPath, err)
+				}
+				observeToolSearchIntegrity(&result.Integrity, engine, response)
+				if exactSearchMatches(response, tool.Identity.CanonicalPath) {
+					nfkcPassed++
+				}
+			}
+
+			result.Identity.ExactFilteredCases++
+			response, err = engine.Search(ctx, ToolSearchRequest{
+				Query:                 tool.Identity.CanonicalPath,
+				ExcludeCanonicalPaths: []string{tool.Identity.CanonicalPath},
+			})
+			if err != nil {
+				return result, fmt.Errorf("audit exact filtered %s: %w", tool.Identity.CanonicalPath, err)
+			}
+			observeToolSearchIntegrity(&result.Integrity, engine, response)
+			if response.Strategy == "exact_filtered" && response.Abstained && len(response.Candidates) == 0 && response.ExactFiltered != nil && response.ExactFiltered.CanonicalPath == tool.Identity.CanonicalPath && response.ExactFiltered.Reason == "excluded" {
+				filteredPassed++
+			}
+
+			for _, query := range tool.Selection.AvoidWhen {
+				if query == "" {
+					continue
+				}
+				if !toolSearchQueryWithinBudget(query) {
+					result.Negative.ExcludedOverBudget++
+					continue
+				}
+				result.Negative.Cases++
+				response, err = engine.Search(ctx, ToolSearchRequest{Query: query, Limit: 5, CandidateLimit: 20})
+				if err != nil {
+					return result, fmt.Errorf("audit negative %s: %w", tool.Identity.CanonicalPath, err)
+				}
+				observeToolSearchIntegrity(&result.Integrity, engine, response)
+				for rank, candidate := range response.Candidates {
+					if candidate.CanonicalPath != tool.Identity.CanonicalPath {
+						continue
+					}
+					if rank == 0 {
+						forbiddenAt1++
+					}
+					forbiddenAt5++
+					break
+				}
+			}
+		}
+	}
+	if result.Identity.CanonicalCases > 0 {
+		result.Identity.CanonicalPassRate = float64(canonicalPassed) / float64(result.Identity.CanonicalCases)
+	}
+	if result.Identity.PrimaryCLICases > 0 {
+		result.Identity.PrimaryCLIPassRate = float64(cliPassed) / float64(result.Identity.PrimaryCLICases)
+	}
+	if result.Identity.AliasCases > 0 {
+		result.Identity.AliasPassRate = float64(aliasPassed) / float64(result.Identity.AliasCases)
+	}
+	if result.Identity.NFKCCases > 0 {
+		result.Identity.NFKCPassRate = float64(nfkcPassed) / float64(result.Identity.NFKCCases)
+	}
+	if result.Identity.ExactFilteredCases > 0 {
+		result.Identity.ExactFilteredPassRate = float64(filteredPassed) / float64(result.Identity.ExactFilteredCases)
+	}
+	if result.Negative.Cases > 0 {
+		result.Negative.ForbiddenAt1 = float64(forbiddenAt1) / float64(result.Negative.Cases)
+		result.Negative.ForbiddenAt5 = float64(forbiddenAt5) / float64(result.Negative.Cases)
+	}
+	return result, nil
+}
+
+func toolSearchFullwidthASCII(value string) string {
+	runes := []rune(value)
+	for index, character := range runes {
+		if character >= '!' && character <= '~' {
+			runes[index] = character + 0xFEE0
+		}
+	}
+	return string(runes)
+}
+
+func toolSearchQueryWithinBudget(query string) bool {
+	return len(query) <= maxToolSearchQueryBytes && utf8.RuneCountInString(query) <= maxToolSearchQueryRunes
+}
+
+func exactSearchMatches(response ToolSearchResponse, canonical string) bool {
+	return response.Strategy == "exact_guard" && len(response.Candidates) == 1 && response.Candidates[0].CanonicalPath == canonical && response.Candidates[0].RequiresInspect
+}
+
+func observeToolSearchIntegrity(metrics *ToolSearchIntegrityMetrics, engine *ToolSearchEngine, response ToolSearchResponse) {
+	metrics.ResponsesEvaluated++
+	if response.Catalog != engine.catalogVersion() {
+		metrics.CatalogBindingFailures++
+	}
+	if encoded, err := json.Marshal(response); err != nil || len(encoded) > maxToolSearchResponseBytes {
+		metrics.ResponseBudgetViolations++
+	}
+	for _, candidate := range response.Candidates {
+		document, ok := engine.documents[candidate.CanonicalPath]
+		if !ok {
+			metrics.UnknownCandidateCount++
+			continue
+		}
+		if !toolSearchEligible(document.tool, nil, nil, nil) {
+			metrics.IneligibleCandidateCount++
+		}
+	}
+}
+
+func evaluateToolSearchWorkflows(ctx context.Context, engine *ToolSearchEngine, workflows []ToolSearchWorkflowEvaluationCase) (ToolSearchWorkflowMetrics, ToolSearchWorkflowMetrics, error) {
+	raw := ToolSearchWorkflowMetrics{Cases: len(workflows)}
+	decomposed := ToolSearchWorkflowMetrics{Cases: len(workflows)}
+	if len(workflows) == 0 {
+		return raw, decomposed, nil
+	}
+	for _, workflow := range workflows {
+		if workflow.ID == "" || workflow.Query == "" || len(workflow.Required) == 0 {
+			return raw, decomposed, fmt.Errorf("workflow evaluation case must have id, query and required tools")
+		}
+		one, err := engine.Search(ctx, ToolSearchRequest{Query: workflow.Query, Limit: 5, CandidateLimit: 20})
+		if err != nil {
+			return raw, decomposed, fmt.Errorf("search workflow %s: %w", workflow.ID, err)
+		}
+		many, err := engine.SearchSubqueries(ctx, workflow.Subqueries, ToolSearchRequest{Query: workflow.Query, Limit: 5, CandidateLimit: 20})
+		if err != nil {
+			return raw, decomposed, fmt.Errorf("search decomposed workflow %s: %w", workflow.ID, err)
+		}
+		accumulateWorkflowMetrics(&raw, one.Candidates, workflow.Required)
+		accumulateWorkflowMetrics(&decomposed, many.Candidates, workflow.Required)
+	}
+	denominator := float64(len(workflows))
+	raw.CompleteAt5 /= denominator
+	raw.RequiredRecallAt5 /= denominator
+	decomposed.CompleteAt5 /= denominator
+	decomposed.RequiredRecallAt5 /= denominator
+	return raw, decomposed, nil
+}
+
+func accumulateWorkflowMetrics(metrics *ToolSearchWorkflowMetrics, candidates []ToolReference, required []string) {
+	found := make(map[string]bool, len(candidates))
+	for _, candidate := range candidates {
+		found[candidate.CanonicalPath] = true
+	}
+	hits := 0
+	for _, canonical := range required {
+		if found[canonical] {
+			hits++
+		}
+	}
+	metrics.RequiredRecallAt5 += float64(hits) / float64(len(required))
+	if hits == len(required) {
+		metrics.CompleteAt5++
+	}
+}
+
+func compactJSONSize(value any) (int, error) {
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		return 0, fmt.Errorf("marshal compact JSON: %w", err)
+	}
+	return len(encoded), nil
+}
+
+func reduction(baseline, candidate float64) float64 {
+	if baseline <= 0 {
+		return 0
+	}
+	return math.Max(-1, math.Min(1, 1-candidate/baseline))
+}
@@ -0,0 +1,98 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cli
+
+import "testing"
+
+func TestAggregateToolSearchAgentAB(t *testing.T) {
+	catalog := CatalogVersionRef{SourceHash: "sha256:source", SurfaceHash: "sha256:surface"}
+	input := ToolSearchAgentABInput{
+		Version: "tool-search-agent-ab.v1",
+		Catalog: catalog,
+		Runs: []ToolSearchAgentABRun{
+			{CaseID: "a", Trial: 0, Arm: ToolSearchAgentArmDirectSchema, CorrectToolPlan: true, ContextTokens: 100, ToolCalls: 3, LatencyMS: 1000},
+			{CaseID: "a", Trial: 0, Arm: ToolSearchAgentArmSearchInspect, TaskCompleted: true, CorrectToolPlan: true, ContextTokens: 40, ToolCalls: 2, LatencyMS: 800},
+			{CaseID: "b", Trial: 0, Arm: ToolSearchAgentArmDirectSchema, TaskCompleted: true, CorrectToolPlan: true, UnsafeAction: true, RecoveryAttempted: true, ContextTokens: 120, ToolCalls: 4, LatencyMS: 1200},
+			{CaseID: "b", Trial: 0, Arm: ToolSearchAgentArmSearchInspect, TaskCompleted: true, CorrectToolPlan: true, RecoveryAttempted: true, RecoverySucceeded: true, ContextTokens: 50, ToolCalls: 3, LatencyMS: 900},
+		},
+	}
+	report, err := AggregateToolSearchAgentAB(input)
+	if err != nil {
+		t.Fatalf("AggregateToolSearchAgentAB() error = %v", err)
+	}
+	if report.Cases != 2 || report.PairedTrials != 2 {
+		t.Fatalf("pair counts = cases %d trials %d", report.Cases, report.PairedTrials)
+	}
+	if report.DirectSchema.TaskSuccessRate != 0.5 || report.SearchInspect.TaskSuccessRate != 1 {
+		t.Fatalf("unexpected success rates: direct=%v search=%v", report.DirectSchema.TaskSuccessRate, report.SearchInspect.TaskSuccessRate)
+	}
+	if delta := report.Deltas["context_tokens"].Delta; delta != -65 {
+		t.Fatalf("context delta = %v, want -65", delta)
+	}
+	if _, ok := report.Deltas["recovery_success_rate_paired_attempts"]; !ok {
+		t.Fatal("paired recovery delta missing")
+	}
+}
+
+func TestAggregateToolSearchAgentABRejectsUnpairedRuns(t *testing.T) {
+	_, err := AggregateToolSearchAgentAB(ToolSearchAgentABInput{
+		Version: "tool-search-agent-ab.v1",
+		Catalog: CatalogVersionRef{SourceHash: "source", SurfaceHash: "surface"},
+		Runs: []ToolSearchAgentABRun{
+			{CaseID: "a", Arm: ToolSearchAgentArmDirectSchema},
+		},
+	})
+	if err == nil {
+		t.Fatal("AggregateToolSearchAgentAB() accepted an unpaired run")
+	}
+}
+
+func TestScoreToolSearchAgentPlanningAB(t *testing.T) {
+	workflows := []ToolSearchWorkflowEvaluationCase{
+		{ID: "one", Required: []string{"chat.search_groups", "chat.send_personal_message"}},
+		{ID: "two", Required: []string{"drive.upload", "drive.add_permission"}},
+	}
+	direct := ToolSearchAgentPlanOutput{Results: []ToolSearchAgentPlanResult{
+		{ID: "one", CanonicalPaths: []string{"chat.search_groups", "chat.send_personal_message"}},
+		{ID: "two", CanonicalPaths: []string{"drive.upload", "drive.add_permission"}},
+	}}
+	search := ToolSearchAgentPlanOutput{Results: []ToolSearchAgentPlanResult{
+		{ID: "one", CanonicalPaths: []string{"chat.list_owned_or_admin_groups", "chat.search_groups", "chat.send_personal_message"}},
+		{ID: "two", CanonicalPaths: []string{"drive.upload", "drive.add_permission"}},
+	}}
+	tools := []ToolSpec{
+		toolSearchTestTool("chat", "search_groups", "chat search-groups", "搜索群聊", "read"),
+		toolSearchTestTool("chat", "send_personal_message", "chat message send", "发送消息", "write"),
+		toolSearchTestTool("drive", "upload", "drive upload", "上传文件", "write"),
+		toolSearchTestTool("drive", "add_permission", "drive permission add", "添加权限", "write"),
+		toolSearchTestTool("chat", "list_owned_or_admin_groups", "chat list-groups", "列出群聊", "read"),
+	}
+	index, indexErr := (SchemaRegistry{Kind: "schema", Level: "catalog", Products: []ProductSpec{
+		{ID: "chat", Tools: []ToolSpec{tools[0], tools[1], tools[4]}},
+		{ID: "drive", Tools: tools[2:4]},
+	}}).Index()
+	if indexErr != nil {
+		t.Fatal(indexErr)
+	}
+	report, err := scoreToolSearchAgentPlanningAB(index, "test-model", workflows, direct, search)
+	if err != nil {
+		t.Fatalf("ScoreToolSearchAgentPlanningAB() error = %v", err)
+	}
+	if report.DirectSchema.ExactMinimalRate != 1 || report.SearchInspect.ExactMinimalRate != 0.5 {
+		t.Fatalf("minimal rates = direct %v search %v", report.DirectSchema.ExactMinimalRate, report.SearchInspect.ExactMinimalRate)
+	}
+	if report.SearchInspect.CompleteRate != 1 || report.SearchInspect.UnnecessaryTools != 1 {
+		t.Fatalf("search metrics = %+v", report.SearchInspect)
+	}
+}
@@ -0,0 +1,357 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"math/rand"
+	"sort"
+	"strings"
+)
+
+// The product-cluster paired bootstrap uses a fixed sample count and seed so a
+// sealed qrels run stays reproducible; both are published in the report so an
+// auditor does not have to read them out of the source.
+const (
+	toolSearchIndependentBootstrapSamples = 10_000
+	toolSearchIndependentBootstrapSeed    = 20260813
+)
+
+// ToolSearchIndependentQrel is an independently authored graded relevance
+// judgment. Relevance uses the frozen 1..3 qrels scale.
+type ToolSearchIndependentQrel struct {
+	Canonical string `json:"canonical"`
+	Relevance int    `json:"relevance"`
+}
+
+type ToolSearchIndependentWorkflow struct {
+	Subqueries []string `json:"subqueries,omitempty"`
+	Required   []string `json:"required"`
+}
+
+type ToolSearchIndependentCase struct {
+	ID              string                         `json:"id"`
+	Query           string                         `json:"query"`
+	Language        string                         `json:"language"`
+	Qrels           []ToolSearchIndependentQrel    `json:"qrels"`
+	Forbidden       []string                       `json:"forbidden,omitempty"`
+	AlternativeGold []string                       `json:"alternative_gold,omitempty"`
+	Workflow        *ToolSearchIndependentWorkflow `json:"workflow,omitempty"`
+	ConfusionFamily []string                       `json:"confusion_family,omitempty"`
+}
+
+type ToolSearchIndependentRankingMetrics struct {
+	Cases                 int     `json:"cases"`
+	RecallAt1             float64 `json:"recall_at_1"`
+	RecallAt5             float64 `json:"recall_at_5"`
+	MeanReciprocalRankAt5 float64 `json:"mean_reciprocal_rank_at_5"`
+	NDCGAt5               float64 `json:"ndcg_at_5"`
+	ZeroResultRate        float64 `json:"zero_result_rate"`
+}
+
+type ToolSearchIndependentSafetyMetrics struct {
+	ForbiddenCases        int     `json:"forbidden_cases"`
+	ForbiddenExposureAt5  float64 `json:"forbidden_exposure_at_5"`
+	AlternativeRecallAt5  float64 `json:"alternative_recall_at_5"`
+	SiblingConfusionCases int     `json:"sibling_confusion_cases"`
+	SiblingExposureAt5    float64 `json:"sibling_exposure_at_5"`
+}
+
+type ToolSearchIndependentReport struct {
+	Version            string                                         `json:"version"`
+	Catalog            CatalogVersionRef                              `json:"catalog"`
+	Algorithm          string                                         `json:"algorithm"`
+	ControlAlgorithm   string                                         `json:"control_algorithm"`
+	Overall            ToolSearchIndependentRankingMetrics            `json:"overall"`
+	ControlOverall     ToolSearchIndependentRankingMetrics            `json:"control_overall"`
+	RecallAt5Delta     float64                                        `json:"recall_at_5_delta"`
+	ProductClusterCI95 ToolSearchConfidenceInterval                   `json:"product_cluster_recall_at_5_delta_ci_95"`
+	LanguageSlices     map[string]ToolSearchIndependentRankingMetrics `json:"language_slices"`
+	Safety             ToolSearchIndependentSafetyMetrics             `json:"safety"`
+	Workflow           ToolSearchWorkflowMetrics                      `json:"workflow"`
+	// BootstrapSamples/BootstrapSeed are set only by the paired delivery
+	// evaluation that computes ProductClusterCI95; they make that interval
+	// reproducible without reading the source.
+	BootstrapSamples int   `json:"bootstrap_samples,omitempty"`
+	BootstrapSeed    int64 `json:"bootstrap_seed,omitempty"`
+}
+
+type ToolSearchConfidenceInterval struct {
+	Lower float64 `json:"lower"`
+	Upper float64 `json:"upper"`
+}
+
+type independentRankingAccumulator struct {
+	metrics ToolSearchIndependentRankingMetrics
+	recall1 float64
+	recall5 float64
+	mrr5    float64
+	ndcg5   float64
+	zero    int
+}
+
+// BuildDeliveryToolSearchIndependentEvaluation evaluates the action-ranking
+// candidate against the shipped fielded BM25 control on sealed external qrels.
+// It never tunes parameters or reads Catalog JSON; the caller owns qrels
+// sealing and threshold enforcement. The candidate may become the runtime
+// default only after the independently frozen default-switch gate passes.
+func BuildDeliveryToolSearchIndependentEvaluation(ctx context.Context, cases []ToolSearchIndependentCase) (ToolSearchIndependentReport, error) {
+	if err := deliverySchemaCatalogError(); err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	loaded := deliverySchemaCatalog()
+	candidateConfig := DefaultToolSearchConfig()
+	candidateConfig.LexicalAlgorithm = ToolSearchLexicalBM25Action
+	candidateConfig.CatalogSourceHash = loaded.Snapshot.SourceHash
+	candidateConfig.CatalogSurfaceHash = loaded.Snapshot.SurfaceHash
+	engine, err := NewToolSearchEngine(loaded.Registry, candidateConfig)
+	if err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	report, err := EvaluateToolSearchIndependent(ctx, engine, cases)
+	if err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	controlConfig := DefaultToolSearchConfig()
+	controlConfig.CatalogSourceHash = loaded.Snapshot.SourceHash
+	controlConfig.CatalogSurfaceHash = loaded.Snapshot.SurfaceHash
+	control, err := NewToolSearchEngine(loaded.Registry, controlConfig)
+	if err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	controlReport, err := EvaluateToolSearchIndependent(ctx, control, cases)
+	if err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	report.ControlAlgorithm = control.lexical.Name()
+	report.ControlOverall = controlReport.Overall
+	report.RecallAt5Delta = report.Overall.RecallAt5 - report.ControlOverall.RecallAt5
+	report.ProductClusterCI95, err = pairedProductClusterRecallCI(ctx, engine, control, cases, toolSearchIndependentBootstrapSamples, toolSearchIndependentBootstrapSeed)
+	if err != nil {
+		return ToolSearchIndependentReport{}, err
+	}
+	report.BootstrapSamples = toolSearchIndependentBootstrapSamples
+	report.BootstrapSeed = toolSearchIndependentBootstrapSeed
+	return report, nil
+}
+
+func EvaluateToolSearchIndependent(ctx context.Context, engine *ToolSearchEngine, cases []ToolSearchIndependentCase) (ToolSearchIndependentReport, error) {
+	if engine == nil || len(cases) == 0 {
+		return ToolSearchIndependentReport{}, fmt.Errorf("independent evaluation requires an engine and non-empty cases")
+	}
+	overall := &independentRankingAccumulator{}
+	slices := map[string]*independentRankingAccumulator{}
+	var forbiddenCases, forbiddenExposed int
+	var siblingCases, siblingExposed int
+	var alternativeRecall float64
+	workflowCases := 0
+	workflowComplete := 0
+	workflowRequiredRecall := 0.0
+	for _, item := range cases {
+		if err := ctx.Err(); err != nil {
+			return ToolSearchIndependentReport{}, err
+		}
+		response, searchErr := engine.Search(ctx, ToolSearchRequest{Query: item.Query, Limit: 5, CandidateLimit: 20})
+		if searchErr != nil {
+			return ToolSearchIndependentReport{}, fmt.Errorf("evaluate %s: %w", item.ID, searchErr)
+		}
+		overall.observe(response.Candidates, item.Qrels)
+		if slices[item.Language] == nil {
+			slices[item.Language] = &independentRankingAccumulator{}
+		}
+		slices[item.Language].observe(response.Candidates, item.Qrels)
+		if len(item.Forbidden) > 0 {
+			forbiddenCases++
+			if candidatesContainAny(response.Candidates, item.Forbidden) {
+				forbiddenExposed++
+			}
+			alternativeRecall += candidateSetRecall(response.Candidates, item.AlternativeGold)
+		}
+		if len(item.ConfusionFamily) > 0 {
+			siblingCases++
+			if candidatesContainAny(response.Candidates, item.ConfusionFamily) {
+				siblingExposed++
+			}
+		}
+		if item.Workflow != nil {
+			workflowCases++
+			workflowResponse := response
+			if len(item.Workflow.Subqueries) > 0 {
+				workflowResponse, searchErr = engine.SearchSubqueries(ctx, item.Workflow.Subqueries, ToolSearchRequest{Query: item.Query, Limit: 5, CandidateLimit: 20})
+				if searchErr != nil {
+					return ToolSearchIndependentReport{}, fmt.Errorf("evaluate workflow %s: %w", item.ID, searchErr)
+				}
+			}
+			recall := candidateSetRecall(workflowResponse.Candidates, item.Workflow.Required)
+			workflowRequiredRecall += recall
+			if recall == 1 {
+				workflowComplete++
+			}
+		}
+	}
+	report := ToolSearchIndependentReport{
+		Version: "tool-search-independent-evaluation.v1", Catalog: engine.catalogVersion(), Algorithm: engine.lexical.Name(),
+		Overall: overall.result(), LanguageSlices: map[string]ToolSearchIndependentRankingMetrics{},
+		Safety:   ToolSearchIndependentSafetyMetrics{ForbiddenCases: forbiddenCases, SiblingConfusionCases: siblingCases},
+		Workflow: ToolSearchWorkflowMetrics{Cases: workflowCases},
+	}
+	for name, accumulator := range slices {
+		report.LanguageSlices[name] = accumulator.result()
+	}
+	if forbiddenCases > 0 {
+		report.Safety.ForbiddenExposureAt5 = float64(forbiddenExposed) / float64(forbiddenCases)
+		report.Safety.AlternativeRecallAt5 = alternativeRecall / float64(forbiddenCases)
+	}
+	if siblingCases > 0 {
+		report.Safety.SiblingExposureAt5 = float64(siblingExposed) / float64(siblingCases)
+	}
+	if workflowCases > 0 {
+		report.Workflow.CompleteAt5 = float64(workflowComplete) / float64(workflowCases)
+		report.Workflow.RequiredRecallAt5 = workflowRequiredRecall / float64(workflowCases)
+	}
+	return report, nil
+}
+
+func pairedProductClusterRecallCI(ctx context.Context, candidate, control *ToolSearchEngine, cases []ToolSearchIndependentCase, iterations int, seed int64) (ToolSearchConfidenceInterval, error) {
+	clusters := map[string][]float64{}
+	for _, item := range cases {
+		candidateResponse, err := candidate.Search(ctx, ToolSearchRequest{Query: item.Query, Limit: 5, CandidateLimit: 20})
+		if err != nil {
+			return ToolSearchConfidenceInterval{}, err
+		}
+		controlResponse, err := control.Search(ctx, ToolSearchRequest{Query: item.Query, Limit: 5, CandidateLimit: 20})
+		if err != nil {
+			return ToolSearchConfidenceInterval{}, err
+		}
+		product := "unknown"
+		if len(item.Qrels) > 0 {
+			if split := strings.SplitN(item.Qrels[0].Canonical, ".", 2); len(split) > 0 {
+				product = split[0]
+			}
+		}
+		clusters[product] = append(clusters[product], candidateSetRecall(candidateResponse.Candidates, qrelCanonicals(item.Qrels))-candidateSetRecall(controlResponse.Candidates, qrelCanonicals(item.Qrels)))
+	}
+	clusterNames := make([]string, 0, len(clusters))
+	clusterMeans := map[string]float64{}
+	for name, values := range clusters {
+		clusterNames = append(clusterNames, name)
+		for _, value := range values {
+			clusterMeans[name] += value
+		}
+		clusterMeans[name] /= float64(len(values))
+	}
+	sort.Strings(clusterNames)
+	if len(clusterNames) == 0 || iterations <= 0 {
+		return ToolSearchConfidenceInterval{}, fmt.Errorf("paired product bootstrap requires cases and iterations")
+	}
+	random := rand.New(rand.NewSource(seed)) // #nosec G404 -- deterministic evaluation bootstrap
+	values := make([]float64, iterations)
+	for iteration := range values {
+		for sample := 0; sample < len(clusterNames); sample++ {
+			values[iteration] += clusterMeans[clusterNames[random.Intn(len(clusterNames))]]
+		}
+		values[iteration] /= float64(len(clusterNames))
+	}
+	sort.Float64s(values)
+	return ToolSearchConfidenceInterval{Lower: percentile(values, 0.025), Upper: percentile(values, 0.975)}, nil
+}
+
+func qrelCanonicals(qrels []ToolSearchIndependentQrel) []string {
+	values := make([]string, 0, len(qrels))
+	for _, qrel := range qrels {
+		values = append(values, qrel.Canonical)
+	}
+	return values
+}
+
+func (a *independentRankingAccumulator) observe(candidates []ToolReference, qrels []ToolSearchIndependentQrel) {
+	a.metrics.Cases++
+	if len(candidates) == 0 {
+		a.zero++
+	}
+	relevance := make(map[string]int, len(qrels))
+	ideal := make([]int, 0, len(qrels))
+	for _, qrel := range qrels {
+		relevance[qrel.Canonical] = qrel.Relevance
+		ideal = append(ideal, qrel.Relevance)
+	}
+	found := 0
+	first := 0
+	dcg := 0.0
+	for rank, candidate := range candidates {
+		if rank >= 5 {
+			break
+		}
+		rel := relevance[candidate.CanonicalPath]
+		if rel == 0 {
+			continue
+		}
+		found++
+		if first == 0 {
+			first = rank + 1
+		}
+		dcg += (math.Pow(2, float64(rel)) - 1) / math.Log2(float64(rank+2))
+	}
+	if len(candidates) > 0 && relevance[candidates[0].CanonicalPath] > 0 {
+		a.recall1 += 1 / float64(len(qrels))
+	}
+	if len(qrels) > 0 {
+		a.recall5 += float64(found) / float64(len(qrels))
+	}
+	if first > 0 {
+		a.mrr5 += 1 / float64(first)
+	}
+	sort.Sort(sort.Reverse(sort.IntSlice(ideal)))
+	idcg := 0.0
+	for rank, rel := range ideal {
+		if rank >= 5 {
+			break
+		}
+		idcg += (math.Pow(2, float64(rel)) - 1) / math.Log2(float64(rank+2))
+	}
+	if idcg > 0 {
+		a.ndcg5 += dcg / idcg
+	}
+}
+
+func (a *independentRankingAccumulator) result() ToolSearchIndependentRankingMetrics {
+	result := a.metrics
+	if result.Cases == 0 {
+		return result
+	}
+	denominator := float64(result.Cases)
+	result.RecallAt1 = a.recall1 / denominator
+	result.RecallAt5 = a.recall5 / denominator
+	result.MeanReciprocalRankAt5 = a.mrr5 / denominator
+	result.NDCGAt5 = a.ndcg5 / denominator
+	result.ZeroResultRate = float64(a.zero) / denominator
+	return result
+}
+
+func candidatesContainAny(candidates []ToolReference, paths []string) bool {
+	for _, candidate := range candidates {
+		if stringSliceContains(paths, candidate.CanonicalPath) {
+			return true
+		}
+	}
+	return false
+}
+
+func candidateSetRecall(candidates []ToolReference, required []string) float64 {
+	if len(required) == 0 {
+		return 0
+	}
+	found := 0
+	for _, canonical := range required {
+		for _, candidate := range candidates {
+			if candidate.CanonicalPath == canonical {
+				found++
+				break
+			}
+		}
+	}
+	return float64(found) / float64(len(required))
+}
@@ -0,0 +1,70 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package cli
+
+import (
+	"context"
+	"math"
+	"testing"
+)
+
+func TestEvaluateToolSearchIndependentScoresGradedSafetyAndWorkflow(t *testing.T) {
+	engine := newToolSearchTestEngine(t)
+	cases := []ToolSearchIndependentCase{
+		{
+			ID: "chat", Query: "给群里发送消息", Language: "chinese_only",
+			Qrels:     []ToolSearchIndependentQrel{{Canonical: "chat.send", Relevance: 3}},
+			Forbidden: []string{"doc.read"}, AlternativeGold: []string{"chat.send"},
+			ConfusionFamily: []string{"chat.read_status"},
+		},
+		{
+			ID: "workflow", Query: "发送消息并读取文档", Language: "chinese_only",
+			Qrels: []ToolSearchIndependentQrel{{Canonical: "chat.send", Relevance: 3}, {Canonical: "doc.read", Relevance: 2}},
+			Workflow: &ToolSearchIndependentWorkflow{
+				Subqueries: []string{"群聊发送消息", "读取在线文档"},
+				Required:   []string{"chat.send", "doc.read"},
+			},
+		},
+	}
+	report, err := EvaluateToolSearchIndependent(context.Background(), engine, cases)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.Version != "tool-search-independent-evaluation.v1" || report.Overall.Cases != 2 {
+		t.Fatalf("report = %#v", report)
+	}
+	if report.Overall.RecallAt5 != 1 || report.Overall.NDCGAt5 <= 0 || report.Overall.MeanReciprocalRankAt5 <= 0 {
+		t.Fatalf("ranking = %#v", report.Overall)
+	}
+	if report.Safety.ForbiddenCases != 1 || report.Safety.ForbiddenExposureAt5 != 0 || report.Safety.AlternativeRecallAt5 != 1 ||
+		report.Safety.SiblingConfusionCases != 1 || report.Safety.SiblingExposureAt5 != 1 {
+		t.Fatalf("safety = %#v", report.Safety)
+	}
+	if report.Workflow.Cases != 1 || report.Workflow.CompleteAt5 != 1 || report.Workflow.RequiredRecallAt5 != 1 {
+		t.Fatalf("workflow = %#v", report.Workflow)
+	}
+}
+
+func TestIndependentRankingMetricsUseGradedRankDiscounts(t *testing.T) {
+	accumulator := &independentRankingAccumulator{}
+	accumulator.observe([]ToolReference{
+		{CanonicalPath: "irrelevant"},
+		{CanonicalPath: "relevant.low"},
+	}, []ToolSearchIndependentQrel{
+		{Canonical: "relevant.high", Relevance: 3},
+		{Canonical: "relevant.low", Relevance: 2},
+	})
+	metrics := accumulator.result()
+	wantNDCG := (3 / math.Log2(3)) / (7 + 3/math.Log2(3))
+	if metrics.RecallAt1 != 0 || metrics.RecallAt5 != 0.5 || metrics.MeanReciprocalRankAt5 != 0.5 || math.Abs(metrics.NDCGAt5-wantNDCG) > 1e-12 || metrics.ZeroResultRate != 0 {
+		t.Fatalf("metrics = %#v, want R1=0 R5=.5 MRR5=.5 NDCG5=%.12f", metrics, wantNDCG)
+	}
+
+	zero := &independentRankingAccumulator{}
+	zero.observe(nil, []ToolSearchIndependentQrel{{Canonical: "relevant", Relevance: 3}})
+	zeroMetrics := zero.result()
+	if zeroMetrics.ZeroResultRate != 1 || zeroMetrics.RecallAt5 != 0 || zeroMetrics.NDCGAt5 != 0 {
+		t.Fatalf("zero metrics = %#v", zeroMetrics)
+	}
+}
@@ -0,0 +1,662 @@
+// 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 cli
+
+import (
+	"context"
+	"fmt"
+	"math"
+	"regexp"
+	"sort"
+	"strings"
+	"unicode/utf8"
+)
+
+const (
+	ToolSearchLexicalBM25       = "fielded_bm25_ensemble"
+	ToolSearchLexicalBM25Action = "fielded_bm25_action_v1"
+	ToolSearchLexicalTFIDF      = "fielded_tfidf_cosine"
+)
+
+// ToolSearchLexicalRequest contains a prefiltered Catalog domain. Hard
+// filtering occurs before scoring, so a retriever cannot spend its Top-K on
+// candidates that DWS is required to reject.
+type ToolSearchLexicalRequest struct {
+	Query                  string
+	CandidateLimit         int
+	EligibleCanonicalPaths []string
+}
+
+// LexicalHit is an internal ordering result, not a confidence probability.
+// Explain is populated only when the engine was built with Explain=true.
+type LexicalHit struct {
+	CanonicalPath string
+	Score         float64
+	MatchedFields []string
+	Explain       *ToolSearchScoreBreakdown
+}
+
+// LexicalRetriever is the zero-model local recall boundary. Implementations
+// must return a deterministic score-desc/canonical-asc order and omit zero
+// score documents.
+type LexicalRetriever interface {
+	Name() string
+	Retrieve(context.Context, ToolSearchLexicalRequest) ([]LexicalHit, error)
+}
+
+func newToolSearchLexicalRetriever(documents map[string]toolSearchDocument, config ToolSearchConfig) (LexicalRetriever, error) {
+	var retriever LexicalRetriever
+	switch config.LexicalAlgorithm {
+	case ToolSearchLexicalBM25Action:
+		retriever = newToolSearchActionRetriever(
+			newToolSearchBM25Retriever(documents, config.FieldWeights, config.BM25K1, config.BM25B, config.Explain),
+			documents,
+			config.Explain,
+		)
+	case ToolSearchLexicalBM25:
+		retriever = newToolSearchBM25Retriever(documents, config.FieldWeights, config.BM25K1, config.BM25B, config.Explain)
+	case ToolSearchLexicalTFIDF:
+		retriever = newToolSearchTFIDFRetriever(documents, config.FieldWeights, config.Explain)
+	default:
+		return nil, fmt.Errorf("unknown tool search lexical algorithm %q", config.LexicalAlgorithm)
+	}
+	return newToolSearchAvoidWhenRetriever(retriever, documents, config.Explain), nil
+}
+
+type toolSearchActionRetriever struct {
+	base      LexicalRetriever
+	documents map[string]toolSearchDocument
+	explain   bool
+}
+
+var toolSearchASCIIWordPattern = regexp.MustCompile(`[A-Za-z][A-Za-z0-9._-]*`)
+
+func newToolSearchActionRetriever(base LexicalRetriever, documents map[string]toolSearchDocument, explain bool) *toolSearchActionRetriever {
+	return &toolSearchActionRetriever{base: base, documents: documents, explain: explain}
+}
+
+func (*toolSearchActionRetriever) Name() string { return ToolSearchLexicalBM25Action }
+
+func (r *toolSearchActionRetriever) Retrieve(ctx context.Context, request ToolSearchLexicalRequest) ([]LexicalHit, error) {
+	deep := request
+	deep.CandidateLimit = len(request.EligibleCanonicalPaths)
+	hits, err := r.base.Retrieve(ctx, deep)
+	if err != nil {
+		return nil, err
+	}
+	query := classifyToolSearchQuery(request.Query)
+	if !query.hasSignal() || toolSearchHasUnclassifiedASCII(request.Query) {
+		return truncateAndSortLexicalHits(hits, request.CandidateLimit), nil
+	}
+	for index := range hits {
+		multiplier := toolSearchStructuredMultiplier(query, r.documents[hits[index].CanonicalPath].tool)
+		hits[index].Score *= multiplier
+		if r.explain && hits[index].Explain != nil {
+			hits[index].Explain.Multiplier = &multiplier
+			hits[index].Explain.Score = hits[index].Score
+			hits[index].Explain.QueryClass = newToolSearchExplainQueryClass(query)
+		}
+	}
+	return truncateAndSortLexicalHits(hits, request.CandidateLimit), nil
+}
+
+// toolSearchHasUnclassifiedASCII reports whether the query carries a technical
+// identifier (camelCase or separator-joined tokens such as openConversationId,
+// task_id, file-path) that the compact vocabularies cannot classify. Plain
+// English words no longer disable structured reranking: they match (or fail
+// to match) the vocabularies exactly like Chinese phrases do, so mixed and
+// English queries keep the effect/product/action/entity routing instead of
+// silently degrading to raw BM25.
+func toolSearchHasUnclassifiedASCII(query string) bool {
+	for _, token := range toolSearchASCIIWordPattern.FindAllString(query, -1) {
+		if len(token) < 4 {
+			continue
+		}
+		switch strings.ToLower(token) {
+		case "id", "ids", "url", "uri":
+			continue
+		}
+		if strings.ContainsAny(token, "._-") {
+			return true
+		}
+		// Only an internal uppercase transition (openConversationId) marks a
+		// technical identifier; a capitalized plain word ("Send") does not.
+		if internal := token[1:]; strings.ToLower(internal) != internal {
+			return true
+		}
+	}
+	return false
+}
+
+type toolSearchQueryClass struct {
+	actions  map[string]bool
+	products map[string]bool
+	entities map[string]bool
+	effect   string
+}
+
+func (q toolSearchQueryClass) hasSignal() bool {
+	return len(q.actions) > 0 || len(q.products) > 0 || len(q.entities) > 0 || q.effect != ""
+}
+
+type toolSearchTermClass struct {
+	name   string
+	query  []string
+	tool   []string
+	effect string
+}
+
+var toolSearchActionClasses = []toolSearchTermClass{
+	{name: "approve", query: []string{"同意", "批准", "审批通过", "approve"}, tool: []string{"approve"}},
+	{name: "reject", query: []string{"拒绝", "驳回", "reject"}, tool: []string{"reject"}},
+	{name: "upload", query: []string{"上传", "upload"}, tool: []string{"upload"}},
+	{name: "download", query: []string{"下载", "download"}, tool: []string{"download"}},
+	{name: "send", query: []string{"发送", "发给", "发消息", "通知", "投递", "send", "notify"}, tool: []string{"send", "notify"}},
+	{name: "search", query: []string{"搜索", "查找", "检索", "定位", "search", "find", "locate"}, tool: []string{"search", "find", "resolve"}},
+	{name: "list", query: []string{"列出", "列表", "浏览", "遍历", "list", "browse"}, tool: []string{"list", "all"}},
+	{name: "read", query: []string{"读取", "查看", "获取", "详情", "正文", "read", "fetch"}, tool: []string{"read", "get", "detail", "info", "query"}},
+	{name: "create", query: []string{"创建", "新建", "create"}, tool: []string{"create", "new"}},
+	{name: "add", query: []string{"添加", "追加", "增加", "授权", "授予", "add", "invite"}, tool: []string{"add", "grant", "invite"}},
+	{name: "update", query: []string{"更新", "修改", "编辑", "重命名", "调整", "update", "edit", "rename"}, tool: []string{"update", "edit", "rename", "set"}},
+	{name: "delete", query: []string{"删除", "移除", "清除", "delete", "remove"}, tool: []string{"delete", "remove", "clear"}},
+	{name: "complete", query: []string{"完成", "提交入库", "complete", "commit"}, tool: []string{"complete", "commit", "finish"}},
+	{name: "enable", query: []string{"启用", "开启", "enable"}, tool: []string{"enable"}},
+	{name: "disable", query: []string{"禁用", "停用", "关闭", "disable"}, tool: []string{"disable"}},
+}
+
+var toolSearchProductClasses = []toolSearchTermClass{
+	{name: "chat", query: []string{"群聊", "群消息", "会话", "单聊", "chat"}, tool: []string{"chat"}},
+	{name: "calendar", query: []string{"日程", "会议日历", "会议室", "calendar"}, tool: []string{"calendar"}},
+	{name: "drive", query: []string{"钉盘", "云盘", "drive"}, tool: []string{"drive"}},
+	{name: "wiki", query: []string{"知识库", "wiki"}, tool: []string{"wiki"}},
+	{name: "todo", query: []string{"待办", "todo"}, tool: []string{"todo"}},
+	{name: "minutes", query: []string{"听记", "会议纪要", "minutes"}, tool: []string{"minutes"}},
+	{name: "oa", query: []string{"审批", "oa", "approval"}, tool: []string{"oa"}},
+	{name: "mail", query: []string{"邮件", "邮箱", "草稿", "mail", "email"}, tool: []string{"mail"}},
+	{name: "sheet", query: []string{"电子表格", "工作表", "单元格", "sheet", "spreadsheet"}, tool: []string{"sheet"}},
+	{name: "doc", query: []string{"在线文字文档", "文档正文", "adoc", "doc", "document"}, tool: []string{"doc"}},
+}
+
+var toolSearchEntityClasses = []toolSearchTermClass{
+	{name: "task_id", query: []string{"任务 id", "任务id", "task id", "taskid"}, tool: []string{"任务 id", "任务id", "task id", "taskid"}},
+	{name: "task", query: []string{"任务", "task id", "taskid", "task"}, tool: []string{"任务", "task"}},
+	{name: "permission", query: []string{"权限", "授权", "协作者", "permission"}, tool: []string{"权限", "授权", "协作者", "permission"}},
+	{name: "content", query: []string{"正文", "文档内容", "content"}, tool: []string{"正文", "内容", "content"}},
+	{name: "status", query: []string{"状态", "已读", "status"}, tool: []string{"状态", "已读", "status"}},
+	{name: "draft", query: []string{"草稿", "draft"}, tool: []string{"草稿", "draft"}},
+	{name: "event", query: []string{"日程", "event"}, tool: []string{"日程", "event"}},
+	{name: "reminder", query: []string{"提醒", "reminder"}, tool: []string{"提醒", "reminder"}},
+	{name: "summary", query: []string{"摘要", "summary"}, tool: []string{"摘要", "summary"}},
+	{name: "sheet", query: []string{"工作表", "worksheet"}, tool: []string{"工作表", "sheet"}},
+	{name: "range", query: []string{"单元格范围", "区域", "range"}, tool: []string{"范围", "区域", "range"}},
+	{name: "group", query: []string{"群聊", "群名", "group"}, tool: []string{"群聊", "群", "group"}},
+}
+
+func classifyToolSearchQuery(query string) toolSearchQueryClass {
+	normalized := strings.ToLower(strings.TrimSpace(query))
+	result := toolSearchQueryClass{actions: map[string]bool{}, products: map[string]bool{}, entities: map[string]bool{}}
+	for _, class := range toolSearchActionClasses {
+		if containsAnyToolSearchPhrase(normalized, class.query) {
+			result.actions[class.name] = true
+		}
+	}
+	for _, class := range toolSearchProductClasses {
+		if containsAnyToolSearchPhrase(normalized, class.query) {
+			result.products[class.name] = true
+		}
+	}
+	for _, class := range toolSearchEntityClasses {
+		if class.name == "task" && result.entities["task_id"] {
+			continue
+		}
+		if containsAnyToolSearchPhrase(normalized, class.query) {
+			result.entities[class.name] = true
+		}
+	}
+	// “查询” is intentionally only a broad read-effect signal. Treating it as
+	// get/list/search would impose a false sibling preference.
+	if strings.Contains(normalized, "查询") || result.actions["read"] || result.actions["search"] || result.actions["list"] {
+		result.effect = "read"
+	}
+	return result
+}
+
+func toolSearchStructuredMultiplier(query toolSearchQueryClass, tool ToolSpec) float64 {
+	multiplier := 1.0
+	if query.effect != "" {
+		if tool.Safety.Effect == query.effect {
+			multiplier += 0.10
+		} else {
+			multiplier -= 0.50
+		}
+	}
+	if len(query.products) > 0 {
+		if query.products[tool.Identity.ProductID] {
+			multiplier += 0.50
+		} else {
+			multiplier -= 0.30
+		}
+	}
+	toolText := strings.ToLower(strings.Join([]string{
+		tool.Identity.Name,
+		tool.Identity.CLIName,
+		tool.Identity.CanonicalPath,
+		tool.Identity.PrimaryCLIPath,
+		tool.Title,
+		tool.Selection.AgentSummary,
+	}, " "))
+	if len(query.actions) > 0 {
+		matched := false
+		for _, class := range toolSearchActionClasses {
+			if query.actions[class.name] && containsAnyToolSearchWord(toolText, class.tool) {
+				matched = true
+				break
+			}
+		}
+		if matched {
+			multiplier += 0.60
+		} else {
+			// An explicit action is a stronger constraint than generic lexical
+			// overlap. Penalize tools that do not advertise that action even
+			// when their sibling verb is not in the compact action vocabulary.
+			multiplier -= 0.65
+		}
+	}
+	if len(query.entities) > 0 {
+		matched := false
+		for _, class := range toolSearchEntityClasses {
+			if query.entities[class.name] && containsAnyToolSearchPhrase(toolText, class.tool) {
+				matched = true
+				break
+			}
+		}
+		if matched {
+			multiplier += 0.35
+		} else {
+			multiplier -= 0.10
+		}
+	}
+	if multiplier < 0.20 {
+		return 0.20
+	}
+	return multiplier
+}
+
+func containsAnyToolSearchPhrase(text string, values []string) bool {
+	for _, value := range values {
+		if toolSearchPhraseContains(text, value) {
+			return true
+		}
+	}
+	return false
+}
+
+// toolSearchPhraseContains matches ASCII single-token values on word
+// boundaries so short English values such as "oa" cannot fire inside
+// unrelated words ("download" contains "oa"). Mixed-script or multi-word
+// values keep substring semantics, which is what Chinese phrases and values
+// like "task id" rely on.
+func toolSearchPhraseContains(text, value string) bool {
+	if value != "" && isAllToolSearchASCII(value) && !strings.ContainsAny(value, " \t") {
+		return containsToolSearchASCIIWord(text, value)
+	}
+	return strings.Contains(text, value)
+}
+
+func isAllToolSearchASCII(value string) bool {
+	for _, character := range value {
+		if character >= utf8.RuneSelf {
+			return false
+		}
+	}
+	return true
+}
+
+func containsToolSearchASCIIWord(text, word string) bool {
+	word = strings.ToLower(word)
+	for _, token := range toolSearchASCIIWordPattern.FindAllString(strings.ToLower(text), -1) {
+		if token == word {
+			return true
+		}
+	}
+	return false
+}
+
+func containsAnyToolSearchWord(text string, values []string) bool {
+	normalized := strings.NewReplacer(".", " ", "_", " ", "-", " ", "/", " ").Replace(text)
+	words := strings.Fields(normalized)
+	for _, value := range values {
+		for _, word := range words {
+			if word == value {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func newToolSearchExplainQueryClass(query toolSearchQueryClass) *ToolSearchExplainQueryClass {
+	return &ToolSearchExplainQueryClass{
+		Actions:  sortedToolSearchClassKeys(query.actions),
+		Products: sortedToolSearchClassKeys(query.products),
+		Entities: sortedToolSearchClassKeys(query.entities),
+		Effect:   query.effect,
+	}
+}
+
+func sortedToolSearchClassKeys(set map[string]bool) []string {
+	if len(set) == 0 {
+		return nil
+	}
+	keys := make([]string, 0, len(set))
+	for key := range set {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// toolSearchAvoidWhenPenalty is applied when a candidate's avoid_when prose
+// matches the query intent. It is a soft demotion, not an eligibility filter:
+// avoid_when is natural-language guidance (often "prefer X for that intent"),
+// so a lexical hit can be wrong and the tool must remain reachable.
+const toolSearchAvoidWhenPenalty = 0.20
+
+// toolSearchAvoidWhenShortcutNoise filters the boilerplate avoid_when that
+// every shortcut carries; it carries no intent signal. Kept lowercase because
+// phrases are compared in the lowercased domain.
+const toolSearchAvoidWhenShortcutNoise = "需要该 shortcut 未公开的底层参数"
+
+// toolSearchAvoidWhenPenaltyReason returns the matched avoid_when phrase, or
+// "" when the tool should not be demoted for this query. The only match shape
+// is the query containing the avoidance prose itself (the Forbidden@5
+// evaluation proxy). Intent-overlap matching was tried and rejected: a tool's
+// own avoid_when describes the same sibling scenario space as its use_when,
+// so "shares an action/entity with the phrase" demotes the gold answer.
+func toolSearchAvoidWhenPenaltyReason(query string, tool ToolSpec) string {
+	if len(tool.Selection.AvoidWhen) == 0 {
+		return ""
+	}
+	normalized := strings.ToLower(strings.TrimSpace(query))
+	if normalized == "" {
+		return ""
+	}
+	for _, phrase := range tool.Selection.AvoidWhen {
+		phrase = strings.ToLower(strings.TrimSpace(phrase))
+		if phrase == "" || strings.Contains(phrase, toolSearchAvoidWhenShortcutNoise) {
+			continue
+		}
+		if strings.Contains(normalized, phrase) {
+			return phrase
+		}
+	}
+	return ""
+}
+
+// toolSearchAvoidWhenRetriever demotes candidates whose avoid_when prose
+// matches the query intent. It wraps every lexical algorithm, including the
+// production ensemble default, so the Forbidden exposure guard is not tied to
+// action_v1.
+type toolSearchAvoidWhenRetriever struct {
+	base      LexicalRetriever
+	documents map[string]toolSearchDocument
+	explain   bool
+}
+
+func newToolSearchAvoidWhenRetriever(base LexicalRetriever, documents map[string]toolSearchDocument, explain bool) *toolSearchAvoidWhenRetriever {
+	return &toolSearchAvoidWhenRetriever{base: base, documents: documents, explain: explain}
+}
+
+func (r *toolSearchAvoidWhenRetriever) Name() string { return r.base.Name() }
+
+func (r *toolSearchAvoidWhenRetriever) Retrieve(ctx context.Context, request ToolSearchLexicalRequest) ([]LexicalHit, error) {
+	hits, err := r.base.Retrieve(ctx, request)
+	if err != nil {
+		return nil, err
+	}
+	penalized := false
+	for index := range hits {
+		reason := toolSearchAvoidWhenPenaltyReason(request.Query, r.documents[hits[index].CanonicalPath].tool)
+		if reason == "" {
+			continue
+		}
+		hits[index].Score *= toolSearchAvoidWhenPenalty
+		if r.explain && hits[index].Explain != nil {
+			hits[index].Explain.Score = hits[index].Score
+			hits[index].Explain.AvoidWhenPenalty = reason
+		}
+		penalized = true
+	}
+	if !penalized {
+		return hits, nil
+	}
+	return truncateAndSortLexicalHits(hits, request.CandidateLimit), nil
+}
+
+type toolSearchBM25Retriever struct {
+	fieldIndex map[toolSearchField]toolSearchBM25Index
+	weights    ToolSearchFieldWeights
+	explain    bool
+}
+
+func newToolSearchBM25Retriever(documents map[string]toolSearchDocument, weights ToolSearchFieldWeights, k1, b float64, explain bool) *toolSearchBM25Retriever {
+	fieldTerms := toolSearchFieldTerms(documents)
+	fieldIndex := make(map[toolSearchField]toolSearchBM25Index, len(toolSearchFieldOrder))
+	for _, field := range toolSearchFieldOrder {
+		fieldIndex[field] = newToolSearchBM25Index(fieldTerms[field], k1, b)
+	}
+	return &toolSearchBM25Retriever{fieldIndex: fieldIndex, weights: weights, explain: explain}
+}
+
+func (*toolSearchBM25Retriever) Name() string { return ToolSearchLexicalBM25 }
+
+func (r *toolSearchBM25Retriever) Retrieve(ctx context.Context, request ToolSearchLexicalRequest) ([]LexicalHit, error) {
+	queryTerms := orderedToolSearchQueryTerms(request.Query)
+	hits := make([]LexicalHit, 0, len(request.EligibleCanonicalPaths))
+	for _, canonical := range request.EligibleCanonicalPaths {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		contributions := make(map[toolSearchField]float64)
+		score := 0.0
+		for _, field := range toolSearchFieldOrder {
+			weight := toolSearchFieldWeight(r.weights, field)
+			if weight <= 0 {
+				continue
+			}
+			value := r.fieldIndex[field].score(canonical, queryTerms) * weight
+			if value > 0 {
+				contributions[field] = value
+				score += value
+			}
+		}
+		if score > 0 {
+			hit := LexicalHit{CanonicalPath: canonical, Score: score, MatchedFields: matchedToolSearchFields(contributions)}
+			if r.explain {
+				hit.Explain = newToolSearchBreakdown(score, contributions)
+			}
+			hits = append(hits, hit)
+		}
+	}
+	return truncateAndSortLexicalHits(hits, request.CandidateLimit), nil
+}
+
+type toolSearchTFIDFDocument struct {
+	weights map[string]float64
+	norm    float64
+}
+
+type toolSearchTFIDFIndex struct {
+	documents map[string]toolSearchTFIDFDocument
+	idf       map[string]float64
+}
+
+type toolSearchTFIDFRetriever struct {
+	fieldIndex map[toolSearchField]toolSearchTFIDFIndex
+	weights    ToolSearchFieldWeights
+	explain    bool
+}
+
+func newToolSearchTFIDFRetriever(documents map[string]toolSearchDocument, weights ToolSearchFieldWeights, explain bool) *toolSearchTFIDFRetriever {
+	fieldTerms := toolSearchFieldTerms(documents)
+	fieldIndex := make(map[toolSearchField]toolSearchTFIDFIndex, len(toolSearchFieldOrder))
+	for _, field := range toolSearchFieldOrder {
+		fieldIndex[field] = newToolSearchTFIDFIndex(fieldTerms[field])
+	}
+	return &toolSearchTFIDFRetriever{fieldIndex: fieldIndex, weights: weights, explain: explain}
+}
+
+func (*toolSearchTFIDFRetriever) Name() string { return ToolSearchLexicalTFIDF }
+
+func (r *toolSearchTFIDFRetriever) Retrieve(ctx context.Context, request ToolSearchLexicalRequest) ([]LexicalHit, error) {
+	queryFrequency := toolSearchTermFrequency(tokenizeToolSearchText(request.Query))
+	hits := make([]LexicalHit, 0, len(request.EligibleCanonicalPaths))
+	for _, canonical := range request.EligibleCanonicalPaths {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		contributions := make(map[toolSearchField]float64)
+		score := 0.0
+		for _, field := range toolSearchFieldOrder {
+			weight := toolSearchFieldWeight(r.weights, field)
+			if weight <= 0 {
+				continue
+			}
+			value := r.fieldIndex[field].score(canonical, queryFrequency) * weight
+			if value > 0 {
+				contributions[field] = value
+				score += value
+			}
+		}
+		if score > 0 {
+			hit := LexicalHit{CanonicalPath: canonical, Score: score, MatchedFields: matchedToolSearchFields(contributions)}
+			if r.explain {
+				hit.Explain = newToolSearchBreakdown(score, contributions)
+			}
+			hits = append(hits, hit)
+		}
+	}
+	return truncateAndSortLexicalHits(hits, request.CandidateLimit), nil
+}
+
+func toolSearchFieldTerms(documents map[string]toolSearchDocument) map[toolSearchField]map[string][]string {
+	fieldTerms := make(map[toolSearchField]map[string][]string, len(toolSearchFieldOrder))
+	for _, field := range toolSearchFieldOrder {
+		fieldTerms[field] = make(map[string][]string, len(documents))
+	}
+	for canonical, document := range documents {
+		for _, field := range toolSearchFieldOrder {
+			fieldTerms[field][canonical] = tokenizeToolSearchText(document.fields[field])
+		}
+	}
+	return fieldTerms
+}
+
+func orderedToolSearchQueryTerms(query string) []toolSearchQueryTerm {
+	frequency := toolSearchTermFrequency(tokenizeToolSearchText(query))
+	terms := make([]toolSearchQueryTerm, 0, len(frequency))
+	for term, count := range frequency {
+		terms = append(terms, toolSearchQueryTerm{term: term, count: count})
+	}
+	sort.Slice(terms, func(i, j int) bool { return terms[i].term < terms[j].term })
+	return terms
+}
+
+func toolSearchTermFrequency(tokens []string) map[string]int {
+	frequency := make(map[string]int, len(tokens))
+	for _, token := range tokens {
+		frequency[token]++
+	}
+	return frequency
+}
+
+func newToolSearchTFIDFIndex(documents map[string][]string) toolSearchTFIDFIndex {
+	index := toolSearchTFIDFIndex{documents: make(map[string]toolSearchTFIDFDocument, len(documents)), idf: map[string]float64{}}
+	documentFrequency := map[string]int{}
+	frequencies := make(map[string]map[string]int, len(documents))
+	for canonical, tokens := range documents {
+		frequency := toolSearchTermFrequency(tokens)
+		frequencies[canonical] = frequency
+		for term := range frequency {
+			documentFrequency[term]++
+		}
+	}
+	n := float64(len(documents))
+	for term, frequency := range documentFrequency {
+		index.idf[term] = math.Log((n+1)/(float64(frequency)+1)) + 1
+	}
+	for canonical, frequency := range frequencies {
+		weights := make(map[string]float64, len(frequency))
+		normSquared := 0.0
+		terms := make([]string, 0, len(frequency))
+		for term := range frequency {
+			terms = append(terms, term)
+		}
+		sort.Strings(terms)
+		for _, term := range terms {
+			count := frequency[term]
+			value := float64(count) * index.idf[term]
+			weights[term] = value
+			normSquared += value * value
+		}
+		index.documents[canonical] = toolSearchTFIDFDocument{weights: weights, norm: math.Sqrt(normSquared)}
+	}
+	return index
+}
+
+func (i toolSearchTFIDFIndex) score(canonical string, queryFrequency map[string]int) float64 {
+	document, ok := i.documents[canonical]
+	if !ok || document.norm == 0 {
+		return 0
+	}
+	terms := make([]string, 0, len(queryFrequency))
+	for term := range queryFrequency {
+		terms = append(terms, term)
+	}
+	sort.Strings(terms)
+	dot := 0.0
+	queryNormSquared := 0.0
+	for _, term := range terms {
+		idf, ok := i.idf[term]
+		if !ok {
+			continue
+		}
+		queryWeight := float64(queryFrequency[term]) * idf
+		queryNormSquared += queryWeight * queryWeight
+		dot += document.weights[term] * queryWeight
+	}
+	if queryNormSquared == 0 {
+		return 0
+	}
+	return dot / (document.norm * math.Sqrt(queryNormSquared))
+}
+
+// toolSearchScoreQuantum is the sort-key quantization grid. Go permits FMA
+// fusion on arm64 but not amd64, so the same ranking expression can differ in
+// the last ulp across architectures; ordering on the raw float would let that
+// ulp flip near-tied candidates past the canonical tie-break and break the
+// byte-determinism contract across CI (linux/amd64) and dev (macOS/arm64)
+// machines. Quantizing only the ordering key keeps same-architecture output
+// identical while making cross-architecture ordering agree; reported scores
+// (explain-only) are untouched.
+const toolSearchScoreQuantum = 1e9
+
+func quantizeToolSearchScore(score float64) float64 {
+	return math.Round(score*toolSearchScoreQuantum) / toolSearchScoreQuantum
+}
+
+func truncateAndSortLexicalHits(hits []LexicalHit, limit int) []LexicalHit {
+	sort.Slice(hits, func(i, j int) bool {
+		left, right := quantizeToolSearchScore(hits[i].Score), quantizeToolSearchScore(hits[j].Score)
+		if left != right {
+			return left > right
+		}
+		return hits[i].CanonicalPath < hits[j].CanonicalPath
+	})
+	if limit >= 0 && len(hits) > limit {
+		hits = hits[:limit]
+	}
+	return hits
+}
@@ -0,0 +1,249 @@
+// 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"
+	"context"
+	"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/cli"
+	"github.com/spf13/cobra"
+)
+
+type workflowFixture struct {
+	Version     int                                    `json:"version"`
+	Description string                                 `json:"description,omitempty"`
+	Cases       []cli.ToolSearchWorkflowEvaluationCase `json:"cases"`
+}
+
+type comparisonOutput struct {
+	Diagnostic      cli.ToolSearchDiagnosticComparison   `json:"diagnostic"`
+	Shadows         []cli.ToolSearchDiagnosticComparison `json:"shadows"`
+	AgentPlanningAB *cli.ToolSearchAgentPlanningABReport `json:"agent_planning_ab,omitempty"`
+	AgentAB         *cli.ToolSearchAgentABReport         `json:"agent_ab,omitempty"`
+	Independent     *cli.ToolSearchIndependentReport     `json:"independent,omitempty"`
+}
+
+type independentFixture struct {
+	Version     string                          `json:"version"`
+	State       string                          `json:"state"`
+	Description string                          `json:"description,omitempty"`
+	Cases       []cli.ToolSearchIndependentCase `json:"cases"`
+}
+
+func main() {
+	var workflowsPath string
+	var agentResultsPath string
+	var directPlansPath string
+	var searchPlansPath string
+	var agentModel string
+	var outputPath string
+	var independentQrelsPath string
+	flag.StringVar(&workflowsPath, "workflows", "scripts/testdata/tool_search_workflows.json", "reviewed diagnostic workflow fixture")
+	flag.StringVar(&agentResultsPath, "agent-results", "", "optional paired Agent A/B result JSON")
+	flag.StringVar(&directPlansPath, "agent-plans-direct", "", "optional direct_schema Agent planning output JSON")
+	flag.StringVar(&searchPlansPath, "agent-plans-search", "", "optional search_inspect Agent planning output JSON")
+	flag.StringVar(&agentModel, "agent-model", "", "model identifier for paired planning outputs")
+	flag.StringVar(&outputPath, "output", "", "output JSON path; stdout when empty")
+	flag.StringVar(&independentQrelsPath, "independent-qrels", "", "optional independently authored tool-search-qrels.v1 JSON")
+	flag.Parse()
+
+	// Runtime and CI use the same declaration-owned Catalog assembly. The
+	// comparison generator never reads or writes a repository Catalog JSON.
+	cli.RegisterSchemaSourceRoot(func() *cobra.Command { return app.NewSchemaSourceRootCommand() })
+
+	workflows, err := readWorkflows(workflowsPath)
+	if err != nil {
+		fatal(err)
+	}
+	diagnostic, err := cli.BuildDeliveryToolSearchDiagnosticComparison(context.Background(), workflows)
+	if err != nil {
+		fatal(err)
+	}
+	actionShadow, err := cli.BuildDeliveryToolSearchDiagnosticComparisonForAlgorithm(context.Background(), workflows, cli.ToolSearchLexicalBM25Action)
+	if err != nil {
+		fatal(err)
+	}
+	shadow, err := cli.BuildDeliveryToolSearchDiagnosticComparisonForAlgorithm(context.Background(), workflows, cli.ToolSearchLexicalTFIDF)
+	if err != nil {
+		fatal(err)
+	}
+	result := comparisonOutput{Diagnostic: diagnostic, Shadows: []cli.ToolSearchDiagnosticComparison{actionShadow, shadow}}
+	if independentQrelsPath != "" {
+		fixture, readErr := readIndependentQrels(independentQrelsPath)
+		if readErr != nil {
+			fatal(readErr)
+		}
+		independent, evaluationErr := cli.BuildDeliveryToolSearchIndependentEvaluation(context.Background(), fixture.Cases)
+		if evaluationErr != nil {
+			fatal(evaluationErr)
+		}
+		result.Independent = &independent
+	}
+	if directPlansPath != "" || searchPlansPath != "" || agentModel != "" {
+		if directPlansPath == "" || searchPlansPath == "" || agentModel == "" {
+			fatal(fmt.Errorf("-agent-plans-direct, -agent-plans-search and -agent-model must be provided together"))
+		}
+		directPlans, readErr := readAgentPlans(directPlansPath)
+		if readErr != nil {
+			fatal(readErr)
+		}
+		searchPlans, readErr := readAgentPlans(searchPlansPath)
+		if readErr != nil {
+			fatal(readErr)
+		}
+		planningReport, scoreErr := cli.ScoreToolSearchAgentPlanningAB(agentModel, workflows, directPlans, searchPlans)
+		if scoreErr != nil {
+			fatal(scoreErr)
+		}
+		result.AgentPlanningAB = &planningReport
+	}
+	if agentResultsPath != "" {
+		agentInput, readErr := readAgentResults(agentResultsPath)
+		if readErr != nil {
+			fatal(readErr)
+		}
+		if agentInput.Catalog != diagnostic.Catalog {
+			fatal(fmt.Errorf("Agent A/B Catalog hashes do not match the embedded binary"))
+		}
+		agentReport, aggregateErr := cli.AggregateToolSearchAgentAB(agentInput)
+		if aggregateErr != nil {
+			fatal(aggregateErr)
+		}
+		diagnostic.AgentABStatus = "completed"
+		result.Diagnostic = diagnostic
+		result.AgentAB = &agentReport
+	}
+	encoded, err := json.MarshalIndent(result, "", "  ")
+	if err != nil {
+		fatal(err)
+	}
+	encoded = append(encoded, '\n')
+	if outputPath == "" {
+		if _, err := os.Stdout.Write(encoded); err != nil {
+			fatal(err)
+		}
+		return
+	}
+	if err := writeAtomically(outputPath, encoded); err != nil {
+		fatal(err)
+	}
+}
+
+func readIndependentQrels(path string) (independentFixture, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return independentFixture{}, fmt.Errorf("read independent qrels: %w", err)
+	}
+	var fixture independentFixture
+	if err := decodeStrict(data, &fixture); err != nil {
+		return independentFixture{}, fmt.Errorf("decode independent qrels: %w", err)
+	}
+	if fixture.Version != "tool-search-qrels.v1" || len(fixture.Cases) == 0 {
+		return independentFixture{}, fmt.Errorf("independent qrels must be tool-search-qrels.v1 and non-empty")
+	}
+	return fixture, nil
+}
+
+func readWorkflows(path string) ([]cli.ToolSearchWorkflowEvaluationCase, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read workflows: %w", err)
+	}
+	var fixture workflowFixture
+	if err := decodeStrict(data, &fixture); err != nil {
+		return nil, fmt.Errorf("decode workflows: %w", err)
+	}
+	if fixture.Version != 1 || len(fixture.Cases) == 0 {
+		return nil, fmt.Errorf("workflow fixture must be version 1 and non-empty")
+	}
+	return fixture.Cases, nil
+}
+
+func readAgentResults(path string) (cli.ToolSearchAgentABInput, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return cli.ToolSearchAgentABInput{}, fmt.Errorf("read Agent A/B results: %w", err)
+	}
+	var input cli.ToolSearchAgentABInput
+	if err := decodeStrict(data, &input); err != nil {
+		return cli.ToolSearchAgentABInput{}, fmt.Errorf("decode Agent A/B results: %w", err)
+	}
+	return input, nil
+}
+
+func readAgentPlans(path string) (cli.ToolSearchAgentPlanOutput, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return cli.ToolSearchAgentPlanOutput{}, fmt.Errorf("read Agent plans: %w", err)
+	}
+	var output cli.ToolSearchAgentPlanOutput
+	if err := decodeStrict(data, &output); err != nil {
+		return cli.ToolSearchAgentPlanOutput{}, fmt.Errorf("decode Agent plans: %w", err)
+	}
+	return output, nil
+}
+
+func decodeStrict(data []byte, target any) error {
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(target); err != nil {
+		return err
+	}
+	var extra any
+	if err := decoder.Decode(&extra); err != io.EOF {
+		if err == nil {
+			return fmt.Errorf("multiple JSON values are not allowed")
+		}
+		return err
+	}
+	return nil
+}
+
+func writeAtomically(path string, data []byte) error {
+	directory := filepath.Dir(path)
+	if err := os.MkdirAll(directory, 0o755); err != nil {
+		return err
+	}
+	temporary, err := os.CreateTemp(directory, ".tool-search-comparison-*.tmp")
+	if err != nil {
+		return err
+	}
+	temporaryPath := temporary.Name()
+	defer os.Remove(temporaryPath)
+	if _, err := temporary.Write(data); err != nil {
+		temporary.Close()
+		return err
+	}
+	if err := temporary.Sync(); err != nil {
+		temporary.Close()
+		return err
+	}
+	if err := temporary.Close(); err != nil {
+		return err
+	}
+	return os.Rename(temporaryPath, path)
+}
+
+func fatal(err error) {
+	fmt.Fprintln(os.Stderr, err)
+	os.Exit(1)
+}
@@ -3,21 +3,18 @@ package helpers
 import (
 	"strings"

-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )

 // boolPtr returns a pointer to v, for ParamDecl.Required declarations.
 func boolPtr(v bool) *bool { return &v }

-// 这些是原有的宽松兜底名，不属于本次 Primary 迁移；保持原生 hidden
-// 注册，不给它们新增 alias_of/origin 元数据。
-var aisearchPersonGuessFlags = []string{"name", "q", "text"}
-
-// 历史解析优先级必须独立于新旧 Primary：双传时旧 --keyword 始终获胜。
-var aisearchQueryResolutionOrder = []string{"keyword", "name", "q", "query", "text"}
+// aisearchKeywordAliases 是 --keyword flag 的同义瞎猜兜底列表。
+// 模型可能写 --name / --q / --query / --text，这些都被识别为 keyword。
+var aisearchKeywordAliases = []string{"name", "q", "query", "text"}

 // flagValue 安全地读取 flag 值：先查 local，再查自身 PersistentFlags，
 // 再查 parents 的 PersistentFlags。比 cmd.Flags().GetString 更鲁棒，
@@ -61,11 +58,14 @@ func aisearchFlagOrDefault(cmd *cobra.Command, primary, def string, aliases ...s
 	return def
 }

-// resolveAisearchKeyword 按历史顺序解析人员搜索词。虽然公开 Primary 已改为
-// --query，但兼容期内显式旧 --keyword 的值仍优先。
+// resolveAisearchKeyword 从命令的 flag 中解析 keyword：优先 --keyword，
+// 否则 fallback 到 aisearchKeywordAliases 中的任一同义 flag。
 func resolveAisearchKeyword(cmd *cobra.Command) string {
-	for _, name := range aisearchQueryResolutionOrder {
-		if v := flagValue(cmd, name); v != "" {
+	if v := flagValue(cmd, "keyword"); v != "" {
+		return v
+	}
+	for _, alias := range aisearchKeywordAliases {
+		if v := flagValue(cmd, alias); v != "" {
 			return v
 		}
 	}
@@ -73,23 +73,9 @@ func resolveAisearchKeyword(cmd *cobra.Command) string {
 }

 func addAisearchPersonFlags(cmd *cobra.Command) {
-	// Alias evidence must be emitted by corecmd.FlagSpec.Aliases. Build the pair
-	// on a temporary declaration command so the legacy alias can retain its
-	// historical -w shorthand without extending the global alias mechanism or
-	// assigning that shorthand to the new --query Primary.
-	declaration := &cobra.Command{Use: "aisearch-query-flags"}
-	corecmd.RegisterFlags(declaration, []corecmd.FlagSpec{{
-		Name:    "query",
-		Usage:   "搜索关键词 (必填，如人名、技能关键词等)",
-		Aliases: []string{"keyword"},
-	}})
-	queryFlag := declaration.Flags().Lookup("query")
-	keywordFlag := declaration.Flags().Lookup("keyword")
-	keywordFlag.Shorthand = "w"
-	cmd.Flags().AddFlag(queryFlag)
-	cmd.Flags().AddFlag(keywordFlag)
+	cmd.Flags().StringP("keyword", "w", "", "搜索关键词 (必填，如人名、技能关键词等)")
 	cmd.Flags().StringP("dimension", "d", "all", "查询维度: all/name/department/position/duty/supervisor/subordinate/phone/jobNumber，多个用逗号分隔")
-	for _, alias := range aisearchPersonGuessFlags {
+	for _, alias := range aisearchKeywordAliases {
 		cmd.Flags().String(alias, "", "")
 		_ = cmd.Flags().MarkHidden(alias)
 	}
@@ -112,7 +98,8 @@ func runAisearchPerson(cmd *cobra.Command, _ []string) error {
 	}
 	keyword := resolveAisearchKeyword(cmd)
 	if keyword == "" {
-		return validateRequiredFlags(cmd, "query")
+		// 复用原有报错文案（"keyword is required"）
+		return validateRequiredFlags(cmd, "keyword")
 	}
 	dimensions := parseDimensions(flagValue(cmd, "dimension"))
 	return callMCPTool("enterprise_person_search", map[string]any{
@@ -201,8 +188,8 @@ func newAisearchCommand() *cobra.Command {
 		Use:   "aisearch",
 		Short: "AI 搜问",
 		Long:  `AI 搜问：搜索企业人员信息、企业内部知识内容与企业内部行为记录。`,
-		// 智能 root：模型常漏 person 子命令直接 dws aisearch --query xxx，
-		// 检测到 query 就自动等价于 person；否则退回 group help。
+		// 智能 root：模型常漏 person 子命令直接 dws aisearch --keyword xxx，
+		// 检测到 keyword 就自动等价于 person；否则退回 group help。
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if resolveAisearchKeyword(cmd) != "" {
 				return runAisearchPerson(cmd, args)
@@ -212,9 +199,9 @@ func newAisearchCommand() *cobra.Command {
 	}

 	// root 和 person 各自定义同一组本地 flag，这样：
-	//   - dws aisearch --query xxx           ← root 自己能解析
-	//   - dws aisearch person --query xxx    ← person 本地 flag
-	//   - dws aisearch search --query xxx    ← search 是 person 的 alias
+	//   - dws aisearch --keyword xxx           ← root 自己能解析
+	//   - dws aisearch person --keyword xxx    ← person 本地 flag
+	//   - dws aisearch search --keyword xxx    ← search 是 person 的 alias
 	// 不能放在 product PersistentFlags：否则 enterprise/behavior 会公开接受
 	// 它们不拥有的 person-only dimension，破坏 Help ↔ Schema 完整性。
 	addAisearchPersonFlags(root)
@@ -232,7 +219,7 @@ func newAisearchCommand() *cobra.Command {
 			"query", "people", "ask", "find", "lookup",
 			"contact",
 		},
-		// 显式声明允许任意位置参数：模型可能写 dws aisearch person search --query xxx，
+		// 显式声明允许任意位置参数：模型可能写 dws aisearch person search --keyword xxx，
 		// 此时 "search" 会作为 positional arg 被忽略，不报错。
 		Args:  cobra.ArbitraryArgs,
 		Short: "搜索企业人员",
@@ -250,13 +237,13 @@ func newAisearchCommand() *cobra.Command {
  jobNumber    工号

 多个维度用逗号分隔。`,
-		Example: `  dws aisearch person --query "张三" --dimension department
-  dws aisearch person --query "产品部" --dimension department
-  dws aisearch person --query "五道" --dimension supervisor
-  dws aisearch person --query "AI搜问" --dimension duty
-  dws aisearch person --query "李四" --dimension name,department
-  dws aisearch person --query "13800138000" --dimension phone
-  dws aisearch person --query "W12345" --dimension jobNumber`,
+		Example: `  dws aisearch person --keyword "张三" --dimension department
+  dws aisearch person --keyword "产品部" --dimension department
+  dws aisearch person --keyword "五道" --dimension supervisor
+  dws aisearch person --keyword "AI搜问" --dimension duty
+  dws aisearch person --keyword "李四" --dimension name,department
+  dws aisearch person --keyword "13800138000" --dimension phone
+  dws aisearch person --keyword "W12345" --dimension jobNumber`,
 		RunE: runAisearchPerson,
 	}
 	DeclareLeafMetadata(personCmd, LeafSpec{
@@ -290,13 +277,10 @@ func newAisearchCommand() *cobra.Command {
 					"搜企业知识内容时用 aisearch enterprise；搜行为记录时用 aisearch behavior",
 				},
 				Examples: []string{
-					"dws aisearch person --query \"张三\" --dimension name --format json",
-					"dws aisearch person --query \"五道\" --dimension supervisor --format json",
+					"dws aisearch person --keyword \"张三\" --dimension name --format json",
+					"dws aisearch person --keyword \"五道\" --dimension supervisor --format json",
 				},
 			},
-			Parameters: []contract.ParamDecl{
-				{Name: "query", Property: "keyword", Required: boolPtr(true)},
-			},
 		},
 	})
 	addAisearchPersonFlags(personCmd)
@@ -4,12 +4,7 @@

 package helpers

-import (
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
-)
+import "testing"

 func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 	root := newAisearchCommand()
@@ -17,34 +12,12 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	for _, name := range []string{"query", "dimension"} {
+	for _, name := range []string{"keyword", "dimension"} {
 		flag := person.Flags().Lookup(name)
 		if flag == nil || flag.Hidden {
 			t.Fatalf("person --%s = %#v, want visible local flag", name, flag)
 		}
 	}
-	if person.Flags().Lookup("query").Shorthand != "" {
-		t.Fatal("new Primary --query must not acquire a shorthand")
-	}
-	keyword := person.Flags().Lookup("keyword")
-	if keyword == nil || !keyword.Hidden || keyword.Shorthand != "w" {
-		t.Fatalf("person --keyword = %#v, want hidden legacy flag with -w", keyword)
-	}
-	if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != "query" {
-		t.Fatalf("person --keyword alias_of = %#v, want query", got)
-	}
-	if got := keyword.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
-		t.Fatalf("person --keyword alias_origin = %#v, want %q", got, runtimeannotate.FlagAliasOriginCorecmdV1)
-	}
-	for _, name := range []string{"name", "q", "text"} {
-		flag := person.Flags().Lookup(name)
-		if flag == nil || !flag.Hidden {
-			t.Fatalf("person --%s = %#v, want preserved hidden guess flag", name, flag)
-		}
-		if got := flag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 0 {
-			t.Fatalf("person --%s unexpectedly gained alias_of metadata: %#v", name, got)
-		}
-	}

 	for _, path := range []string{"enterprise", "behavior"} {
 		cmd, _, err := root.Find([]string{path})
@@ -62,38 +35,3 @@ func TestAisearchPersonFlagsDoNotLeakIntoContentCommands(t *testing.T) {
 		}
 	}
 }
-
-func TestAisearchPersonQueryPrimaryCompatibility(t *testing.T) {
-	tests := []struct {
-		name string
-		args []string
-		want string
-	}{
-		{name: "root new", args: []string{"--query", "new"}, want: "new"},
-		{name: "root old", args: []string{"--keyword", "old"}, want: "old"},
-		{name: "root old shorthand", args: []string{"-w", "old-short"}, want: "old-short"},
-		{name: "root both old wins", args: []string{"--query", "new", "--keyword", "old"}, want: "old"},
-		{name: "person new", args: []string{"person", "--query", "new"}, want: "new"},
-		{name: "person old", args: []string{"person", "--keyword", "old"}, want: "old"},
-		{name: "person old shorthand", args: []string{"person", "-w", "old-short"}, want: "old-short"},
-		{name: "person both old wins", args: []string{"person", "--query", "new", "--keyword", "old"}, want: "old"},
-	}
-	for _, tc := range tests {
-		t.Run(tc.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{}
-			installScriptedCaller(t, caller)
-			if err := executeFilterCoverage(t, newAisearchCommand(), tc.args...); err != nil {
-				t.Fatal(err)
-			}
-			if caller.tool != "enterprise_person_search" || caller.args["keyword"] != tc.want {
-				t.Fatalf("call = %s %#v, want backend keyword %q", caller.tool, caller.args, tc.want)
-			}
-		})
-	}
-
-	installScriptedCaller(t, &scriptedToolCaller{})
-	err := executeFilterCoverage(t, newAisearchCommand(), "person")
-	if err == nil || !strings.Contains(err.Error(), "--query") || strings.Contains(err.Error(), "--keyword") {
-		t.Fatalf("missing query error = %v, want only new Primary", err)
-	}
-}
@@ -520,102 +520,6 @@ func normalizeFilters(parsed any) any {
 	}
 }

-type aitableStatsItem struct {
-	FieldID   string `json:"fieldId"`
-	StatsType string `json:"statsType"`
-}
-
-func aitableStatsValidationf(format string, args ...any) error {
-	return apperrors.NewValidation(fmt.Sprintf(format, args...))
-}
-
-func parseAitableStatsItems(raw string, uppercase, uniqueFields bool, maxItems int) ([]map[string]any, error) {
-	var items []aitableStatsItem
-	if err := json.Unmarshal([]byte(raw), &items); err != nil {
-		return nil, aitableStatsValidationf("--stats 必须是 JSON 数组: %v", err)
-	}
-	var strictItems []aitableStatsItem
-	decoder := json.NewDecoder(strings.NewReader(raw))
-	decoder.DisallowUnknownFields()
-	if err := decoder.Decode(&strictItems); err != nil {
-		return nil, aitableStatsValidationf("--stats 包含不支持的字段: %v", err)
-	}
-	items = strictItems
-	if len(items) == 0 {
-		return nil, aitableStatsValidationf("--stats 至少需要一个统计项")
-	}
-	if maxItems > 0 && len(items) > maxItems {
-		return nil, aitableStatsValidationf("--stats 单次最多支持 %d 个统计项，got %d", maxItems, len(items))
-	}
-
-	seenFields := make(map[string]struct{}, len(items))
-	out := make([]map[string]any, 0, len(items))
-	for index, item := range items {
-		item.FieldID = strings.TrimSpace(item.FieldID)
-		item.StatsType = strings.TrimSpace(item.StatsType)
-		if item.FieldID == "" || item.StatsType == "" {
-			return nil, aitableStatsValidationf("--stats[%d] 的 fieldId 和 statsType 均不能为空", index)
-		}
-		if uniqueFields {
-			if _, exists := seenFields[item.FieldID]; exists {
-				return nil, aitableStatsValidationf("--stats 中 fieldId %q 重复；query_records_stats 要求同一字段的多个统计类型拆成多次调用", item.FieldID)
-			}
-			seenFields[item.FieldID] = struct{}{}
-		}
-		if uppercase && item.StatsType != strings.ToUpper(item.StatsType) {
-			return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用大写枚举值，got %q", index, item.StatsType)
-		}
-		if !uppercase && item.StatsType != strings.ToLower(item.StatsType) {
-			return nil, aitableStatsValidationf("--stats[%d].statsType 必须使用小写值，got %q", index, item.StatsType)
-		}
-		out = append(out, map[string]any{"fieldId": item.FieldID, "statsType": item.StatsType})
-	}
-	return out, nil
-}
-
-func parseAitableObjectFlag(name, raw string) (map[string]any, error) {
-	decoder := json.NewDecoder(strings.NewReader(raw))
-	decoder.UseNumber()
-	var value map[string]any
-	if err := decoder.Decode(&value); err != nil {
-		return nil, aitableStatsValidationf("--%s 必须是 JSON 对象: %v", name, err)
-	}
-	if value == nil {
-		return nil, aitableStatsValidationf("--%s 必须是 JSON 对象，不能是 null", name)
-	}
-	var trailing any
-	if err := decoder.Decode(&trailing); err != io.EOF {
-		if err == nil {
-			return nil, aitableStatsValidationf("--%s 只能包含一个 JSON 对象", name)
-		}
-		return nil, aitableStatsValidationf("--%s 包含无效的尾随内容: %v", name, err)
-	}
-	return value, nil
-}
-
-func validateAitableStatsFilters(value map[string]any, rawJSON string) error {
-	if err := validateFiltersStructure(value, rawJSON); err != nil {
-		return aitableStatsValidationf("%v", err)
-	}
-	return nil
-}
-
-func validateAitableArrayDSL(name, raw string) error {
-	var value []any
-	if err := json.Unmarshal([]byte(raw), &value); err != nil {
-		return aitableStatsValidationf("--%s 必须是 JSON 数组字符串: %v", name, err)
-	}
-	if len(value) == 0 {
-		return aitableStatsValidationf("--%s 至少需要一个条目", name)
-	}
-	for index, item := range value {
-		if _, ok := item.(map[string]any); !ok {
-			return aitableStatsValidationf("--%s[%d] 必须是 JSON 对象，got %T", name, index, item)
-		}
-	}
-	return nil
-}
-
 // normalizeViewConfigFilter 将 view config 中的 filter 字段规范化为服务端要求的数组格式。
 // 服务端 POJO 要求 config.filter 为 []FilterRule（JSON array）。
 // 常见错误格式：
@@ -791,29 +695,15 @@ const aitableMaxRetries = 3
 // callAitableTool 是 aitable 专用的 MCP 调用入口，带自动重试。
 // 替代直接调用 callMCPTool，对网络抖动和服务端瞬态错误进行透明重试。
 func callAitableTool(toolName string, args map[string]any) error {
-	return callAitableToolContext(context.Background(), toolName, args)
-}
-
-func callAitableToolContext(ctx context.Context, toolName string, args map[string]any) error {
-	if ctx == nil {
-		ctx = context.Background()
-	}
 	var lastErr error
 	for attempt := 0; attempt <= aitableMaxRetries; attempt++ {
-		if err := ctx.Err(); err != nil {
-			return err
-		}
 		if attempt > 0 {
 			backoff := time.Duration(1<<(attempt-1)) * time.Second // 1s, 2s, 4s
 			fmt.Fprintf(os.Stderr, "[aitable retry %d/%d] %s after %v...\n", attempt, aitableMaxRetries, toolName, backoff)
-			select {
-			case <-ctx.Done():
-				return ctx.Err()
-			case <-helperAfter(backoff):
-			}
+			helperSleep(backoff)
 		}

-		err := callMCPToolContext(ctx, toolName, args)
+		err := callMCPTool(toolName, args)
 		if err == nil {
 			return nil
 		}
@@ -1208,7 +1098,7 @@ func newAitableCommand() *cobra.Command {
  dws aitable base       [list|search|get|get-primary-doc-id|create|update|delete|copy]  Base 管理
  dws aitable table      [get|create|update|delete]                                     数据表管理
  dws aitable field      [get|create|update|delete|search-options]                      字段管理
-  dws aitable record     [query|stats|group-stats|create|update|delete]                 记录管理
+  dws aitable record     [query|create|update|delete]                                   记录管理
  dws aitable view       [get|create|update|delete]                                     视图管理
  dws aitable form       [list|delete|update]                                           表单管理
  dws aitable form field [list|update|hide]                                             表单字段管理
@@ -1891,7 +1781,7 @@ config 结构参考：
 			if v, _ := cmd.Flags().GetString("field-ids"); v != "" {
 				toolArgs["fieldIds"] = parseCSVValues(v)
 			}
-			return callAitableToolContext(cmd.Context(), "get_fields", toolArgs)
+			return callAitableTool("get_fields", toolArgs)
 		},
 	}
 	DeclareLeafMetadata(fieldGetCmd, LeafSpec{
@@ -2355,199 +2245,6 @@ newFieldName、config、aiConfig 至少传入一项。
 		},
 	})

-	recordStatsCmd := &cobra.Command{
-		Use:   "stats",
-		Short: "整表或过滤后的字段聚合统计",
-		Long: `对单张数据表执行不分组的服务端聚合，底层调用 query_records_stats。
-适用于记录计数、求和、平均值、最大值、最小值、中位数、去重数、完整率等标量统计。
-
--stats 是 JSON 数组，单次最多 20 项；每项必须包含 fieldId 和大写 statsType。
-同一个 fieldId 不能在一次请求中重复，如需对同一字段计算多个指标，请拆成多次调用。
-常用 statsType：COUNT、COUNT_COLUMN、SUM、AVG、MAX、MIN、MEDIAN、STANDARD_DEVIATION、RANGE、
-DISTINCT、DISTINCT_RATIO、EXISTS、UN_EXISTS、EXIST_RATIO、UN_EXIST_RATIO、CHECKED、UN_CHECKED、
-CHECKED_RATIO、UN_CHECKED_RATIO、LATEST_DATE、EARLIEST_DATE、DATE_RANGE、DATE_RANGE_MONTH。
-
-需要统计全部匹配记录时不要传 --limit；limit 会改变参与统计的记录范围。
-lt/gt/lte/gte 的过滤值必须使用 JSON 数字；单选/多选过滤建议使用 field get 返回的选项 ID。`,
-		Example: `  dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldAmount","statsType":"SUM"}]'
-  dws aitable record stats --base-id BASE_ID --table-id TABLE_ID --filters '{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}' --stats '[{"fieldId":"fldTitle","statsType":"COUNT"}]'`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil {
-				return err
-			}
-			baseID, err := mustFlagOrFallback(cmd, "base-id", "base")
-			if err != nil {
-				return err
-			}
-			stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), true, true, 20)
-			if err != nil {
-				return err
-			}
-			toolArgs := map[string]any{
-				"baseId":  baseID,
-				"tableId": mustGetFlag(cmd, "table-id"),
-				"stats":   stats,
-			}
-			if raw, _ := cmd.Flags().GetString("filters"); raw != "" {
-				filters, err := parseAitableObjectFlag("filters", raw)
-				if err != nil {
-					return err
-				}
-				if err := validateAitableStatsFilters(filters, raw); err != nil {
-					return err
-				}
-				toolArgs["filters"] = normalizeFilters(filters)
-			}
-			if raw, _ := cmd.Flags().GetString("sort"); raw != "" {
-				if err := validateAitableArrayDSL("sort", raw); err != nil {
-					return err
-				}
-				// query_records_stats 的 MCP Schema 将 sort 定义为 JSON 数组编码后的字符串，
-				// 与 query_records 使用的数组类型不同。
-				toolArgs["sort"] = raw
-			}
-			if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") {
-				if value <= 0 {
-					return aitableStatsValidationf("--limit 必须大于 0；统计全部匹配记录时请省略该参数")
-				}
-				toolArgs["limit"] = value
-			}
-			if value, _ := cmd.Flags().GetString("keyword"); value != "" {
-				toolArgs["keyword"] = value
-			}
-			if value, _ := cmd.Flags().GetString("search-field-ids"); value != "" {
-				toolArgs["searchFieldIds"] = parseCSVValues(value)
-			}
-			if value, _ := cmd.Flags().GetString("data-version"); value != "" {
-				toolArgs["dataVersion"] = value
-			}
-			return callAitableTool("query_records_stats", toolArgs)
-		},
-	}
-	DeclareLeafMetadata(recordStatsCmd, LeafSpec{
-		Safety: aitableSafetyRead(),
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "aitable",
-				Name:           "query_records_stats",
-				CanonicalPath:  "aitable.query_records_stats",
-				CLIPath:        "aitable record stats",
-				PrimaryCLIPath: "aitable record stats",
-			},
-			Description: "对整表或过滤后的记录执行不分组字段聚合。",
-			Interface:   aitableMCPInterface("query_records_stats"),
-			Selection: contract.SelectionSpec{
-				AgentSummary: "对整表或过滤后的记录执行不分组字段聚合。",
-				UseWhen:      []string{"需要记录总数、SUM/AVG/MAX/MIN、中位数、去重数、完整率等标量统计时，优先服务端聚合"},
-				AvoidWhen:    []string{"需要按字段分组或使用 query_stats 高级聚合时用 record group-stats；需要行级明细时用 record query"},
-				Examples:     []string{`dws aitable record stats --base-id <BASE_ID> --table-id <TABLE_ID> --stats '[{"fieldId":"<FIELD_ID>","statsType":"COUNT"}]'`},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "base-id", Property: "baseId", Required: boolPtr(true)},
-				{Name: "table-id", Property: "tableId", Required: boolPtr(true)},
-				{Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"},
-				{Name: "filters", Property: "filters", InterfaceType: "object"},
-				{Name: "search-field-ids", Property: "searchFieldIds", InterfaceType: "array"},
-				{Name: "data-version", Property: "dataVersion"},
-			},
-			Result: aitableRecordsStatsResultSpec(),
-		},
-	})
-
-	recordGroupStatsCmd := &cobra.Command{
-		Use:   "group-stats",
-		Short: "分组、去重及高级聚合统计",
-		Long: `对单张数据表执行分组或高级服务端聚合，底层调用 query_stats，最多返回 1000 个分组。
-适用于按一个或多个字段分组、条件唯一实体计数，以及 distinct、distinct_ratio 等高级统计。
-
--stats 是 JSON 数组，每项包含 fieldId 和小写 statsType。基础类型为 sum、avg、count、max、min；
-部分后端也支持 median、distinct、distinct_ratio 等高级类型，不支持时服务端会返回明确错误。
--group 是 JSON 数组编码后的字符串，不分组的 DISTINCT 标量统计可以省略。
-不要依赖服务端 limit 选择 Top N；应在不超过 1000 个分组时获取完整结果后再排序。`,
-		Example: `  dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --group '[{"fieldId":"fldCategory","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]' --stats '[{"fieldId":"fldAmount","statsType":"sum"}]'
-  dws aitable record group-stats --base-id BASE_ID --table-id TABLE_ID --stats '[{"fieldId":"fldStore","statsType":"distinct"}]'`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "table-id", "stats"); err != nil {
-				return err
-			}
-			baseID, err := mustFlagOrFallback(cmd, "base-id", "base")
-			if err != nil {
-				return err
-			}
-			stats, err := parseAitableStatsItems(mustGetFlag(cmd, "stats"), false, false, 0)
-			if err != nil {
-				return err
-			}
-			toolArgs := map[string]any{
-				"baseId":  baseID,
-				"tableId": mustGetFlag(cmd, "table-id"),
-				"stats":   stats,
-			}
-			if raw, _ := cmd.Flags().GetString("filters"); raw != "" {
-				filters, err := parseAitableObjectFlag("filters", raw)
-				if err != nil {
-					return err
-				}
-				if err := validateAitableStatsFilters(filters, raw); err != nil {
-					return err
-				}
-				toolArgs["filters"] = normalizeFilters(filters)
-			}
-			if raw, _ := cmd.Flags().GetString("group"); raw != "" {
-				if err := validateAitableArrayDSL("group", raw); err != nil {
-					return err
-				}
-				toolArgs["group"] = raw
-			}
-			if raw, _ := cmd.Flags().GetString("sort"); raw != "" {
-				if err := validateAitableArrayDSL("sort", raw); err != nil {
-					return err
-				}
-				toolArgs["sortDsl"] = raw
-			}
-			if value, _ := cmd.Flags().GetInt("limit"); cmd.Flags().Changed("limit") {
-				if value < 1 || value > 1000 {
-					return aitableStatsValidationf("--limit 必须在 [1, 1000] 范围内，got %d", value)
-				}
-				toolArgs["limit"] = value
-			}
-			if value, _ := cmd.Flags().GetString("data-version"); value != "" {
-				toolArgs["dataVersion"] = value
-			}
-			return callAitableTool("query_stats", toolArgs)
-		},
-	}
-	DeclareLeafMetadata(recordGroupStatsCmd, LeafSpec{
-		Safety: aitableSafetyRead(),
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "aitable",
-				Name:           "query_stats",
-				CanonicalPath:  "aitable.query_stats",
-				CLIPath:        "aitable record group-stats",
-				PrimaryCLIPath: "aitable record group-stats",
-			},
-			Description: "按字段分组，或执行去重等高级聚合统计。",
-			Interface:   aitableMCPInterface("query_stats"),
-			Selection: contract.SelectionSpec{
-				AgentSummary: "按字段分组，或执行去重等高级聚合统计。",
-				UseWhen:      []string{"需要各分类/实体的分组统计，或对满足条件的门店、客户、商品等执行 DISTINCT 唯一计数时"},
-				AvoidWhen:    []string{"普通不分组 COUNT/SUM/AVG/MAX/MIN 优先用 record stats；原始记录和 Top N 明细用 record query"},
-				Examples:     []string{`dws aitable record group-stats --base-id <BASE_ID> --table-id <TABLE_ID> --stats '[{"fieldId":"<FIELD_ID>","statsType":"distinct"}]'`},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "base-id", Property: "baseId", Required: boolPtr(true)},
-				{Name: "table-id", Property: "tableId", Required: boolPtr(true)},
-				{Name: "stats", Property: "stats", Required: boolPtr(true), InterfaceType: "array"},
-				{Name: "filters", Property: "filters", InterfaceType: "object"},
-				{Name: "group", Property: "group"},
-				{Name: "sort", Property: "sortDsl"},
-				{Name: "data-version", Property: "dataVersion"},
-			},
-			Result: aitableGroupedStatsResultSpec(),
-		},
-	})
-
 	recordCreateCmd := &cobra.Command{
 		Use:   "create",
 		Short: "新增记录",
@@ -7533,23 +7230,6 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	recordQueryCmd.Flags().Int("page-limit", 50, "自动翻页最大页数（仅 --all 时生效）。默认 50 页（约 5000 条）；设为 0 表示显式不限页数；超限时错误详情保留已取记录和续传 cursor")
 	recordQueryCmd.Flags().String("view-id", "", "视图 ID（record query 不支持按视图过滤，此参数会被忽略并给出提示）")
 	_ = recordQueryCmd.Flags().MarkHidden("view-id")
-	recordStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)")
-	recordStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)")
-	recordStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"SUM"}]；statsType 必须大写，最多 20 项且 fieldId 不得重复`)
-	recordStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字")
-	recordStatsCmd.Flags().String("sort", "", `参与统计记录的排序 DSL（JSON 数组字符串），例如 [{"fieldId":"fldDate","direction":"ASC"}]`)
-	recordStatsCmd.Flags().Int("limit", 0, "参与统计的最大记录数；省略表示统计全部匹配记录")
-	recordStatsCmd.Flags().String("keyword", "", "全文关键词，仅匹配的记录参与统计")
-	recordStatsCmd.Flags().String("search-field-ids", "", "关键词搜索字段 ID 列表，逗号分隔；仅 --keyword 非空时生效")
-	recordStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本")
-	recordGroupStatsCmd.Flags().String("base-id", "", "Base ID（通过 base get 确认目标）(必填)")
-	recordGroupStatsCmd.Flags().String("table-id", "", "Table ID（通过 table get 获取）(必填)")
-	recordGroupStatsCmd.Flags().String("stats", "", `统计项 JSON 数组（必填），例如 [{"fieldId":"fldAmount","statsType":"sum"}]；statsType 必须小写`)
-	recordGroupStatsCmd.Flags().String("filters", "", "结构化过滤条件 JSON 对象；数值比较值必须是 JSON 数字")
-	recordGroupStatsCmd.Flags().String("group", "", `分组字段 DSL（JSON 数组字符串）；不分组的 distinct 统计可省略`)
-	recordGroupStatsCmd.Flags().String("sort", "", "统计结果排序 DSL（JSON 数组字符串），映射到 MCP sortDsl")
-	recordGroupStatsCmd.Flags().Int("limit", 0, "返回的分组结果数，范围 1-1000；省略表示不额外限制")
-	recordGroupStatsCmd.Flags().String("data-version", "", "可选数据版本；通常省略以使用最新版本")
 	recordCreateCmd.Flags().String("base-id", "", "Base ID，可通过 base list 或 base search 获取 (必填)")
 	recordCreateCmd.Flags().String("table-id", "", "Table ID，可通过 base get 获取 (必填)")
 	recordCreateCmd.Flags().String("records", "", "待创建的记录列表 JSON 数组，单次最多 100 条 (必填)")
@@ -7614,7 +7294,7 @@ parentSectionId 为空串表示该节点在 Base 根目录下。
 	recordPrimaryDocCreateCmd.Flags().String("record-id", "", "目标 Record ID (必填)")

 	recordCmd.AddCommand(
-		recordQueryCmd, recordStatsCmd, recordGroupStatsCmd, recordCreateCmd,
+		recordQueryCmd, recordCreateCmd,
 		recordUpdateCmd, recordDeleteCmd,
 		recordBatchUpdateCmd,
 		recordHistoryListCmd,
@@ -9,7 +9,6 @@ import (
 	"testing"
 	"time"

-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )

@@ -19,22 +18,6 @@ type aitableCommandCoverageCaller struct {
 	response map[string]string
 }

-type aitableCommandContextKey struct{}
-
-type aitableCommandContextCaller struct {
-	value any
-}
-
-func (c *aitableCommandContextCaller) CallTool(ctx context.Context, _, _ string, _ map[string]any) (*edition.ToolResult, error) {
-	c.value = ctx.Value(aitableCommandContextKey{})
-	return nil, context.Canceled
-}
-
-func (*aitableCommandContextCaller) Format() string { return "json" }
-func (*aitableCommandContextCaller) DryRun() bool   { return false }
-func (*aitableCommandContextCaller) Fields() string { return "" }
-func (*aitableCommandContextCaller) JQ() string     { return "" }
-
 func (c *aitableCommandCoverageCaller) CallTool(_ context.Context, _, tool string, _ map[string]any) (*edition.ToolResult, error) {
 	if c.err != nil {
 		return nil, c.err
@@ -84,11 +67,6 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T
 	oldDeps, oldSleep := deps, helperSleep
 	t.Cleanup(func() { deps, helperSleep = oldDeps, oldSleep })
 	helperSleep = func(time.Duration) {}
-	testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time {
-		ready := make(chan time.Time, 1)
-		ready <- time.Time{}
-		return ready
-	})

 	retryable := fmt.Errorf("timeout: retryable: true")
 	caller := &aitableTestCaller{errors: []error{retryable, retryable, retryable, retryable}}
@@ -108,48 +86,6 @@ func TestCrossPlatformCoverageAitableRetryWrappersExhaustAndRecover(t *testing.T
 	if err := callAitableHelperTool("retry", nil); err == nil {
 		t.Fatal("exhausted helper retries returned nil")
 	}
-
-	caller = &aitableTestCaller{}
-	installAitableDeps(t, caller)
-	if err := callAitableToolContext(nil, "nil-context", nil); err != nil {
-		t.Fatalf("nil context was not normalized: %v", err)
-	}
-
-	caller = &aitableTestCaller{errors: []error{retryable}}
-	installAitableDeps(t, caller)
-	ctx, cancel := context.WithCancel(context.Background())
-	backoffPending := make(chan time.Time)
-	testseam.Swap(t, &helperAfter, func(time.Duration) <-chan time.Time {
-		cancel()
-		return backoffPending
-	})
-	if err := callAitableToolContext(ctx, "cancel-during-backoff", nil); err != context.Canceled {
-		t.Fatalf("cancel during retry backoff = %v, want %v", err, context.Canceled)
-	}
-}
-
-func TestCrossPlatformCoverageAitableFieldListPreservesCommandContext(t *testing.T) {
-	old := deps
-	t.Cleanup(func() { deps = old })
-	caller := &aitableCommandContextCaller{}
-	InitDeps(caller)
-	deps.Out.w = io.Discard
-	deps.Out.errW = io.Discard
-
-	root := newAitableCommand()
-	installExampleGlobalFlags(root)
-	root.SilenceErrors = true
-	root.SilenceUsage = true
-	root.SetOut(io.Discard)
-	root.SetErr(io.Discard)
-	root.SetArgs([]string{"field", "list", "--base-id=b", "--table-id=t"})
-	ctx := context.WithValue(context.Background(), aitableCommandContextKey{}, "field-list-context")
-	if err := root.ExecuteContext(ctx); err == nil {
-		t.Fatal("field list context probe unexpectedly succeeded")
-	}
-	if caller.value != "field-list-context" {
-		t.Fatalf("field list caller context value = %#v", caller.value)
-	}
 }

 func TestCrossPlatformCoverageAitableCommandValidationEdges(t *testing.T) {
@@ -14,8 +14,6 @@
 package helpers

 import (
-	"encoding/json"
-
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )

@@ -74,102 +72,3 @@ func aitableCompositeInterface(reason string) *contract.InterfaceSpec {
 		Reason:       reason,
 	}
 }
-
-func aitableRecordsStatsResultSpec() *contract.ResultSpec {
-	return &contract.ResultSpec{
-		Outcomes: []contract.ResultOutcome{
-			contract.ResultOutcomeSuccess,
-			contract.ResultOutcomeFailure,
-		},
-		DataSchema: json.RawMessage(`{
-  "type":"object",
-  "description":"不分组的字段聚合结果",
-  "properties":{
-    "results":{
-      "type":"array",
-      "description":"按数据版本返回的聚合结果批次",
-      "items":{
-        "type":"object",
-        "properties":{
-          "dataVersion":{"description":"参与统计的数据版本"},
-          "deltaVersion":{"description":"聚合结果的增量版本"},
-          "results":{
-            "type":"array",
-            "description":"请求中各统计项的结果",
-            "items":{
-              "type":"object",
-              "properties":{
-                "fieldId":{"type":"string","description":"被统计的字段 ID"},
-                "statsType":{"type":"string","description":"实际执行的统计类型"},
-                "value":{"description":"统计值；具体 JSON 类型取决于统计类型和字段类型"}
-              },
-              "required":["fieldId","statsType","value"],
-              "additionalProperties":true
-            }
-          }
-        },
-        "required":["results"],
-        "additionalProperties":true
-      }
-    }
-  },
-  "required":["results"],
-  "additionalProperties":true
-}`),
-	}
-}
-
-func aitableGroupedStatsResultSpec() *contract.ResultSpec {
-	return &contract.ResultSpec{
-		Outcomes: []contract.ResultOutcome{
-			contract.ResultOutcomeSuccess,
-			contract.ResultOutcomeFailure,
-		},
-		DataSchema: json.RawMessage(`{
-  "type":"object",
-  "description":"分组或高级字段聚合结果",
-  "properties":{
-    "dataVersion":{"description":"参与统计的数据版本"},
-    "results":{
-      "type":"array",
-      "description":"每个分组一条结果；未分组时通常只有一条",
-      "items":{
-        "type":"object",
-        "properties":{
-          "groupKeys":{
-            "type":"array",
-            "description":"当前结果的分组键",
-            "items":{
-              "type":"object",
-              "properties":{
-                "fieldId":{"type":"string","description":"分组字段 ID"},
-                "value":{"description":"分组值；编码取决于字段类型"},
-                "recordCount":{"type":"integer","description":"该分组包含的记录数"}
-              },
-              "additionalProperties":true
-            }
-          },
-          "fieldStatsMap":{
-            "type":"object",
-            "description":"按字段 ID 索引的聚合值",
-            "additionalProperties":{
-              "type":"object",
-              "properties":{
-                "action":{"type":"string","description":"实际执行的统计动作"},
-                "value":{"description":"统计值；具体 JSON 类型取决于统计动作和字段类型"}
-              },
-              "required":["action","value"],
-              "additionalProperties":true
-            }
-          }
-        },
-        "required":["fieldStatsMap"],
-        "additionalProperties":true
-      }
-    }
-  },
-  "required":["results"],
-  "additionalProperties":true
-}`),
-	}
-}
@@ -1,278 +0,0 @@
-// Copyright 2026 Alibaba Group
-// SPDX-License-Identifier: Apache-2.0
-
-package helpers
-
-import (
-	"encoding/json"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
-	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
-)
-
-func runAitableStatsCLI(t *testing.T, args ...string) (*aitableTestCaller, error) {
-	t.Helper()
-	caller := &aitableTestCaller{}
-	installAitableDeps(t, caller)
-	command := newAitableCommand()
-	command.SilenceErrors = true
-	command.SilenceUsage = true
-	command.SetArgs(args)
-	return caller, command.Execute()
-}
-
-func TestCrossPlatformCoverageAitableRecordsStatsForwardsValidatedContract(t *testing.T) {
-	caller, err := runAitableStatsCLI(t,
-		"record", "stats",
-		"--base-id", "base-stats",
-		"--table-id", "table-stats",
-		"--stats", `[{"fieldId":"fldCount","statsType":"COUNT"},{"fieldId":"fldAmount","statsType":"SUM"}]`,
-		"--filters", `{"operator":"and","operands":[{"operator":"gt","operands":["fldAmount",0]}]}`,
-		"--sort", `[{"fieldId":"fldAmount","direction":"DESC"}]`,
-		"--limit", "500",
-		"--keyword", "华东",
-		"--search-field-ids", "fldName,fldRegion",
-		"--data-version", "42",
-	)
-	if err != nil {
-		t.Fatalf("record stats returned error: %v", err)
-	}
-	if len(caller.calls) != 1 {
-		t.Fatalf("tool calls = %d, want 1", len(caller.calls))
-	}
-	call := caller.calls[0]
-	if call.server != "aitable" || call.tool != "query_records_stats" {
-		t.Fatalf("tool = %s/%s, want aitable/query_records_stats", call.server, call.tool)
-	}
-	wantStats := []map[string]any{
-		{"fieldId": "fldCount", "statsType": "COUNT"},
-		{"fieldId": "fldAmount", "statsType": "SUM"},
-	}
-	if !reflect.DeepEqual(call.args["stats"], wantStats) {
-		t.Fatalf("stats = %#v, want %#v", call.args["stats"], wantStats)
-	}
-	filters := call.args["filters"].(map[string]any)
-	condition := filters["operands"].([]any)[0].(map[string]any)
-	if got := condition["operands"].([]any)[1]; got != json.Number("0") {
-		t.Fatalf("numeric filter value = %#v (%T), want json.Number(0)", got, got)
-	}
-	if call.args["sort"] != `[{"fieldId":"fldAmount","direction":"DESC"}]` ||
-		call.args["limit"] != 500 || call.args["keyword"] != "华东" || call.args["dataVersion"] != "42" {
-		t.Fatalf("forwarded args = %#v", call.args)
-	}
-	if !reflect.DeepEqual(call.args["searchFieldIds"], []string{"fldName", "fldRegion"}) {
-		t.Fatalf("searchFieldIds = %#v", call.args["searchFieldIds"])
-	}
-}
-
-func TestCrossPlatformCoverageAitableGroupStatsForwardsStringDSL(t *testing.T) {
-	group := `[{"fieldId":"fldRegion","direction":"ASC","fieldConfig":null,"arraySplitMode":true}]`
-	sortDSL := `[{"fieldId":"fldAmount","direction":"DESC"}]`
-	caller, err := runAitableStatsCLI(t,
-		"record", "group-stats",
-		"--base-id", "base-stats",
-		"--table-id", "table-stats",
-		"--stats", `[{"fieldId":"fldStore","statsType":"distinct"},{"fieldId":"fldAmount","statsType":"avg"}]`,
-		"--filters", `{"operator":"OR","operands":[{"operator":"not_before","operands":["fldDate","2026-01-01"]}]}`,
-		"--group", group,
-		"--sort", sortDSL,
-		"--limit", "1000",
-		"--data-version", "43",
-	)
-	if err != nil {
-		t.Fatalf("record group-stats returned error: %v", err)
-	}
-	if len(caller.calls) != 1 {
-		t.Fatalf("tool calls = %d, want 1", len(caller.calls))
-	}
-	call := caller.calls[0]
-	if call.server != "aitable" || call.tool != "query_stats" {
-		t.Fatalf("tool = %s/%s, want aitable/query_stats", call.server, call.tool)
-	}
-	if call.args["group"] != group || call.args["sortDsl"] != sortDSL || call.args["limit"] != 1000 || call.args["dataVersion"] != "43" {
-		t.Fatalf("forwarded args = %#v", call.args)
-	}
-	stats := call.args["stats"].([]map[string]any)
-	if len(stats) != 2 || stats[0]["statsType"] != "distinct" || stats[1]["statsType"] != "avg" {
-		t.Fatalf("stats = %#v", stats)
-	}
-}
-
-func TestCrossPlatformCoverageAitableStatsRejectsInvalidInputsBeforeCallingMCP(t *testing.T) {
-	tests := []struct {
-		name    string
-		args    []string
-		wantErr string
-	}{
-		{
-			name:    "records stats require uppercase",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`},
-			wantErr: "大写",
-		},
-		{
-			name:    "records stats require at least one item",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[]`},
-			wantErr: "至少需要一个统计项",
-		},
-		{
-			name: "records stats enforce item cap",
-			args: []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[
-				{"fieldId":"f01","statsType":"COUNT"},{"fieldId":"f02","statsType":"COUNT"},
-				{"fieldId":"f03","statsType":"COUNT"},{"fieldId":"f04","statsType":"COUNT"},
-				{"fieldId":"f05","statsType":"COUNT"},{"fieldId":"f06","statsType":"COUNT"},
-				{"fieldId":"f07","statsType":"COUNT"},{"fieldId":"f08","statsType":"COUNT"},
-				{"fieldId":"f09","statsType":"COUNT"},{"fieldId":"f10","statsType":"COUNT"},
-				{"fieldId":"f11","statsType":"COUNT"},{"fieldId":"f12","statsType":"COUNT"},
-				{"fieldId":"f13","statsType":"COUNT"},{"fieldId":"f14","statsType":"COUNT"},
-				{"fieldId":"f15","statsType":"COUNT"},{"fieldId":"f16","statsType":"COUNT"},
-				{"fieldId":"f17","statsType":"COUNT"},{"fieldId":"f18","statsType":"COUNT"},
-				{"fieldId":"f19","statsType":"COUNT"},{"fieldId":"f20","statsType":"COUNT"},
-				{"fieldId":"f21","statsType":"COUNT"}
-			]`},
-			wantErr: "单次最多支持 20 个统计项",
-		},
-		{
-			name:    "records stats require item fields",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":" ","statsType":"COUNT"}]`},
-			wantErr: "均不能为空",
-		},
-		{
-			name:    "records stats reject unknown item fields",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT","unknownKey":123}]`},
-			wantErr: "不支持的字段",
-		},
-		{
-			name:    "records stats reject duplicate field",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"},{"fieldId":"f","statsType":"SUM"}]`},
-			wantErr: "重复",
-		},
-		{
-			name:    "group stats require lowercase",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`},
-			wantErr: "小写",
-		},
-		{
-			name:    "group must be array DSL",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--group", `{}`},
-			wantErr: "JSON 数组",
-		},
-		{
-			name:    "group limit capped",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--limit", "1001"},
-			wantErr: "[1, 1000]",
-		},
-		{
-			name:    "filters require logical root",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"eq","operands":[]}`},
-			wantErr: `root "operator" must be "and" or "or"`,
-		},
-		{
-			name:    "records filters reject malformed JSON",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{`},
-			wantErr: "必须是 JSON 对象",
-		},
-		{
-			name:    "records filters reject null",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `null`},
-			wantErr: "不能是 null",
-		},
-		{
-			name:    "records filters reject a second JSON value",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} {}`},
-			wantErr: "只能包含一个 JSON 对象",
-		},
-		{
-			name:    "records filters reject invalid trailing content",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{} trailing`},
-			wantErr: "无效的尾随内容",
-		},
-		{
-			name:    "records filters require operand array",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":{}}`},
-			wantErr: `"operands" must be an array`,
-		},
-		{
-			name:    "records filters reject silently unsupported operators",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`},
-			wantErr: `unsupported filter operator "date_between"`,
-		},
-		{
-			name:    "records sort requires an item",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[]`},
-			wantErr: "至少需要一个条目",
-		},
-		{
-			name:    "records sort items must be objects",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--sort", `[1]`},
-			wantErr: "必须是 JSON 对象",
-		},
-		{
-			name:    "records limit must be positive",
-			args:    []string{"record", "stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"COUNT"}]`, "--limit", "0"},
-			wantErr: "必须大于 0",
-		},
-		{
-			name:    "group filters reject malformed JSON",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{`},
-			wantErr: "必须是 JSON 对象",
-		},
-		{
-			name:    "group filters require logical root",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"eq","operands":[]}`},
-			wantErr: `root "operator" must be "and" or "or"`,
-		},
-		{
-			name:    "group filters reject silently unsupported operators",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--filters", `{"operator":"and","operands":[{"operator":"date_between","operands":["fldDate",[1,2]]}]}`},
-			wantErr: `unsupported filter operator "date_between"`,
-		},
-		{
-			name:    "group sort rejects invalid DSL",
-			args:    []string{"record", "group-stats", "--base-id", "b", "--table-id", "t", "--stats", `[{"fieldId":"f","statsType":"count"}]`, "--sort", `{}`},
-			wantErr: "JSON 数组",
-		},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller, err := runAitableStatsCLI(t, test.args...)
-			if err == nil || !strings.Contains(err.Error(), test.wantErr) {
-				t.Fatalf("error = %v, want containing %q", err, test.wantErr)
-			}
-			var structured *apperrors.Error
-			if !errors.As(err, &structured) || structured.Category != apperrors.CategoryValidation {
-				t.Fatalf("error = %#v, want structured validation error", err)
-			}
-			if len(caller.calls) != 0 {
-				t.Fatalf("tool calls = %d, want 0", len(caller.calls))
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageAitableStatsPublishInterfaceAndResultContracts(t *testing.T) {
-	root := newAitableCommand()
-	tests := []struct {
-		path string
-		rpc  string
-	}{
-		{path: "aitable record stats", rpc: "query_records_stats"},
-		{path: "aitable record group-stats", rpc: "query_stats"},
-	}
-	for _, test := range tests {
-		leaf := findCLIPath(root, test.path)
-		if leaf == nil {
-			t.Fatalf("missing leaf %q", test.path)
-		}
-		final, ok := contractfinal.RuntimeContractFinal(leaf)
-		if !ok || final.Interface == nil || final.Interface.Ref == nil || final.Interface.Ref.RPCName != test.rpc {
-			t.Fatalf("%s interface = %#v", test.path, final.Interface)
-		}
-		if final.Result == nil || len(final.Result.Outcomes) == 0 || len(final.Result.DataSchema) == 0 {
-			t.Fatalf("%s result = %#v", test.path, final.Result)
-		}
-	}
-}
@@ -19,28 +19,14 @@ import (

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 	"github.com/spf13/cobra"
-)

-// promoteLegacyChatString copies an explicitly supplied legacy flag into the
-// new canonical flag. Cobra validates MarkFlagRequired after PreRunE, and the
-// overwrite also preserves the migration rule that a legacy value wins when
-// both spellings are present.
-func promoteLegacyChatString(cmd *cobra.Command, canonical, legacy string) error {
-	if !cmd.Flags().Changed(legacy) {
-		return nil
-	}
-	value, err := cmd.Flags().GetString(legacy)
-	if err != nil {
-		return err
-	}
-	return cmd.Flags().Set(canonical, value)
-}
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+)

 func callProjectedChatMessages(cmd *cobra.Command, toolName string, args map[string]any, search bool) error {
 	if deps.Caller.DryRun() {
@@ -3158,7 +3144,7 @@ func newChatCommand() *cobra.Command {
  --open-dingtalk-id   单聊接收人 openDingTalkId

 纯文本 / Markdown 消息（默认）：
-  无需指定 --msg-type，直接传消息内容即可。推荐使用 --content flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。
+  无需指定 --msg-type，直接传消息内容即可。推荐使用 --text flag 传递内容（尤其当内容含换行、引号等特殊字符时），也支持位置参数。可选 --title 作为消息标题。
  图文混排时，公网图片 URL 需要写成 Markdown 图片语法：![图片标题](https://example.com/image.png)，才会以内联图片展示。
  如果省略开头的 !，例如 [图片标题](https://example.com/image.png)，将按链接/URL 展示，不会渲染为图片。

@@ -3168,24 +3154,24 @@ func newChatCommand() *cobra.Command {
  获取 openMessageId 和 openConversationId，无需再按消息内容反查。

 本地图片 / 文件消息：
-  统一使用 --msg-type file --file <本地路径>。CLI 会完成上传并按 file 消息发送；
+  统一使用 --msg-type file --file-path <本地路径>。CLI 会完成上传并按 file 消息发送；
  .png/.jpg 也会显示为可下载的文件附件，不会生成 mediaId 或渲染成内联图片。

 旧版内联图片消息：
  仅当上游已经提供有效 mediaId 时，使用 --msg-type image --media-id。
  当前 CLI 不提供本地文件到 mediaId 的上传能力。`,
-		Example: `  dws chat message send --conversation-id <openconversation_id> --content "hello"
-  dws chat message send --user <userId> --content "请查收"
-  dws chat message send --open-dingtalk-id <openDingTalkId> --content "请查收"
-  dws chat message send --conversation-id <openconversation_id> --title "周报提醒" --content "请大家本周五前提交周报"
+		Example: `  dws chat message send --conversation-id <openconversation_id> "hello"
+  dws chat message send --user <userId> "请查收"
+  dws chat message send --open-dingtalk-id <openDingTalkId> "请查收"
+  dws chat message send --conversation-id <openconversation_id> --title "周报提醒" "请大家本周五前提交周报"
  # 图文混排 Markdown：公网图片 URL 需要写成 ![图片标题](URL) 才会以内联图片展示
-  dws chat message send --conversation-id <openconversation_id> --content $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
+  dws chat message send --conversation-id <openconversation_id> --text $'这是图文说明\n\n![这个是展示图片标题](https://down.dingtalk.com/media/lQLPM5jiBEiBNjswMLAKd_CTzm8eowpEWPT_7-cA_48_48.png)'
  # 发送本地图片或文件（图片会作为可下载的 file 附件发送）
-  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./screenshot.png
-  dws chat message send --conversation-id <openconversation_id> --msg-type file --file ./report.pdf
+  dws chat message send --conversation-id <openconversation_id> --msg-type file --file-path ./screenshot.png
+  dws chat message send --conversation-id <openconversation_id> --msg-type file --file-path ./report.pdf
  # 发送本地音频/视频（audio/video 是 file 的语义别名）
-  dws chat message send --conversation-id <openconversation_id> --msg-type audio --file ./recording.mp3
-  dws chat message send --conversation-id <openconversation_id> --msg-type video --file ./demo.mp4
+  dws chat message send --conversation-id <openconversation_id> --msg-type audio --file-path ./recording.mp3
+  dws chat message send --conversation-id <openconversation_id> --msg-type video --file-path ./demo.mp4
  # 旧版内联图片：仅当上游已经持有有效 mediaId 时使用
  dws chat message send --conversation-id <openconversation_id> --msg-type image --media-id <mediaId>
 # 查询群 ID: dws chat search --query "群名"
@@ -3264,7 +3250,7 @@ func newChatCommand() *cobra.Command {
 					contentJSON = fmt.Sprintf(`{"mediaId":"%s"}`, mediaId)
 				case "file", "audio", "video":
 					serviceMsgType = "file"
-					filePath := flagOrFallback(cmd, "file-path", "file")
+					filePath, _ := cmd.Flags().GetString("file-path")
 					dentryId, _ := cmd.Flags().GetInt64("dentry-id")
 					spaceId, _ := cmd.Flags().GetInt64("space-id")
 					if (dentryId == 0) != (spaceId == 0) {
@@ -3295,7 +3281,7 @@ func newChatCommand() *cobra.Command {
 							}
 							contentJSON, _ = buildConversationFileContent(dentryId, spaceId, meta)
 						} else if dentryId == 0 || spaceId == 0 {
-							return fmt.Errorf("--file must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err)
+							return fmt.Errorf("--file-path must be a readable local file, or pass legacy --dentry-id and --space-id: %w", err)
 						}
 					}
 					if contentJSON == "" {
@@ -3303,7 +3289,7 @@ func newChatCommand() *cobra.Command {
 						fileType, _ := cmd.Flags().GetString("file-type")
 						fileSize, _ := cmd.Flags().GetInt64("file-size")
 						if dentryId == 0 || spaceId == 0 || fileName == "" {
-							return fmt.Errorf("readable local --file is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported")
+							return fmt.Errorf("readable local --file-path is required for msgType=file; legacy flags --dentry-id, --space-id, --file-name are still supported")
 						}
 						contentJSON = fmt.Sprintf(`{"dentryId":%d,"spaceId":%d,"fileName":"%s","fileType":"%s","filePath":"%s","fileSize":%d}`,
 							dentryId, spaceId, fileName, fileType, filePath, fileSize)
@@ -3349,7 +3335,7 @@ func newChatCommand() *cobra.Command {
 				text = args[0]
 			}
 			if text == "" {
-				return fmt.Errorf("message content required (use --content or positional arg, or --media-id for image)")
+				return fmt.Errorf("message content required (use --text or positional arg, or --media-id for image)")
 			}
 			title, _ := cmd.Flags().GetString("title")
 			if title == "" {
@@ -3409,7 +3395,7 @@ func newChatCommand() *cobra.Command {
 				AgentSummary: "以当前用户身份发送群聊或单聊消息",
 				UseWhen:      []string{"用户明确要以个人身份发送文本或媒体消息时；响应返回 openTaskId 后用 chat message query-send-status 确认投递并取得后续操作所需的消息 ID"},
 				AvoidWhen:    []string{"机器人身份或 Webhook 发送应使用对应命令"},
-				Examples:     []string{"dws chat message send --group <openConversationId> --content \"项目已更新\""},
+				Examples:     []string{"dws chat message send --group <openConversationId> \"项目已更新\""},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "ai-tag", Property: "clawType", InterfaceType: "string"},
@@ -3730,25 +3716,19 @@ func newChatCommand() *cobra.Command {
 	chatMessageSendByWebhookCmd := &cobra.Command{
 		Use:   "send-by-webhook",
 		Short: "自定义机器人 Webhook 发送群消息",
-		Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --content 中包含 @userId 或 @手机号，否则 @ 不生效。
+		Long: `通过自定义机器人 Webhook 发送群消息。@ 人时需在 --text 中包含 @userId 或 @手机号，否则 @ 不生效。

 ⚠️ 重要：该接口会真实发送消息到目标群聊，不可用于测试或试探性调用。调用前必须确认消息内容无误。`,
-		Example: `  dws chat message send-by-webhook --token <webhook-token> --title "告警" --content "CPU 超 90%" --at-all
-  dws chat message send-by-webhook --token <webhook-token> --title "test" --content "hi @118785" --at-users 118785`,
-		PreRunE: func(cmd *cobra.Command, args []string) error {
-			return promoteLegacyChatString(cmd, "content", "text")
-		},
+		Example: `  dws chat message send-by-webhook --token <webhook-token> --title "告警" --text "CPU 超 90%" --at-all
+  dws chat message send-by-webhook --token <webhook-token> --title "test" --text "hi @118785" --at-users 118785`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := promoteLegacyChatString(cmd, "content", "text"); err != nil {
-				return err
-			}
-			if err := validateRequiredFlags(cmd, "token", "title", "content"); err != nil {
+			if err := validateRequiredFlags(cmd, "token", "title", "text"); err != nil {
 				return err
 			}
 			toolArgs := map[string]any{
 				"robotToken": mustGetFlag(cmd, "token"),
 				"title":      mustGetFlag(cmd, "title"),
-				"text":       mustGetFlag(cmd, "content"),
+				"text":       mustGetFlag(cmd, "text"),
 			}
 			if v, _ := cmd.Flags().GetBool("at-all"); v {
 				toolArgs["isAtAll"] = true
@@ -3823,12 +3803,11 @@ func newChatCommand() *cobra.Command {
 					"使用企业机器人 robot-code 发消息时用 chat message send-by-bot",
 					"以个人身份发消息时用 chat message send",
 				},
-				Examples: []string{"dws chat message send-by-webhook --token <webhook-token> --title \"告警\" --content \"CPU 超 90%\" --at-all"},
+				Examples: []string{"dws chat message send-by-webhook --token <webhook-token> --title \"告警\" --text \"CPU 超 90%\" --at-all"},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "at-all", Property: "isAtAll"},
 				{Name: "at-users", Property: "atUserIds"},
-				{Name: "content", Property: "text"},
 				{Name: "token", Property: "robotToken"},
 			},
 		},
@@ -4377,7 +4356,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Example: `  dws chat message recall --conversation-id <openConversationId> --message-id <openMessageId>

  # 发送后撤回：send -> query-send-status -> recall
-  dws chat message send --conversation-id <openConversationId> --content "待撤回的内容"
+  dws chat message send --conversation-id <openConversationId> --text "待撤回的内容"
  dws chat message query-send-status --open-task-id <上一步返回的openTaskId>
  dws chat message recall --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId>`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -4438,7 +4417,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Example: `  dws chat message edit --conversation-id <openConversationId> --message-id <openMessageId> --text "更新后的内容"

  # 发送后编辑：send -> query-send-status -> edit
-  dws chat message send --conversation-id <openConversationId> --content "原始内容"
+  dws chat message send --conversation-id <openConversationId> --text "原始内容"
  dws chat message query-send-status --open-task-id <上一步返回的openTaskId>
  dws chat message edit --conversation-id <上一步返回的openConversationId> --message-id <上一步返回的openMessageId> --text "更新后的内容"

@@ -4774,19 +4753,21 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	chatMessageSendCmd.Flags().String("user", "", "单聊接收人 userId（单聊时与 --open-dingtalk-id 二选一）")
 	chatMessageSendCmd.Flags().String("open-dingtalk-id", "", "单聊接收人 openDingTalkId（单聊时与 --user 二选一）")
 	chatMessageSendCmd.Flags().String("title", "", "消息标题，显示在消息列表（可选，未指定时使用消息内容）")
-	corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{
-		Name:    "content",
-		Usage:   "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）",
-		Aliases: []string{"text"},
-	}})
-	for _, alias := range []string{"body", "message", "markdown"} {
-		chatMessageSendCmd.Flags().String(alias, "", "--content 的兼容别名")
-		_ = chatMessageSendCmd.Flags().MarkHidden(alias)
-	}
+	// 别名注册: --text/--content/--body/--message/--markdown → 位置参数
+	chatMessageSendCmd.Flags().String("text", "", "消息内容（推荐方式，也可用位置参数传递。内容含换行/特殊字符时必须使用此 flag）")
+	chatMessageSendCmd.Flags().String("content", "", "--text 的别名")
+	chatMessageSendCmd.Flags().String("body", "", "--text 的别名")
+	chatMessageSendCmd.Flags().String("message", "", "--text 的别名")
+	chatMessageSendCmd.Flags().String("markdown", "", "--text 的别名")
+	// --text 不再隐藏，作为首选传参方式展示在 help 中
+	_ = chatMessageSendCmd.Flags().MarkHidden("content")
+	_ = chatMessageSendCmd.Flags().MarkHidden("body")
+	_ = chatMessageSendCmd.Flags().MarkHidden("message")
+	_ = chatMessageSendCmd.Flags().MarkHidden("markdown")
 	chatMessageSendCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效，可选）,设置时，消息内容中一定要包含对应的占位符<@all>")
 	chatMessageSendCmd.Flags().String("at-open-dingtalk-ids", "", "@指定成员的 openDingTalkId 列表，逗号分隔（仅群聊时生效，可选）,设置--at-open-dingtalk-ids openDingTalkId1,openDingTalkId2时，消息内容中一定要包含对应格式的占位符<@openDingTalkId1> <@openDingTalkId2>")
 	chatMessageSendCmd.Flags().String("media-id", "", "上游已提供的图片 mediaId（仅旧版 msgType=image；CLI 不提供本地上传到 mediaId）")
-	chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file；image 仅接受已有 mediaId）")
+	chatMessageSendCmd.Flags().String("msg-type", "", "富媒体消息类型: image/file/audio/video/location/profile（本地图片/文件推荐 file --file-path；image 仅接受已有 mediaId）")
 	chatMessageSendCmd.Flags().String("latitude", "", "位置消息纬度（msgType=location 时必填）")
 	chatMessageSendCmd.Flags().String("longitude", "", "位置消息经度（msgType=location 时必填）")
 	chatMessageSendCmd.Flags().String("location-name", "", "位置消息地址名称（msgType=location 时必填）")
@@ -4796,11 +4777,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	chatMessageSendCmd.Flags().Int64("space-id", 0, "空间 ID（与 --dentry-id 成对传入时跳过自动上传）")
 	chatMessageSendCmd.Flags().String("file-name", "", "文件名")
 	chatMessageSendCmd.Flags().String("file-type", "", "文件类型/扩展名")
-	corecmd.RegisterFlags(chatMessageSendCmd, []corecmd.FlagSpec{{
-		Name:    "file",
-		Usage:   "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）",
-		Aliases: []string{"file-path"},
-	}})
+	chatMessageSendCmd.Flags().String("file-path", "", "本地文件路径（msgType=file/audio/video 时直接上传并按 file 消息发送）")
 	chatMessageSendCmd.Flags().Int64("file-size", 0, "文件大小，单位字节")
 	_ = chatMessageSendCmd.Flags().MarkHidden("dentry-id")
 	_ = chatMessageSendCmd.Flags().MarkHidden("space-id")
@@ -4821,12 +4798,12 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	cli.AnnotateRuntimePositionals(chatMessageSendCmd, contract.RuntimeSchemaPositional{
 		Name:        "content",
 		Type:        "string",
-		Description: "消息内容（也可使用 --content；富媒体消息可省略）",
+		Description: "消息内容（也可使用 --text；富媒体消息可省略）",
 		Required:    false,
 		Index:       0,
 	})
 	cli.AnnotateRuntimeFlagEnum(chatMessageSendCmd, "msg-type", "image", "file", "audio", "video")
-	cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file", "file-path")
+	cli.AnnotateRuntimeFlagFormat(chatMessageSendCmd, "file-path", "file-path")

 	chatMessageSendByBotCmd.Flags().String("robot-code", "", "机器人 Code (必填)")
 	_ = chatMessageSendByBotCmd.MarkFlagRequired("robot-code")
@@ -4861,12 +4838,8 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("token")
 	chatMessageSendByWebhookCmd.Flags().String("title", "", "消息标题 (必填)")
 	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("title")
-	corecmd.RegisterFlags(chatMessageSendByWebhookCmd, []corecmd.FlagSpec{{
-		Name:    "content",
-		Usage:   "消息内容 (必填)",
-		Aliases: []string{"text"},
-	}})
-	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("content")
+	chatMessageSendByWebhookCmd.Flags().String("text", "", "消息内容 (必填)")
+	_ = chatMessageSendByWebhookCmd.MarkFlagRequired("text")
 	chatMessageSendByWebhookCmd.Flags().Bool("at-all", false, "@ 所有人")
 	chatMessageSendByWebhookCmd.Flags().String("at-mobiles", "", "@ 指定手机号，逗号分隔")
 	chatMessageSendByWebhookCmd.Flags().String("at-users", "", "@ 指定用户，逗号分隔")
@@ -5076,7 +5049,7 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Use:   "conversation-info",
 		Short: "获取会话基础信息",
 		Long: `获取指定会话的基础信息。
-发送本地文件消息请优先使用 dws chat message send --msg-type file --file <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`,
+发送本地文件消息请优先使用 dws chat message send --msg-type file --file-path <本地文件>，CLI 不再要求调用方获取或传递 spaceId。`,
 		Example: `  dws chat conversation-info --conversation-id <openConversationId> --format json
  dws chat conversation-info --user <userId> --format json
  dws chat conversation-info --open-dingtalk-id <openDingTalkId> --format json`,
@@ -5191,11 +5164,11 @@ chat message edit 或 chat message recall 的 --message-id 和 --conversation-id
 		Hidden: true,
 		Long: `chat file upload 已下线，不再调用 chat/upload_conversation_file_by_url。

-发送本地文件消息请改用 chat message send --msg-type file --file；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`,
-		Example: `  dws chat message send --conversation-id <openConversationId> --msg-type file --file ./report.pdf --format json
-  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf --format json`,
+发送本地文件消息请改用 chat message send --msg-type file --file-path；该路径仍然可用，CLI 内部会完成本地文件上传和消息发送。`,
+		Example: `  dws chat message send --conversation-id <openConversationId> --msg-type file --file-path ./report.pdf --format json
+  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file-path ./report.pdf --format json`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file <本地路径>")
+			return fmt.Errorf("chat file upload 已下线；chat/upload_conversation_file_by_url 当前不可用。发送本地文件请改用: dws chat message send --msg-type file --file-path <本地路径>")
 		},
 	}
 	chatFileUploadCmd.Flags().String("conversation-id", "", "群聊 openConversationId（群聊时使用）")
@@ -6961,22 +6934,10 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
  - 群聊：dws chat search --query "群名"
  - 单聊：dws chat conversation-info --open-dingtalk-id <openDingTalkId>
          （人员信息可通过 dws contact user search --keyword "姓名" --format json 获取）`,
-		Example: `  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "收到，马上处理"
-  dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content "请看一下" --at-open-dingtalk-ids <mentionedOpenDingTalkId>`,
-		PreRunE: func(cmd *cobra.Command, args []string) error {
-			if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil {
-				return err
-			}
-			return promoteLegacyChatString(cmd, "content", "text")
-		},
+		Example: `  dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text "收到，马上处理"
+  dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text "请看一下" --at-open-dingtalk-ids <mentionedOpenDingTalkId>`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := promoteLegacyChatString(cmd, "group", "conversation-id"); err != nil {
-				return err
-			}
-			if err := promoteLegacyChatString(cmd, "content", "text"); err != nil {
-				return err
-			}
-			if err := validateRequiredFlags(cmd, "group", "ref-msg-id", "ref-sender", "content"); err != nil {
+			if err := validateRequiredFlags(cmd, "conversation-id", "ref-msg-id", "ref-sender", "text"); err != nil {
 				return err
 			}
 			refSender := mustGetFlag(cmd, "ref-sender")
@@ -6993,7 +6954,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 				clawType = edition.ClawType()
 			}
 			toolArgs := map[string]any{
-				"openConversationId": mustGetFlag(cmd, "group"),
+				"openConversationId": mustGetFlag(cmd, "conversation-id"),
 				"msgType":            "reply",
 				"clawType":           clawType,
 			}
@@ -7001,7 +6962,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			atOpenIDs := mustGetFlag(cmd, "at-open-dingtalk-ids")
 			replyText := applyCurrentUserGroupMentions(
 				toolArgs,
-				mustGetFlag(cmd, "content"),
+				mustGetFlag(cmd, "text"),
 				atOpenIDs,
 				atAll,
 			)
@@ -7043,32 +7004,24 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 				AgentSummary: "引用指定消息发送个人回复",
 				UseWhen:      []string{"用户要针对某条已有消息进行引用回复时"},
 				AvoidWhen:    []string{"无需引用上下文的普通消息使用 chat message send"},
-				Examples:     []string{"dws chat message reply --group <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --content \"收到\""},
+				Examples:     []string{"dws chat message reply --conversation-id <openConversationId> --ref-msg-id <openMessageId> --ref-sender <openDingTalkId> --text \"收到\""},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "ai-tag", Property: "clawType", InterfaceType: "string"},
 				{Name: "at-all", Property: "atAll", Required: boolPtr(false), InterfaceType: "boolean"},
 				{Name: "at-open-dingtalk-ids", Property: "atOpenDingTalkIds", Required: boolPtr(false), InterfaceType: "array"},
-				{Name: "group", Property: "openConversationId"},
+				{Name: "conversation-id", Property: "openConversationId"},
 			},
 		},
 	})
-	corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{
-		Name:    "group",
-		Usage:   "会话 openConversationId (必填，支持单聊/群聊)",
-		Aliases: []string{"conversation-id"},
-	}})
-	_ = chatMessageReplyCmd.MarkFlagRequired("group")
+	chatMessageReplyCmd.Flags().String("conversation-id", "", "会话 openConversationId (必填，支持单聊/群聊)")
+	_ = chatMessageReplyCmd.MarkFlagRequired("conversation-id")
 	chatMessageReplyCmd.Flags().String("ref-msg-id", "", "被引用的消息 openMessageId (必填)")
 	_ = chatMessageReplyCmd.MarkFlagRequired("ref-msg-id")
 	chatMessageReplyCmd.Flags().String("ref-sender", "", "被引用消息的发送者 openDingTalkId (必填)")
 	_ = chatMessageReplyCmd.MarkFlagRequired("ref-sender")
-	corecmd.RegisterFlags(chatMessageReplyCmd, []corecmd.FlagSpec{{
-		Name:    "content",
-		Usage:   "回复内容 (必填)",
-		Aliases: []string{"text"},
-	}})
-	_ = chatMessageReplyCmd.MarkFlagRequired("content")
+	chatMessageReplyCmd.Flags().String("text", "", "回复内容 (必填)")
+	_ = chatMessageReplyCmd.MarkFlagRequired("text")
 	chatMessageReplyCmd.Flags().String("uuid", "", "幂等键（可选）")
 	chatMessageReplyCmd.Flags().Bool("ai-tag", true, "消息是否带 AI 发送角标（默认 true）")
 	chatMessageReplyCmd.Flags().Bool("at-all", false, "@所有人（仅群聊时生效；正文缺少 <@all> 时自动补齐）")
@@ -18,7 +18,7 @@ import (
 	"github.com/spf13/cobra"
 )

-const chatMediaUploadReplacement = "dws chat message send --msg-type file --file <本地路径>"
+const chatMediaUploadReplacement = "dws chat message send --msg-type file --file-path <本地路径>"

 func newChatMediaGroup() *cobra.Command {
 	media := &cobra.Command{
@@ -43,11 +43,11 @@ func newChatMediaUploadCommand() *cobra.Command {
 		Deprecated: "请改用 " + chatMediaUploadReplacement,
 		Long: `此命令仅为 1.x 命令行兼容保留，不再读取应用凭证或调用旧版媒体上传接口。

-发送本地图片或文件时，请使用 chat message send --msg-type file --file。
+发送本地图片或文件时，请使用 chat message send --msg-type file --file-path。
 该路径会把图片作为可下载的 file 消息发送，不会生成 mediaId，也不会渲染成内联 image 消息。
 如果上游已经提供 mediaId，仍可使用 chat message send --msg-type image --media-id。`,
-		Example: "  dws chat message send --conversation-id <openConversationId> --msg-type file --file ./screenshot.png\n" +
-			"  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file ./report.pdf",
+		Example: "  dws chat message send --group <openConversationId> --msg-type file --file-path ./screenshot.png\n" +
+			"  dws chat message send --open-dingtalk-id <openDingTalkId> --msg-type file --file-path ./report.pdf",
 		Args:              cobra.NoArgs,
 		DisableAutoGenTag: true,
 		RunE: func(*cobra.Command, []string) error {
@@ -56,7 +56,7 @@ func newChatMediaUploadCommand() *cobra.Command {
 	}
 	// Keep the historical flags so existing argv remains parseable while the
 	// 1.x compatibility command returns an actionable migration error.
-	cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file")
+	cmd.Flags().String("file", "", "旧版兼容参数；本地文件请改用 chat message send --file-path")
 	cmd.Flags().String("type", "image", "旧版兼容参数；不再执行媒体上传")
 	return cmd
 }
@@ -28,7 +28,7 @@ func TestCrossPlatformCoverageChatMediaUploadIsDeprecatedCompatibilityStub(t *te
 	if err == nil {
 		t.Fatal("deprecated media upload returned nil error")
 	}
-	for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file", "--media-id"} {
+	for _, want := range []string{"已下线", "chat message send", "--msg-type file", "--file-path", "--media-id"} {
 		if !strings.Contains(err.Error(), want) {
 			t.Fatalf("media upload migration error missing %q: %v", want, err)
 		}
@@ -1,328 +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 helpers
-
-import (
-	"encoding/json"
-	"fmt"
-	"strings"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
-	"github.com/spf13/cobra"
-)
-
-const commentServer = "doc-comment"
-
-var commentBatchResultSchema = json.RawMessage(`{
-  "type":"object",
-  "description":"按请求顺序返回的评论详情",
-  "properties":{
-    "commentList":{
-      "type":"array",
-      "description":"与请求 comments 顺序一致的评论详情列表",
-      "items":{
-        "type":"object",
-        "description":"单条评论查询结果；不存在时 found=false",
-        "properties":{
-          "topicId":{"type":"string","description":"评论主题 ID"},
-          "commentKey":{"type":"string","description":"评论唯一标识"},
-          "found":{"type":"boolean","description":"该 topicId/commentKey 是否存在"},
-          "content":{"type":["string","null"],"description":"纯文本评论内容"},
-          "quote":{"type":["string","null"],"description":"划词评论引用内容"},
-          "creatorId":{"type":["string","null"],"description":"创建者用户 ID"},
-          "createTime":{"type":["integer","null"],"description":"创建时间，毫秒时间戳"},
-          "updateTime":{"type":["integer","null"],"description":"更新时间，毫秒时间戳"},
-          "isSolved":{"type":["boolean","null"],"description":"是否已解决"},
-          "isEmoji":{"type":["boolean","null"],"description":"是否为表情回复"},
-          "replyCommentKey":{"type":["string","null"],"description":"被回复评论的标识"}
-        },
-        "required":["topicId","commentKey","found"],
-        "additionalProperties":true
-      }
-    }
-  },
-  "required":["commentList"],
-  "additionalProperties":true
-}`)
-
-var commentStatusResultSchema = json.RawMessage(`{
-  "type":"object",
-  "description":"评论解决状态更新结果",
-  "properties":{
-    "commentKey":{"type":"string","description":"评论唯一标识"},
-    "resolved":{"type":"boolean","description":"更新后的解决状态"},
-    "message":{"type":"string","description":"操作结果消息"}
-  },
-  "required":["commentKey","resolved"],
-  "additionalProperties":true
-}`)
-
-var commentReactionResultSchema = json.RawMessage(`{
-  "type":"object",
-  "description":"表情回复创建结果",
-  "properties":{
-    "commentKey":{"type":"string","description":"新建表情回复的评论标识"},
-    "message":{"type":"string","description":"操作结果消息"}
-  },
-  "required":["commentKey"],
-  "additionalProperties":true
-}`)
-
-// newCommentBaseCommands returns the base comment commands shared by Doc and Sheet.
-// Both resource domains call the same comment MCP tools; only CLI identity and
-// guidance differ.
-func newCommentBaseCommands(surface string) []*cobra.Command {
-	batchCmd := newCommentBatchQueryCommand(surface)
-	resolveCmd := newCommentStatusCommand(surface, true)
-	restoreCmd := newCommentStatusCommand(surface, false)
-	reactCmd := newCommentReactionCommand(surface)
-	commands := []*cobra.Command{batchCmd, resolveCmd, restoreCmd, reactCmd}
-	for _, cmd := range commands {
-		addCommentNodeAliases(cmd)
-	}
-	return commands
-}
-
-func newCommentBatchQueryCommand(surface string) *cobra.Command {
-	resourceName := commentResourceName(surface)
-	cmd := &cobra.Command{
-		Use:     "batch-query",
-		Aliases: []string{"batch-query-comments", "batch"},
-		Short:   "按 topicId + commentKey 批量查询评论详情",
-		Long: `批量查询同一文档或表格中的评论详情，单次最多 100 条。
-
--comment-ref 可重复传入，格式为 topicId:commentKey。topicId 和 commentKey
-均可从 comment list 的返回结果中获得。结果严格保持输入顺序；不存在的评论
-会返回 found=false 的占位项。`,
-		Example: fmt.Sprintf("  dws %s comment batch-query --node <NODE_ID> --comment-ref global:<COMMENT_KEY> --comment-ref <TOPIC_ID>:<COMMENT_KEY> --format json", surface),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
-			if err != nil {
-				return err
-			}
-			rawRefs, _ := cmd.Flags().GetStringSlice("comment-ref")
-			refs, err := parseCommentRefs(rawRefs)
-			if err != nil {
-				return err
-			}
-			return callMCPToolOnServer(commentServer, "batch_query_comments", map[string]any{
-				"nodeId":   nodeID,
-				"comments": refs,
-			})
-		},
-	}
-	DeclareLeafMetadata(cmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity:    commentIdentity(surface, "batch_query_comments", "batch-query"),
-			Description: "按 topicId + commentKey 批量查询评论详情，保持输入顺序并显式标记缺失项",
-			Result: &contract.ResultSpec{
-				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema: commentBatchResultSchema,
-			},
-			Interface: commentInterface("batch_query_comments"),
-			Selection: contract.SelectionSpec{
-				AgentSummary: "已知多组 topicId/commentKey 时，一次获取完整评论详情",
-				UseWhen:      []string{fmt.Sprintf("需要回查%s comment list 结果中的多条评论详情，或批量核对评论是否仍存在时", resourceName)},
-				AvoidWhen:    []string{fmt.Sprintf("尚未取得%s评论的 topicId/commentKey 时先使用 comment list", resourceName)},
-				Examples:     []string{fmt.Sprintf("dws %s comment batch-query --node <NODE_ID> --comment-ref <TOPIC_ID>:<COMMENT_KEY> --format json", surface)},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "node", Property: "nodeId"},
-				{Name: "comment-ref", Property: "comments", InterfaceType: "array"},
-			},
-		},
-	})
-	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
-	cmd.Flags().StringSlice("comment-ref", nil, "评论引用 topicId:commentKey，可重复；最多 100 条 (必填)")
-	return cmd
-}
-
-func newCommentStatusCommand(surface string, resolve bool) *cobra.Command {
-	resourceName := commentResourceName(surface)
-	use := "restore"
-	rpc := "restore_comment"
-	short := "将已解决评论恢复为未解决"
-	resolved := false
-	if resolve {
-		use = "resolve"
-		rpc = "resolve_comment"
-		short = "将评论标记为已解决"
-		resolved = true
-	}
-	cmd := &cobra.Command{
-		Use:     use,
-		Aliases: []string{use + "-comment"},
-		Short:   short,
-		Example: fmt.Sprintf("  dws %s comment %s --node <NODE_ID> --comment-key <COMMENT_KEY> --format json", surface, use),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
-			if err != nil {
-				return err
-			}
-			if err := validateRequiredFlags(cmd, "comment-key"); err != nil {
-				return err
-			}
-			return callMCPToolOnServer(commentServer, rpc, map[string]any{
-				"nodeId":     nodeID,
-				"commentKey": mustGetFlag(cmd, "comment-key"),
-			})
-		},
-	}
-	DeclareLeafMetadata(cmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity:    commentIdentity(surface, rpc, use),
-			Description: short,
-			Result: &contract.ResultSpec{
-				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema: commentStatusResultSchema,
-			},
-			Interface: commentInterface(rpc),
-			Selection: contract.SelectionSpec{
-				AgentSummary: short,
-				UseWhen:      []string{fmt.Sprintf("用户明确要求把%s中的某条评论标记为%s时", resourceName, map[bool]string{true: "已解决", false: "未解决"}[resolved])},
-				AvoidWhen:    []string{fmt.Sprintf("永久删除%s评论使用 comment delete；修改文字使用 comment update", resourceName)},
-				Examples:     []string{fmt.Sprintf("dws %s comment %s --node <NODE_ID> --comment-key <COMMENT_KEY> --format json", surface, use)},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "node", Property: "nodeId"},
-				{Name: "comment-key", Property: "commentKey"},
-			},
-		},
-	})
-	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
-	cmd.Flags().String("comment-key", "", "目标评论的 commentKey (必填)")
-	return cmd
-}
-
-func newCommentReactionCommand(surface string) *cobra.Command {
-	resourceName := commentResourceName(surface)
-	cmd := &cobra.Command{
-		Use:   "react-reply",
-		Short: "创建一条表情回复",
-		Long: `创建表情回复的便捷命令。底层复用 reply_comment，并固定传入 emoji=true。
-
-与 comment reply --emoji 一致，--reaction 必须填写钉钉表情名称，不要直接传
-Unicode Emoji。例如用户要求 😄 时传“憨笑”，要求 👏 时传“鼓掌”。
-
-当前轻量版仅支持创建，不包含删除或聚合能力。`,
-		Example: fmt.Sprintf("  dws %s comment react-reply --node <NODE_ID> --comment-key <COMMENT_KEY> --reaction \"憨笑\" --format json", surface),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
-			if err != nil {
-				return err
-			}
-			if err := validateRequiredFlags(cmd, "comment-key", "reaction"); err != nil {
-				return err
-			}
-			return callMCPToolOnServer(commentServer, "reply_comment", map[string]any{
-				"nodeId":          nodeID,
-				"replyCommentKey": mustGetFlag(cmd, "comment-key"),
-				"content":         mustGetFlag(cmd, "reaction"),
-				"emoji":           true,
-			})
-		},
-	}
-	DeclareLeafMetadata(cmd, LeafSpec{
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "low", Confirmation: "not_required", Idempotency: "non_idempotent",
-		},
-		Contract: LeafContract{
-			Identity:    commentIdentity(surface, "react_reply", "react-reply"),
-			Description: "为指定评论创建表情回复（轻量版）",
-			Result: &contract.ResultSpec{
-				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema: commentReactionResultSchema,
-			},
-			Interface: commentInterface("reply_comment"),
-			Selection: contract.SelectionSpec{
-				AgentSummary: "使用钉钉表情名称为指定评论创建表情回复",
-				UseWhen:      []string{fmt.Sprintf("用户要用表情回应%s中的某条评论时；先将 Unicode Emoji 转为钉钉表情名称，例如 😄 转为憨笑、👏 转为鼓掌", resourceName)},
-				AvoidWhen:    []string{fmt.Sprintf("%s评论的普通文字回复使用 comment reply；当前轻量版不支持删除 reaction", resourceName)},
-				Examples:     []string{fmt.Sprintf("dws %s comment react-reply --node <NODE_ID> --comment-key <COMMENT_KEY> --reaction \"憨笑\" --format json", surface)},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "node", Property: "nodeId"},
-				{Name: "comment-key", Property: "replyCommentKey"},
-				{Name: "reaction", Property: "content"},
-			},
-		},
-	})
-	cmd.Flags().String("node", "", "文档或表格 ID / URL (必填)")
-	cmd.Flags().String("comment-key", "", "被回应评论的 commentKey (必填)")
-	cmd.Flags().String("reaction", "", "钉钉表情名称，不是 Unicode Emoji；例如 😄=憨笑、👏=鼓掌 (必填)")
-	return cmd
-}
-
-func parseCommentRefs(rawRefs []string) ([]map[string]any, error) {
-	if len(rawRefs) == 0 {
-		return nil, fmt.Errorf("missing required flag(s): --comment-ref")
-	}
-	if len(rawRefs) > 100 {
-		return nil, fmt.Errorf("--comment-ref 最多可传 100 条，当前为 %d 条", len(rawRefs))
-	}
-	refs := make([]map[string]any, 0, len(rawRefs))
-	for index, raw := range rawRefs {
-		parts := strings.SplitN(strings.TrimSpace(raw), ":", 2)
-		if len(parts) != 2 || strings.TrimSpace(parts[0]) == "" || strings.TrimSpace(parts[1]) == "" {
-			return nil, fmt.Errorf("invalid --comment-ref[%d] %q: expected topicId:commentKey", index, raw)
-		}
-		refs = append(refs, map[string]any{
-			"topicId":    strings.TrimSpace(parts[0]),
-			"commentKey": strings.TrimSpace(parts[1]),
-		})
-	}
-	return refs, nil
-}
-
-func addCommentNodeAliases(cmd *cobra.Command) {
-	cmd.Flags().String("url", "", "")
-	cmd.Flags().String("id", "", "")
-	cmd.Flags().String("node-id", "", "")
-	cmd.Flags().String("doc-id", "", "")
-	cmd.Flags().String("file-id", "", "")
-	for _, name := range []string{"url", "id", "node-id", "doc-id", "file-id"} {
-		_ = cmd.Flags().MarkHidden(name)
-	}
-}
-
-func commentIdentity(surface, name, cliLeaf string) contract.ToolIdentitySpec {
-	return contract.ToolIdentitySpec{
-		ProductID:      surface,
-		Name:           name,
-		CanonicalPath:  surface + "." + name,
-		CLIPath:        surface + " comment " + cliLeaf,
-		PrimaryCLIPath: surface + " comment " + cliLeaf,
-	}
-}
-
-func commentResourceName(surface string) string {
-	if surface == "sheet" {
-		return "表格"
-	}
-	return "文档"
-}
-
-func commentInterface(rpc string) *contract.InterfaceSpec {
-	return &contract.InterfaceSpec{
-		Mode:         "mcp",
-		Availability: "available",
-		Ref:          &contract.InterfaceRefSpec{ProductID: commentServer, RPCName: rpc},
-	}
-}
@@ -1,174 +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 helpers
-
-import (
-	"io"
-	"os"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-)
-
-func executeCommentBaseCommand(t *testing.T, caller *docCommentMutationCaller, surface string, args ...string) error {
-	t.Helper()
-	previousDeps := deps
-	previousArgs := os.Args
-	t.Cleanup(func() {
-		deps = previousDeps
-		os.Args = previousArgs
-	})
-
-	InitDeps(caller)
-	deps.Out.w = io.Discard
-	os.Args = []string{"dws", surface}
-	var cmd *cobra.Command
-	if surface == "sheet" {
-		cmd = newSheetCommand()
-	} else {
-		cmd = newDocCommand()
-	}
-	cmd.PersistentFlags().Bool("yes", false, "skip confirmation")
-	cmd.SilenceErrors = true
-	cmd.SilenceUsage = true
-	cmd.SetArgs(args)
-	return cmd.Execute()
-}
-
-func TestCrossPlatformCoverageCommentBaseCommandsRegisteredForDocAndSheet(t *testing.T) {
-	for _, surface := range []struct {
-		name string
-		cmd  *cobra.Command
-	}{
-		{name: "doc", cmd: newDocCommand()},
-		{name: "sheet", cmd: newSheetCommand()},
-	} {
-		for _, leaf := range []string{"batch-query", "resolve", "restore", "react-reply"} {
-			cmd, remaining, err := surface.cmd.Find([]string{"comment", leaf})
-			if err != nil || len(remaining) != 0 {
-				t.Fatalf("dws %s comment %s not registered: cmd=%v remaining=%v err=%v",
-					surface.name, leaf, cmd, remaining, err)
-			}
-		}
-	}
-}
-
-func TestCrossPlatformCoverageDocCommentBatchQueryMapsStructuredRefs(t *testing.T) {
-	caller := &docCommentMutationCaller{}
-	err := executeCommentBaseCommand(t, caller, "doc",
-		"comment", "batch-query", "--node", "doc-1",
-		"--comment-ref", "global:comment-1", "--comment-ref", "topic-2:comment-2")
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := docCommentMutationCall{
-		productID: commentServer,
-		toolName:  "batch_query_comments",
-		args: map[string]any{
-			"nodeId": "doc-1",
-			"comments": []map[string]any{
-				{"topicId": "global", "commentKey": "comment-1"},
-				{"topicId": "topic-2", "commentKey": "comment-2"},
-			},
-		},
-	}
-	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) {
-		t.Fatalf("calls = %#v, want %#v", caller.calls, want)
-	}
-}
-
-func TestCrossPlatformCoverageSheetCommentResolveAndRestoreUseSharedRPCs(t *testing.T) {
-	caller := &docCommentMutationCaller{}
-	if err := executeCommentBaseCommand(t, caller, "sheet",
-		"comment", "resolve", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil {
-		t.Fatal(err)
-	}
-	if err := executeCommentBaseCommand(t, caller, "sheet",
-		"comment", "restore", "--node", "sheet-1", "--comment-key", "comment-1"); err != nil {
-		t.Fatal(err)
-	}
-	if len(caller.calls) != 2 {
-		t.Fatalf("calls = %#v", caller.calls)
-	}
-	if caller.calls[0].toolName != "resolve_comment" || caller.calls[1].toolName != "restore_comment" {
-		t.Fatalf("tools = %q, %q", caller.calls[0].toolName, caller.calls[1].toolName)
-	}
-	wantArgs := map[string]any{"nodeId": "sheet-1", "commentKey": "comment-1"}
-	if !reflect.DeepEqual(caller.calls[0].args, wantArgs) || !reflect.DeepEqual(caller.calls[1].args, wantArgs) {
-		t.Fatalf("calls = %#v, want args %#v", caller.calls, wantArgs)
-	}
-}
-
-func TestCrossPlatformCoverageCommentReactReplyForcesEmojiTrue(t *testing.T) {
-	caller := &docCommentMutationCaller{}
-	err := executeCommentBaseCommand(t, caller, "doc",
-		"comment", "react-reply", "--file-id", "doc-1",
-		"--comment-key", "comment-1", "--reaction", "鼓掌")
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := docCommentMutationCall{
-		productID: commentServer,
-		toolName:  "reply_comment",
-		args: map[string]any{
-			"nodeId":          "doc-1",
-			"replyCommentKey": "comment-1",
-			"content":         "鼓掌",
-			"emoji":           true,
-		},
-	}
-	if len(caller.calls) != 1 || !reflect.DeepEqual(caller.calls[0], want) {
-		t.Fatalf("calls = %#v, want %#v", caller.calls, want)
-	}
-}
-
-func TestCrossPlatformCoverageCommentReactReplyGuidesDingTalkEmojiNames(t *testing.T) {
-	for _, surface := range []struct {
-		name string
-		cmd  *cobra.Command
-	}{
-		{name: "doc", cmd: newDocCommand()},
-		{name: "sheet", cmd: newSheetCommand()},
-	} {
-		cmd, remaining, err := surface.cmd.Find([]string{"comment", "react-reply"})
-		if err != nil || len(remaining) != 0 {
-			t.Fatalf("dws %s comment react-reply lookup: remaining=%v err=%v", surface.name, remaining, err)
-		}
-		reaction := cmd.Flags().Lookup("reaction")
-		if reaction == nil || !strings.Contains(reaction.Usage, "不是 Unicode Emoji") || !strings.Contains(reaction.Usage, "😄=憨笑") {
-			t.Fatalf("dws %s reaction guidance = %#v", surface.name, reaction)
-		}
-		if !strings.Contains(cmd.Long, "不要直接传") || !strings.Contains(cmd.Example, `--reaction "憨笑"`) {
-			t.Fatalf("dws %s react-reply help missing DingTalk emoji-name guidance", surface.name)
-		}
-	}
-}
-
-func TestCrossPlatformCoverageParseCommentRefsRejectsInvalidShapeAndLimit(t *testing.T) {
-	if _, err := parseCommentRefs(nil); err == nil {
-		t.Fatal("missing refs returned nil error")
-	}
-	if _, err := parseCommentRefs([]string{"missing-separator"}); err == nil {
-		t.Fatal("invalid ref returned nil error")
-	}
-	tooMany := make([]string, 101)
-	for index := range tooMany {
-		tooMany[index] = "global:comment"
-	}
-	if _, err := parseCommentRefs(tooMany); err == nil {
-		t.Fatal("101 refs returned nil error")
-	}
-}
@@ -96,7 +96,7 @@ func TestCallbackInboundMediaPreservesFutureRichTextAttachment(t *testing.T) {

 // TestExtractCallbackText covers the markdown / richText fallback path used
 // when SDK data.Text.Content is empty. This is the recovery path for
-// `dws chat message send --conversation-id ... --content ...` (defaults to msgType=markdown)
+// `dws chat message send --group ... --text ...` (defaults to msgType=markdown)
 // which otherwise gets silently dropped by the connector.
 func TestExtractCallbackText(t *testing.T) {
 	cases := []struct {
@@ -1259,7 +1259,7 @@ func runStreamConnector(ctx context.Context, channel, clientID, clientSecret str
 		}
 		// Structured-text fallback: DingTalk leaves data.Text.Content blank on
 		// markdown / richText callbacks (the body ships in data.Content). Without
-		// this, `dws chat message send --conversation-id ... --content ...` — which defaults
+		// this, `dws chat message send --group ... --text ...` — which defaults
 		// to msgType=markdown — hits the drop branch below and the bot looks
 		// dead to the sender.
 		if text == "" {
@@ -15,10 +15,10 @@ import (
 	"time"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )

 // ──────────────────────────────────────────────────────────
@@ -1018,7 +1018,7 @@ func inferMimeType(fileName string) string {
 }

 // buildBlockElement 从 flags 构建块元素 JSON 对象。
-// 优先级: --element (原始 JSON) > --heading > --text (旧名) > --content
+// 优先级: --element (原始 JSON) > --heading > --text
 func buildBlockElement(cmd *cobra.Command) (any, error) {
 	if raw, _ := cmd.Flags().GetString("element"); raw != "" {
 		var obj any
@@ -1037,13 +1037,13 @@ func buildBlockElement(cmd *cobra.Command) (any, error) {
 			"heading":   map[string]any{"text": h, "level": level},
 		}, nil
 	}
-	if t := flagOrFallback(cmd, "text", "content"); t != "" {
+	if t, _ := cmd.Flags().GetString("text"); t != "" {
 		return map[string]any{
 			"blockType": "paragraph",
 			"paragraph": map[string]any{"text": t},
 		}, nil
 	}
-	return nil, fmt.Errorf("block content required: --content / --heading / --element")
+	return nil, fmt.Errorf("block content required: --text / --heading / --element")
 }

 // buildNodeTransferRunE creates a RunE handler for copy/move commands.
@@ -2127,12 +2127,12 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		Use:   "insert",
 		Short: "插入块元素",
 		Long: `向文档插入块元素。通过 --element 传入 JSON 格式的块元素。
-可用 --content 快速插入段落，--heading + --level 快速插入标题。
+可用 --text 快速插入段落，--heading + --level 快速插入标题。

 块类型: paragraph, heading, blockquote, callout, columns,
        orderedList, unorderedList, table, sheet, attachment, slot`,
 		Example: `  # 快捷插入段落
-  dws doc block insert --node DOC_ID --content "这是一段文字"
+  dws doc block insert --node DOC_ID --text "这是一段文字"

  # 快捷插入标题
  dws doc block insert --node DOC_ID --heading "二级标题" --level 2
@@ -2155,7 +2155,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
  dws doc block insert --node DOC_ID --element '{"blockType":"unorderedList","unorderedList":{"list":{"listId":"list-2"}},"children":[{"text":"第二项"}]}'

  # 在指定位置之前插入
-  dws doc block insert --node DOC_ID --content "插入内容" --ref-block BLOCK_ID --where before`,
+  dws doc block insert --node DOC_ID --text "插入内容" --ref-block BLOCK_ID --where before`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			nodeID, err := mustFlagOrFallback(cmd, "node", "url", "id", "node-id", "doc-id", "file-id")
 			if err != nil {
@@ -2241,14 +2241,14 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 			},
 			Selection: contract.SelectionSpec{
 				AgentSummary: "向文档插入块元素",
-				UseWhen:      []string{"在文档中插入新块（段落/标题等）；简单场景用 --content/--heading，复杂块用 --element JSON"},
+				UseWhen:      []string{"在文档中插入新块（段落/标题等）；简单场景用 --text/--heading，复杂块用 --element JSON"},
 				AvoidWhen: []string{
 					"整篇追加 Markdown 优先 doc update --mode append",
 					"插入本地文件附件优先 doc media insert",
 					"删块用 block delete；改已有块用 block update",
 				},
 				Examples: []string{
-					"dws doc block insert --node <DOC_ID> --content \"这是一段文字\" --format json",
+					"dws doc block insert --node <DOC_ID> --text \"这是一段文字\" --format json",
 					"dws doc block insert --node <DOC_ID> --heading \"二级标题\" --level 2 --format json",
 				},
 			},
@@ -2265,8 +2265,8 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 		Use:   "update",
 		Short: "更新块元素",
 		Long: `更新文档中指定块的内容或样式。需提供 --block-id 和块元素内容。
-可用 --content 快速更新为段落，--heading + --level 快速更新为标题。`,
-		Example: `  dws doc block update --node DOC_ID --block-id BLOCK_ID --content "新内容"    # 查询 nodeId: dws doc search --query "..." 或 dws doc list  # 查询 blockId: dws doc block list --node <nodeId>
+可用 --text 快速更新为段落，--heading + --level 快速更新为标题。`,
+		Example: `  dws doc block update --node DOC_ID --block-id BLOCK_ID --text "新内容"    # 查询 nodeId: dws doc search --query "..." 或 dws doc list  # 查询 blockId: dws doc block list --node <nodeId>
  dws doc block update --node DOC_ID --block-id BLOCK_ID --element '{"blockType":"heading","heading":{"text":"新标题","level":1}}'`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := validateRequiredFlags(cmd, "block-id"); err != nil {
@@ -2338,7 +2338,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 					"插入新块用 block insert；删除用 block delete",
 					"改文档显示名用 rename；整篇覆盖用 update overwrite",
 				},
-				Examples: []string{"dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --content \"新内容\" --format json"},
+				Examples: []string{"dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --text \"新内容\" --format json"},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "content-format", Property: "format"},
@@ -2748,6 +2748,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。

 	// block insert
 	blockInsertCmd.Flags().String("node", "", "文档 ID 或 URL (必填)")
+	blockInsertCmd.Flags().String("text", "", "快捷: 段落文本内容")
 	blockInsertCmd.Flags().String("heading", "", "快捷: 标题文本")
 	blockInsertCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)")
 	blockInsertCmd.Flags().String("element", "", "块元素 JSON (高级)")
@@ -2761,6 +2762,7 @@ WARNING: --mode overwrite 为破坏性写入，会清空原文档全部内容。
 	// block update
 	blockUpdateCmd.Flags().String("node", "", "文档 ID 或 URL (必填)")
 	blockUpdateCmd.Flags().String("block-id", "", "目标块 ID (必填)")
+	blockUpdateCmd.Flags().String("text", "", "快捷: 段落文本内容")
 	blockUpdateCmd.Flags().String("heading", "", "快捷: 标题文本")
 	blockUpdateCmd.Flags().Int("level", 1, "标题级别 1-6 (配合 --heading)")
 	blockUpdateCmd.Flags().String("element", "", "块元素 JSON (高级)")
@@ -3515,7 +3517,6 @@ commentKey可从 dws doc comment create 或 dws doc comment list 返回结果中
 	}

 	commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd, commentCreateInlineCmd)
-	commentCmd.AddCommand(newCommentBaseCommands("doc")...)

 	// ── permission (文档协作权限) ────────────────────────────
 	permissionCmd := &cobra.Command{
@@ -4642,16 +4643,6 @@ CLI 内部自动完成全部流程:
 			RegisterCrossProductAliases(child)
 		}
 	}
-	// Register the block content Primary after the cross-product pass. Registering
-	// --content earlier would make the global content/markdown group expand a new
-	// --markdown alias onto these commands, which is outside this migration.
-	for _, cmd := range []*cobra.Command{blockInsertCmd, blockUpdateCmd} {
-		corecmd.RegisterFlags(cmd, []corecmd.FlagSpec{{
-			Name:    "content",
-			Usage:   "快捷: 段落文本内容",
-			Aliases: []string{"text"},
-		}})
-	}

 	// ── deprecated 标记：文件管理命令已迁移到 drive ──
 	deprecatedDocToDrive := map[*cobra.Command]string{
@@ -155,18 +155,7 @@ func callMCPToolReturnTextOnServer(ctx context.Context, serverID, toolName strin
 // ReadToolCaller capability; if unavailable, it fails closed instead of
 // returning a synthetic dry-run envelope that looks like business data.
 func CallMCPReadToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) {
-	return CallMCPReadToolTextOnServerContext(context.Background(), serverID, toolName, args)
-}
-
-// CallMCPReadToolTextOnServerContext is the cancellable form used by Cobra
-// commands and composite shortcuts. Keeping the caller context attached to the
-// transport lets SIGTERM/parent deadlines stop an in-flight MCP read and return
-// a structured error instead of leaving the CLI silent until the host kills it.
-func CallMCPReadToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
-	if ctx == nil {
-		ctx = context.Background()
-	}
-	return callMCPReadToolReturnTextOnServer(ctx, serverID, toolName, args)
+	return callMCPReadToolReturnTextOnServer(context.Background(), serverID, toolName, args)
 }

 func callMCPReadToolReturnTextOnServer(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
@@ -277,17 +266,7 @@ func parseMCPToolTextResult(serverID, toolName string, result *edition.ToolResul
 // print path. Exported for the shortcut layer's multi-step ("smart") shortcuts,
 // which chain several tool calls and need each intermediate result as data.
 func CallMCPToolTextOnServer(serverID, toolName string, args map[string]any) (string, error) {
-	return CallMCPToolTextOnServerContext(context.Background(), serverID, toolName, args)
-}
-
-// CallMCPToolTextOnServerContext invokes one MCP tool while preserving the
-// command's cancellation and deadline. Legacy callers may continue using
-// CallMCPToolTextOnServer, which intentionally retains background context.
-func CallMCPToolTextOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) (string, error) {
-	if ctx == nil {
-		ctx = context.Background()
-	}
-	return callMCPToolReturnTextOnServer(ctx, serverID, toolName, args)
+	return callMCPToolReturnTextOnServer(context.Background(), serverID, toolName, args)
 }

 // CallMCPToolDataOnServer invokes one tool without printing and decodes its
@@ -314,11 +293,7 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg
 // callMCPTool 是通用的 MCP 工具调用入口：自动路由 → 调用 → 格式化输出。
 // 通过 resolveProductID() 自动确定目标 MCP Server，JSON 输出使用默认的 HTML 转义。
 func callMCPTool(toolName string, args map[string]any) error {
-	return callMCPToolContext(context.Background(), toolName, args)
-}
-
-func callMCPToolContext(ctx context.Context, toolName string, args map[string]any) error {
-	return callMCPToolInternalOptsContext(ctx, "", toolName, args, false)
+	return callMCPToolInternalOpts("", toolName, args, false)
 }

 // callMCPToolUnescaped 与 callMCPTool 功能相同，但 JSON 输出禁用 HTML 转义。
@@ -331,7 +306,7 @@ func callMCPToolUnescaped(toolName string, args map[string]any) error {
 // callMCPToolOnServer 在指定的 MCP Server 上调用工具，跳过 resolveProductID() 的自动路由。
 // 用于需要显式指定 serverID 的场景（如 credit 等多 server 产品）。
 func callMCPToolOnServer(serverID, toolName string, args map[string]any) error {
-	return callMCPToolInternalOptsContext(context.Background(), serverID, toolName, args, false)
+	return callMCPToolInternalOpts(serverID, toolName, args, false)
 }

 // CallMCPToolOnServer is the exported version of callMCPToolOnServer for use
@@ -340,13 +315,6 @@ func CallMCPToolOnServer(serverID, toolName string, args map[string]any) error {
 	return callMCPToolOnServer(serverID, toolName, args)
 }

-// CallMCPToolOnServerContext is the cancellable print-path variant for
-// Shortcut execution. It preserves the same output and error projection as the
-// legacy wrapper while allowing the root signal context to abort transport.
-func CallMCPToolOnServerContext(ctx context.Context, serverID, toolName string, args map[string]any) error {
-	return callMCPToolInternalOptsContext(ctx, serverID, toolName, args, false)
-}
-
 // GroupRunE is the exported version of groupRunE for use by extension packages.
 func GroupRunE(cmd *cobra.Command, args []string) error {
 	return groupRunE(cmd, args)
@@ -375,13 +343,7 @@ func MustGetStringFlag(cmd *cobra.Command, name string) string {
 //  3. 错误分类：网关错误 → 未登录 → PAT 错误 → 业务错误
 //  4. 根据 --format 标志选择输出格式（json / table / raw）
 func callMCPToolInternalOpts(explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error {
-	return callMCPToolInternalOptsContext(context.Background(), explicitServerID, toolName, args, unescapeHTML)
-}
-
-func callMCPToolInternalOptsContext(ctx context.Context, explicitServerID, toolName string, args map[string]any, unescapeHTML bool) error {
-	if ctx == nil {
-		ctx = context.Background()
-	}
+	ctx := context.Background()

 	// DryRun 模式：仅预览工具名和参数，不实际调用 MCP Server
 	if deps.Caller.DryRun() {
@@ -39,20 +39,6 @@ type helpersReadCaller struct {
 	readCalls  int
 }

-type helpersContextCaller struct {
-	*helpersCoreCaller
-	seenErr error
-}
-
-func (c *helpersContextCaller) CallTool(ctx context.Context, _ string, _ string, _ map[string]any) (*edition.ToolResult, error) {
-	c.calls++
-	c.seenErr = ctx.Err()
-	if c.seenErr != nil {
-		return nil, c.seenErr
-	}
-	return nil, errors.New("stop after context capture")
-}
-
 func (c *helpersReadCaller) CallReadTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
 	c.readCalls++
 	return c.readResult, c.readErr
@@ -142,48 +128,6 @@ func TestCrossPlatformCoverageReadLookupInitializationAndRegularExecution(t *tes
 	}
 }

-func TestCrossPlatformCoverageMCPContextWrappersPreserveCancellation(t *testing.T) {
-	caller := &helpersContextCaller{helpersCoreCaller: &helpersCoreCaller{format: "json"}}
-	installHelpersCoreDeps(t, caller)
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	if _, err := CallMCPToolTextOnServerContext(ctx, "aitable", "get_fields", nil); err == nil {
-		t.Fatal("cancelled text call unexpectedly succeeded")
-	}
-	if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 1 {
-		t.Fatalf("text call context/calls = %v, %d", caller.seenErr, caller.calls)
-	}
-
-	if err := CallMCPToolOnServerContext(ctx, "aitable", "get_fields", nil); err == nil {
-		t.Fatal("cancelled print call unexpectedly succeeded")
-	}
-	if !errors.Is(caller.seenErr, context.Canceled) || caller.calls != 2 {
-		t.Fatalf("print call context/calls = %v, %d", caller.seenErr, caller.calls)
-	}
-
-	// Public context-aware wrappers intentionally accept nil for compatibility,
-	// but must normalize it before crossing the transport boundary.
-	if _, err := CallMCPToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
-		t.Fatal("nil-context text call unexpectedly succeeded with a nil result")
-	}
-	if caller.seenErr != nil || caller.calls != 3 {
-		t.Fatalf("nil-context text call context/calls = %v, %d", caller.seenErr, caller.calls)
-	}
-	if _, err := CallMCPReadToolTextOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
-		t.Fatal("nil-context read call unexpectedly succeeded with a nil result")
-	}
-	if caller.seenErr != nil || caller.calls != 4 {
-		t.Fatalf("nil-context read call context/calls = %v, %d", caller.seenErr, caller.calls)
-	}
-	if err := CallMCPToolOnServerContext(nil, "aitable", "get_fields", nil); err == nil {
-		t.Fatal("nil-context print call unexpectedly succeeded with a nil result")
-	}
-	if caller.seenErr != nil || caller.calls != 5 {
-		t.Fatalf("nil-context print call context/calls = %v, %d", caller.seenErr, caller.calls)
-	}
-}
-
 func TestCrossPlatformCoverageSharedDependenciesRoutingAndWrappers(t *testing.T) {
 	oldDeps := deps
 	deps = nil
@@ -10,10 +10,7 @@ import (
 	"strings"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
-	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/spf13/cobra"
 )

@@ -45,283 +42,6 @@ func oaFormValues(raw string) ([]map[string]string, error) {
 	return result, nil
 }

-func parseOAAttachmentFileInfos(raw string) ([]map[string]any, error) {
-	decoder := json.NewDecoder(strings.NewReader(raw))
-	decoder.UseNumber()
-	var items []map[string]any
-	if err := decoder.Decode(&items); err != nil {
-		return nil, fmt.Errorf("--file-infos JSON 解析失败: %w", err)
-	}
-	if err := rejectTrailingOAAttachmentJSON(decoder); err != nil {
-		return nil, err
-	}
-	if len(items) < 1 || len(items) > 10 {
-		return nil, fmt.Errorf("--file-infos 必须包含 1 至 10 个文件")
-	}
-
-	infos := make([]map[string]any, 0, len(items))
-	for index, item := range items {
-		for name := range item {
-			if name != "spaceId" && name != "fileId" {
-				return nil, fmt.Errorf("--file-infos 第 %d 项包含未知字段 %q", index+1, name)
-			}
-		}
-
-		spaceValue, ok := item["spaceId"]
-		if !ok {
-			return nil, fmt.Errorf("--file-infos 第 %d 项缺少 spaceId", index+1)
-		}
-		spaceID, ok := spaceValue.(json.Number)
-		if !ok {
-			return nil, fmt.Errorf("--file-infos 第 %d 项 spaceId 必须是数字", index+1)
-		}
-
-		fileValue, ok := item["fileId"]
-		if !ok {
-			return nil, fmt.Errorf("--file-infos 第 %d 项缺少 fileId", index+1)
-		}
-		fileID, ok := fileValue.(string)
-		if !ok {
-			return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 必须是字符串", index+1)
-		}
-		fileID = strings.TrimSpace(fileID)
-		if fileID == "" {
-			return nil, fmt.Errorf("--file-infos 第 %d 项 fileId 不能为空", index+1)
-		}
-
-		infos = append(infos, map[string]any{"spaceId": spaceID, "fileId": fileID})
-	}
-	return infos, nil
-}
-
-func rejectTrailingOAAttachmentJSON(decoder *json.Decoder) error {
-	var extra any
-	if err := decoder.Decode(&extra); err != io.EOF {
-		if err == nil {
-			return fmt.Errorf("--file-infos JSON 包含多余内容")
-		}
-		return fmt.Errorf("--file-infos JSON 解析失败: %w", err)
-	}
-	return nil
-}
-
-func validateOAAttachmentFileInfos(cmd *cobra.Command, _ []string) error {
-	raw, _ := cmd.Flags().GetString("file-infos")
-	_, err := parseOAAttachmentFileInfos(raw)
-	return err
-}
-
-func validateOAPreviewFileIDs(cmd *cobra.Command, _ []string) error {
-	fileIDs, _ := cmd.Flags().GetStringSlice("file-ids")
-	if len(fileIDs) > 20 {
-		return fmt.Errorf("--file-ids 最多包含 20 个附件 ID")
-	}
-	for index, fileID := range fileIDs {
-		if strings.TrimSpace(fileID) == "" {
-			return fmt.Errorf("--file-ids 第 %d 项不能为空", index+1)
-		}
-	}
-	return nil
-}
-
-func callOAAttachmentResult(cmd *cobra.Command, tool string, args map[string]any) (output.CommandResult, error) {
-	data, err := CallMCPToolDataOnServer(cmd.Context(), "oa", tool, args)
-	if err != nil {
-		return nil, err
-	}
-	response, ok := data.(map[string]any)
-	if !ok {
-		return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值不是 JSON 对象", tool))
-	}
-	result, ok := response["result"]
-	if !ok {
-		return nil, apperrors.NewInternal(fmt.Sprintf("oa/%s 返回值缺少 result", tool))
-	}
-	return output.Success(result), nil
-}
-
-func newOAAttachmentCommand() *cobra.Command {
-	attachmentCmd := &cobra.Command{
-		Use:   "attachment",
-		Short: "审批附件授权与下载链接",
-		RunE:  groupRunE,
-	}
-
-	downloadURLCmd := NewLeafCommand(LeafSpec{
-		Use:           "download-url",
-		Short:         "获取审批附件下载链接",
-		Example:       "  dws oa approval attachment download-url --instance-id <processInstanceId> --file-id <fileId>",
-		Server:        "oa",
-		Tool:          "get_attachment_download_url",
-		OutputRollout: output.RolloutUnifiedActive,
-		ResultCall:    callOAAttachmentResult,
-		Flags: []LeafFlag{
-			{Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true},
-			{Name: "file-id", Usage: "审批附件文件 ID (必填)", Bind: "fileId", Trim: true, Required: true, MarkRequired: true},
-			{Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"},
-		},
-		Safety: contract.SafetySpec{
-			Effect: "read", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "oa",
-				Name:           "get_attachment_download_url",
-				CanonicalPath:  "oa.get_attachment_download_url",
-				CLIPath:        "oa approval attachment download-url",
-				PrimaryCLIPath: "oa approval attachment download-url",
-			},
-			Description: "获取审批附件下载授权并生成临时下载链接",
-			Result: &contract.ResultSpec{
-				Outcomes:       []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema:     json.RawMessage(`{"type":"object","description":"审批附件临时下载信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"downloadUri":{"type":"string","description":"带临时授权签名的附件下载链接"},"class":{"type":"string","description":"服务端响应类型标识"},"fileId":{"type":"string","description":"审批附件文件 ID"}},"required":["spaceId","agentId","downloadUri","fileId"],"additionalProperties":true}`),
-				SensitivePaths: []string{"downloadUri"},
-			},
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_attachment_download_url"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "获取审批实例中指定附件的临时下载链接",
-				UseWhen:      []string{"已从审批详情获得 processInstanceId 和 fileId，需要获取附件下载链接时"},
-				AvoidWhen: []string{
-					"只需查看审批表单和附件元数据时使用 dws oa approval detail",
-					"需要将附件真正保存到本地时不要误认为本命令会下载文件；它只返回链接",
-				},
-				Examples: []string{"dws oa approval attachment download-url --instance-id <processInstanceId> --file-id <fileId>"},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"},
-				{Name: "file-id", Property: "fileId", InterfaceType: "string"},
-				{Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"},
-			},
-		},
-	})
-
-	authorizeDownloadCmd := NewLeafCommand(LeafSpec{
-		Use:           "authorize-download",
-		Short:         "授权当前用户下载审批钉盘文件",
-		Long:          "批量授权当前用户下载指定的审批钉盘文件。",
-		Example:       `  dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`,
-		Server:        "oa",
-		Tool:          "auth_download_file",
-		OutputRollout: output.RolloutUnifiedActive,
-		ResultCall:    callOAAttachmentResult,
-		Flags: []LeafFlag{
-			{
-				Name: "file-infos", Usage: "审批钉盘文件信息 JSON 数组 (必填)",
-				Bind: "fileInfos", Trim: true, Required: true, MarkRequired: true,
-				Transform: func(raw string) (any, error) {
-					return parseOAAttachmentFileInfos(raw)
-				},
-			},
-		},
-		Constraints: []LeafConstraint{{
-			Kind: corecmd.Custom, Flags: []string{"file-infos"},
-			Description: "文件信息列表必须包含 1 至 10 项",
-		}},
-		Validate: validateOAAttachmentFileInfos,
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "oa",
-				Name:           "auth_download_file",
-				CanonicalPath:  "oa.auth_download_file",
-				CLIPath:        "oa approval attachment authorize-download",
-				PrimaryCLIPath: "oa approval attachment authorize-download",
-			},
-			Description: "批量授权当前用户下载指定的审批钉盘文件",
-			Result: &contract.ResultSpec{
-				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema: json.RawMessage(`{"type":"boolean","description":"是否成功为当前用户授予审批钉盘文件下载权限"}`),
-			},
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_download_file"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "使用审批钉盘 spaceId/fileId 批量授权当前用户下载文件",
-				UseWhen:      []string{"已有一个或多个审批钉盘文件的 spaceId 和 fileId，需要为当前用户取得下载权限时"},
-				AvoidWhen: []string{
-					"需要生成单个审批附件下载链接时使用 attachment download-url",
-					"需要授权在审批单内预览附件时使用 attachment authorize-preview",
-				},
-				Examples: []string{`dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]'`},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "file-infos", Property: "fileInfos", InterfaceType: "array"},
-			},
-		},
-	})
-
-	authorizePreviewCmd := NewLeafCommand(LeafSpec{
-		Use:           "authorize-preview",
-		Short:         "授权当前用户预览审批附件",
-		Long:          "批量授权当前用户预览审批单中的附件。",
-		Example:       "  dws oa approval attachment authorize-preview --instance-id <processInstanceId> --file-ids <fileId1>,<fileId2>",
-		Server:        "oa",
-		Tool:          "auth_preview_attachment",
-		OutputRollout: output.RolloutUnifiedActive,
-		ResultCall:    callOAAttachmentResult,
-		Flags: []LeafFlag{
-			{Name: "instance-id", Usage: "审批实例 ID (必填)", Bind: "processInstanceId", Trim: true, Required: true, MarkRequired: true},
-			{Name: "file-ids", Usage: "附件 ID 列表，多个用逗号分隔 (必填)", Kind: LeafStringSlice, Bind: "fileIdList", Required: true, MarkRequired: true},
-			{Name: "with-comment-attachment", Usage: "是否包含评论中的附件", Kind: LeafBool, Bind: "withCommentAttachment"},
-		},
-		Constraints: []LeafConstraint{{
-			Kind: corecmd.Custom, Flags: []string{"file-ids"},
-			Description: "附件 ID 列表最多包含 20 项且每项不能为空",
-		}},
-		Validate: validateOAPreviewFileIDs,
-		Safety: contract.SafetySpec{
-			Effect: "write", Risk: "low",
-			Confirmation: "not_required", Idempotency: "idempotent",
-		},
-		Contract: LeafContract{
-			Identity: contract.ToolIdentitySpec{
-				ProductID:      "oa",
-				Name:           "auth_preview_attachment",
-				CanonicalPath:  "oa.auth_preview_attachment",
-				CLIPath:        "oa approval attachment authorize-preview",
-				PrimaryCLIPath: "oa approval attachment authorize-preview",
-			},
-			Description: "批量授权当前用户预览审批单中的附件",
-			Result: &contract.ResultSpec{
-				Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
-				DataSchema: json.RawMessage(`{"type":"object","description":"审批附件预览授权信息","properties":{"spaceId":{"type":"integer","description":"审批附件所在钉盘空间 ID"},"agentId":{"type":"integer","description":"审批应用 Agent ID"},"class":{"type":"string","description":"服务端响应类型标识"}},"required":["spaceId","agentId"],"additionalProperties":true}`),
-			},
-			Interface: &contract.InterfaceSpec{
-				Mode:         "mcp",
-				Availability: "available",
-				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "auth_preview_attachment"},
-			},
-			Selection: contract.SelectionSpec{
-				AgentSummary: "按审批实例和附件 ID 列表授权当前用户预览附件",
-				UseWhen:      []string{"已有 processInstanceId 和附件 fileId 列表，需要在审批场景中批量取得预览权限时"},
-				AvoidWhen: []string{
-					"需要下载权限而不是预览权限时使用 attachment authorize-download",
-					"需要直接获得单个附件临时下载链接时使用 attachment download-url",
-				},
-				Examples: []string{"dws oa approval attachment authorize-preview --instance-id <processInstanceId> --file-ids <fileId1>,<fileId2>"},
-			},
-			Parameters: []contract.ParamDecl{
-				{Name: "instance-id", Property: "processInstanceId", InterfaceType: "string"},
-				{Name: "file-ids", Property: "fileIdList", InterfaceType: "array"},
-				{Name: "with-comment-attachment", Property: "withCommentAttachment", InterfaceType: "boolean"},
-			},
-		},
-	})
-
-	attachmentCmd.AddCommand(downloadURLCmd, authorizeDownloadCmd, authorizePreviewCmd)
-	return attachmentCmd
-}
-
 // ──────────────────────────────────────────────────────────
 // dws oa — OA 审批
 // MCP tools（tools/list）: list_pending_approvals, get_processInstance_detail,
@@ -329,8 +49,7 @@ func newOAAttachmentCommand() *cobra.Command {
 // get_processInstance_records, list_initiated_instances, list_pending_tasks,
 // list_user_visible_process, append_task, search_form, oa_ding_user, revert_task,
 // get_inst_revert_activities, get_process_schema, forecast_process,
-// start_process_instance, get_attachment_download_url, auth_download_file,
-// auth_preview_attachment
+// start_process_instance
 // ──────────────────────────────────────────────────────────

 func newOaCommand() *cobra.Command {
@@ -339,10 +58,9 @@ func newOaCommand() *cobra.Command {
 	contract.RegisterProductDecl(contract.ProductDecl{
 		ID: "oa",
 		Selection: contract.ProductSelectionDecl{
-			AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送、评论与附件授权",
+			AgentSummary: "查询和处理 OA 审批实例、任务、记录、抄送与评论",
 			UseWhen: []string{
 				"查看待审、已办、已发起或抄送审批，并执行同意、拒绝、撤销、转交等审批动作时",
-				"获取审批附件下载链接，或为当前用户授权下载、预览审批附件时",
 			},
 			AvoidWhen: []string{
 				"不要用于普通待办任务或工作日志；需要实时监听未来的审批任务/实例事件时使用 event consume",
@@ -352,7 +70,7 @@ func newOaCommand() *cobra.Command {
 	root := &cobra.Command{
 		Use:   "oa",
 		Short: "OA 审批 / 同意 / 拒绝 / 撤销",
-		Long:  `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表与附件授权。`,
+		Long:  `管理钉钉 OA 审批：待办查询、审批详情、同意、拒绝、撤销、操作记录、已发起列表、表单列表。`,
 		RunE:  groupRunE,
 	}

@@ -1658,7 +1376,6 @@ func newOaCommand() *cobra.Command {
 		approvalForecastCmd,
 		approvalCreateCmd,
 	)
-	approvalCmd.AddCommand(newOAAttachmentCommand())
 	root.AddCommand(approvalCmd)

 	return root
@@ -1,339 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-
-package helpers
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"os"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
-	"github.com/spf13/cobra"
-)
-
-func executeOAAttachmentCommandCapturingOutput(t *testing.T, caller *scriptedToolCaller, args ...string) (string, error) {
-	t.Helper()
-	testseam.Protect(t, &deps)
-	testseam.Swap(t, &os.Args, []string{"dws", "oa"})
-	InitDeps(caller)
-	var stdout bytes.Buffer
-	deps.Out.w = &stdout
-	deps.Out.errW = io.Discard
-
-	cmd := newOaCommand()
-	cmd.PersistentFlags().Bool("yes", false, "跳过确认")
-	cmd.PersistentFlags().String("format", caller.Format(), "输出格式")
-	ctx, _ := output.WithResultStore(context.Background())
-	cmd.SetContext(ctx)
-	cmd.PersistentPostRunE = func(executed *cobra.Command, _ []string) error {
-		_, _, err := output.EmitStoredResult(executed)
-		return err
-	}
-	cmd.SilenceErrors = true
-	cmd.SilenceUsage = true
-	cmd.SetOut(&stdout)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs(args)
-	err := cmd.Execute()
-	return stdout.String(), err
-}
-
-func TestCrossPlatformCoverageOAAttachmentDownloadURLPreservesSignedQuery(t *testing.T) {
-	const response = `{"result":{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"},"success":true}`
-	commandArgs := []string{
-		"approval", "attachment", "download-url",
-		"--instance-id", "instance-1",
-		"--file-id", "file-1",
-	}
-	wantArgs := map[string]any{
-		"processInstanceId": "instance-1",
-		"fileId":            "file-1",
-	}
-
-	t.Run("json", func(t *testing.T) {
-		caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: response}}}
-		stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...)
-		if err != nil {
-			t.Fatalf("execute command: %v", err)
-		}
-		if caller.server != "oa" || caller.tool != "get_attachment_download_url" {
-			t.Fatalf("called %s/%s, want oa/get_attachment_download_url", caller.server, caller.tool)
-		}
-		if !reflect.DeepEqual(caller.args, wantArgs) {
-			t.Fatalf("args = %#v, want %#v", caller.args, wantArgs)
-		}
-		if !strings.Contains(stdout, "&OSSAccessKeyId=") || !strings.Contains(stdout, "&Signature=") {
-			t.Fatalf("stdout does not preserve signed query separators: %q", stdout)
-		}
-		if strings.Contains(stdout, `\u0026`) {
-			t.Fatalf("stdout contains escaped query separator: %q", stdout)
-		}
-		var envelope map[string]any
-		if err := json.Unmarshal([]byte(stdout), &envelope); err != nil {
-			t.Fatalf("decode unified output: %v", err)
-		}
-		if envelope["ok"] != true || envelope["outcome"] != "success" {
-			t.Fatalf("unified envelope = %#v", envelope)
-		}
-		data, ok := envelope["data"].(map[string]any)
-		if !ok || !strings.Contains(data["downloadUri"].(string), "&Signature=") {
-			t.Fatalf("unified data = %#v", envelope["data"])
-		}
-	})
-
-	t.Run("raw compatibility", func(t *testing.T) {
-		caller := &scriptedToolCaller{format: "raw", steps: []scriptedToolStep{{text: response}}}
-		stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, commandArgs...)
-		if err != nil {
-			t.Fatalf("execute command: %v", err)
-		}
-		const want = `{"downloadUri":"https://example.test/file?Expires=1&OSSAccessKeyId=2&Signature=3"}` + "\n"
-		if stdout != want {
-			t.Fatalf("stdout = %q, want %q", stdout, want)
-		}
-	})
-}
-
-func TestCrossPlatformCoverageOAAttachmentProjectsUnifiedBusinessData(t *testing.T) {
-	tests := []struct {
-		name     string
-		args     []string
-		response string
-		wantData any
-	}{
-		{
-			name:     "download authorization",
-			args:     []string{"approval", "attachment", "authorize-download", "--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`},
-			response: `{"result":true,"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`,
-			wantData: true,
-		},
-		{
-			name:     "preview authorization",
-			args:     []string{"approval", "attachment", "authorize-preview", "--instance-id", "instance-1", "--file-ids", "file-1"},
-			response: `{"result":{"spaceId":27827223951,"agentId":4115627346,"class":"com.dingtalk.bpms.oapi.vo.AppSpaceResponse"},"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`,
-			wantData: map[string]any{
-				"spaceId": float64(27827223951), "agentId": float64(4115627346),
-				"class": "com.dingtalk.bpms.oapi.vo.AppSpaceResponse",
-			},
-		},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: test.response}}}
-			stdout, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...)
-			if err != nil {
-				t.Fatalf("execute command: %v", err)
-			}
-			var envelope map[string]any
-			if err := json.Unmarshal([]byte(stdout), &envelope); err != nil {
-				t.Fatalf("decode unified output: %v", err)
-			}
-			if envelope["ok"] != true || envelope["outcome"] != "success" || !reflect.DeepEqual(envelope["data"], test.wantData) {
-				t.Fatalf("unified envelope = %#v, want data %#v", envelope, test.wantData)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageOAAttachmentRejectsSuccessWithoutResult(t *testing.T) {
-	caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{{text: `{"success":true,"dingOpenErrcode":0,"errorMsg":"ok"}`}}}
-	_, err := executeOAAttachmentCommandCapturingOutput(t, caller,
-		"approval", "attachment", "authorize-download",
-		"--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`,
-	)
-	if err == nil || !strings.Contains(err.Error(), "缺少 result") {
-		t.Fatalf("execute error = %v, want missing result", err)
-	}
-}
-
-func TestCrossPlatformCoverageOAAttachmentRejectsInvalidToolResult(t *testing.T) {
-	tests := []struct {
-		name string
-		step scriptedToolStep
-		want string
-	}{
-		{name: "non-object response", step: scriptedToolStep{text: `[]`}, want: "不是 JSON 对象"},
-		{name: "tool error", step: scriptedToolStep{err: errors.New("tool unavailable")}, want: "tool unavailable"},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{format: "json", steps: []scriptedToolStep{test.step}}
-			_, err := executeOAAttachmentCommandCapturingOutput(t, caller,
-				"approval", "attachment", "authorize-download",
-				"--file-infos", `[{"spaceId":27827223951,"fileId":"file-1"}]`,
-			)
-			if err == nil || !strings.Contains(err.Error(), test.want) {
-				t.Fatalf("execute error = %v, want %q", err, test.want)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageOAAttachmentPayloads(t *testing.T) {
-	tests := []struct {
-		name     string
-		args     []string
-		wantTool string
-		check    func(*testing.T, map[string]any)
-	}{
-		{
-			name: "download URL",
-			args: []string{
-				"approval", "attachment", "download-url",
-				"--instance-id", "instance-1",
-				"--file-id", "file-1",
-				"--with-comment-attachment=false",
-			},
-			wantTool: "get_attachment_download_url",
-			check: func(t *testing.T, got map[string]any) {
-				t.Helper()
-				if got["processInstanceId"] != "instance-1" || got["fileId"] != "file-1" {
-					t.Fatalf("download identifiers = %#v", got)
-				}
-				if value, ok := got["withCommentAttachment"].(bool); !ok || value {
-					t.Fatalf("withCommentAttachment = %#v, want explicit false", got["withCommentAttachment"])
-				}
-			},
-		},
-		{
-			name: "download authorization",
-			args: []string{
-				"approval", "attachment", "authorize-download",
-				"--file-infos", `[{"spaceId":27827223951,"fileId":"file-2"}]`,
-			},
-			wantTool: "auth_download_file",
-			check: func(t *testing.T, got map[string]any) {
-				t.Helper()
-				infos, ok := got["fileInfos"].([]map[string]any)
-				if !ok || len(infos) != 1 {
-					t.Fatalf("fileInfos = %#v", got["fileInfos"])
-				}
-				if infos[0]["spaceId"] != json.Number("27827223951") || infos[0]["fileId"] != "file-2" {
-					t.Fatalf("fileInfos[0] = %#v", infos[0])
-				}
-			},
-		},
-		{
-			name: "preview authorization",
-			args: []string{
-				"approval", "attachment", "authorize-preview",
-				"--instance-id", "instance-2",
-				"--file-ids", "file-3,file-4",
-				"--with-comment-attachment",
-			},
-			wantTool: "auth_preview_attachment",
-			check: func(t *testing.T, got map[string]any) {
-				t.Helper()
-				if got["processInstanceId"] != "instance-2" || got["withCommentAttachment"] != true {
-					t.Fatalf("preview scalar payload = %#v", got)
-				}
-				ids, ok := got["fileIdList"].([]string)
-				if !ok || len(ids) != 2 || ids[0] != "file-3" || ids[1] != "file-4" {
-					t.Fatalf("fileIdList = %#v", got["fileIdList"])
-				}
-			},
-		},
-		{
-			name: "optional boolean omitted",
-			args: []string{
-				"approval", "attachment", "download-url",
-				"--instance-id", "instance-3",
-				"--file-id", "file-5",
-			},
-			wantTool: "get_attachment_download_url",
-			check: func(t *testing.T, got map[string]any) {
-				t.Helper()
-				if _, exists := got["withCommentAttachment"]; exists {
-					t.Fatalf("optional withCommentAttachment should be omitted: %#v", got)
-				}
-			},
-		},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":{},"success":true}`}}}
-			if _, err := executeOAAttachmentCommandCapturingOutput(t, caller, test.args...); err != nil {
-				t.Fatalf("execute command: %v", err)
-			}
-			if caller.server != "oa" || caller.tool != test.wantTool {
-				t.Fatalf("called %s/%s, want oa/%s", caller.server, caller.tool, test.wantTool)
-			}
-			test.check(t, caller.args)
-		})
-	}
-}
-
-func TestCrossPlatformCoverageOAAttachmentRejectsInvalidFileInfos(t *testing.T) {
-	valid := `{"spaceId":27827223951,"fileId":"file-1"}`
-	tests := []struct {
-		name string
-		raw  string
-	}{
-		{name: "malformed JSON", raw: `[{`},
-		{name: "null", raw: `null`},
-		{name: "not array", raw: `{}`},
-		{name: "empty array", raw: `[]`},
-		{name: "more than ten", raw: `[` + strings.Repeat(valid+`,`, 10) + valid + `]`},
-		{name: "missing space ID", raw: `[{"fileId":"file-1"}]`},
-		{name: "string space ID", raw: `[{"spaceId":"27827223951","fileId":"file-1"}]`},
-		{name: "missing file ID", raw: `[{"spaceId":27827223951}]`},
-		{name: "numeric file ID", raw: `[{"spaceId":27827223951,"fileId":232271651278}]`},
-		{name: "blank file ID", raw: `[{"spaceId":27827223951,"fileId":"  "}]`},
-		{name: "unknown property", raw: `[{"spaceId":27827223951,"fileId":"file-1","extra":true}]`},
-		{name: "trailing JSON", raw: `[` + valid + `] {}`},
-		{name: "malformed trailing JSON", raw: `[` + valid + `] {`},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{}
-			err := executeOACommand(t, caller,
-				"approval", "attachment", "authorize-download",
-				"--file-infos", test.raw,
-			)
-			if err == nil {
-				t.Fatalf("fileInfos %q unexpectedly succeeded", test.raw)
-			}
-			if caller.calls != 0 {
-				t.Fatalf("invalid fileInfos made %d MCP call(s)", caller.calls)
-			}
-		})
-	}
-}
-
-func TestCrossPlatformCoverageOAAttachmentRejectsInvalidPreviewFileIDs(t *testing.T) {
-	tests := []struct {
-		name string
-		raw  string
-	}{
-		{name: "separator only", raw: `,`},
-		{name: "blank item", raw: `file-1, ,file-2`},
-		{name: "more than twenty", raw: strings.Repeat("file,", 20) + "file"},
-	}
-
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			caller := &scriptedToolCaller{}
-			err := executeOACommand(t, caller,
-				"approval", "attachment", "authorize-preview",
-				"--instance-id", "instance-1",
-				"--file-ids", test.raw,
-			)
-			if err == nil {
-				t.Fatalf("file IDs %q unexpectedly succeeded", test.raw)
-			}
-			if caller.calls != 0 {
-				t.Fatalf("invalid file IDs made %d MCP call(s)", caller.calls)
-			}
-		})
-	}
-}
@@ -1,499 +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.
-
-package helpers
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
-	"github.com/spf13/cobra"
-)
-
-type nativePrimaryParamCall struct {
-	server string
-	tool   string
-	args   map[string]any
-}
-
-type nativePrimaryParamCaller struct {
-	calls []nativePrimaryParamCall
-}
-
-func (c *nativePrimaryParamCaller) CallTool(_ context.Context, server, tool string, args map[string]any) (*edition.ToolResult, error) {
-	copied := make(map[string]any, len(args))
-	for key, value := range args {
-		copied[key] = value
-	}
-	c.calls = append(c.calls, nativePrimaryParamCall{server: server, tool: tool, args: copied})
-
-	switch tool {
-	case "init_conversation_file_upload", "init_todo_file_upload":
-		return textToolResult(`{"resourceUrl":"https://upload.invalid/file","uploadKey":"upload-key"}`), nil
-	case "commit_conversation_file_upload":
-		fileName, _ := args["fileName"].(string)
-		payload, _ := json.Marshal(map[string]any{
-			"dentryId":    123,
-			"spaceId":     456,
-			"downloadUrl": "https://download.invalid/" + fileName,
-		})
-		return textToolResult(string(payload)), nil
-	case "commit_todo_file_upload":
-		return textToolResult(`{"dentryId":123,"spaceId":456}`), nil
-	default:
-		return textToolResult(`{}`), nil
-	}
-}
-
-func (*nativePrimaryParamCaller) Format() string { return "json" }
-func (*nativePrimaryParamCaller) DryRun() bool   { return false }
-func (*nativePrimaryParamCaller) Fields() string { return "" }
-func (*nativePrimaryParamCaller) JQ() string     { return "" }
-
-func (c *nativePrimaryParamCaller) lastCall(t *testing.T, tool string) nativePrimaryParamCall {
-	t.Helper()
-	for i := len(c.calls) - 1; i >= 0; i-- {
-		if c.calls[i].tool == tool {
-			return c.calls[i]
-		}
-	}
-	t.Fatalf("tool %q not called; calls = %#v", tool, c.calls)
-	return nativePrimaryParamCall{}
-}
-
-func executeNativePrimaryTodo(t *testing.T, caller edition.ToolCaller, args ...string) error {
-	t.Helper()
-	previousDeps, previousArgs := deps, os.Args
-	os.Args = []string{"dws", "todo"}
-	InitDeps(caller)
-	deps.Out.w = io.Discard
-	deps.Out.errW = io.Discard
-	t.Cleanup(func() {
-		deps = previousDeps
-		os.Args = previousArgs
-	})
-
-	cmd := newTodoCommand()
-	if cmd.PersistentFlags().Lookup("yes") == nil {
-		cmd.PersistentFlags().Bool("yes", false, "confirm execution")
-	}
-	if cmd.PersistentFlags().Lookup("dry-run") == nil {
-		cmd.PersistentFlags().Bool("dry-run", false, "preview without executing")
-	}
-	cmd.SilenceErrors = true
-	cmd.SilenceUsage = true
-	cmd.SetOut(io.Discard)
-	cmd.SetErr(io.Discard)
-	cmd.SetArgs(args)
-	return cmd.ExecuteContext(context.Background())
-}
-
-func findNativePrimaryLeaf(t *testing.T, root *cobra.Command, path ...string) *cobra.Command {
-	t.Helper()
-	leaf, remaining, err := root.Find(path)
-	if err != nil {
-		t.Fatalf("find %v: %v", path, err)
-	}
-	if len(remaining) != 0 {
-		t.Fatalf("find %v left arguments %v", path, remaining)
-	}
-	return leaf
-}
-
-func assertNativePrimaryFlagPair(t *testing.T, cmd *cobra.Command, primary, legacy string) {
-	t.Helper()
-	primaryFlag := cmd.Flags().Lookup(primary)
-	if primaryFlag == nil || primaryFlag.Hidden {
-		t.Fatalf("%s --%s = %#v, want visible Primary", cmd.CommandPath(), primary, primaryFlag)
-	}
-	legacyFlag := cmd.Flags().Lookup(legacy)
-	if legacyFlag == nil || !legacyFlag.Hidden {
-		t.Fatalf("%s --%s = %#v, want hidden compatibility alias", cmd.CommandPath(), legacy, legacyFlag)
-	}
-	if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOf]; len(got) != 1 || got[0] != primary {
-		t.Fatalf("%s --%s alias_of = %#v, want %q", cmd.CommandPath(), legacy, got, primary)
-	}
-	if got := legacyFlag.Annotations[runtimeannotate.AnnotationFlagAliasOrigin]; len(got) != 1 || got[0] != runtimeannotate.FlagAliasOriginCorecmdV1 {
-		t.Fatalf("%s --%s alias_origin = %#v, want %q", cmd.CommandPath(), legacy, got, runtimeannotate.FlagAliasOriginCorecmdV1)
-	}
-}
-
-func TestNativePrimaryParamFlagSurfaces(t *testing.T) {
-	aisearch := newAisearchCommand()
-	assertNativePrimaryFlagPair(t, aisearch, "query", "keyword")
-	person := findNativePrimaryLeaf(t, aisearch, "person")
-	assertNativePrimaryFlagPair(t, person, "query", "keyword")
-	for _, cmd := range []*cobra.Command{aisearch, person} {
-		if got := cmd.Flags().Lookup("keyword").Shorthand; got != "w" {
-			t.Fatalf("%s --keyword shorthand = %q, want preserved -w", cmd.CommandPath(), got)
-		}
-		if got := cmd.Flags().Lookup("query").Shorthand; got != "" {
-			t.Fatalf("%s --query shorthand = %q, want none", cmd.CommandPath(), got)
-		}
-	}
-
-	chat := newChatCommand()
-	send := findNativePrimaryLeaf(t, chat, "message", "send")
-	assertNativePrimaryFlagPair(t, send, "content", "text")
-	assertNativePrimaryFlagPair(t, send, "file", "file-path")
-	sendByWebhook := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook")
-	assertNativePrimaryFlagPair(t, sendByWebhook, "content", "text")
-	sendByBot := findNativePrimaryLeaf(t, chat, "message", "send-by-bot")
-	for _, name := range []string{"text", "file-path"} {
-		flag := sendByBot.Flags().Lookup(name)
-		if flag == nil || flag.Hidden {
-			t.Fatalf("%s --%s = %#v, want unchanged visible Primary", sendByBot.CommandPath(), name, flag)
-		}
-	}
-	for _, name := range []string{"content", "file"} {
-		if flag := sendByBot.Flags().Lookup(name); flag != nil && !flag.Hidden {
-			t.Fatalf("%s --%s = %#v, pending migration must not become visible", sendByBot.CommandPath(), name, flag)
-		}
-	}
-	reply := findNativePrimaryLeaf(t, chat, "message", "reply")
-	assertNativePrimaryFlagPair(t, reply, "group", "conversation-id")
-	assertNativePrimaryFlagPair(t, reply, "content", "text")
-
-	doc := newDocCommand()
-	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "insert"), "content", "text")
-	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, doc, "block", "update"), "content", "text")
-
-	todo := newTodoCommand()
-	assertNativePrimaryFlagPair(t, findNativePrimaryLeaf(t, todo, "task", "add-attachment"), "file", "file-path")
-}
-
-type nativePrimaryParamSpelling struct {
-	name string
-	args []string
-	want string
-}
-
-func nativePrimaryParamSpellings(primary, legacy string) []nativePrimaryParamSpelling {
-	return []nativePrimaryParamSpelling{
-		{name: "legacy only", args: []string{"--" + legacy, "legacy-value"}, want: "legacy-value"},
-		{name: "primary only", args: []string{"--" + primary, "primary-value"}, want: "primary-value"},
-		{name: "both legacy wins", args: []string{"--" + primary, "primary-value", "--" + legacy, "legacy-value"}, want: "legacy-value"},
-	}
-}
-
-func nativePrimaryJSONField(t *testing.T, raw any, field string) string {
-	t.Helper()
-	encoded, ok := raw.(string)
-	if !ok {
-		t.Fatalf("payload = %#v, want JSON string", raw)
-	}
-	var payload map[string]any
-	if err := json.Unmarshal([]byte(encoded), &payload); err != nil {
-		t.Fatalf("decode payload %q: %v", encoded, err)
-	}
-	value, _ := payload[field].(string)
-	return value
-}
-
-func nativePrimaryParagraphText(t *testing.T, call nativePrimaryParamCall) string {
-	t.Helper()
-	element, ok := call.args["element"].(map[string]any)
-	if !ok {
-		t.Fatalf("%s element = %#v", call.tool, call.args["element"])
-	}
-	paragraph, ok := element["paragraph"].(map[string]any)
-	if !ok {
-		t.Fatalf("%s paragraph = %#v", call.tool, element["paragraph"])
-	}
-	text, _ := paragraph["text"].(string)
-	return text
-}
-
-func TestNativePrimaryParamTextPayloadCompatibility(t *testing.T) {
-	previousDeps, previousArgs := deps, os.Args
-	os.Args = []string{"dws", "chat"}
-	t.Cleanup(func() {
-		deps = previousDeps
-		os.Args = previousArgs
-	})
-
-	t.Run("chat message send text to content", func(t *testing.T) {
-		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"message", "send", "--group", "cid", "--title", "fixed-title"}
-				args = append(args, spelling.args...)
-				if err := runChatCoverageCommand(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "send_personal_message")
-				if got := nativePrimaryJSONField(t, call.args["content"], "text"); got != spelling.want {
-					t.Fatalf("content.text = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-
-	t.Run("chat message send-by-webhook text to content", func(t *testing.T) {
-		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"message", "send-by-webhook", "--token", "token", "--title", "fixed-title"}
-				args = append(args, spelling.args...)
-				if err := runChatCoverageCommand(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "send_message_by_custom_robot")
-				if got, _ := call.args["text"].(string); got != spelling.want {
-					t.Fatalf("text = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-
-	t.Run("chat message reply conversation-id to group", func(t *testing.T) {
-		for _, spelling := range nativePrimaryParamSpellings("group", "conversation-id") {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "fixed-content"}
-				args = append(args, spelling.args...)
-				if err := runChatCoverageCommand(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "send_personal_message")
-				if got, _ := call.args["openConversationId"].(string); got != spelling.want {
-					t.Fatalf("openConversationId = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-
-	t.Run("chat message reply text to content", func(t *testing.T) {
-		for _, spelling := range nativePrimaryParamSpellings("content", "text") {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID}
-				args = append(args, spelling.args...)
-				if err := runChatCoverageCommand(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "send_personal_message")
-				if got := nativePrimaryJSONField(t, call.args["content"], "content"); got != spelling.want {
-					t.Fatalf("reply content = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-
-	for _, command := range []struct {
-		name string
-		path []string
-		tool string
-	}{
-		{name: "doc block insert text to content", path: []string{"block", "insert", "--node", "node"}, tool: "insert_document_block"},
-		{name: "doc block update text to content", path: []string{"block", "update", "--node", "node", "--block-id", "block"}, tool: "update_document_block"},
-	} {
-		command := command
-		t.Run(command.name, func(t *testing.T) {
-			for _, spelling := range nativePrimaryParamSpellings("content", "text") {
-				t.Run(spelling.name, func(t *testing.T) {
-					caller := &nativePrimaryParamCaller{}
-					args := append(append([]string(nil), command.path...), spelling.args...)
-					if err := runDocCoverageCommand(t, caller, args...); err != nil {
-						t.Fatal(err)
-					}
-					call := caller.lastCall(t, command.tool)
-					if got := nativePrimaryParagraphText(t, call); got != spelling.want {
-						t.Fatalf("paragraph text = %q, want %q; payload = %#v", got, spelling.want, call.args)
-					}
-				})
-			}
-		})
-	}
-}
-
-func TestNativePrimaryParamFilePayloadCompatibility(t *testing.T) {
-	previousDeps, previousPut, previousArgs := deps, httpPutFile, os.Args
-	t.Cleanup(func() {
-		deps = previousDeps
-		httpPutFile = previousPut
-		os.Args = previousArgs
-	})
-	httpPutFile = func(context.Context, string, map[string]string, string, int64) error { return nil }
-
-	dir := t.TempDir()
-	legacyPath := filepath.Join(dir, "legacy-file.txt")
-	primaryPath := filepath.Join(dir, "primary-file.txt")
-	if err := os.WriteFile(legacyPath, []byte("legacy"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(primaryPath, []byte("primary"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	spellings := []nativePrimaryParamSpelling{
-		{name: "legacy only", args: []string{"--file-path", legacyPath}, want: filepath.Base(legacyPath)},
-		{name: "primary only", args: []string{"--file", primaryPath}, want: filepath.Base(primaryPath)},
-		{name: "both legacy wins", args: []string{"--file", primaryPath, "--file-path", legacyPath}, want: filepath.Base(legacyPath)},
-	}
-
-	t.Run("chat message send file-path to file", func(t *testing.T) {
-		os.Args = []string{"dws", "chat"}
-		for _, spelling := range spellings {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"message", "send", "--group", "cid", "--msg-type", "file"}
-				args = append(args, spelling.args...)
-				if err := runChatCoverageCommand(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "send_personal_message")
-				if got := nativePrimaryJSONField(t, call.args["content"], "fileName"); got != spelling.want {
-					t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-
-	t.Run("todo task add-attachment file-path to file", func(t *testing.T) {
-		os.Args = []string{"dws", "todo"}
-		for _, spelling := range spellings {
-			t.Run(spelling.name, func(t *testing.T) {
-				caller := &nativePrimaryParamCaller{}
-				args := []string{"task", "add-attachment", "--task-id", "42"}
-				args = append(args, spelling.args...)
-				if err := executeNativePrimaryTodo(t, caller, args...); err != nil {
-					t.Fatal(err)
-				}
-				call := caller.lastCall(t, "add_todo_attachment")
-				request, ok := call.args["todoAttachmentAddRequest"].(map[string]any)
-				if !ok {
-					t.Fatalf("request = %#v", call.args)
-				}
-				attachments, ok := request["attachmentList"].([]any)
-				if !ok || len(attachments) != 1 {
-					t.Fatalf("attachments = %#v", request["attachmentList"])
-				}
-				attachment, ok := attachments[0].(map[string]any)
-				if !ok {
-					t.Fatalf("attachment = %#v", attachments[0])
-				}
-				if got, _ := attachment["fileName"].(string); got != spelling.want {
-					t.Fatalf("fileName = %q, want %q; payload = %#v", got, spelling.want, call.args)
-				}
-			})
-		}
-	})
-}
-
-func nativePrimaryErrorMentionsFlag(message, name string) bool {
-	return strings.Contains(message, "--"+name) || strings.Contains(message, fmt.Sprintf("%q", name))
-}
-
-func assertNativePrimaryErrorHint(t *testing.T, err error, primary, legacy string) {
-	t.Helper()
-	if err == nil {
-		t.Fatalf("missing --%s returned nil", primary)
-	}
-	message := err.Error()
-	if !nativePrimaryErrorMentionsFlag(message, primary) {
-		t.Fatalf("error %q does not recommend --%s", message, primary)
-	}
-	if nativePrimaryErrorMentionsFlag(message, legacy) {
-		t.Fatalf("error %q still recommends legacy --%s", message, legacy)
-	}
-}
-
-func TestNativePrimaryParamMissingErrorsRecommendPrimaryOnly(t *testing.T) {
-	previousDeps, previousArgs := deps, os.Args
-	t.Cleanup(func() {
-		deps = previousDeps
-		os.Args = previousArgs
-	})
-
-	installScriptedCaller(t, &scriptedToolCaller{})
-	assertNativePrimaryErrorHint(t, executeFilterCoverage(t, newAisearchCommand(), "person"), "query", "keyword")
-
-	os.Args = []string{"dws", "chat"}
-	assertNativePrimaryErrorHint(t,
-		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send", "--group", "cid"),
-		"content", "text")
-	assertNativePrimaryErrorHint(t,
-		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "send-by-webhook", "--token", "token", "--title", "title"),
-		"content", "text")
-	assertNativePrimaryErrorHint(t,
-		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID, "--content", "body"),
-		"group", "conversation-id")
-	assertNativePrimaryErrorHint(t,
-		runChatCoverageCommand(t, &nativePrimaryParamCaller{}, "message", "reply", "--group", "cid", "--ref-msg-id", "mid", "--ref-sender", helperCurrentDOpenID),
-		"content", "text")
-
-	os.Args = []string{"dws", "doc"}
-	assertNativePrimaryErrorHint(t,
-		runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "insert", "--node", "node"),
-		"content", "text")
-	assertNativePrimaryErrorHint(t,
-		runDocCoverageCommand(t, &nativePrimaryParamCaller{}, "block", "update", "--node", "node", "--block-id", "block"),
-		"content", "text")
-
-	os.Args = []string{"dws", "todo"}
-	assertNativePrimaryErrorHint(t,
-		executeTodoEdge(t, &scriptedToolCaller{}, "task", "add-attachment", "--task-id", "42"),
-		"file", "file-path")
-}
-
-func TestNativePrimaryParamPromotionErrorsPropagate(t *testing.T) {
-	chat := newChatCommand()
-	assertPromotionError := func(t *testing.T, err error) {
-		t.Helper()
-		if err == nil || !strings.Contains(err.Error(), "trying to get string value of flag of type bool") {
-			t.Fatalf("promotion error = %v", err)
-		}
-	}
-
-	t.Run("webhook RunE", func(t *testing.T) {
-		target := findNativePrimaryLeaf(t, chat, "message", "send-by-webhook")
-		cmd := &cobra.Command{}
-		cmd.Flags().String("content", "", "")
-		cmd.Flags().Bool("text", false, "")
-		if err := cmd.Flags().Set("text", "true"); err != nil {
-			t.Fatal(err)
-		}
-		assertPromotionError(t, target.RunE(cmd, nil))
-	})
-
-	reply := findNativePrimaryLeaf(t, chat, "message", "reply")
-	newInvalidGroupCommand := func(t *testing.T) *cobra.Command {
-		t.Helper()
-		cmd := &cobra.Command{}
-		cmd.Flags().String("group", "", "")
-		cmd.Flags().Bool("conversation-id", false, "")
-		if err := cmd.Flags().Set("conversation-id", "true"); err != nil {
-			t.Fatal(err)
-		}
-		return cmd
-	}
-
-	t.Run("reply PreRunE group", func(t *testing.T) {
-		assertPromotionError(t, reply.PreRunE(newInvalidGroupCommand(t), nil))
-	})
-
-	t.Run("reply RunE group", func(t *testing.T) {
-		assertPromotionError(t, reply.RunE(newInvalidGroupCommand(t), nil))
-	})
-
-	t.Run("reply RunE content", func(t *testing.T) {
-		cmd := &cobra.Command{}
-		cmd.Flags().String("group", "cid", "")
-		cmd.Flags().String("conversation-id", "", "")
-		cmd.Flags().String("content", "", "")
-		cmd.Flags().Bool("text", false, "")
-		if err := cmd.Flags().Set("text", "true"); err != nil {
-			t.Fatal(err)
-		}
-		assertPromotionError(t, reply.RunE(cmd, nil))
-	})
-}
@@ -304,6 +304,5 @@ func newSheetCommentCmd() *cobra.Command {
 	}

 	commentCmd.AddCommand(commentListCmd, commentCreateCmd, commentReplyCmd, commentUpdateCmd, commentDeleteCmd)
-	commentCmd.AddCommand(newCommentBaseCommands("sheet")...)
 	return commentCmd
 }
@@ -2,7 +2,7 @@ package helpers

 import "strings"

-// ShellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。
+// shellQuoteArg 按 POSIX sh 规则把 s 引用成可安全放进可复制命令的单个 argv 元素。
 //
 // 为什么需要它：错误提示里的恢复命令是给用户直接复制到 shell 执行的，其中的查询域取自用户
 // 输入（--workspace 的常见形态就是带查询串的 URL）。裸拼接下，合法 URL 里的 `&` 就会把命令
@@ -21,7 +21,7 @@ import "strings"
 //
 // 空串必须显式引用成一对空单引号，否则该参数会从 argv 里整个消失，后面的 token 会被前一个
 // flag 吞掉。
-func ShellQuoteArg(s string) string {
+func shellQuoteArg(s string) string {
 	if s == "" {
 		return "''"
 	}
@@ -41,7 +41,7 @@ func shellValueIsBare(s string) bool {
 // driveLatestPosixScopeValue 是 POSIX shell 下把用户值放进可复制命令的策略：单引号内 sh 不做
 // 任何展开，因此含元字符的值引用后即可安全内联。第二个返回值恒为 true。
 func driveLatestPosixScopeValue(value string) (string, bool) {
-	return ShellQuoteArg(value), true
+	return shellQuoteArg(value), true
 }

 // driveLatestWindowsScopeValue 是 Windows 构建下的策略：只内联本身就安全的值，其余一律不进
@@ -51,7 +51,7 @@ func TestCrossPlatformCoverageShellQuoteArgRoundTrip(t *testing.T) {

 	for _, want := range values {
 		t.Run(want, func(t *testing.T) {
-			quoted := ShellQuoteArg(want)
+			quoted := shellQuoteArg(want)

 			// 1) 未被拆参也未被吞掉：位置参数个数必须恰好为 1。
 			//    引用失效时 "sp 7" 会变 2 个、"" 会变 0 个、$(id) 会变 id 的输出词数。
@@ -69,8 +69,8 @@ func TestCrossPlatformCoverageShellQuoteArg(t *testing.T) {
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
-			if got := ShellQuoteArg(tc.in); got != tc.want {
-				t.Fatalf("ShellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want)
+			if got := shellQuoteArg(tc.in); got != tc.want {
+				t.Fatalf("shellQuoteArg(%q)\n got: %s\nwant: %s", tc.in, got, tc.want)
 			}
 		})
 	}
@@ -11,11 +11,11 @@ import (
 	"strings"
 	"time"

-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 )

 // ──────────────────────────────────────────────────────────
@@ -1017,20 +1017,14 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 		Short: "上传待办附件",
 		Long: `上传待办附件
 ⚠️ 重要：该接口会上传文件到附件，不可用于测试或试探性调用。调用前必须确认待办存在。`,
-		Example: `  dws todo task add-attachment --task-id <taskId> --file <filePath>
+		Example: `  dws todo task add-attachment --task-id <taskId> --file-path <filePath>
  # 查询 taskId: dws todo task list`,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			filePath := flagOrFallback(cmd, "file-path", "file")
-			taskID := mustGetFlag(cmd, "task-id")
-			if taskID == "" && filePath == "" {
-				return validateRequiredFlags(cmd, "task-id", "file")
-			}
-			if taskID == "" {
-				return validateRequiredFlags(cmd, "task-id")
-			}
-			if filePath == "" {
-				return validateRequiredFlags(cmd, "file")
+			if err := validateRequiredFlags(cmd, "task-id", "file-path"); err != nil {
+				return err
 			}
+
+			filePath, _ := cmd.Flags().GetString("file-path")
 			meta, err := buildTodoLocalFileMeta(filePath, "", "")
 			if err != nil {
 				return err
@@ -1098,8 +1092,8 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 					"要添加执行人/参与人/提醒时改用对应 add 命令",
 				},
 				Examples: []string{
-					"dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf",
-					"dws todo task add-attachment --task-id <taskId> --file /path/to/file.pdf --format json",
+					"dws todo task add-attachment --task-id <taskId> --file-path /path/to/file.pdf",
+					"dws todo task add-attachment --task-id <taskId> --file-path /path/to/file.pdf --format json",
 				},
 			},
 			Parameters: []contract.ParamDecl{
@@ -1253,11 +1247,7 @@ reset-reminder 写入的提醒规则。提醒写命令的成功响应只能作
 	todoTaskListSubCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskListAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskAddAttachment.Flags().String("task-id", "", "待办任务 ID (必填)")
-	corecmd.RegisterFlags(todoTaskAddAttachment, []corecmd.FlagSpec{{
-		Name:    "file",
-		Usage:   "本地文件路径（必填）",
-		Aliases: []string{"file-path"},
-	}})
+	todoTaskAddAttachment.Flags().String("file-path", "", "本地文件路径（必填）")
 	todoTaskRemoveAttachmentCmd.Flags().String("task-id", "", "待办任务 ID (必填)")
 	todoTaskRemoveAttachmentCmd.Flags().String("attachment-id", "", "待办附件 ID（必填）")

@@ -3,7 +3,6 @@
 package keychain

 import (
-	"bytes"
 	"encoding/base64"
 	"errors"
 	"os"
@@ -247,45 +246,6 @@ func TestCrossPlatformCoverageDarwinDEKKeyringEdges(t *testing.T) {
 	if got, err := getOrCreateDEK("generate-missing"); err != nil || len(got) != dekBytes {
 		t.Fatalf("generate missing = %d, %v", len(got), err)
 	}
-
-	existing := bytesOf(7, dekBytes)
-	setCalls := 0
-	keyringGet = func(string, string) (string, error) {
-		return base64.StdEncoding.EncodeToString(existing), nil
-	}
-	keyringSet = func(string, string, string) error {
-		setCalls++
-		return errors.New("duplicate write must not replace an existing DEK")
-	}
-	got, err := getOrCreateDEK("reuse-existing")
-	if err != nil || !bytes.Equal(got, existing) {
-		t.Fatalf("reuse existing = %d, %v", len(got), err)
-	}
-	if setCalls != 0 {
-		t.Fatalf("reuse existing set calls = %d, want 0", setCalls)
-	}
-
-	gets := 0
-	setCalls = 0
-	keyringGet = func(string, string) (string, error) {
-		gets++
-		if gets == 1 {
-			return "", keyring.ErrNotFound
-		}
-		return encoded, nil
-	}
-	keyringSet = func(string, string, string) error {
-		setCalls++
-		return errors.New("already exists")
-	}
-	got, err = getOrCreateDEK("create-race")
-	if err != nil || !bytes.Equal(got, valid) {
-		t.Fatalf("create race = %d, %v", len(got), err)
-	}
-	if setCalls != 1 {
-		t.Fatalf("create race set calls = %d, want 1", setCalls)
-	}
-	keyringGet = func(string, string) (string, error) { return "", keyring.ErrNotFound }
 	keychainRandRead = func([]byte) (int, error) { return 0, errKeychainInjected }
 	if _, err := getOrCreateDEK("rand"); err == nil {
 		t.Fatal("rand error expected")
@@ -237,26 +237,6 @@ func getSystemDEKReadOnly(service string) ([]byte, error) {
 	return key, err
 }

-func decodeSystemDEK(encodedKey string) ([]byte, bool) {
-	key, err := base64.StdEncoding.DecodeString(encodedKey)
-	return key, err == nil && len(key) == dekBytes
-}
-
-func readStoredSystemDEK(service string, runtime darwinKeychainRuntime) ([]byte, error) {
-	encodedKey, err := runtime.get(service, "dek")
-	if err == nil {
-		key, ok := decodeSystemDEK(encodedKey)
-		if ok {
-			return key, nil
-		}
-		return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
-	}
-	if errors.Is(err, keyring.ErrNotFound) {
-		return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
-	}
-	return nil, NewUnavailableError("read DEK from macOS Keychain", err)
-}
-
 func getSystemDEKReadOnlyWithRuntime(service string, runtime darwinKeychainRuntime) ([]byte, error, <-chan struct{}) {
 	if err := runtime.checkAvailable(); err != nil {
 		return nil, err, finishedDarwinKeychainWorker()
@@ -264,7 +244,18 @@ func getSystemDEKReadOnlyWithRuntime(service string, runtime darwinKeychainRunti

 	const operation = "read DEK from macOS Keychain"
 	worker := startDarwinKeychainWorker(operation, func() ([]byte, error) {
-		return readStoredSystemDEK(service, runtime)
+		encodedKey, err := runtime.get(service, "dek")
+		if err == nil {
+			key, decodeErr := base64.StdEncoding.DecodeString(encodedKey)
+			if decodeErr == nil && len(key) == dekBytes {
+				return key, nil
+			}
+			return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
+		}
+		if errors.Is(err, keyring.ErrNotFound) {
+			return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
+		}
+		return nil, NewUnavailableError("read DEK from macOS Keychain", err)
 	})

 	return waitDarwinKeychainWorker(runtime.timeout, operation, worker)
@@ -285,30 +276,28 @@ func getOrCreateDEKWithRuntime(service string, runtime darwinKeychainRuntime) ([

 	const operation = "read or create DEK in macOS Keychain"
 	worker := startDarwinKeychainWorker(operation, func() ([]byte, error) {
-		key, err := readStoredSystemDEK(service, runtime)
+		// Try to get existing DEK from system Keychain
+		encodedKey, err := runtime.get(service, "dek")
 		if err == nil {
-			return key, nil
-		}
-		if !IsDEKMissing(err) {
-			return nil, err
+			key, decodeErr := base64.StdEncoding.DecodeString(encodedKey)
+			if decodeErr == nil && len(key) == dekBytes {
+				return key, nil
+			}
+		} else if !errors.Is(err, keyring.ErrNotFound) {
+			return nil, NewUnavailableError("read DEK from macOS Keychain", err)
 		}

-		// Generate a candidate only when the slot is empty or unreadable.
-		// Concurrent writers must not replace a DEK another process just stored.
-		key = make([]byte, dekBytes)
+		// Generate new DEK if not found or invalid
+		key := make([]byte, dekBytes)
 		if _, randErr := runtime.randRead(key); randErr != nil {
 			return nil, randErr
 		}
-		if setErr := runtime.set(service, "dek", base64.StdEncoding.EncodeToString(key)); setErr != nil {
-			existing, getErr := readStoredSystemDEK(service, runtime)
-			if getErr == nil {
-				return existing, nil
-			}
+
+		// Store in system Keychain
+		encodedKey = base64.StdEncoding.EncodeToString(key)
+		if setErr := runtime.set(service, "dek", encodedKey); setErr != nil {
 			return nil, NewUnavailableError("store DEK in macOS Keychain", setErr)
 		}
-		if existing, getErr := readStoredSystemDEK(service, runtime); getErr == nil {
-			return existing, nil
-		}
 		return key, nil
 	})

@@ -1,127 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"sync"
-	"time"
-)
-
-// DefaultAuthCodeTTL is the unconsumed-cache window for a freshly minted
-// vendor authCode. The portal issues codes with expiresIn=120s and they are
-// one-shot, so the default stays under that server window. Prefer not wrapping
-// PortalAuthCode in CachedAuthCode: mint in goProxy and discard after the key
-// request.
-const DefaultAuthCodeTTL = 90 * time.Second
-
-// ErrNoAuthCode means the provider returned an empty code without an error.
-var ErrNoAuthCode = errors.New("msgcrypto: auth code provider returned an empty code")
-
-// AuthCodeProvider yields a DingTalk 免登 authCode for key-server
-// authentication. DWS does not mint the code itself, so integrations inject an
-// implementation. The backend calls this only from the vendor goProxy
-// callback, never on every encrypt or decrypt.
-//
-// Implementations must be safe for concurrent use; the backend may call this
-// from a CGO callback while an encrypt or decrypt call is in flight.
-type AuthCodeProvider interface {
-	AuthCode(ctx context.Context) (string, error)
-}
-
-// CorpAuthCodeProvider mints a code for a specific organization. PortalAuthCode
-// implements this so goProxy can pass the C library's corpID. Domain and
-// redirectURI are never part of this call.
-type CorpAuthCodeProvider interface {
-	AuthCodeProvider
-	AuthCodeForCorp(ctx context.Context, corpID string) (string, error)
-}
-
-// AuthCodeFunc adapts a function to AuthCodeProvider.
-type AuthCodeFunc func(ctx context.Context) (string, error)
-
-// AuthCode calls f.
-func (f AuthCodeFunc) AuthCode(ctx context.Context) (string, error) { return f(ctx) }
-
-// StaticAuthCode returns a provider that always yields code. It is meant for
-// tests and manual integration runs; a static code stops working once the
-// server-side five-minute window closes.
-func StaticAuthCode(code string) AuthCodeProvider {
-	return AuthCodeFunc(func(context.Context) (string, error) {
-		if code == "" {
-			return "", ErrNoAuthCode
-		}
-		return code, nil
-	})
-}
-
-// CachedAuthCode memoises an AuthCodeProvider for a TTL so a burst of key
-// requests does not trigger one upstream call each.
-type CachedAuthCode struct {
-	provider AuthCodeProvider
-	ttl      time.Duration
-	now      func() time.Time
-
-	mu        sync.Mutex
-	code      string
-	expiresAt time.Time
-}
-
-// NewCachedAuthCode wraps provider with a TTL cache. A ttl of zero or less
-// selects DefaultAuthCodeTTL.
-func NewCachedAuthCode(provider AuthCodeProvider, ttl time.Duration) *CachedAuthCode {
-	if ttl <= 0 {
-		ttl = DefaultAuthCodeTTL
-	}
-	return &CachedAuthCode{provider: provider, ttl: ttl, now: time.Now}
-}
-
-// AuthCode returns the cached code when it is still fresh, otherwise fetches a
-// new one. A failed fetch leaves no stale value behind.
-func (c *CachedAuthCode) AuthCode(ctx context.Context) (string, error) {
-	if c.provider == nil {
-		return "", ErrNoAuthCodeProvider
-	}
-
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	if c.code != "" && c.now().Before(c.expiresAt) {
-		return c.code, nil
-	}
-
-	code, err := c.provider.AuthCode(ctx)
-	if err != nil {
-		c.code, c.expiresAt = "", time.Time{}
-		return "", fmt.Errorf("msgcrypto: fetch auth code: %w", err)
-	}
-	if code == "" {
-		c.code, c.expiresAt = "", time.Time{}
-		return "", ErrNoAuthCode
-	}
-
-	c.code = code
-	c.expiresAt = c.now().Add(c.ttl)
-	return code, nil
-}
-
-// Invalidate drops the cached code so the next AuthCode call refetches. The
-// backend calls this after the key server rejects a code.
-func (c *CachedAuthCode) Invalidate() {
-	c.mu.Lock()
-	c.code, c.expiresAt = "", time.Time{}
-	c.mu.Unlock()
-}
@@ -1,228 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-)
-
-// countingProvider hands out a fresh code per call and records how often it was
-// asked, so cache behaviour can be asserted.
-type countingProvider struct {
-	mu    sync.Mutex
-	calls int
-	code  string
-	err   error
-}
-
-func (p *countingProvider) AuthCode(context.Context) (string, error) {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	p.calls++
-	if p.err != nil {
-		return "", p.err
-	}
-	if p.code != "" {
-		return p.code, nil
-	}
-	return "code-" + string(rune('a'+p.calls-1)), nil
-}
-
-// callCount reports the number of upstream fetches.
-func (p *countingProvider) callCount() int {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	return p.calls
-}
-
-func TestAuthCodeFuncAdaptsFunction(t *testing.T) {
-	provider := AuthCodeFunc(func(context.Context) (string, error) { return "abc", nil })
-	code, err := provider.AuthCode(context.Background())
-	if err != nil || code != "abc" {
-		t.Fatalf("AuthCode() = %q, %v; want abc, nil", code, err)
-	}
-}
-
-func TestStaticAuthCodeReturnsCode(t *testing.T) {
-	code, err := StaticAuthCode("fixed").AuthCode(context.Background())
-	if err != nil || code != "fixed" {
-		t.Fatalf("AuthCode() = %q, %v; want fixed, nil", code, err)
-	}
-}
-
-func TestStaticAuthCodeRejectsEmptyCode(t *testing.T) {
-	_, err := StaticAuthCode("").AuthCode(context.Background())
-	if !errors.Is(err, ErrNoAuthCode) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCode", err)
-	}
-}
-
-func TestCachedAuthCodeReusesCodeWithinTTL(t *testing.T) {
-	provider := &countingProvider{code: "same"}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	for i := 0; i < 5; i++ {
-		code, err := cache.AuthCode(context.Background())
-		if err != nil {
-			t.Fatalf("AuthCode() #%d = %v", i+1, err)
-		}
-		if code != "same" {
-			t.Fatalf("AuthCode() #%d = %q, want same", i+1, code)
-		}
-	}
-	if got := provider.callCount(); got != 1 {
-		t.Fatalf("upstream called %d times, want 1 (the code must be cached)", got)
-	}
-}
-
-func TestCachedAuthCodeRefetchesAfterTTL(t *testing.T) {
-	provider := &countingProvider{}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	now := time.Now()
-	cache.now = func() time.Time { return now }
-
-	first, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("first AuthCode() = %v", err)
-	}
-
-	// Move past the TTL. The DingTalk code expires server-side, so a stale
-	// one must not be reused.
-	now = now.Add(time.Minute + time.Second)
-
-	second, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("second AuthCode() = %v", err)
-	}
-	if first == second {
-		t.Fatalf("AuthCode() returned the same code %q after the TTL expired", first)
-	}
-	if got := provider.callCount(); got != 2 {
-		t.Fatalf("upstream called %d times, want 2", got)
-	}
-}
-
-func TestCachedAuthCodeDefaultTTLIsUnderServerWindow(t *testing.T) {
-	// Portal vendorAuthCode expiresIn is 120s and the code is one-shot.
-	// The unconsumed-cache window must stay under that server lifetime.
-	if DefaultAuthCodeTTL >= 120*time.Second {
-		t.Fatalf("DefaultAuthCodeTTL = %v, want less than the 120s portal expiresIn", DefaultAuthCodeTTL)
-	}
-	cache := NewCachedAuthCode(&countingProvider{}, 0)
-	if cache.ttl != DefaultAuthCodeTTL {
-		t.Fatalf("ttl = %v, want DefaultAuthCodeTTL %v", cache.ttl, DefaultAuthCodeTTL)
-	}
-}
-
-func TestCachedAuthCodeNegativeTTLFallsBackToDefault(t *testing.T) {
-	cache := NewCachedAuthCode(&countingProvider{}, -time.Second)
-	if cache.ttl != DefaultAuthCodeTTL {
-		t.Fatalf("ttl = %v, want DefaultAuthCodeTTL %v", cache.ttl, DefaultAuthCodeTTL)
-	}
-}
-
-func TestCachedAuthCodePropagatesUpstreamError(t *testing.T) {
-	wantErr := errors.New("token service down")
-	cache := NewCachedAuthCode(&countingProvider{err: wantErr}, time.Minute)
-
-	_, err := cache.AuthCode(context.Background())
-	if !errors.Is(err, wantErr) {
-		t.Fatalf("AuthCode() = %v, want it to wrap %v", err, wantErr)
-	}
-}
-
-func TestCachedAuthCodeDoesNotCacheFailures(t *testing.T) {
-	provider := &countingProvider{err: errors.New("transient")}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	if _, err := cache.AuthCode(context.Background()); err == nil {
-		t.Fatal("AuthCode() = nil error, want failure")
-	}
-
-	provider.mu.Lock()
-	provider.err = nil
-	provider.code = "recovered"
-	provider.mu.Unlock()
-
-	code, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("AuthCode() after recovery = %v", err)
-	}
-	if code != "recovered" {
-		t.Fatalf("AuthCode() = %q, want recovered (a failure must not be cached)", code)
-	}
-}
-
-func TestCachedAuthCodeRejectsEmptyUpstreamCode(t *testing.T) {
-	// A provider that reports success with no code is a bug upstream; the
-	// cache must surface it instead of caching an unusable value.
-	cache := NewCachedAuthCode(AuthCodeFunc(func(context.Context) (string, error) {
-		return "", nil
-	}), time.Minute)
-
-	if _, err := cache.AuthCode(context.Background()); !errors.Is(err, ErrNoAuthCode) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCode", err)
-	}
-}
-
-func TestCachedAuthCodeInvalidateForcesRefetch(t *testing.T) {
-	provider := &countingProvider{}
-	cache := NewCachedAuthCode(provider, time.Hour)
-
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("first AuthCode() = %v", err)
-	}
-	cache.Invalidate()
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("second AuthCode() = %v", err)
-	}
-	if got := provider.callCount(); got != 2 {
-		t.Fatalf("upstream called %d times, want 2 after Invalidate", got)
-	}
-}
-
-func TestCachedAuthCodeWithoutProviderReportsMissingProvider(t *testing.T) {
-	cache := NewCachedAuthCode(nil, time.Minute)
-	if _, err := cache.AuthCode(context.Background()); !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCodeProvider", err)
-	}
-}
-
-func TestCachedAuthCodeIsSafeForConcurrentUse(t *testing.T) {
-	// The backend may ask for a code from a CGO callback while another
-	// operation is in flight, so concurrent access must not race.
-	provider := &countingProvider{code: "shared"}
-	cache := NewCachedAuthCode(provider, time.Hour)
-
-	var wg sync.WaitGroup
-	for i := 0; i < 32; i++ {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			if code, err := cache.AuthCode(context.Background()); err != nil || code != "shared" {
-				t.Errorf("AuthCode() = %q, %v; want shared, nil", code, err)
-			}
-		}()
-	}
-	wg.Wait()
-
-	if got := provider.callCount(); got != 1 {
-		t.Fatalf("upstream called %d times, want 1", got)
-	}
-}
@@ -1,159 +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.
-
-// The constraint below must stay in sync with cipher_stub.go, which negates it
-// verbatim. It encodes the platforms the vendor ships a libsafechat.a for:
-// darwin and linux on amd64/arm64, plus windows/amd64. windows/arm64 is
-// deliberately excluded because the vendor has not delivered that static
-// library, and DWS does release that target.
-
-//go:build safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64))
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"sync"
-
-	safechat "safechat-go-sdk"
-)
-
-// BackendVersion identifies the compiled-in vendor SDK.
-const BackendVersion = "safechat " + safechat.Version
-
-// Available reports that this binary carries the SafeChat backend.
-func Available() bool { return true }
-
-// safechatCipher adapts the vendor client to Cipher.
-//
-// The vendor client serialises its own C calls internally, so this type adds no
-// further locking. Auth codes are minted only from AuthCodeHook, which the
-// vendor SDK calls inside goProxy when a key is actually missing.
-type safechatCipher struct {
-	client      *safechat.Client
-	codes       AuthCodeProvider
-	allowedHost string
-
-	mu          sync.Mutex
-	lastCodeErr error
-}
-
-// newBackend starts the vendor client against cfg's keystore.
-//
-// A warm keystore serves encrypt and decrypt without a key request, so no
-// authCode is fetched at open time. The hook runs only if goProxy fires.
-func newBackend(ctx context.Context, cfg Config) (Cipher, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-
-	var logf func(string, ...any)
-	if cfg.Debug {
-		logf = cfg.Logf
-	}
-
-	c := &safechatCipher{codes: cfg.AuthCode, allowedHost: cfg.AllowedRedirectHost}
-	client, err := safechat.New(safechat.Config{
-		DataPath:     cfg.KeystoreDir,
-		UserID:       cfg.UserID,
-		KeyServer:    cfg.KeyServer,
-		MaxRetry:     cfg.MaxRetry,
-		HTTPTimeout:  cfg.HTTPTimeout,
-		Logger:       newRedactingLogger(logf),
-		AuthCodeHook: c.authCodeHook,
-	})
-	if err != nil {
-		if errors.Is(err, safechat.ErrAlreadyInitialized) {
-			return nil, ErrAlreadyOpen
-		}
-		return nil, fmt.Errorf("msgcrypto: start safechat backend: %w", err)
-	}
-	c.client = client
-	return c, nil
-}
-
-// EncryptMessage encrypts plaintext and returns the vendor ciphertext.
-func (c *safechatCipher) EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	c.setLastCodeErr(nil)
-	out, err := c.client.EncryptMsg(corpID, staffID, plaintext)
-	if err != nil {
-		return nil, c.explain("encrypt", corpID, err)
-	}
-	return out, nil
-}
-
-// DecryptMessage decrypts a vendor ciphertext.
-func (c *safechatCipher) DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	c.setLastCodeErr(nil)
-	out, err := c.client.DecryptMsg(corpID, staffID, ciphertext)
-	if err != nil {
-		return nil, c.explain("decrypt", corpID, err)
-	}
-	return out, nil
-}
-
-// Close releases the vendor client.
-func (c *safechatCipher) Close() error {
-	c.client.Close()
-	return nil
-}
-
-// authCodeHook is invoked from goProxy immediately before the key request.
-// domain is compared locally and never forwarded to portal. The returned
-// code is used once by the SDK and is not stored on the client.
-func (c *safechatCipher) authCodeHook(corpID, domain string) (string, error) {
-	code, err := mintAuthCodeForProxy(c.codes, c.allowedHost, corpID, domain)
-	c.setLastCodeErr(err)
-	return code, err
-}
-
-func (c *safechatCipher) setLastCodeErr(err error) {
-	c.mu.Lock()
-	c.lastCodeErr = err
-	c.mu.Unlock()
-}
-
-func (c *safechatCipher) lastAuthCodeErr() error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.lastCodeErr
-}
-
-// explain turns a vendor error into an actionable one, folding in a failed
-// goProxy authCode mint and the admin-restricted case.
-func (c *safechatCipher) explain(op, corpID string, opErr error) error {
-	if c.client.IsBlocked(corpID) {
-		return fmt.Errorf("msgcrypto: %s blocked: the organization's key is restricted by its administrator: %w", op, opErr)
-	}
-
-	// A key fetch was needed but we had no usable code: that is the real
-	// cause, so report both.
-	if codeErr := c.lastAuthCodeErr(); codeErr != nil {
-		return fmt.Errorf("msgcrypto: %s failed and no usable auth code was available: %w (auth code error: %v)", op, opErr, codeErr)
-	}
-
-	if errors.Is(opErr, safechat.ErrMaxRetryExceeded) {
-		invalidateAuthCode(c.codes)
-		return fmt.Errorf("msgcrypto: %s failed: key material never became available: %w", op, opErr)
-	}
-
-	return fmt.Errorf("msgcrypto: %s failed: %w", op, opErr)
-}
@@ -1,161 +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.
-
-// Keep this constraint in sync with cipher_safechat.go.
-
-//go:build safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64))
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-// These tests exercise the real vendor backend, which means they link
-// libsafechat.a and initialise the C library. They never reach the key server:
-// an authCode is only spent when a key is actually fetched, and asserting that
-// encryption fails without one is exactly the behaviour we want pinned.
-
-func TestBackendIsReportedAvailable(t *testing.T) {
-	if !Available() {
-		t.Fatal("Available() = false in a safechat build")
-	}
-	if BackendVersion == "" {
-		t.Fatal("BackendVersion is empty in a safechat build")
-	}
-	if !strings.Contains(BackendVersion, "safechat") {
-		t.Fatalf("BackendVersion = %q, want it to name the vendor SDK", BackendVersion)
-	}
-}
-
-func TestOpenInitialisesCLibraryAndClosesCleanly(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v, want the C library to initialise", err)
-	}
-
-	if info, statErr := os.Stat(dir); statErr != nil || !info.IsDir() {
-		t.Fatalf("Open did not prepare the keystore dir: %v", statErr)
-	}
-
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-
-	// The slot must be free again, otherwise a second Open in the same
-	// process would be refused forever.
-	second, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("second Open() after Close = %v, want success", err)
-	}
-	if err := second.Close(); err != nil {
-		t.Fatalf("second Close() = %v", err)
-	}
-}
-
-func TestOpenRefusesConcurrentSecondCipher(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	first, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer first.Close()
-
-	_, err = Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrAlreadyOpen) {
-		t.Fatalf("second Open() = %v, want ErrAlreadyOpen (the C library keeps global state)", err)
-	}
-}
-
-func TestOpenHonoursCancelledContext(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	_, err := Open(ctx, Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, context.Canceled) {
-		t.Fatalf("Open() with a cancelled context = %v, want context.Canceled", err)
-	}
-}
-
-func TestEncryptWithoutUsableKeyReportsAuthCodeCause(t *testing.T) {
-	// A cold keystore forces a key request. With no reachable key server the
-	// operation must fail with a message that names the auth code, rather
-	// than a bare vendor return code.
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode: AuthCodeFunc(func(context.Context) (string, error) {
-			return "", errors.New("no code available in test")
-		}),
-		KeyServer: "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer cipher.Close()
-
-	_, err = cipher.EncryptMessage(context.Background(), "test-corp", "test-staff", []byte("hello"))
-	if err == nil {
-		t.Skip("the environment served a key without an auth code; nothing to assert")
-	}
-	if !strings.Contains(err.Error(), "auth code") {
-		t.Fatalf("EncryptMessage() = %v, want the error to name the auth code cause", err)
-	}
-}
-
-func TestCipherRejectsBadArgumentsBeforeCallingC(t *testing.T) {
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer cipher.Close()
-
-	if _, err := cipher.EncryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("EncryptMessage() with no corpID = %v, want ErrNoCorpID", err)
-	}
-	// The vendor SDK dereferences the first byte of the payload, so an empty
-	// slice must never reach it.
-	if _, err := cipher.DecryptMessage(context.Background(), "corp", "staff", nil); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("DecryptMessage() with no payload = %v, want ErrEmptyPayload", err)
-	}
-}
@@ -1,34 +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.
-
-// The constraint below is the exact negation of the one in cipher_safechat.go;
-// change both together. This file covers every default DWS build: the release
-// binaries are cross-compiled with CGO_ENABLED=0, and windows/arm64 has no
-// vendor static library even when the tag is set.
-
-//go:build !(safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64)))
-
-package msgcrypto
-
-import "context"
-
-// BackendVersion is empty because no backend is compiled in.
-const BackendVersion = ""
-
-// Available reports that this binary has no SafeChat backend, so callers should
-// not offer message encryption.
-func Available() bool { return false }
-
-// newBackend always fails here. Open checks Available first, so this exists to
-// keep the package compiling and to fail safe if that check is ever bypassed.
-func newBackend(context.Context, Config) (Cipher, error) { return nil, ErrUnavailable }
@@ -1,54 +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 msgcrypto
-
-import "context"
-
-// mintAuthCodeForProxy is the goProxy-only mint path. domain is compared
-// locally and never forwarded. A successful mint invalidates any unconsumed
-// cache so a one-shot code cannot be reused.
-func mintAuthCodeForProxy(codes AuthCodeProvider, allowedHost, corpID, domain string) (string, error) {
-	if err := matchRedirectHost(domain, allowedHost); err != nil {
-		return "", err
-	}
-	if codes == nil {
-		return "", ErrNoAuthCodeProvider
-	}
-
-	var (
-		code string
-		err  error
-	)
-	if provider, ok := codes.(CorpAuthCodeProvider); ok {
-		code, err = provider.AuthCodeForCorp(context.Background(), corpID)
-	} else {
-		code, err = codes.AuthCode(context.Background())
-	}
-	if err != nil {
-		invalidateAuthCode(codes)
-		return "", err
-	}
-	if code == "" {
-		invalidateAuthCode(codes)
-		return "", ErrNoAuthCode
-	}
-	invalidateAuthCode(codes)
-	return code, nil
-}
-
-func invalidateAuthCode(codes AuthCodeProvider) {
-	if invalidator, ok := codes.(interface{ Invalidate() }); ok {
-		invalidator.Invalidate()
-	}
-}
@@ -1,99 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-)
-
-type corpCountingProvider struct {
-	mu    sync.Mutex
-	calls []string
-	code  string
-	err   error
-}
-
-func (p *corpCountingProvider) AuthCode(context.Context) (string, error) {
-	return p.AuthCodeForCorp(context.Background(), "")
-}
-
-func (p *corpCountingProvider) AuthCodeForCorp(_ context.Context, corpID string) (string, error) {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	p.calls = append(p.calls, corpID)
-	if p.err != nil {
-		return "", p.err
-	}
-	if p.code != "" {
-		return p.code, nil
-	}
-	return "code-for-" + corpID, nil
-}
-
-func TestMintAuthCodeForProxyUsesCorpProvider(t *testing.T) {
-	inner := &corpCountingProvider{}
-	code, err := mintAuthCodeForProxy(inner, "sso.anhei.test", "ding_corp", "https://sso.anhei.test/login")
-	if err != nil || code != "code-for-ding_corp" {
-		t.Fatalf("mint = %q, %v; want code-for-ding_corp, nil", code, err)
-	}
-	if len(inner.calls) != 1 || inner.calls[0] != "ding_corp" {
-		t.Fatalf("corpIDs = %v, want [ding_corp]", inner.calls)
-	}
-}
-
-func TestMintAuthCodeForProxyInvalidatesUnconsumedCache(t *testing.T) {
-	inner := &countingProvider{code: "once"}
-	cache := NewCachedAuthCode(inner, time.Hour)
-
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("seed cache: %v", err)
-	}
-	if got := inner.callCount(); got != 1 {
-		t.Fatalf("seed fetches = %d, want 1", got)
-	}
-
-	code, err := mintAuthCodeForProxy(cache, "sso.anhei.test", "ding_corp", "https://sso.anhei.test/login")
-	if err != nil || code != "once" {
-		t.Fatalf("mint = %q, %v; want once, nil", code, err)
-	}
-
-	// Cache was invalidated after spend; next mint hits upstream again.
-	if _, err := mintAuthCodeForProxy(cache, "sso.anhei.test", "ding_corp", "sso.anhei.test"); err != nil {
-		t.Fatalf("second mint: %v", err)
-	}
-	if got := inner.callCount(); got != 2 {
-		t.Fatalf("upstream calls = %d, want 2 (seed reused once, then refetch)", got)
-	}
-}
-
-func TestMintAuthCodeForProxyRejectsDomainMismatchWithoutFetching(t *testing.T) {
-	inner := &corpCountingProvider{code: "once"}
-	_, err := mintAuthCodeForProxy(inner, "sso.anhei.test", "ding_corp", "evil.example.test")
-	if !errors.Is(err, ErrRedirectHostMismatch) {
-		t.Fatalf("mint = %v, want ErrRedirectHostMismatch", err)
-	}
-	if got := len(inner.calls); got != 0 {
-		t.Fatalf("upstream called %d times on domain mismatch, want 0", got)
-	}
-}
-
-func TestMintAuthCodeForProxyRequiresProvider(t *testing.T) {
-	if _, err := mintAuthCodeForProxy(nil, "", "ding_corp", ""); !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("mint = %v, want ErrNoAuthCodeProvider", err)
-	}
-}
@@ -1,83 +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 msgcrypto
-
-import (
-	"fmt"
-	"net"
-	"net/url"
-	"strings"
-)
-
-// validateKeyServer requires an HTTPS URL with a host so the vendor C
-// library cannot pick the key-request destination.
-func validateKeyServer(raw string) error {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return ErrNoKeyServer
-	}
-	u, err := url.Parse(raw)
-	if err != nil || u.Host == "" || u.Scheme == "" {
-		return fmt.Errorf("%w: %q", ErrInvalidKeyServer, raw)
-	}
-	if !strings.EqualFold(u.Scheme, "https") {
-		return fmt.Errorf("%w: %q", ErrKeyServerNotHTTPS, raw)
-	}
-	if hostnameOf(raw) == "" {
-		return fmt.Errorf("%w: %q", ErrInvalidKeyServer, raw)
-	}
-	return nil
-}
-
-// matchRedirectHost compares the goProxy domain to AllowedRedirectHost.
-// Both sides are reduced to a hostname. An empty domain or an empty
-// allowed host skips the check; the domain is never sent to portal.
-func matchRedirectHost(domain, allowed string) error {
-	domain = strings.TrimSpace(domain)
-	allowed = strings.TrimSpace(allowed)
-	if domain == "" || allowed == "" {
-		return nil
-	}
-	got := hostnameOf(domain)
-	want := hostnameOf(allowed)
-	if got == "" || want == "" || got != want {
-		return fmt.Errorf("%w: got %q, want %q", ErrRedirectHostMismatch, got, want)
-	}
-	return nil
-}
-
-// hostnameOf returns the lower-cased hostname of a URL, host:port, or bare
-// host. Path, query, userinfo and port are ignored.
-func hostnameOf(raw string) string {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return ""
-	}
-	if strings.Contains(raw, "://") {
-		u, err := url.Parse(raw)
-		if err == nil {
-			if host := strings.ToLower(u.Hostname()); host != "" {
-				return host
-			}
-		}
-	}
-	candidate := raw
-	if i := strings.IndexAny(candidate, "/?"); i >= 0 {
-		candidate = candidate[:i]
-	}
-	if host, _, err := net.SplitHostPort(candidate); err == nil {
-		return strings.ToLower(host)
-	}
-	return strings.ToLower(candidate)
-}
@@ -1,77 +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 msgcrypto
-
-import (
-	"errors"
-	"testing"
-)
-
-func TestValidateKeyServerAcceptsHTTPS(t *testing.T) {
-	if err := validateKeyServer("https://key.example.test/v1"); err != nil {
-		t.Fatalf("validateKeyServer() = %v, want nil", err)
-	}
-}
-
-func TestValidateKeyServerRejectsEmpty(t *testing.T) {
-	if err := validateKeyServer("  "); !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("validateKeyServer() = %v, want ErrNoKeyServer", err)
-	}
-}
-
-func TestValidateKeyServerRejectsHTTP(t *testing.T) {
-	if err := validateKeyServer("http://key.example.test"); !errors.Is(err, ErrKeyServerNotHTTPS) {
-		t.Fatalf("validateKeyServer() = %v, want ErrKeyServerNotHTTPS", err)
-	}
-}
-
-func TestValidateKeyServerRejectsBareHost(t *testing.T) {
-	if err := validateKeyServer("key.example.test"); !errors.Is(err, ErrInvalidKeyServer) {
-		t.Fatalf("validateKeyServer() = %v, want ErrInvalidKeyServer", err)
-	}
-}
-
-func TestMatchRedirectHostComparesHostOnly(t *testing.T) {
-	if err := matchRedirectHost("https://sso.anhei.test:443/login", "https://sso.anhei.test/path"); err != nil {
-		t.Fatalf("matchRedirectHost() = %v, want nil", err)
-	}
-	if err := matchRedirectHost("sso.anhei.test", "https://sso.anhei.test"); err != nil {
-		t.Fatalf("bare host match = %v, want nil", err)
-	}
-}
-
-func TestMatchRedirectHostSkipsWhenEitherSideEmpty(t *testing.T) {
-	if err := matchRedirectHost("", "https://sso.anhei.test"); err != nil {
-		t.Fatalf("empty domain = %v, want nil", err)
-	}
-	if err := matchRedirectHost("sso.anhei.test", ""); err != nil {
-		t.Fatalf("empty allowed host = %v, want nil", err)
-	}
-}
-
-func TestMatchRedirectHostRejectsMismatch(t *testing.T) {
-	err := matchRedirectHost("evil.example.test", "https://sso.anhei.test")
-	if !errors.Is(err, ErrRedirectHostMismatch) {
-		t.Fatalf("matchRedirectHost() = %v, want ErrRedirectHostMismatch", err)
-	}
-}
-
-func TestHostnameOfStripsPortAndPath(t *testing.T) {
-	if got := hostnameOf("https://SSO.Example.TEST:8443/login?x=1"); got != "sso.example.test" {
-		t.Fatalf("hostnameOf(url) = %q", got)
-	}
-	if got := hostnameOf("SSO.Example.TEST:8443/login"); got != "sso.example.test" {
-		t.Fatalf("hostnameOf(hostport) = %q", got)
-	}
-}
@@ -1,96 +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 msgcrypto
-
-import "fmt"
-
-// redactingLogger satisfies the vendor SDK's logger interface while making it
-// impossible for the SDK to leak secrets into DWS output.
-//
-// This matters because the vendor SDK logs, at debug level, both the authCode
-// it sends to the key server and the raw key-server response body, which
-// carries key material. Rather than trying to enumerate and pattern-match
-// every sensitive field, we drop every string argument and keep only its
-// length. Numeric and boolean arguments pass through, so operators still get
-// the useful diagnostics: HTTP status, payload sizes, timings and return
-// codes. The format string is preserved so it stays clear which field was
-// elided.
-type redactingLogger struct {
-	logf func(format string, args ...any)
-}
-
-// newRedactingLogger returns a logger that forwards to logf, or nil when logf
-// is nil so the SDK skips logging entirely.
-func newRedactingLogger(logf func(format string, args ...any)) *redactingLogger {
-	if logf == nil {
-		return nil
-	}
-	return &redactingLogger{logf: logf}
-}
-
-// Debug forwards a redacted debug line.
-func (l *redactingLogger) Debug(msg string, args ...interface{}) { l.emit("debug", msg, args) }
-
-// Info forwards a redacted info line.
-func (l *redactingLogger) Info(msg string, args ...interface{}) { l.emit("info", msg, args) }
-
-// Error forwards a redacted error line.
-func (l *redactingLogger) Error(msg string, args ...interface{}) { l.emit("error", msg, args) }
-
-// emit rewrites args so no string value survives, then forwards the line.
-func (l *redactingLogger) emit(level, msg string, args []interface{}) {
-	if l == nil || l.logf == nil {
-		return
-	}
-	l.logf("safechat[%s] "+msg, append([]any{level}, redactArgs(args)...)...)
-}
-
-// redactArgs replaces every string-like argument with a length marker and
-// leaves other kinds intact.
-func redactArgs(args []interface{}) []any {
-	out := make([]any, 0, len(args))
-	for _, arg := range args {
-		out = append(out, redactArg(arg))
-	}
-	return out
-}
-
-// redactArg elides a single argument's contents when it could carry a secret.
-// Strings and byte slices are reduced to their length; errors are reduced to
-// their type so a wrapped body preview cannot slip through; everything else
-// (numbers, booleans, durations) is kept because it cannot carry key material.
-func redactArg(arg any) any {
-	switch v := arg.(type) {
-	case string:
-		return redactedValue(len(v))
-	case []byte:
-		return redactedValue(len(v))
-	case fmt.Stringer:
-		// time.Duration and friends are Stringers, but so are opaque types
-		// that may embed a payload. Keep durations, elide the rest.
-		if _, ok := arg.(interface{ Nanoseconds() int64 }); ok {
-			return v.String()
-		}
-		return redactedValue(len(v.String()))
-	case error:
-		return fmt.Sprintf("<%T redacted>", v)
-	default:
-		return v
-	}
-}
-
-// redactedValue renders the placeholder used in place of elided content.
-func redactedValue(n int) string {
-	return fmt.Sprintf("<redacted len=%d>", n)
-}
@@ -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 msgcrypto
-
-import (
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-)
-
-// captureLogf collects emitted lines for assertions.
-func captureLogf(lines *[]string) func(string, ...any) {
-	return func(format string, args ...any) {
-		*lines = append(*lines, fmt.Sprintf(format, args...))
-	}
-}
-
-func TestNewRedactingLoggerReturnsNilWhenSinkIsNil(t *testing.T) {
-	// A nil logger makes the vendor SDK skip logging entirely, which is the
-	// safe default because it logs the authCode at debug level.
-	if got := newRedactingLogger(nil); got != nil {
-		t.Fatalf("newRedactingLogger(nil) = %v, want nil", got)
-	}
-}
-
-func TestRedactingLoggerHidesAuthCode(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	// This mirrors the vendor SDK's own debug line, which prints the code.
-	const secret = "abc123authcode"
-	logger.Debug("Code (auth_token, length=%d): %s", len(secret), secret)
-
-	if len(lines) != 1 {
-		t.Fatalf("got %d lines, want 1", len(lines))
-	}
-	if strings.Contains(lines[0], secret) {
-		t.Fatalf("log line leaked the auth code: %q", lines[0])
-	}
-	if !strings.Contains(lines[0], "redacted") {
-		t.Fatalf("log line = %q, want a redaction marker", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesKeyServerResponseBody(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	body := `{"key":"BASE64KEYMATERIAL==","keyVersion":3}`
-	logger.Debug("Body (length=%d): %s", len(body), body)
-
-	if strings.Contains(lines[0], "BASE64KEYMATERIAL") {
-		t.Fatalf("log line leaked key material: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesByteSlices(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Info("payload=%s", []byte("plaintext-message"))
-
-	if strings.Contains(lines[0], "plaintext-message") {
-		t.Fatalf("log line leaked a byte payload: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesErrorText(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	// Vendor error strings can embed a response body preview.
-	logger.Error("request failed: %v", errors.New(`server said {"key":"LEAKED"}`))
-
-	if strings.Contains(lines[0], "LEAKED") {
-		t.Fatalf("log line leaked error contents: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerKeepsDiagnosticNumbers(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Debug("Status: %d (took %s), size=%d", 503, 1500*time.Millisecond, 4096)
-
-	line := lines[0]
-	for _, want := range []string{"503", "1.5s", "4096"} {
-		if !strings.Contains(line, want) {
-			t.Fatalf("log line = %q, want it to keep %q for diagnostics", line, want)
-		}
-	}
-}
-
-func TestRedactingLoggerLabelsLevel(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Debug("d")
-	logger.Info("i")
-	logger.Error("e")
-
-	if len(lines) != 3 {
-		t.Fatalf("got %d lines, want 3", len(lines))
-	}
-	for i, want := range []string{"debug", "info", "error"} {
-		if !strings.Contains(lines[i], want) {
-			t.Fatalf("line %d = %q, want level %q", i, lines[i], want)
-		}
-	}
-}
-
-func TestRedactingLoggerToleratesNilSinkAtEmit(t *testing.T) {
-	// Guard against a partially constructed logger being used.
-	var logger *redactingLogger
-	logger.Debug("must not panic %s", "value")
-}
-
-func TestRedactArgKeepsDurations(t *testing.T) {
-	if got := redactArg(2 * time.Second); got != "2s" {
-		t.Fatalf("redactArg(2s) = %v, want 2s", got)
-	}
-}
-
-func TestRedactArgElidesStrings(t *testing.T) {
-	got, ok := redactArg("secret").(string)
-	if !ok {
-		t.Fatalf("redactArg returned %T, want string", got)
-	}
-	if strings.Contains(got, "secret") {
-		t.Fatalf("redactArg = %q, want the value elided", got)
-	}
-	if !strings.Contains(got, "len=6") {
-		t.Fatalf("redactArg = %q, want the length preserved", got)
-	}
-}
-
-func TestRedactArgPassesThroughNumbers(t *testing.T) {
-	if got := redactArg(42); got != 42 {
-		t.Fatalf("redactArg(42) = %v, want 42", got)
-	}
-	if got := redactArg(true); got != true {
-		t.Fatalf("redactArg(true) = %v, want true", got)
-	}
-}
@@ -1,297 +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 msgcrypto wraps the third-party SafeChat SDK so DWS can decrypt
-// DingTalk messages that an organization has encrypted with its own key
-// material, and encrypt outbound ones.
-//
-// The SafeChat backend links a prebuilt C static library and therefore needs
-// CGO. Because DWS ships CGO-free cross-compiled release binaries, the backend
-// is compiled only under the "safechat" build tag:
-//
-//	CGO_ENABLED=1 go build -tags safechat ./cmd
-//
-// Every other build gets a stub whose constructor fails with ErrUnavailable,
-// so callers must always handle that error rather than assume the capability
-// exists. Use Available to branch before offering the feature to a user.
-//
-// Key material is fetched from the vendor key server on demand, which requires
-// a DingTalk 免登 authCode supplied through AuthCodeProvider. DWS does not mint
-// that code itself; the caller injects a provider.
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"sync"
-	"time"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
-)
-
-// Errors reported by this package. Callers are expected to test for
-// ErrUnavailable explicitly, because it is the normal outcome on every build
-// that does not enable the safechat tag.
-var (
-	// ErrUnavailable means this binary was built without the SafeChat
-	// backend, or for a platform the vendor does not ship a static library
-	// for (notably windows/arm64).
-	ErrUnavailable = errors.New("msgcrypto: SafeChat backend not built into this binary")
-
-	// ErrAlreadyOpen means a Cipher is already open. The underlying C
-	// library keeps global state, so only one may exist per process.
-	ErrAlreadyOpen = errors.New("msgcrypto: a cipher is already open in this process")
-
-	// ErrClosed is returned by a Cipher whose Close has already run.
-	ErrClosed = errors.New("msgcrypto: cipher is closed")
-
-	// ErrNoAuthCodeProvider means Config.AuthCode was nil. Without it the
-	// backend cannot fetch or rotate key material.
-	ErrNoAuthCodeProvider = errors.New("msgcrypto: config.AuthCode is required")
-
-	// ErrEmptyPayload means an encrypt or decrypt call got no bytes. The
-	// vendor SDK rejects empty input, so we reject it earlier with a
-	// clearer message.
-	ErrEmptyPayload = errors.New("msgcrypto: payload is empty")
-
-	// ErrNoCorpID means the caller omitted the organization id, which
-	// selects the key and therefore cannot be defaulted.
-	ErrNoCorpID = errors.New("msgcrypto: corpID is required")
-
-	// ErrNoKeyServer means Config.KeyServer was empty. The vendor C
-	// library would otherwise pick the key-request destination.
-	ErrNoKeyServer = errors.New("msgcrypto: config.KeyServer is required")
-
-	// ErrInvalidKeyServer means Config.KeyServer is not a usable URL.
-	ErrInvalidKeyServer = errors.New("msgcrypto: config.KeyServer is not a valid URL")
-
-	// ErrKeyServerNotHTTPS means Config.KeyServer is not https.
-	ErrKeyServerNotHTTPS = errors.New("msgcrypto: config.KeyServer must be an https URL")
-
-	// ErrRedirectHostMismatch means the domain goProxy received does not
-	// match Config.AllowedRedirectHost. The domain is never sent to portal.
-	ErrRedirectHostMismatch = errors.New("msgcrypto: goProxy domain host does not match AllowedRedirectHost")
-)
-
-// keystoreDirPerm keeps the key cache owner-only. The directory holds
-// organization key material, so it must not be group- or world-readable.
-const keystoreDirPerm fs.FileMode = 0o700
-
-// DefaultKeystoreDir returns the default key cache directory,
-// ~/.dws/safechat/keystore, honouring DWS_CONFIG_DIR like the rest of DWS.
-func DefaultKeystoreDir() string {
-	return filepath.Join(config.DefaultConfigDir(), "safechat", "keystore")
-}
-
-// Cipher encrypts and decrypts message payloads for one organization at a
-// time. Implementations are safe for concurrent use.
-type Cipher interface {
-	// EncryptMessage encrypts plaintext for corpID/staffID and returns the
-	// vendor ciphertext envelope.
-	EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error)
-
-	// DecryptMessage decrypts a vendor ciphertext envelope.
-	DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error)
-
-	// Close releases the backend and frees the process-wide slot so a later
-	// Open can succeed. Calling it twice is safe.
-	Close() error
-}
-
-// Config parameterises Open.
-type Config struct {
-	// KeystoreDir is where fetched keys are cached. Defaults to
-	// DefaultKeystoreDir. It is created with 0700 if missing.
-	KeystoreDir string
-
-	// UserID is an opaque local identifier. The vendor SDK stores it but
-	// does not use it for key selection; leave empty to let the SDK
-	// generate one.
-	UserID string
-
-	// AuthCode supplies the DingTalk 免登 authCode used to authenticate key
-	// requests. Required. The backend calls it only from the vendor goProxy
-	// callback (cold keystore or key-version rotation), never on every
-	// encrypt/decrypt.
-	AuthCode AuthCodeProvider
-
-	// KeyServer is the HTTPS URL of the vendor key service. Required: it
-	// replaces the host the closed-source C library would otherwise pick.
-	KeyServer string
-
-	// AllowedRedirectHost, when set, is compared to the domain the C
-	// library passes into goProxy. A mismatch fails that key fetch. It is
-	// a local check only; the domain is never sent to portal.
-	AllowedRedirectHost string
-
-	// MaxRetry bounds retries while a key is still being fetched. Zero
-	// selects the vendor default.
-	MaxRetry int
-
-	// HTTPTimeout bounds each key request. Zero selects the vendor default.
-	HTTPTimeout time.Duration
-
-	// Debug enables backend logging through a redacting logger. Off by
-	// default because the vendor SDK logs the authCode and raw key-server
-	// responses at debug level.
-	Debug bool
-
-	// Logf receives already-redacted backend log lines when Debug is set.
-	// Nil discards them.
-	Logf func(format string, args ...any)
-}
-
-// withDefaults returns cfg with empty optional fields filled in.
-func (cfg Config) withDefaults() Config {
-	if cfg.KeystoreDir == "" {
-		cfg.KeystoreDir = DefaultKeystoreDir()
-	}
-	return cfg
-}
-
-// validate reports whether cfg carries everything the backend needs.
-func (cfg Config) validate() error {
-	if cfg.AuthCode == nil {
-		return ErrNoAuthCodeProvider
-	}
-	if cfg.KeystoreDir == "" {
-		return errors.New("msgcrypto: config.KeystoreDir resolved to an empty path")
-	}
-	if err := validateKeyServer(cfg.KeyServer); err != nil {
-		return err
-	}
-	return nil
-}
-
-// prepareKeystore creates dir if needed and makes sure it is owner-only.
-// An existing directory with looser bits is tightened, because it caches key
-// material.
-func prepareKeystore(dir string) error {
-	if err := os.MkdirAll(dir, keystoreDirPerm); err != nil {
-		return fmt.Errorf("msgcrypto: create keystore dir: %w", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		return fmt.Errorf("msgcrypto: stat keystore dir: %w", err)
-	}
-	if !info.IsDir() {
-		return fmt.Errorf("msgcrypto: keystore path %s is not a directory", dir)
-	}
-	// Windows does not model POSIX bits, so only tighten where they apply.
-	if runtimeSupportsPOSIXPerm && info.Mode().Perm() != keystoreDirPerm {
-		if err := os.Chmod(dir, keystoreDirPerm); err != nil {
-			return fmt.Errorf("msgcrypto: restrict keystore dir permissions: %w", err)
-		}
-	}
-	return nil
-}
-
-// process holds the single-instance guard. The vendor C library keeps global
-// state, so a second concurrent Cipher would corrupt it.
-var process struct {
-	mu   sync.Mutex
-	open bool
-}
-
-// Open validates cfg, prepares the keystore and starts the backend.
-//
-// It returns ErrUnavailable when the backend was not compiled in, so callers
-// can degrade gracefully. Only one Cipher may be open per process; Close frees
-// the slot.
-func Open(ctx context.Context, cfg Config) (Cipher, error) {
-	cfg = cfg.withDefaults()
-	if err := cfg.validate(); err != nil {
-		return nil, err
-	}
-	if !Available() {
-		return nil, ErrUnavailable
-	}
-	if err := prepareKeystore(cfg.KeystoreDir); err != nil {
-		return nil, err
-	}
-
-	process.mu.Lock()
-	defer process.mu.Unlock()
-	if process.open {
-		return nil, ErrAlreadyOpen
-	}
-	backend, err := newBackend(ctx, cfg)
-	if err != nil {
-		return nil, err
-	}
-	process.open = true
-	return &trackedCipher{backend: backend}, nil
-}
-
-// trackedCipher releases the process-wide slot when the wrapped backend closes.
-type trackedCipher struct {
-	mu      sync.Mutex
-	backend Cipher
-}
-
-// EncryptMessage validates the payload and delegates to the backend.
-func (c *trackedCipher) EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error) {
-	backend, err := c.live(corpID, plaintext)
-	if err != nil {
-		return nil, err
-	}
-	return backend.EncryptMessage(ctx, corpID, staffID, plaintext)
-}
-
-// DecryptMessage validates the payload and delegates to the backend.
-func (c *trackedCipher) DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error) {
-	backend, err := c.live(corpID, ciphertext)
-	if err != nil {
-		return nil, err
-	}
-	return backend.DecryptMessage(ctx, corpID, staffID, ciphertext)
-}
-
-// live returns the backend after checking the cipher is open and the arguments
-// are usable.
-func (c *trackedCipher) live(corpID string, payload []byte) (Cipher, error) {
-	if corpID == "" {
-		return nil, ErrNoCorpID
-	}
-	if len(payload) == 0 {
-		return nil, ErrEmptyPayload
-	}
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.backend == nil {
-		return nil, ErrClosed
-	}
-	return c.backend, nil
-}
-
-// Close closes the backend once and releases the process-wide slot.
-func (c *trackedCipher) Close() error {
-	c.mu.Lock()
-	backend := c.backend
-	c.backend = nil
-	c.mu.Unlock()
-	if backend == nil {
-		return nil
-	}
-
-	err := backend.Close()
-
-	process.mu.Lock()
-	process.open = false
-	process.mu.Unlock()
-	return err
-}
@@ -1,345 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"testing"
-)
-
-// fakeCipher stands in for a backend so the wrapper logic can be tested on
-// every platform, with or without the safechat tag.
-type fakeCipher struct {
-	mu         sync.Mutex
-	encrypted  [][]byte
-	decrypted  [][]byte
-	closeCount int
-	closeErr   error
-}
-
-func (f *fakeCipher) EncryptMessage(_ context.Context, _, _ string, plaintext []byte) ([]byte, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.encrypted = append(f.encrypted, plaintext)
-	return []byte("cipher:" + string(plaintext)), nil
-}
-
-func (f *fakeCipher) DecryptMessage(_ context.Context, _, _ string, ciphertext []byte) ([]byte, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.decrypted = append(f.decrypted, ciphertext)
-	return []byte(strings.TrimPrefix(string(ciphertext), "cipher:")), nil
-}
-
-func (f *fakeCipher) Close() error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.closeCount++
-	return f.closeErr
-}
-
-// newTrackedForTest wraps backend and claims the process slot the same way
-// Open does, so slot release can be asserted.
-func newTrackedForTest(t *testing.T, backend Cipher) *trackedCipher {
-	t.Helper()
-	process.mu.Lock()
-	process.open = true
-	process.mu.Unlock()
-	t.Cleanup(func() {
-		process.mu.Lock()
-		process.open = false
-		process.mu.Unlock()
-	})
-	return &trackedCipher{backend: backend}
-}
-
-func TestConfigWithDefaultsFillsKeystoreDir(t *testing.T) {
-	cfg := Config{}.withDefaults()
-	if cfg.KeystoreDir == "" {
-		t.Fatal("withDefaults left KeystoreDir empty")
-	}
-	if want := DefaultKeystoreDir(); cfg.KeystoreDir != want {
-		t.Fatalf("KeystoreDir = %q, want %q", cfg.KeystoreDir, want)
-	}
-}
-
-func TestConfigWithDefaultsKeepsExplicitKeystoreDir(t *testing.T) {
-	cfg := Config{KeystoreDir: "/custom/keys"}.withDefaults()
-	if cfg.KeystoreDir != "/custom/keys" {
-		t.Fatalf("KeystoreDir = %q, want /custom/keys", cfg.KeystoreDir)
-	}
-}
-
-func TestDefaultKeystoreDirHonoursConfigDirOverride(t *testing.T) {
-	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
-	got := DefaultKeystoreDir()
-	if !strings.HasSuffix(got, filepath.Join("safechat", "keystore")) {
-		t.Fatalf("DefaultKeystoreDir() = %q, want it to end with safechat/keystore", got)
-	}
-	if !strings.HasPrefix(got, os.Getenv("DWS_CONFIG_DIR")) {
-		t.Fatalf("DefaultKeystoreDir() = %q, want it under DWS_CONFIG_DIR", got)
-	}
-}
-
-func TestConfigValidateRequiresAuthCodeProvider(t *testing.T) {
-	err := Config{KeystoreDir: "/tmp/keys"}.validate()
-	if !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("validate() = %v, want ErrNoAuthCodeProvider", err)
-	}
-}
-
-func TestConfigValidateAcceptsCompleteConfig(t *testing.T) {
-	cfg := Config{
-		KeystoreDir: "/tmp/keys",
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	}
-	if err := cfg.validate(); err != nil {
-		t.Fatalf("validate() = %v, want nil", err)
-	}
-}
-
-func TestConfigValidateRequiresKeyServer(t *testing.T) {
-	err := Config{KeystoreDir: "/tmp/keys", AuthCode: StaticAuthCode("code")}.validate()
-	if !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("validate() = %v, want ErrNoKeyServer", err)
-	}
-}
-
-func TestConfigValidateRejectsHTTPKeyServer(t *testing.T) {
-	err := Config{
-		KeystoreDir: "/tmp/keys",
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "http://key.example.test",
-	}.validate()
-	if !errors.Is(err, ErrKeyServerNotHTTPS) {
-		t.Fatalf("validate() = %v, want ErrKeyServerNotHTTPS", err)
-	}
-}
-
-func TestPrepareKeystoreCreatesOwnerOnlyDir(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "nested", "keystore")
-	if err := prepareKeystore(dir); err != nil {
-		t.Fatalf("prepareKeystore() = %v", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		t.Fatalf("stat: %v", err)
-	}
-	if !info.IsDir() {
-		t.Fatal("prepareKeystore did not create a directory")
-	}
-	if runtime.GOOS == "windows" {
-		return
-	}
-	if got := info.Mode().Perm(); got != keystoreDirPerm {
-		t.Fatalf("perm = %#o, want %#o", got, keystoreDirPerm)
-	}
-}
-
-func TestPrepareKeystoreTightensLoosePermissions(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("POSIX permission bits are not modelled on Windows")
-	}
-	dir := filepath.Join(t.TempDir(), "keystore")
-	if err := os.MkdirAll(dir, fs.FileMode(0o755)); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-	if err := prepareKeystore(dir); err != nil {
-		t.Fatalf("prepareKeystore() = %v", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		t.Fatalf("stat: %v", err)
-	}
-	if got := info.Mode().Perm(); got != keystoreDirPerm {
-		t.Fatalf("perm = %#o, want %#o (key material must stay owner-only)", got, keystoreDirPerm)
-	}
-}
-
-func TestPrepareKeystoreRejectsFilePath(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "keystore")
-	if err := os.WriteFile(path, []byte("not a dir"), 0o600); err != nil {
-		t.Fatalf("write: %v", err)
-	}
-	err := prepareKeystore(path)
-	if err == nil {
-		t.Fatal("prepareKeystore() = nil, want an error for a non-directory path")
-	}
-}
-
-func TestOpenRejectsMissingAuthCodeProviderBeforeTouchingDisk(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	_, err := Open(context.Background(), Config{KeystoreDir: dir})
-	if !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("Open() = %v, want ErrNoAuthCodeProvider", err)
-	}
-	if _, statErr := os.Stat(dir); !os.IsNotExist(statErr) {
-		t.Fatal("Open created the keystore dir despite an invalid config")
-	}
-}
-
-func TestOpenRejectsMissingKeyServerBeforeTouchingDisk(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("code"),
-	})
-	if !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("Open() = %v, want ErrNoKeyServer", err)
-	}
-	if _, statErr := os.Stat(dir); !os.IsNotExist(statErr) {
-		t.Fatal("Open created the keystore dir despite a missing KeyServer")
-	}
-}
-
-func TestOpenWithoutBackendReportsUnavailable(t *testing.T) {
-	if Available() {
-		t.Skip("this binary has the safechat backend compiled in")
-	}
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrUnavailable) {
-		t.Fatalf("Open() = %v, want ErrUnavailable", err)
-	}
-}
-
-func TestAvailableAgreesWithBackendVersion(t *testing.T) {
-	if Available() != (BackendVersion != "") {
-		t.Fatalf("Available() = %v but BackendVersion = %q; they must agree", Available(), BackendVersion)
-	}
-}
-
-func TestTrackedCipherRoundTripsThroughBackend(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-
-	ciphertext, err := cipher.EncryptMessage(context.Background(), "corp", "staff", []byte("hello"))
-	if err != nil {
-		t.Fatalf("EncryptMessage() = %v", err)
-	}
-	plaintext, err := cipher.DecryptMessage(context.Background(), "corp", "staff", ciphertext)
-	if err != nil {
-		t.Fatalf("DecryptMessage() = %v", err)
-	}
-	if string(plaintext) != "hello" {
-		t.Fatalf("round trip = %q, want hello", plaintext)
-	}
-}
-
-func TestTrackedCipherRejectsEmptyCorpID(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if _, err := cipher.EncryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("EncryptMessage() = %v, want ErrNoCorpID", err)
-	}
-	if _, err := cipher.DecryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("DecryptMessage() = %v, want ErrNoCorpID", err)
-	}
-}
-
-func TestTrackedCipherRejectsEmptyPayload(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if _, err := cipher.EncryptMessage(context.Background(), "corp", "staff", nil); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("EncryptMessage() = %v, want ErrEmptyPayload", err)
-	}
-	if _, err := cipher.DecryptMessage(context.Background(), "corp", "staff", []byte{}); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("DecryptMessage() = %v, want ErrEmptyPayload", err)
-	}
-}
-
-func TestTrackedCipherRejectsUseAfterClose(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-	if _, err := cipher.EncryptMessage(context.Background(), "corp", "staff", []byte("x")); !errors.Is(err, ErrClosed) {
-		t.Fatalf("EncryptMessage() after Close = %v, want ErrClosed", err)
-	}
-}
-
-func TestTrackedCipherCloseIsIdempotentAndClosesBackendOnce(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-	for i := 0; i < 3; i++ {
-		if err := cipher.Close(); err != nil {
-			t.Fatalf("Close() #%d = %v", i+1, err)
-		}
-	}
-	if backend.closeCount != 1 {
-		t.Fatalf("backend Close called %d times, want exactly 1", backend.closeCount)
-	}
-}
-
-func TestTrackedCipherCloseReleasesProcessSlot(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-	process.mu.Lock()
-	open := process.open
-	process.mu.Unlock()
-	if open {
-		t.Fatal("Close did not release the process slot, so a later Open would fail")
-	}
-}
-
-func TestTrackedCipherClosePropagatesBackendError(t *testing.T) {
-	wantErr := errors.New("backend close failed")
-	cipher := newTrackedForTest(t, &fakeCipher{closeErr: wantErr})
-	if err := cipher.Close(); !errors.Is(err, wantErr) {
-		t.Fatalf("Close() = %v, want %v", err, wantErr)
-	}
-	process.mu.Lock()
-	open := process.open
-	process.mu.Unlock()
-	if open {
-		t.Fatal("a failing backend Close must still release the process slot")
-	}
-}
-
-func TestOpenRefusesSecondCipherWhileOneIsOpen(t *testing.T) {
-	// The vendor C library keeps global state, so a second concurrent
-	// cipher must be refused rather than silently corrupt it.
-	process.mu.Lock()
-	process.open = true
-	process.mu.Unlock()
-	t.Cleanup(func() {
-		process.mu.Lock()
-		process.open = false
-		process.mu.Unlock()
-	})
-
-	if !Available() {
-		t.Skip("Open reports ErrUnavailable before reaching the single-instance guard")
-	}
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrAlreadyOpen) {
-		t.Fatalf("Open() = %v, want ErrAlreadyOpen", err)
-	}
-}
@@ -1,20 +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.
-
-//go:build !windows
-
-package msgcrypto
-
-// runtimeSupportsPOSIXPerm reports that the keystore directory's permission
-// bits are meaningful here, so prepareKeystore enforces owner-only access.
-const runtimeSupportsPOSIXPerm = true
@@ -1,21 +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.
-
-//go:build windows
-
-package msgcrypto
-
-// runtimeSupportsPOSIXPerm reports that Windows does not model POSIX
-// permission bits, so prepareKeystore leaves the directory mode alone and
-// relies on the user profile ACL instead.
-const runtimeSupportsPOSIXPerm = false
@@ -1,170 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"strings"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-)
-
-// VendorSafeChat is the first vendorAuthCode vendor.
-const VendorSafeChat = "safechat"
-
-// PortalAuthCode mints a one-shot 免登 authCode from portal
-// POST /oauth2/vendorAuthCode. It does not cache the code: goProxy spends it
-// immediately. Do not wrap this in CachedAuthCode.
-type PortalAuthCode struct {
-	ConfigDir  string
-	Vendor     string
-	CLIVersion string
-	HTTPClient *http.Client
-
-	clientID func() string
-	snapshot func(ctx context.Context, configDir string) (*auth.TokenData, error)
-	refresh  func(ctx context.Context, configDir, rejected string) (string, error)
-	fetch    func(ctx context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error)
-}
-
-// NewPortalAuthCode returns a provider that talks to portal with the current
-// login. cliVersion is sent as x-dws-cli-version; leave empty only when the
-// caller cannot know the CLI version.
-func NewPortalAuthCode(configDir, cliVersion string) *PortalAuthCode {
-	return &PortalAuthCode{
-		ConfigDir:  configDir,
-		Vendor:     VendorSafeChat,
-		CLIVersion: cliVersion,
-		clientID:   auth.ClientID,
-		snapshot: func(ctx context.Context, dir string) (*auth.TokenData, error) {
-			return auth.NewOAuthProvider(dir, nil).GetTokenSnapshot(ctx)
-		},
-		refresh: func(ctx context.Context, dir, rejected string) (string, error) {
-			return auth.NewOAuthProvider(dir, nil).ForceRefreshRejectedToken(ctx, rejected)
-		},
-		fetch: auth.FetchVendorAuthCode,
-	}
-}
-
-// AuthCode mints a code for the logged-in organization. Prefer AuthCodeForCorp
-// when goProxy already has a corpID.
-func (p *PortalAuthCode) AuthCode(ctx context.Context) (string, error) {
-	snap, err := p.loadSnapshot(ctx)
-	if err != nil {
-		return "", err
-	}
-	return p.AuthCodeForCorp(ctx, snap.CorpID)
-}
-
-// AuthCodeForCorp mints a one-shot code for corpID. The request body is only
-// vendor + corpId.
-func (p *PortalAuthCode) AuthCodeForCorp(ctx context.Context, corpID string) (string, error) {
-	corpID = strings.TrimSpace(corpID)
-	if corpID == "" {
-		return "", ErrNoCorpID
-	}
-	snap, err := p.loadSnapshot(ctx)
-	if err != nil {
-		return "", err
-	}
-	token := strings.TrimSpace(snap.AccessToken)
-	if token == "" {
-		return "", fmt.Errorf("msgcrypto: access token is empty")
-	}
-
-	result, err := p.fetchOnce(ctx, snap, token, corpID)
-	if err == nil {
-		return result.AuthCode, nil
-	}
-
-	var verr *auth.VendorAuthCodeError
-	if errors.As(err, &verr) && verr.Code == auth.VendorAuthCodeTokenInvalid {
-		refreshed, rerr := p.doRefresh(ctx, token)
-		if rerr == nil && refreshed != "" && refreshed != token {
-			result, err = p.fetchOnce(ctx, snap, refreshed, corpID)
-			if err == nil {
-				return result.AuthCode, nil
-			}
-		}
-		return "", err
-	}
-	if retryableVendorAuthCode(err) {
-		result, err = p.fetchOnce(ctx, snap, token, corpID)
-		if err == nil {
-			return result.AuthCode, nil
-		}
-	}
-	return "", err
-}
-
-func (p *PortalAuthCode) loadSnapshot(ctx context.Context) (*auth.TokenData, error) {
-	if p.snapshot == nil {
-		return nil, fmt.Errorf("msgcrypto: portal authCode snapshot loader is not configured")
-	}
-	snap, err := p.snapshot(ctx, p.ConfigDir)
-	if err != nil {
-		return nil, fmt.Errorf("msgcrypto: load access token: %w", err)
-	}
-	if snap == nil {
-		return nil, fmt.Errorf("msgcrypto: load access token: empty snapshot")
-	}
-	return snap, nil
-}
-
-func (p *PortalAuthCode) fetchOnce(ctx context.Context, snap *auth.TokenData, token, corpID string) (*auth.VendorAuthCodeResult, error) {
-	fetch := p.fetch
-	if fetch == nil {
-		fetch = auth.FetchVendorAuthCode
-	}
-	vendor := strings.TrimSpace(p.Vendor)
-	if vendor == "" {
-		vendor = VendorSafeChat
-	}
-	clientID := strings.TrimSpace(snap.ClientID)
-	if clientID == "" && p.clientID != nil {
-		clientID = strings.TrimSpace(p.clientID())
-	}
-	return fetch(ctx, auth.VendorAuthCodeInput{
-		AccessToken: token,
-		ClientID:    clientID,
-		CLIVersion:  p.CLIVersion,
-		LoginRegion: auth.LoginRegion(strings.TrimSpace(snap.LoginRegion)),
-		Vendor:      vendor,
-		CorpID:      corpID,
-		HTTPClient:  p.HTTPClient,
-	})
-}
-
-func (p *PortalAuthCode) doRefresh(ctx context.Context, rejected string) (string, error) {
-	if p.refresh == nil {
-		return "", fmt.Errorf("msgcrypto: token refresh is not configured")
-	}
-	return p.refresh(ctx, p.ConfigDir, rejected)
-}
-
-func retryableVendorAuthCode(err error) bool {
-	var verr *auth.VendorAuthCodeError
-	if errors.As(err, &verr) {
-		return verr.Retryable()
-	}
-	var statusErr *auth.HTTPStatusError
-	if errors.As(err, &statusErr) && statusErr != nil {
-		return statusErr.StatusCode == http.StatusTooManyRequests ||
-			statusErr.StatusCode >= http.StatusInternalServerError
-	}
-	return false
-}
@@ -1,121 +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 msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync/atomic"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-)
-
-func TestPortalAuthCodePostsVendorAndCorpOnly(t *testing.T) {
-	var got auth.VendorAuthCodeInput
-	p := &PortalAuthCode{
-		ConfigDir:  t.TempDir(),
-		Vendor:     VendorSafeChat,
-		CLIVersion: "1.2.3",
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{
-				AccessToken: "user-token",
-				ClientID:    "dws-client",
-				CorpID:      "ding_login",
-				LoginRegion: "",
-			}, nil
-		},
-		fetch: func(_ context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			got = in
-			return &auth.VendorAuthCodeResult{AuthCode: "tmp-code", ExpiresIn: 120}, nil
-		},
-	}
-
-	code, err := p.AuthCodeForCorp(context.Background(), "ding_target")
-	if err != nil || code != "tmp-code" {
-		t.Fatalf("AuthCodeForCorp() = %q, %v", code, err)
-	}
-	if got.Vendor != VendorSafeChat || got.CorpID != "ding_target" {
-		t.Fatalf("body vendor/corpId = %q/%q", got.Vendor, got.CorpID)
-	}
-	if got.AccessToken != "user-token" || got.ClientID != "dws-client" || got.CLIVersion != "1.2.3" {
-		t.Fatalf("headers token/client/version = %q/%q/%q", got.AccessToken, got.ClientID, got.CLIVersion)
-	}
-}
-
-func TestPortalAuthCodeRetriesOnceOnTokenInvalidAfterRefresh(t *testing.T) {
-	var calls atomic.Int32
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "stale", ClientID: "dws-client", CorpID: "ding"}, nil
-		},
-		refresh: func(context.Context, string, string) (string, error) {
-			return "fresh", nil
-		},
-		fetch: func(_ context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			n := calls.Add(1)
-			if in.AccessToken == "stale" {
-				return nil, &auth.VendorAuthCodeError{Code: auth.VendorAuthCodeTokenInvalid, Message: "expired"}
-			}
-			if in.AccessToken != "fresh" {
-				t.Fatalf("retry token = %q, want fresh", in.AccessToken)
-			}
-			if n != 2 {
-				t.Fatalf("fetch calls = %d, want 2", n)
-			}
-			return &auth.VendorAuthCodeResult{AuthCode: "new-code", ExpiresIn: 120}, nil
-		},
-	}
-
-	code, err := p.AuthCodeForCorp(context.Background(), "ding")
-	if err != nil || code != "new-code" {
-		t.Fatalf("AuthCodeForCorp() = %q, %v", code, err)
-	}
-	if calls.Load() != 2 {
-		t.Fatalf("fetch called %d times, want 2", calls.Load())
-	}
-}
-
-func TestPortalAuthCodeDoesNotRetryOrgMismatch(t *testing.T) {
-	var calls atomic.Int32
-	want := &auth.VendorAuthCodeError{Code: auth.VendorAuthCodeOrgMismatch, Message: "mismatch"}
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "tok", ClientID: "dws-client", CorpID: "ding"}, nil
-		},
-		fetch: func(context.Context, auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			calls.Add(1)
-			return nil, want
-		},
-	}
-
-	_, err := p.AuthCodeForCorp(context.Background(), "other")
-	if !errors.Is(err, want) {
-		t.Fatalf("AuthCodeForCorp() = %v, want %v", err, want)
-	}
-	if calls.Load() != 1 {
-		t.Fatalf("fetch called %d times, want 1", calls.Load())
-	}
-}
-
-func TestPortalAuthCodeRequiresCorpID(t *testing.T) {
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "tok", ClientID: "id"}, nil
-		},
-	}
-	if _, err := p.AuthCodeForCorp(context.Background(), "  "); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("AuthCodeForCorp() = %v, want ErrNoCorpID", err)
-	}
-}
@@ -659,8 +659,8 @@ var RecordQuery = shortcut.Shortcut{
 	Service:     "aitable",
 	Command:     "+record-query",
 	Product:     serverMain,
-	Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
-	Intent:      "读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。",
+	Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
+	Intent:      "当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。",
 	Risk:        shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -674,20 +674,17 @@ var RecordQuery = shortcut.Shortcut{
 			CLIPath:        "aitable +record-query",
 			PrimaryCLIPath: "aitable +record-query",
 		},
-		Description: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
+		Description: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
 		Interface: &contract.InterfaceSpec{
 			Mode:         "composite",
 			Availability: "available",
 			Reason:       "Reviewed built-in shortcut adapter: the executable CLI owns validation, optional multi-step orchestration, output projection, and confirmation; the complete command contract is not represented by one pinned MCP interface_ref.",
 		},
 		Selection: contract.SelectionSpec{
-			AgentSummary: "查询表格记录（按 ID / 条件 / 关键词，并支持字段投影和分页）",
-			UseWhen:      []string{"读取表格行数据；可按 recordId 精确取、按条件筛选、按关键词搜索，并用 fieldIds 只返回用户要求的字段以避免无关数据和 token 消耗。"},
+			AgentSummary: "查询表格记录（按 ID 取 / 条件筛选 / 关键词 / 分页）",
+			UseWhen:      []string{"当你要读取表格里的行数据——按 recordId 精确取、按结构化条件筛选、按关键词全文搜索或分页遍历时使用；返回匹配记录及其单元格值。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
-			Examples: []string{
-				"dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50",
-				"dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS",
-			},
+			Examples:     []string{"dws aitable +record-query --base-id B --table-id T --query \"关键词\" --limit 50"},
 		},
 	},
 	Flags: []shortcut.Flag{
@@ -701,10 +698,7 @@ var RecordQuery = shortcut.Shortcut{
 		{Name: "limit", Type: shortcut.FlagInt, Desc: "单次最大记录数，默认 100（可选）"},
 		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标（可选）"},
 	},
-	Tips: []string{
-		`dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`,
-		`dws aitable +record-query --base-id B --table-id T --record-ids R1,R2 --field-ids F_NAME,F_STATUS`,
-	},
+	Tips: []string{`dws aitable +record-query --base-id B --table-id T --query "关键词" --limit 50`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		params := map[string]any{
 			"baseId":  rt.Str("base-id"),
@@ -3116,7 +3110,6 @@ func init() {
 		BaseSchemaSnapshot,
 		BaseBootstrap,
 		TableGet,
-		TableBootstrap,
 		TableCopy,
 		TableUpdate,
 		TableDelete,
@@ -5,7 +5,6 @@ package aitable

 import (
 	"fmt"
-	"reflect"
 	"strings"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
@@ -51,7 +50,7 @@ var BaseBootstrap = shortcut.Shortcut{
 		"+base-bootstrap",
 		"一次创建 Base、数据表和字段，逐层读回验证并在中断时报告已知副作用",
 		"当你已有声明式 tables JSON、想一次搭好一套 AI 表格结构时使用；表内字段自动按 15 个拆批，每次创建都读回验证。",
-		"已有 Base 只需新增一张表时用 +table-bootstrap；复制现有 Base 用 +base-copy；不要对失败请求盲目重试",
+		"已有 Base 只需新增一张表时用 table create；复制现有 Base 用 base copy；不要对失败请求盲目重试",
 		`dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[]}]'`,
 	),
 	Flags: []shortcut.Flag{
@@ -74,25 +73,25 @@ type bootstrapTable struct {
 func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 	value, err := parseJSONAny("tables", raw)
 	if err != nil {
-		return nil, baseBootstrapValidation(fmt.Sprintf("--tables 不是合法 JSON 数组：%v", err))
+		return nil, err
 	}
 	items, ok := value.([]any)
 	if !ok || len(items) == 0 {
-		return nil, baseBootstrapValidation("--tables 必须是非空 JSON 数组")
+		return nil, apperrors.NewValidation("--tables 必须是非空 JSON 数组")
 	}
 	if len(items) > 100 {
-		return nil, baseBootstrapValidation("--tables 最多接受 100 张表")
+		return nil, apperrors.NewValidation("--tables 最多接受 100 张表")
 	}
 	seen := map[string]bool{}
 	out := make([]bootstrapTable, 0, len(items))
 	for index, item := range items {
 		object, ok := item.(map[string]any)
 		if !ok {
-			return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index))
+			return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d] 必须是 JSON 对象", index))
 		}
 		name := strings.TrimSpace(stringValue(object, "name"))
 		if name == "" || seen[name] {
-			return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index))
+			return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].name 必须非空且不能重复", index))
 		}
 		seen[name] = true
 		fields := []any{}
@@ -100,24 +99,13 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 			var fieldsOK bool
 			fields, fieldsOK = rawFields.([]any)
 			if !fieldsOK {
-				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index))
+				return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields 必须是 JSON 数组", index))
 			}
 		}
-		fieldNames := map[string]bool{}
 		for fieldIndex, field := range fields {
 			object, ok := field.(map[string]any)
-			fieldName := strings.TrimSpace(stringValue(object, "fieldName", "name"))
-			if !ok || fieldName == "" || strings.TrimSpace(stringValue(object, "type")) == "" {
-				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex))
-			}
-			if fieldNames[fieldName] {
-				return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].fieldName %q 不能重复", index, fieldIndex, fieldName))
-			}
-			fieldNames[fieldName] = true
-			if config, exists := object["config"]; exists {
-				if _, ok := config.(map[string]any); !ok {
-					return nil, baseBootstrapValidation(fmt.Sprintf("--tables[%d].fields[%d].config 必须是 JSON 对象", index, fieldIndex))
-				}
+			if !ok || strings.TrimSpace(stringValue(object, "fieldName", "name")) == "" || strings.TrimSpace(stringValue(object, "type")) == "" {
+				return nil, apperrors.NewValidation(fmt.Sprintf("--tables[%d].fields[%d] 必须包含 fieldName 和 type", index, fieldIndex))
 			}
 		}
 		out = append(out, bootstrapTable{Name: name, Fields: fields})
@@ -125,14 +113,6 @@ func parseBootstrapTables(raw string) ([]bootstrapTable, error) {
 	return out, nil
 }

-func baseBootstrapValidation(message string) error {
-	return apperrors.NewValidation(message,
-		apperrors.WithHint("tables 使用 [{\"name\":\"任务\",\"fields\":[{\"fieldName\":\"标题\",\"type\":\"text\"}]}]；已知参数时不要先调用 --help"),
-		apperrors.WithActions(`dws aitable +base-bootstrap --name "项目管理" --tables '[{"name":"任务","fields":[{"fieldName":"标题","type":"text"}]}]'`),
-		apperrors.WithAvailableFlags("name", "folder-id", "template-id", "tables"),
-	)
-}
-
 func executeBaseSchemaSnapshot(rt *shortcut.RuntimeContext) error {
 	baseID := rt.Str("base-id")
 	base, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID})
@@ -215,20 +195,17 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 	if err != nil {
 		result.Status = "unknown"
 		result.FailedCount = len(tables)
-		result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying", "name": rt.Str("name")}
-		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json")
+		result.Checkpoint = map[string]any{"nextStep": "resolve whether base was created before retrying"}
 		return compositeError(result, err, false)
 	}
 	baseID := findStringByKeys(baseData, "baseId")
 	if baseID == "" {
 		result.Status = "unknown"
 		result.Result = baseData
-		result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying", "name": rt.Str("name")}
-		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-search", "--query", rt.Str("name"), "--format", "json")
+		result.Checkpoint = map[string]any{"nextStep": "locate the created Base by exact name before retrying"}
 		return compositeError(result, fmt.Errorf("create_base response is missing baseId"), false)
 	}
 	result.Resolved = map[string]any{"baseId": baseID}
-	result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+base-get", "--base-id", baseID, "--format", "json")
 	result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_base", "baseId": baseID})
 	result.CompletedSteps = append(result.CompletedSteps, compositeStep{Index: 1, Name: "create base", Tool: "create_base", Status: "completed", Result: baseData})
 	baseRead, err := rt.CallMCPData(serverMain, "get_base", map[string]any{"baseId": baseID})
@@ -260,7 +237,6 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 			return compositeError(result, createErr, false)
 		}
 		result.KnownEffects = append(result.KnownEffects, map[string]any{"tool": "create_table", "baseId": baseID, "tableId": tableID, "name": spec.Name})
-		result.NextCommand = aitableRecoveryCommand("dws", "aitable", "+table-get", "--base-id", baseID, "--table-id", tableID, "--format", "json")
 		for offset := initialEnd; offset < len(spec.Fields); offset += 15 {
 			end := minInt(offset+15, len(spec.Fields))
 			_, fieldErr := rt.CallMCPWriteDataStrict(serverMain, "create_fields", map[string]any{
@@ -283,13 +259,10 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 		}
 		fieldsData, verifyErr := rt.CallMCPData(serverMain, "get_fields", map[string]any{"baseId": baseID, "tableId": tableID})
 		fields, found := findNamedObjectList(fieldsData, "fields", "fieldList")
-		if verifyErr == nil && !found {
-			verifyErr = fmt.Errorf("field read-back for table %s is missing the fields collection", tableID)
-		}
-		if verifyErr == nil {
-			verifyErr = verifyDeclaredFieldStructures(fields, spec.Fields)
-		}
-		if verifyErr != nil {
+		if verifyErr != nil || !found || !containsAllFieldNames(fields, spec.Fields) {
+			if verifyErr == nil {
+				verifyErr = fmt.Errorf("field read-back for table %s does not contain the declared field set", tableID)
+			}
 			result.Status = "partial_success"
 			result.CompletedCount = index
 			result.FailedCount = len(tables) - index
@@ -302,7 +275,6 @@ func executeBaseBootstrap(rt *shortcut.RuntimeContext) error {
 	}
 	result.Verification = map[string]any{"status": "verified", "baseId": baseID, "tableCount": len(createdTables)}
 	result.Result = map[string]any{"baseId": baseID, "tables": createdTables}
-	result.NextCommand = ""
 	return rt.Output(result)
 }

@@ -406,73 +378,16 @@ func deepContainsString(value any, expected string) bool {
 	return false
 }

-func verifyDeclaredFieldStructures(actual []map[string]any, expected []any) error {
-	actualByName := map[string][]map[string]any{}
+func containsAllFieldNames(actual []map[string]any, expected []any) bool {
+	names := map[string]bool{}
 	for _, field := range actual {
-		name := strings.TrimSpace(stringValue(field, "fieldName", "name"))
-		if name != "" {
-			actualByName[name] = append(actualByName[name], field)
-		}
+		names[stringValue(field, "fieldName", "name")] = true
 	}
-	for index, raw := range expected {
-		field, ok := raw.(map[string]any)
-		if !ok {
-			return fmt.Errorf("declared field at index %d is not an object", index)
-		}
-		name := strings.TrimSpace(stringValue(field, "fieldName", "name"))
-		matches := actualByName[name]
-		if len(matches) == 0 {
-			return fmt.Errorf("field read-back is missing declared field %q", name)
-		}
-		if len(matches) != 1 {
-			return fmt.Errorf("field read-back contains %d fields named %q", len(matches), name)
-		}
-		actualField := matches[0]
-		expectedType := strings.TrimSpace(stringValue(field, "type"))
-		actualType := strings.TrimSpace(stringValue(actualField, "type", "fieldType"))
-		if actualType != expectedType {
-			return fmt.Errorf("field %q type mismatch: got %q, want %q", name, actualType, expectedType)
-		}
-		for _, key := range []string{"config", "aiConfig"} {
-			expectedConfig, declared := field[key]
-			if !declared {
-				continue
-			}
-			actualConfig, found := actualField[key]
-			if !found || !declaredValueMatches(actualConfig, expectedConfig) {
-				return fmt.Errorf("field %q %s mismatch", name, key)
-			}
-		}
-	}
-	return nil
-}
-
-func declaredValueMatches(actual, expected any) bool {
-	switch expectedValue := expected.(type) {
-	case map[string]any:
-		actualValue, ok := actual.(map[string]any)
-		if !ok {
+	for _, raw := range expected {
+		field, _ := raw.(map[string]any)
+		if !names[stringValue(field, "fieldName", "name")] {
 			return false
 		}
-		for key, expectedChild := range expectedValue {
-			actualChild, found := actualValue[key]
-			if !found || !declaredValueMatches(actualChild, expectedChild) {
-				return false
-			}
-		}
-		return true
-	case []any:
-		actualValue, ok := actual.([]any)
-		if !ok || len(actualValue) != len(expectedValue) {
-			return false
-		}
-		for index := range expectedValue {
-			if !declaredValueMatches(actualValue[index], expectedValue[index]) {
-				return false
-			}
-		}
-		return true
-	default:
-		return reflect.DeepEqual(actual, expected)
 	}
+	return true
 }
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
玉澜	c7521c1ca3	fix(cli): route Chinese product-name queries to the named product Natural-language queries that name a product in Chinese (e.g. 「帮我搜一下「评测项目管理」钉钉AI表格」) lost the named product's candidates to a sibling product whose summaries repeat a shared bigram (92 sheet tools repeat 「表格」), crowding aitable out of the Top-K cut entirely. Two-part fix in the lexical layer, deterministic and no new dependencies: - Fold the product display name into each tool's identity field at index build (runtime assembly carries the display name in Description). - Query-side named-product guarantee: when the query contains a product's display-name core (NFKC-folded, generic suffixes like 「操作」「管理」 trimmed, longest core wins on overlap), fetch that product's best candidate over its own eligible subset and merge it just above the global top hit. A post-hoc multiplier alone cannot rescue candidates truncated inside Retrieve's CandidateLimit cut. Eval evidence (core120 first-turn coverage): 101→103/120; all four measured 「钉钉AI表格」 misses fixed, zero regressions across the battery.	2026-08-19 14:31:48 +08:00
玉澜	aa0bc0c2d4	Merge remote-tracking branch 'upstream/main' into pr984	2026-08-17 21:55:45 +08:00
玉澜	f2a3dd2344	fix(cli): hint tokenized schema path failures at the path-form boundary - the unknown runtime schema path error now states that canonical paths contain dots and must be a single argument while space-separated tokens resolve as a CLI path; help text and docs only reach agents that consult them, the error is the one surface guaranteed to be seen at failure time - the app trust diagnostic comment is shortened to the durable constraint (do not pin absolute Catalog-size counts) instead of narrating the change - NewDeliveryToolSearchEngine's doc comment notes the memo serves long-lived hosts; the shipped schema search command rebuilds per invocation through NewDeliveryToolSearchEngineWithConfig	2026-08-17 19:10:18 +08:00
玉澜	b8c9ff2619	test(app): drop stale Catalog-size sentinels from the trust diagnostic The diagnostic test pinned absolute counts from one Catalog generation: 1123 intent cases, Recall@5 == 990/1123, 1098 tools and the 402/721 language slices. Merging main grew the Catalog to 1121 tools, so the population became 1147/407/740 and the test failed as a size drift rather than as a trust regression. - the absolute counts are removed; the observed intent, language-slice and context values are logged for CI forensics and the headline numbers stay in the generated comparison JSON - identity coverage is still enforced exhaustively, but the expected count is derived from report.Context.ToolCount instead of a literal - the trust contract that does not move with Catalog size stays a hard gate: every identity pass rate == 1, alias cases non-zero, all four integrity counters == 0, zero-result rate == 0, non-empty language slices and ReductionVsFullSchema >= 0.99	2026-08-17 17:21:28 +08:00
玉澜	225a073d89	fix(cli): close tool search self-review findings - SearchSubqueries returned a nil candidate slice on the decomposed_exact_filtered refusal, so that one strategy encoded "candidates":null while every other path encoded []; the refusal now carries an empty slice and a marshal assertion pins the wire shape - the memoized delivery engine was never invalidated: it indexes one Catalog generation and caches its source/surface hashes, but RegisterSchemaSourceRoot -> resetDeliverySchemaCatalogState left the memo installed, so a re-registered root could be served stale hashes. Catalog delivery reset now clears it, with a ForTest wrapper and a regression test for the rebuild - dangerous filter Unicode is rejected before the effect vocabulary and Catalog product checks, so a control/Bidi character returns dangerous_filter_unicode instead of being echoed back through invalid_effect; the filter list is an ordered slice, not a map, so the reported field name is deterministic - dws schema help and RFC 5.8 record the path-form boundary: multi-token args resolve as a CLI path, a canonical path must stay one argument - --explain and ToolSearchScoreBreakdown declare that the reported score is the raw value while ordering uses the quantized key - --limit/--candidate-limit help state that 0 means "use the default", which was already the behavior but read as an asymmetry against the rejected negative values - bootstrap seeds become named constants and are published in both evaluation reports (bootstrap_samples/bootstrap_seed/ recovery_bootstrap_seed) so an interval is reproducible without reading the source - dingtalk-shared documents the cross-product summary --dry-run flag and that its command list is a plan, not business data	2026-08-17 17:21:10 +08:00
玉澜	45a52dee85	docs: consolidate the six tool search documents into one file The RFC, source-implementation research, GitHub architecture research, ranking evaluation report, 2026-08-14 optimization plan and ten-round review record were six separate files that cross-linked each other for the same decision chain. They are merged into docs/tool-search-progressive-discovery.md as Part 1..6, ordered decision -> research -> evidence -> plan -> review record. - cross-file links become in-document "本文档 Part N" pointers; the five remaining relative links (source and evaluator paths) still resolve - section content is unchanged apart from one addition: 5.8 Inspect now records the path-form boundary (multi-token args resolve as a CLI path; a canonical path must be passed as a single argument), matching the dws schema help text	2026-08-17 17:20:41 +08:00
john	235e881ebe	Merge branch 'main' into test/tool-search-ranking-eval	2026-08-17 15:21:07 +08:00
玉澜	2855f1a84b	fix(skills): multi-turn append semantics for explicit write requests Eval forensics: in clean isolated doc-domain runs the toolsearch arm lost 7/20 paired cases to main on codex+gpt-5.6-sol; 5 of 6 flips showed the same signature — the agent refused an explicit per-turn 'append/insert' request because similar content already existed (front-loaded or matched), and the judge fails the refusal. The clause makes per-turn explicit write requests execute (existence may be noted but never replaces execution), forbids front-loading future turns, and keeps read-back for verification only. Verified: doc domain 30% -> 55% (main 60%), dup-refusal signature 5/6 -> 0.	2026-08-15 18:25:07 +08:00
玉澜	6406c93eaa	feat(cli): convergence signals for capability-absent searches Eval-driven optimizations from the 2026-08-14/15 agent evaluations: - abstained lexical responses now carry a bounded hint naming the one permitted verification step (dws schema <product> --compact) and licensing the conclusion 'unsupported', so agents stop enumerating every product to prove a capability is missing - responses whose candidates only matched weak fields (parameters/ description, no identity/summary hit) set weak_match=true with a matching hint; the flag is field-class based, not a score threshold, preserving the RFC ban on absolute score cutoffs - exact_filtered keeps its typed refusal without inheriting either hint; budget-truncation to zero candidates downgrades to the abstain hint - dingtalk-shared gains the matching convergence rule: one search, at most one schema <product> verification, then conclude honestly Evidence: the nonexistent-capability intent scenario took 15 turns/177s to conclude 'no poll capability' with identical correctness to a 4-turn run; these signals bound that path. Note: on the real catalog the poll phrasing still matches summary fields of generic chat tools, so the behavioral fix for that specific case rides on the shared-skill rule; the wire flags cover genuinely unmatched and weak-field-only queries.	2026-08-15 05:02:28 +08:00
玉澜	747a17f305	fix(cli): close tool search review findings from contract probe - effect filter: case-insensitive against the reviewed vocabulary with a typed invalid_effect refusal; unknown product ids get a typed unknown_product refusal instead of a silent abstain (probe-confirmed: --effect Read used to return 0 candidates silently) - DWS_TOOL_SEARCH_* unparsable values now warn on stderr while keeping the resolved default, so ranking experiments cannot silently measure defaults (probe-confirmed: K1='0,9' was ignored with empty stderr) - --explain help text now declares it a dev-only diagnostic that exposes raw ordering scores; the default wire stays score-free - lexical ordering quantizes the sort key at 1e-9 so architecture dependent FMA fusion (arm64 vs amd64) cannot flip near-tied candidates past the canonical tie-break; reported scores are unchanged Contract probe re-run against this build: 11/11 checks OK (was 3 FINDINGs)	2026-08-14 19:58:09 +08:00
玉澜	d578458315	fix(cli): fail closed on unknown tool-search filters and warn on unparsable env - effect filters are case-normalized against the reviewed vocabulary and reject anything else with a typed invalid_effect error instead of a silent abstain (probe-confirmed: --effect Read now equals --effect read) - unknown product ids reject with unknown_product instead of returning abstained=true, so caller typos cannot masquerade as empty results - unparsable DWS_TOOL_SEARCH_* float env values now warn on stderr; previously a typo like K1=0,9 silently measured the default config - --explain help text declares the raw-score disclosure as a dev-only diagnostic exception to the score-free public wire	2026-08-14 19:53:34 +08:00
玉澜	575b8f32c4	feat(skills): add compact cross-product read summary	2026-08-14 15:37:13 +08:00
玉澜	70e46cbd29	fix(cli): harden tool search evaluation and config	2026-08-14 10:04:53 +08:00
玉澜	e9efd3e909	docs(rfc): sync progressive discovery numbers to post-hardening baseline	2026-08-13 16:58:31 +08:00
玉澜	9bc803fde0	fix(cli): enforce shortcut avoid_when boilerplate filter and sync eval docs Self-review follow-ups on the ranking hardening series: - the avoid_when boilerplate filter compared lowercased phrases against a mixed-case constant, so the "需要该 Shortcut..." noise filter never fired; the constant is now lowercase (no ranking change: the boilerplate was never contained by any query, sentinel 990/1123 unchanged) - add direct unit coverage for the avoid_when penalty (echoed-phrase match, unrelated-query pass-through, boilerplate filter, partial overlap, explain annotation) - update tool-search-ranking-evaluation.md to the post-hardening numbers (ensemble R@5 88.16%, Forbidden 0%/0%, action_v1 shadow 84.24% with the trade-off recorded) - drop the dead algorithm_freeze manifest block; nothing consumes it after the hash decoupling	2026-08-13 16:31:52 +08:00
玉澜	2dc3147cda	refactor(scripts): decouple tool search eval manifest from source hashes and seal gate - drop the algorithm/gate source SHA256 freeze: every ranking change required a manual manifest hash sync, coupling code evolution to the manifest - drop the --require-sealed release gate (sealed qrels hash, dual signatures, coverage minima, independent-result thresholds) and its tool-search-independent-data-gate Makefile target - behavior regression protection stays with the Go evaluation sentinels that run the real assembled catalog	2026-08-13 16:09:19 +08:00
玉澜	e91b30c769	chore(testdata): refresh frozen tool search algorithm source hash The algorithm freeze gate intentionally rejects silent ranking source changes; this records the new source set hash after the ranking hardening commit.	2026-08-13 15:51:27 +08:00
玉澜	0df293186a	feat(cli): harden tool search ranking, guardrails and observability - default engine: fielded BM25 ensemble (action_v1 remains a shadow candidate) - add --explain score_breakdown: per-field contributions, structured multiplier, query classification and avoid_when penalty - add DWS_TOOL_SEARCH_* env overrides (algorithm, k1/b, field weights, explain) for release-independent tuning and rollback - tokenizer: CJK unigram+bigram so single-character intents match; align isToolSearchCJK with unicode.Han used by the evaluation slices - structured routing: extend vocabularies with English synonyms, word-boundary matching for ASCII values, restrict the rerank gate to technical identifiers only - avoid_when demotion layer wraps every lexical algorithm (Forbidden@5 proxy 37.55% -> 0); intent-overlap matching rejected after control showed it demoted gold answers (Recall@5 0.8664 -> 0.7845) - remove the OA task_id +1.00 fixture-specific multiplier - build the default engine once per process for long-lived hosts - evaluation baseline: intent-proxy R@5 990/1123 (88.16%); update integration sentinels accordingly	2026-08-13 15:20:09 +08:00
玉澜	003bbe87ba	Merge remote-tracking branch 'upstream/main' into test/tool-search-ranking-eval	2026-08-13 14:04:53 +08:00
玉澜	fc47e05cd7	docs: clarify local tool search boundaries	2026-08-13 13:21:28 +08:00
玉澜	86ebdd8f25	refactor(cli): remove tool search provider fallback	2026-08-13 11:51:33 +08:00
玉澜	20b8120f59	Merge remote-tracking branch 'upstream/main' into test/tool-search-ranking-eval	2026-08-13 11:10:45 +08:00
玉澜	a08a1f54fd	docs(skill): integrate DWS command discovery	2026-08-13 11:09:31 +08:00
玉澜	93da35413b	feat(cli): add progressive tool search	2026-08-13 10:15:10 +08:00