fix(schema): reject breaking constraint expansion

fix(im): preserve incomplete read failures
fix(im): harden user resolution and broadcast lookup
2026-08-05 14:56:18 +08:00 · 2026-08-05 14:27:53 +08:00 · 2026-08-05 13:57:27 +08:00 · 2026-08-05 11:24:58 +08:00 · 2026-08-05 10:03:21 +08:00 · 2026-08-05 09:35:57 +08:00
185 changed files with 14760 additions and 7671 deletions
@@ -702,14 +702,11 @@ jobs:
        with:
          go-version-file: go.mod

-      # Full ./internal/app (including schema --all assembly) already runs in the
-      # race:app shard. Keep this job focused on native auth/keychain paths so
-      # heavy Schema completeness tests cannot exhaust the 10m budget.
-      - name: Test macOS auth and Keychain paths with Race Detection
-        run: go test -v -race -count=1 -timeout=10m ./internal/keychain ./internal/auth
+      - name: Test macOS auth and Keychain packages with Race Detection
+        run: go test -v -race -count=1 -timeout=6m ./internal/keychain ./internal/auth

-      - name: Test macOS auth migration and portable auth diagnostics
-        run: go test -v -race -count=1 -timeout=5m ./internal/app -run '^Test(CrossPlatformCoverage)?Auth(MigrateKeychain|StatusDiagnosticReportsCiphertextKeyMismatch|ExportRejectsWindowsDPAPIBackend|ImportRejectsWindowsDPAPIBackend)'
+      - name: Test macOS auth migration, Keychain diagnostics, and upgrade self-heal with Race Detection
+        run: go test -v -race -count=1 -timeout=5m ./internal/app -run '^(TestValidateNewBinary_RecoversFromUnsignedDarwin|Test(CrossPlatformCoverage)?Auth(MigrateKeychain|StatusDiagnosticReportsCiphertextKeyMismatch))'

  test-windows:
    name: Test (Windows)
@@ -820,6 +817,7 @@ jobs:
        run: ./scripts/policy/run-platform-coverage-gate.sh --base-ref "$COVERAGE_BASE_REF" --profile coverage-windows.txt

      - name: Upload Windows coverage artifact
+        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-windows
@@ -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 rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks

 all: setup-hooks fmt lint build test rebuild

@@ -33,6 +33,7 @@ help:
 	@printf "  make schema-compatibility BASE_REF=<ref> - Check the complete Schema contract against the PR merge-base\n"
 	@printf "  make skill-command-integrity - Check dws commands referenced by skills exist\n"
 	@printf "  make skill-context-budget - Check generated Skill drift and common-path context budgets\n"
+	@printf "  make multi-im-skill-chain-integrity - Check reviewed IM intents keep one default Skill route\n"
 	@printf "  make cli-smoke     - Verify help for every public top-level command\n"
 	@printf "  make mock-mcp-smoke - Verify HTTP and stdio MCP request/response transport\n"
 	@printf "  make test-schema-agent-examples - Contract-check all Agent examples and dry-run the eligible subset\n"
@@ -87,6 +88,7 @@ policy: test-auth-legacy-compat
 	@mkdir -p "$(POLICY_GOTMPDIR)"
 	@$(POLICY_ENV) ./scripts/policy/check-open-source-assets.sh
 	@$(POLICY_ENV) ./scripts/policy/check-skill-context-budget.sh
+	@$(POLICY_ENV) ./scripts/policy/check-multi-im-skill-chain.sh
 	@$(POLICY_ENV) ./scripts/policy/check-command-surface.sh --strict
 	@$(POLICY_ENV) ./scripts/policy/check-generated-drift.sh
 	@$(POLICY_ENV) ./scripts/policy/check-param-concepts.sh
@@ -126,6 +128,9 @@ skill-command-integrity:
 skill-context-budget:
 	@./scripts/policy/check-skill-context-budget.sh

+multi-im-skill-chain-integrity:
+	@./scripts/policy/check-multi-im-skill-chain.sh
+
 cli-smoke:
 	@./scripts/policy/check-cli-smoke.sh

@@ -70,17 +70,17 @@ The installer ships skills in one of two layouts. CLI commands (`dws aitable ...

 | Mode | What gets installed | Best for |
 |------|----------------------|----------|
-| **multi** (default) | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |
-| **mono** (legacy) | One `dws` skill covering all products | Cross-product workflows; single entry point |
+| **mono** (stable, default) | One `dws` skill covering all products | Cross-product workflows; single entry point |
+| **multi** 🧪 **EXPERIMENTAL** | Per-product skills (`dingtalk-aitable`, `dingtalk-calendar`, `dingtalk-chat`, ...) | Single-product tasks; smaller context per call |

-> Installs and upgrades default to `multi`. `mono` remains available via `DWS_SKILL_MODE=mono` or `dws skill setup --mode mono`. File issues if you hit problems.
+> 🧪 **`multi` is currently EXPERIMENTAL / preview.** All product-scoped skills pass the dispatch verifier, but interface, naming and cross-skill references may change in future releases. For production / shared environments, prefer `mono`. File issues if you hit problems.

 How to pick:

- **Quick install** (one-liner above): non-interactive, installs `multi`.
- **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) multi  2) mono` (default 1).
- **Override via env**: `DWS_SKILL_MODE=mono curl -fsSL ... | sh`.
- **Switch later**: `dws skill setup --mode mono` (or `--mode multi`) — re-run any time.
+- **Quick install** (one-liner above): non-interactive, installs `mono`.
+- **TTY install** (download then run): `curl -O .../install.sh && bash install.sh` — prompts `1) mono  2) multi` (default 1).
+- **Override via env**: `DWS_SKILL_MODE=multi curl -fsSL ... | sh`.
+- **Switch later**: `dws skill setup --mode multi` (or `--mode mono`) — re-run any time.

 </details>

@@ -393,19 +393,19 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

 The repo ships a complete Agent Skill system under `skills/`, organized into two layouts:

- `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), legacy.
- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. Default layout.
+- `skills/mono/` — single-skill layout (one `SKILL.md` + `references/products/`), recommended default.
+- `skills/multi/` — per-product skills (`dingtalk-aitable/`, `dingtalk-calendar/`, `dingtalk-chat/`, ...), each with its own `SKILL.md`. 🧪 **EXPERIMENTAL / preview — see banner in each multi `SKILL.md` for caveats.**

 Leaf safety/parameters/selection prose for Schema generation come from ProductDecl / ContractFinal declarations in Go. The former `internal/cli/schema_hints/` HintFile tree is fully retired and must not reappear.

 After installing, AI tools like Claude Code / Cursor can operate DingTalk directly through natural language:

 ```bash
-# Install skills into current project (defaults to multi; DWS_SKILL_MODE=mono switches back)
+# Install skills into current project (defaults to mono)
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```

-> `install.sh` installs under `$HOME/.agents/skills/` (global; multi layout is per-product siblings, mono is the `dws/` subdirectory); `install-skills.sh` installs under `./.agents/skills/` (current project).
+> `install.sh` installs to `$HOME/.agents/skills/dws` (global); `install-skills.sh` installs to `./.agents/skills/dws` (current project).
 >
 > China users: prefix `DWS_GITEE_REPO` to use the Gitee mirror — see [China mirror](#china-mirror).

@@ -719,7 +719,7 @@ See [`docs/robot-quickstart.md`](./docs/robot-quickstart.md) for the full 4-step
 <summary>Coming soon</summary>

 - `conference` (video meetings)
- Multi-skill mode (default) — per-product skills under `skills/multi/`; installs and upgrades default to it, `dws skill setup --mode mono` switches back
+- Multi-skill mode (experimental) — per-product skills under `skills/multi/`; opt in via `dws skill setup --mode multi`

 </details>

@@ -70,17 +70,17 @@ irm https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/ma

 | 模式 | 安装内容 | 适合场景 |
 |------|----------|----------|
-| **multi**（默认） | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |
-| **mono**（legacy） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
+| **mono**（稳定，默认） | 一个 `dws` skill，覆盖全部产品 | 跨产品组合操作；单一入口召唤 |
+| **multi** 🧪 **试验版 / Preview** | 按产品拆分的独立 skill（`dingtalk-aitable` / `dingtalk-calendar` / `dingtalk-chat` ...） | 单产品任务；每次召唤上下文更小 |

-> 安装与升级默认均为 multi。mono 仍可通过 `DWS_SKILL_MODE=mono` 或 `dws skill setup --mode mono` 使用。问题请提 issue 反馈。
+> 🧪 **multi 模式当前为 EXPERIMENTAL（试验版 / Preview）**。全部独立 skill 均通过 dispatch verifier，但接口、命名、跨 skill 引用后续可能调整。生产 / 共享环境建议优先用 `mono`。问题请提 issue 反馈。

 怎么选：

- **快速安装**（上方一行 curl）：非交互，默认装 `multi`。
- **TTY 安装**（先下载再执行）：`curl -O .../install.sh && bash install.sh`，会弹出 `1) multi  2) mono` 选项（默认 1）。
- **环境变量覆盖**：`DWS_SKILL_MODE=mono curl -fsSL ... | sh`。
- **装完之后再切换**：`dws skill setup --mode mono`（或 `--mode multi`），随时重跑都行。
+- **快速安装**（上方一行 curl）：非交互，默认装 `mono`。
+- **TTY 安装**（先下载再执行）：`curl -O .../install.sh && bash install.sh`，会弹出 `1) mono  2) multi` 选项（默认 1）。
+- **环境变量覆盖**：`DWS_SKILL_MODE=multi curl -fsSL ... | sh`。
+- **装完之后再切换**：`dws skill setup --mode multi`（或 `--mode mono`），随时重跑都行。

 </details>

@@ -387,19 +387,19 @@ dws aitable record query --base-id BASE_ID --table-id TABLE_ID --limit 10

 仓库内置完整的 Agent Skill 体系（`skills/` 目录），分为两套布局：

- `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），legacy。
- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。默认布局。
+- `skills/mono/` — 单 skill 布局（一个 `SKILL.md` + `references/products/`），默认推荐。
+- `skills/multi/` — 每个产品一个独立 skill（`dingtalk-aitable/` / `dingtalk-calendar/` / `dingtalk-chat/` ...），每个 skill 自带 `SKILL.md`。🧪 **试验版 / Preview — 各 multi `SKILL.md` 头部有详细注意事项。**

 Schema 生成的叶子 safety/参数/选型文案由 Go 中的 ProductDecl / ContractFinal 声明驱动。原 `internal/cli/schema_hints/` HintFile 目录已完全退役，不得重新引入。

 安装之后，Claude Code / Cursor 等 AI 工具就能通过自然语言直接操作钉钉：

 ```bash
-# 安装 skills 到当前项目（默认 multi；DWS_SKILL_MODE=mono 可切回）
+# 安装 skills 到当前项目（默认 mono）
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```

-> `install.sh` 安装到 `$HOME/.agents/skills/`（全局，multi 为按产品平铺，mono 为 `dws/` 子目录）；`install-skills.sh` 安装到 `./.agents/skills/`（当前项目）。
+> `install.sh` 安装到 `$HOME/.agents/skills/dws`（全局）；`install-skills.sh` 安装到 `./.agents/skills/dws`（当前项目）。
 >
 > 国内用户加 `DWS_GITEE_REPO` 走 Gitee 镜像，见 [国内加速安装](#国内加速安装)。

@@ -708,7 +708,7 @@ dws dev connect --channel auto --robot-client-id <id> --robot-client-secret <sec
 <summary>即将推出</summary>

 - `conference`（视频会议）
- 多 skill 模式（默认）— 每产品一个独立 skill，位于 `skills/multi/`，安装与升级默认启用；`dws skill setup --mode mono` 可切回单 skill
+- 多 skill 模式（实验中）— 每产品一个独立 skill，位于 `skills/multi/`，通过 `dws skill setup --mode multi` 启用

 </details>

@@ -127,15 +127,6 @@ function installSkillsToHomes(skillRoot) {
    if (index > 0 && !fs.existsSync(parentGate)) {
      return;
    }
-    // Mutual exclusion: remove multi leftovers before laying down mono.
-    // Directories only — a stray file named dingtalk-x.md must survive.
-    if (fs.existsSync(baseDir)) {
-      for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
-        if (entry.isDirectory() && (entry.name.startsWith("dingtalk-") || entry.name === "dws-shared")) {
-          fs.rmSync(path.join(baseDir, entry.name), { recursive: true, force: true });
-        }
-      }
-    }
    const destDir = path.join(baseDir, "dws");
    fs.rmSync(destDir, { recursive: true, force: true });
    copyChildren(skillRoot, destDir);
@@ -147,122 +138,23 @@ function installSkillsToHomes(skillRoot) {
  }
 }

-// multiTreeHasSkills mirrors multi_tree_has_skills in scripts/install.sh and
-// Test-MultiTreeHasSkills in scripts/install.ps1: true only when the multi
-// bundle carries at least one product skill (a subdir with SKILL.md). An
-// empty or corrupt multi/ tree must never select the multi branch nor refresh
-// the multi cache — installing it would wipe existing skills and lay down
-// nothing.
-function multiTreeHasSkills(dir) {
-  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
-    return false;
-  }
-  return fs
-    .readdirSync(dir, { withFileTypes: true })
-    .some((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, "SKILL.md")));
-}
-
-// installMultiSkillsToHomes mirrors installSkillsToHomes for the multi bundle:
-// every product skill becomes a sibling directory of the agent home. Mutual
-// exclusion: the mono leftover (dws/) and stale dingtalk-* skills not present
-// in the new bundle are removed first.
-function installMultiSkillsToHomes(multiRoot) {
-  const homeDir = os.homedir();
-  const skills = fs
-    .readdirSync(multiRoot, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && fs.existsSync(path.join(multiRoot, e.name, "SKILL.md")))
-    .map((e) => e.name);
-  if (skills.length === 0) {
-    throw new Error(`no product skills found under ${multiRoot}`);
-  }
-  const skillSet = new Set(skills);
-  let installed = 0;
-
-  const installToBase = (baseDir) => {
-    fs.mkdirSync(baseDir, { recursive: true });
-    fs.rmSync(path.join(baseDir, "dws"), { recursive: true, force: true });
-    for (const entry of fs.readdirSync(baseDir, { withFileTypes: true })) {
-      if (
-        entry.isDirectory() &&
-        (entry.name.startsWith("dingtalk-") || entry.name === "dws-shared") &&
-        !skillSet.has(entry.name)
-      ) {
-        fs.rmSync(path.join(baseDir, entry.name), { recursive: true, force: true });
-      }
-    }
-    for (const name of skills) {
-      const destDir = path.join(baseDir, name);
-      fs.rmSync(destDir, { recursive: true, force: true });
-      copyChildren(path.join(multiRoot, name), destDir);
-    }
-  };
-
-  AGENT_DIRS.forEach((agentDir, index) => {
-    const baseDir = path.join(homeDir, agentDir);
-    const parentGate = path.dirname(baseDir);
-    if (index > 0 && !fs.existsSync(parentGate)) {
-      return;
-    }
-    installToBase(baseDir);
-    installed += 1;
-  });
-
-  if (installed === 0) {
-    installToBase(path.join(homeDir, ".agents", "skills"));
-  }
-}
-
-// resolveSkillMode mirrors scripts/install.sh: DWS_SKILL_MODE (mono|multi)
-// wins; multi is the default. The --skill-mode flag accepts both the space
-// form (`--skill-mode mono`) and the equals form (`--skill-mode=mono`).
-function resolveSkillMode() {
-  const raw = (process.env.DWS_SKILL_MODE || "").trim().toLowerCase();
-  if (raw === "mono" || raw === "multi") {
-    return raw;
-  }
-  if (raw !== "") {
-    throw new Error(`invalid DWS_SKILL_MODE='${process.env.DWS_SKILL_MODE}'. Use 'mono' or 'multi'.`);
-  }
-  let fromFlag;
-  const flagIndex = process.argv.indexOf("--skill-mode");
-  if (flagIndex !== -1 && process.argv[flagIndex + 1]) {
-    fromFlag = process.argv[flagIndex + 1];
-  } else {
-    const equalsArg = process.argv.find((arg) => arg.startsWith("--skill-mode="));
-    if (equalsArg) {
-      fromFlag = equalsArg.slice("--skill-mode=".length);
-    }
-  }
-  if (fromFlag !== undefined) {
-    const mode = fromFlag.trim().toLowerCase();
-    if (mode === "mono" || mode === "multi") {
-      return mode;
-    }
-    throw new Error(`invalid --skill-mode '${fromFlag}'. Use 'mono' or 'multi'.`);
-  }
-  return "multi";
-}
-
 // cacheUserSkills copies the mono and multi trees out of the freshly extracted
 // dws-skills.zip into ~/.dws/skills/{mono,multi}/ so that `dws skill setup`
-// can fall back to a user-local cache when --source is not provided. A cache
-// is only refreshed when the new bundle actually carries that tree — an
-// empty/corrupt multi/ (or a missing mono tree) must never wipe a previously
-// good cache.
+// can fall back to a user-local cache when --source is not provided. mono is
+// already installed into agent homes by installSkillsToHomes; the cache is
+// purely a source-of-truth for the setup command.
 function cacheUserSkills(extractedSkillsRoot) {
  const cacheBase = path.join(os.homedir(), ".dws", "skills");

  const monoSource = fs.existsSync(path.join(extractedSkillsRoot, "mono", "SKILL.md"))
    ? path.join(extractedSkillsRoot, "mono")
    : extractedSkillsRoot;
-  if (fs.existsSync(path.join(monoSource, "SKILL.md"))) {
-    const monoCache = path.join(cacheBase, "mono");
-    fs.rmSync(monoCache, { recursive: true, force: true });
-    copyChildren(monoSource, monoCache);
-  }
+  const monoCache = path.join(cacheBase, "mono");
+  fs.rmSync(monoCache, { recursive: true, force: true });
+  copyChildren(monoSource, monoCache);

  const multiSource = path.join(extractedSkillsRoot, "multi");
-  if (multiTreeHasSkills(multiSource)) {
+  if (fs.existsSync(multiSource) && fs.statSync(multiSource).isDirectory()) {
    const multiCache = path.join(cacheBase, "multi");
    fs.rmSync(multiCache, { recursive: true, force: true });
    copyChildren(multiSource, multiCache);
@@ -299,25 +191,7 @@ function main() {
  const monoRoot = fs.existsSync(path.join(skillsStaging, "mono", "SKILL.md"))
    ? path.join(skillsStaging, "mono")
    : skillsStaging;
-  // A mono install requires an actual SKILL.md at the root of monoRoot. On a
-  // multi-only zip monoRoot would degrade to the staging root and copy the
-  // whole bundle (multi/ included) into a dws/ directory — skip instead.
-  const monoHasSkill = fs.existsSync(path.join(monoRoot, "SKILL.md"));
-  const multiRoot = path.join(skillsStaging, "multi");
-  const skillMode = resolveSkillMode();
-  if (skillMode === "multi" && multiTreeHasSkills(multiRoot)) {
-    console.log(`Skill mode: multi — installing per-product skills`);
-    installMultiSkillsToHomes(multiRoot);
-  } else {
-    if (skillMode === "multi") {
-      console.log("multi skill tree not found or empty in bundle; falling back to mono.");
-    }
-    if (monoHasSkill) {
-      installSkillsToHomes(monoRoot);
-    } else {
-      console.log("mono skill tree not found in bundle; skipping skill install.");
-    }
-  }
+  installSkillsToHomes(monoRoot);
  cacheUserSkills(skillsStaging);
 }

@@ -40,7 +40,7 @@ Every command inherits these flags (documented here once, not repeated per comma
 - [`dws doc` — DingTalk Doc](#dws-doc) · 21 commands
 - [`dws drive` — DingTalk Drive](#dws-drive) · 6 commands
 - [`dws minutes` — AI Minutes](#dws-minutes) · 19 commands
- [`dws oa` — OA Approval](#dws-oa) · 9 commands
+- [`dws oa` — OA Approval](#dws-oa) · 12 commands
 - [`dws report` — Reports](#dws-report) · 7 commands
 - [`dws todo` — Todo Tasks](#dws-todo) · 6 commands

@@ -277,14 +277,17 @@ _AI meeting notes: listing, summary, todos, transcription, recording control, mi

 ## `dws oa` — OA Approval

-_OA approval workflows: list, approve, reject, revoke, records._
+_OA approval workflows: inspect forms, forecast routes, create instances, approve, reject, revoke, and audit records._

-**9 commands**
+**12 commands**

 | Command | Description | When to use |
 |---|---|---|
 | `dws oa approval approve` | Approve a pending approval process instance (task) as the current user. | When the agent acts on a pending approval the user has delegated it to handle. |
+| `dws oa approval create-instance` | Create a real approval process instance from validated form values or a complete request payload. | After the agent has inspected the form Schema, forecast the route, resolved any selectable approvers, and obtained explicit user confirmation. |
 | `dws oa approval detail` | Retrieve full details of an approval process instance, including form fields, attachments, and state. | When the agent needs to read the content of an approval ticket before deciding on it or summarizing it. |
+| `dws oa approval form-schema` | Retrieve the form Schema for an approval template by processCode. | Before collecting or validating values for a new approval instance. |
+| `dws oa approval forecast-process` | Forecast the approval route for a template and its proposed form values. | Before creating an instance, especially when the route contains user-selectable approver or notifier nodes. |
 | `dws oa approval list-forms` | List approval process templates (forms) the current user is allowed to initiate. | When the agent needs to pick the right approval form before submitting a new request. |
 | `dws oa approval list-initiated` | List approval process instances the current user has initiated. | When the agent reviews the status of approvals the user submitted. |
 | `dws oa approval list-pending` | List approval process instances currently awaiting action from the current user. | When the agent surfaces "needs your approval" items in the user's inbox. |
@@ -1,272 +0,0 @@
-# Skill 分发/安装架构优化方案
-
-> 目标：把 DWS Agent skill 的"装在哪、怎么装、装完记什么"从 7+ 个安装面的
-> N 份漂移拷贝，收敛为 **Go 侧单一事实源 + 单一安装引擎 + 脚本侧 bootstrap**。
-> 本文基于 feat/skill-mode-migration 工作区（multi 化落地后）的代码级盘点
-> （2026-08-05），所有锚点均可跳转验证。
-> 前置文档：[skill-multi-migration-plan.md](skill-multi-migration-plan.md)（下称《迁移计划》）、
-> [skill-distribution-mechanism.md](skill-distribution-mechanism.md)。
-
-## 1. 问题量化
-
-### 1.1 复制矩阵（能力 × 面）
-
-multi 化之后，同一块逻辑在各安装面的拷贝数（✓ = 独立拷贝一份，数字 = 份数）：
-
-| 能力 \ 面 | install.sh | install.ps1 | npm install.js | install-skills.sh | install-event.sh | install-devapp.sh(+ps1) | Homebrew caveats | `dws skill setup` (Go) | `dws upgrade` (Go) |
-|---|---|---|---|---|---|---|---|---|---|
-| agent home 清单 | ✓×3 | ✓ | ✓ | ✓×2 | ✓ | ✓×2 | — | ✓ | ✓ |
-| 互斥清理（mono↔multi） | ✓×2（其中 1 份死代码） | ✓ | ✓ | ✓ | — | — | — | ✓ | ✓ |
-| mode 解析（env/flag/交互） | ✓ | ✓ | ✓ | — | — | — | — | ✓ | 布局嗅探 |
-| stale `dingtalk-*` 清理 | ✓ | ✓ | ✓ | ✓ | — | — | — | ✗（additive，不清） | ✓ |
-| `~/.dws/skills` 缓存写 | ✓ | ✓ | ✓ | — | ✓ | ✓ | — | —（只读回退） | ✓（仅 multi） |
-| 安装状态（state.json） | 无 | 无 | 无 | 无 | 无 | 无 | — | 无 | 无 |
-
-清单锚点（agent home 清单，全仓共 **15 份**）：
-
-| # | 位置 | 备注 |
-|---|---|---|
-| 1 | `internal/app/skill_setup.go:20-37` | `skillSetupAgentHomes`，16 项，**无 opencode** |
-| 2 | `internal/app/skill_command.go:119-141` | `agentSkillPaths`，17 项，含 opencode（`:129`） |
-| 3 | `internal/upgrade/paths.go:35-52` | `knownSkillDirs`，16 项，**无 opencode** |
-| 4 | `scripts/install.sh:370-386` | mono 安装循环内联清单 |
-| 5 | `scripts/install.sh:439-455` | multi 清单（**死代码**，见 1.2） |
-| 6 | `scripts/install.sh:516-532` | multi 清单（生效） |
-| 7 | `scripts/install.ps1:44-61` | `$AgentDirs` |
-| 8 | `build/npm/install.js:11-28` | `AGENT_DIRS` |
-| 9 | `scripts/install-skills.sh:166-182` | multi 清单 |
-| 10 | `scripts/install-skills.sh:247-261` | mono 清单 |
-| 11 | `scripts/install-event.sh:103-107` | 17 项，**含 `.config/opencode/skills`**（`:107`） |
-| 12 | `scripts/install-devapp.sh:87-91` | 含 opencode（`:91`） |
-| 13 | `scripts/install-devapp.ps1:106` | 含 opencode |
-| 14 | `test/scripts/package_script_test.go` | `expectedPackagedSkillTargets` |
-| 15 | `scripts/release/verify-package-managers.sh:75-76` | `HOME_AGENT_PARENTS` / `HOME_SKILL_TARGETS` |
-
-互斥清理逻辑共 **≥8 份**：`skill_setup.go:570-608`、`paths.go:306-327` +
-`paths.go:163-179`（mono 分支内联）、`install.sh:394-399` + `install.sh:557-570`
-+ 死代码 `install.sh:477-486`、`install.ps1:488-498` + `install.ps1:562-570`、
-`install.js:130-137` + `install.js:165-178`、`install-skills.sh:207-220`。
-
-mode 解析共 **4 份**：`skill_setup.go:343-376`、`install.sh:220-257`、
-`install.ps1:293-332`、`install.js:197-214`（各自实现 env 优先级、非法值报错、
-TTY 交互、非 TTY 默认值，措辞与行为细节已不完全一致）。
-
-stale `dingtalk-*` 清理共 **5 份**：`paths.go:317-325`、`install.sh:561-567`、
-`install.ps1:562-570`、`install.js:168-172`、`install-skills.sh:211-220`。
-
-缓存写共 **6 份**：`install.sh:326-344`（multi）+ `install.sh:349-360`（mono）、
-`install.ps1:446-471`、`install.js:221-237`、`install-event.sh:165-169`、
-`install-devapp.sh:82-84`、`paths.go:290-296`（upgrade 只刷 multi）。
-
-### 1.2 已发生的漂移实例（不是假设，是现状）
-
-1. **opencode 清单漂移**：`dws skill install` 支持 opencode 目标
-   （`skill_command.go:129`），install-event / install-devapp 也往
-   `~/.config/opencode/skills` 装（`install-event.sh:107`、
-   `install-devapp.sh:91`），但 `dws skill setup --target all` 与
-   `dws upgrade` 的清单都不含它（`skill_setup.go:20-37`、
-   `paths.go:35-52`）。结果：opencode 用户能收到 event/dev skill，
-   却永远收不到内置 skill 的安装与升级。
-2. **install.sh 死代码**：`install_multi_skills_to_homes` 定义了两次
-   （`install.sh:434` 与 `install.sh:511`），`_install_multi_to_base`
-   同样两次（`install.sh:473` 与 `install.sh:549`）。bash 后定义覆盖先定义，
-   第一对（434-505）整体是死代码——本次 multi 化自己引入的重复。
-3. **"镜像"注释与实现已不符**：`install.sh:507-510` 注释声称 multi 安装
-   "mirroring `dws skill setup --mode multi`"，但脚本会删除 bundle 里不存在
-   的 stale `dingtalk-*`（`install.sh:561-567`），而 setup 是 additive 语义、
-   只清 `dws/`（`skill_setup.go:587-593`）。注释说镜像，行为已分叉。
-4. **互斥语义自相矛盾**：install-event.sh 把 multi 的 `dingtalk-event` 和
-   mono 的 `dws` **同时**装进同一批 agent home（`install-event.sh:171-172`），
-   与其他所有面"mono/multi 互斥"的语义直接冲突。
-5. **缓存只写不读、版本不可见**：`dws skill setup` 默认走二进制 embed
-   （`skill_setup_embed.go:50-59`），`~/.dws/skills` 只是 legacy 回退候选
-   （`skill_setup.go:442-447`）；6 个写入方没有任何版本戳，upgrade 只刷
-   multi 不刷 mono（`paths.go:292-296`），缓存与 embed 漂移不可见。
-6. **保留前缀规则已双份**：`dingtalk-` / `dws-shared` 的保留约定在
-   `skill_setup.go:199`（`multiSkillPrefix`）、`skill_setup.go:205`
-   （`multiSharedSkill`）与 `paths.go:332-334`（`isMultiSkillDirName`）
-   各写一份，互斥清理依赖"市场 skill 不用该前缀"这一隐性约定。
-
-### 1.3 维护成本论证（本次 multi 化实证）
-
-本次"把 7 个面全部 multi 化"这一个语义变更，工作区改动为 **13 个文件、
-+759/−166 行**（`git diff --stat`），横跨 Go / POSIX sh / PowerShell /
-JavaScript 四种语言：
-
-| 文件 | 改动量 | 改了什么 |
-|---|---|---|
-| `scripts/install.sh` | +256/−… | mode 解析、multi 安装×2（含死代码）、互斥清理、缓存写 |
-| `scripts/install.ps1` | +169 | 同上，PowerShell 再写一遍 |
-| `build/npm/install.js` | +87 | 同上，JavaScript 再写一遍 |
-| `scripts/install-skills.sh` | +101 | multi 安装 + stale 清理 |
-| `internal/upgrade/paths.go` | +206 | upgrade multi 刷新 + 互斥清理 + 缓存 |
-| `internal/app/skill_setup.go` 等 Go 侧 | ~+50 | setup multi 语义 |
-| 测试与文档 | 其余 | 4 个测试文件 + README×2 + SKILL.md |
-
-即：**一个语义变更 = 4 种语言 × 7+ 处同步编辑**，且仍然漏了 opencode、
-制造了死代码、留下了语义分叉（1.2）。新增一个 agent home 今天要改 15 份
-清单中的至少 11 份（另 4 份是测试/校验）。这不是"以后会漂移"，而是
-**每一次改动都在当场制造漂移**。
-
-## 2. 目标架构
-
-### 2.1 分层总览
-
-```text
-┌──────────────────────────────────────────────────────────────────┐
-│ L3 分发面（7 个，全部退化为 bootstrap）                            │
-│   install.sh / install.ps1 / npm install.js / install-skills.sh /│
-│   install-event.sh / install-devapp.sh / Homebrew caveats        │
-│   职责：装二进制 → exec `dws skill setup --mode X --yes`           │
-│         └─ 失败 → 冻结的内嵌 fallback 拷贝（一档，不再演进）        │
-├──────────────────────────────────────────────────────────────────┤
-│ L2 单一安装引擎（Go，唯二入口）                                    │
-│   dws skill setup  ─┐                                            │
-│   dws upgrade      ─┴─► 共用同一 install 实现（含互斥清理/记账）   │
-├──────────────────────────────────────────────────────────────────┤
-│ L1 单一事实源：internal/skillhome（新共享包）                      │
-│   AgentHomes() 清单 + 布局规则（mono→<home>/dws，multi→平铺）      │
-│   + 互斥/ stale 清理规则 + 保留前缀常量 + state.json 读写          │
-├──────────────────────────────────────────────────────────────────┤
-│ L0 事实数据                                                       │
-│   //go:embed skills/{mono,multi}（skills_embed.go:28，默认源）     │
-│   ~/.dws/skills/state.json（权威安装状态）                         │
-│   ~/.dws/skills/{mono,multi}（显式回退源，带版本戳，唯一写方=Go）  │
-└──────────────────────────────────────────────────────────────────┘
-        ▲ 门禁：scripts/policy/check-agent-homes-sync.sh（进 make policy）
-        比对各脚本可解析清单块 ↔ skillhome 导出清单
-```
-
-### 2.2 单一事实源：`internal/skillhome` 共享包
-
-新建 `internal/skillhome`，把今天散在 3 处 Go 代码里的规则合并导出，
-setup / upgrade / 测试共用（对应《迁移计划》P0c-1）：
-
-| 导出物 | 收敛的现有拷贝 |
-|---|---|
-| `AgentHomes()`（含 opencode，带"首项必装/其余父目录门控"元数据） | `skill_setup.go:20-37`、`paths.go:35-52`，并与 `skill_command.go:119-141` 互相断言 |
-| `HomeForMode(base, mode)` 布局规则 | `skill_setup.go:502-507`（`agentHomeForMode`） |
-| `MutualExclusionVictims(home, mode)` / stale 判定 | `skill_setup.go:570-596`、`paths.go:306-327` |
-| `ReservedSkillPrefixes` / `ReservedSkillNames` 常量 | `skill_setup.go:199/205`、`paths.go:332-334` |
-| `State` 读写（state.json，见 2.4） | 新增（《迁移计划》P0b-1） |
-
-脚本侧不生成代码（sh/ps1/js 三语言片段生成成本高、措辞差异大），改为
-**可解析标记块 + policy 比对**：每个脚本的清单包在
-`# DWS-AGENT-HOMES-BEGIN` / `# DWS-AGENT-HOMES-END` 注释块内，新增
-`scripts/policy/check-agent-homes-sync.sh` 提取 7 个脚本块与
-`skillhome` 导出清单（`go run ./internal/skillhome/cmd/dump` 或
-`dws skill setup --print-agent-homes` 之类调试出口）逐一比对，挂进
-`make policy`（Makefile:86-97 现有政策链）。对应《迁移计划》P0c-2。
-
-### 2.3 安装逻辑单引擎化：脚本退化为 bootstrap
-
-**终态形态**：每个安装脚本只做两件事——装二进制、执行
-`dws skill setup --mode <resolved> --yes`（mode 解析仍允许脚本做，因为它
-要处理自己的 env/flag；也可以更进一步把 `DWS_SKILL_MODE` 透传给 setup）。
-执行失败（二进制跑不起来、setup 非 0 退出）时，降级到**冻结的内嵌
-fallback 拷贝逻辑一档**——即今天的拷贝实现原样保留但标记"不再演进"，
-语义变更只改 Go 引擎。
-
-各面降级可行性分析：
-
-| 面 | 二进制可得性 | 可行性 | 风险与对策 |
-|---|---|---|---|
-| install.sh | `main` 先 `install_binary` 后 `install_skills`（`install.sh:830-831`），二进制就在 `$INSTALL_DIR` | ✅ 直接调 `"$INSTALL_DIR/dws" skill setup --mode "$SKILL_MODE" --yes` | `DWS_SKILLS_ONLY=1` 时不装二进制 → 先 `command -v dws`，无则走 fallback。curl 下载不带 quarantine 属性，macOS 可直接执行。风险低 |
-| install.ps1 | 同序（`Install-Binary`:337 → `Install-Skills`:622，main 入口 `:700`） | ✅ 调 `& $installDir\dws.exe skill setup ...` | ExecutionPolicy 约束的是 .ps1 脚本本身，**子进程 dws.exe 不受其限制**；AppLocker/WDAC 环境可能拦未签名二进制——但那种环境 dws 本身也跑不了，fallback 拷贝仍必要。风险低-中 |
-| npm install.js | postinstall 已把平台二进制解到 `vendor/`（`install.js:260`）再装 skill（`:271-280`） | ✅ `execFileSync(path.join(vendorDir,'dws'), ['skill','setup','--mode',m,'--yes'])` | `npm i --ignore-scripts` 时 postinstall 整体不跑（现状如此，非新增风险）；部分 CI 以 root 跑生命周期脚本权限怪异；Windows 用 `dws.exe`。风险中，fallback 必须保留 |
-| install-skills.sh | skills-only 面，不装二进制 | ✅ `command -v dws` 有则调引擎，无则 fallback | 本质是"刷新 skill"路径，有 dws 才谈得上刷新。风险低 |
-| install-event.sh | 装二进制 + 单 skill（dingtalk-event + mono dws） | ⚠️ 有条件 | `EVENT_VERSION` 可与已装二进制版本不同（尤其 `DWS_SKILLS_ONLY=1`），embed 与目标 zip 可能错配；且当前同时装 mono+multi 的语义（`:171-172`）需先按 1.2-4 收敛。**最后迁移**，迁移前先把 dingtalk-event 纳入 embed 并改成 `-s event` 调引擎 |
-| install-devapp.sh(+ps1) | 同上（dingtalk-dev） | ⚠️ 有条件 | 同 install-event。风险中-高，最后迁移 |
-| Homebrew caveats | 只打印提示 | ✅ 已是终态 | `homebrew.rb.tmpl:33-36` 现状就是"Run `dws skill setup`"，无需改，是其他面的样板 |
-
-配套收益：《迁移计划》P2-2（sh/ps1 的 multi 分支真装，1.5d）与 P2-3
-（install.js / install-skills.sh 加 mode 支持，1d）在单引擎方案下**大幅
-缩水**——脚本只需把 mode 透传给引擎，不再在 sh/ps1/js 里写安装逻辑。
-
-### 2.4 状态与缓存
-
- **state.json 权威化**（《迁移计划》P0b 原样采纳）：
-  `~/.dws/skills/state.json` 记录 `schema_version / mode / cli_version /
-  installed / agent_homes / previous`，写方只有 `dws skill setup` 与
-  `dws upgrade`（脚本侧不再各自写状态——它们调引擎，引擎记账）；缺失/损坏
-  时按磁盘形态反推（有 `dws/` → mono；有 `dingtalk-*` → multi；都有 →
-  报 drift 要求显式收敛）。
- **`~/.dws/skills` 缓存收敛**：二选一，本文建议后者——
-  1. ~~被 state 取代，删除缓存~~：激进；embed 之外的"无源码机回退源"场景
-     （`skill_setup.go:442-447` 注释描述的场景）会断。
-  2. **明确为 setup 回退源 + 版本戳**（采纳）：缓存目录写入
-     `cli_version` 戳文件（或并入 state.json 的 `cache_version` 字段）；
-     **写缓存收敛到 Go 侧唯一实现**（setup/upgrade 共用），install.sh /
-     ps1 / js / event / devapp 的 6 份缓存写逻辑（1.1 矩阵）随 P1/P3 删除；
-     upgrade 补齐 mono 缓存刷新（修 `paths.go:292-296` 只刷 multi 的不对称）。
-     mono 下线版本再评估整体废弃缓存。
-
-### 2.5 市场 skill 边界正式化
-
-把"`dingtalk-*` 前缀与 `dws-shared` / `dws` 名称为 DWS 内置保留"从隐性约定
-变成共享常量 + 测试：
-
- `skillhome.ReservedSkillPrefixes = ["dingtalk-"]`、
-  `skillhome.ReservedSkillNames = ["dws-shared", "dws"]`，替换
-  `skill_setup.go:199/205` 与 `paths.go:332-334` 两份私有拷贝；所有互斥/
-  stale 清理只认这两个常量。
- 测试一：扫描 `skills/multi/` 实际目录名，断言全部命中保留规则（防新增
-  产品 skill 破坏前缀约定）。
- 测试二：市场 skill 安装路径（`skill_command.go:488-498` 的目标解析）若
-  产物名命中保留名则拒绝安装——把"市场无同名前缀"从祈祷变成门禁。
-
-## 3. 迁移步骤（渐进、不破坏存量用户）
-
-| 阶段 | 内容 | 风险 |
-|---|---|---|
-| **P0 清单 + policy** | 建 `internal/skillhome`：AgentHomes（**补 opencode**，修 1.2-1）、布局/互斥/保留名常量；setup/upgrade 切到共享包；脚本清单包标记块；新增 `check-agent-homes-sync.sh` 进 `make policy`；删 install.sh 死代码（1.2-2） | 低。纯收敛不改行为；policy 脚本初期可能误报 → 先 warn-only 跑一个版本再转 hard-fail |
-| **P1 setup 单引擎 + 脚本降级** | setup/upgrade 安装实现合一（互斥清理、stale 语义统一为"引擎内一种"，修 1.2-3）；install.sh / install.ps1 / install.js / install-skills.sh 改为 bootstrap + 冻结 fallback；install-event/devapp 暂不动 | 中。bootstrap 首版要在三语言 CI 矩阵上验证"引擎失败→fallback"链路；fallback 标记冻结，防止继续演进出第 9 份拷贝 |
-| **P2 state 权威 + 缓存收敛** | state.json 读写进 skillhome，setup/upgrade 记账；缓存加版本戳、写方收敛到 Go、upgrade 补刷 mono 缓存；install-event/devapp 语义收敛（mono+multi 双装改为引擎语义）后同样 bootstrap 化 | 中。存量机器无 state → 磁盘反推逻辑必须有故障注入测试；event/devapp 版本错配场景需保留 zip 直装逃生门 |
-| **P3 删除遗留拷贝** | 删除：脚本侧 6 份缓存写、install.sh/ps1/js 内被引擎接管的安装函数（保留冻结 fallback 一档）、Go 侧 `mutualExclusionVictims` 等被 skillhome 吸收的私有拷贝；观察一个版本后评估 fallback 是否可再降档 | 低-中。每删一处先确认 policy 与测试不再引用；fallback 删除是独立决策，不与本阶段捆绑 |
-
-与《迁移计划》的先后关系：本文 P0 即计划 P0c，应**最先做**；P1 与计划
-P0a/P0b 并行不冲突（引擎合一会让 P0a 的 mode-aware upgrade 少写一份代码）；
-P2 吸收计划 P0b；P3 在计划 P2 切默认之后执行。
-
-## 4. 明确不做
-
- **不重写成 symlink canonical**（canonical 一份 + 各 agent home 软链）：
-  已随生态分发通道一并评估否决，决策与实测原因见
-  《迁移计划》[§7.3](skill-multi-migration-plan.md)（无版本固定、依赖
-  Node/GitHub 可达、mono 会被一起发现、悟空 bundled/离线预装覆盖不了；
-  其中悟空分发线已于 2026-08-05 下线，该条约束随之消失）。
-  本地 symlink 模式（`setup --link`）同样维持计划 §8.2"可选/后置"定位，
-  不在本方案内。
- **不动 `dws-skills.zip` 产物布局**：zip 根 mono 副本 + `mono/` + `multi/`
-  双树保持不变（`scripts/release/post-goreleaser.sh:220-248`）。
- **不动市场 skill**：`dws skill install` 的安装语义、目标解析
-  （`skill_command.go:488-498`）不变；2.5 只新增保留名拒绝门禁与测试，
-  不改变既有安装行为。
- **不删 fallback**：脚本侧内嵌拷贝逻辑降级为冻结档保留，不追求"脚本零
-  拷贝"的纯净化。
-
-## 5. 收益/成本与任务映射
-
-### 5.1 收益/成本表
-
-| 项 | 现状 | 目标 | 量化收益 |
-|---|---|---|---|
-| agent home 清单 | 15 份拷贝，已漂移（opencode） | 1 份 Go 源 + policy 比对 | 新增 agent 从"改 11 处"变"改 1 处" |
-| 安装/互斥/stale 逻辑 | ≥8 份，4 种语言，语义已分叉 | 1 个 Go 引擎 | 语义变更从 4 语言 × 7 面（本次实证 13 文件 +759 行）变 1 包 |
-| mode 解析 | 4 份，行为细节不一 | 脚本只做透传，引擎一处实现 | 非法值/默认值行为天然一致 |
-| 缓存写 | 6 份，无版本戳，只写不读 | Go 唯一写方 + 版本戳 | 缓存漂移可观测、可判废 |
-| 安装状态 | 无 | state.json 权威 | upgrade 粘性、回滚、drift 检测的前提 |
-| 市场边界 | 隐性约定，2 份前缀拷贝 | 共享常量 + 2 个测试 | 互斥清理误伤市场 skill 的风险归零 |
-| 成本 | — | P0≈1.5d，P1≈3-4d，P2≈2d，P3≈1d | 合计 7.5-8.5 人日；其中 P0/P2 与《迁移计划》P0b/P0c 重叠，净新增约 4-5 人日 |
-
-### 5.2 与《迁移计划》§8 任务 ID 映射
-
-| 本文阶段 | 对应计划任务 | 关系 |
-|---|---|---|
-| P0 清单 + policy | P0c-1（清单下沉共享包+补 opencode）、P0c-2（check-agent-homes-sync.sh） | 原样采纳，包名定为 `internal/skillhome` |
-| P1 引擎合一 | P0a-1（UpgradeSkillLocations mode-aware）的前置简化 | 引擎合一后 P0a-1 不复写互斥/清理逻辑 |
-| P1 脚本 bootstrap | **取代** P2-2（sh/ps1 multi 真装，1.5d）、P2-3（install.js/install-skills.sh mode 支持，1d） | 脚本不再写安装逻辑，两个任务缩水为"透传 mode + 调引擎 + 冻结 fallback"，合计从 2.5d 降至 ~1d |
-| P2 state 权威 | P0b-1（state.json schema+setup 写入）、P0b-2（磁盘反推） | 原样采纳；缓存版本戳与写方收敛为本文新增 |
-| P2 event/devapp 收敛 | 新增（修 1.2-4 语义矛盾） | 依赖 P1 引擎稳定 |
-| P3 删除遗留 | 新增 | 在计划 P2 切默认之后执行 |
-| （不在本文） | P0-3 备份式安装、P0-4 请求头、P1-1 `dws skill mode`、P1-2/P2-1 默认翻转、P2-4 文案 | 仍按计划执行，与本文正交；备份式安装落地时直接写进引擎，天然覆盖所有面 |
@@ -1,231 +0,0 @@
-# Skill 能力缺口分析与补全计划
-
-> 基于 `feat/skill-mode-migration` 工作区代码级盘点（2026-08-05）。本工作区已把
-> install / upgrade / setup 的默认形态翻转为 multi；本文回答两个问题：
-> **管理能力上还缺什么**（Part 1）、**multi 内容是否覆盖 mono**（Part 2），
-> 并给出优先级排序的实施清单（Part 3）。
-> 任务 ID 复用 [skill-multi-migration-plan.md](skill-multi-migration-plan.md) §8.2
-> （P0a/P0b/P0c/P0-3/P0-4/P1-1/P1-2/P2-x/W4）；新增项以 `P1-3`、`C1–C7` 编号。
-> 机制背景见 [skill-distribution-mechanism.md](skill-distribution-mechanism.md)。
-
-## 0. 结论速览
-
- **管理面**：默认翻转已落地（setup/四个安装脚本/upgrade 识 multi），但生命周期
-  能力仍缺 6/8 项：无状态（state.json）、无备份回滚、无卸载、无故障恢复、
-  upgrade 不按已装清单做增量、市场/内置边界靠前缀约定。当前形态 = "能装上
-  multi，但装成什么样、出了事怎么退，全靠运气"。
- **内容面**：multi 对产品参考的覆盖**总体是 mono 超集**（chat/event/dev/sheet
-  均更详细），但 mono 有 **4 块全局能力在 multi 完全缺失**（recovery 闭环、
-  确认门禁协议、Schema 渐进查询教学、LICENSE/NOTICE），另有 1 个脚本
-  （`report_inbox_today.py`）未迁移；multi 自身还有 6 项内部不一致（死链、
-  orphan 脚本、漏改 EXPERIMENTAL 文案等）。
- **工作量**：管理面 P0–P2 剩余 ≈ 10.5–13 人日；内容补全 C1–C7 ≈ 3.5–4 人日；
-  合计 ≈ 14–17 人日，与 plan §8.1 的 13–17 人日口径一致（内容项是新增量）。
-
---
-
-## Part 1 — 管理能力缺口（skill 生命周期管理）
-
-### 1.1 现状盘点（本工作区实际状态）
-
-**`dws skill setup`（内置 skill 安装）**
-
-| 能力 | 状态 | 锚点 |
-|---|---|---|
-| mode 选择 | mono / multi；无 `--mode` 时 TTY 交互（multi 为默认项）、非 TTY 默认 multi | `internal/app/skill_setup.go:343-376` |
-| 按产品挑选 | `-s/--skill`、`-x/--exclude` 互斥；`dws-shared` 强制包含；未点名的已有 `dingtalk-*` 保留（additive） | `skill_setup.go:101-102`、`254-318`、`209-226`、`640-670` |
-| `--dry-run` | 有，预览 mode/来源/目标/子 skill，不写文件（root 持久 flag 注入，`internal/app/flags.go:43`） | `skill_setup.go:156-167` |
-| 源 | `--source` / `DWS_SKILL_SOURCE` 显式覆盖（失败不回退）→ 默认 embed（与二进制同版） | `internal/app/skill_setup_embed.go:50-58`、`skills_embed.go:28` |
-| 目标 | 16 个 agent home，父目录门控；`--target all` 不含 opencode，但命名 target 含（不对称） | `skill_setup.go:20-37`、`509-522` vs `internal/app/skill_command.go:129` |
-| 互斥清理 | 装 mono 删 `dingtalk-*`+`dws-shared`，装 multi 删 `dws/`；**best-effort，失败仅 warning 继续装** | `skill_setup.go:570-608` |
-| 备份/记账 | **无**。`RemoveAll` 直删，不写任何状态 | `skill_setup.go:616`、`655` |
-
-**`dws skill search / get / install`（市场 skill）**
-
- 子命令全集仅 `get / install / search / setup`（+ 隐藏的 find/add 兼容提示），
-  **无 status / mode / remove / rollback**（`skill_command.go:202-209`）。
- `install` 解压到 agent skills **根目录**（非 `dws/` 子目录），无 mode 概念、
-  无记账、无覆盖保护（`skill_command.go:378-443`、`653-672`）。
-
-**`dws upgrade`（skill 刷新）**
-
- `LocateSkillsRoot` **优先 zip 内 `multi/`**（`internal/upgrade/paths.go`，
-  接线于 `internal/app/upgrade.go`）；`UpgradeSkillLocations` **包驱动**：有
-  multi 树则始终 multi 刷新，否则 legacy mono 回退（不做磁盘粘性）。
- multi 路径：平铺刷新 `<agent>/dingtalk-*`+`dws-shared`，清 `dws/` 残留与过期
-  `dingtalk-*`，best-effort 刷 `~/.dws/skills/multi`（sibling `mono/` 存在时
-  亦刷 mono 缓存）。
- **有 multi 包时存量 mono 一次性迁 multi**（2026-08-05 owner：升级不做粘性；
-  非运行时 mode-switch 产品，无确认/备份/state）。
- skill 安装发生在**二进制替换之后**，skill 失败时二进制已换 → 半升级态。
-  `dws upgrade --rollback` 只回滚二进制。
-
-**安装脚本（7 面）**
-
-| 面 | 本工作区状态 |
-|---|---|
-| `scripts/install.sh` | 已默认 multi 且**真装**（`install_multi_skills_to_homes`），mono 为 opt-in；`rm -rf` 直删无备份 |
-| `scripts/install.ps1` | 同上（Windows） |
-| `scripts/install-skills.sh` | 已加 `DWS_SKILL_MODE`（默认 multi）+ multi 安装 |
-| `build/npm/install.js` | 已加 `installMultiSkillsToHomes`（互斥清理 + 平铺） |
-| Homebrew formula | 不铺 agent home，caveats 引导 `dws skill setup` |
-| `scripts/install-event.sh` / `install-devapp.sh` | 单 skill 专项语义，缓存 `multi/dingtalk-event` / `multi/dingtalk-dev` 子集 |
-| 共同缺口 | **均不写 state.json、均无备份**；agent home 清单仍是 sh/ps1/js/Go 多份手写（`paths.go:23-52` 的 keep-in-sync 注释约定，无门禁） |
-
-### 1.2 缺口表（对照完整生命周期）
-
-严重度：🔴 高（可致数据丢失/双份派发/半装态）｜🟡 中（能力缺失但有绕行）｜🟢 低（体验项）
-
-| # | 生命周期项 | 现状 | 严重度 | 补全设计（复用 plan §8 ID） |
-|---|---|---|---|---|
-| 1 | **status 查询** | **无**。无 state.json、无 `dws skill mode/status`；判断 mode 只能人工看磁盘形态（`dws/` vs `dingtalk-*`） | 🔴 | **P0b-1** 新增 `~/.dws/skills/state.json`（schema_version/mode/cli_version/installed/agent_homes/previous），setup 与安装脚本写入；**P0b-2** 缺失/损坏时磁盘形态反推，双形态并存 → drift 报错；**P1-1** `dws skill mode`（status 子命令展示 mode/版本/已装列表/上次切换/备份） |
-| 2 | **切换** | 有（`setup --mode`），但**无状态、无记账**：切完不留 previous，互斥清理失败仅 warning 继续装（`skill_setup.go:600-608`）→ 可能 mono+multi 双份共存、Agent 双份派发 | 🔴 | **P0b** 记账（含 `previous`）；**P0-3** 把「清理失败继续装」改为「失败整体回滚」；**P1-1** `mode set <mode>` 复用 setup 安装实现 + 备份 + 记账，成功后提示重启 AI 工具 |
-| 3 | **回滚** | **无备份**。setup/upgrade/安装脚本全部 `RemoveAll`/`rm -rf` 直删（`skill_setup.go:616,655`、`paths.go:181,249,307`、`install.js` `fs.rmSync`）；`upgrade --rollback` 只回二进制 | 🔴 | **P0-3** 备份式安装：`RemoveAll` → `mv` 到 `~/.dws/skills/backup/<ts>-<mode>/`，保留最近 2 份，任一 home 失败自动恢复并非 0 退出；**P1-1** `mode rollback` 一条命令回到 `state.previous` |
-| 4 | **版本对齐** | embed 天然同版（setup 默认源，`skill_setup_embed.go:50-58`）✓；但 `~/.dws/skills` 缓存**只写不读**（仅 legacy 回退候选，`skill_setup.go:445-447`），upgrade 只刷 multi 缓存不刷 mono（`paths.go:290-296`），漂移不可见 | 🟡 | **P0b-1** state.json 记 `cli_version` 使漂移可见；**P0a-1** upgrade 按 mode 同步刷新对应缓存（或评估废弃缓存，plan §6 风险表末行） |
-| 5 | **卸载** | **无 remove**。skill 子命令仅 get/install/search/setup（`skill_command.go:202-209`）；用户只能手动删目录，且不知道该删哪些（16 个 home × N 个 skill） | 🟡 | **新增 P1-3** `dws skill remove`：按 state.json 的 `agent_homes`×`installed` 精确删除内置 skill（`dingtalk-*`+`dws-shared`+`dws/`），不动市场 skill；`--dry-run` 预览（依赖 P0b） |
-| 6 | **局部更新** | setup 侧 additive 语义完整（`-s/-x`，未点名保留）；但 **upgrade 增量语义未按 `state.installed`**：`UpgradeSkillLocations` 用 zip 内 bundle 全集刷新（`paths.go:135-137`、`339-358`），用户 `-x` 排除过的 skill 会被升级装回来 | 🔴 | plan §8.3-1 已定死语义（以 `state.installed` 为准增量刷新、未装不补装）；**P0b-1** 先落 `installed` 列表，**P0a-1** `UpgradeSkillLocations(dir, mode)` 按其过滤 |
-| 7 | **故障恢复** | **无**。setup 清理/拷贝失败仅 warning 或按 home 跳过，留半装态；upgrade 的 skill 失败发生在二进制替换之后（`upgrade.go:593-611`），半升级态无自动恢复、无修复命令 | 🔴 | **P0-3** 备份式安装 + 失败整体回滚（改变「warning 继续装」语义，需同步改 `skill_setup_full_coverage_test.go` 多处断言，plan §8.3-2）；**P0b-2** drift 检测给显式收敛指令；**P1-1** `mode rollback` |
-| 8 | **市场 vs 内置边界** | **隐性前缀约定**：互斥清理按 `dingtalk-`/`dws-shared` 名称扫描（`paths.go:332-334`、`skill_setup.go:581`），无 SKILL.md frontmatter 校验 —— 市场 skill 若同名前缀会被误删；反向地，市场 `install` 解压无保护，可覆盖内置 `dingtalk-*`（`skill_command.go:653-672`） | 🟡 | plan §6 风险行：清理前校验目录内 SKILL.md frontmatter 属 DWS 产品集并写成测试（落入 **P0-3** 的清理改造）；长期由 state.json 的 `installed` 清单取代前缀扫描（P0b 后续） |
-
-**附：本工作区已完成项**（不再列入缺口）：setup 默认 multi（P2-1）、
-install.sh/ps1 真装 multi（P2-2）、install-skills.sh/install.js mode 支持
-（P2-3）、README×2 与 dingtalk-skill 文案（P2-4 部分）、upgrade 识别并刷新
-multi 包（P0a 的布局识别一半）。**尚未做**：P0c 清单收敛、P0b state.json、
-P0-3 备份、P0a 的 mode-aware 一半、P0-4 请求头、P1-1 mode 命令、P1-2 beta 轨。
-
---
-
-## Part 2 — 内容能力对等（mono vs multi）
-
-### 2.1 树对比总览
-
-| 维度 | mono | multi |
-|---|---|---|
-| 规模 | 152 文件 / ≈2.5 MB | 244 文件 / ≈3.3 MB（19 个 `dingtalk-*` + `dws-shared`） |
-| 入口 | 单 `SKILL.md`（332 行，含全局路由/危险表/Schema 教学） | 每产品一个 `SKILL.md` + `dws-shared` 全局契约（90 行） |
-| 全局参考 | `references/` 10 项（intent-guide、global-reference、url-patterns、error-codes、capability-limits、channel-login、field-rules、recovery-guide、best_practices/、products/） | `dws-shared/references/` 9 项 + 各产品 skill 自带 |
-| 脚本 | `scripts/` 37 个 | 10 个 skill 带 `scripts/` 共 55 个 |
-| 最佳实践 | `best_practices/` 01–11 + lite + `_common` | 按产品分发（01→chat … 11→minutes），`_common` 与 lite 入 `dws-shared` |
-
-### 2.2 产品参考覆盖核对
-
-逐产品比对结论：**multi 覆盖 mono 全部产品参考，且多数为超集**。
-
-| mono 产品参考 | multi 对应物 | 结论 |
-|---|---|---|
-| aitable.md + aitable/（20）+ aitable-record-ops | `dingtalk-aitable`（同 20 子章节 + field-rules + 06-data-analytics） | ✅ 超集 |
-| chat.md + chat-emoji-list | `dingtalk-chat`（+ chat/ 5 个子章节） | ✅ 超集 |
-| calendar / contact / doc+doc/ / drive / mail / minutes / todo / wiki / aisearch / hrbrain / pat / markdown | 同名 `dingtalk-*` skill | ✅ 覆盖（doc 侧 mono 的 doc-file-ops/doc-list/doc-permission/doc-search 四篇已迁移为 `dingtalk-doc/references/doc.md:202-207` 的 drive/wiki 迁移表，属刻意重构） |
-| event.md（222 行） | `dingtalk-event`（event-im.md 399 行 + 完整订阅治理契约） | ✅ 超集 |
-| dev.md（212 行） | `dingtalk-dev`（12 篇 reference 共 584 行） | ✅ 超集（结构重组） |
-| oa / attendance / report / sheet / ding / devdoc / agoal | `dingtalk-misc` 对应 reference（sheet 多 3 篇：comment/formula/version） | ✅ 超集 |
-| simple.md（devdoc+oa 合集 + 意图判断 + 上下文传递表） | 已拆入 `dingtalk-misc/references/oa.md:309,425` 与 `devdoc.md:15,19` | ✅ 覆盖 |
-| 多组织/多账号（SKILL.md:64-70 一节） | `dingtalk-profile` 整个 skill | ✅ 超集 |
-| 意图决策树（SKILL.md:101-123） | `dws-shared/references/intent-guide.md`（536 行 ≥ mono 488 行）+ `routing.md` | ✅ 覆盖 |
-| best_practices 01–11 / lite / _common | 按产品分发 + `dws-shared/references/best_practices/_common/` | ✅ 覆盖 |
-| url-patterns / capability-limits / channel-login / error-codes | `dws-shared/references/` 同名 | ✅ 覆盖 |
-| field-rules.md（mono 全局位） | `dingtalk-aitable/references/field-rules.md` | ✅ 合理下沉（内容即 AI 表格字段规则） |
-
-### 2.3 不对等项清单（mono 有、multi 无）
-
-| # | 缺失项 | mono 锚点 | multi 现状证据 | 严重度 | 补齐方式（承载方） |
-|---|---|---|---|---|---|
-| M1 | **Recovery 闭环**（recovery-guide.md + global-reference §Recovery + 错误处理第 2 步） | `skills/mono/SKILL.md:296,311`、`references/recovery-guide.md`、`global-reference.md:62` | multi 全树 `RECOVERY_EVENT_ID` 零引用；`dws-shared/SKILL.md:83-89` 错误最短路径无 recovery；`dingtalk-dev/SKILL.md:124` 指向「root dws / dws-shared 的错误处理」→ **断链** | 🔴 | **dws-shared**：新增 `references/recovery-guide.md`（从 mono 移植）、SKILL.md 错误最短路径加 recovery 步、`global-reference.md` 补 Recovery 节（→ C1） |
-| M2 | **确认门禁协议 + 全局危险操作表** | `skills/mono/SKILL.md:137-187`（危险操作表 + 确认流程 + `confirmation_required` 识别与重试协议） | multi 仅 aitable/doc/misc 三个 SKILL.md 有产品级危险表；`confirmation_required` / 「确认门禁」全树零命中；`dws-shared/SKILL.md:37-38` 只有一行泛化规则 | 🔴 | **dws-shared**：全局确认门禁协议（识别 `confirmation_required`、原始命令追加 `--yes` 重试、`--dry-run` 预览、禁止管道喂答案）+ 危险操作索引指向各产品表（→ C2） |
-| M3 | **Schema 渐进查询教学** | `skills/mono/SKILL.md:198-292`（≈95 行：四层查询、`--compact`/`--all` 边界、字段速查、Schema/Help/业务数据边界表、漂移处理） | 各产品 SKILL.md 仅点状提及 leaf Schema（17 处）；`dws-shared/references/global-reference.md:79-89`「命令自省」只有 `--help` | 🟡 | **dws-shared**：新增 Schema 渐进查询章节（改写为 multi 语境，链入渐进加载表）（→ C3） |
-| M4 | **scripts/report_inbox_today.py** | `skills/mono/scripts/report_inbox_today.py` | multi 无（misc 仅有 `report_received_today.py`）；mono 文档也未引用它 | 🟢 | **dingtalk-misc**：先验证脚本仍可用 → 迁入 `scripts/` 并在 `report.md` 引用；不可用则连同 mono 侧一起删（→ C5） |
-| M5 | **LICENSE / NOTICE** | `skills/mono/LICENSE`、`NOTICE` | multi 20 个 skill 均无 | 🟡 | 每个 multi skill 根复制两份（或 release 打包期注入，`scripts/release/post-goreleaser.sh`）（→ C7） |
-| M6 | **aiapp 意图路由** | `skills/mono/SKILL.md:76,101`（产品表 + 决策树有 aiapp 行，但目标 `aiapp.md` 不存在 —— mono 自身死链） | multi 全树无 aiapp 路由/文档；仅 orphan 脚本 `dingtalk-misc/scripts/aiapp_create_and_poll.py` | 🟡 | 决策：**dws-shared/routing.md** + **dingtalk-misc** 产品索引补 aiapp 行并新建 reference，或明确下线该能力并清掉 mono 死链与 orphan 脚本（→ C5） |
-
-### 2.4 multi 自身不一致项（不阻塞对等结论，但阻塞「multi 可独当一面」）
-
-| # | 问题 | 证据 | 处理 |
-|---|---|---|---|
-| X1 | 16 个 orphan 脚本无任何文档引用（yida×13、finance×2、aiapp×1）；`dws-shared/references/routing.md` 把「宜搭」路由到 dingtalk-misc，但 misc 产品索引无 yida 行、无 yida reference | `skills/multi/dingtalk-misc/scripts/`；`dingtalk-misc/SKILL.md:20-32` | 补文档（misc 产品索引 + reference）或移出发布包（→ C5） |
-| X2 | 死链：`dingtalk-chat/SKILL.md:131` 引用 `scripts/extract_media_id.py`，文件不存在（mono 也无） | 同上 | 补脚本或删引用（→ C4） |
-| X3 | 死链：`dws-shared/references/routing.md:22` 指向 `dingtalk-misc/references/markdown.md`，实际在 `dingtalk-markdown` | 同上 | 改指 `../../dingtalk-markdown/SKILL.md`（→ C4） |
-| X4 | `dingtalk-event/SKILL.md` 缺 `dws-shared` PREREQUISITE 与 `metadata:` 块（其余 19 个 skill 均有） | `skills/multi/dingtalk-event/SKILL.md:1-4` | 补齐（→ C4） |
-| X5 | 4 个 skill 仍是 🧪 EXPERIMENTAL + 「生产优先 mono」文案，与本工作区已翻转的默认矛盾（dingtalk-skill 已改，这 4 个漏改） | `dingtalk-profile/SKILL.md:15`、`dingtalk-hrbrain:15`、`dingtalk-markdown:15`、`dingtalk-pat:15` | 统一下调文案（→ C4，即 plan P2-4 剩余量） |
-| X6 | `<!-- SAFETY_PREAMBLE_INJECT -->` 标记存在于 5 个 SKILL.md，但仓库内无注入器 | `dingtalk-{pat,hrbrain,markdown,skill,profile}/SKILL.md` | 明确注入方（仓外流程则写注释）或移除标记（→ C4） |
-
-### 2.5 测试与政策门覆盖
-
-| 门面 | 覆盖 | 缺口 |
-|---|---|---|
-| `test/skill_tests.md` 覆盖表（40-54 行） | 13 产品 ≈256 用例 | 12/13 行引用 **mono 路径**（`references/products/...`），仅 dev 指 multi；`workbench` 行指向不存在的 `workbench.md`（54 行，mono/multi 均无）；`devdoc` 行指 `simple.md`（47 行，multi 无此文件）；未覆盖 doc/drive/mail/minutes/oa/sheet/wiki/aisearch/hrbrain/markdown/pat/profile/skill。multi 默认后需按 multi 路径重写并补产品（→ C6） |
-| `scripts/policy/check-skill-context-budget.sh` | 锁 `dingtalk-chat/SKILL.md` ≤14000B + shortcut 区块不膨胀 + mono SKILL.md 不含「充分阅读产品参考文件」回归（9-38 行）；`gen_skill_shortcut_sections.py --check` 同时写 mono 与 multi 的 shortcut 区块 | mono 下线判据（plan §5-4）要求先替代对 `skills/mono/SKILL.md` 的依赖 |
-| `make skill-command-integrity`（`check-skill-commands.sh` → `test/skill_static/skill_static_test.go:119-133`） | 静态校验 mono+multi 两树文档中的命令与 flag | 覆盖 OK；X2/X3 类 reference 死链不在其校验面 |
-
-**Part 2 结论**：multi **没有**覆盖 mono 的全部能力 —— 产品参考层面是超集，
-但全局能力缺 M1–M3 三块（recovery / 确认门禁 / Schema 教学），加 M4–M6 三个
-小项；另有 X1–X6 六项 multi 内部不一致。补齐全部落在 `dws-shared`（M1/M2/M3）、
-`dingtalk-misc`（M4/M6/X1）、各产品 skill（X2/X4/X5）与打包流程（M5）。
-
---
-
-## Part 3 — 优先级排序实施清单
-
-> 估时以 1 名熟悉本仓库的工程师计（人日），口径同 plan §8。
-> 「状态」列：✅ 本工作区已完成｜🚧 部分完成｜⬜ 未做。
-
-### 3.1 P0 — 先堵会丢数据/双份派发的洞（≈6.5–8.5d）
-
-| ID | 状态 | 任务 | 文件级改动点 | 估时 | 依赖 |
-|---|---|---|---|---|---|
-| P0c-1 | ⬜ | agent home 清单下沉共享包，补 opencode 不对称 | 新 `internal/skillhome`（或 `internal/upgrade` 导出）：合并 `paths.go:35-52` `knownSkillDirs` + `skill_setup.go:20-37` `skillSetupAgentHomes` + `skill_command.go:119-141` `agentSkillPaths`；setup/upgrade/测试共用 | 0.5d | — |
-| P0c-2 | ⬜ | 清单同步门禁 | 新 `scripts/policy/check-agent-homes-sync.sh`（进 `make policy`）；install.sh:ps1:install.js:install-skills.sh 清单改可解析块 | 1d | P0c-1 |
-| P0b-1 | ❌ CANCELLED | state.json schema + 写入 | 2026-08-05：无运行时切换，不写 state.json | — | — |
-| P0b-2 | ❌ CANCELLED | 磁盘形态反推作 state 兜底 | 无 sticky / 无 state；upgrade 按包刷 multi | — | — |
-| P0-3 | ❌ CANCELLED | 备份式安装 + 失败整体回滚 | 2026-08-05：随切换产品线取消 | — | — |
-| P0a-1 | ✅ | upgrade 包驱动 multi | `UpgradeSkillLocations`：有 multi→始终 multi（含 mono 盘一次性迁移）；legacy 无 multi→mono；不读 state | — | — |
-| P0a-2 | ✅ | force-multi 集成 / E2E | `paths_multi_test.go`（`MonoDiskMigratesToMulti` 等）+ `upgrade_skill_multi_e2e_test.go` | — | — |
-| P0-4 | ❌ CANCELLED | `x-dws-skill-mode` 请求头 | owner 决策移除 | — | — |
-
-### 3.2 P1 — 生命周期命令 + 内容补全（≈7–7.5d，两条线可并行）
-
-**管理命令线**
-
-| ID | 状态 | 任务 | 文件级改动点 | 估时 | 依赖 |
-|---|---|---|---|---|---|
-| P1-1 | ❌ CANCELLED | `dws skill mode` status/set/rollback/--dry-run | 2026-08-05：无运行时模式切换产品 | — | — |
-| P1-3 | ⬜ | `dws skill remove`（新增，缺口 #5） | 按磁盘/约定前缀精确删内置 skill（**不**依赖已取消的 state.json）；`--dry-run` 预览 | 1d | — |
-
-**内容补全线**（对应 Part 2 编号）
-
-| ID | 任务 | 文件级改动点 | 估时 | 依赖 |
-|---|---|---|---|---|
-| C1 | recovery 闭环进 multi（M1） | 新 `skills/multi/dws-shared/references/recovery-guide.md`；`dws-shared/SKILL.md:83-89` 错误最短路径加 recovery 步；`dws-shared/references/global-reference.md` 补 Recovery 节；`dingtalk-dev/SKILL.md:124` 断链改指 | 0.5d | — |
-| C2 | 确认门禁协议 + 危险操作索引（M2） | `dws-shared/SKILL.md` 增「确认门禁」节（移植 mono `SKILL.md:170-187` 协议）+ 危险操作索引表指向各产品 SKILL.md | 0.5d | — |
-| C3 | Schema 渐进查询教学（M3） | `dws-shared/SKILL.md` 渐进加载表加一行 + 新 `references/schema-usage.md`（改写 mono `SKILL.md:198-292`） | 0.5d | — |
-| C4 | multi 一致性修复（X2/X3/X4/X5/X6 = plan P2-4 剩余量） | `dws-shared/references/routing.md:22` 改指 dingtalk-markdown；`dingtalk-chat/SKILL.md:131` 死链处置；`dingtalk-event/SKILL.md` 补 PREREQUISITE+metadata；`dingtalk-{profile,hrbrain,markdown,pat}/SKILL.md:15` EXPERIMENTAL 文案下调；SAFETY_PREAMBLE_INJECT 标记处置 | 0.5d | — |
-| C5 | orphan 脚本与缺失产品处置（X1/M4/M6） | `dingtalk-misc/SKILL.md:20-32` 产品索引补 yida/finance/aiapp 行 + 新 reference（或把 16 个脚本移出发布包）；`report_inbox_today.py` 验证后迁入或删除；aiapp 路由决策落 `dws-shared/references/routing.md` | 0.5–1d | — |
-| C6 | skill_tests.md multi 化 + 扩产品 | `test/skill_tests.md:40-54` 覆盖表改 multi 路径；修 workbench（54 行）/devdoc（47 行）死链；补 doc/drive/mail/minutes/oa/sheet/wiki 用例 | 1d | C1–C5（路径稳定后） |
-| C7 | LICENSE/NOTICE 进 multi（M5） | 20 个 `skills/multi/*/LICENSE|NOTICE`（或 `scripts/release/post-goreleaser.sh` 打包期注入） | 0.25d | — |
-
-### 3.3 P2 / W4 — 收尾（≈1d）
-
-| ID | 状态 | 任务 | 估时 | 依赖 |
-|---|---|---|---|---|
-| P1-2 | ⬜ | beta 轨默认切 multi（版本门控；本工作区已全量切，可选择保留全量或回退为 beta 先行） | 0.5–1d | P1-1 |
-| P2-1 ~ P2-3 | ✅ | setup / install.sh / install.ps1 / install-skills.sh / install.js 默认 multi | — | 已完成 |
-| P2-4 | 🚧 | 文案翻转：README×2、dingtalk-skill 已改 ✅；4 个 EXPERIMENTAL 漏改 → 并入 C4 | — | — |
-| W4 | ⬜ | mono deprecation 警告（不删代码）+ mono 下线判据第 4 条（替代 `check-skill-context-budget.sh:10,34-38` 对 mono 的依赖） | 0.5d | P2、C6 |
-
-### 3.4 依赖图与排期建议
-
-```text
-P0c-1 ─► P0c-2
-P0b-1 ─► P0b-2 ─┐
-P0-3 ───────────┼─► P0a-1 ─► P0a-2 ─► P1-1 ─► P1-3
-P0b-1 ──────────┴─► P0-4
-C1…C5（互相独立，可与 P0 并行）─► C6
-```
-
- **W1**：P0c-1 → P0b-1/P0b-2 → P0-3 → P0a-1/P0a-2（管理面止血）；并行 C1–C4（内容高危项）。
- **W2**：P0-4、P1-1、P1-3；并行 C5、C7。
- **W3**：C6（内容面收口）+ P1-2 beta 决策；`make policy` 全绿。
- **W4**：mono deprecation + 观察（plan §4 原节奏不变）。
-
-合计：P0 ≈ 6.5–8.5d + P1 管理 ≈ 3–3.5d + 内容 C1–C7 ≈ 3.5–4d + P2/W4 ≈ 1d
-= **14–17 人日**。砍法同 plan §8.4：内容线可砍 C3/C7（教学与法律文件可后置），
-管理线不可砍 P0b/P0-3/P0a（缺了就是现在这副「能装不能管」的样子）。
@@ -1,146 +0,0 @@
-# Skill 分发与消费机制调研（含 lark-cli 对标）
-
-> 配套方案：[skill-multi-migration-plan.md](skill-multi-migration-plan.md)
-> 调研日期：2026-08-04，基于 `feat/skill-mode-migration` 工作区代码级梳理 +
-> lark-cli（larksuite/cli@main）公开仓库调研。
-
-## 1. DWS 分发链路（源树 → 制品 → 渠道）
-
-```
-skills/mono/ ─┬─ go build ──► embed.FS（skills_embed.go:28）
-skills/multi/ ┘                    │  dws skill setup 默认源
-              │
-              └─ post-goreleaser.sh:220-248 ──► dws-skills.zip
-                 布局：zip 根 = mono 副本（向后兼容）+ mono/ + multi/
-                        │
-        ┌───────┬───────┼────────┬─────────┬──────────┐
-     GitHub   Gitee    OSS     npm      Homebrew   专项脚本
-     Release  (镜像)  (只发    tarball  (cellar    install-event/
-        │       │     不读)     │       不铺agent) install-devapp
-        │       │              │
-   install.sh/ps1          postinstall
-   install-skills.sh       install.js
-        │                      │
-        ├─► 各 agent home ◄────┤   永远 mono：<agent>/dws/
-        └─► ~/.dws/skills/{mono,multi} 缓存
-```
-
-渠道清单（7 个安装/分发面）：
-
-| 面 | skill 行为 | mode 概念 |
-|---|---|---|
-| `scripts/install.sh` | 装 mono 到 agent homes + 双缓存；选 multi **只打印提示、连缓存都跳过** | 有（半残） |
-| `scripts/install.ps1` | 同 install.sh（Windows） | 有（半残） |
-| `scripts/install-skills.sh` | 只装 mono，缓存 mono+multi | 无 |
-| `build/npm/install.js` | 永远 mono；缓存 mono+multi | 无 |
-| Homebrew formula | 整包 zip 进 cellar，不铺 agent、不写缓存，caveats 提示手动 setup | 无 |
-| `scripts/install-event.sh` | 装 mono + 缓存 `multi/dingtalk-event`；多 `.config/opencode/skills` | 无 |
-| `scripts/install-devapp.sh` | 缓存 `multi/dingtalk-dev` | 无 |
-
-产物事实：`dws-skills.zip` 已含 mono/multi 双树，**切 multi 不需要改 release 产物**。
-
-## 2. DWS 消费链路（源 → agent 目录）
-
-### 2.1 `dws skill setup`（`internal/app/skill_setup.go`）
-
- 源优先级：`--source` / `DWS_SKILL_SOURCE`（失败不回退）→ **embed 默认**
-  （`skill_setup_embed.go:50-58`）；legacy 候选（exe 旁/cwd/`~/.dws/skills`）
-  仅在绕过 wrapper 直连时才走。
- 目标：`skillSetupAgentHomes` 16 个 agent home，父目录门控（i=0 `.agents`
-  无条件，其余需 `~/.claude` 这类父目录存在）。`--target all` **不含
-  opencode**，但 `agentSkillPaths` 命名 target 含（不对称，测试只锁单向）。
- 布局：mono → `<agent-home>/dws/`；multi → `<agent-home>/` 平铺兄弟目录。
- 互斥清理：装 mono 删 `dingtalk-*`、装 multi 删 `dws/`；**best-effort，
-  失败仅 warning 继续装**（`cleanupMutualExclusion:611-620`），无备份。
- multi 过滤：`-s/--skill` 与 `-x/--exclude` 互斥；`dws-shared` 强制包含；
-  未点名的已有 `dingtalk-*` 保留（additive）。
-
-### 2.2 `dws upgrade`（`internal/upgrade/paths.go`）
-
- `LocateSkillMD` 命中 zip 根 mono → `UpgradeSkillLocations` 只写
-  `<agent>/dws/`：**不识 multi、不清理 `dingtalk-*`、不更新 `~/.dws/skills`**。
- 后果：multi 用户升级后 **mono + multi 共存**，Agent 双份派发。
- `--rollback` 只回滚二进制，不回滚 skill。
-
-### 2.3 市场 skill（`dws skill install`）
-
-解压到 agent skills **根目录**（非 `dws/` 子目录），无 mode 概念；互斥清理按
-`dingtalk-*` 前缀扫描，依赖"市场无同名前缀"隐性约定。
-
-### 2.4 状态与缓存
-
- **无任何已安装模式状态**：`~/.dws/` 有 auth/backups/cache，无 install
-  manifest；判断 mode 只能看磁盘形态。
- `~/.dws/skills` 缓存事实**只写不读**（默认 setup 走 embed），upgrade 不更新，
-  版本漂移不可见。
-
-## 3. lark-cli 分发机制（larksuite/cli@main）
-
-npm 包 `@larksuite/cli` 是薄壳（`files` 仅 install.js / install-wizard.js /
-run.js / checksums.txt）：
-
- **二进制**：postinstall 按平台从 GitHub Releases 下载，SHA256 校验
-  （checksums.txt 随 npm 包发）；镜像链 GitHub → 用户 registry 派生镜像 →
-  npmmirror 兜底；host allowlist + checksum 双保险；`run.js` 缺二进制自动补下，
-  Windows 有 `.old` 崩溃恢复。
- **Skills**：不进 npm 包、不进二进制。repo 根 `skills/` 即事实源，由生态
-  安装器 `npx skills add larksuite/cli -y -g`（vercel-labs/skills）安装；
-  wizard 首选 `https://open.feishu.cn` 直链，GitHub shorthand 兜底。
- **一键向导** `npx @larksuite/cli@latest install`：run.js 拦截 `install` →
-  install-wizard.js 串联 4 步（npm 全局装/升级 → skills → config init →
-  auth login），每步幂等（`skills ls -g` 检测 `lark-*` 已装则跳过）；
-  非 TTY 降级为"装完打印后续命令"。
-
-生态安装器 `skills` CLI 提供的能力：
-
- 76 个 agent 目录清单生态维护，自动探测；project/global 双 scope；
- **symlink canonical（推荐）或 copy**；symlink 下升级 = 更新一处；
- `list / find / update / remove` 全生命周期；**skill 升级由
-  `npx skills update` 承担，lark-cli 自己不写 skill 刷新逻辑**；
- 发现约定兼容 catalog 布局 `skills/<catalog>/<name>/SKILL.md`。
-
-## 4. 对标：DWS vs lark-cli
-
-| 维度 | lark-cli | DWS 现状 |
-|---|---|---|
-| 分发单元 | repo `skills/`（源码即事实源） | zip + embed + 5 处拷贝缓存 |
-| 安装器 | 1 个（生态工具） | 7 个自维护脚本，已漂移 |
-| 落盘 | symlink 单点更新 | 全量 copy，升级重写 16 home |
-| skill 升级 | `npx skills update`（生态承担） | `dws upgrade` 自写，不识 multi |
-| mono/multi | 不存在此问题（天生多 skill） | 互斥/切换/状态全自建 |
-| npm 包 | 薄壳运行时下载 | 全平台 archive + zip 全打进 tarball |
-| 大陆镜像 | registry 派生 + npmmirror | Gitee fallback + OSS 只发不读 |
-
-## 5. "分发外包给生态，自己只维护源码目录"是什么
-
-职责切分：skill 的分发/安装/升级/卸载交给生态标准化工具（`npx skills`，
-"agent skill 界的 npm"），DWS 只保证 repo 里 `skills/` 符合 agentskills.io
-规范。它消掉的正是 DWS 现在自维护的四块问题：
-
-1. **N 份事实源**（zip 三拷贝 + embed + 缓存 + 16 home）→ 只剩 repo 目录一份；
-2. **7 个自写安装器** → 零个，agent 清单别人维护（新 agent 自动支持）；
-3. **自建升级/切换/回滚**（UpgradeSkillLocations、互斥清理、方案中的
-   state.json/备份/`dws skill mode`）→ symlink 模式更新 canonical 一处；
-4. **lark-cli 因此根本没有 mono/multi 之争**，也没有 P0 要修的那些 bug。
-
-### 代价与前提（不是免费午餐）
-
-| 风险 | 说明 | 对策 |
-|---|---|---|
-| 版本错配 | DWS skill 从 Cobra 树生成，与 CLI 版本强耦合；embed 天然同版，生态安装从主分支拉可能错配。**已实测**：`skills add`（v1.5.21）无 tag/ref 版本固定参数，`@` 后接的是 skill 名而非 git ref；唯一的可复现机制是 project 级 `skills-lock.json`（experimental_install） | 短期：发布说明引导"skill 随 CLI 升级（`skills update`）"；中期：release 时推一个 `release/vX.Y.Z` 镜像分支或专用 skills 镜像仓供按版本安装；或接受错配（skill 内容为文档，错配成本=提到不存在的命令） |
-| 网络可达 | 依赖 npx + GitHub；大陆/内网现靠 Gitee fallback | `skills` CLI 支持任意 git URL，Gitee 镜像仓兜底，链路需验证 |
-| 离线/打包场景 | 悟空 bundled-skills、企业预装镜像生态通道覆盖不了（2026-08-05 注：悟空分发线已于当日下线，「悟空 bundled-skills」一项不再适用；企业预装镜像约束仍在） | 自维护打包保留一条 |
-| 生态工具策略漂移 | 清单/发现约定/默认值被动跟随 | 作为增量通道而非唯一通道，保留 embed 兜底 |
-
-## 6. 结论
-
- **生态分发通道已否决**（2026-08-04）：无版本固定（`skills add` 不支持
-  tag/ref，实测 v1.5.21）、依赖 Node + GitHub 可达、mono 会被一起发现、
-  悟空/离线场景覆盖不了。分发维持全自维护。（2026-08-05 注：悟空分发线
-  已于当日下线，「悟空场景覆盖不了」一条随之失效；其余否决理由与结论
-  不变。）
- 一个月内：按方案 P0–P2 修自维护通道并切 multi 默认（zip + embed +
-  安装脚本，产物布局不变）。
- 终态即"自维护通道修好之后"的形态，不再向 lark-cli 的生态外包形态收敛。
- 调研保留备查：`npx -y skills add . --list` 实测可发现全部 21 个 skill
-  （若未来生态工具补齐版本固定能力，可重新评估本决策）。
@@ -1,307 +0,0 @@
-# Skill 多 skill（multi）切换方案
-
-> 目标：一个月内把 DWS 的 Agent skill 默认安装形态从 mono（单 skill）切换为
-> multi（按产品拆分），两套并行期后下掉 mono。
-> 本文基于对分发/消费链路的代码级梳理（2026-08-04），所有锚点均可跳转验证。
-> 机制调研与 lark-cli 对标细节：[skill-distribution-mechanism.md](skill-distribution-mechanism.md)
-
-## 1. 目标与约束
-
-| 项 | 内容 |
-|---|---|
-| 终态 | 新装/升级默认铺 multi（`<agent-home>/dingtalk-*/`、`dws-shared/`）；mono 仅 opt-in；最终物理删除 mono |
-| 并行期 | 约一个月，mono 保留可切换、可回退 |
-| 硬约束 | DWS 无服务端灰度/远程配置；skill 是本地文件分发；安装面至少 7 个且已有漂移 |
-| 前置原则 | 先修已存在的 upgrade×multi 双份 bug，再谈切默认 |
-
-## 2. 现状关键事实（梳理结论）
-
-分发侧：
-
- `dws-skills.zip` 布局：zip 根 = mono 副本（向后兼容）+ `mono/` + `multi/`
-  （`scripts/release/post-goreleaser.sh:220-248`）。**产物无需改动**。
- 二进制 `//go:embed all:skills/mono all:skills/multi`（`skills_embed.go:28`），
-  `dws skill setup` 默认源就是 embed，**与分发渠道无关**。
- 7 个安装/分发面：install.sh、install.ps1、install-skills.sh、npm install.js、
-  Homebrew formula、install-event.sh、install-devapp.sh。
- OSS 只发不读；大陆链路靠 Gitee fallback。
-
-消费侧：
-
- `dws skill setup`：源优先级 `--source`/env → embed；目标 16 个 agent home
-  （父目录门控）；互斥清理 best-effort、失败仅 warning、无备份无回滚
-  （`internal/app/skill_setup.go`）。
- `dws upgrade`：`LocateSkillMD` 命中 zip 根 mono → `UpgradeSkillLocations`
-  只写 `<agent>/dws/`、不清理 `dingtalk-*`、不更新 `~/.dws/skills`
-  （`internal/upgrade/paths.go:119-172`）。**multi 用户升级后 mono+multi 共存**。
- `dws upgrade --rollback` 只回滚二进制，不回滚 skill。
- **无任何已安装模式状态**：`~/.dws/` 无 install manifest。
- `~/.dws/skills` 缓存事实上只写不读（默认 setup 走 embed），且 upgrade 不更新，
-  版本漂移不可见。
- `skill setup --target all` 不含 opencode，但 `agentSkillPaths` 含
-  （`skill_command.go:119-141` vs `skill_setup.go:20-37`）。
- 市场 skill（`dws skill install`）解压到 agent skills 根，与内置 skill 无 mode
-  概念；互斥清理按 `dingtalk-*` 前缀扫描，依赖"市场无同名前缀"这一隐性约定。
-
-## 3. 总体设计
-
-### 3.1 单一事实源收敛（P0c）
-
-agent home 清单目前在 5+ 处各写一份（注释约定 keep in sync，无门禁）。
-
- Go 侧：`skillSetupAgentHomes` 与 `knownSkillDirs` 合并为一个导出列表
-  （放在 `internal/upgrade` 或新 `internal/skillhome` 包），补 opencode，
-  setup/upgrade/测试共用。
- 脚本侧：install.sh / install.ps1 / install.js / install-skills.sh /
-  install-event.sh / install-devapp.sh 的清单由同一个 JSON 生成或政策脚本
-  比对（新增 `scripts/policy/check-agent-homes-sync.sh`，进 `make policy`）。
-
-### 3.2 安装状态文件（P0b）— ❌ CANCELLED（2026-08-05）
-
-原计划新增 `~/.dws/skills/state.json`（mode / cli_version / installed /
-previous / backup）。**已取消**：owner 决策不做运行时模式切换产品；upgrade
-有 multi 包时直接刷 multi，不再需要状态文件作为正确性或切换前提。
-
-### 3.3 备份式安装与真回滚（P0a）— ❌ CANCELLED（2026-08-05）
-
-原计划把 `RemoveAll` 改为 `mv` 到 `~/.dws/skills/backup/<ts>-<mode>/` 并
-支持失败整体回滚 / `dws skill mode rollback`。**已取消**：无运行时切换则
-不交付备份回滚产品面。安装/清理仍可为直接删除；mono retirement 版本若做
-一次性迁移，届时再单独评估临时备份，不预建 switch UX。
-
-### 3.4 upgrade 包驱动 multi 刷新（P0a，已落地）
-
-> 取代「按 state.json mode 刷新」与「磁盘粘性」：有 multi 包时一次性刷成 multi。
-
- `UpgradeSkillLocations(extractedDir)`：**不**推断磁盘布局。
-  - 包内有 multi 技能树 → 始终 multi 刷新（清 `dws/`、刷产品 skill、刷
-    `~/.dws/skills/multi`）；存量 mono 在日常 upgrade 上一并迁走。
-  - 无 multi 树的 legacy 包 → mono 刷新回退。
- 这是包驱动的一次性迁移，**不是**运行时 mode-switch 产品。
- 互斥清理在 multi 路径内执行，避免双布局长期共存。
-
-### 3.5 模式切换命令（P1）— ❌ CANCELLED（2026-08-05）
-
-原计划 `dws skill mode status|set|rollback|--dry-run`。**已取消**。
-
-用户若需改布局：重新走安装入口（`dws skill setup --mode <mono|multi> --yes`
-或安装脚本 `DWS_SKILL_MODE=`），不是 lifecycle 切换命令。
-
-### 3.6 默认切换（P2）
-
-改默认值="multi 默认、mono opt-in"，七个面一起改 + 门禁锁一致性：
-
-| 面 | 改动 |
-|---|---|
-| `dws skill setup` | 无 `--mode` 时默认 multi（交互选项顺序反转，mono 标 legacy） |
-| install.sh / install.ps1 | multi 分支**真正安装**（现在是打印提示跳过）；`DWS_SKILL_MODE=mono` opt-in；TTY 默认项改 multi |
-| install-skills.sh / npm install.js | 从零加 mode 支持（env `DWS_SKILL_MODE` / `--skill-mode`），默认 multi |
-| Homebrew formula | caveats 改提示 `dws skill setup`（默认即 multi），无需改资源 |
-| install-event.sh / install-devapp.sh | 维持单 skill 语义，但改走共享 install 函数 |
-
-文档同步：README/README_zh（`README_zh.md:81` "默认 1"）、
-`skills/multi/dingtalk-skill/SKILL.md` 的 🧪 EXPERIMENTAL 措辞下调、
-install.sh 内 multi 警告文案、AGENTS.md"生产优先 mono"表述。
-
-### 3.7 灰度与止血（无服务端能力下的替代）
-
- **L1 渠道灰度（先行）**：beta 轨（GitHub prerelease / npm `beta` dist-tag /
-  `dws upgrade --beta`）先切默认 multi，stable 保持 mono。零新增代码。
- **L2 确定性分桶（可选增强）**：随 release 发 `rollout.json`
-  （GitHub asset + OSS 同步），安装/升级时 `hash(machine-id) % 100 < pct` 决策
-  并粘入 `state.rollout`。规则：本地显式 env/flag 永远优先；拉取失败 fail-safe
-  mono（并行期）/ 保持现状（切默认后）；存量机器不被 rollout 改模式。
- **Kill switch**：`rollout.json` pct=0（若上 L2，已砍）+ beta 撤回 +
-  公告引导重装 `dws skill setup --mode mono --yes`（**无** `skill mode`
-  命令；备份回滚产品已随 D5 取消）。
- **可观测**：原 `x-dws-skill-mode` 请求头方案 **CANCELLED**（2026-08-05
-  owner）；灰度与下线判断改 issue 反馈 + 主动回访。
-
-### 3.8 安装与升级的语义矩阵（两条路径都要支持 multi）
-
-| 场景 | 时期 | 行为 |
-|---|---|---|
-| 新装 | 并行期（切默认前） | mono 默认，`DWS_SKILL_MODE=multi` / 交互可选 multi |
-| 新装 | 切默认后 | **multi 默认**，`DWS_SKILL_MODE=mono` / `--mode mono` / TTY opt-in（**仅安装时**） |
-| 升级（存量 mono） | 含 `multi/` 的包 | **一次性刷成 multi**（清 `dws/`）；无 switch 提示命令 |
-| 升级（存量 multi） | 含 `multi/` 的包 | multi 刷新，清过期 skill，刷 multi 缓存 |
-| 升级（无安装） | 含 `multi/` 的包 | 安装 multi（与安装默认一致） |
-| 升级（任意磁盘） | legacy 无 multi 树的包 | mono 刷新回退 |
-| `dws upgrade --rollback` | 任意 | 只回滚二进制（现状）；skill 无独立 rollback 命令 |
-
-原则：**升级不做磁盘粘性**；有 multi 包时一律刷 multi（含存量 mono 一次性
-迁移）。默认翻转与安装 opt-in 仍只影响新装/重装。无运行时 `dws skill mode`
-产品。
-
-## 4. 阶段与时间线（4 周）
-
-| 周 | 内容 | 出口标准 |
-|---|---|---|
-| W1 | P0a upgrade mode-aware + P0b state.json + P0c 清单收敛与门禁 + 备份式安装 | upgrade×multi 集成测试（装 multi → upgrade → 无 `dws/` 残留）；备份回滚测试（模拟中途失败）；`make policy` 含 homes 同步检查 |
-| W2 | P1 `dws skill mode`（status/set/rollback/dry-run）；beta 轨默认切 multi（L1）；`x-dws-skill-mode` 头 | 双向切换 + 中断恢复手工验收；beta 轨冒烟 |
-| W3 | P2 stable 默认切 multi、mono 降为 opt-in；文案翻转；（可选 L2 分桶 5%→20%） | 七面默认行为一致（政策脚本）；issue/请求头占比观察 |
-| W4 | （L2 则 50%→100%）；mono 打 deprecation 警告，**不删代码** | 连续 7 天无 multi 相关 P1 |
-
-## 5. mono 下线判据（不满足则不删）
-
-> 判据更新（2026-08-05）：原判据 3「悟空 bundled skill 分发线（dws_res →
-> bundled-skills，本仓库外）已切 multi」作废——悟空分发线已于当日决策
-> 下线（见 [skill-multi-roadmap.md](skill-multi-roadmap.md)
-> 「悟空线下线的影响（2026-08-05）」），无仓外 mono 依赖，mono 下线不再
-> 有仓外节奏闸门。判据重新编号如下（原 4/5 顺延为 3/4）。
-
-1. `x-dws-skill-mode=multi` 请求占比 ≥ 90%；
-2.  mono 主动 opt-in 率 ≤ 2%（install 脚本/命令埋点）；
-3. 连续两周无 multi P1；
-4. 已有等价政策门替代 `scripts/policy/check-skill-context-budget.sh` 对
-   `skills/mono/SKILL.md` 的依赖；`skills_embed.go` 去掉 `all:skills/mono`；
-   存量 `<agent>/dws` 目录有"遇到即迁移清理"逻辑。
-
-满足后单独一个版本窗口物理删除 `skills/mono/`，install/setup/upgrade 中 mono
-分支改为报错并指向 `dws skill mode set multi`。
-
-## 6. 风险与对策
-
-| 风险 | 对策 |
-|---|---|
-| 半装状态（清理成功、拷贝失败） | 3.3 备份式安装，失败整体回滚 |
-| multi 用户被 upgrade 塞回 mono | 3.4 mode-aware，P0a 先修 |
-| Agent 目录清单继续漂移 | 3.1 单一事实源 + policy 门禁 |
-| 互斥清理误伤市场 `dingtalk-*` skill | 清理前校验目录内 SKILL.md frontmatter 属 DWS 产品集，写成测试 |
-| 无灰度全切翻车 | beta 轨先行 + 备份回滚 + kill switch 公告命令 |
-| 用户不重启 AI 工具读到旧 skill | mode set / setup / install 输出统一提示重启 |
-| `~/.dws/skills` 缓存与 embed 版本漂移 | upgrade 时同步刷新对应 mode 缓存；长期可评估废弃缓存 |
-
-## 7. 分发机制对标 lark-cli（2026-08-04 调研）
-
-### 7.1 lark-cli 的实际分发结构
-
-npm 包 `@larksuite/cli` 是一个**薄壳**（package.json `files` 只有
-`install.js` / `install-wizard.js` / `run.js` / `checksums.txt`）：
-
- **二进制**：postinstall 时按平台从 GitHub Releases 下载，SHA256 校验
-  （checksums.txt 随 npm 包发布）；镜像链 = GitHub → 用户 registry 派生镜像 →
-  npmmirror 兜底，host allowlist + checksum 双保险。`run.js` 在二进制缺失时
-  自动补下载；Windows 有 `.old` 崩溃恢复。
- **Skills**：**不进 npm 包、不进二进制**。repo 根 `skills/` 目录即事实源，
-  由生态通用安装器 `npx skills add larksuite/cli -y -g`（vercel-labs/skills）
-  安装；wizard 首选 `https://open.feishu.cn` 直链、GitHub shorthand 兜底。
- **一键向导** `npx @larksuite/cli@latest install`：run.js 拦截 `install`
-  子命令 → install-wizard.js 串联 4 步（npm 全局装/升级 → skills 安装 →
-  config init → auth login），每步幂等可跳过（`skills ls -g` 检测 `lark-*`
-  已装则跳过）；非 TTY 自动降级为"装完打印后续命令"。
-
-生态安装器 `skills` CLI 的能力（lark-cli 免费获得的）：
-
- **76 个 agent 的目录清单由生态维护**，自动探测已装 agent；project/global
-  两种 scope；
- **symlink 到 canonical 副本（推荐）或 copy** —— symlink 模式下升级
-  = 更新 canonical 一份，所有 agent 即时生效；
- `list / find / update / remove` 全套生命周期命令，skill 升级由
-  `npx skills update` 承担，**lark-cli 自己不写 skill 刷新逻辑**；
- 发现约定兼容 catalog 布局 `skills/<catalog>/<name>/SKILL.md`。
-
-### 7.2 与 DWS 的关键差异
-
-| 维度 | lark-cli | DWS 现状 |
-|---|---|---|
-| 分发单元 | repo `skills/` 目录（源码即事实源） | zip + 二进制 embed + 5 处拷贝缓存 |
-| 安装器数量 | **1 个**（生态工具，76 agent 清单别人维护） | **7 个**自维护脚本，清单已漂移 |
-| 落盘方式 | symlink（canonical 单点更新） | 全量 copy，升级要重写 16 个 home |
-| skill 升级 | `npx skills update`（生态承担） | `dws upgrade` 自写，且不识 multi |
-| mono/multi 问题 | **不存在** —— 天生按目录多 skill | 互斥清理/模式切换/状态全是自建 |
-| npm 包体积 | 薄壳（运行时下载单平台二进制） | 全平台 archive + skills.zip 全打进 tarball |
-| 大陆镜像 | registry 派生 + npmmirror | Gitee fallback + OSS（只发不读） |
-
-### 7.3 结论：生态分发通道**已否决**（2026-08-04）
-
-~~借生态安装器做分发通道~~ 方向经评估后**放弃**。否决原因（均为实测）：
-
-1. **无版本固定**：`skills add`（v1.5.21）不支持 tag/ref 安装，而 DWS skill
-   从 Cobra 树生成、与 CLI 版本强耦合，错配不可接受；唯一可复现机制
-   `skills-lock.json` 仍是 experimental。
-2. **依赖 Node + GitHub 可达**：curl|sh / Homebrew / 大陆 Gitee fallback 的
-   用户环境大量无 Node，生态通道在这些场景是断的。
-3. **mono 会被一起发现**：发布即制造双份，须等 mono 下线才能发布，节奏不合。
-4. **悟空 bundled / 离线预装**生态通道永远覆盖不了。（2026-08-05 注：
-   悟空分发线已下线，此条约束随之消失；前 3 条否决理由仍成立。）
-
-**决策：分发维持全自维护通道**（zip + embed + 安装脚本），按 P0–P2 落地；
-不从 lark-cli 借鉴分发架构。可保留的借鉴点只剩两个本地语义，与生态无关：
-
-1. **wizard 式幂等安装**：`install.sh` 的 multi 分支从"打印提示跳过"改为
-   检测 state 可重入的真正安装（参考 install-wizard 的步骤化幂等）。
-2. **npm 下载校验**：install.js 如后续薄壳化，可参考其 host allowlist +
-   checksum 双保险与镜像链（GitHub → registry 派生 → npmmirror）设计。
-   与本次 multi 迁移解耦，不单列任务。
-
-## 8. 工作量评估与任务拆解
-
-> 以 1 名熟悉本仓库的工程师计（人日）。规模基线：涉及生产代码约 5.0k 行
-> （Go 3.0k + shell/ps1/js 2.0k），已有测试 1.2k 行可复用。
-
-### 8.1 总体判断
-
-**核心路径 13–17 人日，一人一个月可行但偏紧**。风险不在 Go 而在"shell /
-ps1 / js 三语言 × 七面同步"和对应的测试矩阵。可选项（rollout 分桶、npm
-薄壳化、symlink、生态通道发布）全部可砍可后置，砍后**最小可行集 8–10
-人日**（见 8.4）。
-
-### 8.2 任务拆解（带依赖）
-
-```
-P0c 清单收敛 ──┐
-P0b state.json ─┼─► P0a upgrade mode-aware ─► P1 skill mode ─► P2 切默认
-备份式安装 ────┘         │                        │
-                         └─► x-dws-skill-mode 头   └─► beta 轨先切（P2 预演）
-```
-
-| # | 任务 | 改动面 | 估时 | 依赖 |
-|---|---|---|---|---|
-| P0c-1 | agent home 清单下沉共享包（setup/upgrade 共用），补 opencode | `internal/upgrade/paths.go` 或新 `internal/skillhome`（~80 行新代码） | 0.5d | — |
-| P0c-2 | `scripts/policy/check-agent-homes-sync.sh`：比对 sh/ps1/js/sh 专项清单与 Go 清单，进 `make policy` | 新脚本 ~120 行 + 各脚本清单改成可解析块 | 1d | P0c-1 |
-| P0b-1 | state.json schema + setup 写入（含 installed 列表、agent_homes、previous） | `internal/app/skill_setup.go` +新文件 ~200 行 | 1d | — |
-| P0b-2 | 磁盘形态反推（dws/ → mono；dingtalk-* → multi；都有 → drift 报错）+ 单测 | ~120 行 | 0.5–1d | P0b-1 schema |
-| P0-3 | 备份式安装：RemoveAll→mv backup、失败自动回滚、保留最近 2 份、改 warning 语义 | setup install 两函数重写 ~150 行 + 测试 | 1.5–2d | — |
-| P0a-1 | `UpgradeSkillLocations(dir, mode)`：mono 现状+清残留；multi 从 zip `multi/` 平铺刷新+清 `dws/`+刷缓存 | `internal/upgrade/paths.go` ~150 行 | 1.5d | P0c-1、P0b |
-| P0a-2 | upgrade×multi 集成测试（装 multi→upgrade→无 dws/ 残留、dingtalk-* 已刷新） | 测试 ~200 行 | 1d | P0a-1 |
-| P0-4 | `x-dws-skill-mode` 请求头（仿 `x-dws-channel`） | `internal/auth/oauth_helpers.go` 附近 ~30 行 | 0.5d | P0b |
-| P1-1 | `dws skill mode` status/set/rollback/--dry-run | 新文件 ~350 行 + 测试 | 2–2.5d | P0b、P0-3 |
-| P1-2 | beta 轨默认切 multi（版本门控的默认值翻转，stable 不变） | setup/install.sh 默认值逻辑 ~40 行 | 0.5–1d | P1-1 |
-| P2-1 | setup 默认翻转 + 交互选项反转 + mono 标 legacy | ~30 行 + 测试更新 | 0.5d | P1 |
-| P2-2 | install.sh / install.ps1 的 multi 分支**真装**（幂等、读 state 跳过） | 两个脚本各 ~80 行 | 1.5d | P0b（脚本侧写 state） |
-| P2-3 | install.js / install-skills.sh 加 mode 支持（env + flag，默认 multi） | 各 ~60 行 | 1d | P2-2 同批 |
-| P2-4 | 文案翻转：README×2、SKILL.md EXPERIMENTAL 下调、install 脚本提示、AGENTS.md | 纯文档 | 0.5d | — |
-| W4 | mono deprecation 警告（不删代码）+ 观察 | ~20 行 | 0.5d | P2 |
-
-**小计：核心 13–17 人日**（P0 ≈ 6.5–8.5，P1 ≈ 3–3.5，P2 ≈ 3.5，W4 0.5）。
-
-可选/后置：rollout.json 分桶 2–3d；`setup --link` symlink 1–2d（需逐 agent
-验证）；npm 薄壳化 2–3d（独立立项）。
-
-### 8.3 风险最高的两处（先动）
-
-1. **P0a upgrade multi 刷新语义**：additive 安装 vs upgrade 全量刷新之间存在
-   一个真实设计题 —— 用户手动 `-x` 排除过的 skill，upgrade 要不要装回来？
-   答案：以 state.json 的 `installed` 为准做增量刷新，未装的不得补装
-   （否则违背 additive 语义）。这条必须在 P0a 开工前定死。
-2. **P0-3 备份回滚改语义**：现有测试断言"清理失败继续装"，改语义会动
-   `skill_setup_full_coverage_test.go` 多处；回滚恢复顺序（先恢复再报错）
-   要用故障注入测试覆盖。
-
-### 8.4 一个月做不完时的砍法
-
-按价值/成本比从后往前砍：rollout 分桶（L1 beta 轨已够）→ install.js /
-install-skills.sh mode 支持（npm 渠道用户量小，可先只改 sh/ps1）。砍后**最小可行集 8–10 人日**：
-
-> P0c-1 + P0b + P0-3 + P0a + P1-1 + P2-1 + P2-2（仅 sh/ps1）+ 文案
-
-即：upgrade 不再制造双份、有状态可回滚、setup 与主流安装脚本默认 multi。
-npm/install-skills.sh 维持 mono 显式行为并在输出中标注即将切换。
-
-## 9. 明确不做
-
- 不做服务端远程配置/灰度平台（用 beta 轨 + rollout.json 替代）。
- 不动 `dws-skills.zip` 产物布局（已含 mono/multi 双树）。
- 不动市场 skill（`dws skill install`）的安装语义。
- 并行期内不删 mono 代码与产物，只降级为 opt-in。
@@ -1,153 +0,0 @@
-# Skill multi 迁移：技术方案（as-implemented）与 Roadmap
-
-> 本文是 multi 迁移的当前事实源：第一部分记录**已落地实现**（代码级锚点，
-> 均可跳转验证），第二部分是带实时状态的 roadmap。
-> 原始方案 [skill-multi-migration-plan.md](skill-multi-migration-plan.md) 的
-> 若干"待做"描述已被后续决策取代（见决策记录 D1/D5）；分发机制调研结论见
-> [skill-distribution-mechanism.md](skill-distribution-mechanism.md)。
-> 代码快照：`feat/skill-mode-migration` @ `402429ac` + 工作区
-> upgrade-force-multi 调整（2026-08-05）。
-
-## 状态速览
-
-| 项 | 内容 |
-|---|---|
-| 当前阶段 | **阶段 1 / 1.5 ✅**（安装/升级默认 multi 已落地）；**阶段 2 运行时切换产品线 ❌ CANCELLED**（2026-08-05 owner 决策） |
-| 硬 deadline | **2026-08-30**：安装/升级默认 multi（✅）+ upgrade **有 multi 包时一次性刷成 multi**（不做磁盘粘性）+ mono 仅安装时 opt-in；mono **物理下线**仍可在独立 retirement 版本推进，但**不再**依赖 `dws skill mode` / 备份回滚产品 |
-| 已完成 | 五面默认 multi、`dws skill setup` 默认 multi、互斥清理对称、文案翻转；upgrade 有 `multi/` 时一律刷新 multi（存量 mono 一次性迁移） |
-| 下一步 | beta/L1 版本门控与观察（靠 issue/回访，**无** `x-dws-skill-mode` 埋点）；可选 agent-home 清单门禁；内容 C 线并行 |
-| 终态 | mono 仅安装时 opt-in；日常 upgrade（含 multi 的包）刷 multi；mono 物理删除仍可在 dedicated retirement 版本收尾（非用户切换命令） |
-
-### 简化设计（2026-08-05 起生效）
-
-1. **安装时一次决定**：默认 multi；`DWS_SKILL_MODE=mono` / `--mode mono` / 安装器 TTY 选 mono 为唯一 opt-in。
-2. **装完无运行时切换产品**：不做 `dws skill mode set/rollback`，不做备份式安装 / `state.json` 记账产品面。
-3. **升级不做粘性**：release zip 含 `multi/` 时 **一律** 刷新 multi（清 `dws/`、刷产品 skill + 缓存）；仅 legacy 无 multi 树的包回退 mono 路径。存量 mono 在日常 upgrade 上一次性迁到 multi。
-4. **mono 下线**：安装侧仍可 opt-in；upgrade 已承担「有 multi 包即迁走」；物理删 mono 树可另议 retirement。
-5. **可观测**：`x-dws-skill-mode` 请求头已按 owner 决策移除；灰度靠 issue + 回访。
-
---
-
-# 第一部分：技术方案（as-implemented）
-
-## 1. 升级：包驱动 multi 刷新（`dws upgrade`）
-
-核心语义：**升级不做磁盘粘性**；产物有 `multi/` 时一次性刷成 multi。
-无需 `state.json`，也无运行时切换命令。
-
- `LocateSkillsRoot` 优先返回 zip 内 `multi/`（`internal/upgrade/paths.go`）。
- `UpgradeSkillLocations`：包内有 multi 技能树 → **始终** `upgradeMultiSkillLocations`
-  （平铺 `dingtalk-*` + `dws-shared`，删 mono 残留 `dws/`，清过期 multi skill，
-  刷 `~/.dws/skills/multi`）；无 multi 树的 legacy 包才走 mono 刷新。
- 这是 upgrade 上的一次性迁移，不是 `dws skill mode` 产品。
-
-测试：`internal/upgrade/paths_multi_test.go`（含
-`TestUpgradeSkillLocationsMonoDiskMigratesToMulti`）+
-`internal/app/upgrade_skill_multi_e2e_test.go`。
-
-## 2. 安装默认 multi（四个脚本面）
-
-四个脚本安装面默认值全部为 multi，`DWS_SKILL_MODE=mono` 为统一 opt-in，
-互斥清理双向对称。详见阶段 1 落地说明（`scripts/install.sh` /
-`install.ps1` / `build/npm/install.js` / `scripts/install-skills.sh`）。
-
-## 3. `dws skill setup` 默认 multi
-
- 非交互未指定 `--mode` 时默认 multi。
- 交互选项 multi 在前（默认）、mono 标 legacy。
- 仍可用 `dws skill setup --mode mono --yes` **重装**到 mono（这是安装入口，
-  不是 lifecycle 切换产品；无备份/state/rollback 命令）。
-
-## 4. 文案翻转
-
- `README.md` / `README_zh.md`：multi 默认、mono legacy。
- `skills/multi/dingtalk-skill/SKILL.md`：去掉 EXPERIMENTAL。
-
-## 5. 已验证
-
- `go test ./internal/upgrade ./internal/app ./test/scripts`（阶段 1 基线）+
-  upgrade-force-multi 单测 / fake-HOME E2E。
- 脚本面契约测试暴露 `DWS_SKILL_MODE` 与 mono/multi 选项。
-
-## 6. 决策记录
-
- **D1 升级不依赖 state.json**（仍成立）。不读状态文件；布局由包内容驱动。
- **D2 无服务端灰度**。L1 beta 轨 + issue/回访；L2 `rollout.json` 已砍；
-  kill switch = beta 撤回 / 重装 `--mode mono`（无 `skill mode` 命令）。
- **D3 生态分发通道已否决**（`npx skills add` 等）。见
-  [skill-distribution-mechanism.md](skill-distribution-mechanism.md)。
- **D4 互斥前缀约定**。`dingtalk-*` / `dws-shared` 属 DWS 产品 skill。
- **D5 无运行时模式切换（2026-08-05）**。取消阶段 2 的备份式安装、
-  `state.json`、`dws skill mode`（status/set/rollback）、`x-dws-skill-mode`
-  请求头。Mode 只在安装时决定。
- **D6 升级不做粘性（2026-08-05）**。有 multi 包时 upgrade 一次性刷成 multi
-  （含存量 mono）；legacy 无 multi 树才回退 mono 路径。
-
---
-
-# 第二部分：Roadmap
-
-## ✅ 阶段 1 / 1.5（已完成，2026-08-05）
-
-安装/升级默认 multi、五面互斥清理、文案翻转、1.5 review 修复与实机 9/9。
-HEAD：`402429ac`。
-
-## ❌ 阶段 2（原切换/状态/备份产品线）— CANCELLED（2026-08-05）
-
-| 原任务 | 状态 | 说明 |
-|---|---|---|
-| 备份式安装（`~/.dws/skills/backup/...`） | ❌ CANCELLED | 不做运行时切换，无需备份回滚产品 |
-| `~/.dws/skills/state.json` | ❌ CANCELLED | 无切换产品；upgrade 按包刷 multi，不需要状态文件 |
-| `dws skill mode` status/set/rollback/--dry-run | ❌ CANCELLED | 无运行时切换 UX |
-| `x-dws-skill-mode` 请求头 | ❌ CANCELLED | owner 决策移除；观测改 issue/回访 |
-| agent home 清单门禁 | ⬜ 可选 | 与切换产品无关，仍可作工程质量项 |
-| `upgrade --dry-run` multi 文案 | ⬜ 可选 | 可随 force-multi 语义轻量对齐 |
-
-## 重构后的 8/30 目标
-
-**底线**：新装默认 multi；含 `multi/` 的 release 上 `dws upgrade` **一次性刷成
-multi**（含存量 mono）；仅需保持 mono 的用户用安装入口 opt-in 后勿升级到
-含 multi 的包，或 retirement 前用 setup 重装；mono 物理删除可另议。
-
-### 建议关键路径（简化）
-
-```text
-阶段1默认multi ✅ → upgrade force-multi ✅ → beta/L1（可选）→ 观察(issue/回访)
-→ stable 默认已是 multi → 可选 mono retirement（删 mono 树 / 安装入口报错）
-```
-
-### mono retirement（原阶段 4，重框）
-
- **不再**提供 `dws skill mode rollback` 作为用户出口。
- 日常 upgrade 已在有 multi 包时迁走存量 mono；retirement 版本可进一步移除
-  install/setup 的 mono 分支与 zip 内 mono 树。
- 下线判据改为：issue/回访无系统性 multi P1、mono opt-in 可接受、政策门
-  不再依赖 `skills/mono/SKILL.md`。（原请求头占比判据作废。）
-
-## 悟空线下线的影响（2026-08-05）
-
-悟空 bundled-skill 分发线已下线：mono 下线无仓外节奏闸门；`skills/multi/`
-为唯一 multi 事实源。设计资产留档
-[skill-wukong-comparison.md](skill-wukong-comparison.md)。
-
-## 明确不做
-
- ❌ 运行时模式切换（`dws skill mode set/rollback`）。
- ❌ `state.json` / 备份式安装产品面（随 D5 取消）。
- ❌ `x-dws-skill-mode` 请求头。
- ❌ 服务端远程配置 / L2 `rollout.json`。
- ❌ 运行时「模式切换」产品（含 sticky 伪切换）；upgrade 有 multi 时刷 multi
-  是包驱动的一次性迁移，不是 switch UX。
- 不动 `dws-skills.zip` 双树布局（仍可含 mono 副本供安装 opt-in）；不动市场
-  skill（`dws skill install`）。
-
---
-
-## 风险表
-
-| 风险 | 现状 | 缓解 |
-|---|---|---|
-| 半装无备份 | 安装/清理仍 `RemoveAll` | 接受为非切换产品下的已知限制；重装可收敛 |
-| mono/multi 漂移 | 无 state；upgrade 有 multi 即刷 multi | 升级后收敛为 multi；安装互斥清理 |
-| 用户想换模式 | 无 switch 命令 | 文档引导：`dws skill setup --mode <mono\|multi> --yes` 重装 |
-| 8/30 滑期 | 切换产品线已砍，关键路径缩短 | 聚焦 force-multi upgrade + 默认 multi 稳定 |
@@ -1,290 +0,0 @@
-# DWS Skill mono→multi 灰度能力设计（rollout capability）
-
-> 本文回答一个问题：**在没有服务端远程配置/灰度平台的前提下，mono→multi
-> 默认翻转如何灰度发布、如何观测、如何止血**。关联文档：
-> [skill-multi-roadmap.md](skill-multi-roadmap.md)（迁移事实源，本文展开其
-> 阶段 3「灰度切流」）、[skill-multi-migration-plan.md](skill-multi-migration-plan.md)
-> §3.7（灰度与止血的原始设计）。代码锚点快照：`feat/skill-mode-migration`
-> 工作区未 commit 变更（2026-08-05）。
-
---
-
-## TL;DR 推荐路线
-
-| 步 | 动作 | 层级 | 前置 |
-|---|---|---|---|
-| 1 | 把「五面默认 multi」拆成**版本门控默认**（beta→multi / stable 观察），同一份代码发 beta 轨先吃 | L1 | 无（本文 §2.1） |
-| 2 | ~~阶段 2 四件套（备份 / state.json / `dws skill mode` / 请求头）~~ | — | **❌ CANCELLED（2026-08-05）**：无运行时模式切换；upgrade 有 multi 时刷 multi（不做粘性） |
-| 3 | beta 轨观察：issue 流入 + 主动回访（**无**请求头占比） | 人工 | 步 1 |
-| 4 | stable：默认 multi 已在阶段 1 落地；L2 `rollout.json` 已砍 | — | — |
-| 5 | kill switch：beta 撤回（已有）/ 公告重装 `dws skill setup --mode mono --yes` | — | 无备份回滚产品 |
-
---
-
-## 1. 现状盘点：今天可用于灰度的全部旋钮
-
-### 1.1 旋钮总表
-
-| # | 旋钮 | 代码锚点 | 生效范围 | 盲区（谁够不着） |
-|---|---|---|---|---|
-| K1 | GitHub Release 双轨（stable / prerelease） | `internal/upgrade/github.go:100-106`（`ReleaseTrack`）；`internal/app/upgrade.go:870-875`（`upgradeTrack`）；release.yml 强制版本→轨映射（`release.yml:547` 含 `-beta.` → prerelease） | `dws upgrade --beta` / `--version vX.Y.Z-beta.N` 的二进制+skill 升级 | 不用 `dws upgrade` 的人；Gitee/OSS 镜像用户（见 K3/K4） |
-| K2 | npm dist-tag 双轨（`latest` / `beta`） | `release.yml:1761-1762`（prerelease→`beta` tag）；发布防倒退 `release.yml:1828-1835`；撤回脚本 `scripts/release/withdraw-release.sh:652-665`（dist-tag 回拨+deprecate） | `npm i dingtalk-workspace-cli@beta` 的新装/重装 | npm 默认安装（`@latest`）用户无感；npm 装完即走、不再 `npm i` 的存量 |
-| K3 | Gitee 镜像（代码 + release 资产） | main 代码镜像 `.github/workflows/mirror-to-gitee.yml:42-82`；release 资产镜像 `release.yml:1957-1965`（`sync-to-gitee.sh`）；安装脚本侧 `DWS_GITEE_REPO` 解析 `scripts/install.sh:18-19`、`scripts/install-skills.sh:21-24` | curl\|sh / install-skills.sh 的国内用户（显式 env 或 GitHub 不可达自动回退） | **`dws upgrade` 不到 Gitee**：upgrade client 只打 GitHub API（`internal/app/upgrade.go:48` → `internal/upgrade/github.go`，包内无任何 Gitee 引用）；Gitee release 是否 prerelease 由镜像脚本原样搬运，无独立轨控 |
-| K4 | OSS 镜像（ossutil 同步） | `scripts/release/sync-to-oss.sh:9-14`（`download/<version>/` + `latest.txt`/`beta.txt` 指针）；`release.yml:1897-1908` | 今天：**只写不读**——脚本注释明示「repository installers currently resolve GitHub/Gitee and do not consume these OSS pointers directly」（`sync-to-oss.sh:5-7`） | 所有人（指针无人消费）；但 `latest.txt`/`beta.txt` 是天然的**可变 channel 指针**（见 §2.2 设计复用） |
-| K5 | 安装脚本 env / flag | `DWS_SKILL_MODE`：`scripts/install.sh:17`（解析 `install.sh:220-256`）、`scripts/install.ps1:293-332`、`scripts/install-skills.sh:29-33`；npm `--skill-mode` / env `build/npm/install.js:197-214`；`DWS_VERSION` 指定 beta 版 `install.sh:38` | 新装时的逐台显式控制（CI、内推灰度名单） | 只对**执行安装那一刻**生效；装完无持久化（无 state.json），事后无法得知当初怎么装的；`DWS_VERSION=latest` 在 GitHub 侧只解析 stable（`/releases/latest` 永不指向 prerelease，`install.sh:190-198`），beta 必须显式给版本号 |
-| K6 | 版本门控默认值（构建期注入） | goreleaser ldflags 注入版本 `.goreleaser.yaml:22`（`internal/app.version=v{{.Version}}`）；`prerelease: auto` `.goreleaser.yaml:68` | 同一 commit，beta build 与 stable build 可表现不同默认值（§2.1 切法 B 的机制） | 脚本面拿不到 Go 变量，需各自从「解析出的版本号」重推导（§2.1）；homebrew formula 只搬 zip 根（mono 布局）到 pkgshare（`build/homebrew.rb.tmpl:26-31`），formula 本身无 mode 概念 |
-| K7 | 本地遥测（opt-in） | `internal/shortcut/usage/recorder.go:82-88`（`DWS_USAGE_TRACKING=1`，默认关）；只写本地 `~/.dws/usage.jsonl`（`recorder.go:91`） | 高频命令形状挖掘（shortcut P2） | **不上传任何服务端**：对灰度占比测量零贡献；默认关意味着即使上传也无统计意义 |
-| K8 | 请求头通道（已有上行链路） | MCP 请求统一注入点 `internal/app/runner.go:953-1008`（`resolveIdentityHeaders`，接线于 `runner.go:140/240/597`、`internal/app/recovery_command.go:271/337`）；登录权限检查 `internal/auth/oauth_helpers.go:1424-1428`；`x-dws-channel`（`DWS_CHANNEL`）先例 `runner.go:1006-1008`、`oauth_helpers.go:1425-1426` | 服务端（MCP 网关）已能按 header 聚合：`x-dws-agent-id`、`x-dingtalk-dws-agent-code`、`X-Cli-Version` 均在线 | 只有「已登录且发 MCP 请求」的用户可被观测；纯安装未使用、auth 失败前的用户在分子里缺席（占比偏高估，§2.3） |
-
-### 1.2 结构性盲区（任何旋钮都够不着）
-
-| 盲区 | 说明 | 出处 |
-|---|---|---|
-| ~~悟空 bundled skill 分发线~~（盲区已移除） | 悟空分发线（dws_res → Wukong.app bundled-skills）已于 2026-08-05 决策下线，本盲区随之移除；历史上该线在**本仓库外**、仅有 main CI 成功后的下游触发（`.github/workflows/notify-wukong.yml:13-38`），本仓库默认值翻转管不到它 | 原 roadmap 风险表「悟空线外挂」行（已解除）、阶段 4 原判据 3（已作废） |
-| homebrew 用户 | formula 只把 zip 根（mono 副本）stage 进 `pkgshare/skills/dws`（`build/homebrew.rb.tmpl:26-31`），caveats 指向 `dws skill setup`（`:33-38`）；multi 源不在包内，`setup --mode multi` 只能靠 `~/.dws/skills/multi` 缓存 | 同上，K6 |
-| 永不升级的存量 mono 用户 | 所有旋钮都作用于「新装/升级/重装」三个时点；不动作的用户一切照旧（这正是灰度的天然保护层） | — |
-| 安装后不再运行 `dws` 的用户 | K8 观测不到，占比分母缺失 | §2.3 |
-
---
-
-## 2. 方案设计（分层）
-
-### 2.1 L1 渠道灰度：beta 轨先吃 multi 默认
-
-目标：**同一代码、不同 release 轨不同默认值**，stable 用户在观察期内完全无感。
-
-#### 切法 A：纯流程（零新增代码，不推荐单独使用）
-
-当前工作区五面已无条件翻转 multi；直接发 beta 即完成「beta 先吃」。
-问题：main 上的默认值已是 multi，**下一个 stable 无处可躲**——stable 发布
-窗口一到就必须全切，观察期长短不由人；且中途想给 stable 出补丁版（hotfix）
-会被迫带上 multi 默认。仅适合「beta 观察期确定短、stable 窗口确定远」的情形。
-
-#### 切法 B：版本门控默认值（推荐）
-
-把五面的默认值从「无条件 multi」改为「beta 版本默认 multi，stable 版本默认
-mono」。判据统一用版本号是否含 `-beta.`（release.yml 已强制版本→轨唯一映射，
-`release.yml:547`、`.goreleaser.yaml:68`）：
-
-| 面 | 门控取值来源 | 落点 |
-|---|---|---|
-| `dws skill setup` / `dws upgrade`（Go） | ldflags 注入的 `internal/app.version`（`.goreleaser.yaml:22`），`strings.Contains(version, "-beta.")` | `internal/app/skill_setup.go:354-357`（非交互默认）与 `:364-368`（交互默认项排序） |
-| install.sh / install.ps1 / install-skills.sh | 脚本自己解析出的 `$VERSION`（`install.sh:177-198`；Gitee 侧 `install.sh:180-188`）——`case "$VERSION" in *-beta.*)` | `install.sh:220-256`、`install.ps1:293-332`、`install-skills.sh:29` |
-| npm install.js | 包内 `package.json` 的 `version`（staging 时由 `stage-npm-package.sh` 写入 release 版本） | `build/npm/install.js:197-214` |
-
-**关键发现——upgrade 路径（2026-08-05 更新）。** skill 升级语义是「跟着 zip
-产物布局走、不做磁盘粘性」：`LocateSkillsRoot` 恒优先 `multi/`，
-`UpgradeSkillLocations` 在包内有 multi 时**始终**刷 multi（含存量 mono
-一次性迁移，清 `dws/`）。若仍要做「stable 观察期不迁 mono」，门控必须落在
-**是否发布含 multi 的 zip / 是否走 upgrade skill 刷新**，而不是磁盘粘性分支
-（粘性方案已否决）。当前产品默认接受：含 multi 的 release 上 upgrade = 迁
-multi。
-
-切法 B 的安装默认门控（beta→multi / stable→mono）仍可独立存在；与 upgrade
-force-multi 正交——安装 opt-in mono 的用户一旦升级含 multi 的包会被迁走。
-
-#### 风险与回退
-
-| 风险 | 说明 | 回退 |
-|---|---|---|
-| 门控不可见 | 默认值随版本号变化，review/测试容易漏 | 每面补契约测试（beta→multi / stable→mono），`test/scripts` 已有同构先例（`test/scripts/install_script_test.go:529-576`） |
-| 升级迁走 mono | **接受为产品语义**：有 multi 包时 upgrade 一次性刷 multi；需 mono 则 `dws skill setup --mode mono --yes` 重装（装完后再 upgrade 仍可能被迁回） | S1 撤回含 multi 的坏包；S3 公告重装 |
-| beta 轨整体有毒 | 二进制或 skill 包级事故 | 现有撤回链：`scripts/release/withdraw-release.sh`（GitHub release 撤回 + npm deprecate + dist-tag 回滚，`withdraw-release.sh:652-665`）；stable 轨不受影响 |
-| 版本字符串被仿造 | 本地 `go build` 无版本注入时 `version=""`，门控落 stable 分支（保守方向，正确） | — |
-
-### 2.2 L2 确定性分桶：随 release 发 `rollout.json`
-
-L1 的粒度是「轨」：beta 全吃、stable 全不吃。stable 切流若要 5%→100% 的
-渐进，需要机器级分桶。无服务端，用**随版本分发的只读配置 + 客户端确定性
-哈希**替代。
-
-#### rollout.json schema 与发布链路
-
-作为 release 资产随每个版本发出（进 `dist/`）：
-
-```json
-{
-  "skill_mode": {
-    "pct": 20,
-    "salt": "skill-mode-2026h2",
-    "note": "mono->multi default rollout for stable track"
-  }
-}
-```
-
- `pct`：0–100，`bucket < pct` 的机器默认 multi。
- `salt`：分桶盐，换盐=重新洗牌（默认不换，保证跨版本粘性可比）。
- 发布链路改动：`scripts/release/post-goreleaser.sh` 生成进 `dist/`；
-  **资产命名空间是精确集合**（`scripts/release/verify-release-artifacts.sh:12-38`，
-  「public release assets must contain exactly the supported files」），必须把
-  `rollout.json` 加进 EXPECTED_ASSETS；stable 晋升门会比较 beta 资产集
-  （`release.yml:833-846`），所以引入该资产的那个 beta 起两轨必须同时带。
- checksums.txt 由 dist 自动生成，镜像脚本（Gitee `release.yml:1957-1965`、
-  OSS `sync-to-oss.sh:9-14`）整目录搬运，**rollout.json 自动随资产集流到
-  Gitee/OSS，无需额外接线**。
-
-#### machine-id 来源：读现成，不新建
-
-`internal/auth/identity.go` 已有稳定 per-install UUID v4 `machineId`
-（`identity.go:19-20`、结构体 `:70-76`），持久化在 `~/.dws/identity.json`
-（`identity.go:51` + `pkg/config/constants.go:177-188`），惰性生成
-（`EnsureExists` `:115-133`），v1 文件透明迁移（`:98-113`）。分桶直接复用：
-
-```
-bucket = int(sha256(machineId + "|" + salt)[:8], 16) % 100
-```
-
-边界情况：`identity.json` 首建于首次 MCP 请求链路（`runner.go:954`）。灰度
-决策发生在 setup/upgrade 时，可能早于任何 MCP 请求——此时按 `EnsureExists`
-同款语义**就地惰性创建**（best-effort 持久化，失败则用进程内随机值且当次
-不记账，下次重决）。不引入第二套 `~/.dws/install-id`，避免双事实源。
-
-脚本面（sh/ps1）做 sha256 分桶要读 JSON + 哈希，复杂且易错；npm install.js
-用 node crypto 是一行。**范围划定：L2 分桶只在 Go 面（`dws upgrade` /
-`dws skill setup` / 未来 `dws skill mode`）与 npm install.js 实现**；sh/ps1
-停在 L1 版本门控（curl 用户全是新装，渠道轨已够；百分比分桶的主战场是存量
-升级，而升级必过 Go 二进制）。
-
-#### state.json 的 rollout 字段
-
-依赖阶段 2 的 `~/.dws/skills/state.json`（P0b，未实现，roadmap 阶段 2）：
-
-```json
-{
-  "mode": "multi",
-  "rollout": {
-    "bucket": 37,
-    "pct": 20,
-    "salt": "skill-mode-2026h2",
-    "decision": "multi",
-    "decided_at": "2026-08-20T08:00:00Z",
-    "decided_by": "rollout.json@v1.4.2",
-    "explicit": false
-  }
-}
-```
-
-决策顺序（每台机器只决策一次，粘性）：
-
-1. 本地显式（`DWS_SKILL_MODE` / `--mode` / `--skill-mode` / `dws skill mode set`）
-   → 用之，`explicit=true`；
-2. `state.json` 已有 `mode` 或磁盘形态可反推（roadmap 阶段 2 既定兜底）
-   → 保持现状，不参与分桶；
-3. `state.rollout.decision` 已存在 → 复用（pct 后续变化不翻案）；
-4. 拉取 `rollout.json`（Go 面：upgrade 已下载本版资产，同 release 再取一个
-   小文件；npm：包内自带）→ 算 bucket 决策并记账；
-5. 任一步失败 → 当期默认（L1 版本门控结果）。
-
-#### 三条硬规则
-
-| 规则 | 内容 | 理由 |
-|---|---|---|
-| R1 本地显式优先 | env/flag/命令任何时候压过 rollout 决策；显式选择落 `explicit=true` 后 rollout 永不改它 | 灰度不能覆盖用户意志；也是 kill switch 的用户侧出口 |
-| R2 拉取失败 fail-safe | 拉不到/解析失败/字段越界 → 保持现状（存量）或当期默认（新装），**绝不因拉取失败翻模式** | 无服务端下网络面即故障面，故障必须倒向保守侧 |
-| R3 存量不被改模式 | 已有 mode（state 或磁盘可推）的机器不参与分桶；pct 只影响「未决策」机器 | pct 从 20 降到 0 不能把已进 multi 的 20% 弹回 mono（那需要 kill switch，不是分桶语义） |
-
-#### 与 Gitee / immutable release 的兼容
-
- **Gitee**：`dws upgrade` 不读 Gitee（§1.1-K3），rollout.json 经
-  reconcile/sync 脚本随资产集镜像到 Gitee release；Gitee 侧安装脚本如需消费，
-  走与 `dws-skills.zip` 相同的 Gitee API 资产枚举（`install.sh:180-188` 同
-  模式）。一期不消费、只保证镜像不缺失。
- **immutable release 约束**：官方仓已开启不可变 release（`release.yml:802`
-  「Immutable releases must be enabled before publishing」），**资产发布后不可
-  替换**——调 pct = 发一个新补丁版（beta 线 release.yml 支持连续 beta：
-  `release_bump` 在连续 beta 线时被忽略，`release.yml:25-27`）。这决定了
-  L2 的调参时延 = 一次发版；追求更快止血见 §2.4。
- （可选远期）OSS `latest.txt`/`beta.txt` 是现成的**可变**指针
-  （`sync-to-oss.sh:13-14`），若未来 installer 学会读 OSS，可把
-  `rollout-current.json` 放 OSS 变指针后面实现「不发版调 pct」；今天无消费
-  方，不建。
-
-### 2.3 L3 可观测性：`x-dws-skill-mode` 请求头 — ❌ CANCELLED
-
-**2026-08-05 owner 决策：不实现该请求头**（与运行时模式切换 / state.json
-一并取消）。原设计（注入 `resolveIdentityHeaders`、按 state/磁盘上报
-`mono|multi|unknown`）仅作历史记录，不进入排期。
-
-观察手段改为：**issue 反馈 + 主动回访**；不再有请求级 multi 占比判据。
-
-### 2.4 Kill switch：四层止血
-
-| 层 | 手段 | 时延 | 现状/依赖 |
-|---|---|---|---|
-| S1 beta 轨整体撤回 | `scripts/release/withdraw-release.sh`：GitHub release 撤回 + npm deprecate + `beta` dist-tag 回拨（`:652-665`） | 分钟级 | **今天可用** |
-| S2 rollout.json `pct=0` | 发补丁版把 pct 打 0（immutable release 不允许原地改资产，§2.2） | 一次发版（小时级） | 依赖 L2 落地 |
-| S3 公告命令 | 公告用户重装 `dws skill setup --mode mono --yes`（安装入口，非 switch 产品） | 用户触达时延 | **可用**（无 `dws skill mode`；阶段 2 切换命令已 CANCELLED） |
-| S4 备份回滚 | ~~`dws skill mode rollback` + 备份式安装~~ | — | **❌ CANCELLED（2026-08-05）** 与运行时切换一并取消 |
-
-二进制侧另有既有的 `dws upgrade --rollback`（`internal/upgrade/rollback.go`，
-备份在 `~/.dws/data/backups`、保留 5 份 `:16/:54-63`），但只回滚二进制不回滚
-skill 布局——skill 止血靠 S1 + S3（重装 mono），**无** S4。
-
-**结论（2026-08-05）：** kill switch = S1（beta 撤回）+ S3（公告重装
-`--mode mono`）。S4 已取消；日常 upgrade 有 multi 包时**一次性刷 multi**
-（不做粘性），故「装完 mono 再 upgrade」会迁走——止血靠撤回坏包或重装。
-
---
-
-## 3. 对标（简要）
-
-**npm dist-tag 双轨（lark-cli 类企业内部 CLI 的通行形态）。** 以 npm 仓
-registry 为唯一分发面时，灰度即 dist-tag：`latest` 稳态、`beta`/`next` 先行
-（`next@canary`、`typescript@beta` 同款模式），安装侧 `npm i pkg@beta` 或
-CI 指定 tag 即完成分群；撤回即 `npm dist-tag add pkg@<prev> latest` +
-`npm deprecate`。DWS 已完整具备此形态（§1.1-K2），lark-cli 等内部 CLI 在
-集团内网 registry 上亦按同一范式运作——差别只在内部 registry 可附带按
-员工/部门灰度的下发规则，那是「registry 有服务端」的红利，DWS 面向公网
-npm 没有这一层，故需 L2 补齐。
-
-**安装时下载器内版本选择（deno / rustup 模式）。** `curl | sh` 安装器不显式
-给版本时，先拉一个**可变 channel 指针文件**（如 deno 的
-`dl.deno.land/release-latest.txt`、rustup 的 channel manifest），再按指针下载
-真实产物——指针一改全量新装即转向，**不发版即可调流**。DWS 的 OSS
-`latest.txt`/`beta.txt`（`sync-to-oss.sh:13-14`）已是同构物，只差安装脚本消费
-它；install.sh 今天直接打 GitHub `/releases/latest` 重定向（`install.sh:190-198`），
-等价于把 GitHub 当不可调指针用。此模式是指针级灰度，做不到机器级百分比，
-需与 L2 分桶叠加。
-
-**双产物并行（VS Code Stable / Insiders 模式）。** 两个渠道各发各的包、用户
-自选安装，灰度靠「渠道人口结构」自然形成，无需任何运行时门控。DWS 的
-GitHub prerelease + npm `@beta` 已是它的轻量版（同包不同 tag 而非两个包名），
-L1 切法 B 的版本门控默认正是把「渠道差异」从纯流程下沉为可测试的代码事实。
-
---
-
-## 4. 推荐路线与改动点清单
-
-### 4.1 路线（与 roadmap 阶段 2/3 对齐后的排序）
-
-```
-L1 版本门控拆分（本工作区之上叠加，先合入）
-  → ~~阶段 2 四件套~~ ❌ CANCELLED（无运行时切换；upgrade force-multi）
-  → beta 轨发版先吃（L1 自动生效）+ L3 观察 ≥2 周
-  → stable 切流：小步直接 100%（删门控）；若要求渐进再上 L2 分桶
-  → mono retirement 判据（roadmap：issue/回访，**无**请求头占比）
-```
-
-### 4.2 改动点清单（文件级）
-
-| 项 | 文件 | 改动 | 估时 |
-|---|---|---|---|
-| L1-a Go 门控函数 | `internal/app/skill_setup.go`（或新 `internal/upgrade/track.go` 下沉共享） | `defaultSkillModeForVersion(version)`：含 `-beta.`→multi 否则 mono；替换非交互默认与交互排序 | 0.5d |
-| L1-b upgrade force-multi（已落地） | `internal/upgrade/paths.go` `UpgradeSkillLocations` | 有 multi→始终 multi（含 mono 盘迁移）；legacy 无 multi→mono | ✅ |
-| L1-c 脚本面门控 | `scripts/install.sh` / `install.ps1` / `install-skills.sh` / `build/npm/install.js` | 默认值解析加 `*-beta.*` 分支（若仍做 L1） | 0.5d |
-| L1-d 契约测试 | `test/scripts` / `internal/upgrade` / `internal/app` | 每面断言 beta→multi；upgrade mono→multi E2E | 0.5–1d |
-| L3 请求头 | — | **❌ CANCELLED** | — |
-| L2-a/b/c rollout.json | — | **已砍**（roadmap） | — |
-| S3/S4 | — | S3=重装 mono（可用）；S4 备份/rollback **❌ CANCELLED** | — |
-
-合计：L1 ≈ 2–2.5d；L3 ≈ 0.5d；L2 ≈ 2.5–3d（在 state.json 之后）。
-L1+L3 是进入 beta 观察期的最小集；L2 只在 stable 需要渐进切流时才启动，
-否则删门控一步到位即可。
-
-### 4.3 明确不做（沿用 roadmap/D2，本文补充）
-
- 不建服务端远程配置/灰度平台；不为灰度单独引入可变配置下发通道（OSS 变
-  指针仅作远期可选，今天无消费方）。
- 不动 `dws-skills.zip` 产物布局（D1）；不按轨发不同 zip——轨差异全部落在
-  版本门控的客户端行为上。
- 不用遥测做灰度测量（K7 本地 opt-in 无统计意义），观测只走 K8 请求头。
@@ -1,340 +0,0 @@
-# DWS multi-skill vs 悟空（dws-wukong）分发线对比
-
-> ⚠️ **留档注记（2026-08-05）**：悟空（dws-wukong）bundled-skill 分发线
-> 已于 2026-08-05 决策下线。本文自此仅作**历史调研留档**，不再作为任何
-> 对齐依据——文中的「判据 #3」「对齐清单（§7.1）」「待确认问题（§7.2）」
-> 等均随悟空线下线而 MOOT。其中 bundle 的自描述打包设计
-> （`manifest.json` + `scripts/_install.sh`）与 symlink 提升消费方式
-> 可作为未来打包方案参考保留。
->
-> 撰写日期：2026-08-05。聚焦 **multi-skill** 主题：DWS 侧（本工作区
-> `feat/skill-mode-migration`）已把 multi 翻转为全通道默认，而 mono 下线
-> 原判据 #3 曾要求"悟空 bundled skill 分发线（dws_res → bundled-skills）
-> 已切 multi"（[skill-multi-roadmap.md](skill-multi-roadmap.md) 阶段 4、
-> [skill-multi-migration-plan.md](skill-multi-migration-plan.md) §5；
-> 该判据已于 2026-08-05 随悟空线下线作废）。
-> 本文盘清悟空线现状、两边差异、切换影响与对齐清单。
->
-> 配套阅读：[skill-multi-roadmap.md](skill-multi-roadmap.md)（DWS 侧
-> as-implemented 事实源）、[skill-distribution-mechanism.md](skill-distribution-mechanism.md)
-> （DWS 分发/消费链路调研）。
-
-## 0. 摘要（TL;DR）
-
- **DWS 侧**：multi（`skills/multi/`，19 个 `dingtalk-*` 产品 skill +
-  `dws-shared`）已是安装（4 脚本面）、升级、`dws skill setup` 五面默认；
-  产物 `dws-skills.zip` 恒含"根 mono 副本 + `mono/` + `multi/`"三树，
-  二进制 embed 双树（`skills_embed.go:28`）。**产物零改动即完成默认翻转**。
- **悟空侧**：multi 打包能力**已合入 dws-wukong `develop`**（merge
-  `9eb801e5`，"DWS MultiSkill 与 Qwen Work Cloud 六平台打包"），但
-  **正式发版 target `make real-platform` 仍只打 mono**
-  `dingtalk-workspace.zip`；multi 以 `dingtalk-workspace-bundle.zip` 双包
-  形态存在（`bundle-platform` / `package-dual`），本地有 2026-07-03 的双包
-  实测产物，但**未随已发布版本出门**（`release/0.2.97`–`0.2.99` 均不含该
-  merge）。
- **关键缺口在客户端**：RewindDesktop（悟空桌面端）构建期
-  `download_binary.py` 只认 `dingtalk-workspace.zip` 单 zip；运行时
-  `dws_update.rs` 灰度更新也只 upsert 单个 `dingtalk-workspace` skill；
-  全仓 grep 无 `dingtalk-workspace-bundle` / T4b 处理。**端内尚无消费
-  multi bundle 的代码路径**。
- **悟空线的 multi 与 DWS 的 multi 是两套独立维护的树**（dws-wukong
-  `dingtalk-skills/` 12 产品 + `dws-shared`，由本仓 mono 机械派生；DWS
-  `skills/multi/` 19 产品 + `dws-shared`），内容靠 SOP 人工对齐，无自动
-  同源。判据 #3 的"切 multi"首先要解决的是**打包形态 + 端内加载**，
-  内容同源是紧随其后的问题。
- 结论（历史）：判据 #3 远未满足。对齐需要 dws-wukong 仓（发版 target）、
-  RewindDesktop 仓（构建期 + 运行时两条加载路径）两侧改动，详见 §7 清单。
-  **（2026-08-05 MOOT：悟空线下线，判据 #3 已作废——见
-  [skill-multi-roadmap.md](skill-multi-roadmap.md) 阶段 4 判据更新；
-  上述对齐工作不再需要。）**
-
-## 1. 证据源与版本快照
-
-本地仓库（均为真实磁盘证据，非仅凭文档）：
-
-| 仓库 | 本地路径 | 核查时状态 |
-|---|---|---|
-| DWS（本仓） | `~/GolandProjects/open-source/dws-skill-mode-migration` | `feat/skill-mode-migration`，含未 commit 的阶段 1 变更 |
-| dws-wukong 主仓 | `~/GolandProjects/open-source/dws-wukong` | checkout `codex/deploy-qwenwork-dev`（落后 develop 602 commits）；本文 Makefile/脚本结论均以 `develop` 分支内容（`git show develop:...`）为准 |
-| dws-wukong multiSkill 工作区 | `~/GolandProjects/open-source/dws-wukong-multiSkill` | detached @ `9eb801e5`（multiSkill merge 本体），`target/` 有 2026-07 实测产物 |
-| RewindDesktop | `~/IdeaProjects/RewindDesktop` | checkout `dws/0.2.98`；`develop` 上 `DEFAULT_DWS_RES_URL` = pod `0.2.96` |
-
-关键版本事实：
-
-| 事实 | 证据 |
-|---|---|
-| multiSkill merge `9eb801e5` 已入 `develop` 与本地 `release/0.2.100` | `git branch --contains 9eb801e5` |
-| `release/0.2.97` / `0.2.98` / `0.2.99` **不含** multiSkill merge；其 `real-platform` 不打 bundle | `git merge-base --is-ancestor` + `git show origin/release/0.2.99:Makefile` |
-| 当前发给悟空的 pod 包为 mono：`dws_res_mac.zip` 内仅 `dingtalk-workspace.zip`（单 skill，`SKILL.md`+`references/products/*`）+ 双架构二进制 | 主仓 `target/dws_res_mac.zip`（2026-06-01）`unzip -l` 实测 |
-| 双包形态已实测：`dws_res_mac/` 同时含 `dingtalk-workspace.zip`（924K）与 `dingtalk-workspace-bundle.zip`（1.27M） | multiSkill 工作区 `target/dws_res_mac.zip`（2026-07-03）实测 |
-| multi bundle 内部布局：`manifest.json` + `scripts/_install.sh` + `skills/<name>/SKILL.md...` 平铺目录 | multiSkill 工作区 `target/dingtalk-workspace.zip`（2026-07-24）实测 |
-
-**本地未能验证**（详见 §7.2 问题清单）：pod 线上当前包内容（需内网
-SSO）；`/Applications/Wukong.app` 未安装在本机（bundled-skills 目录不存在，
-无法核对在端真实 zip）；RewindDesktop 端"T4b 二选一"灰度逻辑（全仓无匹配，
-疑似未开发或在平台侧）；Qwen Work Cloud 六平台打包的实际发布状态。
-
-## 2. 分发链路对比
-
-### 2.1 链路全景
-
-DWS 侧（本仓，multi 已默认）：
-
-```text
-skills/mono/ ─┬─ go:embed all:skills/mono all:skills/multi (skills_embed.go:28)
-skills/multi/ ┘      │  `dws skill setup` 默认源（embed 优先）
-              │
-              └─ scripts/release/post-goreleaser.sh:220-248 ──► dws-skills.zip
-                 （根 = mono 副本 + mono/ + multi/，三树恒含）
-                        │
-        GitHub Release / Gitee / OSS / npm tarball / Homebrew / 专项脚本
-                        │
-   install.sh · install.ps1 · install-skills.sh · npm install.js（四面默认 multi）
-   + `dws skill setup`（第五面默认 multi）+ `dws upgrade`（布局探测→multi 刷新）
-                        │
-              各 agent home 平铺 dingtalk-*/（互斥清理 dws/ 与过期 skill）
-              + ~/.dws/skills/{mono,multi} 双缓存
-```
-
-悟空侧（dws-wukong + RewindDesktop，发版线仍 mono）：
-
-```text
-上游 CLI 仓 ../dingtalk-workspace-cli（go.mod replace，sync-upstream 按
-CLI_UPSTREAM_TAG 重建 release 分支）──► 只提供 Go 代码，不提供 skill 内容
-
-dws-wukong 仓内 skill 内容（自维护）：
-  dingtalk-workspace/（mono 源，含 overlays/real）
-      ├─ build-workspace-zip ──► dingtalk-workspace.zip（mono，单 skill）
-      └─ scripts/sync-monolith-to-multiskill.py ──► dingtalk-skills/（multi 派生树）
-             └─ scripts/build-bundle.sh ──► dingtalk-workspace-bundle.zip
-                  （manifest.json + scripts/_install.sh + skills/<name>/）
-
-make real-platform（发版默认）──► dws_res_{mac,win}.zip
-      = dws 二进制 + dingtalk-workspace.zip（仅 mono）
-make bundle-platform / package-dual（已合入 develop，未用于正式发版）
-      = dws 二进制 + dingtalk-workspace.zip（mono 兜底）+ dingtalk-workspace-bundle.zip
-                        │
-        pod.alibaba-inc.com zipUpload（SSO 浏览器上传，版本号独立递增）
-                        │
-        RewindDesktop scripts/download_binary.py（DEFAULT_DWS_RES_URL 手工对齐）
-                        │
-        Wukong.app Contents/Resources/resources/
-            ├─ dws/bin/dws（二进制）
-            └─ bundled-skills/dingtalk-workspace.zip（原样拷贝的单 zip）
-                        │
-        运行时两条路：
-        a) 启动同步 initialize_bundled_skills_from_resources
-           → 解 zip 到中央技能库 ~/.real/.skills/bundled/dingtalk-workspace
-           （及 ~/.real/users/*/.skills/bundled）
-        b) 灰度自更新 dws_update.rs：Gaea 开关 wukong/dws_auto_update_enabled_v2
-           → LWP /r/Adaptor/DwsGrayI/getLatest 取 {version,url,sha256}
-           → 下载 dws_res → 换 seed 二进制 + 换 bundled zip + upsert 单 skill
-```
-
-### 2.2 链路对照表
-
-| 环节 | DWS（本仓） | 悟空线 | 锚点（悟空侧） |
-|---|---|---|---|
-| skill 事实源 | `skills/mono` + `skills/multi`（同仓双树，multi 19 产品 + dws-shared） | dws-wukong 仓 `dingtalk-workspace/`（mono 源）→ 派生 `dingtalk-skills/`（12 产品 + dws-shared）；**与上游 skills/ 无自动同步** | `scripts/sync-monolith-to-multiskill.py` docstring |
-| 二进制与 skill 的版本耦合 | embed 进二进制，天然同版 | 二进制来自上游 tag（`go.mod:58` replace + `sync-upstream` pin `CLI_UPSTREAM_TAG`）；skill 在 dws-wukong 仓随 `VERSION`/`main.go` 双写发版 | dws-wukong `Makefile` `sync-upstream` |
-| 打包产物 | `dws-skills.zip`：根 mono 副本 + `mono/` + `multi/`（`post-goreleaser.sh:220-248`）；embed 双树 | `dws_res_{mac,win}.zip`：二进制 + `dingtalk-workspace.zip`（mono）；双包 target 已存在但未上发版线 | dws-wukong `Makefile` `real-platform` / `bundle-platform` / `package-mac-dual` |
-| 渠道 | GitHub/Gitee/OSS/npm/Homebrew/专项脚本，7 个安装面 | pod zipUpload（SSO）→ RewindDesktop `download_binary.py` → 客户端 bundle | release skill 文档 + `download_binary.py:72-84` |
-| 端内安装 | 4 脚本 + `dws skill setup` 平铺到 16 个 agent home（父目录门控） | 构建期拷贝 zip 进 app 资源；启动时解到 `~/.real/.skills/bundled/` | `startup.rs:486-554` |
-| 运行时更新 | `dws upgrade`（布局探测→multi 刷新 + 互斥清理 + 缓存刷新） | 客户端灰度自更新（Gaea + LWP），整包替换 seed 二进制 + skill zip | `dws_update.rs:107,27-28,440-545` |
-| 灰度能力 | 无服务端：beta 轨（L1）+ 可选 `rollout.json` 分桶（L2）+ 公告 kill switch（决策 D2） | 有服务端：Gaea 开关 + LWP getLatest + pod 版本号 | 决策记录 D2 vs `dws_update.rs` |
-
-## 3. skill 布局对比
-
-### 3.1 三种形态
-
-| 形态 | 布局 | 消费方 |
-|---|---|---|
-| DWS mono | 单 skill：`SKILL.md` + `references/` + `scripts/`，装进 `<agent-home>/dws/` | DWS legacy 安装面；悟空 `dingtalk-workspace.zip` 同构（多 `plugins/`、real overlay） |
-| DWS multi | 平铺目录树：`multi/dingtalk-<product>/{SKILL.md,references,scripts}` + `multi/dws-shared/`，无 manifest、无安装器，拷贝即平铺到 agent home | DWS 五面默认；`dws upgrade` 探测 `multi/` 树（`internal/upgrade/paths.go:363-369`） |
-| 悟空 multi bundle | zip 内 `manifest.json`（`{"version":...}`）+ `scripts/_install.sh` + `skills/<name>/` 平铺目录（含 `dws-shared`） | **Qwen Work Cloud 已消费**（`_install.sh` 把 `skills/*` 以 symlink 提升到一层 skills 根，供 Codex/OpenCode 扫描；`.dws-multiskill-current` + `.dws-multiskill-links` 记账）；**Wukong.app 尚未消费** |
-
-注意两种 multi 的"平铺"语义不同：DWS multi 是**裸目录树**，由安装面自己
-拷贝到各 agent home；悟空 bundle 是**自描述包**（manifest + 安装脚本），
-由消费方解包后提升。`dws-skills.zip` 的 `multi/` 树与
-`dingtalk-workspace-bundle.zip` 的 `skills/` 树**布局同构但内容不同源**
-（见 §3.3）。
-
-### 3.2 悟空客户端加载约定（RewindDesktop 实测）
-
-构建期（`scripts/download_binary.py`）：
-
- `DWS_RES_WORKSPACE_ZIP = "dingtalk-workspace.zip"`（`:103`），
-  `resolve_dws_res_contents`（`:1366-1380`）强制 dws_res 内必须同时有
-  平台二进制和**这个文件名的 zip**——`dingtalk-workspace-bundle.zip` 会被
-  原样忽略（不报错，但也不使用）。
- `sync_dingtalk_workspace_bundle`（`:1422-1432`）把该 zip **原样拷贝**到
-  `tauri-app/src-tauri/resources/bundled-skills/dingtalk-workspace.zip`，不解包。
-
-运行时（`tauri-app/src-tauri/src/skills/startup.rs`）：
-
- `collect_bundled_skill_sources`（`:486-506`）扫描 `resources/bundled-skills/`：
-  **每个子目录或每个 `.zip` = 一个 skill**，`skill_id = 文件主干名`
-  （`dingtalk-workspace.zip` → skill id `dingtalk-workspace`）。
-  该扫描**天然支持多 skill 平铺**（放 `dingtalk-mail.zip`、`dingtalk-doc.zip`
-  就会被分别注册），但**不认识嵌套 bundle**：若把
-  `dingtalk-workspace-bundle.zip` 丢进去，只会被当成一个名叫
-  `dingtalk-workspace-bundle` 的单 skill 解开（内容是 manifest+skills/ 目录，
-  不会被提升）。
- `sync_bundled_skill_source`（`:533-554`）解 zip 拷贝进中央技能库；
-  `cleanup_removed_bundled_skills`（`:508-531`）会删除 bundled-skills 里
-  已不存在的 bundled skill（mono→multi 切换时可自动清掉旧
-  `dingtalk-workspace`，前提是 store 记录完好）。
- 灰度自更新 `dws_update.rs:440-545` 硬编码单 skill：
-  `upsert_bundled_skill_from_source(store, DWS_WORKSPACE_SKILL_ID, …)`
-  （`DWS_WORKSPACE_SKILL_ID = "dingtalk-workspace"`），换包 = 替换
-  `bundled-skills/dingtalk-workspace.zip` + 重 upsert 这一个 skill。
-
-结论：端内**构建期与运行时两条路都按"单 zip 单 skill"接线**；要支持
-multi，二选一：(a) 端内学会解 bundle（manifest + 提升子 skill），或
-(b) 打包侧把每个子 skill 打成独立 zip 平铺进 dws_res，复用现有平铺扫描
-（仅需把 `dws_update.rs` 的单 skill upsert 改为遍历）。详见 §6.2。
-
-### 3.3 两套 multi 树的集合差异
-
-| | DWS `skills/multi/` | dws-wukong `dingtalk-skills/`（develop） |
-|---|---|---|
-| 产品 skill 数 | 19 | 12 |
-| 共有（12 个） | aisearch, aitable, calendar, chat, contact, doc, drive, mail, minutes, misc, todo, wiki | 同左 |
-| 仅 DWS 有（7 个） | dev, event, hrbrain, markdown, pat, profile, skill | — |
-| 共享层 | `dws-shared` | `dws-shared`（内容独立维护） |
-| 内容来源 | 本仓直接维护 | 由本仓 mono `dingtalk-workspace/` 经 `sync-monolith-to-multiskill.py` 机械派生（链接改写 + misc 桶归并） |
-| 场景 skill | 不涉及 | `dingtalk-products-skills/` 23 个 scenario skill **仅保留源码，不进统一发布包**（`build-bundle.sh` 头注释） |
-
-含义：即使悟空线明天切到 multi 形态，其 multi **内容**与 DWS multi 也不
-一致（少 7 个产品、各自演化）。判据 #3 只要求"分发线切 multi"（形态），
-但长期看内容同源（或明确的子集契约）需要一并决策。
-**（2026-08-05 MOOT：悟空线下线，"DWS skills/multi(19) vs 悟空
-dingtalk-skills(12) 分歧"的长期统一问题随之作废，无需统一；DWS
-`skills/multi/` 成为唯一 multi 事实源。）**
-
-## 4. 版本对齐对比
-
-| 维度 | DWS | 悟空线 |
-|---|---|---|
-| skill↔CLI 耦合 | embed 进二进制，`dws skill setup` 装的就是本二进制版本（`skills_embed.go` + `skill_setup_embed.go`） | 二进制版本 = 上游 tag（`sync-upstream` pin）；skill 版本 = dws-wukong `Makefile VERSION` + `main.go version` 双写；**两者只通过"同一次发版动作"对齐，无结构性强约束** |
-| 产物版本 | `dws-skills.zip` 随 goreleaser 与二进制同 tag 发布 | pod 版本号独立于 dws 版本（右most 段 +1 递增，mac/win 各自一条线，如 mac `0.2.28.0`、win `0.2.2`）；RewindDesktop `DEFAULT_DWS_RES_URL` 手工改指 |
-| 端内版本事实源 | — | 客户端以 `dws --version` 输出为准（`get_dws_version_sync`，失败回退 `versions.json`）；skill zip 无独立版本概念（mono zip 内无 manifest） |
-| multi 包版本 | 无 manifest；版本 = 所属 zip/二进制版本 | bundle 内 `manifest.json` 带 `version`（`build-bundle.sh` 由 `$(VERSION)` 写入）——**multi 形态反而第一次给 skill 包带来了显式版本号** |
-| 升级时的布局兼容 | 新 zip 恒含 `multi/`，`LocateSkillsRoot` 优先 multi；老 zip 自然落回 mono（决策 D1，产物零改动） | dws_res 布局固定（二进制 + workspace zip）；双包形态下 mono zip 保留作兜底（`package-mac-dual` 注释："端内 validate 必含，bundle 缺失时兜底"） |
-
-## 5. 更新 / 回滚对比
-
-| 维度 | DWS | 悟空线 |
-|---|---|---|
-| 更新触发 | 用户主动 `dws upgrade` / 重装脚本 | 两条：(a) 随客户端版本更新（app 内嵌资源替换 + 启动同步）；(b) 运行时灰度自更新（Gaea `dws_auto_update_enabled_v2` + LWP getLatest → 下载整包 → 换 seed 二进制 + 换 bundled zip + upsert skill） |
-| skill 刷新语义 | 布局探测（multi 优先）+ 按 home 互斥清理（删 `dws/`、过期 `dingtalk-*`/`dws-shared`），清理失败则该 home 不装，杜绝共存（`internal/upgrade/paths.go:217-299`） | 启动同步按 bundled-skills 现状全量对账（新增拷贝、缺失删除，`startup.rs:508-554`）；自更新路径是单 zip 替换 + 单 skill upsert（`dws_update.rs:462-513`） |
-| 回滚 | `dws upgrade --rollback` 只回二进制不回 skill；备份式安装 + `dws skill mode rollback` 是阶段 2 P0，**尚未落地** | 无显式回滚命令；事实回滚 = Gaea 开关关闭/改指旧 pod 版本重新下发，或客户端版本回退；`replace-wukong-skill.sh`（仅存在于 `codex/deploy-qwenwork-dev` 分支）提供人工替换 + 重启 |
-| 半装保护 | 现状 `RemoveAll` 直删、失败仅 warning（风险表已列，阶段 2 改备份式） | zip 整体替换 + preflight 可写性检查，失败提示重启；粒度为整个 skill 包，无子 skill 级半装概念 |
-| 离线/内网 | embed 兜底（无网可 setup） | app 内嵌 zip 兜底；灰度通道依赖内网 LWP/pod 可达 |
-
-## 6. 切换影响分析
-
-### 6.1 DWS 切 multi 默认 / 最终删 mono 对悟空线的影响点
-
-| # | 影响点 | 评估 |
-|---|---|---|
-| 1 | DWS 删 `skills/mono` 后上游 embed 只剩 multi；悟空二进制由上游 tag 构建，`dws skill setup` 行为随之变 | **低**。悟空客户端不从 embed 装 skill（走 bundled zip）；但悟空用户在端内手动跑 `dws skill setup` 时会得到 multi——行为变化需在悟空侧公告 |
-| 2 | `dws-skills.zip` 布局（根 mono + mono/ + multi/） | **零影响**。悟空线不消费 `dws-skills.zip`；DWS 侧也已承诺不动该产物（决策 D1、"明确不做"） |
-| 3 | dws-wukong 的 mono 内容源 `dingtalk-workspace/` 与上游 `skills/mono` 本就各自维护 | **低（但需注意）**。上游删 mono 不会直接打破 dws-wukong 构建；但两边 mono 的"内容漂移对照基准"消失，dws-wukong mono 将彻底成为孤儿副本，加速与上游 CLI 能力的文档漂移 |
-| 4 | mono 下线判据 #3 反向卡住 DWS 侧进度 | **高（流程性）**。悟空线一天不切 multi，DWS 就不能物理删 `skills/mono/`（roadmap 风险表"悟空线外挂"行）。**（已解除 2026-08-05：悟空线下线，判据 #3 作废，DWS 侧进度不再受仓外闸门约束）** |
-
-### 6.2 悟空线"吃 multi"的改造选项
-
-**选项 A：端内解 bundle（dws-wukong 现有 bundle 产物直接被消费）**
-
- dws-wukong 侧：`real-platform` 改打（或加打）`dingtalk-workspace-bundle.zip`
-  ——`bundle-platform` / `package-dual` 已就绪，基本零新开发。
- RewindDesktop 侧（主要工作量）：
-  - `download_binary.py`：`resolve_dws_res_contents` 接受/校验
-    `dingtalk-workspace-bundle.zip`，同步进 `resources/bundled-skills/`；
-  - `startup.rs`：识别 bundle（`manifest.json` + `skills/*`），把每个子
-    skill 注册为独立 bundled skill（逻辑等价于 `_install.sh` 的提升，
-    但落在中央技能库）；
-  - `dws_update.rs`：灰度自更新从"单 skill upsert"改为"bundle 全量对账"
-    （可复用启动同步的对账逻辑）。
- 优点：与 Qwen Work Cloud 已消费的包形态一致，一份产物两个端；bundle 自
-  带 `manifest.json` 版本号。
- 缺点：端内要新增 bundle 解析/提升代码与测试；`skills/` 嵌套布局与现有
-  "一 zip 一 skill"约定不同，需谨慎处理迁移期（旧 mono skill 清理）。
-
-**选项 B：打包侧拆 zip（端内零新格式）**
-
- dws-wukong 侧：新增 target 把 `dingtalk-skills/` 每个子 skill 打成独立
-  zip（`dingtalk-mail.zip` … `dws-shared.zip`）平铺进 dws_res。
- RewindDesktop 侧：`download_binary.py` 改为同步多个 zip；
-  `startup.rs` 现有平铺扫描**零改动**（自动注册每个 zip）；
-  `dws_update.rs` 仍需从单 skill upsert 改为遍历。
- 优点：复用端内现有"一 zip 一 skill"约定，启动路径几乎不动。
- 缺点：与 Qwen Work 的 bundle 形态分叉（一份内容两种包）；dws_res 内文件
-  数膨胀；`dws-shared` 作为独立 skill id 出现在用户可见列表里需要确认
-  端内展示策略。
-
-**选项 C（过渡态，事实已在用）**：双包并存——mono zip 兜底 + bundle 灰度，
-端内按灰度二选一。`package-dual` 的注释已写明此意图（"端内 T4b 二选一，
-monolith 端内 validate 必含，bundle 缺失时兜底"），但**端内 T4b/灰度选择
-逻辑在 RewindDesktop 尚未找到实现**，当前双包发出去也只会用 mono。
-
-### 6.3 mono 下线判据 #3 的建议验收方式
-
-> **（2026-08-05 MOOT：判据 #3 已随悟空线下线作废，本节验收清单不再
-> 适用，仅留档。）**
-
-判据原文："悟空 bundled skill 分发线（dws_res → bundled-skills，本仓库
-外）已切 multi"（原 [skill-multi-migration-plan.md](skill-multi-migration-plan.md)
-§5-3；该判据已于 2026-08-05 作废，plan §5 已重新编号）。建议按以下
-可核查项验收（全绿才算满足）：
-
-1. **发版**：dws-wukong 正式 release 流程（release skill 文档中的
-   `make real-platform` 路径）产出的 dws_res 内含 multi 形态包（bundle 或
-   平铺 zip 集），且 pod 上当前版本即为该形态。
-2. **构建期消费**：RewindDesktop `develop` 的 `download_binary.py` 把 multi
-   形态同步进 `bundled-skills/`（不再是只认 `dingtalk-workspace.zip`）。
-3. **运行时消费**：悟空端启动同步后，`~/.real/.skills/bundled/` 下出现
-   `dingtalk-*` 多 skill（而非单个 `dingtalk-workspace`）；灰度自更新路径
-   同样支持多 skill 对账。
-4. **实机回归**：全新安装悟空 → 技能列表出现各 `dingtalk-*` skill 且
-   路由正常；从 mono 旧版升级 → 旧 `dingtalk-workspace` 被清理、无双份
-   派发；灰度通道下发一次 multi 包 → 更新后无残留。
-5. **回退预案**：悟空侧保留 mono 兜底产物或快速重发能力，直至 DWS 删
-   mono 窗口关闭。
-
-## 7. 结论
-
-### 7.1 对齐清单（悟空侧待办，按优先级）
-
-> **（2026-08-05 MOOT：悟空线下线，本清单整体不再需要执行，仅留档。）**
-
-| 优先级 | 事项 | 仓库/位置 | 备注 |
-|---|---|---|---|
-| P0 | 决策端内 multi 消费方案（选项 A 解 bundle vs 选项 B 平铺 zip） | RewindDesktop + dws-wukong 联合 | 建议 A：与 Qwen Work 已消费形态一致，且 bundle 带版本 manifest |
-| P0 | `download_binary.py` 支持 multi 形态同步进 bundled-skills | RewindDesktop `scripts/download_binary.py:103,1366-1432` | 选项 A 下识别 `dingtalk-workspace-bundle.zip` |
-| P0 | 启动同步/技能库支持 bundle 解包与子 skill 注册 | RewindDesktop `tauri-app/src-tauri/src/skills/startup.rs:486-554` | 含旧 mono skill 的迁移清理（现有 `cleanup_removed_bundled_skills` 可复用语义） |
-| P0 | 灰度自更新支持 multi（单 skill upsert → 多 skill 对账） | RewindDesktop `.../dws_update.rs:440-545` | 否则运行时更新会把 multi 打回 mono |
-| P1 | 正式发版 target 切 multi（`real-platform` 改打/加打 bundle，或改用 `bundle-platform`/`package-dual`） | dws-wukong `Makefile` | 打包能力已在 develop，缺的是设为默认 + release skill 文档同步更新 |
-| P1 | 端内灰度选择逻辑落地（双包二选一/T4b，或确认直接全量切） | RewindDesktop（未找到现有实现） | 若选选项 C 过渡则必须 |
-| P1 | 两套 multi 树的内容同源策略：dws-wukong `dingtalk-skills/`（12 产品）vs DWS `skills/multi/`（19 产品） | dws-wukong + 本仓 | **MOOT（2026-08-05）**：悟空线下线，无需统一；原备注：至少明确"悟空子集"契约与同步 SOP 的归属；7 个缺失产品（dev/event/hrbrain/markdown/pat/profile/skill）是否需要进悟空 |
-| P2 | `replace-wukong-skill.sh` 等运维脚本支持 bundle 形态 | dws-wukong `scripts/deploy/` | 当前只在特性分支且只处理单 zip |
-| P2 | 悟空侧公告：端内 `dws skill setup` 行为随上游 embed 变化 | dws-wukong 发版流程 | 对应 §6.1 影响点 1 |
-| P2 | 判据 #3 验收清单（§6.3）写入 DWS roadmap 并跟踪 | 本仓 `docs/skill-multi-roadmap.md` | 阶段 3 期间启动 |
-
-### 7.2 待确认问题（本地无法闭环，需找人/仓库确认）
-
-| # | 问题 | 建议确认方 |
-|---|---|---|
-| 1 | pod 线上当前 `dws_res_mac/win` 的版本与内部构成（是否已有人发过双包） | pod.alibaba-inc.com（需内网 SSO）/ 悟空发版 owner |
-| 2 | "端内 T4b 二选一"灰度逻辑是否已存在（在哪个仓库/平台），还是仅写在 Makefile 注释里的规划 | RewindDesktop 团队 / 悟空端内灰度平台 owner |
-| 3 | LWP `/r/Adaptor/DwsGrayI/getLatest` 服务端返回的下载 URL 指向何处（pod？另一制品库？），multi 包下发是否需要服务端配合改造 | Adaptor/DwsGrayI 服务端 owner |
-| 4 | Qwen Work Cloud 六平台打包的发布状态与其对 bundle 的消费方式是否可作为悟空端改造的直接参照 | dws-wukong 仓 owner（merge `9eb801e5` 提交者） |
-| 5 | 悟空端内是否允许 `dws-shared` 作为独立 bundled skill 暴露（名称/展示/路由策略），还是应内联进各产品 skill | RewindDesktop 技能库 owner |
-| 6 | dws-wukong `dingtalk-skills/` 与上游 `skills/multi/` 的长期关系：保持派生自本仓 mono，还是改为从上游 multi 同步（**MOOT 2026-08-05**：悟空线下线，无需统一） | dws-wukong + DWS 双侧 owner 联合决策 |
-| 7 | 悟空线切换的目标时间窗（决定 DWS 阶段 4 判据 #3 的最早可满足点）（**MOOT 2026-08-05**：判据 #3 已作废） | 悟空发版 owner |
-
---
-
-*本文所有"已验证"结论均可按 §1 的仓库路径与文中锚点复查；未能本地验证
-的项集中在 §7.2。*
@@ -2193,8 +2193,8 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dws", "SKILL.md")); err != nil {
 		t.Fatal(err)
 	}
-	if output, _, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--skill", "a"); err != nil || !strings.Contains(output, "installed=2") {
-		t.Fatalf("multi setup = %q, %v", output, err)
+	if output, warnings, err := run("--mode", "multi", "--source", multi, "--target", "agents", "--yes", "--skill", "a"); err != nil || !strings.Contains(output, "installed=2") || warnings == "" {
+		t.Fatalf("multi setup = %q / %q, %v", output, warnings, err)
 	}
 	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dws-shared", "SKILL.md")); err != nil {
 		t.Fatal(err)
@@ -2214,11 +2214,8 @@ func TestCrossPlatformCoverageSkillSetupRuntimeCoverage(t *testing.T) {
 			t.Fatalf("invalid setup %#v succeeded", args)
 		}
 	}
-	if _, _, err := run("--mode", "mono", "--source", mono, "--target", "agents", "--yes", "--dry-run"); err != nil {
-		t.Fatalf("mono setup: %v", err)
-	}
-	if output, _, err := run("--source", multi, "--target", "agents", "--yes", "--dry-run"); err != nil || !strings.Contains(output, "mode=multi") {
-		t.Fatalf("default mode should be multi: %q, %v", output, err)
+	if _, _, err := run("--source", mono, "--target", "agents", "--yes", "--dry-run"); err != nil {
+		t.Fatalf("default mono setup: %v", err)
 	}
 }

@@ -2251,7 +2248,7 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 	if _, err := listMultiSkillNames(filepath.Join(t.TempDir(), "missing")); err == nil {
 		t.Fatal("missing multi source succeeded")
 	}
-	if mode, err := resolveSkillSetupMode("", true, io.Discard); err != nil || mode != skillSetupModeMulti {
+	if mode, err := resolveSkillSetupMode("", true, io.Discard); err != nil || mode != skillSetupModeMono {
 		t.Fatalf("default setup mode = %q, %v", mode, err)
 	}
 	if _, err := resolveSkillSetupMode("bad", true, io.Discard); err == nil {
@@ -2294,8 +2291,8 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {
 	_ = agentHomeForMode("base", skillSetupModeMulti)
 	_ = detectExistingAgentHomes(t.TempDir(), skillSetupModeMono)
 	for _, mode := range []string{skillSetupModeMono, skillSetupModeMulti, "bad"} {
-		_, _ = confirmSkillSetup(io.Discard, mode, root, []string{root}, all, false)
-		_, _ = mutualExclusionVictims(root, mode)
+		_, _ = confirmSkillSetup(io.Discard, mode, root, []string{root}, all)
+		_ = mutualExclusionVictims(root, mode)
 	}
 	if isCharDevice(nil) || isInteractiveTerminal() {
 		t.Fatal("test process unexpectedly interactive")
@@ -2303,17 +2300,17 @@ func TestCrossPlatformCoverageSkillSetupPureCoverage(t *testing.T) {

 	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
 	_ = os.MkdirAll(filepath.Join(filepath.Dir(monoDest), "dingtalk-old"), 0o755)
-	_, _ = mutualExclusionVictims(monoDest, skillSetupModeMono)
+	_ = mutualExclusionVictims(monoDest, skillSetupModeMono)
 	multiDest := filepath.Join(t.TempDir(), "agent")
 	_ = os.MkdirAll(filepath.Join(multiDest, "dws"), 0o755)
-	_, _ = mutualExclusionVictims(multiDest, skillSetupModeMulti)
+	_ = mutualExclusionVictims(multiDest, skillSetupModeMulti)
 	cleanupMutualExclusion(monoDest, skillSetupModeMono, io.Discard, io.Discard)
 	cleanupMutualExclusion(multiDest, skillSetupModeMulti, io.Discard, io.Discard)

 	badParent := filepath.Join(t.TempDir(), "file")
 	_ = os.WriteFile(badParent, []byte("x"), 0o600)
 	_, _, _ = installSkillToHomes(root, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard)
-	_, _, _ = installMultiSkillToHomes(root, []string{"missing"}, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard, true)
+	_, _, _ = installMultiSkillToHomes(root, []string{"missing"}, []string{filepath.Join(badParent, "dest")}, io.Discard, io.Discard)
 	if err := copyDir(filepath.Join(root, "missing"), t.TempDir()); err == nil {
 		t.Fatal("copy missing directory succeeded")
 	}
@@ -99,6 +99,7 @@ func newEventCommand() *cobra.Command {
 		RunE:              func(c *cobra.Command, _ []string) error { return c.Help() },
 	}
 	cmd.AddCommand(
+		newEventListenIMCommand(),
 		newEventConsumeCommand(),
 		newEventListCommand(),
 		newEventSchemaCommand(),
@@ -0,0 +1,295 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+
+package app
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
+	"github.com/spf13/cobra"
+)
+
+type listenIMOptions struct {
+	Kind             string
+	Events           []string
+	UserID           string
+	OpenDingTalkID   string
+	UserQuery        string
+	ChatID           string
+	ChatQuery        string
+	QueryCSV         string
+	MaxEvents        int
+	Duration         time.Duration
+	DryRun           bool
+	ControlBaseURL   string
+	StreamTicketMode string
+	StreamTicketURL  string
+	StreamSourceID   string
+}
+
+type listenIMPlan struct {
+	EventKeys       []string
+	UserID          string
+	OpenDingTalkID  string
+	GroupID         string
+	ResolvedTargets []any
+}
+
+type eventTargetReader struct{}
+
+func (eventTargetReader) CallMCPData(product, tool string, params map[string]any) (map[string]any, error) {
+	text, err := helpers.CallMCPReadToolTextOnServer(product, tool, params)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return map[string]any{}, nil
+	}
+	var data map[string]any
+	if err := json.Unmarshal([]byte(text), &data); err != nil {
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err))
+	}
+	return data, nil
+}
+
+var eventListenIMReader = func() targetresolver.Reader { return eventTargetReader{} }
+
+func newEventListenIMCommand() *cobra.Command {
+	var opts listenIMOptions
+	cmd := &cobra.Command{
+		Use:   "+listen-im",
+		Short: "按 IM 意图解析目标并监听一个或多个个人消息事件",
+		Long: "把 @我、指定发送人、指定群、全部单聊或全部群聊等用户意图确定性编译为个人 EventKey，" +
+			"自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期。",
+		Args:              cobra.NoArgs,
+		DisableAutoGenTag: true,
+		RunE: func(c *cobra.Command, _ []string) error {
+			plan, err := compileListenIMPlan(eventListenIMReader(), opts)
+			if err != nil {
+				return fmt.Errorf("event +listen-im: %w", err)
+			}
+			consumeOpts := personalConsumeOptions{
+				EventKey:         firstArg(plan.EventKeys),
+				EventKeys:        plan.EventKeys,
+				Flatten:          true,
+				UserID:           plan.UserID,
+				OpenDingTalkID:   plan.OpenDingTalkID,
+				GroupID:          plan.GroupID,
+				QueryCSV:         opts.QueryCSV,
+				ControlBaseURL:   opts.ControlBaseURL,
+				StreamTicketMode: opts.StreamTicketMode,
+				StreamTicketURL:  opts.StreamTicketURL,
+				StreamSourceID:   opts.StreamSourceID,
+				Common: commonConsumeOptions{
+					FormatRaw: "ndjson",
+					MaxEvents: opts.MaxEvents,
+					Duration:  opts.Duration,
+					DryRun:    opts.DryRun,
+				},
+			}
+			return eventRunPersonalConsume(c, consumeOpts)
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&opts.Kind, "kind", "at-me", "监听意图: at-me|sender|group|all-direct|all-group")
+	f.StringSliceVar(&opts.Events, "events", []string{"message"}, "事件种类: message,reaction,read,recall")
+	f.StringVar(&opts.UserID, "user", "", "指定发送人/单聊对端 userId")
+	f.StringVar(&opts.OpenDingTalkID, "open-dingtalk-id", "", "指定发送人/单聊对端 openDingTalkId")
+	f.StringVar(&opts.UserQuery, "user-query", "", "按姓名/花名唯一解析指定发送人")
+	f.StringVar(&opts.ChatID, "chat-id", "", "指定群 openConversationId")
+	f.StringVar(&opts.ChatQuery, "chat-query", "", "按群名唯一解析指定群")
+	f.StringVar(&opts.QueryCSV, "query", "", "消息文本关键词过滤，逗号分隔；仅 message 事件")
+	f.IntVar(&opts.MaxEvents, "max-events", 0, "收到 N 条后退出 (0 = 不限)")
+	f.DurationVar(&opts.Duration, "duration", 0, "运行时长上限 (Go duration，如 30s/5m；0 = 不限)")
+	f.BoolVar(&opts.DryRun, "dry-run", false, "解析目标并打印订阅计划，不创建订阅或连接 bus")
+	f.StringVar(&opts.ControlBaseURL, "personal-event-base-url", "", "个人事件控制面 base URL；默认由 MCP base 派生 /dws")
+	f.StringVar(&opts.StreamTicketMode, "stream-ticket-mode", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_MODE")), "个人 Stream 建联模式；默认 normal")
+	f.StringVar(&opts.StreamSourceID, "stream-source-id", strings.TrimSpace(os.Getenv("DWS_STREAM_SOURCE_ID")), "个人 Stream sourceId；开源版默认 open")
+	f.StringVar(&opts.StreamTicketURL, "stream-ticket-url", strings.TrimSpace(os.Getenv("DWS_STREAM_TICKET_URL")), "个人 Stream 取票 URL")
+	hideEventInternalFlags(cmd, "personal-event-base-url", "stream-ticket-mode", "stream-source-id", "stream-ticket-url")
+	cli.AnnotateRuntimeFlagEnum(cmd, "kind", "at-me", "sender", "group", "all-direct", "all-group")
+	cli.AnnotateRuntimeFlagEnum(cmd, "events", "message", "reaction", "read", "recall")
+	cli.AnnotateRuntimeConstraints(cmd, cli.RuntimeSchemaConstraints{
+		MutuallyExclusive: [][]string{{"user", "open-dingtalk-id", "user-query", "chat-id", "chat-query"}},
+	})
+	helpers.DeclareLeafMetadata(cmd, helpers.LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "not_required", Idempotency: "non_idempotent",
+		},
+		Contract: helpers.LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "event",
+				Name:           "listen_im",
+				CanonicalPath:  "event.listen_im",
+				CLIPath:        "event +listen-im",
+				PrimaryCLIPath: "event +listen-im",
+			},
+			Description: "把 @我、指定发送人、指定群、全部单聊或全部群聊等用户意图确定性编译为个人 EventKey，自然姓名/群名会先唯一解析，再复用 event consume 的订阅、ready marker、NDJSON、取消、回滚和清理生命周期。",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "composite",
+				Availability: "available",
+				Reason:       "Reviewed IM event facade: it deterministically maps kind/events to public personal EventKeys, resolves one natural user/chat target with the shared typed resolver, then delegates one single- or multi-event invocation to the existing subscription, bus, ready-marker, NDJSON, rollback, cancellation, and cleanup lifecycle.",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按 @我、姓名、群名或全量范围监听一个或多个 IM 消息事件",
+				UseWhen: []string{
+					"已知要监听 @我、指定发送人、指定群、全部单聊或全部群聊的 message/reaction/read/recall 事件时使用；姓名用 --user-query、群名用 --chat-query，CLI 会唯一解析目标并把多个兼容事件合并到一个消费生命周期。",
+				},
+				AvoidWhen: []string{
+					"需要群标题/成员/解散等生命周期事件、显式 EventKey、复用 subscribe_id、Filter DSL、原始 transport envelope 或其它底层 consume 控制时使用 event consume；只查历史消息时使用 chat 查询入口",
+				},
+				Examples: []string{
+					"dws event +listen-im --kind at-me --max-events 1",
+					"dws event +listen-im --kind group --events message,reaction --chat-id <openConversationId> --duration 10m",
+				},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "chat-id", Property: "chatId"},
+				{Name: "chat-query", Property: "chatQuery"},
+				{Name: "dry-run", Property: "dryRun"},
+				{Name: "duration", Property: "duration"},
+				{Name: "events", Property: "events"},
+				{Name: "kind", Property: "kind"},
+				{Name: "max-events", Property: "maxEvents"},
+				{Name: "open-dingtalk-id", Property: "openDingtalkId"},
+				{Name: "query", Property: "query"},
+				{Name: "user", Property: "user"},
+				{Name: "user-query", Property: "userQuery"},
+			},
+		},
+	})
+	return cmd
+}
+
+func compileListenIMPlan(reader targetresolver.Reader, opts listenIMOptions) (listenIMPlan, error) {
+	kind := strings.ToLower(strings.TrimSpace(opts.Kind))
+	if kind == "" {
+		kind = "at-me"
+	}
+	events := uniqueListenIMValues(opts.Events)
+	if len(events) == 0 {
+		return listenIMPlan{}, apperrors.NewValidation("--events 至少包含一个事件种类")
+	}
+	if strings.TrimSpace(opts.QueryCSV) != "" {
+		for _, eventName := range events {
+			if eventName != "message" {
+				return listenIMPlan{}, apperrors.NewValidation("--query 只支持 message 事件")
+			}
+		}
+	}
+
+	plan := listenIMPlan{}
+	var err error
+	switch kind {
+	case "at-me", "all-direct", "all-group":
+		if listenIMTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation(fmt.Sprintf("--kind %s 不接受用户或群目标", kind))
+		}
+	case "sender":
+		if listenIMUserTargetCount(opts) != 1 || listenIMChatTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation("--kind sender 必须且只能指定 --user、--open-dingtalk-id 或 --user-query 之一")
+		}
+		plan.UserID = strings.TrimSpace(opts.UserID)
+		plan.OpenDingTalkID = strings.TrimSpace(opts.OpenDingTalkID)
+		if query := strings.TrimSpace(opts.UserQuery); query != "" {
+			resolved, resolveErr := targetresolver.ResolveUser(reader, query, targetresolver.IdentityAny)
+			if resolveErr != nil {
+				return listenIMPlan{}, resolveErr
+			}
+			plan.ResolvedTargets = append(plan.ResolvedTargets, resolved)
+			plan.UserID = resolved.Selected.UserID
+			if plan.UserID == "" {
+				plan.OpenDingTalkID = resolved.Selected.OpenDingTalkID
+			}
+		}
+	case "group":
+		if listenIMChatTargetCount(opts) != 1 || listenIMUserTargetCount(opts) != 0 {
+			return listenIMPlan{}, apperrors.NewValidation("--kind group 必须且只能指定 --chat-id 或 --chat-query 之一")
+		}
+		plan.GroupID = strings.TrimSpace(opts.ChatID)
+		if query := strings.TrimSpace(opts.ChatQuery); query != "" {
+			resolved, resolveErr := targetresolver.ResolveChat(reader, query)
+			if resolveErr != nil {
+				return listenIMPlan{}, resolveErr
+			}
+			plan.ResolvedTargets = append(plan.ResolvedTargets, resolved)
+			plan.GroupID = resolved.Selected.OpenConversationID
+		}
+	default:
+		return listenIMPlan{}, apperrors.NewValidation("--kind 必须是 at-me、sender、group、all-direct 或 all-group")
+	}
+
+	plan.EventKeys, err = listenIMEventKeys(kind, events)
+	if err != nil {
+		return listenIMPlan{}, err
+	}
+	return plan, nil
+}
+
+func listenIMEventKeys(kind string, events []string) ([]string, error) {
+	mapping := map[string]map[string]string{
+		"at-me":      {"message": personal.EventMention},
+		"sender":     {"message": personal.EventFromUser, "reaction": personal.EventReactionO2O, "read": personal.EventReadO2O, "recall": personal.EventRecallO2O},
+		"group":      {"message": personal.EventInChat, "reaction": personal.EventReactionGroup, "read": personal.EventReadGroup, "recall": personal.EventRecallGroup},
+		"all-direct": {"message": personal.EventAllSingleChat},
+		"all-group":  {"message": personal.EventAllGroupChat},
+	}
+	byEvent := mapping[kind]
+	keys := make([]string, 0, len(events))
+	for _, eventName := range events {
+		key := byEvent[eventName]
+		if key == "" {
+			return nil, apperrors.NewValidation(fmt.Sprintf("--kind %s 不支持 event %s", kind, eventName))
+		}
+		keys = append(keys, key)
+	}
+	return keys, nil
+}
+
+func listenIMUserTargetCount(opts listenIMOptions) int {
+	return nonEmptyListenIMCount(opts.UserID, opts.OpenDingTalkID, opts.UserQuery)
+}
+
+func listenIMChatTargetCount(opts listenIMOptions) int {
+	return nonEmptyListenIMCount(opts.ChatID, opts.ChatQuery)
+}
+
+func listenIMTargetCount(opts listenIMOptions) int {
+	return listenIMUserTargetCount(opts) + listenIMChatTargetCount(opts)
+}
+
+func nonEmptyListenIMCount(values ...string) int {
+	count := 0
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			count++
+		}
+	}
+	return count
+}
+
+func uniqueListenIMValues(values []string) []string {
+	out := make([]string, 0, len(values))
+	seen := map[string]bool{}
+	for _, value := range values {
+		value = strings.ToLower(strings.TrimSpace(value))
+		if value == "" || seen[value] {
+			continue
+		}
+		seen[value] = true
+		out = append(out, value)
+	}
+	return out
+}
@@ -0,0 +1,360 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/consume"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/event/personal"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/spf13/cobra"
+)
+
+type listenIMFakeReader struct {
+	responses map[string]map[string]any
+	calls     []string
+}
+
+type listenIMErrorReader struct{ err error }
+
+func (r listenIMErrorReader) CallMCPData(string, string, map[string]any) (map[string]any, error) {
+	return nil, r.err
+}
+
+type listenIMHelperCaller struct {
+	text string
+	err  error
+}
+
+func (c listenIMHelperCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return c.result()
+}
+
+func (c listenIMHelperCaller) CallReadTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return c.result()
+}
+
+func (c listenIMHelperCaller) result() (*edition.ToolResult, error) {
+	if c.err != nil {
+		return nil, c.err
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: c.text}}}, nil
+}
+
+func (listenIMHelperCaller) Format() string { return "json" }
+func (listenIMHelperCaller) DryRun() bool   { return false }
+func (listenIMHelperCaller) Fields() string { return "" }
+func (listenIMHelperCaller) JQ() string     { return "" }
+
+func (f *listenIMFakeReader) CallMCPData(product, tool string, _ map[string]any) (map[string]any, error) {
+	key := product + "/" + tool
+	f.calls = append(f.calls, key)
+	if response, ok := f.responses[key]; ok {
+		return response, nil
+	}
+	return map[string]any{}, nil
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanResolvesGroupAndMapsMultipleEvents(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"im/search_groups": {
+			"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+		},
+	}}
+	plan, err := compileListenIMPlan(reader, listenIMOptions{
+		Kind:      "group",
+		Events:    []string{"message", "reaction", "recall"},
+		ChatQuery: "项目群",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantKeys := []string{personal.EventInChat, personal.EventReactionGroup, personal.EventRecallGroup}
+	if !reflect.DeepEqual(plan.EventKeys, wantKeys) || plan.GroupID != "cid-1" {
+		t.Fatalf("plan = %#v, want keys=%v group=cid-1", plan, wantKeys)
+	}
+	if !reflect.DeepEqual(reader.calls, []string{"im/search_groups"}) {
+		t.Fatalf("resolver calls = %#v", reader.calls)
+	}
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanReturnsStructuredAmbiguityBeforeSubscription(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"contact/search_contact_by_key_word": {
+			"result": []any{
+				map[string]any{"name": "张三", "userId": "u1"},
+				map[string]any{"name": "张三", "userId": "u2"},
+			},
+		},
+	}}
+	_, err := compileListenIMPlan(reader, listenIMOptions{
+		Kind:      "sender",
+		Events:    []string{"message"},
+		UserQuery: "张三",
+	})
+	if err == nil {
+		t.Fatal("ambiguous sender unexpectedly compiled")
+	}
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) || typed.Reason != "resolution_ambiguous" {
+		t.Fatalf("ambiguity error = %#v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventListenIMCommandDelegatesOneCompiledConsumeLifecycle(t *testing.T) {
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"im/search_groups": {
+			"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+		},
+	}}
+	oldReader := eventListenIMReader
+	oldRun := eventRunPersonalConsume
+	t.Cleanup(func() {
+		eventListenIMReader = oldReader
+		eventRunPersonalConsume = oldRun
+	})
+	eventListenIMReader = func() targetresolver.Reader { return reader }
+	var captured personalConsumeOptions
+	var calls int
+	eventRunPersonalConsume = func(_ *cobra.Command, opts personalConsumeOptions) error {
+		calls++
+		captured = opts
+		return nil
+	}
+
+	cmd := newEventListenIMCommand()
+	cmd.SetArgs([]string{
+		"--kind", "group",
+		"--events", "message,reaction",
+		"--chat-query", "项目群",
+		"--max-events", "2",
+		"--duration", "30s",
+		"--dry-run",
+	})
+	if err := cmd.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 {
+		t.Fatalf("consume lifecycle calls = %d, want 1", calls)
+	}
+	if !reflect.DeepEqual(captured.EventKeys, []string{personal.EventInChat, personal.EventReactionGroup}) ||
+		captured.GroupID != "cid-1" || !captured.Flatten || !captured.Common.DryRun ||
+		captured.Common.MaxEvents != 2 || captured.Common.Duration.String() != "30s" {
+		t.Fatalf("captured options = %#v", captured)
+	}
+}
+
+func TestCrossPlatformCoverageCompileListenIMPlanRejectsIncompatibleKindAndTargets(t *testing.T) {
+	reader := &listenIMFakeReader{}
+	cases := []listenIMOptions{
+		{Kind: "at-me", Events: []string{"reaction"}},
+		{Kind: "all-group", Events: []string{"message"}, ChatID: "cid"},
+		{Kind: "sender", Events: []string{"message"}},
+		{Kind: "group", Events: []string{"message"}, ChatID: "cid", ChatQuery: "群"},
+		{Kind: "group", Events: []string{"message", "reaction"}, ChatID: "cid", QueryCSV: "关键词"},
+	}
+	for _, opts := range cases {
+		if _, err := compileListenIMPlan(reader, opts); err == nil {
+			t.Errorf("options unexpectedly accepted: %#v", opts)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageListenIMCompletionBranches(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		text string
+		err  error
+		ok   bool
+	}{
+		{name: "transport", err: errors.New("transport")},
+		{name: "empty", text: "  ", ok: true},
+		{name: "invalid json", text: "{invalid"},
+		{name: "valid", text: `{"result":{"ok":true}}`, ok: true},
+	} {
+		t.Run("reader "+tc.name, func(t *testing.T) {
+			helpers.InitDeps(listenIMHelperCaller{text: tc.text, err: tc.err})
+			data, err := (eventTargetReader{}).CallMCPData("im", "search_groups", nil)
+			if (err == nil) != tc.ok {
+				t.Fatalf("data=%#v error=%v ok=%v", data, err, tc.ok)
+			}
+		})
+	}
+
+	if plan, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Events: []string{" MESSAGE ", "message"}}); err != nil || len(plan.EventKeys) != 1 {
+		t.Fatalf("default/deduplicated plan = %#v, %v", plan, err)
+	}
+	if _, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Kind: "at-me"}); err == nil {
+		t.Fatal("empty event set unexpectedly accepted")
+	}
+	if _, err := compileListenIMPlan(&listenIMFakeReader{}, listenIMOptions{Kind: "unknown", Events: []string{"message"}}); err == nil {
+		t.Fatal("unknown kind unexpectedly accepted")
+	}
+
+	reader := &listenIMFakeReader{responses: map[string]map[string]any{
+		"contact/search_contact_by_key_word": {
+			"result": []any{map[string]any{"name": "甲", "openDingTalkId": "D-user"}},
+		},
+	}}
+	plan, err := compileListenIMPlan(reader, listenIMOptions{Kind: "sender", Events: []string{"message"}, UserQuery: "甲"})
+	if err != nil || plan.UserID != "" || plan.OpenDingTalkID != "D-user" {
+		t.Fatalf("open-id sender plan = %#v, %v", plan, err)
+	}
+	wantErr := errors.New("resolution failed")
+	if _, err := compileListenIMPlan(listenIMErrorReader{err: wantErr}, listenIMOptions{Kind: "sender", Events: []string{"message"}, UserQuery: "甲"}); !errors.Is(err, wantErr) {
+		t.Fatalf("sender resolution error = %v", err)
+	}
+	if _, err := compileListenIMPlan(listenIMErrorReader{err: wantErr}, listenIMOptions{Kind: "group", Events: []string{"message"}, ChatQuery: "群"}); !errors.Is(err, wantErr) {
+		t.Fatalf("group resolution error = %v", err)
+	}
+
+	cmd := newEventListenIMCommand()
+	cmd.SilenceUsage = true
+	cmd.SilenceErrors = true
+	cmd.SetArgs([]string{"--kind", "sender"})
+	if err := cmd.Execute(); err == nil || !strings.Contains(err.Error(), "event +listen-im") {
+		t.Fatalf("command compile error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageEventListenIME2ELifecycleCleansAndRollsBack(t *testing.T) {
+	newReader := func() *listenIMFakeReader {
+		return &listenIMFakeReader{responses: map[string]map[string]any{
+			"im/search_groups": {
+				"result": []any{map[string]any{"title": "项目群", "openConversationId": "cid-1"}},
+			},
+		}}
+	}
+	installFacade := func(t *testing.T, reader *listenIMFakeReader) {
+		t.Helper()
+		oldReader := eventListenIMReader
+		oldRun := eventRunPersonalConsume
+		t.Cleanup(func() {
+			eventListenIMReader = oldReader
+			eventRunPersonalConsume = oldRun
+		})
+		eventListenIMReader = func() targetresolver.Reader { return reader }
+		eventRunPersonalConsume = runPersonalEventConsume
+	}
+	installLifecycle := func(t *testing.T) {
+		t.Helper()
+		restore := installPersonalManySeams(t)
+		t.Cleanup(restore)
+		t.Setenv("DWS_CONFIG_DIR", t.TempDir())
+		personalResolveEventIdentity = func(context.Context, string, string) (personal.Identity, error) {
+			return personal.Identity{
+				AccessToken: "token", CorpID: "corp", UserID: "user",
+				ClientID: "client", SourceID: "open",
+			}, nil
+		}
+		personalUpsertRunState = func(string, personal.RunState) error { return nil }
+		personalValidateConsumeConfig = func(consume.Config) error { return nil }
+		personalValidateNoOutputConflict = func(consume.Config, string) error { return nil }
+	}
+
+	t.Run("ready then clean every created subscription", func(t *testing.T) {
+		reader := newReader()
+		installFacade(t, reader)
+		installLifecycle(t)
+		var created, deleted, removed []string
+		personalEnsureSubscription = func(_ context.Context, _ *personal.Client, _ personal.Identity, opts personalConsumeOptions) (*personal.Subscription, string, string, error) {
+			created = append(created, opts.EventKey)
+			return &personal.Subscription{SubscribeID: "sub-" + opts.EventKey}, opts.EventKey, "group", nil
+		}
+		personalDeleteSubscription = func(_ *personal.Client, _ context.Context, id string) error {
+			deleted = append(deleted, id)
+			return nil
+		}
+		personalRemoveRunStates = func(_ string, ids []string) error {
+			removed = append(removed, ids...)
+			return nil
+		}
+		personalConsumeRunMany = func(_ context.Context, cfg consume.Config, specs []consume.ConsumerSpec) error {
+			if len(specs) != 2 || !cfg.Flatten {
+				t.Fatalf("consume specs/config = %#v / %#v", specs, cfg)
+			}
+			fmt.Fprintf(cfg.Stderr, "[event] ready event_count=%d bus_pid=123\n", len(specs))
+			return nil
+		}
+
+		cmd := newEventListenIMCommand()
+		var stderr bytes.Buffer
+		cmd.SetErr(&stderr)
+		cmd.SetArgs([]string{
+			"--kind", "group", "--events", "message,reaction",
+			"--chat-query", "项目群", "--max-events", "1",
+		})
+		if err := cmd.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		wantEvents := []string{personal.EventInChat, personal.EventReactionGroup}
+		if !reflect.DeepEqual(created, wantEvents) {
+			t.Fatalf("created = %#v, want %#v", created, wantEvents)
+		}
+		wantDeleted := []string{"sub-" + personal.EventReactionGroup, "sub-" + personal.EventInChat}
+		if !reflect.DeepEqual(deleted, wantDeleted) || !reflect.DeepEqual(removed, wantDeleted) {
+			t.Fatalf("deleted=%#v removed=%#v want=%#v", deleted, removed, wantDeleted)
+		}
+		if !strings.Contains(stderr.String(), "[event] ready event_count=2") {
+			t.Fatalf("missing ready marker: %s", stderr.String())
+		}
+		if !reflect.DeepEqual(reader.calls, []string{"im/search_groups"}) {
+			t.Fatalf("resolver calls = %#v", reader.calls)
+		}
+	})
+
+	t.Run("second create failure rolls back first without starting consumer", func(t *testing.T) {
+		reader := newReader()
+		installFacade(t, reader)
+		installLifecycle(t)
+		wantErr := errors.New("second subscription failed")
+		calls := 0
+		personalEnsureSubscription = func(_ context.Context, _ *personal.Client, _ personal.Identity, opts personalConsumeOptions) (*personal.Subscription, string, string, error) {
+			calls++
+			if calls == 2 {
+				return nil, "", "", wantErr
+			}
+			return &personal.Subscription{SubscribeID: "sub-first"}, opts.EventKey, "group", nil
+		}
+		var deleted, removed []string
+		personalDeleteSubscription = func(_ *personal.Client, _ context.Context, id string) error {
+			deleted = append(deleted, id)
+			return nil
+		}
+		personalRemoveRunStates = func(_ string, ids []string) error {
+			removed = append(removed, ids...)
+			return nil
+		}
+		personalConsumeRunMany = func(context.Context, consume.Config, []consume.ConsumerSpec) error {
+			t.Fatal("consumer started after partial subscription failure")
+			return nil
+		}
+
+		cmd := newEventListenIMCommand()
+		var stderr bytes.Buffer
+		cmd.SetErr(&stderr)
+		cmd.SilenceUsage = true
+		cmd.SetArgs([]string{
+			"--kind", "group", "--events", "message,reaction",
+			"--chat-query", "项目群",
+		})
+		err := cmd.Execute()
+		if err == nil || !strings.Contains(err.Error(), wantErr.Error()) {
+			t.Fatalf("error = %v, want %v", err, wantErr)
+		}
+		if !reflect.DeepEqual(deleted, []string{"sub-first"}) || !reflect.DeepEqual(removed, []string{"sub-first"}) {
+			t.Fatalf("rollback deleted=%#v removed=%#v", deleted, removed)
+		}
+	})
+}
@@ -10,7 +10,7 @@ import (
 	"github.com/spf13/cobra"
 )

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

-func TestPluginCannotReplaceBuiltInEventCommand(t *testing.T) {
+func TestCrossPlatformCoveragePluginCannotReplaceBuiltInEventCommand(t *testing.T) {
 	root := &cobra.Command{Use: "dws"}
 	builtIn := newEventCommand()
 	root.AddCommand(builtIn)
@@ -27,9 +27,11 @@ import (
 	"github.com/spf13/cobra"
 )

-func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller, loadUserShortcuts bool) []*cobra.Command {
-	injectStaticServers()
-	helpers.InitDeps(caller)
+// mountLegacyPublicCommands builds the product + shortcut command tree without
+// mutating process-global MCP deps or dynamic server endpoints. Used by the
+// Schema source root (declaration-only) path so assembly cannot clobber a live
+// runtime's InitDeps caller or plugin endpoints.
+func mountLegacyPublicCommands(runner executor.Runner, loadUserShortcuts bool) []*cobra.Command {
 	commands := helpers.NewPublicCommands(runner)
 	// Load user-defined shortcuts (~/.dws/shortcuts/*.yaml) BEFORE compiling the
 	// command tree, so distilled high-frequency operations mount alongside the
@@ -51,6 +53,14 @@ func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller,
 	return mergeTopLevelCommands(commands)
 }

+// newLegacyPublicCommands is the executable CLI path: inject static MCP
+// endpoints, InitDeps, then mount the public command tree.
+func newLegacyPublicCommands(runner executor.Runner, caller edition.ToolCaller, loadUserShortcuts bool) []*cobra.Command {
+	injectStaticServers()
+	helpers.InitDeps(caller)
+	return mountLegacyPublicCommands(runner, loadUserShortcuts)
+}
+
 func injectStaticServers() {
 	hooks := edition.Get()
 	var servers []edition.ServerInfo
@@ -58,7 +58,7 @@ func TestP1SharedAlwaysIncludedWithSkillFilter(t *testing.T) {
 	// Actually install with the filtered+mandatory set and assert dws-shared landed.
 	dest := t.TempDir()
 	var out, errOut bytes.Buffer
-	if _, _, err := installMultiSkillToHomes(src, final, []string{dest}, &out, &errOut, true); err != nil {
+	if _, _, err := installMultiSkillToHomes(src, final, []string{dest}, &out, &errOut); err != nil {
 		t.Fatalf("install: %v (%s)", err, errOut.String())
 	}
 	if _, err := os.Stat(filepath.Join(dest, "dws-shared", "SKILL.md")); err != nil {
@@ -29,6 +29,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"attendance check result":                  {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"attendance +check-result":                 {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"calendar event list":                      {"calendar", "event", "list", "--start", "2026-03-10T14:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
+	"chat +chat-messages":                      {"chat", "+chat-messages", "--group", "fixture-conversation"},
 	"chat +bot-find":                           {"chat", "+bot-find", "--query", "fixture", "--limit", "7"},
 	"chat +bot-search":                         {"chat", "+bot-search", "--name", "Fixture Bot", "--page", "2", "--size", "7"},
 	"chat +category-create":                    {"chat", "+category-create", "--title", "Fixture Cat", "--yes"},
@@ -37,6 +38,7 @@ var paramAliasCompleteCommands = map[string][]string{
 	"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-send-by-webhook":           {"chat", "+messages-send-by-webhook", "--token", "fixture-token", "--title", "Fixture Alert", "--text", "fixture", "--at-users", "user-1,user-2", "--yes"},
+	"chat +search-msg":                         {"chat", "+search-msg", "--group", "fixture-conversation", "--query", "fixture", "--start", "2026-03-10T00:00:00+08:00", "--end", "2026-03-11T00:00:00+08:00", "--no-enrich"},
 	"chat +send-to-group":                      {"chat", "+send-to-group", "--group", "Fixture Group", "--text", "hello fixture", "--yes"},
 	"chat +unread-chats":                       {"chat", "+unread-chats", "--count", "7", "--exclude-muted"},
 	"chat bot find":                            {"chat", "bot", "find", "--query", "fixture", "--limit", "7"},
@@ -119,6 +121,7 @@ var paramAliasNewIMCases = []struct {
 	emitted   string
 	canonical string
 }{
+	{command: "chat +chat-messages", emitted: "chat", canonical: "group"},
 	{command: "chat +bot-find", emitted: "name", canonical: "query"},
 	{command: "chat bot find", emitted: "name", canonical: "query"},
 	{command: "chat +bot-search", emitted: "query", canonical: "name"},
@@ -129,6 +132,7 @@ var paramAliasNewIMCases = []struct {
 	{command: "chat +messages-list-unread-conversations", emitted: "limit", canonical: "count"},
 	{command: "chat +messages-list-unread-conversations", emitted: "size", canonical: "count"},
 	{command: "chat +messages-send-by-webhook", emitted: "at-user-ids", canonical: "at-users"},
+	{command: "chat +search-msg", emitted: "chat", canonical: "group"},
 	{command: "chat +unread-chats", emitted: "limit", canonical: "count"},
 	{command: "chat +unread-chats", emitted: "size", canonical: "count"},
 	{command: "chat bot search", emitted: "query", canonical: "name"},
@@ -169,7 +173,7 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("report list", "from-date"):              true, // date-range concept alias
 }

-func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
+func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
 	concepts, err := cli.LoadParamConcepts()
 	if err != nil {
 		t.Fatalf("LoadParamConcepts() error = %v", err)
@@ -220,6 +224,7 @@ func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads
 			if ctx == nil {
 				t.Fatal("complete alias command skipped PreParse")
 			}
+			normalizeParamAliasVolatileDefaults(fixture.Command, canonicalCaller, aliasCaller)
 			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
 				t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
 			}
@@ -252,7 +257,7 @@ func TestReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads
 	}
 }

-func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
+func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 	activeAliases := 0
 	for _, test := range paramAliasNewIMCases {
 		test := test
@@ -292,6 +297,7 @@ func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 			if ctx == nil {
 				t.Fatal("complete alias command skipped PreParse")
 			}
+			normalizeParamAliasVolatileDefaults(test.command, canonicalCaller, aliasCaller)
 			if !reflect.DeepEqual(aliasCaller.calls, canonicalCaller.calls) {
 				t.Fatalf("final transport calls differ\ncanonical args: %v\nalias args: %v\ncanonical calls: %#v\nalias calls: %#v", canonicalArgs, aliasArgs, canonicalCaller.calls, aliasCaller.calls)
 			}
@@ -302,6 +308,23 @@ func TestNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 	}
 }

+// +chat-messages supplies the current wall-clock time when callers omit
+// --time. Alias equivalence concerns the resolved target and transport shape;
+// a suite crossing a second boundary must not make that default appear
+// alias-dependent.
+func normalizeParamAliasVolatileDefaults(command string, callers ...*paramAliasCaptureCaller) {
+	if command != "chat +chat-messages" {
+		return
+	}
+	for _, caller := range callers {
+		for i := range caller.calls {
+			if caller.calls[i].tool == "list_conversation_message_v2" || caller.calls[i].tool == "list_individual_chat_message" {
+				delete(caller.calls[i].args, "time")
+			}
+		}
+	}
+}
+
 func paramAliasCompleteCommand(command, canonical string) ([]string, bool) {
 	complete, ok := paramAliasCompleteCommands[command]
 	if variants := paramAliasCompleteCommandVariants[command]; variants != nil {
@@ -374,19 +374,21 @@ func NewRootCommand(ctx ...context.Context) *cobra.Command {
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
-	return newRootCommandWithEngine(rootCtx, nil, true)
+	return newRootCommandWithEngine(rootCtx, nil, true, false)
 }

 // NewSchemaSourceRootCommand constructs the distribution-owned command tree
 // used as the Schema assembly source root (RegisterSchemaSourceRoot →
 // ResolveSchemaBuild) and by command-surface policy. Installed plugins and
 // user-defined shortcuts must not change the reviewed Schema surface.
+// declarationOnly skips injectStaticServers / helpers.InitDeps so Schema
+// assembly cannot clobber a live process's ToolCaller or plugin endpoints.
 func NewSchemaSourceRootCommand(ctx ...context.Context) *cobra.Command {
 	var rootCtx context.Context
 	if len(ctx) > 0 && ctx[0] != nil {
 		rootCtx = ctx[0]
 	}
-	return newRootCommandWithEngine(rootCtx, nil, false)
+	return newRootCommandWithEngine(rootCtx, nil, false, true)
 }

 // NewRootCommandWithEngine constructs the root CLI command with an
@@ -394,10 +396,10 @@ func NewSchemaSourceRootCommand(ctx ...context.Context) *cobra.Command {
 // no pipeline processing is applied.
 func NewRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine) *cobra.Command {
 	registerSchemaRuntimeDelivery()
-	return newRootCommandWithEngine(rootCtx, engine, true)
+	return newRootCommandWithEngine(rootCtx, engine, true, false)
 }

-func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool) *cobra.Command {
+func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine, loadRuntimeExtensions bool, declarationOnly bool) *cobra.Command {
 	if rootCtx == nil {
 		rootCtx = context.Background()
 	}
@@ -488,7 +490,14 @@ func newRootCommandWithEngine(rootCtx context.Context, engine *pipeline.Engine,
 	}
 	root.AddCommand(utilityCommands...)

-	root.AddCommand(newLegacyPublicCommands(runner, patCaller, loadRuntimeExtensions)...)
+	if declarationOnly {
+		// Schema / surface assembly: mount the reviewed tree only. Do not
+		// injectStaticServers or InitDeps — those mutate process globals and
+		// would clobber a live runtime's caller and plugin endpoints.
+		root.AddCommand(mountLegacyPublicCommands(runner, loadRuntimeExtensions)...)
+	} else {
+		root.AddCommand(newLegacyPublicCommands(runner, patCaller, loadRuntimeExtensions)...)
+	}

 	// PAT authorization commands (open-source core)
 	pat.RegisterCommands(root, patCaller)
@@ -163,9 +163,16 @@ func commandShort(cmd *cobra.Command) string {

 // resolveVisibleProducts returns the set of top-level product IDs that should
 // be treated as visible. It unions the edition's VisibleProducts hook (when
-// set) with DirectRuntimeProductIDs(), so dynamically-registered products —
-// including plugins loaded via AppendDynamicServer — are never silently hidden
-// by a static VisibleProducts list.
+// set), StaticServers product IDs, and DirectRuntimeProductIDs(), so
+// dynamically-registered products — including plugins loaded via
+// AppendDynamicServer — are never silently hidden by a static VisibleProducts
+// list.
+//
+// StaticServers are consulted directly (without injectStaticServers) so the
+// declaration-only Schema source root can keep reviewed products visible
+// without mutating the process-global dynamic endpoint registry.
+// SupplementServers stay out of this set: they are helper-only endpoints and
+// must not synthesize top-level product visibility.
 func resolveVisibleProducts() map[string]bool {
 	allowed := map[string]bool{}
 	if fn := edition.Get().VisibleProducts; fn != nil {
@@ -173,6 +180,13 @@ func resolveVisibleProducts() map[string]bool {
 			allowed[p] = true
 		}
 	}
+	if fn := edition.Get().StaticServers; fn != nil {
+		for _, server := range fn() {
+			if id := strings.TrimSpace(server.ID); id != "" {
+				allowed[id] = true
+			}
+		}
+	}
 	for id := range DirectRuntimeProductIDs() {
 		allowed[id] = true
 	}
@@ -413,6 +413,33 @@ func multiProfileErrorPayload(err error) map[string]any {
 		if typed.Operation != "" {
 			payload["operation"] = typed.Operation
 		}
+		if typed.Origin != "" {
+			payload["origin"] = typed.Origin
+		}
+		if typed.FailureStage != "" {
+			payload["stage"] = typed.FailureStage
+		}
+		if typed.ExecutionStarted != nil {
+			payload["execution_started"] = *typed.ExecutionStarted
+		}
+		if typed.RetryableSet {
+			payload["retryable"] = typed.Retryable
+		}
+		if typed.Hint != "" {
+			payload["hint"] = typed.Hint
+		}
+		if len(typed.Actions) > 0 {
+			payload["actions"] = append([]string(nil), typed.Actions...)
+		}
+		if len(typed.Details) > 0 {
+			payload["details"] = typed.Details
+		}
+		if typed.ServerDiag.TraceID != "" {
+			payload["trace_id"] = typed.ServerDiag.TraceID
+		}
+		if typed.ServerDiag.ServerErrorCode != "" {
+			payload["server_error_code"] = typed.ServerDiag.ServerErrorCode
+		}
 		if code := typed.ExitCode(); code != 0 {
 			payload["exitCode"] = code
 		}
@@ -678,7 +705,6 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,

 	if callResult.IsError {
 		diag := transport.ExtractServerDiagnosticsFromMap(callResult.Content)
-		logBusinessError(r.transport.FileLogger, "mcp_tool_error", invocation, callResult.Content, diag)

 		// ClassifyToolResult hook: let the overlay intercept known error
 		// patterns (PAT permission, gateway-auth) before generic handling.
@@ -695,14 +721,14 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,
 			}
 		}

-		mcpErr := apperrors.NewAPI(
+		mcpErr := newServerFailureAPIError(
 			extractMCPErrorMessage(callResult),
-			apperrors.WithOperation("tools/call"),
-			apperrors.WithReason("mcp_tool_error"),
-			apperrors.WithServerKey(invocation.CanonicalProduct),
-			apperrors.WithHint("MCP tool returned a business error; check tool parameters and refer to skill documentation."),
-			apperrors.WithServerDiag(diag),
+			"mcp_tool_error",
+			"MCP tool returned a business error; check tool parameters and refer to skill documentation.",
+			invocation.CanonicalProduct,
+			diag,
 		)
+		logBusinessError(r.transport.FileLogger, serverFailureReason(mcpErr, "mcp_tool_error"), invocation, callResult.Content, diag)
 		// PAT scope error in business response: offer human-readable output and retry
 		if isPatScopeError(mcpErr) {
 			scopeErr := extractPatScopeError(mcpErr)
@@ -720,14 +746,15 @@ func (r *runtimeRunner) executeInvocation(ctx context.Context, endpoint string,

 	if bizErr := detectBusinessError(callResult.Content); bizErr != "" {
 		diag := transport.ExtractServerDiagnosticsFromMap(callResult.Content)
-		logBusinessError(r.transport.FileLogger, "business_error", invocation, callResult.Content, diag)
-		return executor.Result{}, apperrors.NewAPI(bizErr,
-			apperrors.WithOperation("tools/call"),
-			apperrors.WithReason("business_error"),
-			apperrors.WithServerKey(invocation.CanonicalProduct),
-			apperrors.WithHint("The API returned a business-level error. Check required parameters and values."),
-			apperrors.WithServerDiag(diag),
+		classifiedErr := newServerFailureAPIError(
+			bizErr,
+			"business_error",
+			"The API returned a business-level error. Check required parameters and values.",
+			invocation.CanonicalProduct,
+			diag,
 		)
+		logBusinessError(r.transport.FileLogger, serverFailureReason(classifiedErr, "business_error"), invocation, callResult.Content, diag)
+		return executor.Result{}, classifiedErr
 	}

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

 func TestDeliverySchemaCoversOrExactlyExcludesEveryPublicShortcutContract(t *testing.T) {
@@ -114,7 +114,7 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)

 	product := executeShortcutSchemaQuery(t, "chat")
 	productPayload, _ := product["product"].(map[string]any)
-	if got, want := int(product["count"].(float64)), 129; got != want {
+	if got, want := int(product["count"].(float64)), 180; got != want {
 		t.Fatalf("schema chat count = %d, want %d", got, want)
 	}
 	summaries := schemaContractObjectSlice(productPayload["tools"])
@@ -124,8 +124,8 @@ func TestDeliveryShortcutProgressiveQueriesReturnCompleteContracts(t *testing.T)
 			shortcutCount++
 		}
 	}
-	if shortcutCount != 47 {
-		t.Fatalf("schema chat shortcut summaries = %d, want 47", shortcutCount)
+	if shortcutCount != 98 {
+		t.Fatalf("schema chat shortcut summaries = %d, want 98", shortcutCount)
 	}
 }

@@ -0,0 +1,163 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/cli"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/mcptypes"
+	"github.com/spf13/cobra"
+)
+
+// schemaSourceRootMarkerCaller is a recognizable ToolCaller used to detect
+// InitDeps clobbering when NewSchemaSourceRootCommand builds the tree.
+type schemaSourceRootMarkerCaller struct{}
+
+func (schemaSourceRootMarkerCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return &edition.ToolResult{}, nil
+}
+func (schemaSourceRootMarkerCaller) Format() string { return "json" }
+func (schemaSourceRootMarkerCaller) DryRun() bool   { return false }
+func (schemaSourceRootMarkerCaller) Fields() string { return "" }
+func (schemaSourceRootMarkerCaller) JQ() string     { return "" }
+
+// TestSchemaSourceRootPreservesRuntimeDepsAndPluginEndpoints ensures Schema
+// assembly (NewSchemaSourceRootCommand / ResolveMeta delivery) does not call
+// helpers.InitDeps or SetDynamicServers, which would wipe a live process's
+// caller and plugin endpoints.
+func TestSchemaSourceRootPreservesRuntimeDepsAndPluginEndpoints(t *testing.T) {
+	const (
+		pluginID       = "schema-source-root-plugin-marker"
+		pluginEndpoint = "https://schema-source-root-plugin.example/mcp"
+	)
+
+	dynamicMu.RLock()
+	previousEndpoints := dynamicEndpoints
+	previousProducts := dynamicProducts
+	previousAliases := dynamicAliases
+	previousToolEndpoints := dynamicToolEndpoints
+	dynamicMu.RUnlock()
+	t.Cleanup(func() {
+		dynamicMu.Lock()
+		dynamicEndpoints = previousEndpoints
+		dynamicProducts = previousProducts
+		dynamicAliases = previousAliases
+		dynamicToolEndpoints = previousToolEndpoints
+		dynamicMu.Unlock()
+	})
+
+	marker := schemaSourceRootMarkerCaller{}
+	helpers.InitDepsForTest(t, marker)
+	SetDynamicServers(nil)
+	AppendDynamicServer(mcptypes.ServerDescriptor{
+		Key:      pluginID,
+		Endpoint: pluginEndpoint,
+		CLI: mcptypes.CLIOverlay{
+			ID:      pluginID,
+			Command: pluginID,
+		},
+	})
+
+	root := NewSchemaSourceRootCommand()
+	if root == nil {
+		t.Fatal("NewSchemaSourceRootCommand returned nil")
+	}
+
+	if got := helpers.GetCaller(); got != marker {
+		t.Fatalf("helpers.GetCaller() after NewSchemaSourceRootCommand = %T (%p), want marker caller preserved", got, got)
+	}
+	gotEndpoint, ok := directRuntimeEndpoint(pluginID, "")
+	if !ok || gotEndpoint != pluginEndpoint {
+		t.Fatalf("plugin endpoint after NewSchemaSourceRootCommand = %q ok=%v, want %q preserved", gotEndpoint, ok, pluginEndpoint)
+	}
+
+	resolved, err := cli.ResolveSchemaBuild(root)
+	if err != nil {
+		t.Fatalf("ResolveSchemaBuild after declaration-only root: %v", err)
+	}
+	if resolved.CommandCount() == 0 {
+		t.Fatal("ResolveSchemaBuild command count is 0")
+	}
+
+	// Delivery path also builds NewSchemaSourceRootCommand via the factory.
+	registerSchemaRuntimeDelivery()
+	meta, ok := cli.ResolveMeta("dev app delete")
+	if !ok || meta.Identity.Canonical == "" {
+		t.Fatalf("ResolveMeta after registerSchemaRuntimeDelivery = %#v ok=%v", meta, ok)
+	}
+	if got := helpers.GetCaller(); got != marker {
+		t.Fatalf("helpers.GetCaller() after ResolveMeta delivery = %T, want marker caller preserved", got)
+	}
+	gotEndpoint, ok = directRuntimeEndpoint(pluginID, "")
+	if !ok || gotEndpoint != pluginEndpoint {
+		t.Fatalf("plugin endpoint after ResolveMeta delivery = %q ok=%v, want %q preserved", gotEndpoint, ok, pluginEndpoint)
+	}
+}
+
+// TestCrossPlatformCoverageSchemaSourceRootStaticServerVisibilityWithoutInject
+// proves the declaration-only Schema source root does not need
+// injectStaticServers to keep StaticServers products visible. VisibleProducts
+// may be unset; StaticServers alone must still prevent
+// hideNonDirectRuntimeCommands from marking those products Hidden — without
+// mutating dynamic endpoints.
+func TestCrossPlatformCoverageSchemaSourceRootStaticServerVisibilityWithoutInject(t *testing.T) {
+	previous := edition.Get()
+	t.Cleanup(func() { edition.Override(previous) })
+
+	dynamicMu.RLock()
+	previousEndpoints := dynamicEndpoints
+	previousProducts := dynamicProducts
+	previousAliases := dynamicAliases
+	previousToolEndpoints := dynamicToolEndpoints
+	dynamicMu.RUnlock()
+	t.Cleanup(func() {
+		dynamicMu.Lock()
+		dynamicEndpoints = previousEndpoints
+		dynamicProducts = previousProducts
+		dynamicAliases = previousAliases
+		dynamicToolEndpoints = previousToolEndpoints
+		dynamicMu.Unlock()
+	})
+
+	edition.Override(&edition.Hooks{
+		Name: "schema-source-root-static-visibility",
+		StaticServers: func() []edition.ServerInfo {
+			return []edition.ServerInfo{
+				{ID: "", Name: "ignored-empty", Endpoint: "https://schema-source-root-static.example/empty"},
+				{ID: "  ", Name: "ignored-blank", Endpoint: "https://schema-source-root-static.example/blank"},
+				{ID: "doc", Name: "Doc", Endpoint: "https://schema-source-root-static.example/doc"},
+			}
+		},
+		// VisibleProducts intentionally nil: declaration-only visibility must
+		// still derive from StaticServers without SetDynamicServers.
+	})
+	SetDynamicServers(nil)
+
+	root := NewSchemaSourceRootCommand()
+	var doc *cobra.Command
+	for _, cmd := range root.Commands() {
+		if cmd.Name() == "doc" {
+			doc = cmd
+			break
+		}
+	}
+	if doc == nil {
+		t.Fatal("doc command missing from Schema source root")
+	}
+	if doc.Hidden {
+		t.Fatal("declaration-only Schema source root hid doc despite StaticServers")
+	}
+	// Endpoint resolution may still read StaticServers directly; the invariant
+	// is that declaration-only construction must not mutate the dynamic registry.
+	dynamicMu.RLock()
+	_, injected := dynamicProducts["doc"]
+	dynamicMu.RUnlock()
+	if injected {
+		t.Fatal("declaration-only Schema source root must not inject StaticServers into dynamicProducts")
+	}
+}
@@ -0,0 +1,105 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+type serverFailureClass struct {
+	message string
+	reason  string
+	origin  string
+	stage   string
+	hint    string
+	actions []string
+}
+
+func classifyServerFailure(message string, diag apperrors.ServerDiagnostics) (serverFailureClass, bool) {
+	code := strings.ToUpper(strings.TrimSpace(diag.ServerErrorCode))
+	detail := strings.ToLower(strings.TrimSpace(diag.TechnicalDetail))
+	text := strings.ToLower(strings.TrimSpace(message))
+
+	if code == "NETWORK_ERROR" ||
+		strings.Contains(detail, "statuscode.unavailable") ||
+		strings.Contains(detail, "connection refused") {
+		classified := serverFailureClass{
+			message: "MCP 后端依赖暂时不可用",
+			reason:  "backend_dependency_unavailable",
+			origin:  "mcp_gateway",
+			stage:   "backend_dependency",
+			hint:    "请求参数无需修改；请使用相同参数稍后重试。持续失败时请提供 Trace ID 排查 MCP 服务。",
+			actions: []string{
+				"使用相同参数重试一次",
+				"持续失败时保留 Trace ID 并排查 MCP 后端依赖",
+			},
+		}
+		if strings.Contains(detail, "querytoolmeta") {
+			classified.message = "MCP 后端元数据服务暂时不可用"
+			classified.stage = "tool_metadata_lookup"
+		}
+		return classified, true
+	}
+
+	if code == "PARAM_ERROR" ||
+		strings.Contains(text, "opencid or cid is required") ||
+		strings.Contains(text, "openconversationid") && strings.Contains(text, "required") {
+		return serverFailureClass{
+			message: message,
+			reason:  "invalid_request",
+			origin:  "dingtalk_api",
+			stage:   "tool_validation",
+			hint:    "请求未通过后端参数校验；请核对当前 leaf Help/Schema 和稳定 ID 类型后重试。",
+		}, true
+	}
+
+	return serverFailureClass{}, false
+}
+
+func newServerFailureAPIError(
+	message string,
+	fallbackReason string,
+	fallbackHint string,
+	serverKey string,
+	diag apperrors.ServerDiagnostics,
+) error {
+	opts := []apperrors.Option{
+		apperrors.WithOperation("tools/call"),
+		apperrors.WithReason(fallbackReason),
+		apperrors.WithServerKey(serverKey),
+		apperrors.WithHint(fallbackHint),
+		apperrors.WithServerDiag(diag),
+	}
+	if classified, ok := classifyServerFailure(message, diag); ok {
+		message = classified.message
+		opts = append(opts,
+			apperrors.WithReason(classified.reason),
+			apperrors.WithOrigin(classified.origin),
+			apperrors.WithFailureStage(classified.stage),
+			apperrors.WithHint(classified.hint),
+			apperrors.WithActions(classified.actions...),
+		)
+	}
+	return apperrors.NewAPI(message, opts...)
+}
+
+func serverFailureReason(err error, fallback string) string {
+	typed, ok := err.(*apperrors.Error)
+	if ok && strings.TrimSpace(typed.Reason) != "" {
+		return typed.Reason
+	}
+	return fallback
+}
@@ -0,0 +1,223 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package app
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/executor"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/transport"
+)
+
+func TestCrossPlatformCoverageServerFailureClassifierBackendMetadataUnavailable(t *testing.T) {
+	retryable := true
+	err := newServerFailureAPIError(
+		"business error: success=false",
+		"business_error",
+		"check parameters",
+		"im",
+		apperrors.ServerDiagnostics{
+			TraceID:         "trace-local",
+			ServerErrorCode: "NETWORK_ERROR",
+			TechnicalDetail: "调用 McpService.queryToolMeta 失败: status = StatusCode.UNAVAILABLE; connect: Connection refused (111)",
+			ServerRetryable: &retryable,
+		},
+	)
+
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("error = %T, want *errors.Error", err)
+	}
+	if typed.Reason != "backend_dependency_unavailable" || typed.Origin != "mcp_gateway" || typed.FailureStage != "tool_metadata_lookup" {
+		t.Fatalf("classification = reason %q origin %q stage %q", typed.Reason, typed.Origin, typed.FailureStage)
+	}
+	if typed.ExecutionStarted != nil {
+		t.Fatalf("execution_started = %v, want unknown until the backend publishes it", typed.ExecutionStarted)
+	}
+	if !typed.RetryableSet || !typed.Retryable {
+		t.Fatalf("retryability = (%v, %v), want explicit true", typed.RetryableSet, typed.Retryable)
+	}
+	if strings.Contains(strings.ToLower(typed.Hint), "parameter") || strings.Contains(typed.Hint, "认证") {
+		t.Fatalf("misleading hint = %q", typed.Hint)
+	}
+}
+
+func TestCrossPlatformCoverageServerFailureClassifierRequiredConversationID(t *testing.T) {
+	err := newServerFailureAPIError(
+		"openCid or cid is required",
+		"business_error",
+		"check parameters",
+		"chat",
+		apperrors.ServerDiagnostics{ServerErrorCode: "1001"},
+	)
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("error = %T, want *errors.Error", err)
+	}
+	if typed.Reason != "invalid_request" || typed.FailureStage != "tool_validation" {
+		t.Fatalf("classification = reason %q stage %q", typed.Reason, typed.FailureStage)
+	}
+	if typed.ExecutionStarted != nil {
+		t.Fatalf("execution_started = %v, want unknown until the backend publishes it", typed.ExecutionStarted)
+	}
+}
+
+func TestCrossPlatformCoverageServerFailureClassifierUnknownFallsBack(t *testing.T) {
+	err := newServerFailureAPIError(
+		"business error: success=false",
+		"business_error",
+		"check parameters",
+		"im",
+		apperrors.ServerDiagnostics{},
+	)
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("error = %T, want *errors.Error", err)
+	}
+	if typed.Reason != "business_error" || typed.Origin != "" || typed.FailureStage != "" || typed.ExecutionStarted != nil {
+		t.Fatalf("unexpected fallback classification: %#v", typed)
+	}
+}
+
+func TestCrossPlatformCoverageServerFailureReasonUsesTypedClassification(t *testing.T) {
+	err := newServerFailureAPIError(
+		"business error: success=false",
+		"business_error",
+		"check parameters",
+		"im",
+		apperrors.ServerDiagnostics{ServerErrorCode: "NETWORK_ERROR"},
+	)
+	if got := serverFailureReason(err, "business_error"); got != "backend_dependency_unavailable" {
+		t.Fatalf("reason = %q", got)
+	}
+	if got := serverFailureReason(errors.New("plain"), "fallback"); got != "fallback" {
+		t.Fatalf("fallback reason = %q", got)
+	}
+}
+
+func TestCrossPlatformCoverageMultiProfileErrorPayloadPreservesFailureSemantics(t *testing.T) {
+	retryable := true
+	err := newServerFailureAPIError(
+		"business error: success=false",
+		"business_error",
+		"check parameters",
+		"im",
+		apperrors.ServerDiagnostics{
+			TraceID:         "trace-multi",
+			ServerErrorCode: "NETWORK_ERROR",
+			TechnicalDetail: "McpService.queryToolMeta: StatusCode.UNAVAILABLE",
+			ServerRetryable: &retryable,
+		},
+	)
+	payload := multiProfileErrorPayload(err)
+	for key, want := range map[string]any{
+		"reason":            "backend_dependency_unavailable",
+		"origin":            "mcp_gateway",
+		"stage":             "tool_metadata_lookup",
+		"retryable":         true,
+		"trace_id":          "trace-multi",
+		"server_error_code": "NETWORK_ERROR",
+	} {
+		if got := payload[key]; got != want {
+			t.Errorf("payload[%q] = %#v, want %#v", key, got, want)
+		}
+	}
+	if _, ok := payload["execution_started"]; ok {
+		t.Fatalf("payload must not invent execution_started: %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageMultiProfileErrorPayloadPreservesResolutionDetails(t *testing.T) {
+	err := apperrors.NewValidation(
+		"群目标不唯一",
+		apperrors.WithReason("resolution_ambiguous"),
+		apperrors.WithOrigin("client"),
+		apperrors.WithFailureStage("target_resolution"),
+		apperrors.WithExecutionStarted(false),
+		apperrors.WithHint("请选择候选"),
+		apperrors.WithActions("使用稳定 ID 重试"),
+		apperrors.WithDetails(map[string]any{
+			"type":       "resolution",
+			"candidates": []string{"cid-1", "cid-2"},
+		}),
+	)
+	payload := multiProfileErrorPayload(err)
+	details, ok := payload["details"].(map[string]any)
+	if !ok || details["type"] != "resolution" {
+		t.Fatalf("details = %#v", payload["details"])
+	}
+	if payload["execution_started"] != false || payload["origin"] != "client" || payload["stage"] != "target_resolution" {
+		t.Fatalf("payload = %#v", payload)
+	}
+	if actions, ok := payload["actions"].([]string); !ok || len(actions) != 1 {
+		t.Fatalf("actions = %#v", payload["actions"])
+	}
+}
+
+func TestCrossPlatformCoverageExecuteInvocationClassifiesObservedMCPMetadataFailure(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var request struct {
+			ID int `json:"id"`
+		}
+		if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
+			t.Errorf("decode request: %v", err)
+		}
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"jsonrpc": "2.0",
+			"id":      request.ID,
+			"result": map[string]any{
+				"structuredContent": map[string]any{
+					"success":          false,
+					"code":             "NETWORK_ERROR",
+					"trace_id":         "trace-replay",
+					"technical_detail": "调用 McpService.queryToolMeta 失败: status = StatusCode.UNAVAILABLE; connect: Connection refused (111)",
+					"retryable":        true,
+				},
+			},
+		})
+	}))
+	defer server.Close()
+
+	client := transport.NewClient(server.Client())
+	client.TrustedDomains = []string{strings.TrimPrefix(server.URL, "http://")}
+	runner := &runtimeRunner{
+		transport:   client,
+		globalFlags: &GlobalFlags{Token: "local-test-token"},
+	}
+	_, err := runner.executeInvocation(context.Background(), server.URL, executor.Invocation{
+		CanonicalProduct: "im",
+		Tool:             "list_conversations",
+		Params:           map[string]any{"pageSize": 100},
+	})
+	var typed *apperrors.Error
+	if !errors.As(err, &typed) {
+		t.Fatalf("executeInvocation() error = %T %v, want typed API error", err, err)
+	}
+	if typed.Reason != "backend_dependency_unavailable" || typed.Origin != "mcp_gateway" || typed.FailureStage != "tool_metadata_lookup" {
+		t.Fatalf("classification = reason %q origin %q stage %q", typed.Reason, typed.Origin, typed.FailureStage)
+	}
+	if typed.ServerDiag.TraceID != "trace-replay" || !typed.RetryableSet || !typed.Retryable {
+		t.Fatalf("diagnostics = %#v retryable=(%v,%v)", typed.ServerDiag, typed.RetryableSet, typed.Retryable)
+	}
+	if typed.ExecutionStarted != nil {
+		t.Fatalf("execution_started must remain unknown: %v", typed.ExecutionStarted)
+	}
+}
@@ -75,14 +75,15 @@ func newSkillSetupCommand() *cobra.Command {
 		Long: `安装 dws 自身 skill 文档到 AI Agent 目录（如 ~/.claude/skills/、~/.cursor/skills/ 等）。

 支持两种模式：
-  multi                 多 skill（默认）—— 按产品拆 N 个独立 skill（dingtalk-*）
-  mono                  单 skill（legacy）—— 总入口 SKILL.md + references/products/
+  mono                  单 skill（稳定 / 推荐）—— 总入口 SKILL.md + references/products/
+  multi  🧪 EXPERIMENTAL  多 skill（试验版 / Preview）—— 按产品拆 N 个独立 skill
+                         尚未达到 stable 标准，接口、命名与跨 skill 引用可能变动；
+                         生产前请评估，问题请提 issue 反馈

 multi 模式支持按产品挑选：
  -s/--skill   只装指定子 skill（可重复，短名 aitable 或全名 dingtalk-aitable 均可）
  -x/--exclude 从全装里剔除指定子 skill（可重复，与 --skill 互斥）
-  用 -s/-x 挑选时未列出的已有 dingtalk-* skill 会保留（additive 叠加语义）；
-  不带过滤条件的全量安装会清理不在 bundle 内的过期 dingtalk-* / dws-shared。
+  未列出的已有 dingtalk-* skill 会保留（additive 叠加语义）

 不带 --mode 时进入交互式询问；不带 --target 时铺到所有检测到的 Agent 目录。
 skill 源默认取二进制内嵌的版本（升级二进制即升级 skill）；--source / DWS_SKILL_SOURCE 可显式覆盖。`,
@@ -167,13 +168,8 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 		return nil
 	}

-	// filtered 决定 multi 安装的清理语义：带 -s/--skill 或 -x/--exclude
-	// 时保持 additive（不动未列出的 sibling）；全量安装与 install.sh /
-	// install.js 对齐，清掉不在 bundle 内的过期 dingtalk-* / dws-shared。
-	filtered := len(includeRaw) > 0 || len(excludeRaw) > 0
-
 	if !autoYes {
-		ok, err := skillSetupConfirm(out, mode, skillSrc, dests, multiSkillNames, filtered)
+		ok, err := skillSetupConfirm(out, mode, skillSrc, dests, multiSkillNames)
 		if err != nil {
 			return err
 		}
@@ -181,6 +177,8 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 			fmt.Fprintln(out, "已取消。")
 			return nil
 		}
+	} else if mode == skillSetupModeMulti {
+		fmt.Fprintln(errOut, "🧪 multi 模式当前为 EXPERIMENTAL（试验版 / Preview）—— 接口与布局可能变动，稳定版请用 --mode mono")
 	}

 	var installed, skipped int
@@ -188,7 +186,7 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 	case skillSetupModeMono:
 		installed, skipped, err = skillSetupInstallMono(skillSrc, dests, out, errOut)
 	case skillSetupModeMulti:
-		installed, skipped, err = skillSetupInstallMulti(skillSrc, multiSkillNames, dests, out, errOut, filtered)
+		installed, skipped, err = skillSetupInstallMulti(skillSrc, multiSkillNames, dests, out, errOut)
 	default:
 		return fmt.Errorf("内部错误：未知 mode %q", mode)
 	}
@@ -253,10 +251,10 @@ func normalizeMultiSkillName(name string) string {
 //   - both lists empty → return `all` (install everything)
 //   - exclude that drops every name → error (avoid silent no-op install)
 //
-// The caller threads whether a filter was used into installMultiSkillToHomes:
-// filtered installs stay additive (already-installed dingtalk-* siblings are
-// left untouched); a full unfiltered install also removes stale dingtalk-* /
-// dws-shared directories that are no longer part of the bundle.
+// The caller is responsible for additive installation: install only the
+// returned names, leaving any other already-installed dingtalk-* siblings
+// untouched (handled by installMultiSkillToHomes which does not enumerate
+// the destination).
 func filterMultiSkillNames(all, include, exclude []string) ([]string, error) {
 	if len(include) > 0 && len(exclude) > 0 {
 		return nil, fmt.Errorf("--skill 与 --exclude 不能同时使用")
@@ -358,8 +356,8 @@ func resolveSkillSetupMode(mode string, autoYes bool, out io.Writer) (string, er
 	}

 	if autoYes || !skillSetupInteractive() {
-		fmt.Fprintln(out, "未指定 --mode，非交互环境下默认使用 multi")
-		return skillSetupModeMulti, nil
+		fmt.Fprintln(out, "未指定 --mode，非交互环境下默认使用 mono")
+		return skillSetupModeMono, nil
 	}

 	var choice string
@@ -367,10 +365,10 @@ func resolveSkillSetupMode(mode string, autoYes bool, out io.Writer) (string, er
 		huh.NewGroup(
 			huh.NewSelect[string]().
 				Title("选择 dws skill 安装模式").
-				Description("multi = 按产品拆分（默认）\nmono = 单 skill 入口（legacy）").
+				Description("mono = 单 skill 入口（稳定 / 推荐）\nmulti = 按产品拆分（🧪 EXPERIMENTAL / 试验版，未达 stable，接口可能变动）").
 				Options(
-					huh.NewOption("multi — 多 skill（默认）", skillSetupModeMulti),
-					huh.NewOption("mono — 单 skill（legacy）", skillSetupModeMono),
+					huh.NewOption("mono — 单 skill（稳定 / 推荐）", skillSetupModeMono),
+					huh.NewOption("multi — 多 skill（🧪 EXPERIMENTAL · 试验版）", skillSetupModeMulti),
 				).
 				Value(&choice),
 		),
@@ -382,10 +380,8 @@ func resolveSkillSetupMode(mode string, autoYes bool, out io.Writer) (string, er
 }

 // resolveSkillSetupSource finds the local skill source directory for the
-// given mode ("mono" or "multi"). Explicit overrides (--source flag or
-// DWS_SKILL_SOURCE) win and never fall back to another source; without an
-// override the ordered candidate list (binary-adjacent, working directory,
-// ~/.dws/skills user cache) is probed for a valid skill root of that mode.
+// given mode. PR 1 supports only mono; multi is reserved for a later PR
+// and currently returns an error before reaching this function.
 func resolveSkillSetupSource(explicit, mode string) (string, error) {
 	subdir := mode // "mono" or "multi"

@@ -529,7 +525,16 @@ func detectExistingAgentHomes(home, mode string) []string {
 	return out
 }

-func confirmSkillSetup(out io.Writer, mode, src string, dests []string, multiSkillNames []string, filtered bool) (bool, error) {
+func confirmSkillSetup(out io.Writer, mode, src string, dests []string, multiSkillNames []string) (bool, error) {
+	if mode == skillSetupModeMulti {
+		fmt.Fprintln(out, "\n🧪 ─────────────────────────────────────────────────────────────")
+		fmt.Fprintln(out, "    multi 模式当前为 EXPERIMENTAL（试验版 / Preview）")
+		fmt.Fprintf(out, "    · 当前选择的 %d 个独立 skill 均跑过 verifier，可用但未达 stable\n", len(multiSkillNames))
+		fmt.Fprintln(out, "    · 跨 skill 引用、bundle 命名、目录布局后续可能调整")
+		fmt.Fprintln(out, "    · 不建议在生产 / 共享环境直接落地；问题请提 issue 反馈")
+		fmt.Fprintln(out, "    稳定版请用 --mode mono")
+		fmt.Fprintln(out, "🧪 ─────────────────────────────────────────────────────────────")
+	}
 	fmt.Fprintf(out, "\n📦 将安装 skill：\n  mode: %s\n  source: %s\n", mode, src)
 	if mode == skillSetupModeMulti {
 		fmt.Fprintf(out, "  将装 %d 个独立 skill（按子目录平铺到 <agent-home>/<skill-name>/）：\n", len(multiSkillNames))
@@ -544,21 +549,10 @@ func confirmSkillSetup(out io.Writer, mode, src string, dests []string, multiSki
 	// 列出互斥清理：装 mode 前要把对面 mode 的残留删掉
 	fmt.Fprintln(out, "  互斥清理（确认后才执行）：")
 	for _, d := range dests {
-		victims, _ := mutualExclusionVictims(d, mode) // 预览只读，扫描失败不阻塞确认
-		for _, victim := range victims {
+		for _, victim := range mutualExclusionVictims(d, mode) {
 			fmt.Fprintf(out, "    × 将删除 %s\n", victim)
 		}
 	}
-	// 全量 multi 安装还会清掉不在 bundle 内的过期 dingtalk-* / dws-shared
-	// （removeStaleMultiSkills）；这些删除同样必须先进入确认预览。带
-	// -s/-x 的 filtered 安装是 additive 语义，不会动未列出的 sibling。
-	if mode == skillSetupModeMulti && !filtered {
-		for _, d := range dests {
-			for _, victim := range staleMultiSkillVictims(d, multiSkillNames) {
-				fmt.Fprintf(out, "    × 将删除过期 skill %s\n", victim)
-			}
-		}
-	}

 	if !skillSetupInteractive() {
 		return true, nil
@@ -586,49 +580,38 @@ func confirmSkillSetup(out io.Writer, mode, src string, dests []string, multiSki
 //
 //   - mono dest is <agent-home>/dws  → multi 残留是 <agent-home>/dingtalk-*
 //   - multi dest is <agent-home>     → mono 残留是 <agent-home>/dws
-//
-// A scan failure (e.g. unreadable agent home) is returned as a non-nil error
-// so callers can surface a warning instead of silently skipping cleanup.
-func mutualExclusionVictims(dest, mode string) ([]string, error) {
+func mutualExclusionVictims(dest, mode string) []string {
 	switch mode {
 	case skillSetupModeMono:
 		// dest = <agent-home>/dws → agent-home = parent
 		agentHome := filepath.Dir(dest)
 		entries, err := skillSetupReadDir(agentHome)
 		if err != nil {
-			if errors.Is(err, os.ErrNotExist) {
-				return nil, nil
-			}
-			return nil, fmt.Errorf("扫描 multi 残留失败 %s: %w", agentHome, err)
+			return nil
 		}
 		var victims []string
 		for _, e := range entries {
-			if e.IsDir() && (strings.HasPrefix(e.Name(), multiSkillPrefix) || e.Name() == multiSharedSkill) {
+			if e.IsDir() && strings.HasPrefix(e.Name(), "dingtalk-") {
 				victims = append(victims, filepath.Join(agentHome, e.Name()))
 			}
 		}
 		sort.Strings(victims)
-		return victims, nil
+		return victims
 	case skillSetupModeMulti:
 		// dest = <agent-home> → mono 残留是 dest/dws
 		monoPath := filepath.Join(dest, "dws")
 		if _, err := skillSetupStat(monoPath); err == nil {
-			return []string{monoPath}, nil
+			return []string{monoPath}
 		}
-		return nil, nil
+		return nil
 	}
-	return nil, nil
+	return nil
 }

 // cleanupMutualExclusion best-effort removes the opposite-mode leftovers.
-// Failures — including a failed victim scan — emit a warning to errOut but
-// never abort the install.
+// Failures emit a warning to errOut but never abort the install.
 func cleanupMutualExclusion(dest, mode string, out, errOut io.Writer) {
-	victims, scanErr := mutualExclusionVictims(dest, mode)
-	if scanErr != nil {
-		fmt.Fprintf(errOut, "  ⚠️  互斥清理扫描失败（继续安装） %s: %v\n", dest, scanErr)
-	}
-	for _, victim := range victims {
+	for _, victim := range mutualExclusionVictims(dest, mode) {
 		if err := skillSetupRemoveAll(victim); err != nil {
 			fmt.Fprintf(errOut, "  ⚠️  互斥清理失败（继续安装） %s: %v\n", victim, err)
 			continue
@@ -667,13 +650,7 @@ func installSkillToHomes(src string, dests []string, out, errOut io.Writer) (ins
 // installMultiSkillToHomes installs each subdir of src (dingtalk-*) into
 // dest as a sibling skill directory. installed/skipped is counted per
 // (agent-home × sub-skill) pair so the user sees granular progress.
-//
-// filtered mirrors whether runSkillSetup saw -s/--skill or -x/--exclude:
-// a filtered install stays additive and never touches siblings outside the
-// requested set; a full (unfiltered) install additionally removes stale
-// dingtalk-* / dws-shared directories that are no longer in the bundle,
-// matching install.sh / install.ps1 / install.js / upgrade paths.
-func installMultiSkillToHomes(src string, skillNames []string, dests []string, out, errOut io.Writer, filtered bool) (installed, skipped int, err error) {
+func installMultiSkillToHomes(src string, skillNames []string, dests []string, out, errOut io.Writer) (installed, skipped int, err error) {
 	sort.Strings(dests)
 	for _, dest := range dests {
 		// 互斥清理：装 multi 前先把 dest/dws/ 整个删除（mono 残留）
@@ -685,10 +662,6 @@ func installMultiSkillToHomes(src string, skillNames []string, dests []string, o
 			continue
 		}

-		if !filtered {
-			removeStaleMultiSkills(dest, skillNames, out, errOut)
-		}
-
 		for _, name := range skillNames {
 			subSrc := filepath.Join(src, name)
 			subDest := filepath.Join(dest, name)
@@ -709,65 +682,6 @@ func installMultiSkillToHomes(src string, skillNames []string, dests []string, o
 	return installed, skipped, nil
 }

-// staleMultiSkillVictims lists the dingtalk-* / dws-shared directories under
-// dest that a full (unfiltered) multi install would delete because they are
-// not part of the bundle. It is the read-only preview companion of
-// removeStaleMultiSkills; scan failures degrade to a nil list so the
-// confirmation prompt is never blocked by an unreadable agent home.
-func staleMultiSkillVictims(dest string, keep []string) []string {
-	entries, err := skillSetupReadDir(dest)
-	if err != nil {
-		return nil
-	}
-	keepSet := make(map[string]bool, len(keep))
-	for _, n := range keep {
-		keepSet[n] = true
-	}
-	var victims []string
-	for _, e := range entries {
-		if !e.IsDir() || keepSet[e.Name()] {
-			continue
-		}
-		if !strings.HasPrefix(e.Name(), multiSkillPrefix) && e.Name() != multiSharedSkill {
-			continue
-		}
-		victims = append(victims, filepath.Join(dest, e.Name()))
-	}
-	sort.Strings(victims)
-	return victims
-}
-
-// removeStaleMultiSkills deletes dingtalk-* / dws-shared directories under
-// dest that are not part of the current bundle. Best-effort: scan/removal
-// failures warn on errOut and never abort the install.
-func removeStaleMultiSkills(dest string, keep []string, out, errOut io.Writer) {
-	entries, err := skillSetupReadDir(dest)
-	if err != nil {
-		if !errors.Is(err, os.ErrNotExist) {
-			fmt.Fprintf(errOut, "  ⚠️  过期 skill 扫描失败（继续安装） %s: %v\n", dest, err)
-		}
-		return
-	}
-	keepSet := make(map[string]bool, len(keep))
-	for _, n := range keep {
-		keepSet[n] = true
-	}
-	for _, e := range entries {
-		if !e.IsDir() || keepSet[e.Name()] {
-			continue
-		}
-		if !strings.HasPrefix(e.Name(), multiSkillPrefix) && e.Name() != multiSharedSkill {
-			continue
-		}
-		stale := filepath.Join(dest, e.Name())
-		if err := skillSetupRemoveAll(stale); err != nil {
-			fmt.Fprintf(errOut, "  ⚠️  过期 skill 清理失败（继续安装） %s: %v\n", stale, err)
-			continue
-		}
-		fmt.Fprintf(out, "  × 已清理过期 skill %s\n", stale)
-	}
-}
-
 func copyDir(src, dst string) error {
 	return skillSetupWalk(src, func(path string, info os.FileInfo, walkErr error) error {
 		if walkErr != nil {
@@ -86,12 +86,12 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 		t.Fatal(err)
 	}

-	skillSetupConfirm = func(io.Writer, string, string, []string, []string, bool) (bool, error) { return false, fail }
+	skillSetupConfirm = func(io.Writer, string, string, []string, []string) (bool, error) { return false, fail }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, false)
 	if err := cmd.RunE(cmd, nil); err == nil {
 		t.Fatal("confirmation failure should propagate")
 	}
-	skillSetupConfirm = func(io.Writer, string, string, []string, []string, bool) (bool, error) { return false, nil }
+	skillSetupConfirm = func(io.Writer, string, string, []string, []string) (bool, error) { return false, nil }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMono, false)
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
@@ -113,7 +113,7 @@ func TestCrossPlatformCoverageSkillSetupHighLevelRemainingCoverage(t *testing.T)
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
 	}
-	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) { return 0, 0, fail }
+	skillSetupInstallMulti = func(string, []string, []string, io.Writer, io.Writer) (int, int, error) { return 0, 0, fail }
 	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
 	if err := cmd.RunE(cmd, nil); err == nil {
 		t.Fatal("multi install failure should propagate")
@@ -143,7 +143,7 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 		t.Fatal("interactive mode failure should propagate")
 	}
 	skillSetupRunForm = func(*huh.Form) error { return nil }
-	if got, err := resolveSkillSetupMode("", false, io.Discard); err != nil || got != skillSetupModeMulti {
+	if got, err := resolveSkillSetupMode("", false, io.Discard); err != nil || got != skillSetupModeMono {
 		t.Fatalf("interactive default choice = %q, %v", got, err)
 	}

@@ -202,11 +202,11 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	skillSetupReadDir, skillSetupStat = oldReadDir, oldStat
 	var out, errOut bytes.Buffer
 	skillSetupRunForm = func(*huh.Form) error { return fail }
-	if _, err := confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{monoDest}, []string{"dingtalk-doc"}, false); err == nil {
+	if _, err := confirmSkillSetup(&out, skillSetupModeMulti, "src", []string{monoDest}, []string{"dingtalk-doc"}); err == nil {
 		t.Fatal("confirmation form failure should propagate")
 	}
 	skillSetupRunForm = func(*huh.Form) error { return nil }
-	if ok, err := confirmSkillSetup(&out, skillSetupModeMono, "src", []string{monoDest}, nil, false); err != nil || ok {
+	if ok, err := confirmSkillSetup(&out, skillSetupModeMono, "src", []string{monoDest}, nil); err != nil || ok {
 		t.Fatalf("EOF confirmation = %v, %v", ok, err)
 	}
 	skillSetupRemoveAll = func(string) error { return fail }
@@ -231,18 +231,18 @@ func TestCrossPlatformCoverageSkillSetupLowLevelRemainingCoverage(t *testing.T)
 	}

 	skillSetupMkdirAll = func(string, os.FileMode) error { return fail }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one", "two"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one", "two"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
 	if skipped != 2 {
 		t.Fatal("multi mkdir failure count mismatch")
 	}
 	skillSetupMkdirAll = func(string, os.FileMode) error { return nil }
 	skillSetupRemoveAll = func(string) error { return fail }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
 	if skipped != 1 {
 		t.Fatal("multi remove failure count mismatch")
 	}
 	skillSetupRemoveAll = func(string) error { return nil }
-	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut, true)
+	_, skipped, _ = installMultiSkillToHomes("src", []string{"one"}, []string{filepath.Join(t.TempDir(), "dest")}, &out, &errOut)
 	if skipped != 1 {
 		t.Fatal("multi copy failure count mismatch")
 	}
@@ -2,8 +2,6 @@ package app

 import (
 	"bytes"
-	"errors"
-	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -38,14 +36,14 @@ func TestResolveSkillSetupModeFlagDirect(t *testing.T) {
 	}
 }

-func TestResolveSkillSetupModeNonInteractiveDefaultsMulti(t *testing.T) {
+func TestResolveSkillSetupModeNonInteractiveDefaultsMono(t *testing.T) {
 	var buf bytes.Buffer
 	got, err := resolveSkillSetupMode("", true, &buf)
-	if err != nil || got != skillSetupModeMulti {
-		t.Fatalf("non-interactive empty mode should default to multi, got %q err=%v", got, err)
+	if err != nil || got != skillSetupModeMono {
+		t.Fatalf("non-interactive empty mode should default to mono, got %q err=%v", got, err)
 	}
-	if !strings.Contains(buf.String(), "multi") {
-		t.Fatalf("expected output to mention multi fallback, got %q", buf.String())
+	if !strings.Contains(buf.String(), "mono") {
+		t.Fatalf("expected output to mention mono fallback, got %q", buf.String())
 	}
 }

@@ -212,7 +210,7 @@ func TestInstallMultiSkillToHomes(t *testing.T) {
 	dst2 := filepath.Join(t.TempDir(), ".cursor", "skills")

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, got, []string{dst1, dst2}, &stdout, &stderr, false)
+	installed, skipped, err := installMultiSkillToHomes(src, got, []string{dst1, dst2}, &stdout, &stderr)
 	if err != nil {
 		t.Fatalf("installMultiSkillToHomes err: %v", err)
 	}
@@ -256,16 +254,13 @@ func TestSkillSetupMutualExclusion(t *testing.T) {
 	}

 	// Confirm mutualExclusionVictims sees the leftover
-	victims, vErr := mutualExclusionVictims(agentHome, skillSetupModeMulti)
-	if vErr != nil {
-		t.Fatalf("mutualExclusionVictims err: %v", vErr)
-	}
+	victims := mutualExclusionVictims(agentHome, skillSetupModeMulti)
 	if len(victims) != 1 || victims[0] != monoLeftover {
 		t.Fatalf("expected victims=[%s], got %v", monoLeftover, victims)
 	}

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr, false)
+	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr)
 	if err != nil {
 		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
 	}
@@ -487,7 +482,7 @@ func TestSkillSetupMultiAdditivePreservesSiblings(t *testing.T) {
 	}

 	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, filtered, []string{agentHome}, &stdout, &stderr, true)
+	installed, skipped, err := installMultiSkillToHomes(src, filtered, []string{agentHome}, &stdout, &stderr)
 	if err != nil {
 		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
 	}
@@ -554,114 +549,3 @@ func TestResolveSkillSetupSourceMultiFinds(t *testing.T) {
 		t.Fatalf("expected %s, got %s", multiDir, got)
 	}
 }
-
-// TestSkillSetupMultiFullInstallCleansStale verifies that a full (unfiltered)
-// multi install removes stale dingtalk-* / dws-shared directories that are no
-// longer part of the bundle, matching install.sh / install.js / upgrade paths.
-// The additive counterpart (filtered install) is covered by
-// TestSkillSetupMultiAdditivePreservesSiblings.
-func TestSkillSetupMultiFullInstallCleansStale(t *testing.T) {
-	names := []string{"dingtalk-aitable"}
-	src := writeMultiSkillSource(t, names)
-
-	agentHome := filepath.Join(t.TempDir(), ".claude", "skills")
-	// Stale multi skills absent from the bundle, plus a non-DWS dir that must survive.
-	for _, n := range []string{"dingtalk-stale", "dws-shared", "other-skill"} {
-		dir := filepath.Join(agentHome, n)
-		if err := os.MkdirAll(dir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("OLD "+n), 0o644); err != nil {
-			t.Fatal(err)
-		}
-	}
-
-	var stdout, stderr bytes.Buffer
-	installed, skipped, err := installMultiSkillToHomes(src, names, []string{agentHome}, &stdout, &stderr, false)
-	if err != nil {
-		t.Fatalf("install err: %v (stderr=%s)", err, stderr.String())
-	}
-	if installed != 1 || skipped != 0 {
-		t.Fatalf("expected installed=1 skipped=0, got %d/%d", installed, skipped)
-	}
-
-	if _, err := os.Stat(filepath.Join(agentHome, "dingtalk-aitable", "SKILL.md")); err != nil {
-		t.Errorf("missing installed skill: %v", err)
-	}
-	for _, stale := range []string{"dingtalk-stale", "dws-shared"} {
-		if _, err := os.Stat(filepath.Join(agentHome, stale)); !os.IsNotExist(err) {
-			t.Errorf("stale %q should be removed by a full multi install (stat err=%v)", stale, err)
-		}
-	}
-	body, err := os.ReadFile(filepath.Join(agentHome, "other-skill", "SKILL.md"))
-	if err != nil || !strings.HasPrefix(string(body), "OLD ") {
-		t.Errorf("non-DWS dir must be preserved (body=%q, err=%v)", string(body), err)
-	}
-	if !strings.Contains(stdout.String(), "已清理过期 skill") {
-		t.Errorf("expected stale cleanup log line, got stdout=%q", stdout.String())
-	}
-}
-
-// TestSkillSetupMutualExclusionScanWarning verifies that a victim-scan failure
-// surfaces as an errOut warning instead of silently skipping cleanup.
-func TestSkillSetupMutualExclusionScanWarning(t *testing.T) {
-	oldReadDir := skillSetupReadDir
-	t.Cleanup(func() { skillSetupReadDir = oldReadDir })
-	scanFail := errors.New("scan boom")
-	skillSetupReadDir = func(string) ([]os.DirEntry, error) { return nil, scanFail }
-
-	monoDest := filepath.Join(t.TempDir(), "agent", "dws")
-	if _, err := mutualExclusionVictims(monoDest, skillSetupModeMono); err == nil {
-		t.Fatal("scan failure should surface as an error")
-	}
-
-	var out, errOut bytes.Buffer
-	cleanupMutualExclusion(monoDest, skillSetupModeMono, &out, &errOut)
-	if !strings.Contains(errOut.String(), "互斥清理扫描失败") {
-		t.Fatalf("expected scan warning on errOut, got %q", errOut.String())
-	}
-}
-
-// TestRunSkillSetupThreadsFilteredFlag verifies runSkillSetup tells
-// installMultiSkillToHomes whether -s/--skill or -x/--exclude was used, so a
-// full install cleans stale siblings while a filtered install stays additive.
-func TestRunSkillSetupThreadsFilteredFlag(t *testing.T) {
-	oldMode, oldSource, oldTargets := skillSetupResolveMode, skillSetupResolveSource, skillSetupResolveTargets
-	oldList, oldFilter, oldMulti := skillSetupListMulti, skillSetupFilterMulti, skillSetupInstallMulti
-	t.Cleanup(func() {
-		skillSetupResolveMode, skillSetupResolveSource, skillSetupResolveTargets = oldMode, oldSource, oldTargets
-		skillSetupListMulti, skillSetupFilterMulti, skillSetupInstallMulti = oldList, oldFilter, oldMulti
-	})
-
-	skillSetupResolveMode = func(mode string, _ bool, _ io.Writer) (string, error) { return mode, nil }
-	skillSetupResolveSource = func(string, string) (string, func(), error) { return "source", func() {}, nil }
-	skillSetupResolveTargets = func(string, string) ([]string, error) {
-		return []string{filepath.Join(t.TempDir(), "dest")}, nil
-	}
-	skillSetupListMulti = func(string) ([]string, error) { return []string{"dingtalk-aitable", "dws-shared"}, nil }
-	skillSetupFilterMulti = filterMultiSkillNames
-	var gotFiltered []bool
-	skillSetupInstallMulti = func(_ string, _ []string, _ []string, _, _ io.Writer, filtered bool) (int, int, error) {
-		gotFiltered = append(gotFiltered, filtered)
-		return 1, 0, nil
-	}
-
-	// Full install (no -s/-x): filtered must be false.
-	cmd := skillSetupCoverageCommand(t, skillSetupModeMulti, true)
-	if err := cmd.RunE(cmd, nil); err != nil {
-		t.Fatalf("full install run err: %v", err)
-	}
-
-	// Filtered install: filtered must be true.
-	cmd = skillSetupCoverageCommand(t, skillSetupModeMulti, true)
-	if err := cmd.Flags().Set("skill", "aitable"); err != nil {
-		t.Fatal(err)
-	}
-	if err := cmd.RunE(cmd, nil); err != nil {
-		t.Fatalf("filtered install run err: %v", err)
-	}
-
-	if len(gotFiltered) != 2 || gotFiltered[0] != false || gotFiltered[1] != true {
-		t.Fatalf("filtered flag threading = %v, want [false true]", gotFiltered)
-	}
-}
@@ -57,7 +57,7 @@ var (
 	downloadUpgradeProgress = upgrade.DownloadWithProgress
 	extractUpgradeZip       = upgrade.ExtractZip
 	findExtractedBinary     = upgrade.FindBinaryInDir
-	locateUpgradeSkill      = upgrade.LocateSkillsRoot
+	locateUpgradeSkill      = upgrade.LocateSkillMD
 	replaceUpgradeSelf      = upgrade.ReplaceSelf
 	installUpgradeSkills    = upgrade.UpgradeSkillLocations
 	upgradeMkdirTemp        = os.MkdirTemp
@@ -1,67 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0
-
-package app
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
-)
-
-// TestUpgradeSkillLocationsMonoSeedMigratesToMulti is the fake-HOME E2E for
-// the 2026-08-05 owner decision: upgrade is not disk-sticky. Seeding a mono
-// layout then calling UpgradeSkillLocations with a multi bundle must install
-// product skills, remove dws/, and leave non-DWS dirs alone.
-func TestUpgradeSkillLocationsMonoSeedMigratesToMulti(t *testing.T) {
-	home := t.TempDir()
-	setTestHome(t, home)
-	upgrade.SwapUserHomeDirForTest(t, func() (string, error) { return home, nil })
-
-	agentsBase := filepath.Join(home, ".agents", "skills")
-	if err := os.MkdirAll(filepath.Join(agentsBase, "dws"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(agentsBase, "dws", "SKILL.md"), []byte("old mono"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.MkdirAll(filepath.Join(agentsBase, "other-skill"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(agentsBase, "other-skill", "SKILL.md"), []byte("not dws"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	extract := t.TempDir()
-	multiRoot := filepath.Join(extract, "multi")
-	for _, name := range []string{"dingtalk-chat", "dws-shared"} {
-		dir := filepath.Join(multiRoot, name)
-		if err := os.MkdirAll(dir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# "+name), 0o644); err != nil {
-			t.Fatal(err)
-		}
-	}
-
-	result, err := upgrade.UpgradeSkillLocations(multiRoot)
-	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v", err)
-	}
-	if failed := result.Failed(); len(failed) != 0 {
-		t.Fatalf("expected 0 failures, got %v", failed)
-	}
-	if _, err := os.Stat(filepath.Join(agentsBase, "dws")); !os.IsNotExist(err) {
-		t.Fatalf("mono leftover dws/ must be gone, stat err=%v", err)
-	}
-	for _, name := range []string{"dingtalk-chat", "dws-shared"} {
-		if _, err := os.Stat(filepath.Join(agentsBase, name, "SKILL.md")); err != nil {
-			t.Errorf("multi skill missing: %s: %v", name, err)
-		}
-	}
-	if _, err := os.Stat(filepath.Join(agentsBase, "other-skill", "SKILL.md")); err != nil {
-		t.Errorf("non-DWS dir should be preserved: %v", err)
-	}
-}
@@ -543,6 +543,13 @@ func TestIsLikelyAMFIKill(t *testing.T) {
 // validateNewBinary recovers via repairDarwinBinary (ad-hoc codesign) and
 // successfully re-executes the binary. We use go itself as a stand-in for the
 // new dws binary — it's a real signed Mach-O we can strip and re-sign.
+//
+// GitHub's hosted macOS runners do not reproduce the amfid kill, so in CI this
+// test reports a skip that names the unverified path rather than implying the
+// self-heal was exercised. Set DWS_REQUIRE_AMFI_SELF_HEAL=1 on a host that does
+// enforce amfid to turn such a vacuous run into a hard failure.
+
+const requireAMFISelfHealEnv = "DWS_REQUIRE_AMFI_SELF_HEAL"

 func TestValidateNewBinary_RecoversFromUnsignedDarwin(t *testing.T) {
 	if runtime.GOOS != "darwin" {
@@ -573,15 +580,24 @@ func TestValidateNewBinary_RecoversFromUnsignedDarwin(t *testing.T) {
 		t.Fatalf("strip signature: %v\n%s", err, out)
 	}

-	// Sanity: confirm direct exec is killed.
+	// Sanity: confirm direct exec is killed. When it is not, repairDarwinBinary
+	// never runs and the rest of this test proves nothing — say so.
 	if _, err := tryExecVersion(bin); err == nil {
-		t.Skip("unsigned binary executed without amfid kill — likely Intel Mac or SIP disabled")
+		const unverified = "amfid did not kill the unsigned binary, so repairDarwinBinary was NOT exercised"
+		if os.Getenv(requireAMFISelfHealEnv) == "1" {
+			t.Fatalf("%s (%s=1)", unverified, requireAMFISelfHealEnv)
+		}
+		t.Skipf("%s — host does not enforce amfid (Intel Mac, SIP disabled, or hosted runner)", unverified)
 	}

 	// validateNewBinary should self-heal and succeed.
 	if err := validateNewBinary(bin, "dev"); err != nil {
 		if strings.Contains(err.Error(), "signal: killed") {
-			t.Skipf("host security policy still rejects the ad-hoc signed test binary: %v", err)
+			const unverified = "host security policy still rejects the ad-hoc signed binary, so the self-heal outcome was NOT verified"
+			if os.Getenv(requireAMFISelfHealEnv) == "1" {
+				t.Fatalf("%s (%s=1): %v", unverified, requireAMFISelfHealEnv, err)
+			}
+			t.Skipf("%s: %v", unverified, err)
 		}
 		t.Fatalf("validateNewBinary did not recover: %v", err)
 	}
@@ -23,11 +23,11 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
-	"sync"
 	"time"

 	"github.com/google/uuid"

+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/profilectx"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
 )

@@ -117,23 +117,14 @@ type Profile struct {
 	UpdatedAt         string   `json:"updatedAt,omitempty"`
 }

-var (
-	runtimeProfileMu sync.RWMutex
-	runtimeProfile   string
-)
-
 // SetRuntimeProfile sets a process-local one-shot profile override.
 func SetRuntimeProfile(profile string) {
-	runtimeProfileMu.Lock()
-	defer runtimeProfileMu.Unlock()
-	runtimeProfile = strings.TrimSpace(profile)
+	profilectx.Set(profile)
 }

 // RuntimeProfile returns the process-local one-shot profile override.
 func RuntimeProfile() string {
-	runtimeProfileMu.RLock()
-	defer runtimeProfileMu.RUnlock()
-	return runtimeProfile
+	return profilectx.Get()
 }

 // ProfilesPath returns the profile metadata path for a config dir.
@@ -4,6 +4,7 @@
 package homology

 import (
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -19,8 +20,22 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
 )

+// homologyProbeCaller is a throwaway ToolCaller for Execute-based confirmation
+// probes. Schema source roots stay declaration-only (no InitDeps); the probe
+// path initializes deps locally so leaf RunE wrappers do not nil-deref.
+type homologyProbeCaller struct{}
+
+func (homologyProbeCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return &edition.ToolResult{}, nil
+}
+func (homologyProbeCaller) Format() string { return "json" }
+func (homologyProbeCaller) DryRun() bool   { return false }
+func (homologyProbeCaller) Fields() string { return "" }
+func (homologyProbeCaller) JQ() string     { return "" }
+
 // TestUserRequiredSafetyHomologyWithRuntimeGate proves Catalog Safety and the
 // executable confirmation gate share one source for every live user_required leaf:
 //
@@ -29,6 +44,12 @@ import (
 //     Sheet protect marker, or framework NewCommand/Shortcut RunE (verified by
 //     closed-stdin Execute → confirmation_required / 用户取消了操作 without --yes)
 func TestUserRequiredSafetyHomologyWithRuntimeGate(t *testing.T) {
+	// Declaration-only Schema roots intentionally skip InitDeps. Probes Execute
+	// live leaves (including deprecated doc wrappers), so install a local
+	// throwaway caller without touching SetDynamicServers. Restore the prior
+	// deps pointer (including nil) — InitDeps(previousCaller) cannot.
+	helpers.InitDepsForTest(t, homologyProbeCaller{})
+
 	root := app.NewSchemaSourceRootCommand()
 	if root.PersistentFlags().Lookup("yes") == nil {
 		root.PersistentFlags().Bool("yes", false, "")
@@ -158,6 +158,12 @@ var generatedParamAliases = []ParamAliasEntry{
 		},
 		Blocked: []string{"conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "id", "name", "open-conversation-ids", "source", "src-conversation-id", "target"},
 	},
+	{
+		CLIPath: "chat +chat-messages",
+		Aliases: map[string]string{
+			"chat": "group",
+		},
+	},
 	{
 		CLIPath: "chat +chat-mute",
 		Aliases: map[string]string{
@@ -336,6 +342,12 @@ var generatedParamAliases = []ParamAliasEntry{
 			"at-user-ids": "at-users",
 		},
 	},
+	{
+		CLIPath: "chat +search-msg",
+		Aliases: map[string]string{
+			"chat": "group",
+		},
+	},
 	{
 		CLIPath: "chat +send-to-group",
 		Aliases: map[string]string{
@@ -57,6 +57,8 @@
    "mail message search": {"scoped_aliases": {"subject": "query"}, "scope_strict": true, "note": "never globalize: mail template create has a real and different --subject"},
    "calendar event list": {"scoped_aliases": {"date": "start"}, "note": "reviewed against ParseISOTimeToMillis and final list_calendar_events payload; --date is normalized centrally while the command's existing hidden compatibility flags remain native fallbacks"},
    "chat +bot-find": {"scoped_aliases": {"name": "query"}, "scope_strict": true, "note": "On this exact bot-search shortcut, --name and --query denote the same search keyword; --name must not become a global search alias."},
+    "chat +chat-messages": {"scoped_aliases": {"chat": "group"}, "scope_strict": true, "note": "Evaluation compatibility: --chat carries one stable openConversationId and normalizes to the existing --group identifier route."},
+    "chat +search-msg": {"scoped_aliases": {"chat": "group"}, "scope_strict": true, "note": "Evaluation compatibility: scalar --chat carries one stable openConversationId and normalizes to the existing scalar --group filter."},
    "chat bot find": {"scoped_aliases": {"name": "query"}, "scope_strict": true, "note": "On this exact bot-search command, --name and --query denote the same search keyword; --name must not become a global search alias."},
    "chat +bot-search": {"scoped_aliases": {"query": "name", "current-page": "page"}, "block": ["cursor"], "scope_strict": true, "note": "Only the reviewed bot keyword and page-number spellings are accepted; cursor pagination cannot be converted to a page number."},
    "chat bot search": {"scoped_aliases": {"query": "name", "current-page": "page"}, "block": ["cursor"], "scope_strict": true, "note": "Only the reviewed bot keyword and page-number spellings are accepted; cursor pagination cannot be converted to a page number."},
@@ -255,7 +257,9 @@
      {"command": "chat +unread-chats", "emitted": "limit", "expect": "count", "via": "override:scoped"},
      {"command": "chat +unread-chats", "emitted": "size", "expect": "count", "via": "override:scoped"},
      {"command": "chat category rename", "emitted": "name", "expect": "title", "via": "override:scoped"},
-      {"command": "chat message list-unread-conversations", "emitted": "size", "expect": "count", "via": "override:scoped"}
+      {"command": "chat message list-unread-conversations", "emitted": "size", "expect": "count", "via": "override:scoped"},
+      {"command": "chat +chat-messages", "emitted": "chat", "expect": "group", "via": "override:scoped-eval"},
+      {"command": "chat +search-msg", "emitted": "chat", "expect": "group", "via": "override:scoped-eval"}
    ]
  }
 }
@@ -1142,6 +1142,12 @@ func inferredRuntimeFlagFormat(flag *pflag.Flag) string {
 	}
 	usage := strings.ToLower(strings.TrimSpace(flag.Usage))
 	if strings.Contains(usage, "iso-8601") || strings.Contains(usage, "rfc3339") {
+		// JSON Schema's date-time format means one RFC3339 value. Do not publish
+		// that narrower wire contract when the CLI also accepts local timestamps
+		// or date-only values alongside RFC3339.
+		if strings.Contains(usage, "yyyy-mm-dd") {
+			return ""
+		}
 		return "date-time"
 	}
 	if strings.Contains(usage, "a1") {
@@ -171,62 +171,4 @@ var reviewedRuntimeSchemaExclusionGroups = []runtimeSchemaExclusionGroup{
 			"todo task remove-attachment",
 		},
 	},
-	{
-		ID:       "chat-shortcuts-pending-schema-curation",
-		Reason:   "These reviewed public Chat shortcuts remain executable and discoverable through the Shortcut catalog while their typed Schema selection and metadata records are curated; exact paths keep reverse completeness strict without hiding future shortcuts.",
-		Reviewed: true,
-		Commands: []string{
-			"chat +category-add-conversation",
-			"chat +category-list-conversations",
-			"chat +category-remove-conversation",
-			"chat +chat-add-bot",
-			"chat +chat-audit-join",
-			"chat +chat-create",
-			"chat +chat-list",
-			"chat +chat-get-by-id",
-			"chat +chat-members-get",
-			"chat +chat-members-list",
-			"chat +chat-mute-member",
-			"chat +chat-quit",
-			"chat +chat-remove-bot",
-			"chat +chat-role-remove",
-			"chat +chat-role-remove-user",
-			"chat +chat-transfer-owner",
-			"chat +chat-update",
-			"chat +chat-update-icon",
-			"chat +chat-update-settings",
-			"chat +conversation-clear-messages",
-			"chat +conversation-clear-red-point",
-			"chat +conversation-hide",
-			"chat +conversation-mark-read",
-			"chat +conversation-mark-unread",
-			"chat +conversation-mute",
-			"chat +conversation-set-top",
-			"chat +feed-group-query-item",
-			"chat +flag-cancel",
-			"chat +flag-create",
-			"chat +flag-list",
-			"chat +messages-add-emoji",
-			"chat +messages-add-text-emotion",
-			"chat +messages-batch-recall-by-bot",
-			"chat +messages-batch-send-by-bot",
-			"chat +messages-combine-forward",
-			"chat +messages-create-text-emotion",
-			"chat +messages-forward",
-			"chat +messages-forward-topic",
-			"chat +messages-list",
-			"chat +messages-recall",
-			"chat +messages-recall-by-bot",
-			"chat +messages-remove-emoji",
-			"chat +messages-remove-text-emotion",
-			"chat +messages-reply",
-			"chat +messages-resource-download",
-			"chat +messages-resource-url",
-			"chat +messages-send-by-bot",
-			"chat +messages-set-pin",
-			"chat +messages-set-top",
-			"chat +messages-unset-pin",
-			"chat +messages-unset-top",
-		},
-	},
 }
@@ -511,6 +511,17 @@ var reviewedSchemaParameterMappingExclusions = map[string]string{
 	"minutes.record_resume --session-id":                                 "Reviewed unpinned adapter: minutes.record_resume has no singular pinned interface_ref; --session-id is a CLI wrapper input and does not publish a direct interface property.",
 	"minutes.record_start --session-id":                                  "Reviewed unpinned adapter: minutes.record_start has no singular pinned interface_ref; --session-id is a CLI wrapper input and does not publish a direct interface property.",
 	"minutes.record_stop --session-id":                                   "Reviewed unpinned adapter: minutes.record_stop has no singular pinned interface_ref; --session-id is a CLI wrapper input and does not publish a direct interface property.",
+	"oa.forecast_process --dept-id":                                      "Conditional request wrapper: --dept-id is encoded inside ProcessForecastPopRequest together with the other simple-mode flags, so it has no independent top-level MCP property.",
+	"oa.forecast_process --form-values":                                  "Conditional request wrapper: --form-values is transformed into formComponentValues inside ProcessForecastPopRequest, so it has no independent top-level MCP property.",
+	"oa.forecast_process --process-code":                                 "Conditional request wrapper: --process-code is encoded inside ProcessForecastPopRequest together with the other simple-mode flags, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --approvers":                              "Conditional request wrapper: --approvers is transformed into an approvers array inside ProcessInstanceCreationPopRequest, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --approvers-action-type":                  "Conditional request wrapper: --approvers-action-type only configures the generated approvers array inside ProcessInstanceCreationPopRequest, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --cc-list":                                "Conditional request wrapper: --cc-list is encoded inside ProcessInstanceCreationPopRequest only when supplied, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --cc-position":                            "Conditional request wrapper: --cc-position only configures the generated ccList inside ProcessInstanceCreationPopRequest, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --dept-id":                                "Conditional request wrapper: --dept-id is encoded inside ProcessInstanceCreationPopRequest together with the other simple-mode flags, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --form-values":                            "Conditional request wrapper: --form-values is transformed into formComponentValues inside ProcessInstanceCreationPopRequest, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --originator-user-id":                     "Conditional request wrapper: --originator-user-id is encoded inside ProcessInstanceCreationPopRequest only when supplied, so it has no independent top-level MCP property.",
+	"oa.start_process_instance --process-code":                           "Conditional request wrapper: --process-code is encoded inside ProcessInstanceCreationPopRequest together with the other simple-mode flags, so it has no independent top-level MCP property.",
 	"pat.batch_grant --domain":                                           "aggregate/two-stage wrapper: --domain is merged with all product/domain flags into productCodes for pat.batch_plan; only the plan's selectedScopes are later sent to pat.batch_grant.scopes",
 	"pat.batch_grant --domains":                                          "aggregate/two-stage wrapper: --domains is merged with all product/domain flags into productCodes for pat.batch_plan; only the plan's selectedScopes are later sent to pat.batch_grant.scopes",
 	"pat.batch_grant --product":                                          "aggregate/two-stage wrapper: --product is merged with all product/domain flags into productCodes for pat.batch_plan; only the plan's selectedScopes are later sent to pat.batch_grant.scopes",
@@ -103,11 +103,12 @@ const ValidationShortcut FlagValidationMode = "shortcut"
 // fields intentionally mirror the former helpers.LeafFlag one-for-one so that
 // helpers can alias to it without touching any call site.
 type FlagSpec struct {
-	Name    string   // flag name (kebab-case)
-	Usage   string   // registration usage text
-	Kind    FlagKind // value type, defaults to KindString
-	Default string   // registration default for every Kind; also the fallback-chain tail when aliases/env are empty
-	Hidden  bool     // hide the real flag from help/Schema while keeping it invocable
+	Name      string   // flag name (kebab-case)
+	Shorthand string   // optional one-character Cobra shorthand
+	Usage     string   // registration usage text
+	Kind      FlagKind // value type, defaults to KindString
+	Default   string   // registration default for every Kind; also the fallback-chain tail when aliases/env are empty
+	Hidden    bool     // hide the real flag from help/Schema while keeping it invocable

 	// Required, when true, validates a non-empty effective value in RunE. Plain
 	// Required flags aggregate into a cmdutil.ValidateRequiredFlags-compatible
@@ -551,7 +552,7 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) {
 				"flag %q: MarkRequired cannot be combined with Aliases: cobra MarkFlagRequired only recognizes the main name, so a value passed via an alias would be rejected",
 				flag.Name))
 		}
-		RegisterFlag(cmd, flag.Kind, flag.Name, flag.Default, flag.Usage)
+		registerFlagP(cmd, flag.Kind, flag.Name, flag.Shorthand, flag.Default, flag.Usage)
 		// Aliases are registered with the main flag's Kind, otherwise an integer
 		// alias's value would never be readable (silently dropped).
 		for _, alias := range flag.Aliases {
@@ -572,6 +573,10 @@ func RegisterFlags(cmd *cobra.Command, flags []FlagSpec) {
 // Malformed KindInt / KindBool Default values panic at registration (fail-closed)
 // instead of silently degrading to 0 / false.
 func RegisterFlag(cmd *cobra.Command, kind FlagKind, name, def, usage string) {
+	registerFlagP(cmd, kind, name, "", def, usage)
+}
+
+func registerFlagP(cmd *cobra.Command, kind FlagKind, name, shorthand, def, usage string) {
 	switch kind {
 	case KindInt:
 		defInt := 0
@@ -582,7 +587,7 @@ func RegisterFlag(cmd *cobra.Command, kind FlagKind, name, def, usage string) {
 			}
 			defInt = v
 		}
-		cmd.Flags().Int(name, defInt, usage)
+		cmd.Flags().IntP(name, shorthand, defInt, usage)
 	case KindBool:
 		defBool := false
 		if def != "" {
@@ -595,15 +600,15 @@ func RegisterFlag(cmd *cobra.Command, kind FlagKind, name, def, usage string) {
 				panic(fmt.Sprintf("flag %q: invalid KindBool Default %q (want \"true\" or \"false\")", name, def))
 			}
 		}
-		cmd.Flags().Bool(name, defBool, usage)
+		cmd.Flags().BoolP(name, shorthand, defBool, usage)
 	case KindStringSlice:
 		var defaults []string
 		if value := strings.TrimSpace(def); value != "" {
 			defaults = strings.Split(value, ",")
 		}
-		cmd.Flags().StringSlice(name, defaults, usage)
+		cmd.Flags().StringSliceP(name, shorthand, defaults, usage)
 	default:
-		cmd.Flags().String(name, def, usage)
+		cmd.Flags().StringP(name, shorthand, def, usage)
 	}
 }

@@ -885,7 +890,21 @@ func BuildArgs(cmd *cobra.Command, flags []FlagSpec) (map[string]any, error) {
 			if err != nil {
 				return nil, err
 			}
-			if value == nil {
+			// Required is checked on the pre-transform string. A transform that
+			// collapses separator-only input ("," / ";") to nil/empty must still
+			// fail required flags locally — otherwise BuildArgs would omit the
+			// key and ConfirmFirst write paths could reach the backend.
+			if value == nil || emptyTransformResult(value) {
+				if flag.Required {
+					message := strings.TrimSpace(flag.RequiredHint)
+					if message == "" {
+						message = strings.TrimSpace(flag.RequiredError)
+					}
+					if message == "" {
+						message = fmt.Sprintf("必填参数 --%s 不能为空", flag.Name)
+					}
+					return nil, apperrors.NewValidation(message)
+				}
 				continue
 			}
 			toolArgs[bind] = value
@@ -896,6 +915,21 @@ func BuildArgs(cmd *cobra.Command, flags []FlagSpec) (map[string]any, error) {
 	return toolArgs, nil
 }

+// emptyTransformResult reports whether a Transform produced an empty payload
+// that must not satisfy a Required flag (nil is handled by the caller).
+func emptyTransformResult(value any) bool {
+	switch v := value.(type) {
+	case string:
+		return strings.TrimSpace(v) == ""
+	case []string:
+		return len(v) == 0
+	case []any:
+		return len(v) == 0
+	default:
+		return false
+	}
+}
+
 // EffectiveValue reads the value by "explicit main flag → alias → env →
 // registration default" order (string form, integers uniformly formatted);
 // Trim TrimSpace's the result.
@@ -67,10 +67,10 @@ func testDestructiveSafety() contract.SafetySpec {
 func TestCrossPlatformCoverageRegisterFlagsAllKinds(t *testing.T) {
 	cmd := newTestCommand()
 	RegisterFlags(cmd, []FlagSpec{
-		{Name: "s", Usage: "S", Default: "d"},
-		{Name: "i", Usage: "I", Kind: KindInt, Aliases: []string{"i-alias"}},
-		{Name: "b", Usage: "B", Kind: KindBool},
-		{Name: "sl", Usage: "SL", Kind: KindStringSlice, Default: "a,b", Aliases: []string{"sl-alias"}},
+		{Name: "s", Shorthand: "s", Usage: "S", Default: "d"},
+		{Name: "i", Shorthand: "i", Usage: "I", Kind: KindInt, Aliases: []string{"i-alias"}},
+		{Name: "b", Shorthand: "b", Usage: "B", Kind: KindBool},
+		{Name: "sl", Shorthand: "l", Usage: "SL", Kind: KindStringSlice, Default: "a,b", Aliases: []string{"sl-alias"}},
 		{Name: "req", Usage: "R", MarkRequired: true},
 		{Name: "hidden", Usage: "H", Hidden: true},
 	})
@@ -78,6 +78,11 @@ func TestCrossPlatformCoverageRegisterFlagsAllKinds(t *testing.T) {
 	if f := cmd.Flags().Lookup("s"); f == nil || f.DefValue != "d" || f.Usage != "S" {
 		t.Fatalf("string flag = %#v", f)
 	}
+	for shorthand, name := range map[string]string{"s": "s", "i": "i", "b": "b", "l": "sl"} {
+		if flag := cmd.Flags().ShorthandLookup(shorthand); flag == nil || flag.Name != name {
+			t.Fatalf("shorthand -%s = %#v, want --%s", shorthand, flag, name)
+		}
+	}
 	for name, wantType := range map[string]string{"i": "int", "b": "bool", "sl": "stringSlice"} {
 		f := cmd.Flags().Lookup(name)
 		if f == nil || f.Value.Type() != wantType {
@@ -458,6 +463,70 @@ func TestCrossPlatformCoverageBuildArgsTransformAndErrors(t *testing.T) {
 		t.Fatalf("nil transform should skip key: %#v", args)
 	}

+	// Required + transform-to-empty must fail (separator-only lists)
+	requiredEmpty := []FlagSpec{{
+		Name: "codes", Usage: "C", Required: true, RequiredHint: "--codes 为必填",
+		Transform: func(string) (any, error) { return nil, nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, requiredEmpty)
+	_ = cmd.Flags().Set("codes", ",")
+	if _, err := BuildArgs(cmd, requiredEmpty); err == nil || !strings.Contains(err.Error(), "--codes 为必填") {
+		t.Fatalf("required empty transform err = %v", err)
+	}
+	requiredEmptySlice := []FlagSpec{{
+		Name: "codes", Usage: "C", Required: true,
+		Transform: func(string) (any, error) { return []string{}, nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, requiredEmptySlice)
+	_ = cmd.Flags().Set("codes", ";")
+	if _, err := BuildArgs(cmd, requiredEmptySlice); err == nil || !strings.Contains(err.Error(), "必填参数 --codes 不能为空") {
+		t.Fatalf("required empty-slice transform err = %v", err)
+	}
+	requiredEmptyString := []FlagSpec{{
+		Name: "codes", Usage: "C", Required: true,
+		Transform: func(string) (any, error) { return "  ", nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, requiredEmptyString)
+	_ = cmd.Flags().Set("codes", ",")
+	if _, err := BuildArgs(cmd, requiredEmptyString); err == nil || !strings.Contains(err.Error(), "必填参数 --codes 不能为空") {
+		t.Fatalf("required empty-string transform err = %v", err)
+	}
+	requiredEmptyAnySlice := []FlagSpec{{
+		Name: "codes", Usage: "C", Required: true,
+		Transform: func(string) (any, error) { return []any{}, nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, requiredEmptyAnySlice)
+	_ = cmd.Flags().Set("codes", ",")
+	if _, err := BuildArgs(cmd, requiredEmptyAnySlice); err == nil || !strings.Contains(err.Error(), "必填参数 --codes 不能为空") {
+		t.Fatalf("required empty []any transform err = %v", err)
+	}
+	requiredErrorHint := []FlagSpec{{
+		Name: "codes", Usage: "C", Required: true, RequiredError: "codes missing after transform",
+		Transform: func(string) (any, error) { return nil, nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, requiredErrorHint)
+	_ = cmd.Flags().Set("codes", ",")
+	if _, err := BuildArgs(cmd, requiredErrorHint); err == nil || !strings.Contains(err.Error(), "codes missing after transform") {
+		t.Fatalf("required RequiredError transform err = %v", err)
+	}
+	// Non-empty non-list transform result is kept (covers emptyTransformResult default).
+	keepScalar := []FlagSpec{{
+		Name: "n", Usage: "N", Required: true, Bind: "count",
+		Transform: func(string) (any, error) { return 3, nil },
+	}}
+	cmd = newTestCommand()
+	RegisterFlags(cmd, keepScalar)
+	_ = cmd.Flags().Set("n", "x")
+	args, err = BuildArgs(cmd, keepScalar)
+	if err != nil || args["count"] != 3 {
+		t.Fatalf("scalar transform args = %#v err = %v", args, err)
+	}
+
 	// Transform error propagates
 	boom := errors.New("transform boom")
 	bad := []FlagSpec{{Name: "y", Usage: "Y", Transform: func(string) (any, error) { return nil, boom }}}
@@ -46,6 +46,9 @@ type Error struct {
 	Message           string
 	Operation         string
 	ServerKey         string
+	Origin            string
+	FailureStage      string
+	ExecutionStarted  *bool
 	Retryable         bool
 	RetryableSet      bool
 	RetryAfterSeconds *int64
@@ -55,6 +58,7 @@ type Error struct {
 	Actions           []string
 	AvailableFlags    []string
 	Snapshot          string
+	Details           map[string]any
 	RPCCode           int               `json:"rpc_code,omitempty"`
 	RPCData           json.RawMessage   `json:"rpc_data,omitempty"`
 	ServerDiag        ServerDiagnostics `json:"-"`
@@ -107,6 +111,32 @@ func WithServerKey(serverKey string) Option {
 	}
 }

+// WithOrigin records the component that produced the failure, such as the
+// client, MCP gateway, or DingTalk API. It is independent from Category,
+// which remains the stable exit-code contract.
+func WithOrigin(origin string) Option {
+	return func(err *Error) {
+		err.Origin = strings.TrimSpace(origin)
+	}
+}
+
+// WithFailureStage records the execution stage at which the failure occurred.
+func WithFailureStage(stage string) Option {
+	return func(err *Error) {
+		err.FailureStage = strings.TrimSpace(stage)
+	}
+}
+
+// WithExecutionStarted records whether the downstream business operation was
+// known to have started. Unknown state must be represented by omitting this
+// option, which is important for safe retry decisions on write operations.
+func WithExecutionStarted(started bool) Option {
+	return func(err *Error) {
+		value := started
+		err.ExecutionStarted = &value
+	}
+}
+
 // WithRetryable marks whether the error can be retried safely.
 func WithRetryable(retryable bool) Option {
 	return func(err *Error) {
@@ -186,6 +216,21 @@ func WithSnapshot(path string) Option {
 	}
 }

+// WithDetails records an additive machine-readable payload for errors whose
+// recovery needs typed context, such as ambiguous target-resolution
+// candidates. Callers must keep credentials and other secrets out of details.
+func WithDetails(details map[string]any) Option {
+	return func(err *Error) {
+		if len(details) == 0 {
+			return
+		}
+		err.Details = make(map[string]any, len(details))
+		for key, value := range details {
+			err.Details[key] = value
+		}
+	}
+}
+
 // WithRPCCode records the original JSON-RPC error code.
 func WithRPCCode(code int) Option {
 	return func(err *Error) {
@@ -295,6 +340,15 @@ func PrintJSON(w io.Writer, err error) error {
 		if typed.ServerKey != "" {
 			errorPayload["server_key"] = typed.ServerKey
 		}
+		if typed.Origin != "" {
+			errorPayload["origin"] = typed.Origin
+		}
+		if typed.FailureStage != "" {
+			errorPayload["stage"] = typed.FailureStage
+		}
+		if typed.ExecutionStarted != nil {
+			errorPayload["execution_started"] = *typed.ExecutionStarted
+		}
 		if typed.RetryableSet {
 			errorPayload["retryable"] = typed.Retryable
 		}
@@ -316,6 +370,9 @@ func PrintJSON(w io.Writer, err error) error {
 		if typed.Snapshot != "" {
 			errorPayload["snapshot_path"] = typed.Snapshot
 		}
+		if len(typed.Details) > 0 {
+			errorPayload["details"] = typed.Details
+		}
 		if typed.RPCCode != 0 {
 			errorPayload["rpc_code"] = typed.RPCCode
 		}
@@ -447,6 +504,15 @@ func PrintHumanAt(w io.Writer, err error, v Verbosity) error {
 		if typed.ServerKey != "" {
 			lines = append(lines, tui.Dim(fmt.Sprintf("Server: %s", typed.ServerKey)))
 		}
+		if typed.Origin != "" {
+			lines = append(lines, tui.Dim(fmt.Sprintf("Origin: %s", typed.Origin)))
+		}
+		if typed.FailureStage != "" {
+			lines = append(lines, tui.Dim(fmt.Sprintf("Stage: %s", typed.FailureStage)))
+		}
+		if typed.ExecutionStarted != nil {
+			lines = append(lines, tui.Dim(fmt.Sprintf("Execution Started: %t", *typed.ExecutionStarted)))
+		}
 		if typed.Snapshot != "" {
 			lines = append(lines, tui.Dim(fmt.Sprintf("Snapshot: %s", typed.Snapshot)))
 		}
@@ -20,7 +20,7 @@ import (
 	"time"
 )

-func TestExitCodeByCategory(t *testing.T) {
+func TestCrossPlatformCoverageExitCodeByCategory(t *testing.T) {
 	t.Parallel()

 	cases := []struct {
@@ -42,17 +42,24 @@ func TestExitCodeByCategory(t *testing.T) {
 	}
 }

-func TestPrintJSON(t *testing.T) {
+func TestCrossPlatformCoveragePrintJSON(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
 	if err := PrintJSON(&b, NewValidation(
 		"bad flag",
 		WithReason("missing_required_flag"),
+		WithOrigin("client"),
+		WithFailureStage("request_validation"),
+		WithExecutionStarted(false),
 		WithHint("Pass the required flag and retry."),
 		WithRetryable(true),
 		WithActions("dws schema doc.create_document", "retry command"),
 		WithSnapshot("/tmp/dws-recovery/snapshot.json"),
+		WithDetails(map[string]any{
+			"type":  "resolution",
+			"query": "项目群",
+		}),
 	)); err != nil {
 		t.Fatalf("PrintJSON() error = %v", err)
 	}
@@ -67,6 +74,11 @@ func TestPrintJSON(t *testing.T) {
 	if !strings.Contains(got, "\"reason\": \"missing_required_flag\"") {
 		t.Fatalf("expected reason in output, got %q", got)
 	}
+	if !strings.Contains(got, "\"origin\": \"client\"") ||
+		!strings.Contains(got, "\"stage\": \"request_validation\"") ||
+		!strings.Contains(got, "\"execution_started\": false") {
+		t.Fatalf("expected failure provenance in output, got %q", got)
+	}
 	if !strings.Contains(got, "\"retryable\": true") {
 		t.Fatalf("expected retryable in output, got %q", got)
 	}
@@ -76,6 +88,9 @@ func TestPrintJSON(t *testing.T) {
 	if !strings.Contains(got, "\"snapshot_path\": \"/tmp/dws-recovery/snapshot.json\"") {
 		t.Fatalf("expected snapshot path in output, got %q", got)
 	}
+	if !strings.Contains(got, "\"type\": \"resolution\"") || !strings.Contains(got, "\"query\": \"项目群\"") {
+		t.Fatalf("expected structured details in output, got %q", got)
+	}
 }

 func TestCrossPlatformCoverageRetryabilityTriStateAndRetryTiming(t *testing.T) {
@@ -171,7 +186,7 @@ func TestCrossPlatformCoverageRetryTimingOptionsIgnoreInvalidValues(t *testing.T
 	}
 }

-func TestPrintJSON_AvailableFlags(t *testing.T) {
+func TestCrossPlatformCoveragePrintJSON_AvailableFlags(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -192,7 +207,7 @@ func TestPrintJSON_AvailableFlags(t *testing.T) {
 	}
 }

-func TestPrintHuman(t *testing.T) {
+func TestCrossPlatformCoveragePrintHuman(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -201,6 +216,9 @@ func TestPrintHuman(t *testing.T) {
 		WithReason("missing_required_flag"),
 		WithOperation("calendar.list"),
 		WithServerKey("calendar"),
+		WithOrigin("client"),
+		WithFailureStage("request_validation"),
+		WithExecutionStarted(false),
 		WithHint("Pass the required flag and retry."),
 		WithRetryable(true),
 		WithActions("retry command"),
@@ -228,9 +246,19 @@ func TestPrintHuman(t *testing.T) {
 	if !strings.Contains(got, "Retryable: true") {
 		t.Fatalf("expected retryable marker in output, got %q", got)
 	}
+	for _, want := range []string{"Origin: client", "Stage: request_validation", "Execution Started: false"} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("expected %q in verbose output, got %q", want, got)
+		}
+	}
+
+	withoutDetails := NewValidation("empty", WithDetails(nil)).(*Error)
+	if withoutDetails.Details != nil {
+		t.Fatalf("empty details were retained: %#v", withoutDetails.Details)
+	}
 }

-func TestPrintHuman_NormalMode(t *testing.T) {
+func TestCrossPlatformCoveragePrintHuman_NormalMode(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -254,7 +282,7 @@ func TestPrintHuman_NormalMode(t *testing.T) {
 	}
 }

-func TestPrintJSONIncludesServerDiag(t *testing.T) {
+func TestCrossPlatformCoveragePrintJSONIncludesServerDiag(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -289,7 +317,7 @@ func TestPrintJSONIncludesServerDiag(t *testing.T) {
 	}
 }

-func TestPrintHumanIncludesServerGuidance(t *testing.T) {
+func TestCrossPlatformCoveragePrintHumanIncludesServerGuidance(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -313,7 +341,7 @@ func TestPrintHumanIncludesServerGuidance(t *testing.T) {
 	}
 }

-func TestPrintJSONIncludesRPCCodeAndData(t *testing.T) {
+func TestCrossPlatformCoveragePrintJSONIncludesRPCCodeAndData(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -335,7 +363,7 @@ func TestPrintJSONIncludesRPCCodeAndData(t *testing.T) {
 	}
 }

-func TestPrintHumanIncludesRPCCode_Debug(t *testing.T) {
+func TestCrossPlatformCoveragePrintHumanIncludesRPCCode_Debug(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -356,7 +384,7 @@ func TestPrintHumanIncludesRPCCode_Debug(t *testing.T) {
 	}
 }

-func TestPrintHumanHidesRPCCode_Normal(t *testing.T) {
+func TestCrossPlatformCoveragePrintHumanHidesRPCCode_Normal(t *testing.T) {
 	t.Parallel()

 	var b strings.Builder
@@ -69,4 +69,103 @@ func TestCrossPlatformCoverageInterfaceSummaryRemainingEdges(t *testing.T) {
 	if interfaceIdentifierOnly("含中文") {
 		t.Fatal("non-ASCII summary classified as identifier-only")
 	}
+	if !interfaceIdentifierOnly("search_open_platform-docs.v1") {
+		t.Fatal("identifier-only summary must be detected")
+	}
+	if got := summarizeInterfaceDescription("search_open_platform_docs", 40); got != "" {
+		t.Fatalf("identifier description = %q, want empty", got)
+	}
+	if got := summarizeInterfaceDescription("**查询日历。** 第二句不保留。", 40); got != "查询日历。" {
+		t.Fatalf("sentence summary = %q", got)
+	}
+	if got := summarizeInterfaceDescription("这是一个没有句号而且明显超过允许长度的接口描述文本", 12); got != "这是一个没有句号而..." {
+		t.Fatalf("truncated summary = %q", got)
+	}
+	if got := summarizeInterfaceDescription("First half, then a very long continuation without a terminal mark", 20); !strings.HasSuffix(got, "...") {
+		t.Fatalf("punctuation-cut summary = %q", got)
+	}
+	if got := interfaceSummarySource(interfaceMetadataFile{Source: "  mcp-tools  ", SourceRevision: "abcdef1234567890"}); got != "mcp-tools@abcdef123456" {
+		t.Fatalf("interfaceSummarySource = %q", got)
+	}
+	if got := interfaceSummarySource(interfaceMetadataFile{}); got != "mcp-interface" {
+		t.Fatalf("default interfaceSummarySource = %q", got)
+	}
+}
+
+func TestOverallCoverageGapInterfaceMetadataFallbackSuccessPath(t *testing.T) {
+	if err := applyInterfaceMetadataFallback(&File{}, nil, Options{}, &Stats{}, sourceTracker{}); err != nil {
+		t.Fatalf("empty InterfaceMetadataPath error = %v", err)
+	}
+	if hasSurfaceAgentSummary(File{Tools: map[string]ToolMetadata{
+		"blank": {AgentSummary: "", agentSummaryPresent: false},
+	}}, nil, "blank") {
+		t.Fatal("absent agent summary must not match")
+	}
+	if got := summarizeInterfaceDescription("first line\n\nsecond paragraph ignored", 80); got != "first line" {
+		t.Fatalf("paragraph break summary = %q", got)
+	}
+
+	display := filepath.ToSlash("interface.json")
+	body := `{
+  "version": 1,
+  "source": "mcp-tools-list+cli-registry",
+  "source_revision": "abcdef1234567890",
+  "source_hash": "sha256:interface",
+  "tools": {
+    "calendar.get": {
+      "description": "读取指定日历。",
+      "interface_ref": {"product_id": "calendar", "rpc_name": "get"}
+    },
+    "calendar.list": {
+      "description": "列出当前用户可访问的日历。后续句子不应进入 summary。"
+    },
+    "calendar.raw": {"description": "raw_tool_name"},
+    "outside.tool": {"description": "不在公开命令面"}
+  }
+}`
+	files := map[string]sourceFile{display: {display: display, data: []byte(body)}}
+	out := &File{Tools: map[string]ToolMetadata{
+		"calendar.get": {AgentSummary: "已有摘要", agentSummaryPresent: true},
+	}}
+	stats := &Stats{}
+	if err := applyInterfaceMetadataFallback(out, files, Options{
+		InterfaceMetadataPath: "interface.json",
+		ToolPaths: map[string]string{
+			"calendar.get":  "calendar get",
+			"calendar.list": "calendar list",
+			"calendar.raw":  "calendar raw",
+		},
+	}, stats, sourceTracker{}); err != nil {
+		t.Fatal(err)
+	}
+	audit := stats.InterfaceMetadata
+	if audit == nil || audit.SourceTools != 4 || audit.SurfaceTools != 3 ||
+		audit.EligibleSummaries != 2 || audit.AppliedSummaries != 1 ||
+		audit.PreservedSummaries != 1 {
+		t.Fatalf("interface audit = %#v", audit)
+	}
+	if len(audit.RejectedTools) != 1 || audit.RejectedTools[0] != "calendar.raw" ||
+		len(audit.OutsideSurface) != 1 || audit.OutsideSurface[0] != "outside.tool" {
+		t.Fatalf("interface audit paths = %#v", audit)
+	}
+	list := out.Tools["calendar.list"]
+	if list.AgentSummary != "列出当前用户可访问的日历。" {
+		t.Fatalf("applied MCP summary = %q", list.AgentSummary)
+	}
+	if list.AgentSummarySource != "mcp-tools-list+cli-registry@abcdef123456" {
+		t.Fatalf("applied summary source = %q", list.AgentSummarySource)
+	}
+	if list.Reviewed == nil || *list.Reviewed {
+		t.Fatalf("applied reviewed = %#v, want false", list.Reviewed)
+	}
+	if list.InterfaceRef != nil {
+		t.Fatalf("list tool unexpectedly gained interface_ref: %#v", list.InterfaceRef)
+	}
+	get := out.Tools["calendar.get"]
+	if get.InterfaceRef == nil || get.InterfaceRef.ProductID != "calendar" || get.InterfaceRef.RPCName != "get" {
+		t.Fatalf("preserved tool interface_ref = %#v", get.InterfaceRef)
+	}
+	if get.AgentSummary != "已有摘要" {
+		t.Fatalf("preserved summary overwritten: %#v", get)
+	}
 }
@@ -3,6 +3,7 @@ package helpers
 import (
 	"strings"

+	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"
@@ -78,6 +79,8 @@ func addAisearchPersonFlags(cmd *cobra.Command) {
 		cmd.Flags().String(alias, "", "")
 		_ = cmd.Flags().MarkHidden(alias)
 	}
+	cmd.Flags().String("type", "", "兼容选择器；person/search 路径仅接受 person/user/people")
+	_ = cmd.Flags().MarkHidden("type")
 }

 func addAisearchKeywordCompatibilityFlag(cmd *cobra.Command) {
@@ -90,6 +93,9 @@ func addAisearchKeywordCompatibilityFlag(cmd *cobra.Command) {
 // runAisearchPerson 是 aisearch person 的实际执行体，被 personCmd 和 root
 // 的智能 RunE（裸调兜底）共享调用。
 func runAisearchPerson(cmd *cobra.Command, _ []string) error {
+	if selector := strings.ToLower(strings.TrimSpace(flagValue(cmd, "type"))); selector != "" && selector != "person" && selector != "user" && selector != "people" {
+		return apperrors.NewValidation("aisearch person/search 的 --type 仅接受 person、user 或 people")
+	}
 	keyword := resolveAisearchKeyword(cmd)
 	if keyword == "" {
 		// 复用原有报错文案（"keyword is required"）
@@ -28,3 +28,13 @@ func TestCrossPlatformCoverageAISearchRemainingFallbackBranches(t *testing.T) {
 		}
 	}
 }
+
+func TestCrossPlatformCoverageAisearchPersonAcceptsRedundantTypeSelector(t *testing.T) {
+	installScriptedCaller(t, &scriptedToolCaller{dry: true})
+	if err := executeFilterCoverage(t, newAisearchCommand(), "search", "--query", "张三", "--type", "person"); err != nil {
+		t.Fatal(err)
+	}
+	if err := executeFilterCoverage(t, newAisearchCommand(), "search", "--query", "张三", "--type", "document"); err == nil {
+		t.Fatal("invalid person type selector unexpectedly succeeded")
+	}
+}
@@ -18,6 +18,7 @@ import (

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

@@ -53,6 +54,35 @@ func resolveMessageForward(cmd *cobra.Command, defaultForward bool) (bool, error
 	}
 }

+type nativeChatTargetReader struct{}
+
+func (nativeChatTargetReader) CallMCPData(product, tool string, params map[string]any) (map[string]any, error) {
+	text, err := CallMCPReadToolTextOnServer(product, tool, params)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return map[string]any{}, nil
+	}
+	var data map[string]any
+	if err := json.Unmarshal([]byte(text), &data); err != nil {
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err))
+	}
+	return data, nil
+}
+
+func resolveNativeChatTarget(raw string) (string, error) {
+	raw = strings.TrimSpace(raw)
+	if targetresolver.LooksLikeOpenConversationID(raw) {
+		return raw, nil
+	}
+	resolved, err := targetresolver.ResolveChat(nativeChatTargetReader{}, raw)
+	if err != nil {
+		return "", err
+	}
+	return resolved.Selected.OpenConversationID, nil
+}
+
 const maxConversationCategoryTitleRunes = 15

 func validatedConversationCategoryTitle(raw string) (string, error) {
@@ -78,6 +108,61 @@ func chatIntFlagOrFallback(cmd *cobra.Command, primary string, aliases ...string
 	return v
 }

+func runChatGroupSearch(cmd *cobra.Command, args []string) error {
+	keyword := flagOrFallback(cmd, "query", "keyword", "name", "group")
+	if len(args) == 1 {
+		if keyword != "" {
+			return apperrors.NewValidation("群搜索位置参数与 --query/--keyword 不能同时指定")
+		}
+		keyword = strings.TrimSpace(args[0])
+	}
+	if keyword == "" {
+		return apperrors.NewValidation("flag --query is required\n  hint: dws chat search --query \"test\"")
+	}
+	limit := chatIntFlagOrFallback(cmd, "limit", "size")
+	cursor, _ := cmd.Flags().GetString("cursor")
+	toolArgs := map[string]any{
+		"keyword": keyword,
+		"limit":   limit,
+		"cursor":  cursor,
+	}
+	if v, _ := cmd.Flags().GetBool("exclude-muted"); v {
+		toolArgs["excludeMuted"] = true
+	}
+	return callMCPToolOnServer("im", "search_groups", toolArgs)
+}
+
+func newChatGroupSearchCommand(hidden bool) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:    "search [query]",
+		Short:  "根据关键词搜索群聊",
+		Hidden: hidden,
+		Long: `根据关键词搜索群聊列表。分页参数 --limit（默认 20）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。
+
+注意：
+1. query 不要拆分得太细，应使用群名称中连续的核心词作为关键词（如群名"项目冲刺群"应搜"项目冲刺"而非拆成"项目"+"冲刺"分别搜索）。
+2. 当搜索结果返回多个群聊时，应列出候选群让用户确认目标群聊，不要自行假定并直接进行后续操作。`,
+		Example: `  dws chat search --query "项目冲刺"
+  dws chat search "项目冲刺"
+  dws chat search --query "项目冲刺" --limit 20 --cursor 0`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: runChatGroupSearch,
+	}
+	cmd.Flags().String("query", "", "搜索关键词 (必填)")
+	cmd.Flags().String("keyword", "", "--query 的别名")
+	_ = cmd.Flags().MarkHidden("keyword")
+	cmd.Flags().String("name", "", "--query 的兼容别名")
+	_ = cmd.Flags().MarkHidden("name")
+	cmd.Flags().String("group", "", "--query 的兼容别名")
+	_ = cmd.Flags().MarkHidden("group")
+	cmd.Flags().Int("limit", 20, "每页返回数量（默认 20）")
+	cmd.Flags().Int("size", 0, "--limit 的旧版别名")
+	_ = cmd.Flags().MarkHidden("size")
+	cmd.Flags().String("cursor", "0", "分页游标（默认 \"0\"，翻页传 nextCursor）")
+	cmd.Flags().Bool("exclude-muted", false, "是否排除已设置免打扰的群聊（默认 false）")
+	return cmd
+}
+
 func runChatSearchCommon(cmd *cobra.Command, _ []string) error {
 	if err := validateRequiredFlags(cmd, "nicks"); err != nil {
 		return err
@@ -1277,34 +1362,23 @@ func newChatCommand() *cobra.Command {
 		},
 	})

-	chatSearchCmd := &cobra.Command{
-		Use:   "search",
-		Short: "根据关键词搜索群聊",
-		Long: `根据关键词搜索群聊列表。分页参数 --limit（默认 20）和 --cursor（默认 "0"）始终传递；hasMore=true 时用返回的 nextCursor 作为下次 --cursor 继续翻页。
-
-注意：
-1. query 不要拆分得太细，应使用群名称中连续的核心词作为关键词（如群名"项目冲刺群"应搜"项目冲刺"而非拆成"项目"+"冲刺"分别搜索）。
-2. 当搜索结果返回多个群聊时，应列出候选群让用户确认目标群聊，不要自行假定并直接进行后续操作。`,
-		Example: `  dws chat search --query "项目冲刺"
-  dws chat search --query "项目冲刺" --limit 20 --cursor 0`,
-		RunE: func(cmd *cobra.Command, args []string) error {
-			keyword := flagOrFallback(cmd, "query", "keyword")
-			if keyword == "" {
-				return fmt.Errorf("flag --query is required\n  hint: dws chat search --query \"test\"")
-			}
-			limit := chatIntFlagOrFallback(cmd, "limit", "size")
-			cursor, _ := cmd.Flags().GetString("cursor")
-			toolArgs := map[string]any{
-				"keyword": keyword,
-				"limit":   limit,
-				"cursor":  cursor,
-			}
-			if v, _ := cmd.Flags().GetBool("exclude-muted"); v {
-				toolArgs["excludeMuted"] = true
-			}
-			return callMCPToolOnServer("im", "search_groups", toolArgs)
+	chatSearchCmd := newChatGroupSearchCommand(false)
+	chatGroupSearchCompatibilityCmd := newChatGroupSearchCommand(true)
+	cli.AttachRuntimeSchema(
+		chatGroupSearchCompatibilityCmd,
+		"chat",
+		"search_groups",
+		"reviewed-compatibility:chat-group-search",
+	)
+	cli.AnnotateRuntimeCompatibilityEquivalence(
+		chatSearchCmd,
+		chatGroupSearchCompatibilityCmd,
+		cli.RuntimeCompatibilityEquivalence{
+			ID:       "chat-group-search-compatibility-v1",
+			Reason:   "Both leaves share the same constructor, flags, positional normalization, read-only search_groups transport, and result contract.",
+			Reviewed: true,
 		},
-	}
+	)
 	DeclareLeafMetadata(chatSearchCmd, LeafSpec{
 		Safety: contract.SafetySpec{
 			Effect: "read", Risk: "low",
@@ -3353,15 +3427,6 @@ func newChatCommand() *cobra.Command {
 	chatGroupCreateCmd.Flags().String("type", "INTERNAL", "群类型: INTERNAL(内部群,默认)/EXTERNAL(外部群)/NORMAL(普通群)")
 	chatGroupCreateCmd.Flags().Bool("thread", false, "开启话题模式，将创建话题圈")

-	chatSearchCmd.Flags().String("query", "", "搜索关键词 (必填)")
-	chatSearchCmd.Flags().String("keyword", "", "--query 的别名")
-	_ = chatSearchCmd.Flags().MarkHidden("keyword")
-	chatSearchCmd.Flags().Int("limit", 20, "每页返回数量（默认 20）")
-	chatSearchCmd.Flags().Int("size", 0, "--limit 的旧版别名")
-	_ = chatSearchCmd.Flags().MarkHidden("size")
-	chatSearchCmd.Flags().String("cursor", "0", "分页游标（默认 \"0\"，翻页传 nextCursor）")
-	chatSearchCmd.Flags().Bool("exclude-muted", false, "是否排除已设置免打扰的群聊（默认 false）")
-
 	chatGroupMembersCmd.Flags().String("id", "", "群 ID / openconversation_id (必填)")
 	_ = chatGroupMembersCmd.MarkFlagRequired("id")
 	chatGroupMembersCmd.Flags().String("cursor", "", "分页游标，首次从 0 开始")
@@ -3387,7 +3452,7 @@ func newChatCommand() *cobra.Command {
 	_ = chatGroupMemberRemoveCmd.MarkFlagRequired("users")

 	chatGroupCmd.AddCommand(chatGroupCreateCmd, chatGroupMembersCmd, chatGroupRenameCmd)
-	chatGroupCmd.AddCommand(hintSubCmd("search", "use: dws chat search --query <关键词>"))
+	chatGroupCmd.AddCommand(chatGroupSearchCompatibilityCmd)
 	chatGroupMembersCmd.AddCommand(chatGroupMemberAddCmd, chatGroupMemberRemoveCmd, chatGroupMembersAddBotCmd)

 	// message 子命令 flags
@@ -3940,6 +4005,7 @@ func newChatCommand() *cobra.Command {
 	chatCategoryDeleteCmd := &cobra.Command{
 		Use:   "delete",
 		Short: "删除用户自定义会话分组",
+		Long:  "删除用户自定义会话分组。该操作不可逆；必须先获得用户确认，再追加 --yes 执行。",
 		Example: `  dws chat category delete --category-id <分组ID>
  # 分组ID 可通过 dws chat category list 获取`,
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -3947,6 +4013,14 @@ func newChatCommand() *cobra.Command {
 			if categoryId == 0 {
 				return fmt.Errorf("flag --category-id is required")
 			}
+			if !commandBoolFlag(cmd, "yes") {
+				return apperrors.NewValidation(
+					"删除会话分组不可逆；获得用户确认后加 --yes 执行",
+					apperrors.WithReason("confirmation_required"),
+					apperrors.WithHint("先确认目标分组及影响范围；用户明确同意后以相同参数追加 --yes"),
+					apperrors.WithActions("确认目标会话分组", "获得用户确认后使用 --yes 执行"),
+				)
+			}
 			return callMCPToolOnServer("im", "delete_conv_category", map[string]any{
 				"categoryId": categoryId,
 			})
@@ -6261,8 +6335,12 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			if err := validateRequiredFlags(cmd, "group"); err != nil {
 				return err
 			}
+			groupID, err := resolveNativeChatTarget(mustGetFlag(cmd, "group"))
+			if err != nil {
+				return err
+			}
 			return callMCPToolOnServer("bot", "list_group_bots", map[string]any{
-				"openConversationId": mustGetFlag(cmd, "group"),
+				"openConversationId": groupID,
 			})
 		},
 	}
@@ -6296,7 +6374,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			},
 		},
 	})
-	chatGroupBotsCmd.Flags().String("group", "", "群聊 openConversationId (必填)")
+	chatGroupBotsCmd.Flags().String("group", "", "群聊 openConversationId 或需唯一解析的群名 (必填)")
 	_ = chatGroupBotsCmd.MarkFlagRequired("group")

 	chatGroupMembersRemoveBotCmd := &cobra.Command{
@@ -6432,7 +6510,7 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 		Use:   "dismiss",
 		Short: "解散群聊",
 		Long:  `解散指定群聊。该操作不可逆，需要群主权限；必须先获得用户确认，再追加 --yes 执行。`,
-		Example: `  dws chat group dismiss --group <openConversationId> --yes
+		Example: `  dws chat group dismiss --group <openConversationId>
  # 查询群 ID: dws chat search --query "群名"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := validateRequiredFlags(cmd, "group"); err != nil {
@@ -7276,7 +7354,7 @@ status 可选值:
 	chatClearMessagesCmd := &cobra.Command{
 		Use:   "clear-messages",
 		Short: "清空当前用户指定会话的聊天记录",
-		Long: `清空当前用户在指定会话中的聊天记录。仅清空当前用户视角的消息，不影响其他成员。
+		Long: `清空当前用户在指定会话中的聊天记录。仅清空当前用户视角的消息，不影响其他成员。该操作不可逆；必须先获得用户确认，再追加 --yes 执行。

 如何获取 openConversationId（如果上层已有则直接使用，不必再查）：
  - 群聊：dws chat search --query "群名"
@@ -7288,6 +7366,14 @@ status 可选值:
 			if convID == "" {
 				return fmt.Errorf("flag --conversation-id is required\n  hint: dws chat clear-messages --conversation-id <openConversationId>")
 			}
+			if !commandBoolFlag(cmd, "yes") {
+				return apperrors.NewValidation(
+					"清空会话聊天记录不可逆；获得用户确认后加 --yes 执行",
+					apperrors.WithReason("confirmation_required"),
+					apperrors.WithHint("先确认目标会话及影响范围；用户明确同意后以相同参数追加 --yes"),
+					apperrors.WithActions("确认目标会话", "获得用户确认后使用 --yes 执行"),
+				)
+			}
 			return callMCPToolOnServer("im", "clear_conversation_messages", map[string]any{
 				"openConversationId": convID,
 			})
@@ -7763,8 +7849,8 @@ status 可选值:
 本命令升级已有普通群；新建外部群请使用 chat group create --type EXTERNAL。

 该操作不可逆，仅群主可执行。正式执行必须通过 --yes 显式确认，可先使用 --dry-run 预览。`,
-		Example: `  dws chat group upgrade-to-external --group <openConversationId> --yes
-  dws chat group upgrade-to-external --group <openConversationId> --extension '{"source":"dws"}' --yes
+		Example: `  dws chat group upgrade-to-external --group <openConversationId> --dry-run
+  dws chat group upgrade-to-external --group <openConversationId> --extension '{"source":"dws"}' --dry-run
  # 查询群 ID: dws chat search --query "群名"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := validateRequiredFlags(cmd, "group"); err != nil {
@@ -8080,10 +8166,5 @@ pl_PL, sv_SE, fi_FI, cs_CZ, ar_SA, tl_PH, he_IL, nl_NL, lo_LA, it_IT`,

 	root.AddCommand(chatChmodCmd, chatDataAuthCmd, chatGroupCmd, chatSearchCmd, chatSearchCommonCmd, chatMessageCmd, chatFileCmd, newChatMediaGroup(), chatBotCmd, chatMessageListTopConversationsCmd, chatConversationInfoCmd, chatCategoryCmd, chatGroupRoleCmd, chatMuteCmd, chatSetTopCmd, chatGroupMuteCmd, chatGroupMuteMemberCmd, chatHideCmd, chatMuteAtAllCmd, chatMuteRedEnvelopeCmd, chatMarkUnreadCmd, chatClearRedPointCmd, chatClearAllRedPointCmd, chatListAllConversationsCmd, chatClearMessagesCmd, chatMarkReadCmd, chatTextCmd)

-	// hint: dws chat send → dws chat message send
-	root.AddCommand(hintSubCmd("send", "use: dws chat message send"))
-	// hint: dws chat history → dws chat message list
-	root.AddCommand(hintSubCmd("history", "use: dws chat message list --group <GROUP_OPEN_CONVERSATION_ID>"))
-
 	return root
 }
@@ -43,6 +43,66 @@ func runChatCoverageDirect(t *testing.T, path []string, flags map[string]string)
 	return command.RunE(command, nil)
 }

+func TestCrossPlatformCoverageEvaluationRegressionChatSearchSpellingsAndNaturalBotTarget(t *testing.T) {
+	if got, err := resolveNativeChatTarget("  cid123456789  "); err != nil || got != "cid123456789" {
+		t.Fatalf("stable native chat target = %q, %v", got, err)
+	}
+	t.Run("group search path accepts query", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[]}`}}}
+		if err := runChatCoverageCommand(t, caller, "group", "search", "--query", "项目群"); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 1 {
+			t.Fatalf("calls = %d", caller.calls)
+		}
+	})
+
+	t.Run("group search accepts positional", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{{text: `{"result":[]}`}}}
+		if err := runChatCoverageCommand(t, caller, "group", "search", "项目群"); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 1 {
+			t.Fatalf("calls = %d", caller.calls)
+		}
+	})
+
+	t.Run("native bots resolves group name", func(t *testing.T) {
+		caller := &scriptedToolCaller{steps: []scriptedToolStep{
+			{text: `{"result":[{"openConversationId":"cid-project","title":"项目群"}],"hasMore":false}`},
+			{text: `{"result":{"bots":[]}}`},
+		}}
+		if err := runChatCoverageCommand(t, caller, "group", "bots", "--group", "项目群"); err != nil {
+			t.Fatal(err)
+		}
+		if caller.calls != 2 {
+			t.Fatalf("calls = %d", caller.calls)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageChatMisroutedPathsRemainUnknownSubcommands(t *testing.T) {
+	for _, tc := range []struct {
+		path string
+		flag string
+	}{
+		{path: "send", flag: "--group"},
+		{path: "history", flag: "--group"},
+	} {
+		caller := &productExampleCaller{}
+		err := runChatCoverageCommand(t, caller, tc.path, tc.flag, "cid")
+		if err == nil || !strings.Contains(err.Error(), "unknown command") || !strings.Contains(err.Error(), tc.path) {
+			t.Fatalf("chat %s error = %v, want unknown command", tc.path, err)
+		}
+		if strings.Contains(err.Error(), "unknown flag") {
+			t.Fatalf("chat %s was misreported as a flag error: %v", tc.path, err)
+		}
+		if caller.calls != 0 {
+			t.Fatalf("chat %s tool calls = %d, want 0", tc.path, caller.calls)
+		}
+	}
+}
+
 func TestCrossPlatformCoverageChatGroupUpdateIconAcceptsUploadedMediaIDPrefixes(t *testing.T) {
 	previousDeps, previousArgs := deps, os.Args
 	os.Args = []string{"dws", "chat"}
@@ -112,6 +172,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T)
 		{"message", "search", "--query=q", "--start=2026-01-02T00:00:00Z", "--end=2026-01-01T00:00:00Z"},
 		{"message", "search", "--query=q", "--start=2026-01-01T00:00:00Z", "--end=2026-01-02T00:00:00Z", "--group=cid"},
 		{"message", "recall", "--conversation-id=cid", "--msg-id=mid"},
+		{"category", "delete", "--category-id=1"},
 		{"category", "rename", "--category-id=1", "--title=renamed"},
 		{"category", "add-conv", "--group=cid", "--category-ids=1,2"},
 		{"category", "remove-conv", "--group=cid", "--category-ids=1,2"},
@@ -98,13 +98,8 @@ func TestApprovalRevokeDryRunSkipsConfirmationAndEmitsPreview(t *testing.T) {
 	}
 }

-func TestDocVersionRevertDryRunPreflightsVersionAndEmitsPreview(t *testing.T) {
-	caller := &contractDefectCaller{
-		dryRun: true,
-		responses: map[string]string{
-			"doc/list_doc_versions": `{"versions":[{"version":7}]}`,
-		},
-	}
+func TestDocVersionRevertDryRunSkipsRemotePreflightAndEmitsPreview(t *testing.T) {
+	caller := &contractDefectCaller{dryRun: true}
 	output, err := executeContractDefectCommand(t, caller, newDocCommand,
 		"version", "revert", "--node", "node-dry-run", "--version", "7", "--dry-run")
 	if err != nil {
@@ -113,10 +108,8 @@ func TestDocVersionRevertDryRunPreflightsVersionAndEmitsPreview(t *testing.T) {
 	if len(caller.calls) != 0 {
 		t.Fatalf("dry-run mutation calls = %#v, want none", caller.calls)
 	}
-	if len(caller.readCalls) != 1 ||
-		caller.readCalls[0].productID != "doc" ||
-		caller.readCalls[0].toolName != "list_doc_versions" {
-		t.Fatalf("dry-run read calls = %#v, want doc/list_doc_versions", caller.readCalls)
+	if len(caller.readCalls) != 0 {
+		t.Fatalf("dry-run read calls = %#v, want none (no remote version preflight)", caller.readCalls)
 	}
 	if !strings.Contains(output, `"tool": "revert_doc_version"`) ||
 		!strings.Contains(output, `"version": 7`) {
@@ -124,30 +117,46 @@ func TestDocVersionRevertDryRunPreflightsVersionAndEmitsPreview(t *testing.T) {
 	}
 }

-func TestDocVersionRevertDryRunRejectsMissingVersionBeforePreview(t *testing.T) {
-	caller := &contractDefectCaller{
-		dryRun: true,
-		responses: map[string]string{
-			"doc/list_doc_versions": `{"versions":[{"version":7}]}`,
-		},
-	}
+func TestDocVersionRevertDryRunDoesNotRejectMissingVersionRemotely(t *testing.T) {
+	caller := &contractDefectCaller{dryRun: true}
 	output, err := executeContractDefectCommand(t, caller, newDocCommand,
 		"version", "revert", "--node", "node-dry-run", "--version", "999", "--dry-run")
-	if err == nil || !strings.Contains(err.Error(), "文档版本 999 不存在") {
-		t.Fatalf("missing version error = %v, want explicit rejection", err)
+	if err != nil {
+		t.Fatalf("doc version revert dry-run returned error: %v", err)
 	}
-	var appErr *apperrors.Error
-	if !errors.As(err, &appErr) || appErr.Reason != "version_not_found" {
-		t.Fatalf("missing version error = %#v, want typed version_not_found", err)
-	}
-	if len(caller.readCalls) != 1 {
-		t.Fatalf("dry-run read calls = %#v, want one version lookup", caller.readCalls)
+	if len(caller.readCalls) != 0 {
+		t.Fatalf("dry-run read calls = %#v, want none (no remote version preflight)", caller.readCalls)
 	}
 	if len(caller.calls) != 0 {
 		t.Fatalf("dry-run mutation calls = %#v, want none", caller.calls)
 	}
-	if strings.Contains(output, `"tool": "revert_doc_version"`) {
-		t.Fatalf("missing version emitted a misleading mutation preview: %q", output)
+	if !strings.Contains(output, `"tool": "revert_doc_version"`) ||
+		!strings.Contains(output, `"version": 999`) {
+		t.Fatalf("dry-run output = %q, want preview without remote missing-version rejection", output)
+	}
+}
+
+func TestDocVersionRevertNonDryRunPreflightsVersion(t *testing.T) {
+	caller := &contractDefectCaller{
+		responses: map[string]string{
+			"doc/list_doc_versions":  `{"versions":[{"version":7}]}`,
+			"doc/revert_doc_version": `{}`,
+		},
+	}
+	output, err := executeContractDefectCommand(t, caller, newDocCommand,
+		"version", "revert", "--node", "node-live", "--version", "7", "--yes")
+	if err != nil {
+		t.Fatalf("doc version revert returned error: %v", err)
+	}
+	// Outside --dry-run, list_doc_versions rides the normal CallTool channel
+	// (CallReadTool is dry-run-only). Expect preflight then mutation.
+	if len(caller.calls) != 2 ||
+		caller.calls[0].productID != "doc" || caller.calls[0].toolName != "list_doc_versions" ||
+		caller.calls[1].productID != "doc" || caller.calls[1].toolName != "revert_doc_version" {
+		t.Fatalf("non-dry-run calls = %#v, want list_doc_versions then revert_doc_version", caller.calls)
+	}
+	if strings.Contains(output, `"dry_run": true`) {
+		t.Fatalf("non-dry-run output unexpectedly previewed: %q", output)
 	}
 }

@@ -2232,7 +2232,9 @@ func splitDevAppList(raw string) []string {
 }

 // transformDevAppListParam splits a comma/semicolon list for LeafFlag.Transform.
-// Empty input returns nil so the key is omitted from toolArgs.
+// Empty input (including separator-only) returns nil so optional flags omit the
+// key from toolArgs. Required flags that collapse to empty are rejected by
+// corecmd.BuildArgs after transform.
 func transformDevAppListParam(raw string) (any, error) {
 	values := splitDevAppList(raw)
 	if len(values) == 0 {
@@ -709,6 +709,33 @@ func TestDevAppEventSubscribeRequiresEventCodes(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageDevAppEventSubscribeRejectsSeparatorOnlyEventCodes(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		args []string
+	}{
+		{"subscribe_comma", []string{"dev", "app", "event", "subscribe", "--unified-app-id", "u-1", "--event-codes", ",", "--yes"}},
+		{"subscribe_semicolon", []string{"dev", "app", "event", "subscribe", "--unified-app-id", "u-1", "--event-codes", ";", "--yes"}},
+		{"unsubscribe_comma", []string{"dev", "app", "event", "unsubscribe", "--unified-app-id", "u-1", "--event-codes", ",", "--yes"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			runner := &captureRunner{}
+			root := newDevAppTestRoot(runner)
+			var out bytes.Buffer
+			root.SetOut(&out)
+			root.SetErr(&out)
+			root.SetArgs(tc.args)
+			err := root.Execute()
+			if err == nil || !strings.Contains(err.Error(), "--event-codes 为必填") {
+				t.Fatalf("Execute() error = %v, want --event-codes 为必填", err)
+			}
+			if runner.last.Tool != "" {
+				t.Fatalf("runner should not be called, got tool %q", runner.last.Tool)
+			}
+		})
+	}
+}
+
 func TestDevAppWebappCommandsBuildParams(t *testing.T) {
 	cases := []struct {
 		name       string
@@ -3911,20 +3911,22 @@ CLI 内部自动完成全部流程:
 				return fmt.Errorf("flag --version is required")
 			}
 			version, _ := cmd.Flags().GetInt("version")
-			exists, err := docVersionExists(cmd.Context(), nodeID, version)
-			if err != nil {
-				return err
-			}
-			if !exists {
-				return apperrors.NewValidation(
-					fmt.Sprintf("文档版本 %d 不存在，已停止回滚", version),
-					apperrors.WithReason("version_not_found"),
-					apperrors.WithHint(fmt.Sprintf(
-						"请先执行 dws doc version list --node %s --format json 获取可回滚版本",
-						nodeID,
-					)),
-					apperrors.WithActions("查询可用文档版本", "选择存在的版本号后重新预览"),
-				)
+			if !commandDryRun(cmd) {
+				exists, err := docVersionExists(cmd.Context(), nodeID, version)
+				if err != nil {
+					return err
+				}
+				if !exists {
+					return apperrors.NewValidation(
+						fmt.Sprintf("文档版本 %d 不存在，已停止回滚", version),
+						apperrors.WithReason("version_not_found"),
+						apperrors.WithHint(fmt.Sprintf(
+							"请先执行 dws doc version list --node %s --format json 获取可回滚版本",
+							nodeID,
+						)),
+						apperrors.WithActions("查询可用文档版本", "选择存在的版本号后重新预览"),
+					)
+				}
 			}
 			return callMCPToolOnServer("doc", "revert_doc_version", map[string]any{
 				"nodeId":  nodeID,
@@ -4230,6 +4232,16 @@ CLI 内部自动完成全部流程:
 	return root
 }

+// printDocDeprecationWarning emits a deprecation warning when shared deps are
+// initialized. Schema declaration-only roots skip InitDeps; homology and other
+// Execute probes must remain nil-safe on that path.
+func printDocDeprecationWarning(msg string) {
+	if deps == nil || deps.Out == nil {
+		return
+	}
+	deps.Out.PrintWarning(msg)
+}
+
 // wrapDocDeprecated wraps a doc command's RunE to print a deprecation warning
 // directing users to the corresponding drive command. The original command
 // continues to function normally during the transition period.
@@ -4237,7 +4249,7 @@ func wrapDocDeprecated(cmd *cobra.Command, driveSubCmd string) {
 	originalRunE := cmd.RunE
 	cmd.RunE = func(c *cobra.Command, args []string) error {
 		if strings.HasPrefix(c.CommandPath(), "dws doc ") {
-			deps.Out.PrintWarning(fmt.Sprintf(
+			printDocDeprecationWarning(fmt.Sprintf(
 				"⚠️  'dws doc %s' is deprecated, use 'dws drive %s' instead.",
 				c.CommandPath()[8:], // strip "dws doc " prefix
 				driveSubCmd,
@@ -4253,7 +4265,7 @@ func wrapDocDeprecatedToWiki(cmd *cobra.Command, wikiSubCmd string) {
 	originalRunE := cmd.RunE
 	cmd.RunE = func(c *cobra.Command, args []string) error {
 		if strings.HasPrefix(c.CommandPath(), "dws doc ") {
-			deps.Out.PrintWarning(fmt.Sprintf(
+			printDocDeprecationWarning(fmt.Sprintf(
 				"⚠️  'dws doc %s' is deprecated, use 'dws %s' instead.",
 				c.CommandPath()[8:],
 				wikiSubCmd,
@@ -4269,7 +4281,7 @@ func wrapDocDeprecatedToTarget(cmd *cobra.Command, targetCmd string) {
 	originalRunE := cmd.RunE
 	cmd.RunE = func(c *cobra.Command, args []string) error {
 		if strings.HasPrefix(c.CommandPath(), "dws doc ") {
-			deps.Out.PrintWarning(fmt.Sprintf(
+			printDocDeprecationWarning(fmt.Sprintf(
 				"⚠️  'dws doc %s' is deprecated, use 'dws %s' instead.",
 				c.CommandPath()[8:],
 				targetCmd,
@@ -173,6 +173,24 @@ func TestCrossPlatformCoverageDocDeprecationWrappersCoverage(t *testing.T) {
 			_ = cmd.RunE(cmd, nil)
 		}
 	}
+
+	// Declaration-only Schema roots leave deps nil; wrappers must not panic.
+	deps = nil
+	for _, wrap := range []func(*cobra.Command){
+		func(cmd *cobra.Command) { wrapDocDeprecated(cmd, "drive target") },
+		func(cmd *cobra.Command) { wrapDocDeprecatedToWiki(cmd, "wiki target") },
+		func(cmd *cobra.Command) { wrapDocDeprecatedToTarget(cmd, "target") },
+	} {
+		cmd := &cobra.Command{Use: "leaf", RunE: func(*cobra.Command, []string) error { return nil }}
+		wrap(cmd)
+		root := &cobra.Command{Use: "dws"}
+		doc := &cobra.Command{Use: "doc"}
+		root.AddCommand(doc)
+		doc.AddCommand(cmd)
+		if err := cmd.RunE(cmd, nil); err != nil {
+			t.Fatalf("nil-deps deprecation wrapper: %v", err)
+		}
+	}
 }

 func TestCrossPlatformCoverageRunDocUploadDownloadAndMediaCoverage(t *testing.T) {
@@ -0,0 +1,34 @@
+// 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 (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+// Test helpers for package-level deps. Production code must not call these;
+// the ForTest suffix is the boundary.
+
+// InitDepsForTest installs caller for the test duration and restores the prior
+// deps pointer (including a prior nil) via testseam. Prefer this over
+// InitDeps + InitDeps(previousCaller): restoring through InitDeps(nil) leaves a
+// non-nil Deps with a nil Caller, which is not the original unset state.
+func InitDepsForTest(t *testing.T, caller edition.ToolCaller) {
+	t.Helper()
+	testseam.Protect(t, &deps)
+	InitDeps(caller)
+}
@@ -0,0 +1,38 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+import (
+	"context"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)
+
+type fortestCoverageCaller struct{}
+
+func (fortestCoverageCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+	return &edition.ToolResult{}, nil
+}
+func (fortestCoverageCaller) Format() string { return "json" }
+func (fortestCoverageCaller) DryRun() bool   { return false }
+func (fortestCoverageCaller) Fields() string { return "" }
+func (fortestCoverageCaller) JQ() string     { return "" }
+
+// TestCrossPlatformCoverageInitDepsForTestRestoresPriorDeps covers the
+// ForTest deps restore helper used by declaration-only Schema probes.
+func TestCrossPlatformCoverageInitDepsForTestRestoresPriorDeps(t *testing.T) {
+	testseam.Protect(t, &deps)
+	deps = nil
+
+	marker := fortestCoverageCaller{}
+	InitDepsForTest(t, marker)
+	if got := GetCaller(); got != marker {
+		t.Fatalf("GetCaller() during InitDepsForTest = %T, want marker", got)
+	}
+	if deps == nil {
+		t.Fatal("InitDepsForTest left deps nil before test cleanup")
+	}
+}
@@ -64,6 +64,7 @@ func TestCrossPlatformCoverageReadToolNameContractAndHelperBoundary(t *testing.T
 		"LIST_MESSAGES":                    true,
 		"query_send_status":                true,
 		"search_messages":                  true,
+		"enterprise_person_search":         true,
 		"unread_message_conversation_list": true,
 		"send_personal_message":            false,
 		"":                                 false,
@@ -190,6 +190,9 @@ func callMCPReadToolReturnTextOnServer(ctx context.Context, serverID, toolName s
 // ReadToolCaller.
 func IsReadToolName(toolName string) bool {
 	toolName = strings.TrimSpace(strings.ToLower(toolName))
+	if toolName == "enterprise_person_search" {
+		return true
+	}
 	for _, prefix := range []string{
 		"get_", "list_", "query_", "search_", "unread_",
 	} {
@@ -229,6 +229,15 @@ func TestLeafArgs(t *testing.T) {

 func TestLeafArgsOmitsEmptyAndNonPositive(t *testing.T) {
 	cmd := NewLeafCommand(leafTestSpec())
+	// Satisfy Required flags first: BuildArgs now rejects Required transforms that
+	// collapse to empty (unset CSV), matching runtime behavior after ValidateRequired.
+	t.Setenv("DWS_LEAF_TEST_TOKEN", "tok")
+	if err := cmd.Flags().Set("users", "u1"); err != nil {
+		t.Fatal(err)
+	}
+	if err := cmd.Flags().Set("content", "hello"); err != nil {
+		t.Fatal(err)
+	}
 	args, err := corecmd.BuildArgs(cmd, leafTestSpec().Flags)
 	if err != nil {
 		t.Fatalf("leafArgs() error = %v", err)
@@ -239,10 +248,8 @@ func TestLeafArgsOmitsEmptyAndNonPositive(t *testing.T) {
 	if _, present := args["cursor"]; present {
 		t.Fatalf("cursor present = %v, want omitted when zero", args["cursor"])
 	}
-	// 未配置 OmitEmpty 的 flag 即使为空也入参（复现手写语义；Required 校验在
-	// leafArgs 之前执行，保证真实路径不会发出空值）。
-	if v, present := args["accessToken"]; !present || v != "" {
-		t.Fatalf("accessToken = %v/%v, want present-but-empty without OmitEmpty", v, present)
+	if v, present := args["accessToken"]; !present || v != "tok" {
+		t.Fatalf("accessToken = %v/%v, want env tok", v, present)
 	}
 	// 未设置 OmitEmpty 的字符串即使为空也入参（复现手写 remindType 恒入参语义）。
 	if v, present := args["remindType"]; !present || v != "app" {
@@ -1,21 +1,55 @@
 package helpers

 import (
+	"bytes"
+	"encoding/json"
+	"errors"
 	"fmt"
+	"io"
 	"strconv"
 	"strings"

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

+func decodeOARequest(raw string) (map[string]any, error) {
+	dec := json.NewDecoder(bytes.NewBufferString(raw))
+	dec.UseNumber()
+	var request map[string]any
+	if err := dec.Decode(&request); err != nil || request == nil {
+		if err != nil {
+			return nil, err
+		}
+		return nil, fmt.Errorf("JSON 请求不能为 null")
+	}
+	if err := dec.Decode(new(any)); !errors.Is(err, io.EOF) {
+		return nil, fmt.Errorf("JSON 请求包含多余内容")
+	}
+	return request, nil
+}
+
+func oaFormValues(raw string) ([]map[string]string, error) {
+	var values map[string]string
+	if err := json.Unmarshal([]byte(raw), &values); err != nil {
+		return nil, err
+	}
+	result := make([]map[string]string, 0, len(values))
+	for name, value := range values {
+		result = append(result, map[string]string{"name": name, "value": value})
+	}
+	return result, nil
+}
+
 // ──────────────────────────────────────────────────────────
 // dws oa — OA 审批
 // MCP tools（tools/list）: list_pending_approvals, get_processInstance_detail,
 // approve_processInstance, reject_processInstance, revoke_processInstance,
 // 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_inst_revert_activities, get_process_schema, forecast_process,
+// start_process_instance
 // ──────────────────────────────────────────────────────────

 func newOaCommand() *cobra.Command {
@@ -1017,6 +1051,195 @@ func newOaCommand() *cobra.Command {
 		},
 	}

+	approvalFormSchemaCmd := &cobra.Command{
+		Use: "form-schema", Short: "查询审批模板的表单 Schema",
+		Example: "dws oa approval form-schema --process-code <processCode>",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := validateRequiredFlags(cmd, "process-code"); err != nil {
+				return err
+			}
+			return callMCPTool("get_process_schema", map[string]any{"processCode": mustGetFlag(cmd, "process-code")})
+		},
+	}
+	DeclareLeafMetadata(approvalFormSchemaCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "get_process_schema",
+				CanonicalPath:  "oa.get_process_schema",
+				CLIPath:        "oa approval form-schema",
+				PrimaryCLIPath: "oa approval form-schema",
+			},
+			Description: "查询审批模板的表单 Schema",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "get_process_schema"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "查询审批模板的表单 Schema",
+				UseWhen:      []string{"已从 list-forms 或 search-forms 获得 processCode，需要读取字段、选项和必填规则后再填写审批时"},
+				AvoidWhen:    []string{"只需列出可用模板时使用 list-forms；不要把返回的 Schema 当作可直接提交的实例请求"},
+				Examples:     []string{"dws oa approval form-schema --process-code <processCode>"},
+			},
+			Parameters: []contract.ParamDecl{
+				{Name: "process-code", Property: "processCode"},
+			},
+		},
+	})
+	approvalForecastCmd := &cobra.Command{
+		Use: "forecast-process", Short: "根据表单值预测审批流程与自选节点",
+		Example: "dws oa approval forecast-process --process-code <processCode> --dept-id -1 --form-values '{\"金额\":\"100\"}'",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if raw, _ := cmd.Flags().GetString("request"); raw != "" {
+				request, err := decodeOARequest(raw)
+				if err != nil {
+					return fmt.Errorf("--request JSON 解析失败: %w", err)
+				}
+				return callMCPTool("forecast_process", map[string]any{"ProcessForecastPopRequest": request})
+			}
+			if err := validateRequiredFlags(cmd, "process-code", "dept-id", "form-values"); err != nil {
+				return err
+			}
+			deptID, err := strconv.ParseInt(mustGetFlag(cmd, "dept-id"), 10, 64)
+			if err != nil {
+				return fmt.Errorf("--dept-id 必须为整数: %w", err)
+			}
+			values, err := oaFormValues(mustGetFlag(cmd, "form-values"))
+			if err != nil {
+				return fmt.Errorf("--form-values JSON 解析失败: %w", err)
+			}
+			return callMCPTool("forecast_process", map[string]any{"ProcessForecastPopRequest": map[string]any{"processCode": mustGetFlag(cmd, "process-code"), "deptId": deptID, "formComponentValues": [][]map[string]string{values}}})
+		},
+	}
+	DeclareLeafMetadata(approvalForecastCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "forecast_process",
+				CanonicalPath:  "oa.forecast_process",
+				CLIPath:        "oa approval forecast-process",
+				PrimaryCLIPath: "oa approval forecast-process",
+			},
+			Description: "根据表单值预测审批流程与自选节点",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "forecast_process"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "预测审批流程与自选审批节点",
+				UseWhen:      []string{"已知道 processCode 且已根据表单 Schema 组装字段，需要在发起前确认审批路径或自选节点时"},
+				AvoidWhen:    []string{"需要真正创建审批单时改用 create-instance；未获得字段定义时先用 form-schema"},
+				Examples: []string{
+					"dws oa approval forecast-process --process-code <processCode> --dept-id -1 --form-values '{\"金额\":\"100\"}'",
+					"dws oa approval forecast-process --request '{\"processCode\":\"PROC-xxx\",\"deptId\":-1,\"formComponentValues\":[[{\"name\":\"金额\",\"value\":\"100\"}]]}'",
+				},
+			},
+			// Simple-mode flags are mapping exclusions (encoded inside ProcessForecastPopRequest).
+			Parameters: []contract.ParamDecl{
+				{Name: "request", Property: "ProcessForecastPopRequest", InterfaceType: "object"},
+			},
+		},
+	})
+	approvalCreateCmd := &cobra.Command{
+		Use: "create-instance", Short: "发起审批实例（需要 --yes 确认）",
+		Example: "dws oa approval create-instance --process-code <processCode> --form-values '{\"事由\":\"测试\"}' --yes",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if !commandDryRun(cmd) {
+				yes, _ := cmd.Flags().GetBool("yes")
+				if !yes {
+					return fmt.Errorf("发起审批实例会创建真实业务数据；请先核对参数，然后添加 --yes 确认执行")
+				}
+			}
+			var request map[string]any
+			if raw, _ := cmd.Flags().GetString("request"); raw != "" {
+				var err error
+				request, err = decodeOARequest(raw)
+				if err != nil {
+					return fmt.Errorf("--request JSON 解析失败: %w", err)
+				}
+			} else {
+				if err := validateRequiredFlags(cmd, "process-code", "form-values"); err != nil {
+					return err
+				}
+				values, err := oaFormValues(mustGetFlag(cmd, "form-values"))
+				if err != nil {
+					return fmt.Errorf("--form-values JSON 解析失败: %w", err)
+				}
+				request = map[string]any{"processCode": mustGetFlag(cmd, "process-code"), "formComponentValues": values}
+				if dept, _ := cmd.Flags().GetString("dept-id"); dept != "" {
+					value, err := strconv.ParseInt(dept, 10, 64)
+					if err != nil {
+						return fmt.Errorf("--dept-id 必须为整数: %w", err)
+					}
+					request["deptId"] = value
+				}
+				if userID, _ := cmd.Flags().GetString("originator-user-id"); userID != "" {
+					request["originatorUserId"] = userID
+				}
+				if rawApprovers, _ := cmd.Flags().GetString("approvers"); rawApprovers != "" {
+					action, _ := cmd.Flags().GetString("approvers-action-type")
+					if action != "AND" && action != "OR" && action != "NONE" {
+						return fmt.Errorf("--approvers-action-type 必须为 AND、OR 或 NONE")
+					}
+					request["approvers"] = []map[string]any{{"actionType": action, "userIds": strings.Split(rawApprovers, ",")}}
+				}
+				if rawCC, _ := cmd.Flags().GetString("cc-list"); rawCC != "" {
+					position, _ := cmd.Flags().GetString("cc-position")
+					if position != "START" && position != "FINISH" && position != "START_FINISH" {
+						return fmt.Errorf("--cc-position 必须为 START、FINISH 或 START_FINISH")
+					}
+					request["ccList"] = strings.Split(rawCC, ",")
+					request["ccPosition"] = position
+				}
+			}
+			return callMCPTool("start_process_instance", map[string]any{"ProcessInstanceCreationPopRequest": request})
+		},
+	}
+	DeclareLeafMetadata(approvalCreateCmd, LeafSpec{
+		Safety: contract.SafetySpec{
+			Effect: "write", Risk: "high",
+			Confirmation: "user_required", Idempotency: "non_idempotent",
+		},
+		Contract: LeafContract{
+			Identity: contract.ToolIdentitySpec{
+				ProductID:      "oa",
+				Name:           "start_process_instance",
+				CanonicalPath:  "oa.start_process_instance",
+				CLIPath:        "oa approval create-instance",
+				PrimaryCLIPath: "oa approval create-instance",
+			},
+			Description: "发起审批实例（需要 --yes 确认）",
+			Interface: &contract.InterfaceSpec{
+				Mode:         "mcp",
+				Availability: "available",
+				Ref:          &contract.InterfaceRefSpec{ProductID: "oa", RPCName: "start_process_instance"},
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "发起新的审批实例",
+				UseWhen:      []string{"用户确认要发起审批，且已查询表单 Schema、核对字段及审批路径后使用"},
+				AvoidWhen:    []string{"只需预测流程时使用 forecast-process；用户尚未确认或字段未按 Schema 核对时不要发起"},
+				Examples: []string{
+					"dws oa approval create-instance --process-code <processCode> --form-values '{\"事由\":\"测试\"}'",
+					"dws oa approval create-instance --request '{\"processCode\":\"PROC-xxx\",\"deptId\":-1,\"formComponentValues\":[{\"name\":\"事由\",\"value\":\"测试\"}],\"targetSelectActioners\":[{\"actionerKey\":\"manual-node\",\"actionerStaffIds\":[\"user-id\"]}]}'",
+				},
+			},
+			// Simple-mode flags are mapping exclusions (encoded inside ProcessInstanceCreationPopRequest).
+			Parameters: []contract.ParamDecl{
+				{Name: "request", Property: "ProcessInstanceCreationPopRequest", InterfaceType: "object"},
+			},
+		},
+	})
+
 	approvalListPendingCmd.Flags().String("start", "", "开始时间 ISO-8601 (如 2026-03-10T00:00:00+08:00) (必填)")
 	approvalListPendingCmd.Flags().String("end", "", "结束时间 ISO-8601 (如 2026-03-10T23:59:59+08:00) (必填)")
 	approvalListPendingCmd.Flags().String("page", "", "分页页码 (可选)")
@@ -1087,6 +1310,46 @@ func newOaCommand() *cobra.Command {
 	approvalRevertTaskCmd.Flags().String("target-activity-id", "", "退回到的节点 ID（退回发起人固定传 sid-startevent）(必填)")
 	approvalRevertTaskCmd.Flags().String("action", "", "退回方式：REVERT_FOR_APPROVAL（退回到审批人）/ REVERT_FOR_RESUBMIT（退回到发起人）(必填)")
 	approvalRevertTaskCmd.Flags().String("remark", "", "退回说明 (可选)")
+	approvalFormSchemaCmd.Flags().String("process-code", "", "审批模板 processCode (必填)")
+	approvalForecastCmd.Flags().String("process-code", "", "审批模板 processCode（简单模式使用；与 --request 互斥）")
+	approvalForecastCmd.Flags().String("dept-id", "", "发起人部门 ID（简单模式使用；与 --request 互斥）")
+	approvalForecastCmd.Flags().String("form-values", "", "表单值 JSON（简单模式使用；与 --request 互斥）")
+	approvalForecastCmd.Flags().String("request", "", "完整请求 JSON（高级模式；与简单模式参数互斥）")
+	approvalForecastCmd.MarkFlagsOneRequired("request", "process-code")
+	approvalForecastCmd.MarkFlagsRequiredTogether("process-code", "dept-id", "form-values")
+	forecastMutuallyExclusive := make([][]string, 0, 3)
+	for _, name := range []string{"process-code", "dept-id", "form-values"} {
+		approvalForecastCmd.MarkFlagsMutuallyExclusive("request", name)
+		forecastMutuallyExclusive = append(forecastMutuallyExclusive, []string{"request", name})
+	}
+	cli.AnnotateRuntimeConstraints(approvalForecastCmd, cli.RuntimeSchemaConstraints{
+		MutuallyExclusive: forecastMutuallyExclusive,
+		RequireOneOf:      [][]string{{"request", "process-code"}},
+		RequireTogether:   [][]string{{"process-code", "dept-id", "form-values"}},
+	})
+
+	approvalCreateCmd.Flags().String("process-code", "", "审批模板 processCode（简单模式使用；与 --request 互斥）")
+	approvalCreateCmd.Flags().String("dept-id", "-1", "发起人部门 ID")
+	approvalCreateCmd.Flags().String("form-values", "", "表单值 JSON（简单模式使用；与 --request 互斥）")
+	approvalCreateCmd.Flags().String("request", "", "完整请求 JSON（高级模式；与简单模式参数互斥）")
+	approvalCreateCmd.Flags().String("originator-user-id", "", "审批发起人 userId")
+	approvalCreateCmd.Flags().String("approvers", "", "审批人 userId 列表，多个用逗号分隔")
+	approvalCreateCmd.Flags().String("approvers-action-type", "OR", "审批类型：AND、OR 或 NONE")
+	approvalCreateCmd.Flags().String("cc-list", "", "抄送人 userId 列表，多个用逗号分隔")
+	approvalCreateCmd.Flags().String("cc-position", "START", "抄送时点：START、FINISH 或 START_FINISH")
+	approvalCreateCmd.MarkFlagsOneRequired("request", "process-code")
+	approvalCreateCmd.MarkFlagsRequiredTogether("process-code", "form-values")
+	createSimpleFlags := []string{"process-code", "dept-id", "form-values", "originator-user-id", "approvers", "approvers-action-type", "cc-list", "cc-position"}
+	createMutuallyExclusive := make([][]string, 0, len(createSimpleFlags))
+	for _, name := range createSimpleFlags {
+		approvalCreateCmd.MarkFlagsMutuallyExclusive("request", name)
+		createMutuallyExclusive = append(createMutuallyExclusive, []string{"request", name})
+	}
+	cli.AnnotateRuntimeConstraints(approvalCreateCmd, cli.RuntimeSchemaConstraints{
+		MutuallyExclusive: createMutuallyExclusive,
+		RequireOneOf:      [][]string{{"request", "process-code"}},
+		RequireTogether:   [][]string{{"process-code", "form-values"}},
+	})

 	approvalCmd.AddCommand(
 		approvalListPendingCmd,
@@ -1109,6 +1372,9 @@ func newOaCommand() *cobra.Command {
 		approvalAppendTaskCmd,
 		approvalRevertActivitiesCmd,
 		approvalRevertTaskCmd,
+		approvalFormSchemaCmd,
+		approvalForecastCmd,
+		approvalCreateCmd,
 	)
 	root.AddCommand(approvalCmd)

@@ -1,6 +1,34 @@
 package helpers

-import "testing"
+import (
+	"io"
+	"os"
+	"strings"
+	"testing"
+)
+
+func executeOACommand(t *testing.T, caller *scriptedToolCaller, args ...string) error {
+	t.Helper()
+	previous := deps
+	previousArgs := os.Args
+	os.Args = []string{"dws", "oa"}
+	InitDeps(caller)
+	deps.Out.w = io.Discard
+	deps.Out.errW = io.Discard
+	t.Cleanup(func() {
+		deps = previous
+		os.Args = previousArgs
+	})
+
+	cmd := newOaCommand()
+	cmd.PersistentFlags().Bool("yes", false, "跳过确认")
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	cmd.SetOut(io.Discard)
+	cmd.SetErr(io.Discard)
+	cmd.SetArgs(args)
+	return cmd.Execute()
+}

 func TestCrossPlatformCoverageOARemainingTimeAndRevertBranches(t *testing.T) {
 	installScriptedCaller(t, &scriptedToolCaller{dry: true})
@@ -31,3 +59,143 @@ func TestCrossPlatformCoverageOARemainingTimeAndRevertBranches(t *testing.T) {
 		t.Fatalf("revert task: %v", err)
 	}
 }
+
+func TestCrossPlatformCoverageOAApprovalCreateInstanceMapsInternalSimpleOptions(t *testing.T) {
+	caller := &scriptedToolCaller{}
+	err := executeOACommand(t, caller,
+		"approval", "create-instance",
+		"--process-code", "PROC",
+		"--form-values", `{"事由":"测试"}`,
+		"--originator-user-id", "originator",
+		"--approvers", "approver-1,approver-2",
+		"--approvers-action-type", "AND",
+		"--cc-list", "cc-1,cc-2",
+		"--cc-position", "FINISH",
+		"--yes",
+	)
+	if err != nil {
+		t.Fatalf("create instance: %v", err)
+	}
+	if caller.server != "oa" || caller.tool != "start_process_instance" {
+		t.Fatalf("called %s/%s, want oa/start_process_instance", caller.server, caller.tool)
+	}
+	request, ok := caller.args["ProcessInstanceCreationPopRequest"].(map[string]any)
+	if !ok {
+		t.Fatalf("request payload = %#v", caller.args)
+	}
+	if got := request["originatorUserId"]; got != "originator" {
+		t.Fatalf("originatorUserId = %#v", got)
+	}
+	approvers, ok := request["approvers"].([]map[string]any)
+	if !ok || len(approvers) != 1 || approvers[0]["actionType"] != "AND" {
+		t.Fatalf("approvers = %#v", request["approvers"])
+	}
+	if got := approvers[0]["userIds"]; len(got.([]string)) != 2 || got.([]string)[0] != "approver-1" || got.([]string)[1] != "approver-2" {
+		t.Fatalf("approver userIds = %#v", got)
+	}
+	if got := request["ccList"]; len(got.([]string)) != 2 || got.([]string)[0] != "cc-1" || got.([]string)[1] != "cc-2" {
+		t.Fatalf("ccList = %#v", got)
+	}
+	if got := request["ccPosition"]; got != "FINISH" {
+		t.Fatalf("ccPosition = %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageOAApprovalCreateInstanceRejectsMixedRequestModes(t *testing.T) {
+	caller := &scriptedToolCaller{}
+	err := executeOACommand(t, caller,
+		"approval", "create-instance",
+		"--request", `{"processCode":"PROC"}`,
+		"--process-code", "PROC",
+		"--yes",
+	)
+	if err == nil {
+		t.Fatal("mixed request modes returned nil")
+	}
+	if caller.calls != 0 {
+		t.Fatalf("unexpected MCP call count: %d", caller.calls)
+	}
+}
+
+func TestCrossPlatformCoverageOAApprovalCreateInstanceRequiresExplicitYes(t *testing.T) {
+	caller := &scriptedToolCaller{}
+	err := executeOACommand(t, caller,
+		"approval", "create-instance",
+		"--request", `{"processCode":"PROC"}`,
+	)
+	if err == nil || !strings.Contains(err.Error(), "--yes") {
+		t.Fatalf("create instance without --yes error = %v, want explicit --yes requirement", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("create instance without --yes made %d MCP calls", caller.calls)
+	}
+}
+
+func TestCrossPlatformCoverageOAApprovalNewCommandValidationAndRequestModes(t *testing.T) {
+	validCases := []struct {
+		name string
+		args []string
+		tool string
+	}{
+		{
+			name: "form schema",
+			args: []string{"approval", "form-schema", "--process-code", "PROC"},
+			tool: "get_process_schema",
+		},
+		{
+			name: "forecast simple mode",
+			args: []string{"approval", "forecast-process", "--process-code", "PROC", "--dept-id", "-1", "--form-values", `{"金额":"100"}`},
+			tool: "forecast_process",
+		},
+		{
+			name: "forecast request mode",
+			args: []string{"approval", "forecast-process", "--request", `{"processCode":"PROC"}`},
+			tool: "forecast_process",
+		},
+		{
+			name: "create request mode",
+			args: []string{"approval", "create-instance", "--request", `{"processCode":"PROC"}`, "--yes"},
+			tool: "start_process_instance",
+		},
+	}
+	for _, tc := range validCases {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			if err := executeOACommand(t, caller, tc.args...); err != nil {
+				t.Fatalf("execute %v: %v", tc.args, err)
+			}
+			if caller.tool != tc.tool || caller.calls != 1 {
+				t.Fatalf("called tool=%q calls=%d, want %q once", caller.tool, caller.calls, tc.tool)
+			}
+		})
+	}
+
+	invalidCases := [][]string{
+		{"approval", "form-schema"},
+		{"approval", "forecast-process"},
+		{"approval", "forecast-process", "--request", `{"processCode":"PROC"}`, "--process-code", "PROC"},
+		{"approval", "forecast-process", "--request", "{"},
+		{"approval", "forecast-process", "--request", "null"},
+		{"approval", "forecast-process", "--request", "{} {}"},
+		{"approval", "forecast-process", "--process-code", "PROC", "--dept-id", "bad", "--form-values", `{"金额":"100"}`},
+		{"approval", "forecast-process", "--process-code", "PROC", "--dept-id", "-1", "--form-values", "["},
+		{"approval", "create-instance", "--process-code", "PROC", "--form-values", `{}`},
+		{"approval", "create-instance", "--yes"},
+		{"approval", "create-instance", "--request", "{", "--yes"},
+		{"approval", "create-instance", "--request", "null", "--yes"},
+		{"approval", "create-instance", "--request", "{} {}", "--yes"},
+		{"approval", "create-instance", "--process-code", "PROC", "--form-values", "[", "--yes"},
+		{"approval", "create-instance", "--process-code", "PROC", "--form-values", `{}`, "--dept-id", "bad", "--yes"},
+		{"approval", "create-instance", "--process-code", "PROC", "--form-values", `{}`, "--approvers", "u", "--approvers-action-type", "bad", "--yes"},
+		{"approval", "create-instance", "--process-code", "PROC", "--form-values", `{}`, "--cc-list", "u", "--cc-position", "bad", "--yes"},
+	}
+	for _, args := range invalidCases {
+		caller := &scriptedToolCaller{}
+		if err := executeOACommand(t, caller, args...); err == nil {
+			t.Fatalf("invalid args %v returned nil", args)
+		}
+		if caller.calls != 0 {
+			t.Fatalf("invalid args %v made %d MCP calls", args, caller.calls)
+		}
+	}
+}
@@ -24,10 +24,16 @@ type scriptedToolCaller struct {
 	format string
 	dry    bool
 	calls  int
+	server string
+	tool   string
+	args   map[string]any
 }

-func (c *scriptedToolCaller) CallTool(context.Context, string, string, map[string]any) (*edition.ToolResult, error) {
+func (c *scriptedToolCaller) CallTool(_ context.Context, serverID, toolName string, args map[string]any) (*edition.ToolResult, error) {
 	c.calls++
+	c.server = serverID
+	c.tool = toolName
+	c.args = args
 	if len(c.steps) == 0 {
 		return &edition.ToolResult{}, nil
 	}
@@ -271,6 +271,10 @@ func TestCrossPlatformCoverageProtectSheetMutationCommandPanics(t *testing.T) {
 func TestSheetMutationGuardRejectsPipedYesEvenWithContractConfirmSafety(t *testing.T) {
 	// Sheet agent hardening: outer --yes-only gate must win over ConfirmSafety
 	// honoring piped stdin yes (review: delete-sheet / range clear / version revert).
+	// This fixture exercises the no-caller fallback. Isolate it from commands
+	// built by earlier tests, which may initialize the package-level deps.
+	testseam.Protect(t, &deps)
+	deps = nil
 	ran := false
 	cmd := &cobra.Command{
 		Use: "delete-sheet",
@@ -0,0 +1,30 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+// Package profilectx owns the process-local profile selector without importing
+// authentication or transport packages.
+package profilectx
+
+import (
+	"strings"
+	"sync"
+)
+
+var (
+	runtimeProfileMu sync.RWMutex
+	runtimeProfile   string
+)
+
+// Set records the explicit profile selector for the current process.
+func Set(profile string) {
+	runtimeProfileMu.Lock()
+	defer runtimeProfileMu.Unlock()
+	runtimeProfile = strings.TrimSpace(profile)
+}
+
+// Get returns the explicit process-local profile selector.
+func Get() string {
+	runtimeProfileMu.RLock()
+	defer runtimeProfileMu.RUnlock()
+	return runtimeProfile
+}
@@ -0,0 +1,20 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package profilectx
+
+import "testing"
+
+func TestCrossPlatformCoverageSetAndGet(t *testing.T) {
+	t.Cleanup(func() { Set("") })
+
+	Set("  fixture-profile  ")
+	if got := Get(); got != "fixture-profile" {
+		t.Fatalf("Get() = %q, want fixture-profile", got)
+	}
+
+	Set("")
+	if got := Get(); got != "" {
+		t.Fatalf("Get() after reset = %q, want empty", got)
+	}
+}
@@ -36,6 +36,16 @@ func FromShortcut(s Shortcut) corecmd.Spec {
 	if !safetySpecDeclared(safety) {
 		safety = shortcutSafetySpec(s.risk())
 	}
+	declaredContract := s.Contract
+	if !declaredContract.Empty() && len(s.Aliases) > 0 && len(declaredContract.Identity.Aliases) == 0 {
+		declaredContract.Identity.Aliases = make([]string, 0, len(s.Aliases))
+		for _, alias := range s.Aliases {
+			declaredContract.Identity.Aliases = append(
+				declaredContract.Identity.Aliases,
+				s.Service+" "+strings.TrimSpace(alias),
+			)
+		}
+	}
 	return corecmd.Spec{
 		Use:     s.Command,
 		Short:   s.Description,
@@ -47,11 +57,12 @@ func FromShortcut(s Shortcut) corecmd.Spec {
 		Flags:       fromShortcutFlags(s.Flags),
 		Constraints: fromShortcutConstraints(s.Constraints),
 		Safety:      safety,
-		Contract:    s.Contract,
+		Contract:    declaredContract,
 		// Preserve the shipped Shortcut Catalog provenance: Cobra remains the
 		// source for type/default/usage, while command adds Required/Enum/rules.
 		ParameterProjection: corecmd.ProjectCobraParameters,
 		Validate:            fromShortcutValidate(s),
+		PostMount:           fromShortcutPostMount(s),
 		// Multi-step body: command stays backend-agnostic, so the shortcut's own
 		// RuntimeContext — which owns CallMCPData/CallMCPWriteData/Output — is
 		// built here from the Ctx's command.
@@ -65,6 +76,40 @@ func FromShortcut(s Shortcut) corecmd.Spec {
 	}
 }

+func fromShortcutPostMount(s Shortcut) func(*cobra.Command) {
+	if len(s.Aliases) == 0 && strings.TrimSpace(s.SinglePositionalAliasFor) == "" {
+		return nil
+	}
+	return func(cmd *cobra.Command) {
+		cmd.Aliases = append([]string(nil), s.Aliases...)
+		name := strings.TrimSpace(s.SinglePositionalAliasFor)
+		if name == "" {
+			return
+		}
+		cmd.Args = func(cmd *cobra.Command, args []string) error {
+			if err := cobra.MaximumNArgs(1)(cmd, args); err != nil {
+				return err
+			}
+			if len(args) == 0 {
+				return nil
+			}
+			flag := cmd.Flags().Lookup(name)
+			if flag == nil {
+				return apperrors.NewInternal(fmt.Sprintf(
+					"shortcut %s %s positional alias flag --%s is not registered",
+					s.Service, s.Command, name))
+			}
+			if flag.Changed {
+				return apperrors.NewValidation(fmt.Sprintf("位置参数与 --%s 不能同时提供", name))
+			}
+			if err := cmd.Flags().Set(name, args[0]); err != nil {
+				return apperrors.NewValidation(fmt.Sprintf("位置参数无法写入 --%s: %v", name, err))
+			}
+			return nil
+		}
+	}
+}
+
 func safetySpecDeclared(safety contract.SafetySpec) bool {
 	return strings.TrimSpace(safety.Effect) != "" ||
 		strings.TrimSpace(safety.Risk) != "" ||
@@ -133,6 +178,7 @@ func fromShortcutFlags(flags []Flag) []corecmd.FlagSpec {
 	for _, f := range flags {
 		out = append(out, corecmd.FlagSpec{
 			Name:           f.Name,
+			Shorthand:      f.Shorthand,
 			Usage:          flagHelp(f),
 			Kind:           fromShortcutFlagKind(f.Type),
 			Default:        f.Default,
@@ -20,6 +20,7 @@ import (
 	"github.com/spf13/pflag"

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

 // TestCrossPlatformCoverageFromShortcutMapsSharedBase verifies FromShortcut
@@ -33,7 +34,7 @@ func TestCrossPlatformCoverageFromShortcutMapsSharedBase(t *testing.T) {
 		Hidden:      true,
 		Tips:        []string{"dws chat +demo --name a"},
 		Flags: []Flag{
-			{Name: "name", Type: FlagString, Desc: "名称", Required: true, Default: "d", Enum: []string{"a", "b"}, Hidden: true},
+			{Name: "name", Shorthand: "n", Type: FlagString, Desc: "名称", Required: true, Default: "d", Enum: []string{"a", "b"}, Hidden: true},
 			{Name: "count", Type: FlagInt, Desc: "数量"},
 			{Name: "flag", Type: FlagBool, Desc: "开关"},
 			{Name: "ids", Type: FlagStringSlice, Desc: "列表"},
@@ -85,7 +86,7 @@ func TestCrossPlatformCoverageFromShortcutMapsSharedBase(t *testing.T) {
 		}
 	}
 	name := cs.Flags[0]
-	if name.Name != "name" || !name.Required || name.Default != "d" ||
+	if name.Name != "name" || name.Shorthand != "n" || !name.Required || name.Default != "d" ||
 		!name.Hidden || name.ValidationMode != corecmd.ValidationShortcut ||
 		name.RequiredError != "缺少必填参数 --name：名称" ||
 		strings.Join(name.Enum, ",") != "a,b" {
@@ -120,6 +121,72 @@ func TestCrossPlatformCoverageFromShortcutMapsSharedBase(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageFromShortcutAliasesAndPositionalAlias(t *testing.T) {
+	executed := ""
+	s := Shortcut{
+		Service:                  "chat",
+		Command:                  "+search",
+		Aliases:                  []string{"+search-group"},
+		SinglePositionalAliasFor: "query",
+		Description:              "搜索群",
+		Intent:                   "按名称搜索群",
+		Contract: corecmd.ContractDecl{
+			Description: "按名称搜索群",
+			Interface: &contract.InterfaceSpec{
+				Mode: contract.InterfaceModeComposite, Availability: contract.InterfaceAvailable, Reason: "test composite",
+			},
+			Selection: contract.SelectionSpec{
+				AgentSummary: "搜索群", UseWhen: []string{"按名称搜索群"}, AvoidWhen: []string{"不要用于成员搜索"}, Examples: []string{"dws chat +search --query demo"},
+			},
+			Identity: contract.ToolIdentitySpec{
+				ProductID: "chat", Name: "shortcut_search", CanonicalPath: "chat.shortcut_search", CLIPath: "chat +search", PrimaryCLIPath: "chat +search",
+			},
+		},
+		Flags:   []Flag{{Name: "query", Desc: "关键词", Required: true}},
+		Execute: func(rt *RuntimeContext) error { executed = rt.Str("query"); return nil },
+	}
+	spec := FromShortcut(s)
+	if got := spec.Contract.Identity.Aliases; len(got) != 1 || got[0] != "chat +search-group" {
+		t.Fatalf("contract aliases = %#v", got)
+	}
+	cmd := mount(s)
+	if !cmd.HasAlias("+search-group") {
+		t.Fatalf("cobra aliases = %#v", cmd.Aliases)
+	}
+	cmd.SetArgs([]string{"项目群"})
+	if err := cmd.Execute(); err != nil || executed != "项目群" {
+		t.Fatalf("positional execute err=%v value=%q", err, executed)
+	}
+
+	conflict := mount(s)
+	conflict.SetArgs([]string{"项目群", "--query", "另一个群"})
+	if err := conflict.Execute(); err == nil || !strings.Contains(err.Error(), "不能同时提供") {
+		t.Fatalf("positional/flag conflict err = %v", err)
+	}
+	tooMany := mount(s)
+	tooMany.SetArgs([]string{"one", "two"})
+	if err := tooMany.Execute(); err == nil {
+		t.Fatal("multiple positional aliases unexpectedly accepted")
+	}
+
+	missing := mount(Shortcut{
+		Service: "chat", Command: "+missing", Description: "missing",
+		SinglePositionalAliasFor: "query", Execute: func(*RuntimeContext) error { return nil },
+	})
+	missing.SetArgs([]string{"value"})
+	if err := missing.Execute(); err == nil || !strings.Contains(err.Error(), "is not registered") {
+		t.Fatalf("missing positional flag err = %v", err)
+	}
+	invalid := mount(Shortcut{
+		Service: "chat", Command: "+invalid", Description: "invalid",
+		SinglePositionalAliasFor: "query", Flags: []Flag{{Name: "query", Type: FlagInt}}, Execute: func(*RuntimeContext) error { return nil },
+	})
+	invalid.SetArgs([]string{"not-an-int"})
+	if err := invalid.Execute(); err == nil || !strings.Contains(err.Error(), "无法写入") {
+		t.Fatalf("invalid positional value err = %v", err)
+	}
+}
+
 // TestCrossPlatformCoverageFromShortcutMatchesMountSurface pins the live
 // adapter surface: flag set (names/types/usage) and rendered Long must agree.
 // This catches a double-rendered 参数约束 or lost flagHelp decoration.
@@ -5,6 +5,9 @@
 package chat

 import (
+	"fmt"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 )

@@ -28,14 +31,15 @@ func executeShortcutBatchWrite(rt *shortcut.RuntimeContext, product, tool string
 			})
 		}
 		return rt.Output(map[string]any{
-			"dry_run":        true,
-			"executed":       false,
-			"preview_kind":   "plan",
-			"tool":           tool,
-			"actionCount":    len(actions),
-			"failedCount":    0,
-			"actions":        actions,
-			"requestedCount": len(items),
+			"contractVersion": "im.batch-write.v1",
+			"dry_run":         true,
+			"executed":        false,
+			"preview_kind":    "plan",
+			"tool":            tool,
+			"actionCount":     len(actions),
+			"failedCount":     0,
+			"actions":         actions,
+			"requestedCount":  len(items),
 		})
 	}

@@ -56,13 +60,33 @@ func executeShortcutBatchWrite(rt *shortcut.RuntimeContext, product, tool string
 		}
 		succeeded = append(succeeded, entry)
 	}
-	return rt.Output(map[string]any{
-		"ok":             len(failures) == 0,
-		"partial":        len(succeeded) > 0 && len(failures) > 0,
-		"requestedCount": len(items),
-		"succeededCount": len(succeeded),
-		"failedCount":    len(failures),
-		"succeeded":      succeeded,
-		"failures":       failures,
-	})
+	result := map[string]any{
+		"contractVersion": "im.batch-write.v1",
+		"ok":              len(failures) == 0,
+		"partial":         len(succeeded) > 0 && len(failures) > 0,
+		"requestedCount":  len(items),
+		"succeededCount":  len(succeeded),
+		"failedCount":     len(failures),
+		"succeeded":       succeeded,
+		"failures":        failures,
+	}
+	if err := rt.Output(result); err != nil {
+		return err
+	}
+	if len(failures) > 0 {
+		return apperrors.NewAPI(
+			fmt.Sprintf("批量执行 %s 失败：%d/%d 个目标未完成", tool, len(failures), len(items)),
+			apperrors.WithOperation(product+"/"+tool),
+			apperrors.WithReason("batch_write_failed"),
+			apperrors.WithExecutionStarted(true),
+			apperrors.WithRetryable(false),
+			apperrors.WithDetails(map[string]any{
+				"requestedCount": len(items),
+				"succeededCount": len(succeeded),
+				"failedCount":    len(failures),
+				"partial":        len(succeeded) > 0,
+			}),
+		)
+	}
+	return nil
 }
@@ -228,8 +228,8 @@ func botFindProject(data map[string]any) []map[string]any {

 // SearchCommonGroups searches groups shared with given people (search_common_groups, chat server).
 func init() {
-	shortcut.Register(
+	shortcut.Register(withReviewedChatShortcutContracts(
 		BotSearch,
 		BotFind,
-	)
+	)...)
 }
@@ -15,6 +15,7 @@ package chat

 import (
 	"fmt"
+	"strconv"
 	"strings"
 	"unicode/utf8"

@@ -88,8 +89,8 @@ var ConversationSetTop = shortcut.Shortcut{
 	Intent:      "当你想把一个或多个单聊/群聊置顶到会话列表顶部、或取消置顶时使用；支持 1-10 个 openConversationId，逐项执行并返回成功/失败 ledger，某一项失败不阻断其余项。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "单个会话 openConversationId"},
-		{Name: "conversation-ids", Type: shortcut.FlagStringSlice, Desc: "多个会话 openConversationId（最多 10 个）"},
+		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "单个会话 openConversationId；会话 ID 去重后必须为 1-10 个"},
+		{Name: "conversation-ids", Type: shortcut.FlagStringSlice, Desc: "多个会话 openConversationId；会话 ID 去重后必须为 1-10 个"},
 		{Name: "off", Type: shortcut.FlagBool, Desc: "取消置顶（不传则设置置顶）"},
 	},
 	Constraints: []shortcut.Constraint{
@@ -164,7 +165,7 @@ var ConversationMuteAtAll = shortcut.Shortcut{
 	Command:     "+conversation-mute-at-all",
 	Product:     "im",
 	Description: "关闭/开启 @所有人消息提醒",
-	Intent:      "当你在某个群里不想再被'@所有人'打扰、或想恢复该提醒时使用；会实际修改该会话的@所有人提醒开关，需传 openConversationId。",
+	Intent:      "当你已对某个会话开启消息免打扰，并希望额外关闭或恢复'@所有人'提醒时使用；这是免打扰的子开关，若尚未开启总免打扰，先执行 +conversation-mute，否则平台会返回 NotificationOffNotEnabled。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
@@ -185,7 +186,7 @@ var ConversationMuteRedEnvelope = shortcut.Shortcut{
 	Command:     "+conversation-mute-red-envelope",
 	Product:     "im",
 	Description: "关闭/开启红包消息提醒",
-	Intent:      "当你想在某个会话里关闭或恢复红包消息提醒时使用；会实际修改该会话的红包提醒开关，需传 openConversationId。",
+	Intent:      "当你已对某个会话开启消息免打扰，并希望额外关闭或恢复红包提醒时使用；这是免打扰的子开关，若尚未开启总免打扰，或刚恢复过@所有人提醒，先执行 +conversation-mute，否则平台会返回 NotificationOffNotEnabled。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
@@ -284,8 +285,8 @@ var ConversationList = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+conversation-list",
 	Product:     "im",
-	Description: "分页获取当前用户的全部会话列表（单聊+群聊）",
-	Intent:      "当你想遍历当前用户的所有会话（单聊+群聊）做统计、清理或批量处理时使用；只读分页返回，可用 --exclude-muted 排除已免打扰会话。",
+	Description: "分页或一键全量获取当前用户的会话列表（单聊+群聊）",
+	Intent:      "当你想遍历当前用户的所有会话（单聊+群聊）做统计、清理或批量处理时使用；默认读取一页，明确要求全部时使用 --page-all，CLI 会按服务端每页上限自动翻页并公开完整性 ledger；可用 --exclude-muted 排除已免打扰会话。",
 	Risk:        shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -299,47 +300,143 @@ var ConversationList = shortcut.Shortcut{
 			CLIPath:        "chat +conversation-list",
 			PrimaryCLIPath: "chat +conversation-list",
 		},
-		Description: "分页获取当前用户的全部会话列表（单聊+群聊）",
+		Description: "分页或一键全量获取当前用户的会话列表（单聊+群聊）",
 		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: "分页获取当前用户的全部会话列表（单聊+群聊）",
-			UseWhen:      []string{"当你想遍历当前用户的所有会话（单聊+群聊）做统计、清理或批量处理时使用；只读分页返回，可用 --exclude-muted 排除已免打扰会话。"},
+			AgentSummary: "分页或一键全量获取当前用户的会话列表（单聊+群聊）",
+			UseWhen:      []string{"当你想遍历当前用户的所有会话（单聊+群聊）做统计、清理或批量处理时使用；默认读取一页，明确要求全部时使用 --page-all，CLI 会按服务端每页上限自动翻页并公开完整性 ledger；可用 --exclude-muted 排除已免打扰会话。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
 			Examples:     []string{"dws chat +conversation-list --limit 50"},
 		},
 	},
 	Flags: []shortcut.Flag{
-		{Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页数量（1-100）"},
+		{Name: "limit", Type: shortcut.FlagInt, Default: "100", Desc: "每页数量；--limit 必须在 1-100"},
 		{Name: "cursor", Type: shortcut.FlagInt, Desc: "分页游标（首次不传或 0）"},
 		{Name: "exclude-muted", Type: shortcut.FlagBool, Desc: "排除已免打扰会话"},
+		{Name: "page-all", Type: shortcut.FlagBool, Desc: "自动读取全部分页；--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Name: "page-limit", Type: shortcut.FlagInt, Default: "50", Desc: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+	},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "--limit 必须在 1-100"},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "page-limit"}, Description: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+	},
+	Tips: []string{
+		`dws chat +conversation-list --limit 50`,
+		`dws chat +conversation-list --page-all --limit 100`,
+	},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if limit := rt.Int("limit"); limit < 1 || limit > 100 {
+			return apperrors.NewValidation("--limit 必须在 1-100 之间；读取全部会话请使用 --page-all")
+		}
+		if !rt.Bool("page-all") && rt.Changed("page-limit") {
+			return apperrors.NewValidation("--page-limit 仅与 --page-all 一起使用")
+		}
+		if pageLimit := rt.Int("page-limit"); pageLimit < 1 || pageLimit > 500 {
+			return apperrors.NewValidation("--page-limit 必须在 1-500 之间")
+		}
+		return nil
 	},
-	Tips: []string{`dws chat +conversation-list --limit 50`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
-		params := map[string]any{}
-		if rt.Int("limit") > 0 {
-			params["limit"] = rt.Int("limit")
+		cursor := int64(rt.Int("cursor"))
+		pageLimit := 1
+		if rt.Bool("page-all") {
+			pageLimit = rt.Int("page-limit")
 		}
-		if rt.Int("cursor") > 0 {
-			params["cursor"] = rt.Int("cursor")
+		convs := make([]map[string]any, 0)
+		seenConversations := map[string]bool{}
+		seenCursors := map[int64]bool{cursor: true}
+		pagesFetched := 0
+		complete := false
+		hasMore := false
+		nextCursor := int64(0)
+		failures := make([]map[string]any, 0)
+		for pagesFetched < pageLimit {
+			params := map[string]any{"limit": rt.Int("limit")}
+			if cursor > 0 {
+				params["cursor"] = cursor
+			}
+			if rt.Bool("exclude-muted") {
+				params["excludeMuted"] = true
+			}
+			data, err := rt.CallMCPData("im", "list_all_conversations", params)
+			if err != nil {
+				if pagesFetched == 0 {
+					return err
+				}
+				failures = append(failures, map[string]any{"stage": "conversation-page", "cursor": cursor, "error": err.Error()})
+				break
+			}
+			pagesFetched++
+			for _, conversation := range conversationListProject(data) {
+				id := strings.TrimSpace(fmt.Sprint(conversation["openConversationId"]))
+				if id != "" && id != "<nil>" {
+					if seenConversations[id] {
+						continue
+					}
+					seenConversations[id] = true
+				}
+				convs = append(convs, conversation)
+			}
+			page := chatmsg.Pagination(data)
+			hasMoreValue, known := page["hasMore"].(bool)
+			hasMore = hasMoreValue
+			if !known {
+				failures = append(failures, map[string]any{"stage": "conversation-pagination", "error": "下层未返回 hasMore，无法证明结果完整"})
+				break
+			}
+			if !hasMore {
+				complete = true
+				break
+			}
+			nextCursor, err = conversationPaginationCursor(page["nextCursor"])
+			if err != nil || nextCursor == 0 || seenCursors[nextCursor] {
+				failures = append(failures, map[string]any{"stage": "conversation-pagination", "error": "hasMore=true 但 nextCursor 缺失、无效或未前进"})
+				break
+			}
+			if !rt.Bool("page-all") {
+				break
+			}
+			seenCursors[nextCursor] = true
+			cursor = nextCursor
 		}
-		if rt.Bool("exclude-muted") {
-			params["excludeMuted"] = true
+		if rt.Bool("page-all") && hasMore && pagesFetched == pageLimit {
+			failures = append(failures, map[string]any{"stage": "conversation-page-limit", "error": fmt.Sprintf("达到 --page-limit=%d，仍有更多会话", pageLimit)})
 		}
-		data, err := rt.CallMCPData("im", "list_all_conversations", params)
-		if err != nil {
-			return err
+		payload := map[string]any{
+			"count":           len(convs),
+			"conversations":   convs,
+			"pagesFetched":    pagesFetched,
+			"complete":        complete,
+			"hasMore":         hasMore,
+			"nextCursor":      nextCursor,
+			"paginationKnown": len(failures) == 0 || hasMore,
+			"failedCount":     len(failures),
+			"failures":        failures,
+			"partial":         len(failures) > 0,
 		}
-		convs := conversationListProject(data)
-		payload := map[string]any{"count": len(convs), "conversations": convs}
-		chatmsg.ApplyPagination(payload, data)
 		return rt.Output(payload)
 	},
 }

+func conversationPaginationCursor(value any) (int64, error) {
+	switch typed := value.(type) {
+	case int:
+		return int64(typed), nil
+	case int64:
+		return typed, nil
+	case float64:
+		return int64(typed), nil
+	case string:
+		return strconv.ParseInt(strings.TrimSpace(typed), 10, 64)
+	default:
+		return 0, fmt.Errorf("unsupported cursor type %T", value)
+	}
+}
+
 // conversationListProject reshapes the raw list_all_conversations response into a
 // clean conversation list — clean output projection. Both the list
 // container and the per-item field names are probed defensively across candidate
@@ -379,12 +476,12 @@ func conversationListResolveList(data map[string]any) []any {
 			continue
 		}
 		if arr, ok := v.([]any); ok {
-			return arr
+			return unwrapConversationTuple(arr)
 		}
 		if inner, ok := v.(map[string]any); ok {
 			for _, ik := range []string{"conversationList", "conversations", "list", "items", "result", "data"} {
 				if arr, ok := inner[ik].([]any); ok {
-					return arr
+					return unwrapConversationTuple(arr)
 				}
 			}
 		}
@@ -392,6 +489,19 @@ func conversationListResolveList(data map[string]any) []any {
 	return []any{}
 }

+// unwrapConversationTuple handles gateway responses shaped as
+// result:[conversationList,nextCursor,hasMore] while leaving ordinary arrays
+// untouched. This prevents the first list from being mistaken for one row.
+func unwrapConversationTuple(values []any) []any {
+	if len(values) == 0 {
+		return values
+	}
+	if nested, ok := values[0].([]any); ok {
+		return nested
+	}
+	return values
+}
+
 // conversationListFirst returns the first present candidate key's value.
 func conversationListFirst(m map[string]any, keys ...string) (any, bool) {
 	for _, k := range keys {
@@ -576,12 +686,12 @@ func conversationListTopResolveList(data map[string]any) []any {
 			continue
 		}
 		if arr, ok := v.([]any); ok {
-			return arr
+			return unwrapConversationTuple(arr)
 		}
 		if inner, ok := v.(map[string]any); ok {
 			for _, ik := range []string{"conversationList", "conversations", "topConversations", "list", "items", "result", "data"} {
 				if arr, ok := inner[ik].([]any); ok {
-					return arr
+					return unwrapConversationTuple(arr)
 				}
 			}
 		}
@@ -1070,7 +1180,7 @@ var CategoryRemoveConversation = shortcut.Shortcut{
 }

 func init() {
-	shortcut.Register(
+	shortcut.Register(withReviewedChatShortcutContracts(
 		ConversationInfo,
 		ConversationSetTop,
 		ConversationMute,
@@ -1091,5 +1201,5 @@ func init() {
 		CategoryRename,
 		CategoryAddConversation,
 		CategoryRemoveConversation,
-	)
+	)...)
 }
@@ -14,13 +14,15 @@
 package chat

 import (
+	"bytes"
+	"encoding/json"
 	"reflect"
 	"testing"

 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 )

-func TestConversationListTopProjectNormalizesAndFiltersType(t *testing.T) {
+func TestCrossPlatformCoverageConversationListTopProjectNormalizesAndFiltersType(t *testing.T) {
 	data := map[string]any{
 		"result": map[string]any{
 			"items": []any{
@@ -75,7 +77,7 @@ func TestConversationListTopProjectNormalizesAndFiltersType(t *testing.T) {
 	}
 }

-func TestConversationListTopRejectsInvalidType(t *testing.T) {
+func TestCrossPlatformCoverageConversationListTopRejectsInvalidType(t *testing.T) {
 	fake := &platformCoverageCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -87,3 +89,82 @@ func TestConversationListTopRejectsInvalidType(t *testing.T) {
 		t.Fatalf("invalid --type reached lower tool %s/%s", fake.product, fake.tool)
 	}
 }
+
+func TestCrossPlatformCoverageConversationListProjectUnwrapsGatewayTuple(t *testing.T) {
+	data := map[string]any{
+		"result": []any{
+			[]any{map[string]any{"openConversationId": "cid-1", "title": "项目群"}},
+			float64(2),
+			true,
+		},
+	}
+	if got := conversationListProject(data); len(got) != 1 || got[0]["openConversationId"] != "cid-1" {
+		t.Fatalf("conversation tuple projection = %#v", got)
+	}
+	if got := conversationListTopProject(data); len(got) != 1 || got[0]["openConversationId"] != "cid-1" {
+		t.Fatalf("top tuple projection = %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListPageAllFollowsTypedCursor(t *testing.T) {
+	fake := &larkAlignmentCaller{sequenceResponses: map[string][]string{
+		"im/list_all_conversations": {
+			`{"result":{"conversationList":[{"openConversationId":"cid-1","title":"一"}],"hasMore":true,"nextCursor":2}}`,
+			`{"result":{"conversationList":[{"openConversationId":"cid-2","title":"二"}],"hasMore":false}}`,
+		},
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+conversation-list", "--page-all"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 || fake.calls[1].args["cursor"] != int64(2) {
+		t.Fatalf("calls = %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListSinglePagePreservesTypedCursor(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1","title":"一"}],"hasMore":true,"nextCursor":2}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+conversation-list"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 1 {
+		t.Fatalf("calls = %#v, want exactly one page", fake.calls)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["hasMore"] != true || payload["nextCursor"] != float64(2) {
+		t.Fatalf("pagination payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageConversationListDeduplicatesStableIDs(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/list_all_conversations": `{"result":{"conversationList":[{"openConversationId":"cid-1","title":"一"},{"openConversationId":"cid-1","title":"重复"}],"hasMore":false}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+conversation-list"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["count"] != float64(1) {
+		t.Fatalf("deduplicated payload = %#v", payload)
+	}
+}
@@ -23,16 +23,19 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

 // ChatSearch searches groups by keyword (search_groups on the im server).
 var ChatSearch = shortcut.Shortcut{
-	Service:     "chat",
-	Command:     "+chat-search",
-	Product:     "im",
-	Description: "按关键词搜索群聊",
-	Intent:      "当你只记得群名称关键词、需要拿到群 openConversationId 以便发消息或管理该群时使用；按群名模糊搜索，只读分页返回匹配的群列表。",
-	Risk:        shortcut.RiskRead,
+	Service:                  "chat",
+	Command:                  "+chat-search",
+	Aliases:                  []string{"+chat-group-search", "+search-group"},
+	SinglePositionalAliasFor: "query",
+	Product:                  "im",
+	Description:              "按关键词搜索群聊",
+	Intent:                   "当你只记得群名称关键词、需要拿到群 openConversationId 以便发消息或管理该群时使用；按群名模糊搜索，只读分页返回匹配的群列表。",
+	Risk:                     shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
 		Confirmation: "not_required", Idempotency: "idempotent",
@@ -147,7 +150,7 @@ var ChatInviteURL = shortcut.Shortcut{
 	Command:     "+chat-invite-url",
 	Product:     "im",
 	Description: "获取群邀请链接",
-	Intent:      "当你想拿到一条群邀请链接分享给别人加群时使用；只读生成链接，需传群 openConversationId，可用 --expires-seconds 设置有效期（0 表示永久）。",
+	Intent:      "当你想拿到一条群邀请链接分享给别人加群时使用；--group 可传群 openConversationId 或群名，多命中会安全停止。可用 --expires-seconds 设置有效期（0 表示永久）。",
 	Risk:        shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -169,20 +172,32 @@ var ChatInviteURL = shortcut.Shortcut{
 		},
 		Selection: contract.SelectionSpec{
 			AgentSummary: "获取群邀请链接",
-			UseWhen:      []string{"当你想拿到一条群邀请链接分享给别人加群时使用；只读生成链接，需传群 openConversationId，可用 --expires-seconds 设置有效期（0 表示永久）。"},
+			UseWhen:      []string{"当你想拿到一条群邀请链接分享给别人加群时使用；--group 可传群 openConversationId 或群名，多命中会安全停止。可用 --expires-seconds 设置有效期（0 表示永久）。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
 			Examples:     []string{"dws chat +chat-invite-url --group <openConversationId>"},
 		},
 	},
 	Flags: []shortcut.Flag{
-		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId", Required: true},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId；兼容直接传群名并唯一解析"},
+		{Name: "chat-query", Type: shortcut.FlagString, Desc: "--group 的旧版自然名称入口", Hidden: true},
+		{Name: "group-query", Type: shortcut.FlagString, Desc: "--chat-query 的兼容别名", Hidden: true},
 		{Name: "expires-seconds", Type: shortcut.FlagInt, Desc: "链接有效期（秒），0 表示永久"},
 	},
-	Tips: []string{`dws chat +chat-invite-url --group <openConversationId>`},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"group", "chat-query", "group-query"}},
+	},
+	Tips: []string{
+		`dws chat +chat-invite-url --group <openConversationId>`,
+		`dws chat +chat-invite-url --group "项目群"`,
+	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		groupID, err := resolveStableOrNamedChat(rt)
+		if err != nil {
+			return err
+		}
 		params := map[string]any{
-			"openConversationId": rt.Str("group"),
-			"cid":                rt.Str("group"),
+			"openConversationId": groupID,
+			"cid":                groupID,
 		}
 		if rt.Changed("expires-seconds") {
 			params["expiresSeconds"] = rt.Int("expires-seconds")
@@ -777,7 +792,7 @@ var ChatBots = shortcut.Shortcut{
 	Command:     "+chat-bots",
 	Product:     "bot",
 	Description: "查看群内所有机器人",
-	Intent:      "当你想查看某个群里已添加了哪些机器人时使用；需传群 openConversationId，只读返回群内机器人列表（含 openBotId，供后续移除）。",
+	Intent:      "当你想查看某个群里已添加了哪些机器人时使用；--group 可传群 openConversationId 或群名，多命中会安全停止。只读返回机器人列表（含 openBotId，供后续移除）。",
 	Risk:        shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -799,17 +814,29 @@ var ChatBots = shortcut.Shortcut{
 		},
 		Selection: contract.SelectionSpec{
 			AgentSummary: "查看群内所有机器人",
-			UseWhen:      []string{"当你想查看某个群里已添加了哪些机器人时使用；需传群 openConversationId，只读返回群内机器人列表（含 openBotId，供后续移除）。"},
+			UseWhen:      []string{"当你想查看某个群里已添加了哪些机器人时使用；--group 可传群 openConversationId 或群名，多命中会安全停止。只读返回机器人列表（含 openBotId，供后续移除）。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
 			Examples:     []string{"dws chat +chat-bots --group <openConversationId>"},
 		},
 	},
 	Flags: []shortcut.Flag{
-		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId", Required: true},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId；兼容直接传群名并唯一解析"},
+		{Name: "chat-query", Type: shortcut.FlagString, Desc: "--group 的旧版自然名称入口", Hidden: true},
+		{Name: "group-query", Type: shortcut.FlagString, Desc: "--chat-query 的兼容别名", Hidden: true},
+	},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"group", "chat-query", "group-query"}},
+	},
+	Tips: []string{
+		`dws chat +chat-bots --group <openConversationId>`,
+		`dws chat +chat-bots --group "项目群"`,
 	},
-	Tips: []string{`dws chat +chat-bots --group <openConversationId>`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
-		data, err := rt.CallMCPData("bot", "list_group_bots", map[string]any{"openConversationId": rt.Str("group")})
+		groupID, err := resolveStableOrNamedChat(rt)
+		if err != nil {
+			return err
+		}
+		data, err := rt.CallMCPData("bot", "list_group_bots", map[string]any{"openConversationId": groupID})
 		if err != nil {
 			return err
 		}
@@ -818,6 +845,21 @@ var ChatBots = shortcut.Shortcut{
 	},
 }

+// resolveStableOrNamedChat gives read-only group shortcuts one safe target
+// contract. Stable cid values bypass search; natural names always go through
+// the shared exact-match, full-pagination and ambiguity rules.
+func resolveStableOrNamedChat(rt *shortcut.RuntimeContext) (string, error) {
+	resolved, err := targetresolver.ResolveChatTarget(
+		rt,
+		strings.TrimSpace(rt.Str("group")),
+		strings.TrimSpace(rt.StrFirst("chat-query", "group-query")),
+	)
+	if err != nil {
+		return "", err
+	}
+	return resolved.Selected.OpenConversationID, nil
+}
+
 // chatBotsProject reshapes list_group_bots into a clean bot list
 // ({openBotId, name}) — clean output projection. List container and
 // per-item field names are probed defensively across candidate keys so shape
@@ -1461,7 +1503,7 @@ var ChatRoleQueryUser = shortcut.Shortcut{
 }

 func init() {
-	shortcut.Register(
+	shortcut.Register(withReviewedChatShortcutContracts(
 		ChatSearch,
 		ChatMembersGet,
 		ChatTransferOwner,
@@ -1491,5 +1533,5 @@ func init() {
 		ChatRoleSetUser,
 		ChatRoleRemoveUser,
 		ChatRoleQueryUser,
-	)
+	)...)
 }
@@ -21,8 +21,8 @@ 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/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
 )
@@ -110,8 +110,8 @@ var MessagesSendByWebhook = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-send-by-webhook",
 	Product:     "bot",
-	Description: "自定义机器人 Webhook 发送群消息",
-	Intent:      "当你只有自定义机器人的 Webhook token、想往其所在群推送消息时使用；会实际通过 Webhook 发群消息，需传 token、标题、正文，可 @手机号/userId 或 @所有人。",
+	Description: "兼容旧入口的自定义机器人 Webhook 群消息发送",
+	Intent:      "只有既有自动化明确依赖 +messages-send-by-webhook 兼容路径、暂时不能迁移统一身份入口时使用",
 	Risk:        shortcut.RiskWrite,
 	Safety: contract.SafetySpec{
 		Effect: "write", Risk: "medium",
@@ -125,15 +125,15 @@ var MessagesSendByWebhook = shortcut.Shortcut{
 			CLIPath:        "chat +messages-send-by-webhook",
 			PrimaryCLIPath: "chat +messages-send-by-webhook",
 		},
-		Description: "自定义机器人 Webhook 发送群消息",
+		Description: "兼容旧入口的自定义机器人 Webhook 群消息发送",
 		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: "自定义机器人 Webhook 发送群消息",
-			UseWhen:      []string{"当你只有自定义机器人的 Webhook token、想往其所在群推送消息时使用；会实际通过 Webhook 发群消息，需传 token、标题、正文，可 @手机号/userId 或 @所有人。"},
+			AgentSummary: "兼容旧入口的自定义机器人 Webhook 群消息发送",
+			UseWhen:      []string{"只有既有自动化明确依赖 +messages-send-by-webhook 兼容路径、暂时不能迁移统一身份入口时使用"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
 			Examples:     []string{"dws chat +messages-send-by-webhook --token <token> --title \"告警\" --text \"CPU 超 90%\" --at-all"},
 		},
@@ -172,17 +172,56 @@ var MessagesRecall = shortcut.Shortcut{
 	Command:     "+messages-recall",
 	Product:     "im",
 	Description: "撤回当前用户发送的消息",
-	Intent:      "当你想撤回当前用户刚发出的某条消息时使用；会实际撤回消息，需传会话 openConversationId 和消息 openMessageId。",
+	Intent:      "当你想撤回当前用户刚发出的某条消息时使用；会实际撤回消息。推荐同时传会话 openConversationId 和消息 openMessageId；若只传一个消息 ID，CLI 会先只读查询消息详情并补齐会话 ID。兼容 --message-id/--message-ids 的单值写法。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
-		{Name: "msg-id", Type: shortcut.FlagString, Desc: "消息 openMessageId", Required: true},
+		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId；省略时从消息详情解析"},
+		{Name: "group", Type: shortcut.FlagString, Desc: "--conversation-id 的兼容别名", Hidden: true},
+		{Name: "id", Type: shortcut.FlagString, Desc: "--conversation-id 的兼容别名", Hidden: true},
+		{Name: "chat", Type: shortcut.FlagString, Desc: "--conversation-id 的兼容别名", Hidden: true},
+		{Name: "msg-id", Type: shortcut.FlagString, Desc: "消息 openMessageId；一次只能撤回一个消息 ID；--message-ids 仅接受单值"},
+		{Name: "message-id", Type: shortcut.FlagString, Desc: "--msg-id 的兼容别名", Hidden: true},
+		{Name: "message-ids", Type: shortcut.FlagStringSlice, Desc: "--msg-id 的兼容单值别名；不支持批量撤回", Hidden: true},
+	},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"msg-id", "message-id", "message-ids"}},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"msg-id"}, Description: "一次只能撤回一个消息 ID；--message-ids 仅接受单值"},
 	},
 	Tips: []string{`dws chat +messages-recall --conversation-id <openConversationId> --msg-id <openMessageId>`},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		messageIDs := uniqueShortcutStrings(append(
+			[]string{rt.StrFirst("msg-id", "message-id")},
+			rt.StrSlice("message-ids")...,
+		))
+		if len(messageIDs) != 1 {
+			return apperrors.NewValidation("撤回一次只接受一个消息 ID；请通过 --msg-id 或单值 --message-ids 传入")
+		}
+		return nil
+	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		messageIDs := uniqueShortcutStrings(append(
+			[]string{rt.StrFirst("msg-id", "message-id")},
+			rt.StrSlice("message-ids")...,
+		))
+		messageID := messageIDs[0]
+		conversationID := strings.TrimSpace(rt.StrFirst("conversation-id", "group", "id", "chat"))
+		if conversationID == "" {
+			data, err := rt.CallMCPData("im", "list_messages_by_ids", map[string]any{"openMsgIds": []string{messageID}})
+			if err != nil {
+				return err
+			}
+			messages := listMessagesResolveMaps(data)
+			if len(messages) == 0 {
+				return apperrors.NewValidation("无法根据消息 ID 查询到会话；请补充 --conversation-id")
+			}
+			conversationID = strings.TrimSpace(fmt.Sprint(chatmsg.ConversationID(messages[0])))
+			if conversationID == "" || conversationID == "<nil>" {
+				return apperrors.NewValidation("消息详情未返回会话 ID；请补充 --conversation-id")
+			}
+		}
 		return rt.CallMCP("recall_message", map[string]any{
-			"openConversationId": rt.Str("conversation-id"),
-			"openMessageId":      rt.Str("msg-id"),
+			"openConversationId": conversationID,
+			"openMessageId":      messageID,
 		})
 	},
 }
@@ -314,46 +353,22 @@ func listMessageProjectOne(m map[string]any) map[string]any {
 }

 func listMessageProjectOneWithReactions(m map[string]any, includeReactions bool) map[string]any {
-	row := map[string]any{}
-	if v, ok := listMessagesFirst(m, "openMessageId", "openMsgId", "messageId", "msgId"); ok {
-		row["messageId"] = v
-	}
-	if v, ok := listMessagesFirst(m, "senderOpenDingTalkId", "senderUserId", "senderId", "senderStaffId"); ok {
-		row["senderId"] = v
-	}
-	if v, ok := listMessagesFirst(m, "msgType", "messageType", "type"); ok {
-		row["msgType"] = v
-	}
-	if v, ok := listMessagesFirst(m, "createTime", "sendTime", "gmtCreate", "messageTime"); ok {
-		row["createTime"] = v
-	}
-	if text := chatmsg.Text(m); text != nil {
-		row["text"] = text
-	}
-	if conversationID := chatmsg.ConversationID(m); conversationID != nil {
-		row["conversationId"] = conversationID
-	}
-	if threadID := chatmsg.ThreadID(m); threadID != nil {
-		row["threadId"] = threadID
-	}
-	if updateTime := chatmsg.UpdateTime(m); updateTime != nil {
-		row["updateTime"] = updateTime
-	}
-	if includeReactions {
-		if reactions := chatmsg.Reactions(m); len(reactions) > 0 {
-			row["reactions"] = reactions
+	row := chatmsg.ProjectMessageV1(m, includeReactions)
+	// The established mget/list projection omits absent scalar fields; keep
+	// that wire behavior even though the shared chat/search view retains them.
+	for _, key := range []string{"sender", "text", "createTime"} {
+		if row[key] == nil {
+			delete(row, key)
 		}
 	}
-	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
-		row["quotedMessage"] = quoted
+	// Keep the historical mget/list msgType alias while adding the canonical
+	// messageType field from MessageViewV1.
+	if messageType := chatmsg.MessageType(m); messageType != nil {
+		row["msgType"] = messageType
 	}
-	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
-		row["resourceRefs"] = resources
-	}
-	projectForwarded := func(item map[string]any) map[string]any {
+	if forwarded := chatmsg.Forwarded(m, func(item map[string]any) map[string]any {
 		return listMessageProjectOneWithReactions(item, includeReactions)
-	}
-	if forwarded := chatmsg.Forwarded(m, projectForwarded); len(forwarded) > 0 {
+	}); len(forwarded) > 0 {
 		row["forwarded"] = forwarded
 	}
 	return row
@@ -665,20 +680,35 @@ var MessagesMget = shortcut.Shortcut{
 			}
 		}
 		notFound := make([]string, 0)
+		failures := make([]map[string]any, 0)
 		for _, id := range ids {
 			if !found[id] {
 				notFound = append(notFound, id)
+				failures = append(failures, map[string]any{
+					"stage":     "mget",
+					"messageId": id,
+					"error":     "下层未返回该消息",
+				})
 			}
 		}
 		payload := map[string]any{
+			"contractVersion":    chatmsg.MessageListContractVersion,
 			"requestedCount":     len(ids),
 			"foundCount":         len(ids) - len(notFound),
 			"notFoundCount":      len(notFound),
 			"notFoundMessageIds": notFound,
 			"messages":           messages,
+			"complete":           len(notFound) == 0,
+			"hasMore":            false,
+			"nextCursor":         "",
+			"paginationKnown":    true,
+			"pagesFetched":       1,
+			"enrichedCount":      0,
+			"failedCount":        len(failures),
+			"failures":           failures,
 		}
 		if rt.Bool("download-resources") {
-			payload["resourceDownloads"] = DownloadMessageResources(rt, rawMessages, "")
+			AttachMessageResourceDownloads(payload, DownloadMessageResources(rt, rawMessages, ""))
 		}
 		return rt.Output(payload)
 	},
@@ -690,7 +720,7 @@ func MessageResourceDownloadFlags() []shortcut.Flag {
 	return []shortcut.Flag{
 		{Name: "download-resources", Type: shortcut.FlagBool, Desc: "自动下载消息中的全部可识别 mediaId/fileId 资源"},
 		{Name: "output-dir", Type: shortcut.FlagString, Default: "./downloads", Desc: "资源输出目录；必须是工作目录内的相对路径，禁止绝对路径和 .. 逃逸"},
-		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖同名资源文件（默认拒绝）"},
+		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖工作目录内已存在的本地输出文件（默认拒绝）"},
 	}
 }

@@ -902,6 +932,47 @@ func DownloadMessageResources(
 	}
 }

+// AttachMessageResourceDownloads publishes the download ledger and folds any
+// resource failure into the task-level completeness contract without dropping
+// successfully read messages or downloaded files.
+func AttachMessageResourceDownloads(payload, ledger map[string]any) {
+	payload["resourceDownloads"] = ledger
+	failed := messageLedgerInt(ledger["failedCount"])
+	if failed == 0 {
+		return
+	}
+	payload["complete"] = false
+	payload["failedCount"] = messageLedgerInt(payload["failedCount"]) + failed
+	taskFailures, _ := payload["failures"].([]map[string]any)
+	resourceFailures, _ := ledger["failures"].([]map[string]any)
+	for _, failure := range resourceFailures {
+		row := make(map[string]any, len(failure)+1)
+		row["stage"] = "resource-download"
+		for key, value := range failure {
+			row[key] = value
+		}
+		taskFailures = append(taskFailures, row)
+	}
+	payload["failures"] = taskFailures
+}
+
+func messageLedgerInt(value any) int {
+	switch typed := value.(type) {
+	case int:
+		return typed
+	case int32:
+		return int(typed)
+	case int64:
+		return int(typed)
+	case float32:
+		return int(typed)
+	case float64:
+		return int(typed)
+	default:
+		return 0
+	}
+}
+
 func disambiguateResourceDownloadFilename(filename string, used map[string]bool) string {
 	if !used[strings.ToLower(filename)] {
 		return filename
@@ -1168,7 +1239,7 @@ var MessagesSendCard = shortcut.Shortcut{
 	Command:     "+messages-send-card",
 	Product:     "im",
 	Description: "创建流式卡片，可在同一次调用中写入内容并结束",
-	Intent:      "当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。",
+	Intent:      "当你要发送一张流式文本卡片时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成。当前只支持 streaming text，不支持 Card JSON 组件或 action callback。",
 	Risk:        shortcut.RiskWrite,
 	Safety: contract.SafetySpec{
 		Effect: "write", Risk: "medium",
@@ -1190,7 +1261,7 @@ var MessagesSendCard = shortcut.Shortcut{
 		},
 		Selection: contract.SelectionSpec{
 			AgentSummary: "创建流式卡片，可在同一次调用中写入内容并结束",
-			UseWhen:      []string{"当你要发送一张流式卡片消息时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成，避免卡片停留在加载中。"},
+			UseWhen:      []string{"当你要发送一张流式文本卡片时使用；群 openConversationId、单聊 userId、单聊 openDingTalkId 严格三选一，分别使用 --group、--receiver、--receiver-open-dingtalk-id。--receiver 始终按 userId 通过通讯录关键词搜索做精确匹配，即使值以 D/d 开头也不会猜成 openDingTalkId；已有 openDingTalkId 时必须用显式参数直传。userId 包括在 --dry-run 时也会先解析。只传目标时创建卡片并返回 bizId，供后续 messages-update-card 流式更新；同时传 --content 时会自动串联创建和更新，默认以 flowStatus=3 完成。当前只支持 streaming text，不支持 Card JSON 组件或 action callback。"},
 			AvoidWhen:    []string{"已有 bizId、只需要追加或更新现有卡片内容时使用 +messages-update-card"},
 			Examples: []string{
 				"dws chat +messages-send-card --group <openConversationId> --content \"任务已完成\"",
@@ -1221,7 +1292,7 @@ var MessagesSendCard = shortcut.Shortcut{
 		`dws chat +messages-send-card --group <openConversationId> --content "任务已完成"`,
 	},
 	Validate: func(rt *shortcut.RuntimeContext) error {
-		if status := rt.Int("flow-status"); status < 1 || status > 5 {
+		if status := rt.Int("flow-status"); !validCardFlowStatus(status) {
 			return fmt.Errorf("--flow-status 必须在 1-5 之间")
 		}
 		if rt.Changed("flow-status") && rt.Str("content") == "" {
@@ -1253,11 +1324,12 @@ var MessagesSendCard = shortcut.Shortcut{
 		status := rt.Int("flow-status")
 		if rt.DryRun() {
 			return rt.Output(map[string]any{
-				"dry_run":      true,
-				"executed":     false,
-				"preview_kind": "plan",
-				"actionCount":  2,
-				"failedCount":  0,
+				"contractVersion": currentCardWorkflowContract.Version,
+				"dry_run":         true,
+				"executed":        false,
+				"preview_kind":    "plan",
+				"actionCount":     2,
+				"failedCount":     0,
 				"actions": []map[string]any{
 					{
 						"tool":      "create_and_send_card",
@@ -1291,11 +1363,12 @@ var MessagesSendCard = shortcut.Shortcut{
 			return fmt.Errorf("卡片已创建（bizId=%s），但自动更新失败: %w", bizID, err)
 		}
 		return rt.Output(map[string]any{
-			"ok":         true,
-			"bizId":      bizID,
-			"flowStatus": status,
-			"created":    created,
-			"updated":    updated,
+			"contractVersion": currentCardWorkflowContract.Version,
+			"ok":              true,
+			"bizId":           bizID,
+			"flowStatus":      status,
+			"created":         created,
+			"updated":         updated,
 		})
 	},
 }
@@ -1362,7 +1435,7 @@ var MessagesUpdateCard = shortcut.Shortcut{
 	Command:     "+messages-update-card",
 	Product:     "im",
 	Description: "流式更新卡片内容（最后一次 --flow-status 应为 3）",
-	Intent:      "当你要向已发送的流式卡片持续追加/更新内容时使用；会实际更新卡片，需传 send-card 返回的 bizId、新内容及 flowStatus（最后一次应为 3 表示完成）。",
+	Intent:      "当你要向已发送的流式文本卡片持续追加/更新内容时使用；会实际更新卡片，需传 send-card 返回的 bizId、新内容及 flowStatus 1-5（最后一次应为 3 表示完成）。当前不支持 Card JSON 组件或 action callback。",
 	Risk:        shortcut.RiskWrite,
 	Safety: contract.SafetySpec{
 		Effect: "write", Risk: "medium",
@@ -1384,7 +1457,7 @@ var MessagesUpdateCard = shortcut.Shortcut{
 		},
 		Selection: contract.SelectionSpec{
 			AgentSummary: "流式更新卡片内容（最后一次 --flow-status 应为 3）",
-			UseWhen:      []string{"当你要向已发送的流式卡片持续追加/更新内容时使用；会实际更新卡片，需传 send-card 返回的 bizId、新内容及 flowStatus（最后一次应为 3 表示完成）。"},
+			UseWhen:      []string{"当你要向已发送的流式文本卡片持续追加/更新内容时使用；会实际更新卡片，需传 send-card 返回的 bizId、新内容及 flowStatus 1-5（最后一次应为 3 表示完成）。当前不支持 Card JSON 组件或 action callback。"},
 			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
 			Examples:     []string{"dws chat +messages-update-card --biz-id <bizId> --content \"内容\" --flow-status 3"},
 		},
@@ -1392,9 +1465,18 @@ var MessagesUpdateCard = shortcut.Shortcut{
 	Flags: []shortcut.Flag{
 		{Name: "biz-id", Type: shortcut.FlagString, Desc: "send-card 返回的卡片业务 ID", Required: true},
 		{Name: "content", Type: shortcut.FlagString, Desc: "卡片消息内容", Required: true},
-		{Name: "flow-status", Type: shortcut.FlagInt, Desc: "流式状态 1处理中/2输入中/3完成/4执行中/5错误", Required: true},
+		{Name: "flow-status", Type: shortcut.FlagInt, Desc: "流式状态 1处理中/2输入中/3完成/4执行中/5错误；--flow-status 必须在 1-5 之间", Required: true},
+	},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"flow-status"}, Description: "--flow-status 必须在 1-5 之间"},
 	},
 	Tips: []string{`dws chat +messages-update-card --biz-id <bizId> --content "内容" --flow-status 3`},
+	Validate: func(rt *shortcut.RuntimeContext) error {
+		if !validCardFlowStatus(rt.Int("flow-status")) {
+			return fmt.Errorf("--flow-status 必须在 1-5 之间")
+		}
+		return nil
+	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
 		return rt.CallMCP("update_streaming_card", map[string]any{
 			"bizId":      rt.Str("biz-id"),
@@ -1735,7 +1817,7 @@ var MessagesUnsetTop = shortcut.Shortcut{
 }

 func init() {
-	shortcut.Register(
+	shortcut.Register(withReviewedChatShortcutContracts(
 		MessagesSendByBot,
 		MessagesBatchSendByBot,
 		MessagesSendByWebhook,
@@ -1764,5 +1846,5 @@ func init() {
 		MessagesListPin,
 		MessagesSetTop,
 		MessagesUnsetTop,
-	)
+	)...)
 }
@@ -20,7 +20,7 @@ import (

 const testCipher = "SwzNkAraDE6lUHUNlVT3mjFdbxL6dWvmt77XtjACdpJx9VFibzTbW9KtDbkzGOYP||2||1||1"

-func TestListMessageProjectOne(t *testing.T) {
+func TestCrossPlatformCoverageListMessageProjectOne(t *testing.T) {
 	// full field mapping + forwarded expansion; an encrypted body is marked (no
 	// cross-conversation recovery), not leaked as base64.
 	row := listMessageProjectOne(map[string]any{
@@ -75,7 +75,35 @@ func TestListMessageProjectOne(t *testing.T) {
 	}
 }

-func TestListPinProjectPreservesThreadIdentity(t *testing.T) {
+func TestCrossPlatformCoverageAttachMessageResourceDownloadsPreservesMessagesAndMarksIncomplete(t *testing.T) {
+	payload := map[string]any{
+		"messages":    []map[string]any{{"messageId": "msg-1"}},
+		"complete":    true,
+		"failedCount": 0,
+		"failures":    []map[string]any{},
+	}
+	ledger := map[string]any{
+		"failedCount": 1,
+		"failures": []map[string]any{{
+			"messageId": "msg-1",
+			"error":     "download failed",
+		}},
+	}
+	AttachMessageResourceDownloads(payload, ledger)
+	if payload["complete"] != false || payload["failedCount"] != 1 {
+		t.Fatalf("task completeness = %#v", payload)
+	}
+	messages, _ := payload["messages"].([]map[string]any)
+	if len(messages) != 1 || messages[0]["messageId"] != "msg-1" {
+		t.Fatalf("messages were dropped: %#v", messages)
+	}
+	failures, _ := payload["failures"].([]map[string]any)
+	if len(failures) != 1 || failures[0]["stage"] != "resource-download" {
+		t.Fatalf("resource failures = %#v", failures)
+	}
+}
+
+func TestCrossPlatformCoverageListPinProjectPreservesThreadIdentity(t *testing.T) {
 	got := listPinProject(map[string]any{
 		"result": map[string]any{
 			"messages": []any{
@@ -94,6 +94,13 @@ func TestCrossPlatformCoverageCompatibilityAliases(t *testing.T) {
 			wantTool:    "search_groups",
 			wantArgs:    map[string]any{"keyword": "树莓派", "limit": 5},
 		},
+		{
+			name:        "chat search command alias and positional query",
+			argv:        []string{"chat", "+search-group", "树莓派", "--yes"},
+			wantProduct: "im",
+			wantTool:    "search_groups",
+			wantArgs:    map[string]any{"keyword": "树莓派", "limit": 20},
+		},
 		{
 			name:        "bot find keyword",
 			argv:        []string{"chat", "+bot-find", "--keyword", "日报", "--yes"},
@@ -175,6 +182,16 @@ func TestCrossPlatformCoverageCompatibilityAliases(t *testing.T) {
 				"openConversationId": "cid-1",
 			},
 		},
+		{
+			name:        "message recall plural single id alias",
+			argv:        []string{"chat", "+messages-recall", "--conversation-id", "cid-1", "--message-ids", "msg-1", "--yes"},
+			wantProduct: "im",
+			wantTool:    "recall_message",
+			wantArgs: map[string]any{
+				"openConversationId": "cid-1",
+				"openMessageId":      "msg-1",
+			},
+		},
 	}

 	for _, tc := range tests {
@@ -203,6 +220,15 @@ func TestCrossPlatformCoverageCompatibilityAliases(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageConversationNotificationSubSwitchesPublishMutePrerequisite(t *testing.T) {
+	for _, command := range []shortcut.Shortcut{ConversationMuteAtAll, ConversationMuteRedEnvelope} {
+		if !strings.Contains(command.Intent, "+conversation-mute") ||
+			!strings.Contains(command.Intent, "NotificationOffNotEnabled") {
+			t.Errorf("%s intent does not publish the live platform prerequisite: %q", command.Command, command.Intent)
+		}
+	}
+}
+
 func TestCrossPlatformCoverageChatIDHelpers(t *testing.T) {
 	t.Run("recognize open DingTalk IDs", func(t *testing.T) {
 		tests := []struct {
@@ -248,7 +274,7 @@ func TestCrossPlatformCoverageChatIDHelpers(t *testing.T) {
 	})
 }

-func TestChatMuteMemberResolvesUserIDToOpenDingTalkID(t *testing.T) {
+func TestCrossPlatformCoverageChatMuteMemberResolvesUserIDToOpenDingTalkID(t *testing.T) {
 	fake := &muteMemberResolutionCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -277,7 +303,7 @@ func TestChatMuteMemberResolvesUserIDToOpenDingTalkID(t *testing.T) {
 	}
 }

-func TestConversationCategoryTitleValidation(t *testing.T) {
+func TestCrossPlatformCoverageConversationCategoryTitleValidation(t *testing.T) {
 	tests := []struct {
 		name      string
 		argv      []string
@@ -7,6 +7,8 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"os"
+	"path/filepath"
 	"reflect"
 	"strconv"
 	"strings"
@@ -91,6 +93,62 @@ func TestCrossPlatformCoverageConversationAndGroupListExecution(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageConversationListFailureBoundaries(t *testing.T) {
+	for _, tail := range [][]string{
+		{"--limit", "0"},
+		{"--limit", "101"},
+		{"--page-limit", "2"},
+		{"--page-all", "--page-limit", "0"},
+		{"--page-all", "--page-limit", "501"},
+	} {
+		root := newPlatformCoverageRoot()
+		root.SetArgs(append([]string{"chat", "+conversation-list"}, tail...))
+		if err := root.Execute(); err == nil {
+			t.Errorf("invalid conversation args succeeded: %v", tail)
+		}
+	}
+
+	for _, tc := range []struct {
+		name      string
+		caller    *larkAlignmentCaller
+		args      []string
+		wantError bool
+	}{
+		{name: "first read failure", caller: &larkAlignmentCaller{failProductTool: "im/list_all_conversations"}, wantError: true},
+		{name: "later read failure", caller: &larkAlignmentCaller{
+			sequenceResponses: map[string][]string{"im/list_all_conversations": {`{"result":{"conversationList":[],"hasMore":true,"nextCursor":2}}`}},
+			failProductToolAt: map[string]int{"im/list_all_conversations": 2},
+		}, args: []string{"--page-all"}},
+		{name: "missing pagination", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_all_conversations": `{"result":{"conversationList":[]}}`}}},
+		{name: "invalid cursor", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_all_conversations": `{"result":{"conversationList":[],"hasMore":true,"nextCursor":"bad"}}`}}},
+		{name: "stalled cursor", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_all_conversations": `{"result":{"conversationList":[],"hasMore":true,"nextCursor":2}}`}}, args: []string{"--page-all", "--cursor", "2"}},
+		{name: "page limit", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_all_conversations": `{"result":{"conversationList":[],"hasMore":true,"nextCursor":2}}`}}, args: []string{"--page-all", "--page-limit", "1"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(tc.caller)
+			root := newPlatformCoverageRoot()
+			root.SetArgs(append([]string{"chat", "+conversation-list"}, tc.args...))
+			err := root.Execute()
+			if (err != nil) != tc.wantError {
+				t.Fatalf("error = %v, wantError=%v", err, tc.wantError)
+			}
+		})
+	}
+
+	for value, want := range map[any]int64{int(1): 1, int64(2): 2, float64(3): 3, "4": 4} {
+		got, err := conversationPaginationCursor(value)
+		if err != nil || got != want {
+			t.Fatalf("cursor %#v = %d, %v; want %d", value, got, err, want)
+		}
+	}
+	if _, err := conversationPaginationCursor(struct{}{}); err == nil {
+		t.Fatal("unsupported cursor unexpectedly accepted")
+	}
+	if got := unwrapConversationTuple(nil); got != nil {
+		t.Fatalf("empty tuple = %#v", got)
+	}
+}
+
 func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) {
 	tests := []struct {
 		name      string
@@ -98,6 +156,12 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) {
 		args      []string
 		wantError string
 	}{
+		{
+			name:      "owner query resolution",
+			caller:    &larkAlignmentCaller{failProductTool: "contact/search_contact_by_key_word"},
+			args:      []string{"chat", "+chat-create", "--name", "群", "--users", "u1", "--owner-query", "群主", "--yes"},
+			wantError: "fixture lower call failed",
+		},
 		{
 			name:      "current profile call",
 			caller:    &larkAlignmentCaller{failProductTool: "contact/get_current_user_profile"},
@@ -152,6 +216,18 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) {
 			args:      []string{"chat", "+feed-group-query-item", "--category-id", "1", "--conversation-ids", "cid"},
 			wantError: "fixture lower call failed",
 		},
+		{
+			name:      "chat update resolution",
+			caller:    &larkAlignmentCaller{responses: map[string]string{"im/search_groups": `{"result":[]}`}},
+			args:      []string{"chat", "+chat-update", "--group", "missing", "--name", "新群", "--yes"},
+			wantError: "没有找到",
+		},
+		{
+			name:      "reply write",
+			caller:    &larkAlignmentCaller{failProductTool: "chat/send_personal_message"},
+			args:      []string{"chat", "+messages-reply", "--conversation-id", "cid", "--message-id", "msg", "--ref-sender", "D-sender", "--text", "收到", "--yes"},
+			wantError: "fixture lower call failed",
+		},
 	}
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
@@ -177,6 +253,27 @@ func TestCrossPlatformCoverageChatCreateAndReplyFailures(t *testing.T) {
 		dry.calls[1].tool != "create_group_conversation" {
 		t.Fatalf("chat-create dry-run calls = %#v", dry.calls)
 	}
+
+	external := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"外部联系人","openDingTalkId":"D-external"}]}`,
+	}}
+	helpers.InitDeps(external)
+	root = newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+chat-create", "--name", "群", "--owner-open-dingtalk-id", "D-owner", "--member-query", "外部联系人", "--yes"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestCrossPlatformCoverageNaturalGroupReadFailures(t *testing.T) {
+	for _, command := range []string{"+chat-invite-url", "+chat-bots"} {
+		helpers.InitDeps(&larkAlignmentCaller{responses: map[string]string{"im/search_groups": `{"result":[]}`}})
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", command, "--group", "missing"})
+		if err := root.Execute(); err == nil {
+			t.Errorf("%s missing natural group unexpectedly resolved", command)
+		}
+	}
 }

 func TestCrossPlatformCoverageReplyShapeHelpers(t *testing.T) {
@@ -240,6 +337,45 @@ func TestCrossPlatformCoverageFlagAndMgetValidation(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageRecallCardAndLedgerBoundaries(t *testing.T) {
+	for _, tc := range []struct {
+		name   string
+		caller *larkAlignmentCaller
+		args   []string
+	}{
+		{name: "multiple recall ids", caller: &larkAlignmentCaller{}, args: []string{"chat", "+messages-recall", "--message-ids", "m1,m2", "--yes"}},
+		{name: "recall lookup failure", caller: &larkAlignmentCaller{failProductTool: "im/list_messages_by_ids"}, args: []string{"chat", "+messages-recall", "--msg-id", "m1", "--yes"}},
+		{name: "recall lookup empty", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_messages_by_ids": `{"result":[]}`}}, args: []string{"chat", "+messages-recall", "--msg-id", "m1", "--yes"}},
+		{name: "recall lookup missing conversation", caller: &larkAlignmentCaller{responses: map[string]string{"im/list_messages_by_ids": `{"result":[{"openMessageId":"m1"}]}`}}, args: []string{"chat", "+messages-recall", "--msg-id", "m1", "--yes"}},
+		{name: "card status low", caller: &larkAlignmentCaller{}, args: []string{"chat", "+messages-update-card", "--biz-id", "b", "--content", "x", "--flow-status", "0", "--yes"}},
+		{name: "card status high", caller: &larkAlignmentCaller{}, args: []string{"chat", "+messages-update-card", "--biz-id", "b", "--content", "x", "--flow-status", "6", "--yes"}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			helpers.InitDeps(tc.caller)
+			root := newPlatformCoverageRoot()
+			root.SetArgs(tc.args)
+			if err := root.Execute(); err == nil {
+				t.Fatal("failure boundary unexpectedly succeeded")
+			}
+		})
+	}
+
+	helpers.InitDeps(&larkAlignmentCaller{})
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+messages-update-card", "--biz-id", "b", "--content", "x", "--flow-status", "3", "--yes"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+
+	for value, want := range map[any]int{
+		int(1): 1, int32(2): 2, int64(3): 3, float32(4): 4, float64(5): 5, "bad": 0,
+	} {
+		if got := messageLedgerInt(value); got != want {
+			t.Fatalf("messageLedgerInt(%#v) = %d, want %d", value, got, want)
+		}
+	}
+}
+
 func TestCrossPlatformCoverageFeedCompleteAndExcludeMuted(t *testing.T) {
 	fake := &larkAlignmentCaller{category: `{"result":{"hasMore":false,"list":[{"openConversationId":"cid"}]}}`}
 	helpers.InitDeps(fake)
@@ -388,6 +524,90 @@ func TestCrossPlatformCoverageUnifiedSendUnsupportedIdentityGuard(t *testing.T)
 	}
 }

+func TestCrossPlatformCoverageUnifiedSendGroupFileAndBatchBoundaries(t *testing.T) {
+	readGroupFile := messagesSendReadGroupFile
+	t.Cleanup(func() { messagesSendReadGroupFile = readGroupFile })
+
+	for _, tail := range [][]string{
+		{"--identity", "bot", "--robot-code", "r", "--group", "cid", "--groups", "c1", "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups", "c1", "--groups-file", "groups.txt", "--text", "x"},
+		{"--identity", "webhook", "--webhook-token", "token", "--chat-query", "群", "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups", "", "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups", strings.Join(makeIDs(101), ","), "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups-file", "/absolute.txt", "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups-file", "../escape.txt", "--text", "x"},
+		{"--identity", "bot", "--robot-code", "r", "--groups-file", "missing.txt", "--text", "x"},
+	} {
+		helpers.InitDeps(&larkAlignmentCaller{})
+		root := newPlatformCoverageRoot()
+		root.SetArgs(append([]string{"chat", "+messages-send"}, append(tail, "--yes")...))
+		if err := root.Execute(); err == nil {
+			t.Errorf("invalid unified send args succeeded: %v", tail)
+		}
+	}
+
+	temp := t.TempDir()
+	if err := os.Mkdir(filepath.Join(temp, "groups-dir"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(temp, "large.txt"), make([]byte, messagesSendMaxGroupFileSize+1), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(temp, "unreadable.txt"), []byte("cid"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	messagesSendReadGroupFile = func(path string) ([]byte, error) {
+		if filepath.Base(path) == "unreadable.txt" {
+			return nil, os.ErrPermission
+		}
+		return readGroupFile(path)
+	}
+	t.Chdir(temp)
+	for _, path := range []string{"groups-dir", "large.txt", "unreadable.txt"} {
+		helpers.InitDeps(&larkAlignmentCaller{})
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", "+messages-send", "--identity", "bot", "--robot-code", "r", "--groups-file", path, "--text", "x", "--yes"})
+		if err := root.Execute(); err == nil {
+			t.Errorf("invalid group file %q succeeded", path)
+		}
+	}
+
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--identity", "bot", "--robot-code", "r",
+		"--groups", "c1,c2", "--text", "x", "--at-user-ids", "u1",
+		"--at-open-dingtalk-ids", "D1", "--at-all", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 {
+		t.Fatalf("batch calls = %#v", fake.calls)
+	}
+	for _, call := range fake.calls {
+		if !reflect.DeepEqual(call.args["atUserIds"], []string{"u1"}) ||
+			!reflect.DeepEqual(call.args["atOpendingtalkIds"], []string{"D1"}) ||
+			call.args["isAtAll"] != "true" {
+			t.Fatalf("batch mention args = %#v", call.args)
+		}
+	}
+
+	shortcut.Register(shortcut.Shortcut{
+		Service: "chat", Command: "+coverage-unified-execute-error",
+		Flags: MessagesSend.Flags, Execute: executeMessagesSend,
+	})
+	root = newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+coverage-unified-execute-error", "--identity", "bot", "--robot-code", "r",
+		"--groups-file", "missing-again.txt", "--text", "x",
+	})
+	if err := root.Execute(); err == nil {
+		t.Fatal("execute-time group file error was swallowed")
+	}
+}
+
 func TestCrossPlatformCoverageMuteMemberResolutionFailures(t *testing.T) {
 	tests := []struct {
 		name   string
@@ -0,0 +1,11 @@
+// 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.
+
+//go:build !windows
+
+package chat
+
+import "os"
+
+var replaceFileAtomically = os.Rename
@@ -0,0 +1,11 @@
+// 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.
+
+//go:build windows
+
+package chat
+
+import "golang.org/x/sys/windows"
+
+var replaceFileAtomically = windows.Rename
@@ -17,13 +17,22 @@ import (
 	"strings"
 	"testing"

+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 )

-func TestMessagesSendPublishesCompleteIdentityConstraintInputs(t *testing.T) {
+type chatOutputErrorWriter struct {
+	err error
+}
+
+func (w chatOutputErrorWriter) Write([]byte) (int, error) {
+	return 0, w.err
+}
+
+func TestCrossPlatformCoverageMessagesSendPublishesCompleteIdentityConstraintInputs(t *testing.T) {
 	want := []string{
-		"identity", "as", "group", "chat-id", "user", "open-dingtalk-id",
+		"identity", "as", "group", "chat-id", "groups", "groups-file", "chat-query", "user", "user-query", "open-dingtalk-id",
 		"users", "open-dingtalk-ids", "robot-code", "webhook-token",
 		"uuid", "idempotency-key",
 	}
@@ -54,6 +63,251 @@ func TestMessagesSendPublishesCompleteIdentityConstraintInputs(t *testing.T) {
 	}
 }

+func TestCrossPlatformCoverageMessagesSendIdentityDescriptorMatchesRuntimeSurface(t *testing.T) {
+	capabilities := MessageIdentityCapabilities()
+	if len(capabilities) != 3 {
+		t.Fatalf("identity capabilities = %#v", capabilities)
+	}
+	byIdentity := make(map[string]MessageIdentityCapability, len(capabilities))
+	for _, capability := range capabilities {
+		byIdentity[capability.Identity] = capability
+	}
+	if !byIdentity["user"].IdempotencyKeys || byIdentity["user"].BatchLedger {
+		t.Fatalf("user capability = %#v", byIdentity["user"])
+	}
+	if !byIdentity["bot"].BatchLedger || byIdentity["bot"].IdempotencyKeys ||
+		!reflect.DeepEqual(byIdentity["bot"].ContentTypes, []string{"text", "markdown"}) {
+		t.Fatalf("bot capability = %#v", byIdentity["bot"])
+	}
+	if byIdentity["webhook"].BatchLedger || byIdentity["webhook"].IdempotencyKeys {
+		t.Fatalf("webhook capability = %#v", byIdentity["webhook"])
+	}
+	capabilities[0].ContentTypes[0] = "mutated"
+	if MessageIdentityCapabilities()[0].ContentTypes[0] == "mutated" {
+		t.Fatal("identity capability descriptor leaked mutable storage")
+	}
+	if !messageIdentitySupportsContent("user", "audio") ||
+		!messageIdentitySupportsContent("user", "video") ||
+		messageIdentitySupportsContent("missing", "text") {
+		t.Fatal("identity content normalization or unknown-identity guard drifted")
+	}
+}
+
+func TestCrossPlatformCoverageIMWorkflowContractsPublishRealPositiveAndNegativeBoundaries(t *testing.T) {
+	card := CurrentCardWorkflowContract()
+	if card.Version != "im.streaming-card.v1" || card.CallbackSupported ||
+		!reflect.DeepEqual(card.ContentTypes, []string{"streaming-text"}) || len(card.FlowStatuses) != 5 {
+		t.Fatalf("card contract = %#v", card)
+	}
+	card.Targets[0] = "mutated"
+	if CurrentCardWorkflowContract().Targets[0] == "mutated" {
+		t.Fatal("card contract leaked mutable storage")
+	}
+
+	boundaries := CurrentIMCapabilityBoundaries()
+	byName := make(map[string]bool, len(boundaries))
+	for _, boundary := range boundaries {
+		byName[boundary.Capability] = boundary.Supported
+		if boundary.Alternative == "" {
+			t.Errorf("boundary %s lacks alternative", boundary.Capability)
+		}
+	}
+	for _, unsupported := range []string{"thread-write", "bot-rich-media", "card-action-callback", "resource-resume"} {
+		if byName[unsupported] {
+			t.Errorf("unsupported boundary %s was advertised", unsupported)
+		}
+	}
+	for _, supported := range []string{"group-member-full-pagination", "group-owner-selection"} {
+		if !byName[supported] {
+			t.Errorf("supported boundary %s was hidden", supported)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendBotMultiGroupPublishesPerTargetLedger(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "bot", "--robot-code", "robot",
+		"--groups", "cid-a,cid-b,cid-a", "--markdown", "通知", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 {
+		t.Fatalf("multi-group calls = %#v", fake.calls)
+	}
+	for index, target := range []string{"cid-a", "cid-b"} {
+		if fake.calls[index].tool != "send_robot_group_message" ||
+			fake.calls[index].args["openConversationId"] != target {
+			t.Fatalf("multi-group call[%d] = %#v", index, fake.calls[index])
+		}
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["contractVersion"] != "im.batch-write.v1" || payload["ok"] != true ||
+		payload["requestedCount"] != float64(2) || payload["succeededCount"] != float64(2) ||
+		payload["failedCount"] != float64(0) {
+		t.Fatalf("multi-group ledger = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendBotMultiGroupFailuresReturnNonzero(t *testing.T) {
+	tests := []struct {
+		name          string
+		fake          *larkAlignmentCaller
+		wantSucceeded float64
+		wantFailed    float64
+		wantPartial   bool
+	}{
+		{
+			name: "partial failure",
+			fake: &larkAlignmentCaller{failProductToolAt: map[string]int{
+				"bot/send_robot_group_message": 2,
+			}},
+			wantSucceeded: 1,
+			wantFailed:    1,
+			wantPartial:   true,
+		},
+		{
+			name:          "all failed",
+			fake:          &larkAlignmentCaller{failProductTool: "bot/send_robot_group_message"},
+			wantSucceeded: 0,
+			wantFailed:    2,
+			wantPartial:   false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			helpers.InitDeps(tt.fake)
+			root := newPlatformCoverageRoot()
+			var output bytes.Buffer
+			root.SetOut(&output)
+			root.SetArgs([]string{
+				"chat", "+messages-send", "--as", "bot", "--robot-code", "robot",
+				"--groups", "cid-a,cid-b", "--markdown", "通知", "--yes",
+			})
+
+			err := root.Execute()
+			if err == nil {
+				t.Fatal("failed multi-group delivery returned success")
+			}
+			var typed *apperrors.Error
+			if !errors.As(err, &typed) || typed.Category != apperrors.CategoryAPI ||
+				typed.Reason != "batch_write_failed" || typed.ExitCode() == 0 {
+				t.Fatalf("batch error = %#v (%v)", typed, err)
+			}
+
+			var payload map[string]any
+			if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+				t.Fatal(err)
+			}
+			if payload["ok"] != false || payload["partial"] != tt.wantPartial ||
+				payload["succeededCount"] != tt.wantSucceeded ||
+				payload["failedCount"] != tt.wantFailed {
+				t.Fatalf("failure ledger = %#v", payload)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendBotMultiGroupPropagatesOutputFailure(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	wantErr := errors.New("fixture output failed")
+	root := newPlatformCoverageRoot()
+	root.SetOut(chatOutputErrorWriter{err: wantErr})
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "bot", "--robot-code", "robot",
+		"--groups", "cid-a,cid-b", "--markdown", "通知", "--yes",
+	})
+
+	if err := root.Execute(); !errors.Is(err, wantErr) {
+		t.Fatalf("output error = %v, want %v", err, wantErr)
+	}
+	if len(fake.calls) != 2 {
+		t.Fatalf("multi-group calls = %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendBotGroupsFileUsesSafeDeduplicatedTargets(t *testing.T) {
+	t.Chdir(t.TempDir())
+	if err := os.WriteFile("groups.txt", []byte("# comment\ncid-a,cid-b\ncid-a\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetOut(&bytes.Buffer{})
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "bot", "--robot-code", "robot",
+		"--groups-file", "groups.txt", "--text", "通知", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 {
+		t.Fatalf("groups-file calls = %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageChatCreateExplicitOwnerSkipsCurrentProfileAndDeduplicatesMember(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetOut(&bytes.Buffer{})
+	root.SetArgs([]string{
+		"chat", "+chat-create", "--name", "测试群", "--users", "D-owner,user-1",
+		"--owner-open-dingtalk-id", "D-owner", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 1 || fake.calls[0].tool != "create_group_conversation" {
+		t.Fatalf("explicit owner calls = %#v", fake.calls)
+	}
+	create := fake.calls[0].args
+	if create["ownerOpenDingTalkId"] != "D-owner" {
+		t.Fatalf("ownerOpenDingTalkId = %#v", create["ownerOpenDingTalkId"])
+	}
+	if got, want := create["groupMembers"], []string{"D-owner", "user-1"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("groupMembers = %#v, want %#v", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageChatCreateOwnerQueryResolvesBeforeSingleCreate(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"owner-user","openDingTalkId":"D-owner"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetOut(&bytes.Buffer{})
+	root.SetArgs([]string{
+		"chat", "+chat-create", "--name", "测试群", "--users", "user-1",
+		"--owner-query", "张三", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 || fake.calls[0].tool != "search_contact_by_key_word" ||
+		fake.calls[1].tool != "create_group_conversation" {
+		t.Fatalf("owner query calls = %#v", fake.calls)
+	}
+	create := fake.calls[1].args
+	if create["ownerOpenDingTalkId"] != "D-owner" {
+		t.Fatalf("ownerOpenDingTalkId = %#v", create["ownerOpenDingTalkId"])
+	}
+	if got, want := create["groupMembers"], []string{"D-owner", "user-1"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("groupMembers = %#v, want %#v", got, want)
+	}
+}
+
 func TestCrossPlatformCoverageSafeResourceDownloadsStayReadOnly(t *testing.T) {
 	for _, command := range []shortcut.Shortcut{MessagesMget, MessagesResourceDownload} {
 		if command.Risk != shortcut.RiskRead {
@@ -0,0 +1,81 @@
+// 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 chat
+
+// MessageIdentityCapability is the reviewed Runtime capability descriptor for
+// +messages-send. Validation and Skill drift checks consume this same typed
+// source; it describes only behavior that the current lower transports expose.
+type MessageIdentityCapability struct {
+	Identity        string
+	Targets         []string
+	ContentTypes    []string
+	NaturalTargets  []string
+	MentionTargets  []string
+	IdempotencyKeys bool
+	BatchLedger     bool
+}
+
+var messageIdentityCapabilities = []MessageIdentityCapability{
+	{
+		Identity:        "user",
+		Targets:         []string{"group", "direct-user", "direct-open-dingtalk-id"},
+		ContentTypes:    []string{"text", "markdown", "image-media-id", "file", "audio-as-file", "video-as-file"},
+		NaturalTargets:  []string{"chat-query", "user-query"},
+		MentionTargets:  []string{"open-dingtalk-id", "all"},
+		IdempotencyKeys: true,
+		BatchLedger:     false,
+	},
+	{
+		Identity:        "bot",
+		Targets:         []string{"group", "groups", "direct-users", "direct-open-dingtalk-ids"},
+		ContentTypes:    []string{"text", "markdown"},
+		NaturalTargets:  []string{},
+		MentionTargets:  []string{"user-id", "open-dingtalk-id", "all"},
+		IdempotencyKeys: false,
+		BatchLedger:     true,
+	},
+	{
+		Identity:        "webhook",
+		Targets:         []string{"token-owned-group"},
+		ContentTypes:    []string{"text", "markdown"},
+		NaturalTargets:  []string{},
+		MentionTargets:  []string{"user-id", "mobile", "all"},
+		IdempotencyKeys: false,
+		BatchLedger:     false,
+	},
+}
+
+// MessageIdentityCapabilities returns defensive copies of the public matrix.
+func MessageIdentityCapabilities() []MessageIdentityCapability {
+	out := make([]MessageIdentityCapability, len(messageIdentityCapabilities))
+	for i, capability := range messageIdentityCapabilities {
+		out[i] = capability
+		out[i].Targets = append([]string(nil), capability.Targets...)
+		out[i].ContentTypes = append([]string(nil), capability.ContentTypes...)
+		out[i].NaturalTargets = append([]string(nil), capability.NaturalTargets...)
+		out[i].MentionTargets = append([]string(nil), capability.MentionTargets...)
+	}
+	return out
+}
+
+func messageIdentitySupportsContent(identity, contentType string) bool {
+	if contentType == "audio" || contentType == "video" {
+		contentType += "-as-file"
+	} else if contentType == "image" {
+		contentType = "image-media-id"
+	}
+	for _, capability := range messageIdentityCapabilities {
+		if capability.Identity != identity {
+			continue
+		}
+		for _, supported := range capability.ContentTypes {
+			if supported == contentType {
+				return true
+			}
+		}
+		return false
+	}
+	return false
+}
@@ -0,0 +1,76 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package chat
+
+// CardFlowStatus is one reviewed state accepted by DingTalk's streaming-card
+// update transport.
+type CardFlowStatus struct {
+	Value int
+	Name  string
+}
+
+// CardWorkflowContract describes the real card subset exposed by the current
+// Runtime. It intentionally does not claim Lark card JSON/component compilation
+// or callback consumption, neither of which exists in the lower interface.
+type CardWorkflowContract struct {
+	Version           string
+	Targets           []string
+	ContentTypes      []string
+	FlowStatuses      []CardFlowStatus
+	CallbackSupported bool
+}
+
+var currentCardWorkflowContract = CardWorkflowContract{
+	Version:      "im.streaming-card.v1",
+	Targets:      []string{"group", "direct-user", "direct-open-dingtalk-id"},
+	ContentTypes: []string{"streaming-text"},
+	FlowStatuses: []CardFlowStatus{
+		{Value: 1, Name: "processing"},
+		{Value: 2, Name: "typing"},
+		{Value: 3, Name: "completed"},
+		{Value: 4, Name: "executing"},
+		{Value: 5, Name: "error"},
+	},
+	CallbackSupported: false,
+}
+
+// CurrentCardWorkflowContract returns a defensive copy for policy and docs.
+func CurrentCardWorkflowContract() CardWorkflowContract {
+	contract := currentCardWorkflowContract
+	contract.Targets = append([]string(nil), contract.Targets...)
+	contract.ContentTypes = append([]string(nil), contract.ContentTypes...)
+	contract.FlowStatuses = append([]CardFlowStatus(nil), contract.FlowStatuses...)
+	return contract
+}
+
+func validCardFlowStatus(value int) bool {
+	for _, status := range currentCardWorkflowContract.FlowStatuses {
+		if status.Value == value {
+			return true
+		}
+	}
+	return false
+}
+
+// IMCapabilityBoundary makes unsupported Lark-parity requests explicit and
+// testable instead of leaving them to prose or transport guessing.
+type IMCapabilityBoundary struct {
+	Capability  string
+	Supported   bool
+	Alternative string
+}
+
+var currentIMCapabilityBoundaries = []IMCapabilityBoundary{
+	{Capability: "thread-write", Supported: false, Alternative: "quote reply with +messages-reply; thread reading with +thread-replies"},
+	{Capability: "bot-rich-media", Supported: false, Alternative: "bot text/markdown, or current-user file/image send"},
+	{Capability: "card-action-callback", Supported: false, Alternative: "streaming text card create/update only"},
+	{Capability: "resource-resume", Supported: false, Alternative: "atomic whole-file download with explicit retry"},
+	{Capability: "group-member-full-pagination", Supported: true, Alternative: "+chat-members-list or +group-members"},
+	{Capability: "group-owner-selection", Supported: true, Alternative: "+chat-create owner flags"},
+}
+
+// CurrentIMCapabilityBoundaries returns the reviewed positive/negative matrix.
+func CurrentIMCapabilityBoundaries() []IMCapabilityBoundary {
+	return append([]IMCapabilityBoundary(nil), currentIMCapabilityBoundaries...)
+}
@@ -13,44 +13,81 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

-// ChatCreate creates a DingTalk group as the current user. It intentionally
-// does not advertise Lark-only owner, description, initial-bot, or visibility
-// semantics.
+// ChatCreate creates a DingTalk group after resolving every natural member and
+// the optional owner to stable DingTalk identities. Description, initial-bot,
+// idempotency, and Lark visibility semantics remain deliberately unsupported.
 var ChatCreate = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+chat-create",
 	Product:     "im",
-	Description: "以当前用户身份创建钉钉群聊",
-	Intent:      "当你要创建一个基础钉钉群聊时使用；自动把当前用户加入成员列表并作为群主，支持 INTERNAL、EXTERNAL、NORMAL 和话题模式。它不支持指定其他 owner、群 description、初始机器人或 Lark public/private 语义。",
+	Description: "按成员和可选群主全量预检后创建一个钉钉群聊",
+	Intent:      "当你要创建钉钉群聊时使用；成员可传稳定 ID 或 --member-query 姓名，群主默认当前用户，也可用 --owner-open-dingtalk-id 或 --owner-query 明确指定。所有自然身份会在唯一解析并去重后才执行一次创建，任一零命中或多命中都会整体停止。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
 		{Name: "name", Type: shortcut.FlagString, Desc: "群名称", Required: true},
-		{Name: "users", Type: shortcut.FlagStringSlice, Desc: "初始成员 userId 或 openDingTalkId 列表", Required: true},
+		{Name: "users", Type: shortcut.FlagStringSlice, Desc: "初始成员 userId 或 openDingTalkId 列表"},
+		{Name: "member-query", Type: shortcut.FlagStringSlice, Desc: "按姓名/花名唯一解析的初始成员，可逗号分隔或重复传入"},
+		{Name: "owner-open-dingtalk-id", Type: shortcut.FlagString, Desc: "明确指定群主 openDingTalkId（与 --owner-query 互斥；省略时群主为当前用户）"},
+		{Name: "owner-query", Type: shortcut.FlagString, Desc: "按姓名唯一解析群主 openDingTalkId（与 --owner-open-dingtalk-id 互斥）"},
 		{Name: "type", Type: shortcut.FlagString, Default: "INTERNAL", Desc: "群类型", Enum: []string{"INTERNAL", "EXTERNAL", "NORMAL"}},
 		{Name: "thread", Type: shortcut.FlagBool, Desc: "创建为话题群"},
 	},
+	Constraints: []shortcut.Constraint{
+		{Kind: shortcut.ConstraintAtLeastOne, Flags: []string{"users", "member-query"}},
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"owner-open-dingtalk-id", "owner-query"}},
+	},
 	Tips: []string{
 		`dws chat +chat-create --name "项目冲刺群" --users userId1,userId2`,
-		`dws chat +chat-create --name "合作群" --users userId1,userId2 --type EXTERNAL`,
+		`dws chat +chat-create --name "合作群" --member-query "张三,李四" --type EXTERNAL`,
 	},
 	Execute: func(rt *shortcut.RuntimeContext) error {
-		profile, err := rt.CallMCPData("contact", "get_current_user_profile", nil)
+		resolvedMembers, err := targetresolver.ResolveUsers(
+			rt,
+			rt.StrSlice("member-query"),
+			targetresolver.IdentityAny,
+		)
 		if err != nil {
-			return fmt.Errorf("读取当前用户以设置群主失败: %w", err)
+			return err
 		}
-		currentUserID := currentProfileUserID(profile)
-		if currentUserID == "" {
-			return apperrors.NewValidation("当前用户资料缺少 userId，无法保证群主属于初始成员列表")
+		ownerOpenID := rt.Str("owner-open-dingtalk-id")
+		if query := rt.Str("owner-query"); query != "" {
+			resolvedOwner, resolveErr := targetresolver.ResolveUser(
+				rt, query, targetresolver.IdentityOpenDingTalkID)
+			if resolveErr != nil {
+				return resolveErr
+			}
+			ownerOpenID = resolvedOwner.Selected.OpenDingTalkID
+		}
+		members := make([]string, 0, len(rt.StrSlice("users"))+len(resolvedMembers)+1)
+		if ownerOpenID != "" {
+			members = append(members, ownerOpenID)
+		} else {
+			profile, profileErr := rt.CallMCPData("contact", "get_current_user_profile", nil)
+			if profileErr != nil {
+				return fmt.Errorf("读取当前用户以设置群主失败: %w", profileErr)
+			}
+			currentUserID := currentProfileUserID(profile)
+			if currentUserID == "" {
+				return apperrors.NewValidation("当前用户资料缺少 userId，无法保证群主属于初始成员列表")
+			}
+			members = append(members, currentUserID)
 		}
-		members := []string{currentUserID}
 		for _, member := range rt.StrSlice("users") {
 			member = strings.TrimSpace(member)
 			if member != "" {
 				members = appendUniqueShortcutString(members, member)
 			}
 		}
+		for _, resolved := range resolvedMembers {
+			member := resolved.Selected.UserID
+			if member == "" {
+				member = resolved.Selected.OpenDingTalkID
+			}
+			members = appendUniqueShortcutString(members, member)
+		}
 		params := map[string]any{
 			"groupName":    rt.Str("name"),
 			"groupMembers": members,
@@ -59,6 +96,9 @@ var ChatCreate = shortcut.Shortcut{
 		if rt.Bool("thread") {
 			params["convThreadEnabled"] = true
 		}
+		if ownerOpenID != "" {
+			params["ownerOpenDingTalkId"] = ownerOpenID
+		}
 		if rt.DryRun() {
 			return rt.CallMCP("create_group_conversation", params)
 		}
@@ -114,18 +154,23 @@ func normalizeCreatedConversation(data map[string]any) {
 var ChatUpdate = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+chat-update",
+	Aliases:     []string{"+chat-rename"},
 	Product:     "chat",
 	Description: "更新群名称（仅名称，不支持 description）",
-	Intent:      "当你只需要修改群名称时使用；这是 lark-cli +chat-update 的诚实子集，只接受群 openConversationId 和新名称。修改群 description、个人备注、群昵称或其他群设置时不要使用。",
+	Intent:      "当你只需要修改群名称时使用；--group 可传群名或 openConversationId，群名必须唯一解析后才会写入。修改群 description、个人备注、群昵称或其他群设置时不要使用。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId", Required: true},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群名称或 openConversationId", Required: true},
 		{Name: "name", Type: shortcut.FlagString, Desc: "新的群名称", Required: true},
 	},
-	Tips: []string{`dws chat +chat-update --group <openConversationId> --name "新群名"`},
+	Tips: []string{`dws chat +chat-update --group <群名或openConversationId> --name "新群名"`},
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		resolved, err := targetresolver.ResolveChatTarget(rt, rt.Str("group"), "")
+		if err != nil {
+			return err
+		}
 		return rt.CallMCP("update_group_name", map[string]any{
-			"openconversation_id": rt.Str("group"),
+			"openconversation_id": resolved.Selected.OpenConversationID,
 			"group_name":          rt.Str("name"),
 		})
 	},
@@ -138,8 +183,8 @@ var MessagesReply = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-reply",
 	Product:     "chat",
-	Description: "以当前用户身份引用回复消息（自动补全原发送者）",
-	Intent:      "当你要以当前用户身份对已有消息发送纯文本引用回复时使用；提供会话和被引用消息即可，默认通过 mget 自动读取原发送者，也可显式传 openDingTalkId/userId；userId 会通过通讯录搜索精确匹配 openDingTalkId。它不支持 bot 身份、富媒体、卡片或 thread 内回复。",
+	Description: "引用回复一条已有消息，并返回可继续查询或撤回的发送上下文",
+	Intent:      "当你要以当前用户身份对一条已有消息发送纯文本引用回复时使用；传会话和原消息 ID，CLI 会先读取原发送者，也可显式传 --ref-sender。成功结果在保留下层响应的同时增量返回 messageId（下层提供时）、conversationId、threadId（适用时）、deliveryStatus、idempotencyKey 和 referencedMessage 来源上下文。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "会话 openConversationId", Required: true},
@@ -175,10 +220,79 @@ var MessagesReply = shortcut.Shortcut{
 		if value := rt.StrFirst("idempotency-key", "uuid"); value != "" {
 			params["uuid"] = value
 		}
-		return rt.CallMCP("send_personal_message", params)
+		if rt.DryRun() {
+			return rt.Output(map[string]any{
+				"contractVersion": "im.message-reply.v1",
+				"dryRun":          true,
+				"willSend":        false,
+				"transport":       "chat/send_personal_message",
+				"arguments":       params,
+				"conversationId":  rt.Str("conversation-id"),
+				"referencedMessage": map[string]any{
+					"messageId":            replyMessageID(rt),
+					"senderOpenDingTalkId": refSender,
+				},
+			})
+		}
+		data, err := rt.CallMCPWriteData("chat", "send_personal_message", params)
+		if err != nil {
+			return err
+		}
+		enrichReplyResult(data, rt, refSender)
+		return rt.Output(data)
 	},
 }

+func enrichReplyResult(data map[string]any, rt *shortcut.RuntimeContext, refSender string) {
+	data["contractVersion"] = "im.message-reply.v1"
+	data["conversationId"] = rt.Str("conversation-id")
+	data["referencedMessage"] = map[string]any{
+		"messageId":            replyMessageID(rt),
+		"senderOpenDingTalkId": refSender,
+		"resolutionSource": func() string {
+			if rt.Str("ref-sender") != "" {
+				return "explicit"
+			}
+			return "message_lookup"
+		}(),
+	}
+	if key := rt.StrFirst("idempotency-key", "uuid"); key != "" {
+		data["idempotencyKey"] = key
+	}
+	if value := replyResponseValue(data, "openMessageId", "openMsgId", "messageId", "msgId"); value != nil {
+		data["messageId"] = value
+	}
+	if value := replyResponseValue(data, "openConvThreadId", "threadId", "topicId"); value != nil {
+		data["threadId"] = value
+	}
+	if value := replyResponseValue(data, "deliveryStatus", "sendStatus", "status"); value != nil {
+		data["deliveryStatus"] = value
+		data["deliveryStatusKnown"] = true
+	} else {
+		data["deliveryStatus"] = "unknown"
+		data["deliveryStatusKnown"] = false
+	}
+}
+
+func replyResponseValue(data map[string]any, keys ...string) any {
+	scopes := []map[string]any{data}
+	for _, wrapper := range []string{"result", "data"} {
+		if nested, ok := data[wrapper].(map[string]any); ok {
+			scopes = append(scopes, nested)
+		}
+	}
+	for _, scope := range scopes {
+		for _, key := range keys {
+			if value, ok := scope[key]; ok && value != nil {
+				if text, isString := value.(string); !isString || strings.TrimSpace(text) != "" {
+					return value
+				}
+			}
+		}
+	}
+	return nil
+}
+
 func resolveReplySender(rt *shortcut.RuntimeContext) (string, error) {
 	if value := rt.Str("ref-sender"); value != "" {
 		if isOpenID(value) {
@@ -303,8 +417,8 @@ var FlagCreate = shortcut.Shortcut{
 	Intent:      "当你要把同一会话中的一条或多条消息加入当前用户的个人收藏时使用；逐项返回成功/失败 ledger。这是消息 favorite，不是消息 Pin、会话置顶或 feed-layer thread flag。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "message-id", Type: shortcut.FlagString, Desc: "单条消息 openMessageId"},
-		{Name: "message-ids", Type: shortcut.FlagStringSlice, Desc: "多条消息 openMessageId（最多 10 条）"},
+		{Name: "message-id", Type: shortcut.FlagString, Desc: "单条消息 openMessageId；消息 ID 去重后必须为 1-10 条"},
+		{Name: "message-ids", Type: shortcut.FlagStringSlice, Desc: "多条消息 openMessageId；消息 ID 去重后必须为 1-10 条"},
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "消息所在会话 openConversationId", Required: true},
 	},
 	Constraints: []shortcut.Constraint{
@@ -330,8 +444,8 @@ var FlagCancel = shortcut.Shortcut{
 	Intent:      "当你要移除当前用户对同一会话中一条或多条消息的个人收藏标记时使用；逐项返回成功/失败 ledger，只影响 message favorite，不删除原消息，也不会修改 Pin 或会话置顶。",
 	Risk:        shortcut.RiskWrite,
 	Flags: []shortcut.Flag{
-		{Name: "message-id", Type: shortcut.FlagString, Desc: "单条消息 openMessageId"},
-		{Name: "message-ids", Type: shortcut.FlagStringSlice, Desc: "多条消息 openMessageId（最多 10 条）"},
+		{Name: "message-id", Type: shortcut.FlagString, Desc: "单条消息 openMessageId；消息 ID 去重后必须为 1-10 条"},
+		{Name: "message-ids", Type: shortcut.FlagStringSlice, Desc: "多条消息 openMessageId；消息 ID 去重后必须为 1-10 条"},
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "消息所在会话 openConversationId", Required: true},
 	},
 	Constraints: []shortcut.Constraint{
@@ -389,8 +503,8 @@ var FlagList = shortcut.Shortcut{
 	Intent:      "当你要查看当前用户的 DingTalk message favorite 列表时使用；返回下层分页结果，不把 message favorite 与 Pin、会话置顶或 Lark feed-layer thread flag 混为一谈。",
 	Risk:        shortcut.RiskRead,
 	Flags: []shortcut.Flag{
-		{Name: "cursor", Type: shortcut.FlagInt, Default: "0", Desc: "数字分页游标，首次传 0"},
-		{Name: "size", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量，范围 1-100"},
+		{Name: "cursor", Type: shortcut.FlagInt, Default: "0", Desc: "数字分页游标；--cursor 必须大于等于 0，--size 必须在 1-100 之间"},
+		{Name: "size", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量；--cursor 必须大于等于 0，--size 必须在 1-100 之间"},
 	},
 	Constraints: []shortcut.Constraint{{
 		Kind:        shortcut.ConstraintCustom,
@@ -516,10 +630,10 @@ var ChatList = shortcut.Shortcut{
 		"不支持 lark 的 sort/sort-type，也不模拟 bot 身份剥离 p2p。",
 	Risk: shortcut.RiskRead,
 	Flags: []shortcut.Flag{
-		{Name: "types", Type: shortcut.FlagStringSlice, Desc: "会话类型：group、p2p；省略时默认只返回群聊"},
-		{Name: "page-size", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量（1-100）"},
-		{Name: "limit", Type: shortcut.FlagInt, Desc: "--page-size 的别名"},
-		{Name: "page-token", Type: shortcut.FlagString, Desc: "分页游标（钉钉为整数游标的字符串形式）"},
+		{Name: "types", Type: shortcut.FlagStringSlice, Desc: "会话类型只能包含 group 和/或 p2p；省略时默认只返回群聊"},
+		{Name: "page-size", Type: shortcut.FlagInt, Default: "20", Desc: "每页数量，必须在 1-100 之间"},
+		{Name: "limit", Type: shortcut.FlagInt, Desc: "--page-size 的别名，必须在 1-100 之间"},
+		{Name: "page-token", Type: shortcut.FlagString, Desc: "分页游标；若提供则必须是非负整数"},
 		{Name: "cursor", Type: shortcut.FlagInt, Desc: "--page-token 的整数别名"},
 		{Name: "exclude-muted", Type: shortcut.FlagBool, Desc: "排除已免打扰会话"},
 	},
@@ -721,7 +835,7 @@ func chatListFilterTypes(chats []map[string]any, types []string) []map[string]an
 }

 func init() {
-	shortcut.Register(
+	shortcut.Register(withReviewedChatShortcutContracts(
 		ChatCreate,
 		ChatList,
 		ChatUpdate,
@@ -730,5 +844,5 @@ func init() {
 		FlagCancel,
 		FlagList,
 		FeedGroupQueryItem,
-	)
+	)...)
 }
@@ -23,11 +23,14 @@ type larkAlignmentCall struct {
 }

 type larkAlignmentCaller struct {
-	calls           []larkAlignmentCall
-	failTarget      string
-	failProductTool string
-	category        string
-	responses       map[string]string
+	calls             []larkAlignmentCall
+	failTarget        string
+	failProductTool   string
+	failProductToolAt map[string]int
+	callCounts        map[string]int
+	category          string
+	responses         map[string]string
+	sequenceResponses map[string][]string
 }

 func (f *larkAlignmentCaller) CallTool(_ context.Context, product, tool string, args map[string]any) (*edition.ToolResult, error) {
@@ -36,9 +39,16 @@ func (f *larkAlignmentCaller) CallTool(_ context.Context, product, tool string,
 		return nil, errors.New("fixture write failed")
 	}
 	key := product + "/" + tool
+	if f.callCounts == nil {
+		f.callCounts = map[string]int{}
+	}
+	f.callCounts[key]++
 	if f.failProductTool == key {
 		return nil, errors.New("fixture lower call failed")
 	}
+	if f.failProductToolAt[key] == f.callCounts[key] {
+		return nil, errors.New("fixture sequenced lower call failed")
+	}
 	text := `{"success":true}`
 	switch key {
 	case "contact/get_current_user_profile":
@@ -75,6 +85,10 @@ func (f *larkAlignmentCaller) CallTool(_ context.Context, product, tool string,
 	if response, ok := f.responses[key]; ok {
 		text = response
 	}
+	if responses := f.sequenceResponses[key]; len(responses) > 0 {
+		text = responses[0]
+		f.sequenceResponses[key] = responses[1:]
+	}
 	return &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: text}}}, nil
 }

@@ -87,7 +101,67 @@ func (f *larkAlignmentCaller) DryRun() bool   { return false }
 func (f *larkAlignmentCaller) Fields() string { return "" }
 func (f *larkAlignmentCaller) JQ() string     { return "" }

-func TestChatCreateAddsCurrentUserAndNormalizesResult(t *testing.T) {
+func TestCrossPlatformCoverageEvaluationRegressionNaturalGroupTargetsAndRecallInference(t *testing.T) {
+	t.Run("group name to bots", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/search_groups":    `{"result":[{"openConversationId":"cid-project","title":"项目群"}],"hasMore":false}`,
+			"bot/list_group_bots": `{"result":{"bots":[]}}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", "+chat-bots", "--group", "项目群"})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 2 || fake.calls[1].tool != "list_group_bots" || fake.calls[1].args["openConversationId"] != "cid-project" {
+			t.Fatalf("calls = %#v", fake.calls)
+		}
+	})
+
+	t.Run("group query to invite url", func(t *testing.T) {
+		fake := &larkAlignmentCaller{responses: map[string]string{
+			"im/search_groups": `{"result":[{"openConversationId":"cid-project","title":"项目群"}],"hasMore":false}`,
+		}}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", "+chat-invite-url", "--chat-query", "项目群"})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 2 || fake.calls[1].tool != "get_group_invite_url" || fake.calls[1].args["openConversationId"] != "cid-project" {
+			t.Fatalf("calls = %#v", fake.calls)
+		}
+	})
+
+	t.Run("stable id in group query bypasses search", func(t *testing.T) {
+		fake := &larkAlignmentCaller{}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", "+chat-invite-url", "--chat-query", "cid-fixture-chat-0001"})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 1 || fake.calls[0].tool != "get_group_invite_url" ||
+			fake.calls[0].args["openConversationId"] != "cid-fixture-chat-0001" {
+			t.Fatalf("calls = %#v", fake.calls)
+		}
+	})
+
+	t.Run("message id fills conversation before recall", func(t *testing.T) {
+		fake := &larkAlignmentCaller{}
+		helpers.InitDeps(fake)
+		root := newPlatformCoverageRoot()
+		root.SetArgs([]string{"chat", "+messages-recall", "--message-ids", "msg", "--yes"})
+		if err := root.Execute(); err != nil {
+			t.Fatal(err)
+		}
+		if len(fake.calls) != 2 || fake.calls[0].tool != "list_messages_by_ids" || fake.calls[1].tool != "recall_message" || fake.calls[1].args["openConversationId"] != "cid" {
+			t.Fatalf("calls = %#v", fake.calls)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageChatCreateAddsCurrentUserAndNormalizesResult(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -127,7 +201,80 @@ func TestChatCreateAddsCurrentUserAndNormalizesResult(t *testing.T) {
 	}
 }

-func TestMessagesSendRoutesIdentitySpecificTransports(t *testing.T) {
+func TestCrossPlatformCoverageChatCreateResolvesEveryNaturalMemberBeforeCreating(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"resolved-user","openDingTalkId":"D-resolved"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+chat-create",
+		"--name", "测试群",
+		"--users", "explicit-user",
+		"--member-query", "张三",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 3 {
+		t.Fatalf("calls = %#v, want member resolve + current profile + create", fake.calls)
+	}
+	if fake.calls[0].tool != "search_contact_by_key_word" ||
+		fake.calls[1].tool != "get_current_user_profile" ||
+		fake.calls[2].tool != "create_group_conversation" {
+		t.Fatalf("call order = %#v", fake.calls)
+	}
+	if got, want := fake.calls[2].args["groupMembers"], []string{"self-user", "explicit-user", "resolved-user"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("groupMembers = %#v, want %#v", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageChatCreateNaturalMemberAmbiguityStopsBeforeProfileAndCreate(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"u1"},{"name":"张三","userId":"u2"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+chat-create",
+		"--name", "测试群",
+		"--member-query", "张三",
+		"--yes",
+	})
+	if err := root.Execute(); err == nil {
+		t.Fatal("ambiguous member unexpectedly created a group")
+	}
+	if len(fake.calls) != 1 || fake.calls[0].tool != "search_contact_by_key_word" {
+		t.Fatalf("ambiguous member reached profile/create: %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageChatCreateNaturalMemberDryRunUsesSameResolutionChain(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"resolved-user"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+chat-create",
+		"--name", "测试群",
+		"--member-query", "张三",
+		"--dry-run",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 3 ||
+		fake.calls[0].tool != "search_contact_by_key_word" ||
+		fake.calls[1].tool != "get_current_user_profile" ||
+		fake.calls[2].tool != "create_group_conversation" {
+		t.Fatalf("dry-run calls = %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendRoutesIdentitySpecificTransports(t *testing.T) {
 	tests := []struct {
 		name    string
 		args    []string
@@ -201,7 +348,7 @@ func TestMessagesSendRoutesIdentitySpecificTransports(t *testing.T) {
 	}
 }

-func TestMessagesSendRejectsUnsupportedIdentityCapability(t *testing.T) {
+func TestCrossPlatformCoverageMessagesSendRejectsUnsupportedIdentityCapability(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -222,7 +369,7 @@ func TestMessagesSendRejectsUnsupportedIdentityCapability(t *testing.T) {
 	}
 }

-func TestLarkAlignmentWriteMappings(t *testing.T) {
+func TestCrossPlatformCoverageLarkAlignmentWriteMappings(t *testing.T) {
 	tests := []struct {
 		name     string
 		args     []string
@@ -232,11 +379,11 @@ func TestLarkAlignmentWriteMappings(t *testing.T) {
 	}{
 		{
 			name:    "chat-update-name-only",
-			args:    []string{"chat", "+chat-update", "--group", "cid", "--name", "新群名", "--yes"},
+			args:    []string{"chat", "+chat-update", "--group", "cid-fixture-chat-0001", "--name", "新群名", "--yes"},
 			product: "chat",
 			tool:    "update_group_name",
 			wantArgs: map[string]any{
-				"openconversation_id": "cid",
+				"openconversation_id": "cid-fixture-chat-0001",
 				"group_name":          "新群名",
 			},
 		},
@@ -291,10 +438,32 @@ func TestLarkAlignmentWriteMappings(t *testing.T) {
 	}
 }

-func TestMessagesReplyPublishesPlainTextBoundary(t *testing.T) {
-	fake := &larkAlignmentCaller{}
+func TestCrossPlatformCoverageObservedChatRenameAliasResolvesNameBeforeWrite(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/search_groups": `{"result":[{"openConversationId":"cid-project","title":"项目评测群"}],"hasMore":false}`,
+	}}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{"chat", "+chat-rename", "--group", "项目评测群", "--name", "项目讨论群", "--yes"})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 2 || fake.calls[0].tool != "search_groups" || fake.calls[1].tool != "update_group_name" {
+		t.Fatalf("calls = %#v", fake.calls)
+	}
+	if fake.calls[1].args["openconversation_id"] != "cid-project" || fake.calls[1].args["group_name"] != "项目讨论群" {
+		t.Fatalf("write args = %#v", fake.calls[1].args)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesReplyPublishesPlainTextBoundary(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"chat/send_personal_message": `{"result":{"openMessageId":"new-msg","openConvThreadId":"thread-1","sendStatus":"accepted"}}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
 	root.SetArgs([]string{
 		"chat", "+messages-reply",
 		"--conversation-id", "cid",
@@ -327,9 +496,46 @@ func TestMessagesReplyPublishesPlainTextBoundary(t *testing.T) {
 		content["content"] != "收到" {
 		t.Fatalf("reply content = %#v", content)
 	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["contractVersion"] != "im.message-reply.v1" ||
+		payload["messageId"] != "new-msg" ||
+		payload["conversationId"] != "cid" ||
+		payload["threadId"] != "thread-1" ||
+		payload["deliveryStatus"] != "accepted" ||
+		payload["idempotencyKey"] != "reply-uuid" {
+		t.Fatalf("reply result context = %#v", payload)
+	}
+	referenced, _ := payload["referencedMessage"].(map[string]any)
+	if referenced["messageId"] != "msg" || referenced["resolutionSource"] != "explicit" {
+		t.Fatalf("referenced message context = %#v", referenced)
+	}
 }

-func TestFlagBatchContinuesAndPublishesFailureLedger(t *testing.T) {
+func TestCrossPlatformCoverageMessagesReplyDryRunStopsBeforeWrite(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-reply",
+		"--conversation-id", "cid",
+		"--message-id", "msg",
+		"--ref-sender", "D-sender",
+		"--text", "收到",
+		"--dry-run",
+		"--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 0 {
+		t.Fatalf("reply dry-run reached write transport: %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageFlagBatchContinuesAndPublishesFailureLedger(t *testing.T) {
 	fake := &larkAlignmentCaller{failTarget: "m2"}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -341,8 +547,8 @@ func TestFlagBatchContinuesAndPublishesFailureLedger(t *testing.T) {
 		"--conversation-id", "cid",
 		"--yes",
 	})
-	if err := root.Execute(); err != nil {
-		t.Fatal(err)
+	if err := root.Execute(); err == nil {
+		t.Fatal("partial batch failure returned success")
 	}
 	if len(fake.calls) != 2 {
 		t.Fatalf("calls = %#v", fake.calls)
@@ -359,7 +565,7 @@ func TestFlagBatchContinuesAndPublishesFailureLedger(t *testing.T) {
 	}
 }

-func TestConversationSetTopBatchDryRunPublishesActionsWithoutWrites(t *testing.T) {
+func TestCrossPlatformCoverageConversationSetTopBatchDryRunPublishesActionsWithoutWrites(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -390,7 +596,7 @@ func TestConversationSetTopBatchDryRunPublishesActionsWithoutWrites(t *testing.T
 	}
 }

-func TestMessagesMgetDryRunPublishesMultiResourceDownloadPlan(t *testing.T) {
+func TestCrossPlatformCoverageMessagesMgetDryRunPublishesMultiResourceDownloadPlan(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -450,7 +656,7 @@ func TestCrossPlatformCoverageMessagesReplyResolvesUserIDBeforeExecution(t *test
 	}
 }

-func TestMessagesReplyInfersSenderFromReferencedMessage(t *testing.T) {
+func TestCrossPlatformCoverageMessagesReplyInfersSenderFromReferencedMessage(t *testing.T) {
 	fake := &larkAlignmentCaller{}
 	helpers.InitDeps(fake)
 	root := newPlatformCoverageRoot()
@@ -479,7 +685,7 @@ func TestMessagesReplyInfersSenderFromReferencedMessage(t *testing.T) {
 	}
 }

-func TestFindMessageSenderOpenDingTalkIDIgnoresUnrelatedNestedIdentity(t *testing.T) {
+func TestCrossPlatformCoverageFindMessageSenderOpenDingTalkIDIgnoresUnrelatedNestedIdentity(t *testing.T) {
 	message := map[string]any{
 		"content": map[string]any{
 			"mentions": []any{
@@ -627,7 +833,7 @@ func TestChatListP2POnlyDropsGroups(t *testing.T) {
 	}
 }

-func TestFeedGroupQueryProjectPreservesRequestOrderAndMissingLedger(t *testing.T) {
+func TestCrossPlatformCoverageFeedGroupQueryProjectPreservesRequestOrderAndMissingLedger(t *testing.T) {
 	conversations := []map[string]any{
 		{"openConversationId": "cid-a", "conversationName": "A"},
 		{"openConversationId": "cid-b", "conversationName": "B"},
@@ -645,7 +851,7 @@ func TestFeedGroupQueryProjectPreservesRequestOrderAndMissingLedger(t *testing.T
 	}
 }

-func TestFeedGroupQueryDoesNotMisreportMissingItemWhenSourceHasMore(t *testing.T) {
+func TestCrossPlatformCoverageFeedGroupQueryDoesNotMisreportMissingItemWhenSourceHasMore(t *testing.T) {
 	fake := &larkAlignmentCaller{
 		category: `{"result":{"hasMore":true,"list":[{"openConversationId":"cid-a","conversationName":"A"}]}}`,
 	}
@@ -0,0 +1,120 @@
+// 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 chat
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+)
+
+// ValidateMessageExportOutput applies the same workspace-relative and
+// no-symlink boundary used by message resource downloads. The export target is
+// always a file; directory-shaped paths are rejected instead of inventing a
+// name.
+func ValidateMessageExportOutput(output string) error {
+	trimmed := strings.TrimSpace(output)
+	if strings.HasSuffix(trimmed, "/") ||
+		strings.HasSuffix(trimmed, string(os.PathSeparator)) {
+		return apperrors.NewValidation("--output 必须是 JSON 文件路径，不能是目录")
+	}
+	if !strings.EqualFold(filepath.Ext(trimmed), ".json") {
+		return apperrors.NewValidation("--output 必须使用 .json 文件扩展名")
+	}
+	return validateResourceDownloadOutputFlag(output, "--output")
+}
+
+// WriteMessageExportJSON atomically publishes the exact structured message
+// ledger. It defaults to no-clobber and never follows a symlink outside the
+// current working directory.
+func WriteMessageExportJSON(output string, overwrite bool, payload any) (relativePath string, size int, err error) {
+	if err := ValidateMessageExportOutput(output); err != nil {
+		return "", 0, err
+	}
+	cwd, err := resourceGetwd()
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("读取工作目录失败: %v", err))
+	}
+	base, err := resourceAbs(cwd)
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("解析工作目录失败: %v", err))
+	}
+	realBase, err := resourceEvalSymlinks(base)
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("解析工作目录失败: %v", err))
+	}
+
+	target := filepath.Join(realBase, filepath.Clean(strings.TrimSpace(output)))
+	parent := filepath.Dir(target)
+	if err := ensureResourceDownloadParent(realBase, parent); err != nil {
+		return "", 0, err
+	}
+	realParent, err := resourceEvalSymlinks(parent)
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("解析输出目录失败: %v", err))
+	}
+	parentRel, err := resourceRel(realBase, realParent)
+	if err != nil || parentRel == ".." || strings.HasPrefix(parentRel, ".."+string(os.PathSeparator)) {
+		return "", 0, apperrors.NewValidation("--output 解析后逃逸工作目录")
+	}
+	target = filepath.Join(realParent, filepath.Base(target))
+	if info, statErr := resourceLstat(target); statErr == nil {
+		if info.Mode()&os.ModeSymlink != 0 {
+			return "", 0, apperrors.NewValidation("--output 目标不能是符号链接")
+		}
+		if info.IsDir() {
+			return "", 0, apperrors.NewValidation("--output 目标是目录，无法写入 JSON 文件")
+		}
+		if !overwrite {
+			return "", 0, apperrors.NewValidation("目标文件已存在；如确认覆盖请显式传 --overwrite")
+		}
+	} else if !errors.Is(statErr, os.ErrNotExist) {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("检查输出文件失败: %v", statErr))
+	}
+
+	rendered, err := json.MarshalIndent(payload, "", "  ")
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("编码消息导出失败: %v", err))
+	}
+	rendered = append(rendered, '\n')
+	temp, err := resourceCreateTemp(realParent, "."+filepath.Base(target)+".part-*")
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("创建消息导出临时文件失败: %v", err))
+	}
+	tempPath := temp.Name()
+	defer func() {
+		_ = resourceTempClose(temp)
+		_ = os.Remove(tempPath)
+	}()
+	if _, err := temp.Write(rendered); err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("写入消息导出失败: %v", err))
+	}
+	if err := resourceTempSync(temp); err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("同步消息导出失败: %v", err))
+	}
+	if err := resourceTempClose(temp); err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("关闭消息导出失败: %v", err))
+	}
+	if overwrite {
+		if err := resourceRename(tempPath, target); err != nil {
+			return "", 0, apperrors.NewInternal(fmt.Sprintf("发布消息导出失败: %v", err))
+		}
+	} else if err := resourceLink(tempPath, target); err != nil {
+		if errors.Is(err, os.ErrExist) {
+			return "", 0, apperrors.NewValidation("目标文件已存在；如确认覆盖请显式传 --overwrite")
+		}
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("发布消息导出失败: %v", err))
+	}
+	relativePath, err = resourceRel(realBase, target)
+	if err != nil {
+		return "", 0, apperrors.NewInternal(fmt.Sprintf("解析输出相对路径失败: %v", err))
+	}
+	return filepath.ToSlash(relativePath), len(rendered), nil
+}
@@ -22,6 +22,7 @@ import (
 	"net/http"
 	"net/url"
 	"os"
+	pathpkg "path"
 	"path/filepath"
 	"strings"
 	"time"
@@ -44,7 +45,7 @@ var (
 	resourceCopy         = io.Copy
 	resourceTempSync     = (*os.File).Sync
 	resourceTempClose    = (*os.File).Close
-	resourceRename       = os.Rename
+	resourceRename       = replaceFileAtomically
 	resourceLink         = os.Link
 	resourceDownload     = downloadResourceAtomically
 )
@@ -58,15 +59,15 @@ var MessagesResourceDownload = shortcut.Shortcut{
 	Description: "安全下载消息资源（图片/视频/语音/文件）到本地",
 	Intent: "当你需要拿到消息里的实际图片、视频、语音或钉盘文件，而不只是资源 ID 时使用；" +
 		"mediaId 用消息和会话身份换取下载地址，fileId 复用钉盘下载能力，再安全写入工作目录内的相对路径。" +
-		"默认不覆盖已有文件，只有显式传 --overwrite 才覆盖；按既有安全本地下载约定无需交互确认。",
+		"默认不覆盖已有文件，只有显式传 --overwrite 才覆盖；下载采用整文件临时落盘后原子发布，不支持 Range 断点续传。按既有安全本地下载约定无需交互确认。",
 	Risk: shortcut.RiskRead,
 	Flags: []shortcut.Flag{
-		{Name: "type", Type: shortcut.FlagString, Default: "mediaId", Desc: "资源类型", Enum: []string{"mediaId", "fileId"}},
+		{Name: "type", Type: shortcut.FlagString, Default: "mediaId", Desc: "资源类型；--type mediaId 时必须同时提供 --message-id 和 --open-conversation-id；fileId 不需要消息上下文", Enum: []string{"mediaId", "fileId"}},
 		{Name: "resource-id", Type: shortcut.FlagString, Desc: "消息中的 mediaId 或 fileId", Required: true},
-		{Name: "message-id", Type: shortcut.FlagString, Desc: "mediaId 所属消息的 openMessageId"},
-		{Name: "open-conversation-id", Type: shortcut.FlagString, Desc: "mediaId 所属会话的 openConversationId"},
-		{Name: "output", Type: shortcut.FlagString, Default: ".", Desc: "工作目录内的相对文件或目录路径"},
-		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖已存在的目标文件（默认拒绝）"},
+		{Name: "message-id", Type: shortcut.FlagString, Desc: "mediaId 所属消息的 openMessageId；--type mediaId 时必须同时提供 --message-id 和 --open-conversation-id；fileId 不需要消息上下文"},
+		{Name: "open-conversation-id", Type: shortcut.FlagString, Desc: "mediaId 所属会话的 openConversationId；--type mediaId 时必须同时提供 --message-id 和 --open-conversation-id；fileId 不需要消息上下文"},
+		{Name: "output", Type: shortcut.FlagString, Default: ".", Desc: "工作目录内的相对路径；不允许绝对路径或 .. 逃逸"},
+		{Name: "overwrite", Type: shortcut.FlagBool, Desc: "允许覆盖工作目录内已存在的目标文件（默认拒绝）"},
 	},
 	Constraints: []shortcut.Constraint{
 		{
@@ -204,24 +205,35 @@ func validateResourceDownloadOutputFlag(output, flagName string) error {
 	if output == "" {
 		return apperrors.NewValidation(flagName + " 不能为空")
 	}
-	// Reject OS-absolute paths and Unix-rooted forms ("/x") even on Windows,
-	// where filepath.IsAbs("/x") is false but the path is still not a cwd-relative output.
-	if filepath.IsAbs(output) || strings.HasPrefix(filepath.ToSlash(output), "/") {
+	if resourcePathIsAbsolute(output) {
 		return apperrors.NewValidation(flagName + " 只接受工作目录内的相对路径")
 	}
-	clean := filepath.Clean(filepath.FromSlash(output))
-	if resourcePathEscapesBase(clean) {
+	if resourcePathEscapesBase(output) {
 		return apperrors.NewValidation(flagName + " 不允许使用 .. 逃逸工作目录")
 	}
 	return nil
 }

-// resourcePathEscapesBase reports whether rel escapes its base directory.
-// Rel values may use '/' or the OS separator (for example mocked filepath.Rel
-// results), so normalize before comparing against "..".
-func resourcePathEscapesBase(rel string) bool {
-	rel = filepath.Clean(filepath.FromSlash(strings.TrimSpace(rel)))
-	return rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator))
+func resourcePathIsAbsolute(value string) bool {
+	if filepath.IsAbs(value) {
+		return true
+	}
+	portable := strings.ReplaceAll(strings.TrimSpace(value), "\\", "/")
+	if pathpkg.IsAbs(portable) {
+		return true
+	}
+	return len(portable) >= 2 &&
+		((portable[0] >= 'a' && portable[0] <= 'z') ||
+			(portable[0] >= 'A' && portable[0] <= 'Z')) &&
+		portable[1] == ':'
+}
+
+// resourcePathEscapesBase reports whether a relative path escapes its base.
+// Normalize both separators so the check remains portable on every host OS.
+func resourcePathEscapesBase(value string) bool {
+	portable := strings.ReplaceAll(strings.TrimSpace(value), "\\", "/")
+	clean := pathpkg.Clean(portable)
+	return clean == ".." || strings.HasPrefix(clean, "../")
 }

 func resourceDownloadInfo(data map[string]any) (string, map[string]string, error) {
@@ -600,5 +612,5 @@ func downloadResourceAtomically(
 }

 func init() {
-	shortcut.Register(MessagesResourceDownload)
+	shortcut.Register(withReviewedChatShortcutContracts(MessagesResourceDownload)...)
 }
@@ -599,3 +599,221 @@ func TestCrossPlatformCoverageDownloadResourceCopySuccessWithBuffer(t *testing.T
 		t.Fatalf("copied = %q", copied.String())
 	}
 }
+
+func TestCrossPlatformCoverageMessageExportFailureBoundaries(t *testing.T) {
+	for _, output := range []string{"exports/", "exports/messages.txt"} {
+		if err := ValidateMessageExportOutput(output); err == nil {
+			t.Fatalf("ValidateMessageExportOutput(%q) succeeded", output)
+		}
+	}
+	if _, _, err := WriteMessageExportJSON("not-json.txt", false, map[string]any{}); err == nil {
+		t.Fatal("invalid export path reached write pipeline")
+	}
+
+	baseSetup := func(t *testing.T) string {
+		t.Helper()
+		resetResourceDownloadHooks(t)
+		base := t.TempDir()
+		resourceGetwd = func() (string, error) { return base, nil }
+		resourceAbs = filepath.Abs
+		resourceEvalSymlinks = filepath.EvalSymlinks
+		resourceLstat = os.Lstat
+		resourceRel = filepath.Rel
+		resourceCreateTemp = os.CreateTemp
+		resourceTempSync = (*os.File).Sync
+		resourceTempClose = (*os.File).Close
+		resourceRename = os.Rename
+		resourceLink = os.Link
+		return base
+	}
+
+	t.Run("path setup", func(t *testing.T) {
+		baseSetup(t)
+		resourceGetwd = func() (string, error) { return "", errors.New("getwd") }
+		if _, _, err := WriteMessageExportJSON("out.json", false, map[string]any{}); err == nil {
+			t.Fatal("getwd failure ignored")
+		}
+	})
+	t.Run("absolute path", func(t *testing.T) {
+		baseSetup(t)
+		resourceAbs = func(string) (string, error) { return "", errors.New("abs") }
+		if _, _, err := WriteMessageExportJSON("out.json", false, map[string]any{}); err == nil {
+			t.Fatal("abs failure ignored")
+		}
+	})
+	t.Run("base symlink", func(t *testing.T) {
+		baseSetup(t)
+		resourceEvalSymlinks = func(string) (string, error) { return "", errors.New("eval") }
+		if _, _, err := WriteMessageExportJSON("out.json", false, map[string]any{}); err == nil {
+			t.Fatal("base symlink failure ignored")
+		}
+	})
+	t.Run("parent symlink", func(t *testing.T) {
+		base := baseSetup(t)
+		calls := 0
+		resourceEvalSymlinks = func(path string) (string, error) {
+			calls++
+			if calls == 1 {
+				return base, nil
+			}
+			return "", errors.New("parent")
+		}
+		if _, _, err := WriteMessageExportJSON("exports/out.json", false, map[string]any{}); err == nil {
+			t.Fatal("parent symlink failure ignored")
+		}
+	})
+	t.Run("parent creation", func(t *testing.T) {
+		baseSetup(t)
+		resourceLstat = func(string) (os.FileInfo, error) {
+			return os.Stat(filepath.Join(t.TempDir(), "missing-parent"))
+		}
+		resourceMkdir = func(string, os.FileMode) error { return errors.New("mkdir") }
+		if _, _, err := WriteMessageExportJSON("exports/out.json", false, map[string]any{}); err == nil {
+			t.Fatal("parent creation failure ignored")
+		}
+	})
+	t.Run("parent escapes", func(t *testing.T) {
+		base := baseSetup(t)
+		resourceEvalSymlinks = func(path string) (string, error) {
+			if path == base {
+				return base, nil
+			}
+			return filepath.Dir(base), nil
+		}
+		if _, _, err := WriteMessageExportJSON("exports/out.json", false, map[string]any{}); err == nil {
+			t.Fatal("parent escape accepted")
+		}
+	})
+
+	for _, tc := range []struct {
+		name  string
+		setup func(t *testing.T, base string)
+	}{
+		{name: "existing symlink", setup: func(t *testing.T, base string) {
+			target := filepath.Join(base, "out.json")
+			if err := os.Symlink("missing", target); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "existing directory", setup: func(t *testing.T, base string) {
+			if err := os.Mkdir(filepath.Join(base, "out.json"), 0o755); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "existing no clobber", setup: func(t *testing.T, base string) {
+			if err := os.WriteFile(filepath.Join(base, "out.json"), []byte("old"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+		}},
+		{name: "lstat error", setup: func(t *testing.T, _ string) {
+			resourceLstat = func(string) (os.FileInfo, error) { return nil, errors.New("lstat") }
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			base := baseSetup(t)
+			tc.setup(t, base)
+			if _, _, err := WriteMessageExportJSON("out.json", false, map[string]any{}); err == nil {
+				t.Fatal("invalid existing target accepted")
+			}
+		})
+	}
+
+	for _, tc := range []struct {
+		name      string
+		overwrite bool
+		payload   any
+		setup     func(t *testing.T, base string)
+	}{
+		{name: "marshal", payload: make(chan int)},
+		{name: "create temp", payload: map[string]any{}, setup: func(t *testing.T, _ string) {
+			resourceCreateTemp = func(string, string) (*os.File, error) { return nil, errors.New("create") }
+		}},
+		{name: "write", payload: map[string]any{}, setup: func(t *testing.T, base string) {
+			resourceCreateTemp = func(string, string) (*os.File, error) {
+				file, err := os.CreateTemp(base, "closed-*")
+				if err == nil {
+					_ = file.Close()
+				}
+				return file, err
+			}
+		}},
+		{name: "sync", payload: map[string]any{}, setup: func(t *testing.T, _ string) {
+			resourceTempSync = func(*os.File) error { return errors.New("sync") }
+		}},
+		{name: "close", payload: map[string]any{}, setup: func(t *testing.T, _ string) {
+			resourceTempClose = func(file *os.File) error {
+				_ = file.Close()
+				return errors.New("close")
+			}
+		}},
+		{name: "rename", overwrite: true, payload: map[string]any{}, setup: func(t *testing.T, base string) {
+			if err := os.WriteFile(filepath.Join(base, "out.json"), []byte("old"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			resourceRename = func(string, string) error { return errors.New("rename") }
+		}},
+		{name: "link exists", payload: map[string]any{}, setup: func(t *testing.T, _ string) {
+			resourceLink = func(string, string) error { return os.ErrExist }
+		}},
+		{name: "link", payload: map[string]any{}, setup: func(t *testing.T, _ string) {
+			resourceLink = func(string, string) error { return errors.New("link") }
+		}},
+		{name: "final rel", overwrite: true, payload: map[string]any{}, setup: func(t *testing.T, base string) {
+			if err := os.WriteFile(filepath.Join(base, "out.json"), []byte("old"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			calls := 0
+			resourceRel = func(from, to string) (string, error) {
+				calls++
+				if calls < 3 {
+					return filepath.Rel(from, to)
+				}
+				return "", errors.New("rel")
+			}
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			base := baseSetup(t)
+			if tc.setup != nil {
+				tc.setup(t, base)
+			}
+			if _, _, err := WriteMessageExportJSON("out.json", tc.overwrite, tc.payload); err == nil {
+				t.Fatal("failure hook was ignored")
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessageExportOverwriteReplacesExistingFile(t *testing.T) {
+	resetResourceDownloadHooks(t)
+	base := t.TempDir()
+	resourceGetwd = func() (string, error) { return base, nil }
+	resourceAbs = filepath.Abs
+	resourceEvalSymlinks = filepath.EvalSymlinks
+	resourceLstat = os.Lstat
+	resourceRel = filepath.Rel
+	resourceCreateTemp = os.CreateTemp
+	resourceTempSync = (*os.File).Sync
+	resourceTempClose = (*os.File).Close
+	resourceRename = replaceFileAtomically
+	resourceLink = os.Link
+
+	target := filepath.Join(base, "out.json")
+	if err := os.WriteFile(target, []byte("old\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	relative, size, err := WriteMessageExportJSON(
+		"out.json", true, map[string]any{"value": "new"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(target)
+	if err != nil {
+		t.Fatal(err)
+	}
+	const want = "{\n  \"value\": \"new\"\n}\n"
+	if relative != "out.json" || size != len(want) || string(data) != want {
+		t.Fatalf("relative=%q size=%d data=%q", relative, size, data)
+	}
+}
@@ -95,7 +95,7 @@ func TestCrossPlatformCoverageResourceDownloadInfo(t *testing.T) {
 	}
 }

-func TestResolveResourceDownloadPath(t *testing.T) {
+func TestCrossPlatformCoverageResolveResourceDownloadPath(t *testing.T) {
 	base := t.TempDir()
 	if err := os.Mkdir(filepath.Join(base, "downloads"), 0o755); err != nil {
 		t.Fatal(err)
@@ -122,14 +122,30 @@ func TestResolveResourceDownloadPath(t *testing.T) {
 	}
 }

-func TestValidateResourceDownloadOutputUsesOwningFlagName(t *testing.T) {
+func TestCrossPlatformCoverageValidateResourceDownloadOutputUsesOwningFlagName(t *testing.T) {
 	err := validateResourceDownloadOutputFlag("../escape", "--output-dir")
 	if err == nil || !strings.Contains(err.Error(), "--output-dir") {
 		t.Fatalf("error = %v, want --output-dir", err)
 	}
 }

-func TestResolveResourceDownloadPathRejectsSymlinkParentBeforeCreatingOutside(t *testing.T) {
+func TestCrossPlatformCoverageValidateResourceDownloadOutputRejectsPortableAbsolutePaths(t *testing.T) {
+	for _, output := range []string{
+		"/absolute", `\\absolute`, `C:\\absolute`, "C:/absolute",
+		"C:relative", "c:relative",
+	} {
+		if err := validateResourceDownloadOutput(output); err == nil {
+			t.Errorf("portable absolute output %q unexpectedly accepted", output)
+		}
+	}
+	for _, output := range []string{"../escape", `..\\escape`} {
+		if err := validateResourceDownloadOutput(output); err == nil {
+			t.Errorf("portable parent escape %q unexpectedly accepted", output)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageResolveResourceDownloadPathRejectsSymlinkParentBeforeCreatingOutside(t *testing.T) {
 	base := t.TempDir()
 	outside := t.TempDir()
 	link := filepath.Join(base, "linked")
@@ -0,0 +1,160 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package chat
+
+import (
+	"strings"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+const reviewedChatShortcutInterfaceReason = "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."
+
+// reviewedChatShortcutContractCommands is the exact reviewed migration ledger
+// for Chat shortcuts that were delivered by the former committed Schema
+// catalog but did not yet carry #830's typed Contract declaration. Exact names
+// deliberately prevent a future shortcut from entering Schema by accident.
+var reviewedChatShortcutContractCommands = map[string]struct{}{
+	"+category-add-conversation":    {},
+	"+category-list-conversations":  {},
+	"+category-remove-conversation": {},
+	"+chat-add-bot":                 {},
+	"+chat-audit-join":              {},
+	"+chat-create":                  {},
+	"+chat-get-by-id":               {},
+	"+chat-list":                    {},
+	"+chat-members-get":             {},
+	"+chat-mute-member":             {},
+	"+chat-quit":                    {},
+	"+chat-remove-bot":              {},
+	"+chat-role-remove":             {},
+	"+chat-role-remove-user":        {},
+	"+chat-transfer-owner":          {},
+	"+chat-update":                  {},
+	"+chat-update-icon":             {},
+	"+chat-update-settings":         {},
+	"+conversation-clear-messages":  {},
+	"+conversation-clear-red-point": {},
+	"+conversation-hide":            {},
+	"+conversation-mark-read":       {},
+	"+conversation-mark-unread":     {},
+	"+conversation-mute":            {},
+	"+conversation-set-top":         {},
+	"+feed-group-query-item":        {},
+	"+flag-cancel":                  {},
+	"+flag-create":                  {},
+	"+flag-list":                    {},
+	"+messages-add-emoji":           {},
+	"+messages-add-text-emotion":    {},
+	"+messages-batch-recall-by-bot": {},
+	"+messages-batch-send-by-bot":   {},
+	"+messages-combine-forward":     {},
+	"+messages-create-text-emotion": {},
+	"+messages-forward":             {},
+	"+messages-forward-topic":       {},
+	"+messages-list":                {},
+	"+messages-recall":              {},
+	"+messages-recall-by-bot":       {},
+	"+messages-remove-emoji":        {},
+	"+messages-remove-text-emotion": {},
+	"+messages-reply":               {},
+	"+messages-resource-download":   {},
+	"+messages-resource-url":        {},
+	"+messages-send-by-bot":         {},
+	"+messages-set-pin":             {},
+	"+messages-set-top":             {},
+	"+messages-unset-pin":           {},
+	"+messages-unset-top":           {},
+}
+
+// withReviewedChatShortcutContracts ports the previously reviewed Chat Schema
+// records into #830's typed declaration model. Existing explicit Contracts are
+// preserved. Missing Contracts must be listed in the exact ledger above.
+func withReviewedChatShortcutContracts(values ...shortcut.Shortcut) []shortcut.Shortcut {
+	out := make([]shortcut.Shortcut, len(values))
+	for i, value := range values {
+		out[i] = value
+		if !value.Contract.Empty() {
+			continue
+		}
+		if _, reviewed := reviewedChatShortcutContractCommands[value.Command]; !reviewed {
+			continue
+		}
+		out[i].Safety = reviewedChatShortcutSafety(value.Risk)
+		out[i].Contract = reviewedChatShortcutContract(value)
+	}
+	return out
+}
+
+func reviewedChatShortcutSafety(risk shortcut.Risk) contract.SafetySpec {
+	switch risk {
+	case shortcut.RiskWrite:
+		return contract.SafetySpec{
+			Effect: "write", Risk: "medium",
+			Confirmation: "user_required", Idempotency: "unknown",
+		}
+	case shortcut.RiskHighWrite:
+		return contract.SafetySpec{
+			Effect: "destructive", Risk: "high",
+			Confirmation: "user_required", Idempotency: "unknown",
+		}
+	default:
+		return contract.SafetySpec{
+			Effect: "read", Risk: "low",
+			Confirmation: "not_required", Idempotency: "idempotent",
+		}
+	}
+}
+
+func reviewedChatShortcutContract(value shortcut.Shortcut) corecmd.ContractDecl {
+	name := "shortcut_" + strings.ReplaceAll(strings.TrimPrefix(value.Command, "+"), "-", "_")
+	cliPath := value.Service + " " + value.Command
+	aliases := make([]string, 0, len(value.Aliases))
+	for _, alias := range value.Aliases {
+		aliases = append(aliases, value.Service+" "+alias)
+	}
+	description := strings.TrimSpace(value.Intent)
+	if description == "" {
+		description = strings.TrimSpace(value.Description)
+	}
+	examples := append([]string(nil), value.Tips...)
+	if len(examples) > 2 {
+		examples = examples[:2]
+	}
+	return corecmd.ContractDecl{
+		Title:       value.Description,
+		Description: description,
+		Interface: &contract.InterfaceSpec{
+			Mode:         contract.InterfaceModeComposite,
+			Availability: contract.InterfaceAvailable,
+			Reason:       reviewedChatShortcutInterfaceReason,
+		},
+		Selection: contract.SelectionSpec{
+			AgentSummary: value.Description,
+			UseWhen:      []string{description},
+			AvoidWhen:    []string{"需要该 Shortcut 未公开的底层参数、原始响应或不同执行语义时，改用对应原子命令"},
+			Examples:     examples,
+		},
+		Identity: contract.ToolIdentitySpec{
+			ProductID:      value.Service,
+			Name:           name,
+			CanonicalPath:  value.Service + "." + name,
+			CLIPath:        cliPath,
+			PrimaryCLIPath: cliPath,
+			Aliases:        aliases,
+		},
+	}
+}
@@ -0,0 +1,77 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package chat
+
+import (
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+)
+
+func TestCrossPlatformCoverageReviewedChatShortcutContracts(t *testing.T) {
+	base := shortcut.Shortcut{
+		Service:     "chat",
+		Command:     "+chat-create",
+		Aliases:     []string{"+chat-create-alias"},
+		Description: "创建群聊",
+		Intent:      "需要创建群聊时使用",
+		Risk:        shortcut.RiskWrite,
+		Tips: []string{
+			"dws chat +chat-create --title demo",
+			"dws chat +chat-create --title demo2",
+			"dws chat +chat-create --title ignored",
+		},
+	}
+	got := withReviewedChatShortcutContracts(base)
+	if len(got) != 1 || got[0].Contract.Empty() {
+		t.Fatalf("reviewed contract = %#v", got)
+	}
+	declared := got[0]
+	if declared.Safety.Effect != "write" || declared.Safety.Confirmation != "user_required" {
+		t.Fatalf("write safety = %#v", declared.Safety)
+	}
+	if declared.Contract.Identity.CanonicalPath != "chat.shortcut_chat_create" ||
+		declared.Contract.Identity.PrimaryCLIPath != "chat +chat-create" ||
+		len(declared.Contract.Identity.Aliases) != 1 ||
+		declared.Contract.Identity.Aliases[0] != "chat +chat-create-alias" {
+		t.Fatalf("identity = %#v", declared.Contract.Identity)
+	}
+	if len(declared.Contract.Selection.Examples) != 2 {
+		t.Fatalf("examples = %#v, want reviewed maximum of two", declared.Contract.Selection.Examples)
+	}
+
+	high := base
+	high.Risk = shortcut.RiskHighWrite
+	if safety := withReviewedChatShortcutContracts(high)[0].Safety; safety.Effect != "destructive" || safety.Risk != "high" {
+		t.Fatalf("high-write safety = %#v", safety)
+	}
+	read := base
+	read.Risk = shortcut.RiskRead
+	read.Intent = ""
+	if declared := withReviewedChatShortcutContracts(read)[0]; declared.Safety.Effect != "read" || declared.Contract.Description != read.Description {
+		t.Fatalf("read/fallback declaration = %#v", declared)
+	}
+
+	unreviewed := base
+	unreviewed.Command = "+future-unreviewed"
+	if declared := withReviewedChatShortcutContracts(unreviewed)[0]; !declared.Contract.Empty() {
+		t.Fatalf("unreviewed future shortcut entered Schema: %#v", declared.Contract)
+	}
+	explicit := base
+	explicit.Contract = corecmd.ContractDecl{Description: "preserve"}
+	if declared := withReviewedChatShortcutContracts(explicit)[0]; declared.Contract.Description != "preserve" {
+		t.Fatalf("explicit contract overwritten: %#v", declared.Contract)
+	}
+}
@@ -8,6 +8,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"os"
 	"strings"
 	"time"
 	"unicode/utf8"
@@ -18,10 +19,18 @@ import (
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

 const messagesSendFileUploadTimeout = 10 * time.Minute

+const (
+	messagesSendMaxBotGroups     = 100
+	messagesSendMaxGroupFileSize = 1 << 20
+)
+
+var messagesSendReadGroupFile = os.ReadFile
+
 // MessagesSend is the identity-aware common sending entry point. The current
 // user branch reuses the native message leaf's reviewed file-upload flow and
 // existing-mediaId image path. Bot and webhook remain text/Markdown-only
@@ -30,8 +39,8 @@ var MessagesSend = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+messages-send",
 	Product:     "chat",
-	Description: "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
-	Intent:      "当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。",
+	Description: "按身份和目标统一发送消息，Bot 多群返回逐目标 ledger",
+	Intent:      "当你需要文件、复杂 @、幂等，或选择 current-user、bot、webhook 身份发送消息时使用；current-user 可直接传稳定 ID，也可用 --user-query/--chat-query 在 CLI 内唯一解析自然目标，dry-run 与真实执行使用同一解析链。Bot 可用 --groups/--groups-file 向最多 100 个稳定群 ID 发送文本或 Markdown，去重后返回 im.batch-write.v1 逐目标 ledger；webhook 目标由 token 所在群决定。文件上传和已有 mediaId 图片仅 current-user 支持，bot/webhook 不支持富媒体。",
 	Risk:        shortcut.RiskWrite,
 	Safety: contract.SafetySpec{
 		Effect: "write", Risk: "medium",
@@ -45,15 +54,15 @@ var MessagesSend = shortcut.Shortcut{
 			CLIPath:        "chat +messages-send",
 			PrimaryCLIPath: "chat +messages-send",
 		},
-		Description: "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
+		Description: "按身份和目标统一发送消息，Bot 多群返回逐目标 ledger",
 		Interface: &contract.InterfaceSpec{
 			Mode:         "composite",
 			Availability: "available",
 			Reason:       "Reviewed composite send adapter: it selects current-user, bot, or webhook transport; current-user additionally supports live-compatible contact search with exact userId matching, mediaId images, and the native init/upload/commit local-file flow.",
 		},
 		Selection: contract.SelectionSpec{
-			AgentSummary: "统一发送文本、Markdown、当前用户文件或已有 mediaId 图片",
-			UseWhen:      []string{"当你希望用同一个入口选择 current-user、bot 或 webhook 身份发送消息时使用；命令会按身份校验目标、内容和凭据并路由到真实下层。current-user 支持文本/Markdown、已有 mediaId 图片、安全相对路径文件上传和幂等键；--user 传 userId 时包括在 --dry-run 中也会先通过通讯录关键词搜索并按 userId 精确匹配 openDingTalkId。bot 支持群聊或批量单聊文本/Markdown；webhook 的目标由 token 所在群决定。不会把 user 文件能力伪装成 bot/webhook 等价能力。"},
+			AgentSummary: "按身份和目标统一发送消息，Bot 多群返回逐目标 ledger",
+			UseWhen:      []string{"当你需要文件、复杂 @、幂等，或选择 current-user、bot、webhook 身份发送消息时使用；current-user 可直接传稳定 ID，也可用 --user-query/--chat-query 在 CLI 内唯一解析自然目标，dry-run 与真实执行使用同一解析链。Bot 可用 --groups/--groups-file 向最多 100 个稳定群 ID 发送文本或 Markdown，去重后返回 im.batch-write.v1 逐目标 ledger；webhook 目标由 token 所在群决定。文件上传和已有 mediaId 图片仅 current-user 支持，bot/webhook 不支持富媒体。"},
 			AvoidWhen:    []string{"需要 bot/webhook 发送媒体、卡片或 thread 回复时不要假设等价支持；改用真实存在的专用下层命令，缺少下层能力时停止"},
 			Examples: []string{
 				"dws chat +messages-send --as user --chat-id <openConversationId> --markdown \"## 周报\" --idempotency-key <key>",
@@ -66,7 +75,11 @@ var MessagesSend = shortcut.Shortcut{
 		{Name: "as", Type: shortcut.FlagString, Enum: []string{"user", "bot", "webhook"}, Desc: "--identity 的 lark-cli 对齐别名；受发送身份能力矩阵约束"},
 		{Name: "group", Type: shortcut.FlagString, Desc: "群 openConversationId（user/bot 群聊）；受发送身份能力矩阵约束"},
 		{Name: "chat-id", Type: shortcut.FlagString, Desc: "--group 的 lark-cli 对齐别名；受发送身份能力矩阵约束"},
+		{Name: "groups", Type: shortcut.FlagStringSlice, Desc: "多个群 openConversationId（仅 bot；受发送身份能力矩阵约束，逐群返回 typed ledger，最多 100 个）"},
+		{Name: "groups-file", Type: shortcut.FlagString, Desc: "工作目录内相对文本文件（仅 bot；受发送身份能力矩阵约束），每行或逗号分隔一个群 openConversationId"},
+		{Name: "chat-query", Type: shortcut.FlagString, Desc: "按群名解析唯一群聊（仅 user 的高级发送场景）；受发送身份能力矩阵约束"},
 		{Name: "user", Type: shortcut.FlagString, Desc: "单聊接收者 userId（user；包括 --dry-run 也会先通过通讯录搜索精确匹配 openDingTalkId）；受发送身份能力矩阵约束"},
+		{Name: "user-query", Type: shortcut.FlagString, Desc: "按姓名解析唯一 openDingTalkId（仅 user 的高级发送场景）；受发送身份能力矩阵约束"},
 		{Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊接收者 openDingTalkId（user）；受发送身份能力矩阵约束"},
 		{Name: "users", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 userId（bot）；受发送身份能力矩阵约束"},
 		{Name: "open-dingtalk-ids", Type: shortcut.FlagStringSlice, Desc: "批量单聊接收者 openDingTalkId（bot）；受发送身份能力矩阵约束"},
@@ -99,14 +112,14 @@ var MessagesSend = shortcut.Shortcut{
 		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"uuid", "idempotency-key"}},
 		{
 			Kind:        shortcut.ConstraintCustom,
-			Flags:       []string{"identity", "as", "group", "chat-id", "user", "open-dingtalk-id", "users", "open-dingtalk-ids", "robot-code", "webhook-token", "uuid", "idempotency-key"},
-			Description: "目标、凭据和幂等参数受发送身份能力矩阵约束：user 必须指定一个群聊或单聊目标；bot 必须指定 robot-code 和一类目标；webhook 必须指定 webhook-token；幂等键仅 user 支持",
+			Flags:       []string{"identity", "as", "group", "chat-id", "groups", "groups-file", "chat-query", "user", "user-query", "open-dingtalk-id", "users", "open-dingtalk-ids", "robot-code", "webhook-token", "uuid", "idempotency-key"},
+			Description: "目标、凭据和幂等参数受发送身份能力矩阵约束：user 必须指定一个群聊或单聊目标；bot 必须指定 robot-code 和一类目标，多群最多 100 个并逐项返回 ledger；webhook 必须指定 webhook-token；幂等键仅 user 支持",
 		},
 	},
 	Tips: []string{
 		`dws chat +messages-send --as user --chat-id <openConversationId> --markdown "## 周报" --idempotency-key <key>`,
 		`dws chat +messages-send --as user --user <userId> --msg-type file --file ./report.pdf --idempotency-key <key>`,
-		`dws chat +messages-send --as bot --robot-code <robotCode> --users userId1,userId2 --text "请提交周报"`,
+		`dws chat +messages-send --as bot --robot-code <robotCode> --groups <openConversationId1>,<openConversationId2> --text "请提交周报"`,
 	},
 	Validate: validateMessagesSend,
 	Execute:  executeMessagesSend,
@@ -115,7 +128,13 @@ var MessagesSend = shortcut.Shortcut{
 func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 	identity := messagesSendIdentity(rt)
 	group := rt.StrFirst("chat-id", "group")
+	botGroups, botGroupsErr := messagesSendBotGroups(rt)
+	if botGroupsErr != nil {
+		return botGroupsErr
+	}
+	chatQuery := rt.Str("chat-query")
 	userID := rt.Str("user")
+	userQuery := rt.Str("user-query")
 	openID := rt.Str("open-dingtalk-id")
 	users := uniqueShortcutStrings(rt.StrSlice("users"))
 	openIDs := uniqueShortcutStrings(rt.StrSlice("open-dingtalk-ids"))
@@ -134,29 +153,36 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 	}
 	switch identity {
 	case "user":
-		targetCount := nonEmptyStringCount(group, userID, openID)
+		targetCount := nonEmptyStringCount(group, chatQuery, userID, userQuery, openID)
 		if targetCount != 1 {
-			return apperrors.NewValidation("--identity user 时 --group、--user、--open-dingtalk-id 必须且只能指定一个")
+			return apperrors.NewValidation("--identity user 时 --group/--chat-id、--chat-query、--user、--user-query、--open-dingtalk-id 必须且只能指定一个")
 		}
-		if len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" || rt.Str("webhook-token") != "" {
+		if len(users) > 0 || len(openIDs) > 0 || len(botGroups) > 0 || rt.Str("robot-code") != "" || rt.Str("webhook-token") != "" {
 			return apperrors.NewValidation("--identity user 不接受 bot/webhook 凭据或批量目标")
 		}
 		if len(atUserIDs) > 0 || len(atMobiles) > 0 {
 			return apperrors.NewValidation("--identity user 只接受 --at-open-dingtalk-ids")
 		}
-		if (userID != "" || openID != "") && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
+		if (userID != "" || userQuery != "" || openID != "") && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
 			return apperrors.NewValidation("user 单聊不接受 @ 参数；@ 只适用于群聊")
 		}
 		if contentType != "text" && contentType != "markdown" && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
 			return apperrors.NewValidation("user image/file/audio/video 当前不接受 @ 参数")
 		}
 	case "bot":
+		if chatQuery != "" || userQuery != "" {
+			return apperrors.NewValidation("--identity bot 当前不接受 --chat-query 或 --user-query；请传真实群 ID 或批量用户 ID")
+		}
 		if rt.Str("robot-code") == "" {
 			return apperrors.NewValidation("--identity bot 必须指定 --robot-code")
 		}
 		hasDirect := len(users)+len(openIDs) > 0
-		if (group != "") == hasDirect {
-			return apperrors.NewValidation("--identity bot 时 --group 与批量单聊目标必须且只能指定一类")
+		hasGroup := group != "" || len(botGroups) > 0
+		if hasGroup == hasDirect {
+			return apperrors.NewValidation("--identity bot 时单群/多群与批量单聊目标必须且只能指定一类")
+		}
+		if group != "" && len(botGroups) > 0 {
+			return apperrors.NewValidation("--identity bot 时 --group/--chat-id 与 --groups/--groups-file 不能同时使用")
 		}
 		if userID != "" || openID != "" || rt.Str("webhook-token") != "" {
 			return apperrors.NewValidation("--identity bot 不接受 --user、--open-dingtalk-id 或 --webhook-token")
@@ -170,14 +196,17 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if messagesSendIdempotencyKey(rt) != "" {
 			return apperrors.NewValidation("--uuid 当前仅 user 身份的下层支持")
 		}
-		if contentType != "text" && contentType != "markdown" {
+		if !messageIdentitySupportsContent(identity, contentType) {
 			return apperrors.NewValidation("--identity bot 当前下层只支持 text/markdown")
 		}
 	case "webhook":
+		if chatQuery != "" || userQuery != "" {
+			return apperrors.NewValidation("--identity webhook 的目标由 token 所在群决定，不接受 --chat-query 或 --user-query")
+		}
 		if rt.Str("webhook-token") == "" {
 			return apperrors.NewValidation("--identity webhook 必须指定 --webhook-token")
 		}
-		if group != "" || userID != "" || openID != "" || len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" {
+		if group != "" || len(botGroups) > 0 || userID != "" || openID != "" || len(users) > 0 || len(openIDs) > 0 || rt.Str("robot-code") != "" {
 			return apperrors.NewValidation("--identity webhook 的目标由 token 所在群决定，不接受其他目标或 bot Code")
 		}
 		if len(atOpenIDs) > 0 {
@@ -186,7 +215,7 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if messagesSendIdempotencyKey(rt) != "" {
 			return apperrors.NewValidation("--uuid 当前仅 user 身份的下层支持")
 		}
-		if contentType != "text" && contentType != "markdown" {
+		if !messageIdentitySupportsContent(identity, contentType) {
 			return apperrors.NewValidation("--identity webhook 当前下层只支持 text/markdown")
 		}
 	}
@@ -225,33 +254,10 @@ func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 		if contentType == "file" || contentType == "audio" || contentType == "video" {
 			return executeMessagesSendUserFile(rt, group, openID, contentType)
 		}
-		if group != "" {
-			body = helpers.NormalizeMessageMentions(
-				body,
-				uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")),
-				rt.Bool("at-all"),
-				true,
-			)
-		}
-		content, _ := json.Marshal(map[string]string{"title": title, "text": body})
-		params := rt.AddAIMessageTag(map[string]any{
-			"msgType": "markdown",
-			"content": string(content),
-		})
-		if group != "" {
-			params["openConversationId"] = group
-			if values := uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")); len(values) > 0 {
-				params["atOpenDingTalkIds"] = values
-			}
-			if rt.Bool("at-all") {
-				params["atAll"] = true
-			}
-		} else {
-			params["receiverOpenDingTalkId"] = openID
-		}
-		if value := messagesSendIdempotencyKey(rt); value != "" {
-			params["uuid"] = value
-		}
+		params := resolvedUserMarkdownParams(rt, ResolvedUserMessageTarget{
+			GroupID:        group,
+			OpenDingTalkID: openID,
+		}, title, body, uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")), rt.Bool("at-all"), messagesSendIdempotencyKey(rt))
 		return executeUnifiedMessageWrite(rt, "chat", "send_personal_message", params)
 	case "bot":
 		body = helpers.NormalizeMessageMentions(
@@ -281,6 +287,31 @@ func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 			}
 			return executeUnifiedMessageWrite(rt, "bot", "send_robot_group_message", params)
 		}
+		groups, err := messagesSendBotGroups(rt)
+		if err != nil {
+			return err
+		}
+		if len(groups) > 0 {
+			items := make([]shortcutBatchWrite, 0, len(groups))
+			for _, group := range groups {
+				arguments := make(map[string]any, len(params)+1)
+				for key, value := range params {
+					arguments[key] = value
+				}
+				arguments["openConversationId"] = group
+				if values := uniqueShortcutStrings(rt.StrSlice("at-user-ids")); len(values) > 0 {
+					arguments["atUserIds"] = values
+				}
+				if values := uniqueShortcutStrings(rt.StrSlice("at-open-dingtalk-ids")); len(values) > 0 {
+					arguments["atOpendingtalkIds"] = values
+				}
+				if rt.Bool("at-all") {
+					arguments["isAtAll"] = "true"
+				}
+				items = append(items, shortcutBatchWrite{target: group, arguments: arguments})
+			}
+			return executeShortcutBatchWrite(rt, "bot", "send_robot_group_message", items)
+		}
 		if values := uniqueShortcutStrings(rt.StrSlice("users")); len(values) > 0 {
 			params["userIds"] = values
 		}
@@ -393,6 +424,20 @@ func messagesSendUserTarget(rt *shortcut.RuntimeContext) (group, openID string,
 	if openID != "" || group != "" {
 		return group, openID, nil
 	}
+	if query := rt.Str("chat-query"); query != "" {
+		resolved, resolveErr := targetresolver.ResolveChat(rt, query)
+		if resolveErr != nil {
+			return "", "", resolveErr
+		}
+		return resolved.Selected.OpenConversationID, "", nil
+	}
+	if query := rt.Str("user-query"); query != "" {
+		resolved, resolveErr := targetresolver.ResolveUser(rt, query, targetresolver.IdentityOpenDingTalkID)
+		if resolveErr != nil {
+			return "", "", resolveErr
+		}
+		return "", resolved.Selected.OpenDingTalkID, nil
+	}
 	openID, err = resolveUserOpenDingTalkID(rt, rt.Str("user"))
 	if err != nil {
 		return "", "", err
@@ -400,6 +445,64 @@ func messagesSendUserTarget(rt *shortcut.RuntimeContext) (group, openID string,
 	return "", openID, nil
 }

+// ResolvedUserMessageTarget is the stable target accepted by the shared user
+// send engine after natural-name resolution has completed.
+type ResolvedUserMessageTarget struct {
+	GroupID        string
+	OpenDingTalkID string
+}
+
+// ExecuteResolvedUserMarkdown lets narrow semantic shortcuts such as +dm and
+// +send-to-group reuse the same target/content/AI-tag parameter builder while
+// preserving their existing raw lower-response output contract.
+func ExecuteResolvedUserMarkdown(
+	rt *shortcut.RuntimeContext,
+	target ResolvedUserMessageTarget,
+	text string,
+) error {
+	params := resolvedUserMarkdownParams(
+		rt,
+		target,
+		text,
+		text,
+		nil,
+		false,
+		"",
+	)
+	return rt.CallMCP("send_personal_message", params)
+}
+
+func resolvedUserMarkdownParams(
+	rt *shortcut.RuntimeContext,
+	target ResolvedUserMessageTarget,
+	title, body string,
+	atOpenIDs []string,
+	atAll bool,
+	idempotencyKey string,
+) map[string]any {
+	if target.GroupID != "" {
+		body = helpers.NormalizeMessageMentions(body, atOpenIDs, atAll, true)
+	}
+	content, _ := json.Marshal(map[string]string{"title": title, "text": body})
+	params := rt.AddAIMessageTag(map[string]any{
+		"msgType": "markdown",
+		"content": string(content),
+	})
+	addMessagesSendUserTarget(params, target.GroupID, target.OpenDingTalkID)
+	if target.GroupID != "" {
+		if len(atOpenIDs) > 0 {
+			params["atOpenDingTalkIds"] = atOpenIDs
+		}
+		if atAll {
+			params["atAll"] = true
+		}
+	}
+	if idempotencyKey != "" {
+		params["uuid"] = idempotencyKey
+	}
+	return params
+}
+
 func resolveUserOpenDingTalkID(rt *shortcut.RuntimeContext, userID string) (string, error) {
 	userID = strings.TrimSpace(userID)
 	data, err := rt.CallMCPData("contact", "search_contact_by_key_word", map[string]any{
@@ -546,6 +649,52 @@ func messagesSendIdempotencyKey(rt *shortcut.RuntimeContext) string {
 	return rt.StrFirst("idempotency-key", "uuid")
 }

+func messagesSendBotGroups(rt *shortcut.RuntimeContext) ([]string, error) {
+	if rt.Changed("groups") && rt.Changed("groups-file") {
+		return nil, apperrors.NewValidation("--groups 与 --groups-file 不能同时指定")
+	}
+	groups := uniqueShortcutStrings(rt.StrSlice("groups"))
+	if path := rt.Str("groups-file"); path != "" {
+		safePath, err := apperrors.SafeInputPath(path)
+		if err != nil {
+			return nil, fmt.Errorf("校验 --groups-file 失败: %w", err)
+		}
+		info, err := os.Stat(safePath)
+		if err != nil {
+			return nil, fmt.Errorf("读取 --groups-file 失败: %w", err)
+		}
+		if !info.Mode().IsRegular() {
+			return nil, apperrors.NewValidation("--groups-file 必须是普通文本文件")
+		}
+		if info.Size() > messagesSendMaxGroupFileSize {
+			return nil, apperrors.NewValidation("--groups-file 不能超过 1 MiB")
+		}
+		raw, err := messagesSendReadGroupFile(safePath)
+		if err != nil {
+			return nil, fmt.Errorf("读取 --groups-file 失败: %w", err)
+		}
+		values := make([]string, 0)
+		for _, line := range strings.Split(string(raw), "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" || strings.HasPrefix(line, "#") {
+				continue
+			}
+			values = append(values, strings.Split(line, ",")...)
+		}
+		groups = uniqueShortcutStrings(values)
+	}
+	if len(groups) > messagesSendMaxBotGroups {
+		return nil, apperrors.NewValidation(fmt.Sprintf(
+			"bot 多群发送最多支持 %d 个群，当前 %d 个",
+			messagesSendMaxBotGroups, len(groups),
+		))
+	}
+	if (rt.Changed("groups") || rt.Changed("groups-file")) && len(groups) == 0 {
+		return nil, apperrors.NewValidation("bot 多群发送至少需要一个 openConversationId")
+	}
+	return groups, nil
+}
+
 func shortcutMessageTitle(text string) string {
 	text = strings.TrimSpace(strings.SplitN(text, "\n", 2)[0])
 	if utf8.RuneCountInString(text) <= 40 {
@@ -556,5 +705,5 @@ func shortcutMessageTitle(text string) string {
 }

 func init() {
-	shortcut.Register(MessagesSend)
+	shortcut.Register(withReviewedChatShortcutContracts(MessagesSend)...)
 }
@@ -0,0 +1,177 @@
+// 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 chat
+
+import (
+	stderrors "errors"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+)
+
+func TestCrossPlatformCoverageMessagesSendResolvesNaturalUserAndChatTargets(t *testing.T) {
+	tests := []struct {
+		name       string
+		args       []string
+		responses  map[string]string
+		wantTarget string
+		wantValue  string
+	}{
+		{
+			name: "user query",
+			args: []string{
+				"chat", "+messages-send", "--as", "user",
+				"--user-query", "张三", "--text", "你好", "--yes",
+			},
+			responses: map[string]string{
+				"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"u1","openDingTalkId":"D1"}]}`,
+			},
+			wantTarget: "receiverOpenDingTalkId",
+			wantValue:  "D1",
+		},
+		{
+			name: "chat query exact wins",
+			args: []string{
+				"chat", "+messages-send", "--as", "user",
+				"--chat-query", "项目群", "--text", "你好", "--yes",
+			},
+			responses: map[string]string{
+				"im/search_groups": `{"result":[{"title":"项目群-归档","openConversationId":"c2"},{"title":"项目群","openConversationId":"c1"}]}`,
+			},
+			wantTarget: "openConversationId",
+			wantValue:  "c1",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fake := &larkAlignmentCaller{responses: tt.responses}
+			helpers.InitDeps(fake)
+			root := newPlatformCoverageRoot()
+			root.SetArgs(tt.args)
+			if err := root.Execute(); err != nil {
+				t.Fatal(err)
+			}
+			if len(fake.calls) != 2 {
+				t.Fatalf("calls = %#v, want resolve + send", fake.calls)
+			}
+			send := fake.calls[1]
+			if send.product != "chat" || send.tool != "send_personal_message" {
+				t.Fatalf("send = %#v", send)
+			}
+			if send.args[tt.wantTarget] != tt.wantValue {
+				t.Fatalf("%s = %#v, want %q", tt.wantTarget, send.args[tt.wantTarget], tt.wantValue)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendNaturalTargetAmbiguityHasNoWrite(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"contact/search_contact_by_key_word": `{"result":[{"name":"张三","userId":"u1","openDingTalkId":"D1"},{"name":"张三","userId":"u2","openDingTalkId":"D2"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "user",
+		"--user-query", "张三", "--text", "你好", "--yes",
+	})
+	err := root.Execute()
+	if err == nil {
+		t.Fatal("ambiguous user unexpectedly sent")
+	}
+	if len(fake.calls) != 1 || fake.calls[0].tool != "search_contact_by_key_word" {
+		t.Fatalf("ambiguous resolution reached write: %#v", fake.calls)
+	}
+	var typed *apperrors.Error
+	if !stderrors.As(err, &typed) {
+		t.Fatalf("error type = %T", err)
+	}
+	if typed.Reason != "resolution_ambiguous" || typed.Details["type"] != "resolution" {
+		t.Fatalf("structured error = %#v", typed)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendChatQueryResolvesAllPagesBeforeWrite(t *testing.T) {
+	fake := &larkAlignmentCaller{sequenceResponses: map[string][]string{
+		"im/search_groups": {
+			`{"result":[{"title":"项目群-归档","openConversationId":"archive"}],"hasMore":true,"nextCursor":"page-2"}`,
+			`{"result":[{"title":"项目群","openConversationId":"active"}],"hasMore":false}`,
+		},
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "user",
+		"--chat-query", "项目群", "--text", "你好", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 3 || fake.calls[0].tool != "search_groups" ||
+		fake.calls[1].tool != "search_groups" || fake.calls[2].tool != "send_personal_message" {
+		t.Fatalf("calls = %#v, want two resolution pages then one write", fake.calls)
+	}
+	if fake.calls[1].args["cursor"] != "page-2" || fake.calls[2].args["openConversationId"] != "active" {
+		t.Fatalf("calls = %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendIncompleteChatResolutionHasNoWrite(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/search_groups": `{"result":[{"title":"项目群","openConversationId":"c1"}],"hasMore":true}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "user",
+		"--chat-query", "项目群", "--text", "你好", "--yes",
+	})
+	err := root.Execute()
+	var typed *apperrors.Error
+	if !stderrors.As(err, &typed) || typed.Reason != "resolution_incomplete" {
+		t.Fatalf("error = %#v", err)
+	}
+	if len(fake.calls) != 1 || fake.calls[0].tool != "search_groups" {
+		t.Fatalf("incomplete resolution reached write: %#v", fake.calls)
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendDryRunUsesRealNaturalTargetResolution(t *testing.T) {
+	fake := &larkAlignmentCaller{responses: map[string]string{
+		"im/search_groups": `{"result":[{"title":"项目群","openConversationId":"c1"}]}`,
+	}}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "user",
+		"--chat-query", "项目群", "--text", "你好", "--dry-run", "--yes",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(fake.calls) != 1 {
+		t.Fatalf("dry-run calls = %#v, want one read-only resolution", fake.calls)
+	}
+	if fake.calls[0].product != "im" || fake.calls[0].tool != "search_groups" {
+		t.Fatalf("dry-run resolution = %#v", fake.calls[0])
+	}
+}
+
+func TestCrossPlatformCoverageMessagesSendRejectsNaturalTargetForUnsupportedIdentity(t *testing.T) {
+	fake := &larkAlignmentCaller{}
+	helpers.InitDeps(fake)
+	root := newPlatformCoverageRoot()
+	root.SetArgs([]string{
+		"chat", "+messages-send", "--as", "bot", "--robot-code", "r",
+		"--chat-query", "项目群", "--text", "你好", "--yes",
+	})
+	if err := root.Execute(); err == nil {
+		t.Fatal("bot natural target unexpectedly accepted")
+	}
+	if len(fake.calls) != 0 {
+		t.Fatalf("invalid identity reached lower service: %#v", fake.calls)
+	}
+}
@@ -38,6 +38,98 @@ import (
 	"strings"
 )

+// MessageListContractVersion identifies the additive, compatibility-preserving
+// public envelope shared by message list/search/mget/thread projections.
+const MessageListContractVersion = "im.message-list.v1"
+
+// MessageResultContract is the reviewed additive contract shared by message
+// list, search, mget, @me and thread projections. Keep this descriptor small:
+// Runtime owns the values, while Skill references and policy checks consume a
+// copy of these field names so prose cannot silently invent another result
+// shape.
+type MessageResultContract struct {
+	Version        string
+	MessageFields  []string
+	EnvelopeFields []string
+}
+
+var messageResultContractV1 = MessageResultContract{
+	Version: MessageListContractVersion,
+	MessageFields: []string{
+		"messageId",
+		"conversationId",
+		"threadId",
+		"sender",
+		"senderId",
+		"senderType",
+		"messageType",
+		"text",
+		"createTime",
+		"updateTime",
+		"reactions",
+		"quotedMessage",
+		"forwarded",
+		"resourceRefs",
+	},
+	EnvelopeFields: []string{
+		"contractVersion",
+		"messages",
+		"count",
+		"pagesFetched",
+		"paginationKnown",
+		"complete",
+		"hasMore",
+		"nextPage",
+		"stopReason",
+		"truncatedByPageLimit",
+		"truncatedByResultLimit",
+		"failedCount",
+		"failures",
+		"partial",
+		"resourceDownloads",
+	},
+}
+
+// CurrentMessageResultContract returns defensive copies so callers cannot
+// mutate the process-wide reviewed descriptor.
+func CurrentMessageResultContract() MessageResultContract {
+	contract := messageResultContractV1
+	contract.MessageFields = append([]string(nil), contract.MessageFields...)
+	contract.EnvelopeFields = append([]string(nil), contract.EnvelopeFields...)
+	return contract
+}
+
+// NewMessageListPayload initializes the common result ledger before a caller
+// adds pagination or resource-download facts.
+func NewMessageListPayload(messages []map[string]any) map[string]any {
+	if messages == nil {
+		messages = []map[string]any{}
+	}
+	return map[string]any{
+		"contractVersion": MessageListContractVersion,
+		"messages":        messages,
+		"count":           len(messages),
+		"pagesFetched":    0,
+		"paginationKnown": false,
+		"complete":        false,
+		"hasMore":         false,
+		"failedCount":     0,
+		"failures":        []map[string]any{},
+		"partial":         false,
+	}
+}
+
+// StableMessageID returns the normalized message identity used for
+// cross-page deduplication. An empty value means the lower response did not
+// publish a stable identity; callers must keep that row rather than guessing.
+func StableMessageID(message map[string]any) string {
+	value := MessageID(message)
+	if value == nil {
+		return ""
+	}
+	return strings.TrimSpace(fmt.Sprint(value))
+}
+
 // Sender reads a message's speaker display name, tolerating common sender-name
 // keys. The message-list responses carry the display name under the bare
 // "sender" key (verified live), so it is probed first; the remaining aliases and
@@ -150,6 +242,88 @@ func MessageType(m map[string]any) any {
 	return firstMessageValue(m, "msgType", "messageType", "message_type", "type")
 }

+// SenderID preserves the stable sender identity without replacing the legacy
+// scalar sender display field. Nested sender records and both userId families
+// are accepted because list/search/mget currently expose different shapes.
+func SenderID(m map[string]any) any {
+	for _, key := range []string{"sender", "from", "senderUser"} {
+		if nested, ok := m[key].(map[string]any); ok {
+			if value := firstMessageValue(nested,
+				"openDingTalkId", "openDingtalkId", "userId", "senderId", "id"); value != nil {
+				return value
+			}
+		}
+	}
+	return firstMessageValue(m,
+		"senderOpenDingTalkId", "senderOpenDingtalkId", "senderUserId",
+		"senderId", "sender_id", "senderStaffId", "openDingTalkId", "userId")
+}
+
+// SenderType returns only an explicitly published lower sender type. It does
+// not guess that every sender identity is a user because bot/system messages
+// can share the same generic senderId key.
+func SenderType(m map[string]any) any {
+	for _, key := range []string{"sender", "from", "senderUser"} {
+		if nested, ok := m[key].(map[string]any); ok {
+			if value := firstMessageValue(nested, "senderType", "type", "entityType"); value != nil {
+				return value
+			}
+		}
+	}
+	return firstMessageValue(m, "senderType", "sender_type", "fromType", "from_type")
+}
+
+// ProjectMessageV1 is the single compatibility-preserving core projection for
+// list, search, mget, @me, and thread readers. Public wrappers may retain
+// legacy aliases such as time or msgType, but the underlying identity,
+// context, reaction, quote, forward, and resource semantics come from here.
+func ProjectMessageV1(m map[string]any, includeReactions bool) map[string]any {
+	row := map[string]any{
+		"sender":     Sender(m),
+		"text":       Text(m),
+		"createTime": CreateTime(m),
+	}
+	if value := MessageID(m); value != nil {
+		row["messageId"] = value
+	}
+	if value := ConversationID(m); value != nil {
+		row["conversationId"] = value
+	}
+	if value := ThreadID(m); value != nil {
+		row["threadId"] = value
+	}
+	if value := SenderID(m); value != nil {
+		row["senderId"] = value
+	}
+	if value := SenderType(m); value != nil {
+		row["senderType"] = value
+	}
+	if value := MessageType(m); value != nil {
+		row["messageType"] = value
+	}
+	if value := UpdateTime(m); value != nil {
+		row["updateTime"] = value
+	}
+	if includeReactions {
+		if reactions := Reactions(m); len(reactions) > 0 {
+			row["reactions"] = reactions
+		}
+	}
+	if quoted := QuotedMessage(m); len(quoted) > 0 {
+		row["quotedMessage"] = quoted
+	}
+	if resources := ResourcesDeep(m); len(resources) > 0 {
+		row["resourceRefs"] = resources
+	}
+	projectForwarded := func(item map[string]any) map[string]any {
+		return ProjectMessageV1(item, includeReactions)
+	}
+	if forwarded := Forwarded(m, projectForwarded); len(forwarded) > 0 {
+		row["forwarded"] = forwarded
+	}
+	return row
+}
+
 // QuotedMessage projects one level of quoted/replied-to context. It is
 // deliberately non-recursive: a reply chain may be arbitrarily deep or even
 // cyclic after gateway reshaping, while an Agent primarily needs the quoted
@@ -605,13 +779,35 @@ func ApplyPagination(payload, data map[string]any) {
 // message-list contract paginates with the boundary message createTime, so the
 // resume object uses exactly that accepted parameter.
 func ApplyMessagePagination(payload, data map[string]any, messages []map[string]any, direction string) {
+	payload["contractVersion"] = MessageListContractVersion
+	payload["pagesFetched"] = 1
+	payload["enrichedCount"] = 0
+	payload["failedCount"] = 0
+	payload["failures"] = []map[string]any{}
+	payload["hasMore"] = false
+	payload["complete"] = false
 	page := Pagination(data)
 	if len(page) == 0 {
+		payload["paginationKnown"] = false
+		payload["failedCount"] = 1
+		payload["failures"] = []map[string]any{{
+			"stage": "pagination",
+			"error": "下层未返回可靠的 hasMore/nextCursor，无法证明结果完整",
+		}}
 		return
 	}
-	if value, ok := page["hasMore"]; ok {
-		payload["hasMore"] = value
+	value, hasMoreKnown := page["hasMore"]
+	if !hasMoreKnown {
+		payload["paginationKnown"] = false
+		payload["failedCount"] = 1
+		payload["failures"] = []map[string]any{{
+			"stage": "pagination",
+			"error": "下层仅返回 cursor、未返回 hasMore，无法证明结果完整",
+		}}
+		return
 	}
+	payload["paginationKnown"] = true
+	payload["hasMore"] = value
 	if value, ok := page["complete"]; ok {
 		payload["complete"] = value
 	}
@@ -621,6 +817,11 @@ func ApplyMessagePagination(payload, data map[string]any, messages []map[string]
 	}
 	boundary := CreateTime(messages[len(messages)-1])
 	if boundary == nil {
+		payload["failedCount"] = 1
+		payload["failures"] = []map[string]any{{
+			"stage": "pagination",
+			"error": "下层返回 hasMore=true，但末条消息缺少可继续读取的 createTime",
+		}}
 		return
 	}
 	next := map[string]any{"time": boundary}
@@ -18,7 +18,7 @@ import (
 	"testing"
 )

-func TestSender(t *testing.T) {
+func TestCrossPlatformCoverageSender(t *testing.T) {
 	// The display name lives under the bare "sender" key.
 	if got := Sender(map[string]any{"sender": "念晨", "senderOpenDingTalkId": "D1"}); got != "念晨" {
 		t.Fatalf("sender = %v, want 念晨", got)
@@ -48,7 +48,37 @@ func TestSender(t *testing.T) {
 	}
 }

-func TestCleanText(t *testing.T) {
+func TestCrossPlatformCoverageProjectMessageV1PublishesSharedIdentityAndContext(t *testing.T) {
+	row := ProjectMessageV1(map[string]any{
+		"openMessageId":      "msg-1",
+		"openConversationId": "cid-1",
+		"openConvThreadId":   "thread-1",
+		"sender": map[string]any{
+			"name":           "张三",
+			"openDingTalkId": "D1",
+			"senderType":     "user",
+		},
+		"msgType":    "text",
+		"content":    "你好",
+		"createTime": "2026-08-03 10:00:00",
+	}, true)
+	for key, want := range map[string]any{
+		"messageId":      "msg-1",
+		"conversationId": "cid-1",
+		"threadId":       "thread-1",
+		"sender":         "张三",
+		"senderId":       "D1",
+		"senderType":     "user",
+		"messageType":    "text",
+		"text":           "你好",
+	} {
+		if row[key] != want {
+			t.Errorf("%s = %#v, want %#v; row=%#v", key, row[key], want, row)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageCleanText(t *testing.T) {
 	// Out-of-office auto-reply: readable body lives in items[].data.text; the
 	// decorative preview/config JSON lines and "empty" placeholder are dropped.
 	autoReply := "* 仅你和对方可见\n" +
@@ -98,7 +128,7 @@ func TestCleanText(t *testing.T) {
 	}
 }

-func TestIsEncryptedAndMarker(t *testing.T) {
+func TestCrossPlatformCoverageIsEncryptedAndMarker(t *testing.T) {
 	cipher := "SwzNkAraDE6lUHUNlVT3mjFdbxL6dWvmt77XtjACdpJx9VFibzTbW9KtDbkzGOYP\n" +
 		"7oDptklFO+YzDltH+myErV6rkc8URHYykpeSDsMP6kznFa9E320NsIntfY771dx+\n" +
 		"||2||1||196"
@@ -121,7 +151,7 @@ func TestIsEncryptedAndMarker(t *testing.T) {
 	}
 }

-func TestText(t *testing.T) {
+func TestCrossPlatformCoverageText(t *testing.T) {
 	if got := Text(map[string]any{"content": "你好"}); got != "你好" {
 		t.Errorf("Text string = %v", got)
 	}
@@ -136,7 +166,7 @@ func TestText(t *testing.T) {
 	}
 }

-func TestCreateTime(t *testing.T) {
+func TestCrossPlatformCoverageCreateTime(t *testing.T) {
 	if got := CreateTime(map[string]any{"sendTime": "2026-07-19 13:37:03"}); got != "2026-07-19 13:37:03" {
 		t.Errorf("CreateTime = %v", got)
 	}
@@ -145,7 +175,7 @@ func TestCreateTime(t *testing.T) {
 	}
 }

-func TestStableMessageIdentity(t *testing.T) {
+func TestCrossPlatformCoverageStableMessageIdentity(t *testing.T) {
 	message := map[string]any{
 		"openMessageId":      "msg-1",
 		"openConversationId": "cid-1",
@@ -166,7 +196,31 @@ func TestStableMessageIdentity(t *testing.T) {
 	}
 }

-func TestQuotedMessageIsBoundedAndSemantic(t *testing.T) {
+func TestCrossPlatformCoverageMessageLedgerNilAndCursorOnlyBoundaries(t *testing.T) {
+	contract := CurrentMessageResultContract()
+	if contract.Version != MessageListContractVersion || len(contract.MessageFields) == 0 || len(contract.EnvelopeFields) == 0 {
+		t.Fatalf("message result contract = %#v", contract)
+	}
+	contract.MessageFields[0] = "mutated"
+	contract.EnvelopeFields[0] = "mutated"
+	second := CurrentMessageResultContract()
+	if second.MessageFields[0] == "mutated" || second.EnvelopeFields[0] == "mutated" {
+		t.Fatal("message result contract leaked mutable storage")
+	}
+	payload := NewMessageListPayload(nil)
+	if payload["count"] != 0 || payload["messages"] == nil {
+		t.Fatalf("nil message ledger = %#v", payload)
+	}
+	if StableMessageID(map[string]any{}) != "" {
+		t.Fatal("missing message identity was fabricated")
+	}
+	ApplyMessagePagination(payload, map[string]any{"result": map[string]any{"nextCursor": "next"}}, nil, "older")
+	if payload["paginationKnown"] != false || payload["failedCount"] != 1 {
+		t.Fatalf("cursor-only pagination = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageQuotedMessageIsBoundedAndSemantic(t *testing.T) {
 	got := QuotedMessage(map[string]any{
 		"quotedMessage": map[string]any{
 			"openMessageId":      "quoted-1",
@@ -294,7 +348,7 @@ func TestCrossPlatformCoverageResourceBoundaryHelpers(t *testing.T) {
 	}
 }

-func TestUpdateTimeOmitsUneditedEcho(t *testing.T) {
+func TestCrossPlatformCoverageUpdateTimeOmitsUneditedEcho(t *testing.T) {
 	if got := UpdateTime(map[string]any{
 		"createTime": "2026-07-19 13:37:03",
 		"updateTime": "2026-07-19 13:37:03",
@@ -309,7 +363,7 @@ func TestUpdateTimeOmitsUneditedEcho(t *testing.T) {
 	}
 }

-func TestReactionsNormalizesEmotionReplyList(t *testing.T) {
+func TestCrossPlatformCoverageReactionsNormalizesEmotionReplyList(t *testing.T) {
 	got := Reactions(map[string]any{
 		"emotionReplyList": []any{
 			map[string]any{
@@ -345,7 +399,7 @@ func TestReactionsNormalizesEmotionReplyList(t *testing.T) {
 	}
 }

-func TestApplyPaginationReadsNestedEnvelope(t *testing.T) {
+func TestCrossPlatformCoverageApplyPaginationReadsNestedEnvelope(t *testing.T) {
 	payload := map[string]any{"count": 98}
 	ApplyPagination(payload, map[string]any{
 		"result": map[string]any{
@@ -369,7 +423,7 @@ func TestApplyPaginationReadsNestedEnvelope(t *testing.T) {
 	}
 }

-func TestApplyMessagePaginationUsesExecutableTimeBoundary(t *testing.T) {
+func TestCrossPlatformCoverageApplyMessagePaginationUsesExecutableTimeBoundary(t *testing.T) {
 	payload := map[string]any{}
 	ApplyMessagePagination(payload, map[string]any{
 		"result": map[string]any{
@@ -389,7 +443,21 @@ func TestApplyMessagePaginationUsesExecutableTimeBoundary(t *testing.T) {
 	}
 }

-func TestResourcesBuildsActionableDownloadReferences(t *testing.T) {
+func TestCrossPlatformCoverageApplyMessagePaginationFailsClosedWhenCompletenessIsUnknown(t *testing.T) {
+	payload := map[string]any{}
+	ApplyMessagePagination(payload, map[string]any{"result": map[string]any{"messages": []any{}}}, nil, "older")
+	if payload["contractVersion"] != MessageListContractVersion ||
+		payload["complete"] != false || payload["paginationKnown"] != false ||
+		payload["failedCount"] != 1 {
+		t.Fatalf("unknown pagination contract = %#v", payload)
+	}
+	failures, _ := payload["failures"].([]map[string]any)
+	if len(failures) != 1 || failures[0]["stage"] != "pagination" {
+		t.Fatalf("unknown pagination failures = %#v", failures)
+	}
+}
+
+func TestCrossPlatformCoverageResourcesBuildsActionableDownloadReferences(t *testing.T) {
 	resources := Resources(map[string]any{
 		"openMessageId":      "msg-1",
 		"openConversationId": "cid-1",
@@ -416,7 +484,7 @@ func TestResourcesBuildsActionableDownloadReferences(t *testing.T) {
 	}
 }

-func TestResourcesReportsMissingDownloadContext(t *testing.T) {
+func TestCrossPlatformCoverageResourcesReportsMissingDownloadContext(t *testing.T) {
 	resources := Resources(map[string]any{"content": `{"mediaId":"@image-a"}`})
 	if len(resources) != 1 {
 		t.Fatalf("resources = %#v", resources)
@@ -431,7 +499,7 @@ func TestResourcesReportsMissingDownloadContext(t *testing.T) {
 	}
 }

-func TestResourcesTextMediaIDRequiresWordBoundary(t *testing.T) {
+func TestCrossPlatformCoverageResourcesTextMediaIDRequiresWordBoundary(t *testing.T) {
 	resources := Resources(map[string]any{
 		"openMessageId":      "msg-1",
 		"openConversationId": "cid-1",
@@ -442,7 +510,7 @@ func TestResourcesTextMediaIDRequiresWordBoundary(t *testing.T) {
 	}
 }

-func TestForwarded(t *testing.T) {
+func TestCrossPlatformCoverageForwarded(t *testing.T) {
 	var project func(m map[string]any) map[string]any
 	project = func(m map[string]any) map[string]any {
 		row := map[string]any{"text": Text(m)}
@@ -24,6 +24,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

 // AtMe: pull the messages that recently @-mentioned ME across chats in one step.
@@ -86,18 +87,37 @@ var AtMe = shortcut.Shortcut{
 		},
 	},
 	Flags: append([]shortcut.Flag{
-		{Name: "days", Type: shortcut.FlagInt, Desc: "回溯天数（可选，默认 7）", Default: "7", Required: false},
-		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页返回数量（默认 50）", Default: "50"},
+		{Name: "group", Type: shortcut.FlagString, Desc: "仅查看指定群；可传 openConversationId 或群名"},
+		{Name: "chat-query", Type: shortcut.FlagString, Desc: "--group 的旧版自然名称入口", Hidden: true},
+		{Name: "group-query", Type: shortcut.FlagString, Desc: "--chat-query 的兼容别名", Hidden: true},
+		{Name: "days", Type: shortcut.FlagInt, Desc: "回溯天数（默认 7）；--days 必须在 1-3650 之间", Default: "7", Required: false},
+		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页返回数量（默认 50）；--limit 必须大于 0", Default: "50"},
 		{Name: "cursor", Type: shortcut.FlagString, Desc: "分页游标，翻页传上次的 nextCursor", Default: "0"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出消息 reaction（默认输出）"},
 	}, chatshortcut.MessageResourceDownloadFlags()...),
-	Constraints: chatshortcut.MessageResourceDownloadConstraints(),
+	Constraints: append([]shortcut.Constraint{
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"group", "chat-query", "group-query"}},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"days"}, Description: "--days 必须在 1-3650 之间"},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "--limit 必须大于 0"},
+	}, chatshortcut.MessageResourceDownloadConstraints()...),
 	Tips: []string{
 		`dws chat +at-me`,
 		`dws chat +at-me --days 3`,
+		`dws chat +at-me --group "项目群"`,
 	},
-	Validate: chatshortcut.ValidateMessageResourceDownload,
+	Validate: validateAtMe,
 	Execute: func(rt *shortcut.RuntimeContext) error {
+		groupID := ""
+		directTarget := strings.TrimSpace(rt.Str("group"))
+		queryTarget := strings.TrimSpace(rt.StrFirst("chat-query", "group-query"))
+		if directTarget != "" || queryTarget != "" {
+			resolved, err := targetresolver.ResolveChatTarget(rt, directTarget, queryTarget)
+			if err != nil {
+				return err
+			}
+			groupID = resolved.Selected.OpenConversationID
+		}
+
 		// Step 1 — look-back window [now-Nd, now] in epoch millis. days defaults
 		// to 7; guard against non-positive overrides so the window stays sane.
 		days := rt.Int("days")
@@ -111,35 +131,75 @@ var AtMe = shortcut.Shortcut{
 		// Step 2 — search @me messages. startTime/endTime/limit/cursor and the
 		// first-page defaults (limit 50, cursor "0") mirror
 		// helpers.chatMessageListMentionsCmd's search_at_me_message call.
-		data, err := rt.CallMCPData("chat", "search_at_me_message", map[string]any{
+		params := map[string]any{
 			"startTime": startMs,
 			"endTime":   endMs,
 			"limit":     rt.Int("limit"),
 			"cursor":    rt.Str("cursor"),
-		})
+		}
+		if groupID != "" {
+			params["openConversationId"] = groupID
+		}
+		data, err := rt.CallMCPData("chat", "search_at_me_message", params)
 		if err != nil {
 			return err
 		}

-		// Step 3 — project matched messages; fall back to the raw payload when we
-		// cannot locate a recognisable message list.
+		// Step 3 — always publish the stable list envelope, including for an empty
+		// or newly-shaped response. This keeps common .messages[]/.items[] jq
+		// projections deterministic instead of turning absence into null.
 		items := atMeMessageItems(data)
-		if len(items) == 0 {
-			return rt.Output(data)
-		}
 		results := make([]map[string]any, 0, len(items))
 		for _, m := range items {
 			results = append(results, atMeProjectWithReactions(m, !rt.Bool("no-reactions")))
 		}
-		payload := map[string]any{"messages": results}
+		payload := chatmsg.NewMessageListPayload(results)
+		payload["items"] = atMeCompatibilityItems(results)
 		chatmsg.ApplyPagination(payload, data)
 		if rt.Bool("download-resources") {
-			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, "")
+			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, groupID)
 		}
 		return rt.Output(payload)
 	},
 }

+func validateAtMe(rt *shortcut.RuntimeContext) error {
+	if err := chatshortcut.ValidateMessageResourceDownload(rt); err != nil {
+		return err
+	}
+	days := rt.Int("days")
+	if days < 1 || days > 3650 {
+		return localChatOptionError("invalid_lookback_window", "+at-me 的 --days 必须在 1-3650 之间", "--days")
+	}
+	if rt.Int("limit") <= 0 {
+		return localChatOptionError("invalid_page_size", "+at-me 的 --limit 必须大于 0", "--limit")
+	}
+	return nil
+}
+
+// atMeCompatibilityItems preserves the common list/items projection used by
+// older Agent snippets while keeping messages as the canonical v1 contract.
+// Its conversation field is an object so `.items[].conversation.name` is safe.
+func atMeCompatibilityItems(messages []map[string]any) []map[string]any {
+	items := make([]map[string]any, 0, len(messages))
+	for _, message := range messages {
+		item := make(map[string]any, len(message))
+		for key, value := range message {
+			item[key] = value
+		}
+		conversation := map[string]any{}
+		if name := atMeString(message["conversation"]); name != "" {
+			conversation["name"] = name
+		}
+		if id := atMeString(message["conversationId"]); id != "" {
+			conversation["openConversationId"] = id
+		}
+		item["conversation"] = conversation
+		items = append(items, item)
+	}
+	return items
+}
+
 // atMeMessageItems locates the message list inside a search_at_me_message
 // response, probing common container keys at the top level and nested under
 // "result". Returns nil when no list is found.
@@ -20,7 +20,7 @@ import (

 const testCipher = "SwzNkAraDE6lUHUNlVT3mjFdbxL6dWvmt77XtjACdpJx9VFibzTbW9KtDbkzGOYP||2||1||1"

-func TestAtMeProject(t *testing.T) {
+func TestCrossPlatformCoverageAtMeProject(t *testing.T) {
 	// nested sender object + plain text
 	row := atMeProject(map[string]any{
 		"sender":             map[string]any{"name": "念晨"},
@@ -87,7 +87,7 @@ func TestAtMeProject(t *testing.T) {
 	}
 }

-func TestSearchMsgProject(t *testing.T) {
+func TestCrossPlatformCoverageSearchMsgProject(t *testing.T) {
 	// nested sender + plain text + messageId
 	row := searchMsgProject(map[string]any{
 		"sender":     map[string]any{"nick": "千启"},
@@ -129,7 +129,7 @@ func TestSearchMsgProject(t *testing.T) {
 // TestSenderHelpers exercises the atMe/searchMsg sender key families directly:
 // a senderName-family key (first probe loop), a flat string under "sender"
 // (second loop), and the "null" sentinel normalisation.
-func TestSenderHelpers(t *testing.T) {
+func TestCrossPlatformCoverageSenderHelpers(t *testing.T) {
 	cases := []struct {
 		fn   func(map[string]any) any
 		name string
@@ -23,6 +23,7 @@ import (
 	"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"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

 // Broadcast: send the SAME single-chat message to several people by NAME.
@@ -96,14 +97,28 @@ var Broadcast = shortcut.Shortcut{

 			// Step 1 — resolve this name to a unique userId. On failure
 			// (unknown / ambiguous) record it and keep going.
-			user, err := resolveOpenDingTalkUser(rt, name)
+			resolved, err := targetresolver.ResolveEnterpriseUser(rt, name, targetresolver.IdentityAny)
 			if err != nil {
 				failed = append(failed, fmt.Sprintf("%s（%s）", name, err.Error()))
 				continue
 			}
-			if user.openDingTalkID == "" {
-				failed = append(failed, fmt.Sprintf("%s（通讯录结果缺少 openDingTalkId）", name))
-				continue
+			user := resolved.Selected
+			targetArgs := map[string]any{}
+			if user.OpenDingTalkID != "" {
+				targetArgs["receiverOpenDingTalkId"] = user.OpenDingTalkID
+			} else {
+				targetArgs["receiverUserId"] = user.UserID
+			}
+			recipient := user.Name
+			if recipient == "" {
+				recipient = name
+			}
+			messageArgs := rt.AddAIMessageTag(map[string]any{
+				"msgType": "markdown",
+				"content": string(content),
+			})
+			for key, value := range targetArgs {
+				messageArgs[key] = value
 			}

 			// Step 2 — send the single-chat message to this recipient. Under
@@ -111,26 +126,18 @@ var Broadcast = shortcut.Shortcut{
 			// resolved recipient as "would send" and move on.
 			if rt.DryRun() {
 				plans = append(plans, map[string]any{
-					"recipient": user.name,
+					"recipient": recipient,
 					"tool":      "send_personal_message",
-					"arguments": rt.AddAIMessageTag(map[string]any{
-						"receiverOpenDingTalkId": user.openDingTalkID,
-						"msgType":                "markdown",
-						"content":                string(content),
-					}),
+					"arguments": messageArgs,
 				})
-				sent = append(sent, user.name)
+				sent = append(sent, recipient)
 				continue
 			}
-			if _, err := rt.CallMCPWriteData("chat", "send_personal_message", rt.AddAIMessageTag(map[string]any{
-				"receiverOpenDingTalkId": user.openDingTalkID,
-				"msgType":                "markdown",
-				"content":                string(content),
-			})); err != nil {
+			if _, err := rt.CallMCPWriteData("chat", "send_personal_message", messageArgs); err != nil {
 				failed = append(failed, fmt.Sprintf("%s（发送失败：%s）", name, err.Error()))
 				continue
 			}
-			sent = append(sent, user.name)
+			sent = append(sent, recipient)
 		}

 		// Summarize via rt.Output (structured, honours --format/--jq/--fields)
@@ -14,40 +14,34 @@
 package smart

 import (
+	"fmt"
 	"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/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut"
 	chatshortcut "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chat"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/chatmsg"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/shortcut/targetresolver"
 )

 var dingTalkMessageLocation = time.FixedZone("CST", 8*60*60)

+const (
+	chatMessagesDefaultPageLimit = 50
+	chatMessagesHardPageLimit    = 500
+	chatMessagesAllPageSize      = 100
+)
+
 func formatDingTalkMessageBoundary(now time.Time) string {
 	return now.In(dingTalkMessageLocation).Format("2006-01-02 15:04:05")
 }

-// ChatMessages: fetch the message list of one conversation (group OR single
-// chat) and print a clean projected list (speaker / text / time) instead of a
-// raw dump.
-//
-// Steps:
-//  1. depending on whether --group or --user is given, call either
-//     list_conversation_message_v2 (group; param openconversation_id) or
-//     list_individual_chat_message (single chat; param userId) on the chat
-//     server — tool names and param keys copied verbatim from chat.go's
-//     `dws chat message list` call sites;
-//  2. defensively unwrap the message list (multiple candidate container keys)
-//     and project each message to {sender, text, createTime} tolerating field
-//     aliases and one level of nesting;
-//  3. print via rt.Output as {messages, count} so it honours --format/--jq/--fields.
-//
-// The default path only reads and reshapes conversation messages;
-// --download-resources additionally writes resource files locally.
+// ChatMessages resolves one conversation, projects messages into the shared
+// typed result contract, and optionally follows bounded continuation pages,
+// downloads resources, or atomically exports the complete ledger as JSON.
 //
 //	dws chat +chat-messages --group <openconversation_id> --time "2025-03-01 00:00:00"
 //	dws chat +chat-messages --user <userId> --time "2025-03-01 00:00:00" --limit 50
@@ -55,12 +49,12 @@ var ChatMessages = shortcut.Shortcut{
 	Service:     "chat",
 	Command:     "+chat-messages",
 	Product:     "chat",
-	Description: "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
-	Intent: "当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；" +
-		"群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。" +
+	Description: "按会话 ID、群名或用户 ID 读取消息，支持有界全量分页与原子 JSON 导出",
+	Intent: "当你想快速看一个群聊或单聊里的消息（谁在什么时间说了什么），而不想拿到大段原始消息字段时使用；" +
+		"群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" +
 		"省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。" +
-		"内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。" +
-		"默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。",
+		"全量读取用 --page-all，并由 --page-limit/--max-results 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" +
+		"默认只读；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘。",
 	Risk: shortcut.RiskRead,
 	Safety: contract.SafetySpec{
 		Effect: "read", Risk: "low",
@@ -74,16 +68,20 @@ var ChatMessages = shortcut.Shortcut{
 			CLIPath:        "chat +chat-messages",
 			PrimaryCLIPath: "chat +chat-messages",
 		},
-		Description: "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
+		Description: "按会话 ID、群名或用户 ID 读取消息，支持有界全量分页与原子 JSON 导出",
 		Interface: &contract.InterfaceSpec{
 			Mode:         "composite",
 			Availability: "available",
 			Reason:       "Reviewed built-in Shortcut adapter: it routes group or direct-message history reads, projects a stable message shape, and optionally orchestrates safe resource downloads with a failure ledger.",
 		},
 		Selection: contract.SelectionSpec{
-			AgentSummary: "拉取某个会话（群聊或单聊）的消息列表并投影出发言人/文本/时间",
-			UseWhen:      []string{"当你想快速看某个会话里的消息（谁在什么时间说了什么），而不想拿到一大坨原始消息字段时使用；群聊传 --group（群会话 ID，openConversationId），单聊传 --user（对方 userId），两者互斥且必须二选一。省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。内部据此调用群聊或单聊的消息列表接口，再在本地投影出每条消息的发言人、文本和时间。默认只读且不会发送或修改任何消息；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘，按既有安全下载约定无需交互确认。"},
-			AvoidWhen:    []string{"要跨多个会话按关键词、发送者或消息类型检索时使用 +search-msg；已有一批精确消息 ID 时使用 +messages-mget"},
+			AgentSummary: "按会话 ID、群名或用户 ID 读取消息，支持有界全量分页与原子 JSON 导出",
+			UseWhen: []string{"当你想快速看一个群聊或单聊里的消息（谁在什么时间说了什么），而不想拿到大段原始消息字段时使用；" +
+				"群聊的 --group 可传群名或 openConversationId，单聊可传 --user 或 --open-dingtalk-id，所有目标参数互斥且必须选一个。自然群名只在唯一解析后读取，多候选会返回结构化 candidates。" +
+				"省略 --time 时默认从当前时间向前读取最近消息；也可指定时间边界并用 --direction newer/older 控制方向。" +
+				"全量读取用 --page-all，并由 --page-limit/--max-results 保持有界；结果公开 complete、hasMore、nextPage、stopReason、截断和逐页失败，不能把部分结果称为完整。--output 把同一 ledger 原子写为工作目录内 JSON。" +
+				"默认只读；--download-resources 使用工作目录内安全路径、默认不覆盖和原子落盘。"},
+			AvoidWhen: []string{"要跨多个会话按关键词、发送者或消息类型检索时使用 +search-msg；已有一批精确消息 ID 时使用 +messages-mget"},
 			Examples: []string{
 				"dws chat +chat-messages --group <openConversationId> --direction older",
 				"dws chat +chat-messages --open-dingtalk-id <openDingTalkId> --download-resources --output-dir ./downloads",
@@ -91,92 +89,382 @@ var ChatMessages = shortcut.Shortcut{
 		},
 	},
 	Flags: append([]shortcut.Flag{
-		{Name: "group", Type: shortcut.FlagString, Desc: "群会话 ID（openConversationId），与 --user 互斥"},
+		{Name: "group", Type: shortcut.FlagString, Desc: "群名称或 openConversationId，与单聊目标互斥"},
 		{Name: "conversation-id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true},
 		{Name: "id", Type: shortcut.FlagString, Desc: "--group 的别名", Hidden: true},
+		{Name: "open-conversation-id", Type: shortcut.FlagString, Desc: "--conversation-id 的兼容别名", Hidden: true},
+		{Name: "chat-query", Type: shortcut.FlagString, Desc: "--group 的旧版自然名称入口", Hidden: true},
 		{Name: "user", Type: shortcut.FlagString, Desc: "单聊对方的 userId，与 --group 互斥"},
+		{Name: "user-query", Type: shortcut.FlagString, Desc: "按姓名解析唯一 openDingTalkId 的兼容入口", Hidden: true},
 		{Name: "open-dingtalk-id", Type: shortcut.FlagString, Desc: "单聊对方的 openDingTalkId，与 --group/--user 互斥"},
-		{Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；省略时从当前时间向前读取最近消息"},
-		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页拉取的消息条数（可选）"},
+		{Name: "time", Type: shortcut.FlagString, Desc: "时间边界，如 \"2025-03-01 00:00:00\"；--time 必须是 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD；省略时从当前时间向前读取最近消息"},
+		{Name: "limit", Type: shortcut.FlagInt, Desc: "每页拉取的消息条数；显式页大小必须大于 0"},
 		{Name: "size", Type: shortcut.FlagInt, Desc: "--limit 的旧版别名", Hidden: true},
+		{Name: "page-size", Type: shortcut.FlagInt, Desc: "--limit 的兼容别名", Hidden: true},
 		{Name: "direction", Type: shortcut.FlagString, Enum: []string{"newer", "older"}, Desc: "时间方向 newer/older；省略时为 older，从时间边界向前读取"},
 		{Name: "no-reactions", Type: shortcut.FlagBool, Desc: "不输出消息 reaction（默认输出）"},
+		{Name: "page-all", Type: shortcut.FlagBool, Desc: "沿 typed nextPage.time 自动读取后续页；--page-limit 仅与 --page-all 一起使用且范围 1-500；--max-results 仅与 --page-all 一起使用且不能为负数"},
+		{Name: "page-limit", Type: shortcut.FlagInt, Default: "50", Desc: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Name: "max-results", Type: shortcut.FlagInt, Desc: "--max-results 仅与 --page-all 一起使用且不能为负数；0 表示仅受页数上限约束"},
+		{Name: "output", Shorthand: "o", Type: shortcut.FlagString, Desc: "把完整结构化 ledger 原子写入工作目录内的相对 JSON 文件"},
 	}, chatshortcut.MessageResourceDownloadFlags()...),
 	Constraints: append([]shortcut.Constraint{
-		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"group", "conversation-id", "id", "user", "open-dingtalk-id"}},
+		{Kind: shortcut.ConstraintExactlyOne, Flags: []string{"group", "conversation-id", "id", "open-conversation-id", "chat-query", "user", "user-query", "open-dingtalk-id"}},
+		{Kind: shortcut.ConstraintMutuallyExclusive, Flags: []string{"limit", "size", "page-size"}},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"time"}, Description: "--time 必须是 RFC3339、YYYY-MM-DD HH:mm:ss 或 YYYY-MM-DD"},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"limit"}, Description: "显式页大小必须大于 0"},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "page-limit"}, Description: "--page-limit 仅与 --page-all 一起使用且范围 1-500"},
+		{Kind: shortcut.ConstraintCustom, Flags: []string{"page-all", "max-results"}, Description: "--max-results 仅与 --page-all 一起使用且不能为负数"},
+		{
+			Kind:        shortcut.ConstraintCustom,
+			Flags:       []string{"output", "overwrite"},
+			Description: "--output 必须是工作目录内的相对 JSON 文件；默认不覆盖，--overwrite 仅与 --output 一起使用",
+		},
 	}, chatshortcut.MessageResourceDownloadConstraints()...),
 	Tips: []string{
 		`dws chat +chat-messages --group <openconversation_id> --time "2025-03-01 00:00:00"`,
-		`dws chat +chat-messages --user <userId> --time "2025-03-01 00:00:00" --limit 50`,
-		`dws chat +chat-messages --group <openconversation_id> --direction older`,
+		`dws chat +chat-messages --user <userId> --time "2025-03-01 00:00:00" --page-all --page-limit 50`,
+		`dws chat +chat-messages --group <openconversation_id> --direction older --page-all --output ./exports/messages.json`,
 	},
-	Validate: chatshortcut.ValidateMessageResourceDownload,
-	Execute: func(rt *shortcut.RuntimeContext) error {
-		// Step 1 — build params and pick the right tool. Param keys
-		// (openconversation_id / userId / time / forward / limit) match the MCP server
-		// schema for group and direct message listing.
-		var tool string
-		params := map[string]any{}
-		fallbackConversationID := ""
+	Validate: validateChatMessages,
+	Execute:  executeChatMessages,
+}

-		if rt.Changed("time") && rt.Str("time") != "" {
-			params["time"] = rt.Str("time")
-		} else {
-			params["time"] = formatDingTalkMessageBoundary(time.Now())
+func validateChatMessages(rt *shortcut.RuntimeContext) error {
+	if err := chatshortcut.ValidateMessageResourceDownload(rt); err != nil {
+		return err
+	}
+	if rt.Changed("time") && strings.TrimSpace(rt.Str("time")) != "" && !validChatTime(rt.Str("time")) {
+		return localChatOptionError("invalid_time_boundary", "+chat-messages 的 --time 格式无效", "--time")
+	}
+	for _, name := range []string{"limit", "size", "page-size"} {
+		if rt.Changed(name) && rt.Int(name) <= 0 {
+			return localChatOptionError("invalid_page_size", "+chat-messages 的 --"+name+" 必须大于 0", "--"+name)
 		}
-		if limit := rt.IntFirst("limit", "size"); limit > 0 {
-			params["limit"] = limit
+	}
+	if !rt.Bool("page-all") && (rt.Changed("page-limit") || rt.Changed("max-results")) {
+		return apperrors.NewValidation("--page-limit/--max-results 仅与 --page-all 一起使用")
+	}
+	if rt.Bool("page-all") {
+		if pageLimit := rt.Int("page-limit"); pageLimit < 1 || pageLimit > chatMessagesHardPageLimit {
+			return apperrors.NewValidation("--page-limit 必须在 1-500 之间")
 		}
-		// direction newer/older maps to the tools' boolean `forward` param
-		// (newer -> forward=true, older -> forward=false), matching chat.go's
-		// resolveMessageForward.
-		if rt.Changed("direction") {
-			switch strings.TrimSpace(strings.ToLower(rt.Str("direction"))) {
-			case "newer":
-				params["forward"] = true
-			case "older":
-				params["forward"] = false
-			}
-		} else {
-			params["forward"] = false
+		if rt.Int("max-results") < 0 {
+			return apperrors.NewValidation("--max-results 不能小于 0")
 		}
-
-		if group := rt.StrFirst("group", "conversation-id", "id"); group != "" {
-			tool = "list_conversation_message_v2"
-			params["openconversation_id"] = group
-			fallbackConversationID = group
-		} else if openID := strings.TrimSpace(rt.Str("open-dingtalk-id")); openID != "" {
-			tool = "list_individual_chat_message"
-			params["openDingTalkId"] = openID
-		} else {
-			tool = "list_individual_chat_message"
-			params["userId"] = rt.Str("user")
-		}
-
-		data, err := rt.CallMCPData("chat", tool, params)
-		if err != nil {
+	}
+	if rt.Changed("output") {
+		if err := chatshortcut.ValidateMessageExportOutput(rt.Str("output")); err != nil {
 			return err
 		}
+	} else if rt.Bool("overwrite") {
+		return apperrors.NewValidation("--overwrite 仅与 --output 一起使用")
+	}
+	return nil
+}

-		// Step 2 — defensively unwrap and project. Response shape has no
-		// contract, so probe multiple candidate container/field keys.
+type chatMessagesRequest struct {
+	tool                   string
+	params                 map[string]any
+	direction              string
+	fallbackConversationID string
+}
+
+func resolveChatMessagesRequest(rt *shortcut.RuntimeContext) (chatMessagesRequest, error) {
+	groupID := strings.TrimSpace(rt.StrFirst("conversation-id", "id", "open-conversation-id"))
+	userID := rt.Str("user")
+	openID := rt.Str("open-dingtalk-id")
+	if targetresolver.LooksLikeOpenConversationID(openID) {
+		return chatMessagesRequest{}, apperrors.NewValidation(
+			"--open-dingtalk-id 收到的是群 openConversationId；群聊请改用 --group（兼容别名 --chat）",
+		)
+	}
+	if groupID == "" && (rt.Str("group") != "" || rt.Str("chat-query") != "") {
+		resolved, err := targetresolver.ResolveChatTarget(rt, rt.Str("group"), rt.Str("chat-query"))
+		if err != nil {
+			return chatMessagesRequest{}, err
+		}
+		groupID = resolved.Selected.OpenConversationID
+	}
+	if query := rt.Str("user-query"); query != "" {
+		resolved, err := targetresolver.ResolveUser(rt, query, targetresolver.IdentityOpenDingTalkID)
+		if err != nil {
+			return chatMessagesRequest{}, err
+		}
+		openID = resolved.Selected.OpenDingTalkID
+	}
+
+	direction := strings.TrimSpace(strings.ToLower(rt.Str("direction")))
+	if direction == "" {
+		direction = "older"
+	}
+	params := map[string]any{
+		"time":    formatDingTalkMessageBoundary(time.Now()),
+		"forward": direction == "newer",
+	}
+	if rt.Changed("time") && rt.Str("time") != "" {
+		params["time"] = rt.Str("time")
+	}
+	if limit := rt.IntFirst("limit", "size", "page-size"); limit > 0 {
+		params["limit"] = limit
+	} else if rt.Bool("page-all") {
+		params["limit"] = chatMessagesAllPageSize
+	}
+
+	request := chatMessagesRequest{params: params, direction: direction}
+	switch {
+	case groupID != "":
+		request.tool = "list_conversation_message_v2"
+		request.params["openconversation_id"] = groupID
+		request.fallbackConversationID = groupID
+	case openID != "":
+		request.tool = "list_individual_chat_message"
+		request.params["openDingTalkId"] = openID
+	default:
+		request.tool = "list_individual_chat_message"
+		request.params["userId"] = userID
+	}
+	return request, nil
+}
+
+func executeChatMessages(rt *shortcut.RuntimeContext) error {
+	request, err := resolveChatMessagesRequest(rt)
+	if err != nil {
+		return err
+	}
+	var payload map[string]any
+	var rawItems []map[string]any
+	if rt.Bool("page-all") {
+		payload, rawItems, err = collectAllChatMessages(rt, request)
+	} else {
+		payload, rawItems, err = collectOneChatMessagesPage(rt, request)
+	}
+	if err != nil {
+		// Full-page collection returns its failure ledger together with a
+		// non-zero error. Publish that ledger for diagnosis, but stop before
+		// resource downloads or a requested export can look successful.
+		if payload != nil {
+			if outputErr := rt.Output(payload); outputErr != nil {
+				return outputErr
+			}
+		}
+		return err
+	}
+	if rt.Bool("download-resources") {
+		chatshortcut.AttachMessageResourceDownloads(
+			payload,
+			chatshortcut.DownloadMessageResources(rt, rawItems, request.fallbackConversationID),
+		)
+	}
+	if rt.Changed("output") {
+		if rt.DryRun() {
+			payload["export"] = map[string]any{
+				"dryRun":    true,
+				"format":    "json",
+				"localPath": rt.Str("output"),
+				"overwrite": rt.Bool("overwrite"),
+			}
+		} else {
+			path, size, writeErr := chatshortcut.WriteMessageExportJSON(
+				rt.Str("output"), rt.Bool("overwrite"), payload)
+			if writeErr != nil {
+				return writeErr
+			}
+			payload["export"] = map[string]any{
+				"format":    "json",
+				"localPath": path,
+				"sizeBytes": size,
+			}
+		}
+	}
+	return rt.Output(payload)
+}
+
+func collectOneChatMessagesPage(rt *shortcut.RuntimeContext, request chatMessagesRequest) (map[string]any, []map[string]any, error) {
+	data, err := rt.CallMCPData("chat", request.tool, request.params)
+	if err != nil {
+		return nil, nil, err
+	}
+	items := chatMessageItems(data)
+	results := projectChatMessages(items, !rt.Bool("no-reactions"))
+	payload := chatmsg.NewMessageListPayload(results)
+	chatmsg.ApplyMessagePagination(payload, data, items, request.direction)
+	if payload["complete"] == true {
+		payload["stopReason"] = "source_complete"
+	} else {
+		payload["stopReason"] = "single_page"
+	}
+	return payload, items, nil
+}
+
+func collectAllChatMessages(rt *shortcut.RuntimeContext, request chatMessagesRequest) (map[string]any, []map[string]any, error) {
+	pageLimit := defaultChatPageLimit(rt.Int("page-limit"), chatMessagesDefaultPageLimit)
+	maxResults := rt.Int("max-results")
+	seenIDs := map[string]bool{}
+	seenBoundaries := map[string]bool{fmt.Sprint(request.params["time"]): true}
+	allItems := make([]map[string]any, 0)
+	failures := make([]map[string]any, 0)
+	pagesFetched := 0
+	paginationKnown := true
+	complete := false
+	hasMore := false
+	stopReason := "source_complete"
+	truncatedByPageLimit := false
+	truncatedByResultLimit := false
+	var nextPage map[string]any
+
+	for pagesFetched < pageLimit {
+		data, err := rt.CallMCPData("chat", request.tool, request.params)
+		if err != nil {
+			failures = append(failures, map[string]any{
+				"page":  pagesFetched + 1,
+				"stage": "read",
+				"error": err.Error(),
+			})
+			stopReason = "read_failure"
+			break
+		}
+		pagesFetched++
 		items := chatMessageItems(data)
-		results := make([]map[string]any, 0, len(items))
-		for _, m := range items {
-			results = append(results, projectChatMessageWithReactions(m, !rt.Bool("no-reactions")))
+		keptOnPage := make([]map[string]any, 0, len(items))
+		for _, item := range items {
+			stableID := chatmsg.StableMessageID(item)
+			if stableID != "" && seenIDs[stableID] {
+				continue
+			}
+			if stableID != "" {
+				seenIDs[stableID] = true
+			}
+			allItems = append(allItems, item)
+			keptOnPage = append(keptOnPage, item)
+			if maxResults > 0 && len(allItems) >= maxResults {
+				break
+			}
 		}

-		payload := map[string]any{
-			"messages": results,
-			"count":    len(results),
+		page := chatmsg.Pagination(data)
+		pageHasMore, hasMoreKnown := page["hasMore"].(bool)
+		if !hasMoreKnown {
+			paginationKnown = false
+			failures = append(failures, map[string]any{
+				"page":  pagesFetched,
+				"stage": "pagination",
+				"error": "下层未返回可靠的 hasMore，无法证明全量结果完整",
+			})
+			stopReason = "pagination_error"
+			break
 		}
-		direction := strings.TrimSpace(strings.ToLower(rt.Str("direction")))
-		chatmsg.ApplyMessagePagination(payload, data, items, direction)
-		if rt.Bool("download-resources") {
-			payload["resourceDownloads"] = chatshortcut.DownloadMessageResources(rt, items, fallbackConversationID)
+		hasMore = pageHasMore
+
+		if maxResults > 0 && len(allItems) >= maxResults {
+			truncatedByResultLimit = pageHasMore || len(keptOnPage) < len(items)
+			if truncatedByResultLimit {
+				hasMore = true
+				stopReason = "result_limit"
+				if len(keptOnPage) > 0 {
+					nextPage = messageNextPage(keptOnPage[len(keptOnPage)-1], request.direction)
+					boundary := strings.TrimSpace(fmt.Sprint(nextPage["time"]))
+					if boundary == "" || boundary == "<nil>" {
+						failures = append(failures, map[string]any{
+							"page":  pagesFetched,
+							"stage": "pagination",
+							"error": "达到结果上限但无法生成可靠的 nextPage.time",
+						})
+						stopReason = "pagination_error"
+						nextPage = nil
+					}
+				}
+				break
+			}
 		}
-		return rt.Output(payload)
-	},
+		if !pageHasMore {
+			complete = true
+			hasMore = false
+			stopReason = "source_complete"
+			break
+		}
+		if len(items) == 0 {
+			failures = append(failures, map[string]any{
+				"page":  pagesFetched,
+				"stage": "pagination",
+				"error": "下层返回 hasMore=true 但当前页没有消息",
+			})
+			stopReason = "pagination_error"
+			break
+		}
+		nextPage = messageNextPage(items[len(items)-1], request.direction)
+		boundary := strings.TrimSpace(fmt.Sprint(nextPage["time"]))
+		if boundary == "" || boundary == "<nil>" || seenBoundaries[boundary] {
+			failures = append(failures, map[string]any{
+				"page":  pagesFetched,
+				"stage": "pagination",
+				"error": "hasMore=true 但 nextPage.time 缺失或停滞",
+			})
+			stopReason = "pagination_error"
+			break
+		}
+		seenBoundaries[boundary] = true
+		request.params["time"] = boundary
+	}
+	if !complete && hasMore && len(failures) == 0 && pagesFetched >= pageLimit {
+		truncatedByPageLimit = true
+		stopReason = "page_limit"
+	}
+
+	results := projectChatMessages(allItems, !rt.Bool("no-reactions"))
+	payload := chatmsg.NewMessageListPayload(results)
+	payload["pagesFetched"] = pagesFetched
+	payload["paginationKnown"] = paginationKnown
+	payload["complete"] = complete && len(failures) == 0
+	payload["hasMore"] = hasMore
+	payload["stopReason"] = stopReason
+	payload["truncatedByPageLimit"] = truncatedByPageLimit
+	payload["truncatedByResultLimit"] = truncatedByResultLimit
+	payload["failedCount"] = len(failures)
+	payload["failures"] = failures
+	payload["partial"] = len(failures) > 0 && len(results) > 0
+	if hasMore && nextPage != nil {
+		payload["nextPage"] = nextPage
+	}
+	if len(failures) > 0 {
+		failureStage := "pagination"
+		if stopReason == "read_failure" {
+			failureStage = "read"
+		}
+		return payload, allItems, apperrors.NewAPI(
+			fmt.Sprintf("全量消息读取未完成：%d 页成功，%d 个页面失败", pagesFetched, len(failures)),
+			apperrors.WithOperation("chat/"+request.tool),
+			apperrors.WithReason("chat_messages_incomplete"),
+			apperrors.WithOrigin("mcp_gateway"),
+			apperrors.WithFailureStage(failureStage),
+			apperrors.WithExecutionStarted(true),
+			apperrors.WithRetryable(true),
+			apperrors.WithHint("请根据 failures 和 nextPage 重试；失败 ledger 不会写入 --output 文件"),
+			apperrors.WithDetails(map[string]any{
+				"pagesFetched": pagesFetched,
+				"failedCount":  len(failures),
+				"failures":     failures,
+				"partial":      len(results) > 0,
+				"stopReason":   stopReason,
+			}),
+		)
+	}
+	return payload, allItems, nil
+}
+
+func projectChatMessages(items []map[string]any, includeReactions bool) []map[string]any {
+	results := make([]map[string]any, 0, len(items))
+	for _, item := range items {
+		results = append(results, projectChatMessageWithReactions(item, includeReactions))
+	}
+	return results
+}
+
+func messageNextPage(message map[string]any, direction string) map[string]any {
+	return map[string]any{
+		"time":      chatmsg.CreateTime(message),
+		"direction": direction,
+	}
 }

 // chatMessageItems defensively unwraps the message list from the response,
@@ -219,44 +507,7 @@ func projectChatMessage(m map[string]any) map[string]any {
 }

 func projectChatMessageWithReactions(m map[string]any, includeReactions bool) map[string]any {
-	row := map[string]any{
-		"sender":     chatmsg.Sender(m),
-		"text":       chatmsg.Text(m),
-		"createTime": chatmsg.CreateTime(m),
-	}
-	if messageID := chatmsg.MessageID(m); messageID != nil {
-		row["messageId"] = messageID
-	}
-	if conversationID := chatmsg.ConversationID(m); conversationID != nil {
-		row["conversationId"] = conversationID
-	}
-	if threadID := chatmsg.ThreadID(m); threadID != nil {
-		row["threadId"] = threadID
-	}
-	if messageType := chatmsg.MessageType(m); messageType != nil {
-		row["messageType"] = messageType
-	}
-	if updateTime := chatmsg.UpdateTime(m); updateTime != nil {
-		row["updateTime"] = updateTime
-	}
-	if includeReactions {
-		if reactions := chatmsg.Reactions(m); len(reactions) > 0 {
-			row["reactions"] = reactions
-		}
-	}
-	if quoted := chatmsg.QuotedMessage(m); len(quoted) > 0 {
-		row["quotedMessage"] = quoted
-	}
-	if resources := chatmsg.ResourcesDeep(m); len(resources) > 0 {
-		row["resourceRefs"] = resources
-	}
-	projectForwarded := func(item map[string]any) map[string]any {
-		return projectChatMessageWithReactions(item, includeReactions)
-	}
-	if forwarded := chatmsg.Forwarded(m, projectForwarded); len(forwarded) > 0 {
-		row["forwarded"] = forwarded
-	}
-	return row
+	return chatmsg.ProjectMessageV1(m, includeReactions)
 }

 func init() {
@@ -13,14 +13,25 @@

 package smart

-import "testing"
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	stderrors "errors"
+	"os"
+	"testing"
+
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/edition"
+)

 // TestProjectChatMessageExpandsForwarded guards that a forwarded chat record
 // ("聊天记录") exposes its nested messages under "forwarded" instead of
 // collapsing to the lossy top-level "[卡片]" summary, recursing through nested
 // forwards, and that the string-"null" sender is nulled out. The per-field
 // behaviour (sender/text/encryption) is covered in the chatmsg package tests.
-func TestProjectChatMessageExpandsForwarded(t *testing.T) {
+func TestCrossPlatformCoverageProjectChatMessageExpandsForwarded(t *testing.T) {
 	row := projectChatMessage(map[string]any{
 		"sender":             "hugozhu",
 		"openMessageId":      "msg-top",
@@ -86,3 +97,238 @@ func TestProjectChatMessageExpandsForwarded(t *testing.T) {
 		t.Errorf("no-reactions projection leaked reactions: %#v", withoutReactions)
 	}
 }
+
+type chatMessagesPagingCaller struct {
+	responses []string
+	args      []map[string]any
+	failAt    int
+}
+
+type chatMessagesFailWriter struct{}
+
+func (chatMessagesFailWriter) Write([]byte) (int, error) {
+	return 0, stderrors.New("fixture output failure")
+}
+
+func (c *chatMessagesPagingCaller) CallTool(
+	_ context.Context,
+	_, _ string,
+	args map[string]any,
+) (*edition.ToolResult, error) {
+	copied := make(map[string]any, len(args))
+	for key, value := range args {
+		copied[key] = value
+	}
+	c.args = append(c.args, copied)
+	index := len(c.args) - 1
+	if c.failAt > 0 && len(c.args) == c.failAt {
+		return nil, stderrors.New("fixture read failure")
+	}
+	if index >= len(c.responses) {
+		index = len(c.responses) - 1
+	}
+	return &edition.ToolResult{Content: []edition.ContentBlock{{
+		Type: "text",
+		Text: c.responses[index],
+	}}}, nil
+}
+
+func (c *chatMessagesPagingCaller) CallReadTool(
+	ctx context.Context,
+	product, tool string,
+	args map[string]any,
+) (*edition.ToolResult, error) {
+	return c.CallTool(ctx, product, tool, args)
+}
+
+func (*chatMessagesPagingCaller) Format() string { return "json" }
+func (*chatMessagesPagingCaller) DryRun() bool   { return false }
+func (*chatMessagesPagingCaller) Fields() string { return "" }
+func (*chatMessagesPagingCaller) JQ() string     { return "" }
+
+func TestCrossPlatformCoverageChatMessagesPageAllUsesTypedBoundaryAndDeduplicates(t *testing.T) {
+	caller := &chatMessagesPagingCaller{responses: []string{
+		`{"result":{"hasMore":true,"messages":[{"openMessageId":"m2","createTime":"2026-01-02 00:00:00"},{"openMessageId":"m1","createTime":"2026-01-01 00:00:00"}]}}`,
+		`{"result":{"hasMore":false,"messages":[{"openMessageId":"m1","createTime":"2026-01-01 00:00:00"},{"openMessageId":"m0","createTime":"2025-12-31 00:00:00"}]}}`,
+	}}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+chat-messages", "--conversation-id", "cid",
+		"--time", "2026-01-03 00:00:00", "--page-all", "--page-limit", "5",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	if len(caller.args) != 2 || caller.args[1]["time"] != "2026-01-01 00:00:00" {
+		t.Fatalf("pagination calls = %#v", caller.args)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["complete"] != true || payload["hasMore"] != false ||
+		payload["count"] != float64(3) || payload["pagesFetched"] != float64(2) ||
+		payload["stopReason"] != "source_complete" {
+		t.Fatalf("all-page payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesPageAllPublishesBoundedContinuation(t *testing.T) {
+	caller := &chatMessagesPagingCaller{responses: []string{
+		`{"result":{"hasMore":true,"messages":[{"openMessageId":"m1","createTime":"2026-01-01 00:00:00"}]}}`,
+	}}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+chat-messages", "--conversation-id", "cid",
+		"--page-all", "--page-limit", "1",
+	})
+	if err := root.Execute(); err != nil {
+		t.Fatal(err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	next, _ := payload["nextPage"].(map[string]any)
+	if payload["complete"] != false || payload["hasMore"] != true ||
+		payload["truncatedByPageLimit"] != true || payload["stopReason"] != "page_limit" ||
+		next["time"] != "2026-01-01 00:00:00" {
+		t.Fatalf("bounded payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesPageAllFailsClosedOnStalledBoundary(t *testing.T) {
+	caller := &chatMessagesPagingCaller{responses: []string{
+		`{"result":{"hasMore":true,"messages":[{"openMessageId":"m1"}]}}`,
+	}}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{"chat", "+chat-messages", "--conversation-id", "cid", "--page-all"})
+	err := root.Execute()
+	var typed *apperrors.Error
+	if !stderrors.As(err, &typed) || typed.Category != apperrors.CategoryAPI ||
+		typed.Reason != "chat_messages_incomplete" || !typed.Retryable ||
+		typed.ExecutionStarted == nil || !*typed.ExecutionStarted {
+		t.Fatalf("error = %#v", err)
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+		t.Fatal(err)
+	}
+	if payload["complete"] != false || payload["failedCount"] != float64(1) ||
+		payload["stopReason"] != "pagination_error" {
+		t.Fatalf("stalled payload = %#v", payload)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesFailedPageDoesNotExportPartialLedger(t *testing.T) {
+	t.Chdir(t.TempDir())
+	caller := &chatMessagesPagingCaller{
+		responses: []string{
+			`{"result":{"hasMore":true,"messages":[{"openMessageId":"m1","createTime":"2026-01-01 00:00:00"}]}}`,
+		},
+		failAt: 2,
+	}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	var output bytes.Buffer
+	root.SetOut(&output)
+	root.SetArgs([]string{
+		"chat", "+chat-messages", "--conversation-id", "cid", "--page-all",
+		"--output", "exports/partial.json",
+	})
+	err := root.Execute()
+	var typed *apperrors.Error
+	if !stderrors.As(err, &typed) || typed.Reason != "chat_messages_incomplete" {
+		t.Fatalf("error = %#v", err)
+	}
+	if _, statErr := os.Lstat("exports/partial.json"); !os.IsNotExist(statErr) {
+		t.Fatalf("partial export exists: %v", statErr)
+	}
+	var ledger map[string]any
+	if err := json.Unmarshal(output.Bytes(), &ledger); err != nil {
+		t.Fatal(err)
+	}
+	if ledger["partial"] != true || ledger["failedCount"] != float64(1) || ledger["count"] != float64(1) {
+		t.Fatalf("failure ledger = %#v", ledger)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesFailureLedgerOutputErrorIsNonZero(t *testing.T) {
+	caller := &chatMessagesPagingCaller{responses: []string{
+		`{"result":{"hasMore":true,"messages":[{"openMessageId":"m1"}]}}`,
+	}}
+	helpers.InitDeps(caller)
+	root := newPlatformCoverageRoot()
+	root.SetOut(chatMessagesFailWriter{})
+	root.SetArgs([]string{"chat", "+chat-messages", "--conversation-id", "cid", "--page-all"})
+	if err := root.Execute(); err == nil || err.Error() != "fixture output failure" {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesExportIsAtomicAndNoClobber(t *testing.T) {
+	t.Chdir(t.TempDir())
+	newCaller := func() *chatMessagesPagingCaller {
+		return &chatMessagesPagingCaller{responses: []string{
+			`{"result":{"hasMore":false,"messages":[{"openMessageId":"m1","createTime":"2026-01-01 00:00:00"}]}}`,
+		}}
+	}
+	run := func(overwrite bool) error {
+		helpers.InitDeps(newCaller())
+		root := newPlatformCoverageRoot()
+		root.SetOut(&bytes.Buffer{})
+		args := []string{"chat", "+chat-messages", "--conversation-id", "cid", "--page-all", "--output", "exports/messages.json"}
+		if overwrite {
+			args = append(args, "--overwrite")
+		}
+		root.SetArgs(args)
+		return root.Execute()
+	}
+	if err := run(false); err != nil {
+		t.Fatal(err)
+	}
+	raw, err := os.ReadFile("exports/messages.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var exported map[string]any
+	if err := json.Unmarshal(raw, &exported); err != nil {
+		t.Fatal(err)
+	}
+	if exported["complete"] != true || exported["count"] != float64(1) {
+		t.Fatalf("exported ledger = %#v", exported)
+	}
+	if err := run(false); err == nil {
+		t.Fatal("existing export was overwritten without --overwrite")
+	}
+	if err := run(true); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestCrossPlatformCoverageChatMessagesExportRejectsNonJSONPlaceholder(t *testing.T) {
+	t.Chdir(t.TempDir())
+	helpers.InitDeps(&chatMessagesPagingCaller{responses: []string{
+		`{"result":{"hasMore":false,"messages":[]}}`,
+	}})
+	root := newPlatformCoverageRoot()
+	root.SetOut(&bytes.Buffer{})
+	root.SetArgs([]string{
+		"chat", "+chat-messages", "--conversation-id", "cid", "--output", "{}",
+	})
+	if err := root.Execute(); err == nil {
+		t.Fatal("non-JSON placeholder output unexpectedly succeeded")
+	}
+	if _, err := os.Lstat("{}"); !os.IsNotExist(err) {
+		t.Fatalf("placeholder output was created: %v", err)
+	}
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Dennis	e2c15fe9c8	fix(schema): reject breaking constraint expansion	2026-08-05 14:56:18 +08:00
Dennis	9fdf0d2cb3	fix(im): preserve incomplete read failures	2026-08-05 14:27:53 +08:00
Dennis	b6325a4f8a	fix(im): harden user resolution and broadcast lookup	2026-08-05 13:57:27 +08:00
Dennis	2588c711a7	Merge origin/main into codex/multi-im-optimization	2026-08-05 11:24:58 +08:00
john	000bc13450	Merge pull request #830 from typefield/agent/cmdcore-phase2 feat(corecmd): unify leaf/shortcut command framework onto a shared typed base	2026-08-05 10:03:21 +08:00
Dennis	01782cd9d7	test(profilectx): cover profile selector	2026-08-05 09:35:57 +08:00
玉澜andCursor	ba56b7ff78	fix(test): use testseam.Protect in InitDepsForTest coverage Policy bans manual t.Cleanup deps restores; Protect is the required seam form. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-05 02:03:51 +08:00
玉澜andCursor	c5c97e60f3	test(coverage): cover InitDepsForTest and StaticServers visibility Platform coverage only selects TestCrossPlatformCoverage*; name the new declaration-only visibility regression accordingly and exercise the ForTest deps restore helper. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-05 01:49:37 +08:00
玉澜andCursor	6780177356	fix(test): assert non-dry-run version preflight via CallTool Outside --dry-run, list_doc_versions uses the normal CallTool channel; CallReadTool is reserved for the dry-run read path. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-05 01:30:17 +08:00
玉澜andCursor	5fa40b8ada	fix: keep Schema source visibility without clobbering deps Declaration-only roots skip injectStaticServers; derive product visibility from StaticServers directly so reverse completeness is not weakened, and restore helpers deps via pointer snapshot instead of InitDeps(nil). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-05 01:22:45 +08:00
玉澜andCursor	8a7d4a7027	fix: nil-safe doc deprecation wrappers for declaration-only Schema probes Homology Execute probes use NewSchemaSourceRootCommand (no InitDeps); skip deps.Out when unset and InitDeps a throwaway caller on the probe path. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-05 00:18:46 +08:00
玉澜andCursor	894e550950	fix: keep schema source root from clobbering runtime deps/endpoints Schema assembly must mount the reviewed command tree without InitDeps or SetDynamicServers, so a live process keeps its ToolCaller and plugin endpoints. Also restore doc version revert dry-run short-circuit so --dry-run skips remote version preflight. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 23:42:05 +08:00
Dennis	ad4ed41559	Merge origin/main into codex/multi-im-optimization	2026-08-04 22:23:31 +08:00
玉澜andCursor	bb205c0f5c	ci: align macOS auth filter with main Drop Windows-only DPAPI export/import names from the darwin -run filter; those tests skip on macOS and already run under the Windows job. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 22:14:48 +08:00
Dennis	86f9054d5b	test(chat): cover batch output failures	2026-08-04 22:13:20 +08:00
玉澜andCursor	82c6b631bf	Merge origin/main into agent/cmdcore-phase2 Resolve macOS CI auth/keychain job conflicts by keeping main's focused 6m keychain/auth split and unsigned-darwin self-heal filter, while retaining this branch's portable DPAPI export/import diagnostics coverage. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 22:11:33 +08:00
github-actions[bot]	306c30ecad	Merge pull request #857 from DingTalk-Real-AI/codex/fix-macos-auth-test-scope ci: avoid duplicate internal/app race suite on macOS	2026-08-04 22:07:20 +08:00
玉澜andCursor	f793d980b5	fix(test): align leaf BuildArgs expectations with required-after-transform TestLeafArgsOmitsEmptyAndNonPositive called BuildArgs with unset required CSV flags; after rejecting empty required transforms that path correctly errors. Satisfy required flags in the omit-empty case and cover the new RequiredError / scalar-transform branches for the macOS coverage gate. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 21:54:02 +08:00
玉澜andCursor	706dbb349c	fix(corecmd): reject required flags that transform to empty lists Separator-only inputs like --event-codes ',' passed pre-transform Required checks, then BuildArgs omitted the key and ConfirmFirst write paths could still call MCP. Enforce non-empty transform results for Required flags and add CrossPlatformCoverage regression coverage. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 21:38:40 +08:00
玉澜andCursor	45d0d1cd72	test(ci): reject restoring combined macOS app race shard Keep the darwin workflow contract from re-accepting the merged keychain+auth+app invocation that main briefly required. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 21:06:33 +08:00
玉澜andCursor	e9a2360d36	fix(ci): align darwin workflow contract with auth/keychain split Keep the changelog gate asserting the focused macOS auth/keychain job instead of main's combined keychain/auth/app race command. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 21:05:17 +08:00
玉澜andCursor	9531dad9c6	Merge origin/main into agent/cmdcore-phase2 Port OA approval form-schema / forecast-process / create-instance from main via DeclareLeafMetadata and mapping-ledger exclusions; keep retired schema pin paths deleted and preserve the CI auth/keychain split. Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 20:52:53 +08:00
chichuan	20d27f6db9	Merge latest main into codex/fix-macos-auth-test-scope Resolve the macOS race budget conflict in favour of the focused scope. `c1f96241` on main extended the whole-package macOS race step from 10m to 12m and pinned that budget in the workflow contract. This branch removes the whole-package run instead: ./internal/app is already covered by the Ubuntu "race: app" shard, and macOS only needs the natively-gated tests. With the focused scope the job drops from 10m47s to ~3m, so the 12m budget is no longer needed and the two step timeouts (6m + 5m) fit inside the 15m job budget with headroom. The contract assertion `c1f96241` added is superseded rather than dropped: pinning both focused commands locks the per-step timeouts, and the existing checks still block a whole-package regression and require ./internal/app to appear exactly once.	2026-08-04 20:14:58 +08:00
github-actions[bot]	ca2b8adcb2	Merge pull request #853 from DingTalk-Real-AI/codex/sync-wukong-oa-approval feat(oa): add approval form workflow commands	2026-08-04 20:05:58 +08:00
Dennis	c4d5139a50	fix(chat): fail batch sends on delivery errors	2026-08-04 19:43:22 +08:00
Dennis	867f20abec	test(chat): cover unsafe group files on Windows	2026-08-04 19:22:58 +08:00
Dennis	7c07b29de5	ci: retain failed Windows coverage profiles	2026-08-04 19:06:50 +08:00
Dennis	6ee0df8a9c	test(chat): cover Windows drive-relative paths	2026-08-04 18:53:24 +08:00
Dennis	33ceab6000	test(chat): keep platform replace alias coverage-neutral	2026-08-04 18:36:39 +08:00
Dennis	26b06fe0ff	fix(chat): replace exports atomically on Windows	2026-08-04 18:18:08 +08:00
chichuan	a3c7009f9b	Merge latest main into codex/fix-macos-auth-test-scope	2026-08-04 18:17:33 +08:00
chichuan	2d3f820f91	ci: keep the darwin-gated upgrade self-heal test reachable on macOS Narrowing the macOS internal/app -run pattern orphaned TestValidateNewBinary_RecoversFromUnsignedDarwin: it is the only runtime.GOOS != "darwin" gated test in the package, the Ubuntu race shard skips it on Linux, and the platform coverage gate only runs ^(TestAllShortcuts\|TestCrossPlatformCoverage). No CI job selected it any more, so it could never run or fail again. - Add the self-heal test back to the macOS -run pattern. - Add the (CrossPlatformCoverage)? group the Windows pattern already has, which also recovers TestCrossPlatformCoverageAuthMigrateKeychainRemainingBranches. - Attribute vacuous runs: the two skip paths now name the branch that went unverified, and DWS_REQUIRE_AMFI_SELF_HEAL=1 escalates such a run to a hard failure on a host that does enforce amfid. GitHub's hosted macOS runners do not reproduce the amfid kill, so this test has been silently skipping there all along. - Restore step-timeout headroom: 10m + 5m exactly equalled the 15m job budget, leaving none for setup. The keychain/auth step drops to 6m (measured 2m43s). - Add a contract test that couples the macOS -run pattern to the set of darwin-gated tests in internal/app, so the next narrowing fails loudly instead of silently orphaning one.	2026-08-04 17:59:59 +08:00
chichuan	f5a1b64d7a	test(oa): include approval cases in native coverage	2026-08-04 17:36:22 +08:00
chichuan	c1f96241af	ci: extend macOS race test budget	2026-08-04 17:23:04 +08:00
玉澜andCursor	eb63b3933e	test(schema): restore interface metadata fallback coverage for overall gate Cover applyInterfaceMetadataFallback success/audit paths and summary edges that were lost when interface_metadata_test.go was retired, closing the aggregate overall non-regression gap (~91.22% → above merge-base). Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-04 17:19:51 +08:00
Dennis	7a5582f4f9	fix(ci): make multi IM coverage platform-safe	2026-08-04 17:05:59 +08:00
chichuan	eb571e6e73	fix(oa): remove unreachable mode checks	2026-08-04 16:42:57 +08:00
Dennis	f050fbdebc	Merge latest main into codex/multi-im-optimization	2026-08-04 16:17:01 +08:00
chichuan	4d5a47ac93	Merge latest main into codex/sync-wukong-oa-approval	2026-08-04 16:16:21 +08:00
Dennis	e27dc9fe53	fix(schema): close chat runtime contract review	2026-08-04 16:09:54 +08:00
chichuan	6108f51c9d	fix(oa): align approval mode schema contracts	2026-08-04 16:08:51 +08:00
Dennis	85587b9b62	fix(schema): preserve published chat constraints	2026-08-04 15:31:10 +08:00
Dennis	10d93f310e	fix(schema): restore chat compatibility gates	2026-08-04 15:18:04 +08:00
Dennis	99478c0060	feat(schema): publish complete chat shortcut catalog	2026-08-04 14:24:49 +08:00
chichuan	31e3f6bcbc	Merge remote-tracking branch 'origin/main' into codex/sync-wukong-oa-approval # Conflicts: # internal/cli/schema_agent_metadata/index.json # internal/cli/schema_agent_metadata_audit.json # internal/cli/schema_catalog/catalog.json	2026-08-04 11:41:38 +08:00
chichuan	678f108adf	docs(oa): complete approval workflow references	2026-08-04 11:39:55 +08:00
Dennis	ee943d9b3f	Merge remote-tracking branch 'origin/main' into codex/multi-im-optimization # Conflicts: # internal/cli/schema_agent_metadata/index.json # internal/cli/schema_agent_metadata_audit.json # internal/cli/schema_catalog/catalog.json # internal/cli/schema_hints/runtime-surface-completeness.json # test/mock_mcp/mock_mcp_smoke_test.go	2026-08-04 11:25:36 +08:00
Dennis	a3c85a01a8	chore(im): sanitize pull request fixtures	2026-08-04 11:19:38 +08:00
Dennis	81f67c8d7b	fix(im): classify failures and normalize chat targets	2026-08-04 11:06:35 +08:00
Raph	a240ad2b81	ci: focus macOS auth race tests	2026-08-03 23:09:58 +08:00
chichuan	f39a3f5417	Merge branch 'main' into codex/sync-wukong-oa-approval	2026-08-03 21:18:39 +08:00
Dennis	30314311e4	fix(im): harden live audit contracts	2026-08-03 20:39:27 +08:00
Dennis	2a8c6c87cb	feat(im): harden multi IM golden routes	2026-08-03 19:50:10 +08:00
chichuan	e806e761ad	test(oa): cover approval request branches	2026-08-03 19:48:26 +08:00
chichuan	a6696fe9e9	fix(schema): map OA request wrappers	2026-08-03 19:26:22 +08:00
chichuan	06af21c7a1	fix(oa): complete approval instance options	2026-08-03 19:09:51 +08:00
chichuan	eba2b692ec	feat(oa): add approval form workflow commands	2026-08-03 19:02:39 +08:00
Dennis	017258e5b4	feat(im): optimize Multi IM golden routes Unify natural target resolution and message contracts, add deterministic IM event listening, streamline cold-start skills, and cover the flows with schema gates and end-to-end tests.	2026-08-03 14:54:19 +08:00