test(ci): cover command governance branches

feat(chat): expose single group role flag

.changes/1058-chat-group-role-single-flag.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **Chat group roles** (#1058) — exposes the single-value `--role-id` flag for assigning one custom group role while preserving hidden `--role-ids` compatibility.

.changes/976-recruit-job.md

@@ -0,0 +1,5 @@
+---
+category: Added
+---
+
+- **招聘职位管理** (#976) — 新增招聘职位列表、详情查询和职位创建命令。

.changes/chat-user-mention-tokens.md

@@ -0,0 +1,6 @@
+---
+category: Fixed
+---
+
+- **Chat user mentions** — preserves literal `<@openDingTalkId>` tokens in current-user Markdown messages and rejects mismatches between message-body mentions and mention flags before sending.
+- **Chat direct media** — uses the IM upload target field for current-user direct file, audio, and video uploads, then uses the Chat receiver field for final message delivery.

.changes/command-path-migration-governance.md

@@ -0,0 +1,5 @@
+---
+category: Changed
+---
+
+- **CLI compatibility governance** — adds a reviewed two-stage path for hiding retained legacy commands or optional `NoOpt=true` boolean flags from Help and Schema when their activated capability moves to a dedicated command, with legacy-leaf, complete parameter/constant mapping, durable runtime constant evidence, protected framework bridges, dry-run preservation, parameter-collision, and fail-closed required-parameter checks.

.github/workflows/ci.yml

@@ -512,6 +512,12 @@ jobs:
         if: steps.classify.outputs.changelog_only != 'true' && steps.classify.outputs.docs_only != 'true'
         run: node .github/reviewer-routing.test.js
 
+      - name: Test npm installer smoke (prune, backup, publish)
+        if: steps.classify.outputs.changelog_only != 'true' && steps.classify.outputs.docs_only != 'true'
+        env:
+          XDG_CONFIG_HOME: ""
+        run: node test/scripts/install_js_smoke.mjs
+
   test-focused:
     name: "Test (focused: ${{ matrix.shard }})"
     needs: lint

CONTRIBUTING.md

@@ -74,9 +74,9 @@ coverage is additionally selected for platform-sensitive code.
    `make authoritative-interface-integrity BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>`.
    The Make target delegates to the authoritative wrapper; CI does not invoke a
    second comparator or the legacy fixture checker. See
-   [CLI flag compatibility migration governance](docs/cli-interface-flag-migrations.md)
+   [CLI Help / Schema compatibility migration governance](docs/cli-interface-flag-migrations.md)
    for the reviewed two-stage `pending` → `consumed` lifecycle.
-   Agent-visible flag migrations must also run
+   Agent-visible flag or command-path migrations must also run
    `make schema-compatibility BASE_REF=<merge-base> STABLE_REF=<latest-GA-tag> CANDIDATE_REF=<candidate-sha>`;
    it consumes the same base-owned ledger rather than a second exception list.
 5. Run `./scripts/policy/check-generated-drift.sh` when generated artifacts may

Makefile

@@ -10,7 +10,7 @@ SCHEMA_META_INDEX_OUTPUT ?= artifacts/schema_meta_index.gob
 POLICY_ENV = DWS_POLICY_TMPDIR="$(DWS_POLICY_TMPDIR)" GOTMPDIR="$(POLICY_GOTMPDIR)"
 GO_SOURCE_LIST = git ls-files -z --cached --others --exclude-standard -- '*.go'
 
-.PHONY: all help build check-safechat test-safechat rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
+.PHONY: all help build rebuild test test-plan test-auth-legacy-compat lint format-check fmt policy edition-test interface-integrity authoritative-interface-integrity coverage-gate coverage-gate-platform update-interface-baseline reset-interface-baseline schema-compatibility skill-command-integrity skill-context-budget multi-im-skill-chain-integrity cli-smoke mock-mcp-smoke test-schema-agent-examples generate-schema fetch-mcp-metadata generate-schema-catalog package release release-pre release-stable changelog-pre changelog-stable publish-homebrew-formula setup-hooks
 
 all: setup-hooks fmt lint build test rebuild
 
@@ -18,8 +18,6 @@ help:
 	@printf "Available targets:\n"
 	@printf "  make build         - Build the dws CLI binary\n"
 	@printf "  make test          - Run the Go test suite\n"
-	@printf "  make check-safechat - Compile and vet the SafeChat message-crypto backend (needs CGO)\n"
-	@printf "  make test-safechat - Run the message-crypto tests against the SafeChat backend\n"
 	@printf "  make test-plan     - Verify CI test and full-suite coverage package plans cover their scopes exactly once\n"
 	@printf "  make test-auth-legacy-compat - Run stable legacy authentication compatibility regressions\n"
 	@printf "  make lint          - Run formatting checks, go vet, and staticcheck\n"
@@ -54,16 +52,6 @@ build:
 rebuild:
 	@./scripts/dev/build.sh
 
-# No dws command imports internal/msgcrypto yet, so a tagged CLI build would
-# link nothing extra and look identical to the default binary. Gate the package
-# itself until a caller wires it in.
-check-safechat:
-	@CGO_ENABLED=1 $(GO) build -tags safechat ./internal/msgcrypto/...
-	@CGO_ENABLED=1 $(GO) vet -tags safechat ./internal/msgcrypto/...
-
-test-safechat:
-	@CGO_ENABLED=1 $(GO) test -count=1 -tags safechat ./internal/msgcrypto/...
-
 test:
 	@DWS_PACKAGE_VERSION="$(DWS_PACKAGE_VERSION)" $(GO) test -count=1 -timeout=10m ./...
 

README.md

@@ -210,7 +210,7 @@ The verifier uses isolated directories and does not replace the `dws` on the cur
 The upgrade process follows a two-phase atomic flow to ensure consistency:
 
 1. **Prepare** — downloads the platform-specific binary and skill packages to a temporary directory, verifies SHA256 checksums, and extracts/validates all files. If any step fails, the upgrade aborts without modifying the existing installation.
-2. **Apply** — only after all preparations succeed, the binary is replaced and skills are flattened into detected agent-specific roots (for example `~/.codex/skills/dingtalk-chat`). `~/.agents/skills` is used only when no specific Agent is detected; once a specific root is active, older DWS-managed generic copies are backed up and retired so the same Skill is not discovered twice.
+2. **Apply** — only after all preparations succeed, the binary is replaced and skills are flattened into the canonical `~/.agents/skills` root. Agents classified by the pinned compatibility registry as supporting the universal root read it directly; other detected Agents receive links to the canonical copy, with a direct-copy fallback when links are unavailable. Older DWS-managed agent-specific copies are backed up and retired so the same Skill is not discovered twice.
 
 A backup of the current version is automatically created before each upgrade. Use `dws upgrade --rollback` to restore the previous version if needed.
 
@@ -405,7 +405,7 @@ After installing, AI tools like Claude Code / Cursor can operate DingTalk direct
 curl -fsSL https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-workspace-cli/main/scripts/install-skills.sh | sh
 ```
 
-> Installers prefer detected agent-specific roots such as `$HOME/.codex/skills/`. They use `.agents/skills/` only as the generic fallback when no specific Agent is detected; multi layout is per-product siblings, while mono uses the `dws/` subdirectory.
+> Installers use `$HOME/.agents/skills/` as the canonical global store, following the universal `.agents/skills` convention. Agents classified by the pinned compatibility registry as universal read that root directly; detected non-universal Agents receive links to it (or copies when links are unavailable). Multi layout is per-product siblings, while mono uses the `dws/` subdirectory.
 >
 > China users: prefix `DWS_GITEE_REPO` to use the Gitee mirror — see [China mirror](#china-mirror).
 
@@ -482,7 +482,7 @@ Env vars: `DWS_SKILL_MODE=mono|multi` (also honored by `install.sh` / `install.p
 <details>
 <summary><strong>Personal Event Subscription</strong> — real-time DingTalk messages for event-driven agents</summary>
 
-`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, and six OA approval task/instance events.
+`dws event consume` subscribes as the currently logged-in user over a managed Stream WebSocket and emits each event as one NDJSON line on stdout. The public catalog covers scoped and all one-to-one/group messages, specified senders, read/recall/reaction events, group lifecycle events, and seven OA approval task/instance events.
 
 The default `ndjson`, `json`, and `pretty` output preserves the transport envelope (`type`, `event_type`, string `data`, and `headers`) for existing scripts; `compact` retains its existing processor. Add `--flatten` to emit the stable top-level business fields used by Agent workflows. `--format` controls JSON serialization; `--flatten` controls the data structure and cannot be combined with `-f raw` or `--debug-raw-events`.
 
@@ -530,12 +530,13 @@ dws event consume user_im_group_disbanded --group <openConversationId> --flatten
 dws event +listen-im --kind sender --user <userId> \
   --events message,read,recall -f ndjson
 
-# Listen for all six public OA approval events in one process
+# Listen for all seven public OA approval events in one process
 dws event consume \
   user_oa_approval_task_created \
   user_oa_approval_task_finished \
   user_oa_approval_task_redirected \
   user_oa_approval_instance_started \
+  user_oa_approval_instance_cc \
   user_oa_approval_instance_terminated \
   user_oa_approval_instance_finished \
   --flatten -f ndjson

README_zh.md

@@ -476,7 +476,7 @@ multi setup 或 upgrade 后，DWS 会把官方 bundle 快照和统一所有权
 <details>
 <summary><strong>个人事件订阅</strong> — 实时接收钉钉消息，驱动事件触发的 Agent</summary>
 
-`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期，以及六个 OA 审批任务/实例事件。
+`dws event consume` 使用当前 OAuth 登录用户建立托管的 Stream WebSocket 长连接，并把每条事件以 NDJSON 一行输出到 stdout。当前公开目录覆盖指定范围和全量单聊/群消息、指定发送人、已读/撤回/表情回应、群生命周期，以及七个 OA 审批任务/实例事件。
 
 默认 `ndjson`、`json`、`pretty` 输出保留兼容 transport envelope（`type`、`event_type`、字符串 `data`、`headers`），`compact` 继续沿用原 processor。Agent 或新脚本显式加 `--flatten` 后，输出稳定的顶层业务字段。`--format` 控制 JSON 序列化，`--flatten` 控制数据结构，且不能与 `-f raw` 或 `--debug-raw-events` 同时使用。
 
@@ -524,12 +524,13 @@ dws event consume user_im_group_disbanded --group <openConversationId> --flatten
 dws event +listen-im --kind sender --user <userId> \
   --events message,read,recall -f ndjson
 
-# 一个进程监听全部六个公开 OA 审批事件
+# 一个进程监听全部七个公开 OA 审批事件
 dws event consume \
   user_oa_approval_task_created \
   user_oa_approval_task_finished \
   user_oa_approval_task_redirected \
   user_oa_approval_instance_started \
+  user_oa_approval_instance_cc \
   user_oa_approval_instance_terminated \
   user_oa_approval_instance_finished \
   --flatten -f ndjson

build/npm/package.json.tmpl

@@ -32,6 +32,6 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=16"
+    "node": ">=16.7.0"
   }
 }

cmd/interface-snapshot/main.go

@@ -157,6 +157,16 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 		"",
 		"candidate flag migration manifest",
 	)
+	approvedCommandMigrationsPath := flags.String(
+		"approved-command-migrations",
+		"",
+		"merge-base-owned approved command migration manifest",
+	)
+	candidateCommandMigrationsPath := flags.String(
+		"candidate-command-migrations",
+		"",
+		"candidate command migration manifest",
+	)
 	if err := flags.Parse(args); err != nil {
 		return false, err
 	}
@@ -174,8 +184,13 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 			"--approved-flag-migrations and --candidate-flag-migrations must be provided together",
 		)
 	}
-	if *approvedMigrationsPath != "" && (*basePath == "" || *stablePath == "") {
-		return false, fmt.Errorf("flag migration compare requires both --base and --stable")
+	if (*approvedCommandMigrationsPath == "") != (*candidateCommandMigrationsPath == "") {
+		return false, fmt.Errorf(
+			"--approved-command-migrations and --candidate-command-migrations must be provided together",
+		)
+	}
+	if (*approvedMigrationsPath != "" || *approvedCommandMigrationsPath != "") && (*basePath == "" || *stablePath == "") {
+		return false, fmt.Errorf("migration compare requires both --base and --stable")
 	}
 
 	current, err := readSnapshot(*currentPath)
@@ -197,7 +212,39 @@ func runCompare(args []string, stdout, stderr io.Writer) (bool, error) {
 	}
 
 	report := interfacesnapshot.CompareAll(current, references)
-	if *approvedMigrationsPath != "" {
+	if *approvedCommandMigrationsPath != "" {
+		flagApproved := interfacesnapshot.FlagMigrationManifest{Version: interfacesnapshot.FlagMigrationManifestVersion, Migrations: []interfacesnapshot.FlagMigration{}}
+		flagCandidate := flagApproved
+		if *approvedMigrationsPath != "" {
+			flagApproved, err = readFlagMigrationManifest(*approvedMigrationsPath)
+			if err != nil {
+				return false, fmt.Errorf("read approved flag migrations: %w", err)
+			}
+			flagCandidate, err = readFlagMigrationManifest(*candidateMigrationsPath)
+			if err != nil {
+				return false, fmt.Errorf("read candidate flag migrations: %w", err)
+			}
+		}
+		commandApproved, readErr := readCommandMigrationManifest(*approvedCommandMigrationsPath)
+		if readErr != nil {
+			return false, fmt.Errorf("read approved command migrations: %w", readErr)
+		}
+		commandCandidate, readErr := readCommandMigrationManifest(*candidateCommandMigrationsPath)
+		if readErr != nil {
+			return false, fmt.Errorf("read candidate command migrations: %w", readErr)
+		}
+		report, err = interfacesnapshot.CompareAllWithInterfaceMigrations(
+			current,
+			references,
+			flagApproved,
+			flagCandidate,
+			commandApproved,
+			commandCandidate,
+		)
+		if err != nil {
+			return false, fmt.Errorf("validate interface migration lifecycle: %w", err)
+		}
+	} else if *approvedMigrationsPath != "" {
 		approved, readErr := readFlagMigrationManifest(*approvedMigrationsPath)
 		if readErr != nil {
 			return false, fmt.Errorf("read approved flag migrations: %w", readErr)
@@ -234,6 +281,15 @@ func readFlagMigrationManifest(path string) (interfacesnapshot.FlagMigrationMani
 	return interfacesnapshot.ReadFlagMigrationManifest(file)
 }
 
+func readCommandMigrationManifest(path string) (interfacesnapshot.CommandMigrationManifest, error) {
+	file, err := os.Open(filepath.Clean(path))
+	if err != nil {
+		return interfacesnapshot.CommandMigrationManifest{}, err
+	}
+	defer file.Close()
+	return interfacesnapshot.ReadCommandMigrationManifest(file)
+}
+
 func validateHelpRendering(root *cobra.Command, snapshot interfacesnapshot.Snapshot) error {
 	for _, command := range snapshot.Commands {
 		path := strings.TrimPrefix(command.Path, "dws")
@@ -280,5 +336,5 @@ func readSnapshot(path string) (interfacesnapshot.Snapshot, error) {
 func printUsage(w io.Writer) {
 	fmt.Fprintln(w, "usage:")
 	fmt.Fprintln(w, "  interface-snapshot generate [--output FILE]")
-	fmt.Fprintln(w, "  interface-snapshot compare --current FILE [--base FILE] [--stable FILE] [--approved-flag-migrations FILE --candidate-flag-migrations FILE]")
+	fmt.Fprintln(w, "  interface-snapshot compare --current FILE [--base FILE] [--stable FILE] [--approved-flag-migrations FILE --candidate-flag-migrations FILE] [--approved-command-migrations FILE --candidate-command-migrations FILE]")
 }

cmd/interface-snapshot/main_test.go

@@ -166,6 +166,102 @@ func TestCrossPlatformCoverageRunCompareRequiresBothFlagMigrationInputs(t *testi
 	}
 }
 
+func TestCrossPlatformCoverageRunCompareCommandMigrationInputs(t *testing.T) {
+	dir := t.TempDir()
+	snapshotPath := writeSnapshot(t, dir, "snapshot.json", commandSnapshot("dws"))
+	emptyFlag := writeManifest(t, dir, "empty-flags.json", `{"version":1,"migrations":[]}`)
+	emptyCommand := writeManifest(t, dir, "empty-commands.json", `{"version":1,"migrations":[]}`)
+	invalid := writeManifest(t, dir, "invalid-commands.json", `{`)
+
+	var stdout, stderr bytes.Buffer
+	args := []string{
+		"compare",
+		"--current", snapshotPath,
+		"--base", snapshotPath,
+		"--stable", snapshotPath,
+		"--approved-flag-migrations", emptyFlag,
+		"--candidate-flag-migrations", emptyFlag,
+		"--approved-command-migrations", emptyCommand,
+		"--candidate-command-migrations", emptyCommand,
+	}
+	if exitCode := run(args, &stdout, &stderr); exitCode != 0 {
+		t.Fatalf("combined migration compare exit=%d stderr=%s", exitCode, stderr.String())
+	}
+	for _, test := range []struct {
+		name      string
+		approved  string
+		candidate string
+		want      string
+	}{
+		{"approved flag", invalid, emptyFlag, "read approved flag migrations"},
+		{"candidate flag", emptyFlag, invalid, "read candidate flag migrations"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			stdout.Reset()
+			stderr.Reset()
+			testArgs := []string{
+				"compare", "--current", snapshotPath, "--base", snapshotPath, "--stable", snapshotPath,
+				"--approved-flag-migrations", test.approved,
+				"--candidate-flag-migrations", test.candidate,
+				"--approved-command-migrations", emptyCommand,
+				"--candidate-command-migrations", emptyCommand,
+			}
+			if exitCode := run(testArgs, &stdout, &stderr); exitCode != 2 || !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("combined flag error exit=%d stderr=%s", exitCode, stderr.String())
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name      string
+		approved  string
+		candidate string
+		want      string
+	}{
+		{"approved", invalid, emptyCommand, "read approved command migrations"},
+		{"candidate", emptyCommand, invalid, "read candidate command migrations"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			stdout.Reset()
+			stderr.Reset()
+			testArgs := []string{
+				"compare", "--current", snapshotPath, "--base", snapshotPath, "--stable", snapshotPath,
+				"--approved-command-migrations", test.approved,
+				"--candidate-command-migrations", test.candidate,
+			}
+			if exitCode := run(testArgs, &stdout, &stderr); exitCode != 2 || !strings.Contains(stderr.String(), test.want) {
+				t.Fatalf("command manifest error exit=%d stderr=%s", exitCode, stderr.String())
+			}
+		})
+	}
+
+	stderr.Reset()
+	if exitCode := run([]string{
+		"compare", "--current", snapshotPath, "--base", snapshotPath,
+		"--approved-command-migrations", emptyCommand,
+	}, &stdout, &stderr); exitCode != 2 || !strings.Contains(stderr.String(), "provided together") {
+		t.Fatalf("one-sided command manifest exit=%d stderr=%s", exitCode, stderr.String())
+	}
+
+	if _, err := readCommandMigrationManifest(filepath.Join(dir, "missing.json")); err == nil {
+		t.Fatal("missing command migration manifest unexpectedly read")
+	}
+	if _, err := readCommandMigrationManifest(invalid); err == nil {
+		t.Fatal("invalid command migration manifest unexpectedly read")
+	}
+
+	pending := writeManifest(t, dir, "pending-command.json", commandMigrationManifestJSON("pending"))
+	consumed := writeManifest(t, dir, "consumed-command.json", commandMigrationManifestJSON("consumed"))
+	stderr.Reset()
+	if exitCode := run([]string{
+		"compare", "--current", snapshotPath, "--base", snapshotPath, "--stable", snapshotPath,
+		"--approved-command-migrations", pending,
+		"--candidate-command-migrations", consumed,
+	}, &stdout, &stderr); exitCode != 2 || !strings.Contains(stderr.String(), "validate interface migration lifecycle") {
+		t.Fatalf("command lifecycle error exit=%d stderr=%s", exitCode, stderr.String())
+	}
+}
+
 func TestCrossPlatformCoverageRunCompareRequiresBothReferencesForFlagMigrations(t *testing.T) {
 	dir := t.TempDir()
 	currentPath := writeSnapshot(t, dir, "current.json", commandSnapshot("dws"))
@@ -567,6 +663,33 @@ func flagMigrationManifestJSON(state string) string {
 }`, "STATE", state, 1)
 }
 
+func commandMigrationManifestJSON(state string) string {
+	return strings.Replace(`{
+  "version": 1,
+  "migrations": [{
+    "kind": "command_move",
+    "legacy": {
+      "command": "dws chat message old",
+      "before": {"present": true, "runnable": true},
+      "after": {"present": true, "runnable": true, "hidden": true}
+    },
+    "replacement": {
+      "command": "dws chat topic new",
+      "before": {"present": false},
+      "after": {"present": true, "runnable": true}
+    },
+    "schema": {
+      "product_id": "chat",
+      "source_tool_id": "chat.move",
+      "replacement_tool_id": "chat.move",
+      "parameters": []
+    },
+    "state": "STATE",
+    "reason": "reviewed command migration"
+  }]
+}`, "STATE", state, 1)
+}
+
 func hasFlag(flags []interfacesnapshot.Flag, name, flagType string) bool {
 	for _, flag := range flags {
 		if flag.Name == name && flag.Type == flagType {

docs/ci-pr-gates.md

@@ -184,11 +184,11 @@ candidate SHA。
 `check-interface-baseline.sh` 不再作为本地或 CI 的兼容性审批入口，也不能用于批准
 flag 迁移。
 
-Schema compatibility 使用同一组 base、stable、candidate refs 和同一份 base-owned flag
-migration ledger。merge-base-owned checker 分别规范化 merge-base 与 stable 的完整
-Schema，并让 candidate 对两份历史 contract 独立执行检查；它只把已通过 Interface
-lifecycle 的 exact rename 规范化到当前历史副本，不会维护第二份 allowlist，也不会
-放宽其他 Schema 历史字段。
+Schema compatibility 使用同一组 base、stable、candidate refs，以及 base-owned flag
+与 command migration ledgers。merge-base-owned checker 分别规范化 merge-base 与
+stable 的完整 Schema，并让 candidate 对两份历史 contract 独立执行检查；它只把已通过
+Interface lifecycle 的 exact rename、command move 或 flag extraction 规范化到当前历史
+副本，不会维护第二份 allowlist，也不会放宽其他 Schema 历史字段。
 
 For a release-seal branch that archives rendered fragments:
 

docs/cli-interface-flag-migrations.md

@@ -1,7 +1,9 @@
-# CLI flag 兼容迁移治理
+# CLI Help / Schema 兼容迁移治理
 
 本文定义一种受控迁移：保留旧 flag 的可执行兼容性，但把它从 Help 与 Agent Schema 中隐藏，并将新的规范 flag 设为唯一可见入口。迁移必须保持原 flag 的 requiredness：optional 只能迁到 optional，required 只能迁到 required。它只解决这一种精确变更，不是通用 breaking-change 豁免。
 
+同一套 base-owned lifecycle 也治理两类跨命令迁移：旧命令保留执行能力但从 Help / Schema 导航隐藏，并迁到新的公开命令路径；或把旧命令中的一个可选 flag 拆成新的专用命令。跨命令迁移只允许清单精确声明的 `command_became_hidden` / `flag_became_hidden` 及其 Schema 投影，不是通用 command-path breaking-change 豁免。
+
 同名 flag 的精确类型迁移属于另一类评审机制，只能进入
 `internal/interfacesnapshot/reviewed.go` 与 legacy smoke helper 的镜像表；flag rename
 只能进入本文的 JSON lifecycle ledger。一项迁移不得跨两种机制组合授权。
@@ -31,7 +33,7 @@ Smoke fixture，不参与迁移审批。
 同时提供 `--base` 与 `--stable`；核心 lifecycle 也拒绝缺失 stable 的非空清单，避免
 调用方因漏传历史参考而提前清理 consumed receipt。
 
-PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁用这套 base-owned helper 检查同一个已提交 candidate revision、merge-base 与 stable，candidate 不能通过修改自己的 Go 比较 helper 来放宽规则。candidate 中的清单只参与迁移状态流转，不能批准同一个 PR 引入的接口变化。首次引入本机制时，merge-base 尚无迁移解析器；bootstrap 会用 merge-base 已有的 modern Interface Snapshot 做不带豁免的普通比较，并只接受 candidate 中逐字匹配的空清单，不会让 candidate 新增的 comparator 决定本 PR 是否兼容。bootstrap 无法让旧 helper 证明新治理实现本身正确，因此本治理 PR 的新 parser、lifecycle、launcher 与 hostile tests 仍是必须由真人评审的受保护策略变更；它们合入后才成为后续 PR 的 base-owned authority。
+PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁用这套 base-owned helper 检查同一个已提交 candidate revision、merge-base 与 stable，candidate 不能通过修改自己的 Go 比较 helper 来放宽规则。candidate 中的清单只参与迁移状态流转，不能批准同一个 PR 引入的接口变化。首次引入 flag 机制时，merge-base 尚无迁移解析器；bootstrap 会用 merge-base 已有的 modern Interface Snapshot 做不带豁免的普通比较，并只接受 candidate 中逐字匹配的空 flag 清单。后续引入 command migration 扩展时，base 已拥有 flag comparator；bootstrap 仍只执行 base-owned 普通比较，不向旧 helper 传入新的 command ledger，因此允许随治理 PR 提交仍处于 before 的 pending 计划，也不会授予任何迁移豁免。bootstrap 无法让旧 helper 证明新治理实现本身正确，因此本治理 PR 的新 parser、lifecycle、launcher 与 hostile tests 仍是必须由真人评审的受保护策略变更；它们合入后才成为后续 PR 的 base-owned authority。
 
 这条边界保护比较规则和审批数据，不是任意代码沙箱。GitHub workflow / launcher 的变更仍由仓库保护规则和真人评审负责；candidate Cobra 构建也会执行 candidate 代码，因此对同一 runner 上的主动恶意代码，需要独立进程或文件系统隔离，不能把本门禁描述成已经解决。
 
@@ -39,10 +41,55 @@ PR merge-base 同时拥有快照生成器、比较器和已审批清单。门禁
 
 ```text
 scripts/policy/interface-migrations/approved-flag-migrations-v1.json
+scripts/policy/interface-migrations/approved-command-migrations-v1.json
 ```
 
 清单使用严格 JSON 解析：版本、字段名大小写、JSON 值类型、命令路径和 flag 名都必须精确；拒绝重复键、未知键、scalar `null` 与尾随 JSON 值，`reason` 不能为空；禁止 `*`、`?`、前缀规则或其他 wildcard。清单中的 `pending` 记录只记录已评审计划，并授权其精确列出的后续产品迁移；候选与 merge-base 仍必须精确匹配 `before`，不能授权同一个提交中的接口变化，也不能作为其他命令或参数的通配豁免。
 
+## 跨命令迁移原语
+
+`approved-command-migrations-v1.json` 只接受两种 `kind`：
+
+| kind | CLI after 状态 | Schema 允许的精确投影 |
+|---|---|---|
+| `command_move` | legacy 命令仍 runnable、由 visible 变 hidden；replacement 由 absent 变 visible runnable | 同一 stable tool identity 的 `primary_cli_path` 改到 replacement；只允许清单列出的参数改名，参数类型、property、requiredness、default 等必须等价 |
+| `flag_extraction` | legacy 命令保持 visible runnable；指定 legacy flag 仍可执行但由 visible 变 hidden；replacement 由 absent 变 visible runnable | source tool 只删除指定参数；replacement tool 必须位于精确的新路径，并保持 source 的 interface 与 safety identity；清单必须完整列出每个 source 参数到 replacement 参数或常量 property 的承接关系 |
+
+`command_move` 只能隐藏没有子命令的 legacy leaf，且 legacy 与 replacement
+不得互为祖先路径；整棵命令树的迁移需要单独设计逐叶治理，不能复用这一原语。
+稳定 Schema tool 可以继续接受普通的 optional 参数新增，但不得借路径迁移引入清单未登记的
+`required`、`cli_required` 或 `required_when` 参数；参数改名的目标也不得与历史
+Schema 中已有的其他参数重名，避免把两个历史参数静默合并。`flag_extraction` 只接受
+optional bool legacy flag，不能隐藏仍由 Cobra hard-required 的参数。它必须对 source tool
+的全部历史参数逐项声明：普通参数使用精确 `from` → `to`（同名也必须显式写出），且恰好
+一个与 legacy flag 同名的 `from` 使用 `replacement_constant`，不得同时声明 `to`；所有
+`from` 与 replacement 参数/property 目标必须唯一。legacy bool flag 的 `no_opt` 必须等于
+常量布尔值的字符串形式。v1 只治理 optional bool flag 的 `NoOpt=true` 激活分支，因此
+`replacement_constant.value` 与 legacy `no_opt` 都必须是 `true`；negative flag、默认即
+`true` 或固定 `false` 的语义不在本轮证明范围，必须另行设计，不能借本清单放行。
+
+`replacement_constant` 不是清单自报即可成立的例外。after 阶段的 Interface Snapshot
+必须从 replacement 命令的同一份框架运行时声明中捕获完全一致的 property/value，缺失、
+值不符或额外常量都会使 lifecycle 落入 partial。对于 #1054，`dws chat topic create`
+必须通过 `NewLeafCommand` 的 `ConstParams` 声明并实际注入
+`convThreadEnabled=true`；手写 `RunE` 固定值、Cobra annotation 或只改清单都不能提供这份
+同源证据，Snapshot 只读取 `corecmd` 包内私有注册表公开的只读副本。第一次向旧快照增加
+bool 常量证据属于 bootstrap；一旦任一历史快照已记录该
+证据，普通 Interface Compare 会持续要求 property/value 集合完全一致，因此 ledger 清理后
+删除、翻转或增加常量仍会阻塞。若 candidate 改动 command ledger，则
+`internal/corecmd/corecmd.go`、`internal/corecmd/interface_const_params.go` 与
+`internal/helpers/leaf.go` 三份执行/证据桥必须保持 base Git blob 不变；框架演进必须先用
+独立 PR 合入，不能和产品消费混在一起。
+
+replacement 必须保留 source 已发布的 dry-run 能力：历史 `dry_run` 非空时不得删除或改值；
+历史未声明时允许 replacement 新增 dry-run。这与普通 Schema 兼容规则保持同一单调边界。
+
+两种迁移都要求旧 argv 继续可执行。删除旧命令、删除旧 flag、把 legacy 改成 non-runnable、改变未登记的历史参数、改变 interface / safety，或只完成部分 before → after 转换都会 fail closed。命令别名会先规范到 reference 的 canonical path，但清单本身仍只能记录精确 canonical 命令，不能用 alias 或前缀扩大授权。
+
+跨命令清单复用下文同一套 `pending → consumed → cleanup` 生命周期。治理 PR 只能新增 `pending` 且产品 surface 必须仍是 before；后续产品 PR 才能一次性切到 after 并改为 `consumed`。candidate 新增的 pending 记录不能批准自己的改动。
+
+当前首批 pending 记录覆盖 `chat topic` 收口：`chat group create --thread` 拆到 `chat topic create`，以及 `chat message list-topic-replies` / `forward-topic` 迁到对应的 `chat topic` 命令。前一条完整登记 `name` / `type` / `users` 的同名承接，以及 `thread` → `convThreadEnabled=true` 的常量承接。产品 PR 消费这些记录时只能把三条 `state` 改为 `consumed`，不得改写其 before、after、Schema mapping、constant 或 reason。
+
 ## 两阶段迁移与回执清理
 
 每条迁移以 `(command, legacy flag, canonical flag)` 为唯一精确键，并经历以下生命周期：

docs/rfc-skill-installation-and-upgrade.md

@@ -54,8 +54,8 @@ DWS 对任何外部实现的持续兼容义务。后续设计以 DWS 自身约
 
 | 模式 | Agent 目录布局 | 选择方式 |
 |---|---|---|
-| multi（默认） | `<agent-home>/dingtalk-*/` 与必选 `dingtalk-shared/` | 默认；`dws skill setup --mode multi` |
-| mono（兼容） | `<agent-home>/dws/` | `dws skill setup --mode mono` 或安装器的 mono opt-in |
+| multi（默认） | canonical `~/.agents/skills/dingtalk-*/`；非 universal Agent 使用链接或复制兼容层 | 默认；`dws skill setup --mode multi` |
+| mono（兼容） | canonical `~/.agents/skills/dws/`；非 universal Agent 使用链接或复制兼容层 | `dws skill setup --mode mono` 或安装器的 mono opt-in |
 
 模式切换通过重新执行 setup 完成。安装 multi 前备份并移除 mono 的 `dws/`；安装
 mono 前只备份并移除能够证明由 DWS 管理的 multi 目录。两个方向都不提供隐式、
@@ -140,10 +140,26 @@ Agent 仍只需以 `SKILL.md` 发现和加载 Skill；统一元数据位于 Agen
 
 ## 8. Upgrade 与恢复语义
 
-升级器对每个 Agent 目标执行：
+升级器始终先发布 `~/.agents/skills` canonical 集合。固定兼容注册表中被分类为
+universal 的 Agent 不再保留 Agent 私有副本；检测到的
+非 universal Agent（如 Claude、OpenClaw、Hermes、Windsurf）使用指向 canonical
+的目录链接：npm 与 PowerShell 安装器在 Windows 上创建 junction，`dws upgrade` /
+`dws skill setup` 创建符号链接（`os.Symlink`）。链接不可用时回退为内容完整的
+直接复制，包括未开启开发者模式、因而无法创建符号链接的 Windows。
+自定义 `CODEX_HOME`、`CLAUDE_CONFIG_DIR`、`HERMES_HOME`、`AUTOHAND_HOME`、
+`GROK_HOME`、`VIBE_HOME`、`XDG_CONFIG_HOME` 与 OpenClaw 历史目录 `.clawdbot`、
+`.moltbot` 必须按 Agent 实际优先级解析。
 
-- 先探测具体 Agent home；只在没有任何具体 Agent 时使用 `~/.agents/skills` 通用 fallback；
-- 具体 Agent 安装成功后，将 `~/.agents/skills` 中旧的 DWS 受管副本可恢复地迁入备份，避免 Codex 等同时扫描两个根目录时重复发现同名 Skill；
+Agent 兼容矩阵以 `vercel-labs/skills` 的 `agents.ts` 与 `installer.ts`（基准提交
+`c6f69c6`）为契约：76 个 ID 必须完整登记，其中 19 个 universal、57 个
+non-universal。`eve`、`promptscript` 没有全局目录，因此全局安装时跳过；多个 Agent
+解析到同一个 XDG 目录时按最终绝对路径去重（Windows 大小写不敏感）。DWS 额外支持
+Qoderwork（按 non-universal Agent 建立兼容链接）；旧版使用的 `.github/skills`、
+`.amp/skills`、`.cline/skills` 与
+`.windsurf/skills` 仅作为可恢复迁移清理目标，不计入上游 Agent 枚举。
+对 universal Agent，上游 installer 的 global 模式明确选择 canonical 并跳过
+Agent 私有 global 目录；注册表中的 `globalSkillsDir` 仍用于识别和退役历史 native
+路径，不作为 universal symlink 模式的发布目标。
 
 1. 只读计算对面布局、过期受管 Skill 和同名官方 Skill；
 2. 在目标文件系统的 staging 中复制完整新集合；
@@ -151,6 +167,14 @@ Agent 仍只需以 `SKILL.md` 发现和加载 Skill；统一元数据位于 Agen
 4. 逐项发布 staging；任一发布失败时删除已发布的新目录，并逆序恢复该目标的全部旧目录；
 5. 仅在没有目标失败且至少一个目标成功时更新状态快照。
 
+旧集合可能位于外部卷或自定义 Agent 根，而备份固定写入
+`~/.dws/skill-backups`。因此备份与反向恢复统一采用 rename-first：同卷直接原子
+rename；遇到跨文件系统错误时，在目标所在文件系统创建临时 staging，词法复制并
+保留目录/文件权限、普通文件、符号链接及 dangling symlink，校验路径类型、目录项、
+文件大小与 SHA256、链接目标后，再将 staging 原子 rename 为正式目标。正式目标
+再次校验成功后才删除源路径。复制、校验或发布失败时保留源并清理 staging；源删除
+失败时允许源与正式目标同时存在，但必须返回明确错误，不能报告成功。
+
 Go upgrade 当前提供 **单 Agent 目标级事务恢复**：复制失败发生在旧目录移动前；
 备份中途失败会恢复此前已移动的目录；发布中途失败会恢复该目标的完整旧集合。不同
 Agent 目标仍彼此独立，一个目标失败不会回滚此前已经成功升级的其他目标，这与
@@ -159,11 +183,31 @@ Agent 目标仍彼此独立，一个目标失败不会回滚此前已经成功
 ## 9. 备份合同
 
 - 路径：`~/.dws/skill-backups/<UTC 时间戳>/...`；
-- 主要操作：同一文件系统内使用 rename 移动；
+- 主要操作：同一文件系统内使用 rename 移动；跨文件系统使用目标卷 staging 的
+  copy → verify → publish → remove 回退；
 - 失败语义：备份失败时原目录保持不变，目标安装失败；
+- 恢复语义：反向恢复使用相同回退；若删除备份源失败，原路径和备份可同时存在，
+  但恢复必须失败并明确提示两份均被保留；
 - 可见性：计划和执行日志显示原路径与备份路径；
 - 保留策略：自动修剪，仅保留最近 5 批。
 
+跨卷回退只有 staging → 正式目标的发布 rename 是原子的，整次迁移不是跨文件系统
+原子事务；该边界由“发布前不删源、发布后再次校验、删除失败保留两份”补偿。Shell
+入口继续使用系统 `mv` 的跨文件系统复制/删除能力；Go、npm 与 PowerShell 显式实现
+上述验证和失败合同。
+
+原子 no-replace 发布（Linux `RENAME_NOREPLACE`、Darwin `RENAME_EXCL`）依赖底层文件
+系统支持：`rename(2)` 只列出 ext4、btrfs、tmpfs 与 cifs，因此 NFS、FUSE 与
+overlayfs 家目录会以 `EINVAL` 拒绝该 flag。这些文件系统不得让安装整体失败，而是降级
+为原子占位发布：目录目标用 `mkdir` 认领（已占用即 `EEXIST`，认领期间目标始终被本事务
+持有，源子项逐个移入认领目录，最终以 rename 覆盖仅属于本事务的空认领或直接移入）；
+普通文件目标用硬链接占位（同样以 `EEXIST` 拒绝已占用路径）后删除源。任何一步失败都会
+回迁已移动的子项并只撤销本事务的占位，被并发创建的对象（文件、符号链接或目录）既不会
+被覆盖，也不会被链接进内部。逐子项移动路径不是全量原子可见（降级文件系统上的可接受
+边界），但不覆盖契约在所有平台保持不变。Windows `MoveFile` 本身即拒绝已存在的目标，
+无需降级。npm 与 Shell 安装面遵循同一占位模型：目录用 `mkdir`/子项移动，链接直接在
+目标路径创建（symlink(2) 原子拒绝已占用路径）。
+
 备份是安装安全机制，不等于独立 rollback 产品。需要切回 mono 时重新运行
 `dws skill setup --mode mono`。
 
@@ -192,6 +236,7 @@ setup 在未显式指定 `--source` 时的本地回退缓存。
 | `scripts/install.ps1` | multi | 任一检测到的目标失败则脚本非零 |
 | `scripts/install-skills.sh` | multi | 任一检测到的目标失败则脚本非零 |
 | npm `install.js` | multi | 任一检测到的目标失败则 postinstall 失败 |
+| `scripts/install-event.sh` / `install-devapp.*` | 产品 multi 子集 | 同样使用 canonical 与 Agent 兼容层 |
 
 Homebrew 不直接向 Agent home 铺设 Skill；安装 CLI 后由 setup 执行相同流程。
 
@@ -209,6 +254,12 @@ Homebrew 不直接向 Agent home 铺设 Skill；安装 CLI 后由 setup 执行
 - 复制失败不留下 Agent 可见的残缺官方目录；
 - 普通 upgrade 恢复被删除的预制 Skill，并安装新增官方 Skill；
 - Windows、macOS、Linux 的路径和覆盖率门禁；
+- symlinked parent、npm/PowerShell 的 Windows junction、`dws upgrade` /
+  `dws skill setup` 的符号链接、链接失败复制回退与 broken link 修复；
+- Claude/Codex/Hermes 自定义根目录及 OpenClaw 历史目录优先级；
+- `CLAUDE_CONFIG_DIR`、`HERMES_HOME`、`XDG_CONFIG_HOME` 等自定义根跨文件系统时的
+  正向备份、反向恢复、普通链接及 dangling symlink 词法保留；
+- copy、verify、publish、remove 各阶段故障，以及非跨设备权限错误不得进入复制回退；
 - npm、Shell、PowerShell 与包管理器安装冒烟。
 
 ## 13. 后续演进

go.mod

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

internal/app/event_command.go

@@ -403,7 +403,7 @@ SIGTERM、关 stdin，或先用 dws event stop <subscribe_id> --dry-run 预览
 			Selection: contract.SelectionSpec{
 				AgentSummary: "消费 OA、群生命周期或需要底层控制的个人事件流；Agent 通常使用 --flatten 输出 NDJSON",
 				UseWhen: []string{
-					"需要监听六个公开 OA 审批任务/实例 EventKey 中的一个或多个事件",
+					"需要监听七个公开 OA 审批任务/实例 EventKey 中的一个或多个事件",
 					"需要监听指定群的标题变更、成员进退群或群解散事件",
 					"用户显式给出原始 EventKey、Filter DSL、subscribe_id，要求原始 transport envelope，或需要普通 IM facade 不提供的高级多事件控制",
 				},

internal/app/event_personal_attempts_test.go

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

internal/app/event_personal_oa_test.go

@@ -61,6 +61,13 @@ func TestPersonalOAEventListAndSchemaCommands(t *testing.T) {
 				"process_code", "title", "status", "create_time", "event_time",
 			},
 		},
+		{
+			eventKey: personal.EventOAApprovalInstanceCC,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "event_time",
+			},
+		},
 		{
 			eventKey: personal.EventOAApprovalInstanceTerminated,
 			properties: []string{
@@ -161,6 +168,7 @@ func TestPersonalOAEventConsumeDryRunAndValidation(t *testing.T) {
 		personal.EventOAApprovalTaskFinished,
 		personal.EventOAApprovalTaskRedirected,
 		personal.EventOAApprovalInstanceStarted,
+		personal.EventOAApprovalInstanceCC,
 		personal.EventOAApprovalInstanceTerminated,
 		personal.EventOAApprovalInstanceFinished,
 	}
@@ -414,6 +422,7 @@ func TestPersonalOAMultiConsumeCreatesIndependentAllSubscriptionsOnSharedBus(t *
 		personal.EventOAApprovalTaskFinished,
 		personal.EventOAApprovalTaskRedirected,
 		personal.EventOAApprovalInstanceStarted,
+		personal.EventOAApprovalInstanceCC,
 		personal.EventOAApprovalInstanceTerminated,
 		personal.EventOAApprovalInstanceFinished,
 	}

internal/app/param_alias_e2e_test.go

@@ -51,7 +51,38 @@ func (c *paramAliasCaptureCaller) CallTool(_ context.Context, server, tool strin
 func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string {
 	switch tool {
 	case "list_calendar_events":
-		return `{"result":{"events":[]}}`
+		return `{"success":true,"result":{"events":[],"hasMore":false,"nextCursor":""}}`
+	case "get_calendar_detail":
+		return c.paramAliasCalendarDetailResponse()
+	case "get_calendar_participants":
+		return `{"success":true,"result":{"participants":[{"userId":"fixture-user","displayName":"Fixture User"},{"userId":"user-2","displayName":"User Two"}]}}`
+	case "search_calendar":
+		return `{"success":true,"result":{"calendars":[]}}`
+	case "search_rooms":
+		return `{"success":true,"result":{"rooms":[]}}`
+	case "query_available_meeting_room":
+		return `{"success":true,"result":{"rooms":[],"hasMore":false}}`
+	case "list_meeting_room_groups":
+		return `{"success":true,"result":{"groups":[]}}`
+	case "query_busy_status":
+		return `{"success":true,"result":[]}`
+	case "list_suggested_event_times":
+		return `{"success":true,"result":{"recommendEventTimes":[]}}`
+	case "create_calendar_event":
+		return `{"success":true,"result":{"eventId":"event-1"}}`
+	case "update_calendar_event", "delete_calendar_event", "add_calendar_participant", "remove_calendar_participant":
+		return `{"success":true}`
+	case "respond":
+		status := "accepted"
+		if call := c.lastParamAliasCall(); call != nil {
+			if value, ok := call.args["responseStatus"].(string); ok && value != "" {
+				status = value
+			}
+		}
+		encoded, _ := json.Marshal(map[string]any{"success": true, "result": map[string]any{"responseStatus": status}})
+		return string(encoded)
+	case "get_current_user_profile":
+		return `{"success":true,"result":{"userId":"user-1","name":"Fixture Current User"}}`
 	case "query_records":
 		return `{"success":true,"status":"success","error":{},"data":{}}`
 	case "search_mail_users":
@@ -127,6 +158,41 @@ func (c *paramAliasCaptureCaller) paramAliasResponseForTool(tool string) string
 	}
 }
 
+func (c *paramAliasCaptureCaller) lastParamAliasCall() *paramAliasToolCall {
+	if len(c.calls) == 0 {
+		return nil
+	}
+	return &c.calls[len(c.calls)-1]
+}
+
+func (c *paramAliasCaptureCaller) paramAliasCalendarDetailResponse() string {
+	event := map[string]any{
+		"eventId":       "event-1",
+		"summary":       "Fixture Meeting",
+		"description":   "fixture description",
+		"startDateTime": "2026-03-10T09:00:00+08:00",
+		"endDateTime":   "2026-03-10T10:00:00+08:00",
+	}
+	for _, call := range c.calls {
+		switch call.tool {
+		case "create_calendar_event", "update_calendar_event":
+			for _, key := range []string{"eventId", "summary", "description", "startDateTime", "endDateTime", "timeZone", "location", "freeBusy"} {
+				if value, ok := call.args[key]; ok {
+					event[key] = value
+				}
+			}
+		case "respond":
+			if value, ok := call.args["responseStatus"]; ok {
+				event["responseStatus"] = value
+			}
+		case "delete_calendar_event":
+			event["status"] = "cancelled"
+		}
+	}
+	encoded, _ := json.Marshal(map[string]any{"success": true, "result": event})
+	return string(encoded)
+}
+
 func (*paramAliasCaptureCaller) Format() string { return "json" }
 func (*paramAliasCaptureCaller) DryRun() bool   { return false }
 func (*paramAliasCaptureCaller) Fields() string { return "" }

internal/app/param_alias_payload_equivalence_test.go

@@ -5,6 +5,8 @@ package app
 
 import (
 	"errors"
+	"os"
+	"os/exec"
 	"reflect"
 	"strings"
 	"testing"
@@ -17,6 +19,8 @@ import (
 const (
 	appFixtureCurrentDOpenID  = "DAAAAAAAAAAAiE"
 	appFixtureCurrentDOpenID2 = "DAQEBAQEBAQEiE"
+
+	paramAliasCalendarPayloadChildEnv = "DWS_TEST_CALENDAR_PARAM_ALIAS_PAYLOAD_CHILD"
 )
 
 // paramAliasCompleteCommands is deliberately keyed by the exact reviewed
@@ -46,7 +50,37 @@ var paramAliasCompleteCommands = map[string][]string{
 	"aitable workflow run":                     {"aitable", "workflow", "run", "--base-id", "base-1", "--workflow-id", "workflow-1", "--table-id", "table-1", "--record-ids", "record-1", "--yes"},
 	"attendance check result":                  {"attendance", "check", "result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
 	"attendance +check-result":                 {"attendance", "+check-result", "--users", "user-1,user-2", "--start", "2026-03-01", "--end", "2026-03-02"},
+	"calendar +agenda":                         {"calendar", "+agenda", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
+	"calendar +attendee-list":                  {"calendar", "+attendee-list", "--event", "event-1", "--calendar-id", "primary"},
+	"calendar +book":                           {"calendar", "+book", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--with", "Fixture User", "--yes"},
+	"calendar +book-search":                    {"calendar", "+book-search", "--query", "fixture"},
+	"calendar +cancel-event":                   {"calendar", "+cancel-event", "--event", "event-1", "--yes"},
+	"calendar +conflicts":                      {"calendar", "+conflicts", "--in-days", "1"},
+	"calendar +create":                         {"calendar", "+create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--desc", "fixture description", "--attendees", "user-1,user-2", "--rooms", "room-1,room-2", "--calendar-id", "primary", "--yes"},
+	"calendar +free":                           {"calendar", "+free", "--who", "Fixture User", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"},
+	"calendar +free-slots":                     {"calendar", "+free-slots", "--from", "9", "--to", "18", "--in-days", "1"},
+	"calendar +freebusy":                       {"calendar", "+freebusy", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"},
+	"calendar +get":                            {"calendar", "+get", "--event", "event-1", "--calendar-id", "primary"},
+	"calendar +invite":                         {"calendar", "+invite", "--event", "event-1", "--with", "Fixture User", "--yes"},
+	"calendar +my-free":                        {"calendar", "+my-free", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"},
+	"calendar +reschedule":                     {"calendar", "+reschedule", "--event", "event-1", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--yes"},
+	"calendar +room-find":                      {"calendar", "+room-find", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--room-name", "Fixture Room", "--group-id", "group-1", "--page", "1", "--limit", "7"},
+	"calendar +room-groups":                    {"calendar", "+room-groups", "--page", "1", "--limit", "7"},
+	"calendar +room-search":                    {"calendar", "+room-search", "--room-name", "Fixture Room"},
+	"calendar +rsvp":                           {"calendar", "+rsvp", "--event", "event-1", "--status", "accept", "--calendar-id", "primary", "--yes"},
+	"calendar +search-event":                   {"calendar", "+search-event", "--query", "fixture", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--calendar-id", "primary", "--cursor", "cursor-1", "--limit", "7"},
+	"calendar +suggest-time":                   {"calendar", "+suggest-time", "--with", "Fixture User", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"},
+	"calendar +suggestion":                     {"calendar", "+suggestion", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"},
+	"calendar +update":                         {"calendar", "+update", "--event", "event-1", "--title", "Fixture Updated Meeting", "--desc", "fixture updated description", "--start", "2026-03-10T10:00:00+08:00", "--end", "2026-03-10T11:00:00+08:00", "--add-attendees", "user-2", "--remove-attendees", "user-1", "--yes"},
+	"calendar busy search":                     {"calendar", "busy", "search", "--users", "user-1,user-2", "--rooms", "room-1,room-2", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00"},
+	"calendar event create":                    {"calendar", "event", "create", "--title", "Fixture Meeting", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T10:00:00+08:00", "--remind-minutes", "15", "--timezone", "Asia/Shanghai", "--rooms", "room-1,room-2"},
 	"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"},
+	"calendar event respond":                   {"calendar", "event", "respond", "--id", "event-1", "--status", "accepted"},
+	"calendar event suggest":                   {"calendar", "event", "suggest", "--users", "user-1,user-2", "--duration", "30", "--start", "2026-03-10T09:00:00+08:00", "--end", "2026-03-10T18:00:00+08:00", "--timezone", "Asia/Shanghai"},
+	"calendar event update":                    {"calendar", "event", "update", "--id", "event-1", "--timezone", "Asia/Shanghai"},
+	"calendar room add":                        {"calendar", "room", "add", "--event", "event-1", "--rooms", "room-1,room-2"},
+	"calendar room delete":                     {"calendar", "room", "delete", "--event", "event-1", "--rooms", "room-1,room-2"},
+	"calendar room search":                     {"calendar", "room", "search", "--room-name", "Fixture Room", "--group-id", "group-1", "--start", "2027-03-10T09:00:00+08:00", "--end", "2027-03-10T10:00:00+08:00", "--page", "1", "--limit", "7"},
 	"chat +chat-messages":                      {"chat", "+chat-messages", "--group", "fixture-conversation"},
 	"chat +chat-add-bot":                       {"chat", "+chat-add-bot", "--id", "fixture-conversation", "--robot-code", "robot-1", "--yes"},
 	"chat +chat-audit-join":                    {"chat", "+chat-audit-join", "--group", "fixture-conversation", "--record-id", "7", "--applicant", "user-1", "--inviter", "user-2", "--status", "AuditApprove", "--yes"},
@@ -566,6 +600,108 @@ var paramAliasRepresentativePayloadCases = map[string]bool{
 	paramAliasPayloadCaseKey("report list", "from-date"):                             true, // date-range concept alias
 }
 
+// paramAliasCalendarPayloadCases keeps the full reviewed Calendar expansion
+// separate from the long-lived app-c race process. Each case still executes
+// both canonical and alias argv through the real PreParse/Cobra path and
+// compares the final captured transport calls; the owning top-level test runs
+// these allocations in a short-lived race-instrumented subprocess so all Root
+// registrations are released together when that process exits.
+var paramAliasCalendarPayloadCases = map[string]bool{
+	paramAliasPayloadCaseKey("calendar +agenda", "from"):                    true,
+	paramAliasPayloadCaseKey("calendar +agenda", "to"):                      true,
+	paramAliasPayloadCaseKey("calendar +agenda", "max-results"):             true,
+	paramAliasPayloadCaseKey("calendar +agenda", "next-cursor"):             true,
+	paramAliasPayloadCaseKey("calendar +agenda", "calendar-book-id"):        true,
+	paramAliasPayloadCaseKey("calendar +attendee-list", "event-id"):         true,
+	paramAliasPayloadCaseKey("calendar +attendee-list", "calendar-book-id"): true,
+	paramAliasPayloadCaseKey("calendar +book", "summary"):                   true,
+	paramAliasPayloadCaseKey("calendar +book", "attendee-names"):            true,
+	paramAliasPayloadCaseKey("calendar +book-search", "keyword"):            true,
+	paramAliasPayloadCaseKey("calendar +book-search", "search"):             true,
+	paramAliasPayloadCaseKey("calendar +book-search", "name"):               true,
+	paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"):          true,
+	paramAliasPayloadCaseKey("calendar +cancel-event", "id"):                true,
+	paramAliasPayloadCaseKey("calendar +free", "name"):                      true,
+	paramAliasPayloadCaseKey("calendar +free-slots", "start-hour"):          true,
+	paramAliasPayloadCaseKey("calendar +free-slots", "end-hour"):            true,
+	paramAliasPayloadCaseKey("calendar +free-slots", "day-offset"):          true,
+	paramAliasPayloadCaseKey("calendar +freebusy", "user-ids"):              true,
+	paramAliasPayloadCaseKey("calendar +freebusy", "room-ids"):              true,
+	paramAliasPayloadCaseKey("calendar +freebusy", "room-id"):               true,
+	paramAliasPayloadCaseKey("calendar +my-free", "from"):                   true,
+	paramAliasPayloadCaseKey("calendar +my-free", "to"):                     true,
+	paramAliasPayloadCaseKey("calendar +invite", "id"):                      true,
+	paramAliasPayloadCaseKey("calendar +invite", "participant-names"):       true,
+	paramAliasPayloadCaseKey("calendar +reschedule", "id"):                  true,
+	paramAliasPayloadCaseKey("calendar +reschedule", "from"):                true,
+	paramAliasPayloadCaseKey("calendar +reschedule", "to"):                  true,
+	paramAliasPayloadCaseKey("calendar +room-groups", "page-size"):          true,
+	paramAliasPayloadCaseKey("calendar +room-groups", "page-index"):         true,
+	paramAliasPayloadCaseKey("calendar +room-search", "query"):              true,
+	paramAliasPayloadCaseKey("calendar +suggest-time", "duration-minutes"):  true,
+	paramAliasPayloadCaseKey("calendar +suggest-time", "attendee-names"):    true,
+	paramAliasPayloadCaseKey("calendar +conflicts", "day-offset"):           true,
+	paramAliasPayloadCaseKey("calendar busy search", "room-id"):             true,
+	paramAliasPayloadCaseKey("calendar event create", "reminder-minutes"):   true,
+	paramAliasPayloadCaseKey("calendar event create", "tz"):                 true,
+	paramAliasPayloadCaseKey("calendar event create", "room-id"):            true,
+	paramAliasPayloadCaseKey("calendar event respond", "response-status"):   true,
+	paramAliasPayloadCaseKey("calendar event suggest", "duration-minutes"):  true,
+	paramAliasPayloadCaseKey("calendar event update", "tz"):                 true,
+	paramAliasPayloadCaseKey("calendar room add", "room-id"):                true,
+	paramAliasPayloadCaseKey("calendar room delete", "room-id"):             true,
+	paramAliasPayloadCaseKey("calendar room search", "room-group-id"):       true,
+	paramAliasPayloadCaseKey("calendar +create", "summary"):                 true,
+	paramAliasPayloadCaseKey("calendar +create", "description"):             true,
+	paramAliasPayloadCaseKey("calendar +create", "user-ids"):                true,
+	paramAliasPayloadCaseKey("calendar +create", "room-ids"):                true,
+	paramAliasPayloadCaseKey("calendar +create", "room-id"):                 true,
+	paramAliasPayloadCaseKey("calendar +create", "calendar-book-id"):        true,
+	paramAliasPayloadCaseKey("calendar +create", "to"):                      true,
+	paramAliasPayloadCaseKey("calendar +create", "from"):                    true,
+	paramAliasPayloadCaseKey("calendar +get", "event-id"):                   true,
+	paramAliasPayloadCaseKey("calendar +get", "calendar-book-id"):           true,
+	paramAliasPayloadCaseKey("calendar +room-find", "from"):                 true,
+	paramAliasPayloadCaseKey("calendar +room-find", "to"):                   true,
+	paramAliasPayloadCaseKey("calendar +room-find", "page-size"):            true,
+	paramAliasPayloadCaseKey("calendar +room-find", "page-index"):           true,
+	paramAliasPayloadCaseKey("calendar +room-find", "room-group-id"):        true,
+	paramAliasPayloadCaseKey("calendar +room-find", "query"):                true,
+	paramAliasPayloadCaseKey("calendar +rsvp", "event-id"):                  true,
+	paramAliasPayloadCaseKey("calendar +rsvp", "response-status"):           true,
+	paramAliasPayloadCaseKey("calendar +search-event", "keyword"):           true,
+	paramAliasPayloadCaseKey("calendar +search-event", "from"):              true,
+	paramAliasPayloadCaseKey("calendar +search-event", "to"):                true,
+	paramAliasPayloadCaseKey("calendar +search-event", "next-cursor"):       true,
+	paramAliasPayloadCaseKey("calendar +search-event", "max-results"):       true,
+	paramAliasPayloadCaseKey("calendar +suggestion", "user-ids"):            true,
+	paramAliasPayloadCaseKey("calendar +suggestion", "duration-minutes"):    true,
+	paramAliasPayloadCaseKey("calendar +suggestion", "from"):                true,
+	paramAliasPayloadCaseKey("calendar +suggestion", "to"):                  true,
+	paramAliasPayloadCaseKey("calendar +suggestion", "tz"):                  true,
+	paramAliasPayloadCaseKey("calendar +update", "event-id"):                true,
+	paramAliasPayloadCaseKey("calendar +update", "from"):                    true,
+	paramAliasPayloadCaseKey("calendar +update", "summary"):                 true,
+	paramAliasPayloadCaseKey("calendar +update", "description"):             true,
+	paramAliasPayloadCaseKey("calendar +update", "add-user-ids"):            true,
+	paramAliasPayloadCaseKey("calendar +update", "remove-user-ids"):         true,
+}
+
+// paramAliasCalendarConfirmationCases selects one newly reviewed alias for
+// every Calendar Shortcut whose runtime contract requires user confirmation.
+// The complete Calendar matrix proves confirmed canonical/alias payload
+// equality; these representatives additionally prove semantic normalization
+// cannot cross the confirmation boundary before the first transport call.
+var paramAliasCalendarConfirmationCases = map[string]bool{
+	paramAliasPayloadCaseKey("calendar +book", "summary"):          true,
+	paramAliasPayloadCaseKey("calendar +cancel-event", "event-id"): true,
+	paramAliasPayloadCaseKey("calendar +create", "summary"):        true,
+	paramAliasPayloadCaseKey("calendar +invite", "id"):             true,
+	paramAliasPayloadCaseKey("calendar +reschedule", "from"):       true,
+	paramAliasPayloadCaseKey("calendar +rsvp", "response-status"):  true,
+	paramAliasPayloadCaseKey("calendar +update", "event-id"):       true,
+}
+
 func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepresentativeFinalPayloads(t *testing.T) {
 	concepts, err := cli.LoadParamConcepts()
 	if err != nil {
@@ -599,28 +735,7 @@ func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepres
 		}
 		executedRepresentatives[caseKey] = true
 		t.Run(fixture.Command+"/"+fixture.Emitted, func(t *testing.T) {
-
-			canonicalCaller := &paramAliasCaptureCaller{}
-			_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
-			if canonicalErr != nil {
-				t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
-			}
-			if len(canonicalCaller.calls) == 0 {
-				t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs)
-			}
-
-			aliasCaller := &paramAliasCaptureCaller{}
-			ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
-			if aliasErr != nil {
-				t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
-			}
-			if ctx == nil {
-				t.Fatal("complete alias command skipped PreParse")
-			}
-			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)
-			}
+			assertParamAliasFinalPayloadEquivalent(t, fixture.Command, canonicalArgs, aliasArgs)
 		})
 	}
 
@@ -650,6 +765,118 @@ func TestCrossPlatformCoverageReviewedParamAliasesHaveCompleteTemplatesAndRepres
 	}
 }
 
+func TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
+	if os.Getenv(paramAliasCalendarPayloadChildEnv) != "1" {
+		command := exec.Command(
+			os.Args[0],
+			"-test.run=^TestCrossPlatformCoverageReviewedCalendarParamAliasesReachCanonicalEquivalentFinalPayloads$",
+			"-test.count=1",
+			"-test.timeout=5m",
+		)
+		command.Env = append(os.Environ(), paramAliasCalendarPayloadChildEnv+"=1")
+		output, err := command.CombinedOutput()
+		if err != nil {
+			t.Fatalf("Calendar param-alias payload subprocess failed: %v\n%s", err, strings.TrimSpace(string(output)))
+		}
+		return
+	}
+
+	concepts, err := cli.LoadParamConcepts()
+	if err != nil {
+		t.Fatalf("LoadParamConcepts() error = %v", err)
+	}
+
+	executed := make(map[string]bool)
+	executedConfirmation := make(map[string]bool)
+	for _, fixture := range concepts.Fixture {
+		caseKey := paramAliasPayloadCaseKey(fixture.Command, fixture.Emitted)
+		if !paramAliasCalendarPayloadCases[caseKey] {
+			continue
+		}
+		executed[caseKey] = true
+		fixture := fixture
+		t.Run(fixture.Command+"/"+fixture.Emitted, func(t *testing.T) {
+			complete, ok := paramAliasCompleteCommand(fixture.Command, fixture.Expect)
+			if !ok {
+				t.Fatal("reviewed Calendar alias has no complete-command E2E template")
+			}
+			canonicalArgs := append([]string(nil), complete...)
+			aliasArgs, replacements := replaceLongFlag(canonicalArgs, fixture.Expect, fixture.Emitted)
+			if replacements != 1 {
+				t.Fatalf("complete Calendar command must contain canonical --%s exactly once; replacements=%d args=%v", fixture.Expect, replacements, canonicalArgs)
+			}
+			assertParamAliasFinalPayloadEquivalent(t, fixture.Command, canonicalArgs, aliasArgs)
+			if paramAliasCalendarConfirmationCases[caseKey] {
+				executedConfirmation[caseKey] = true
+				assertParamAliasCannotBypassConfirmation(t, aliasArgs)
+			}
+		})
+	}
+
+	for caseKey := range paramAliasCalendarPayloadCases {
+		if !executed[caseKey] {
+			t.Errorf("Calendar final-payload case %q has no active reviewed fixture", caseKey)
+		}
+	}
+	if len(executed) != len(paramAliasCalendarPayloadCases) {
+		t.Fatalf("Calendar final-payload coverage = %d, want %d", len(executed), len(paramAliasCalendarPayloadCases))
+	}
+	for caseKey := range paramAliasCalendarConfirmationCases {
+		if !executedConfirmation[caseKey] {
+			t.Errorf("Calendar confirmation case %q has no active reviewed fixture", caseKey)
+		}
+	}
+	if len(executedConfirmation) != len(paramAliasCalendarConfirmationCases) {
+		t.Fatalf("Calendar confirmation coverage = %d, want %d", len(executedConfirmation), len(paramAliasCalendarConfirmationCases))
+	}
+}
+
+func assertParamAliasCannotBypassConfirmation(t *testing.T, aliasArgs []string) {
+	t.Helper()
+	unconfirmedArgs, removals := removeExactArg(aliasArgs, "--yes")
+	if removals != 1 {
+		t.Fatalf("confirmation template must contain --yes exactly once; removals=%d args=%v", removals, aliasArgs)
+	}
+
+	caller := &paramAliasCaptureCaller{}
+	ctx, err := executeParamAliasPayloadE2E(t, caller, unconfirmedArgs...)
+	if ctx == nil {
+		t.Fatal("unconfirmed Calendar alias command skipped PreParse")
+	}
+	var appErr *apperrors.Error
+	if !errors.As(err, &appErr) || appErr.Reason != "confirmation_required" {
+		t.Fatalf("unconfirmed Calendar alias command error = %#v, want confirmation_required\nargs=%v", err, unconfirmedArgs)
+	}
+	if len(caller.calls) != 0 {
+		t.Fatalf("unconfirmed Calendar alias crossed the transport boundary: args=%v calls=%#v", unconfirmedArgs, caller.calls)
+	}
+}
+
+func assertParamAliasFinalPayloadEquivalent(t *testing.T, command string, canonicalArgs, aliasArgs []string) {
+	t.Helper()
+	canonicalCaller := &paramAliasCaptureCaller{}
+	_, canonicalErr := executeParamAliasPayloadE2E(t, canonicalCaller, canonicalArgs...)
+	if canonicalErr != nil {
+		t.Fatalf("complete canonical command failed: %v\nargs=%v\ncalls=%#v", canonicalErr, canonicalArgs, canonicalCaller.calls)
+	}
+	if len(canonicalCaller.calls) == 0 {
+		t.Fatalf("complete canonical command reached no final transport payload: args=%v", canonicalArgs)
+	}
+
+	aliasCaller := &paramAliasCaptureCaller{}
+	ctx, aliasErr := executeParamAliasPayloadE2E(t, aliasCaller, aliasArgs...)
+	if aliasErr != nil {
+		t.Fatalf("complete alias command failed: %v\nargs=%v\ncalls=%#v", aliasErr, aliasArgs, aliasCaller.calls)
+	}
+	if ctx == nil {
+		t.Fatal("complete alias command skipped PreParse")
+	}
+	normalizeParamAliasVolatileDefaults(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)
+	}
+}
+
 func TestCrossPlatformCoverageNewIMParamAliasesReachCanonicalEquivalentFinalPayloads(t *testing.T) {
 	activeAliases := 0
 	for _, test := range paramAliasNewIMCases {

internal/app/schema_agent_examples_dry_run_test.go

@@ -274,6 +274,7 @@ type agentExampleFiles struct {
 	markdown string
 	json     string
 	batch    string
+	job      string
 	binary   string
 	image    string
 }
@@ -283,12 +284,14 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles {
 	markdown := filepath.Join(root, "content.md")
 	jsonFile := filepath.Join(root, "report.json")
 	batch := filepath.Join(root, "styles.json")
+	job := filepath.Join(root, "job.json")
 	binary := filepath.Join(root, "report.pdf")
 	image := filepath.Join(root, "chart.png")
 	for path, content := range map[string][]byte{
 		markdown: []byte("# Agent dry-run fixture\n\nNo business call is allowed.\n"),
 		jsonFile: []byte(`[{"content":"Agent dry-run fixture","sort":"0","key":"fixture","contentType":"markdown","type":"1"}]`),
 		batch:    []byte(`[{"sheetId":"Sheet1","range":"A1:B2","fontWeight":"bold"}]`),
+		job:      []byte(`{"name":"Java 工程师","description":"服务端开发","jobNature":"FULL-TIME","requiredEdu":6,"minSalary":20000,"maxSalary":35000,"extData":{"headCount":1,"fullTimeExtData":{"salaryMonth":12}},"creatorUserId":"creator-user-id","ownerUserIds":["owner-user-id"]}`),
 		binary:   []byte("%PDF-1.4\n%%EOF\n"),
 		image:    {0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'},
 	} {
@@ -301,6 +304,7 @@ func newAgentExampleFiles(t testing.TB, root string) agentExampleFiles {
 		markdown: "./" + filepath.Base(markdown),
 		json:     "./" + filepath.Base(jsonFile),
 		batch:    "./" + filepath.Base(batch),
+		job:      "./" + filepath.Base(job),
 		binary:   "./" + filepath.Base(binary),
 		image:    "./" + filepath.Base(image),
 	}
@@ -351,6 +355,10 @@ func materializeAgentExampleArgv(argv []string, files agentExampleFiles) []strin
 			replacement = files.markdown
 		case "contents-file":
 			replacement = files.json
+		case "from":
+			if strings.HasSuffix(strings.ToLower(value), "job.json") {
+				replacement = files.job
+			}
 		case "batch":
 			if strings.HasSuffix(strings.ToLower(value), "styles.json") {
 				replacement = files.batch

internal/app/schema_recruit_contract_test.go

@@ -0,0 +1,74 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package app
+
+import (
+	"bytes"
+	"encoding/json"
+	"reflect"
+	"testing"
+)
+
+func recruitSchemaLeaf(t *testing.T, canonical string, compact bool) map[string]any {
+	t.Helper()
+	root := NewRootCommand()
+	var stdout, stderr bytes.Buffer
+	root.SetOut(&stdout)
+	root.SetErr(&stderr)
+	args := []string{"schema", canonical, "--format", "json"}
+	if compact {
+		args = append(args, "--compact")
+	}
+	root.SetArgs(args)
+	if err := root.Execute(); err != nil {
+		t.Fatalf("execute schema %s compact=%v: %v; stderr=%s", canonical, compact, err, stderr.String())
+	}
+	var payload map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &payload); err != nil {
+		t.Fatalf("decode schema %s compact=%v: %v", canonical, compact, err)
+	}
+	return payload
+}
+
+func TestRecruitDeliveredSchemaPublishesResultAndPagination(t *testing.T) {
+	for _, canonical := range []string{"recruit.list_jobs", "recruit.get_job_detail", "recruit.create_job"} {
+		t.Run(canonical, func(t *testing.T) {
+			full := recruitSchemaLeaf(t, canonical, false)
+			compact := recruitSchemaLeaf(t, canonical, true)
+			if full["result"] == nil || compact["result"] == nil {
+				t.Fatalf("result missing: full=%#v compact=%#v", full["result"], compact["result"])
+			}
+			if !reflect.DeepEqual(full["result"], compact["result"]) {
+				t.Fatalf("full/compact result mismatch\nfull=%#v\ncompact=%#v", full["result"], compact["result"])
+			}
+			if canonical == "recruit.list_jobs" {
+				if full["pagination"] == nil || compact["pagination"] == nil {
+					t.Fatalf("list pagination missing: full=%#v compact=%#v", full["pagination"], compact["pagination"])
+				}
+				if !reflect.DeepEqual(full["pagination"], compact["pagination"]) {
+					t.Fatalf("full/compact pagination mismatch\nfull=%#v\ncompact=%#v", full["pagination"], compact["pagination"])
+				}
+				parameters, _ := full["parameters"].(map[string]any)
+				cursor, _ := parameters["cursor"].(map[string]any)
+				if cursor["type"] != "string" || cursor["interface_type"] != "number" {
+					t.Fatalf("cursor contract = %#v, want CLI string converted to MCP number", cursor)
+				}
+				size, _ := parameters["size"].(map[string]any)
+				if required, _ := size["required"].(bool); required {
+					t.Fatalf("size required = true, want false: %#v", size)
+				}
+				if size["default"] != "20" {
+					t.Fatalf("size default = %#v, want 20", size["default"])
+				}
+				compactParameters, _ := compact["parameters"].(map[string]any)
+				compactSize, _ := compactParameters["size"].(map[string]any)
+				if compactRequired, _ := compactSize["required"].(bool); compactRequired || compactSize["default"] != "20" {
+					t.Fatalf("compact size contract = %#v, want required=false default=20", compactSize)
+				}
+			} else if full["pagination"] != nil || compact["pagination"] != nil {
+				t.Fatalf("non-list pagination must be absent: full=%#v compact=%#v", full["pagination"], compact["pagination"])
+			}
+		})
+	}
+}

internal/app/skill_command.go

@@ -117,38 +117,114 @@ type CliSkillDTO struct {
 // (skill_setup.go) MUST have a matching path value here — enforced by
 // TestAgentSkillPathsCoversSetupHomes.
 var agentSkillPaths = map[string]string{
-	// `agents` is the generic-agent sentinel: install scripts and `setup`
-	// special-case ~/.agents/skills as a no-checks-required fallback so a
-	// fresh machine without any IDE/agent registry still gets skills.
-	"agents":    ".agents/skills",
-	"qoder":     ".qoder/skills",
-	"qoderwork": ".qoderwork/skills",
+	// Universal agents. Those without an independent global directory map
+	// directly to the canonical ~/.agents/skills store.
+	"agents":          ".agents/skills",
+	"amp":             filepath.Join(".config", "agents", "skills"),
+	"antigravity":     ".gemini/antigravity/skills",
+	"antigravity-cli": ".gemini/antigravity-cli/skills",
+	"codex":           ".codex/skills",
+	"cursor":          ".cursor/skills",
+	"deepagents":      ".deepagents/agent/skills",
+	"firebender":      ".firebender/skills",
+	"gemini-cli":      ".gemini/skills",
+	"github-copilot":  ".copilot/skills",
+	"opencode":        filepath.Join(".config", "opencode", "skills"),
+	"replit":          filepath.Join(".config", "agents", "skills"),
+	"universal":       filepath.Join(".config", "agents", "skills"),
+	"cline":           ".agents/skills",
+	"dexto":           ".agents/skills",
+	"kimi-code-cli":   ".agents/skills",
+	"loaf":            ".agents/skills",
+	"warp":            ".agents/skills",
+	"zed":             ".agents/skills",
+
+	// Non-universal agents with global Skill directories.
+	"aider-desk":     ".aider-desk/skills",
+	"astrbot":        ".astrbot/data/skills",
+	"autohand-code":  ".autohand/skills",
+	"augment":        ".augment/skills",
+	"bob":            ".bob/skills",
+	"claude-code":    ".claude/skills",
+	"openclaw":       ".openclaw/skills",
+	"codearts-agent": ".codeartsdoer/skills",
+	"codebuddy":      ".codebuddy/skills",
+	"codemaker":      ".codemaker/skills",
+	"codestudio":     ".codestudio/skills",
+	"command-code":   ".commandcode/skills",
+	"continue":       ".continue/skills",
+	"cortex":         ".snowflake/cortex/skills",
+	"crush":          filepath.Join(".config", "crush", "skills"),
+	"devin":          filepath.Join(".config", "devin", "skills"),
+	"droid":          ".factory/skills",
+	"forgecode":      ".forge/skills",
+	"goose":          filepath.Join(".config", "goose", "skills"),
+	"grok":           ".grok/skills",
+	"hermes-agent":   ".hermes/skills",
+	"inference-sh":   ".inferencesh/skills",
+	"jazz":           ".jazz/skills",
+	"junie":          ".junie/skills",
+	"iflow-cli":      ".iflow/skills",
+	"kilo":           ".kilocode/skills",
+	"kimchi":         filepath.Join(".config", "kimchi", "harness", "skills"),
+	"kiro-cli":       ".kiro/skills",
+	"kode":           ".kode/skills",
+	"lingma":         ".lingma/skills",
+	"mcpjam":         ".mcpjam/skills",
+	"minimax-code":   ".minimax/skills",
+	"mistral-vibe":   ".vibe/skills",
+	"moxby":          ".moxby/skills",
+	"mux":            ".mux/skills",
+	"openhands":      ".openhands/skills",
+	"ona":            ".ona/skills",
+	"pi":             ".pi/agent/skills",
+	"qoder":          ".qoder/skills",
+	"qoder-cn":       ".qoder-cn/skills",
+	"qwen-code":      ".qwen/skills",
+	"reasonix":       ".reasonix/skills",
+	"rovodev":        ".rovodev/skills",
+	"roo":            ".roo/skills",
+	"tabnine-cli":    ".tabnine/agent/skills",
+	"terramind":      ".terramind/skills",
+	"tinycloud":      ".tinycloud/skills",
+	"trae":           ".trae/skills",
+	"trae-cn":        ".trae-cn/skills",
+	"windsurf":       ".codeium/windsurf/skills",
+	"zcode":          ".zcode/skills",
+	"zencoder":       ".zencoder/skills",
+	"zenflow":        ".zencoder/skills",
+	"neovate":        ".neovate/skills",
+	"pochi":          ".pochi/skills",
+	"adal":           ".adal/skills",
+
+	// DWS compatibility aliases and DWS-only integrations.
 	"claude":    ".claude/skills",
-	"cursor":    ".cursor/skills",
-	"codex":     ".codex/skills",
-	"zcode":     ".zcode/skills",
-	"opencode":  filepath.Join(".config", "opencode", "skills"),
-	// IDE / agent registries also probed by `dws skill setup --target all`.
-	"gemini":   ".gemini/skills",
-	"github":   ".github/skills",
-	"windsurf": ".windsurf/skills",
-	"augment":  ".augment/skills",
-	"cline":    ".cline/skills",
-	"amp":      ".amp/skills",
-	"kiro":     ".kiro/skills",
-	"trae":     ".trae/skills",
-	"openclaw": ".openclaw/skills",
-	"hermes":   ".hermes/skills",
+	"gemini":    ".gemini/skills",
+	"github":    ".copilot/skills",
+	"hermes":    ".hermes/skills",
+	"kiro":      ".kiro/skills",
+	"qoderwork": ".qoderwork/skills",
+}
+
+// Eve has project-scoped Skill directories but no upstream globalSkillsDir.
+// Keep it in the advertised enumeration while failing explicitly instead of
+// pretending that a global install configured Eve.
+var unsupportedGlobalAgentTargets = map[string]string{
+	"eve":          "Eve 不支持全局 Skill 安装，请在 Eve 项目内配置 agent/skills",
+	"promptscript": "PromptScript 不支持全局 Skill 安装，请在项目内使用 .agents/skills",
 }
 
 // supportedTargets returns a sorted, comma-separated list of supported
 // targets. Sorted so help text and error messages stay stable across runs
 // (Go map iteration order is intentionally randomized).
 func supportedTargets() string {
-	targets := make([]string, 0, len(agentSkillPaths)+1)
+	targets := make([]string, 0, len(agentSkillPaths)+len(unsupportedGlobalAgentTargets)+1)
 	for target := range agentSkillPaths {
 		targets = append(targets, target)
 	}
+	for target := range unsupportedGlobalAgentTargets {
+		targets = append(targets, target)
+	}
 	sort.Strings(targets)
 	targets = append(targets, ".")
 	return strings.Join(targets, ", ")
@@ -182,11 +258,28 @@ func formatAgentSkillPathsForHelp() string {
 	sort.Strings(names)
 	var b strings.Builder
 	for _, n := range names {
-		fmt.Fprintf(&b, "  %-*s -> ~/%s/\n", maxWidth, n, agentSkillPaths[n])
+		installPath := agentSkillPaths[n]
+		if isUniversalSkillInstallTarget(n) {
+			installPath = ".agents/skills"
+		}
+		fmt.Fprintf(&b, "  %-*s -> ~/%s/\n", maxWidth, n, installPath)
 	}
 	return b.String()
 }
 
+// Universal Agents discover the shared ~/.agents/skills store directly. A
+// marketplace install addressed to one of those Agent IDs must therefore
+// publish to canonical instead of recreating an Agent-private duplicate.
+func isUniversalSkillInstallTarget(target string) bool {
+	rel, ok := agentSkillPaths[target]
+	if !ok {
+		return false
+	}
+	base := filepath.Join("__home__", rel)
+	canonical := filepath.Join("__home__", ".agents", "skills")
+	return sameSkillSetupPath(base, canonical) || isUniversalSkillSetupBase(base)
+}
+
 func buildSkillCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:               "skill",
@@ -485,8 +578,13 @@ func resolveSkillTargetPath(target string) (string, error) {
 		return os.Getwd()
 	}
 
-	// Look up predefined agent paths
-	relPath, ok := agentSkillPaths[strings.ToLower(target)]
+	target = strings.ToLower(target)
+	if reason, unsupported := unsupportedGlobalAgentTargets[target]; unsupported {
+		return "", errors.New(reason)
+	}
+
+	// Look up predefined agent paths.
+	_, ok := agentSkillPaths[target]
 	if !ok {
 		return "", fmt.Errorf("unsupported target")
 	}
@@ -496,7 +594,11 @@ func resolveSkillTargetPath(target string) (string, error) {
 		return "", fmt.Errorf("failed to get home directory: %w", err)
 	}
 
-	return filepath.Join(homeDir, relPath), nil
+	destination := resolveSkillSetupBase(homeDir, target)
+	if isUniversalSkillInstallTarget(target) {
+		destination = filepath.Join(homeDir, ".agents", "skills")
+	}
+	return destination, nil
 }
 
 // fetchSkillDownloadInfo calls the download API to get the skill download URL.

internal/app/skill_command_test.go

@@ -28,6 +28,7 @@ import (
 	"time"
 
 	authpkg "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 )
 
 func TestResolveSkillTargetPath(t *testing.T) {
@@ -57,19 +58,19 @@ func TestResolveSkillTargetPath(t *testing.T) {
 		{
 			name:       "cursor target",
 			target:     "cursor",
-			wantSuffix: filepath.Join(".cursor", "skills"),
+			wantSuffix: filepath.Join(".agents", "skills"),
 			wantErr:    false,
 		},
 		{
 			name:       "codex target",
 			target:     "codex",
-			wantSuffix: filepath.Join(".codex", "skills"),
+			wantSuffix: filepath.Join(".agents", "skills"),
 			wantErr:    false,
 		},
 		{
 			name:       "opencode target",
 			target:     "opencode",
-			wantSuffix: filepath.Join(".config", "opencode", "skills"),
+			wantSuffix: filepath.Join(".agents", "skills"),
 			wantErr:    false,
 		},
 		{
@@ -118,6 +119,37 @@ func TestResolveSkillTargetPath(t *testing.T) {
 	}
 }
 
+func TestCrossPlatformCoverageUniversalSkillInstallTargetsUseCanonical(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillUserHomeDir, func() (string, error) { return home, nil })
+	if isUniversalSkillInstallTarget("missing-agent") {
+		t.Fatal("unknown Agent target classified as universal")
+	}
+	for _, target := range []string{
+		"amp", "antigravity", "antigravity-cli", "cline", "codex", "cursor",
+		"deepagents", "dexto", "firebender", "gemini", "gemini-cli", "github",
+		"github-copilot", "kimi-code-cli", "loaf", "opencode", "replit",
+		"universal", "warp", "zed",
+	} {
+		got, err := resolveSkillTargetPath(target)
+		if err != nil {
+			t.Fatalf("resolve %s: %v", target, err)
+		}
+		if want := filepath.Join(home, ".agents", "skills"); got != want {
+			t.Errorf("resolve %s = %s, want canonical %s", target, got, want)
+		}
+	}
+	for target, want := range map[string]string{
+		"claude": filepath.Join(home, ".claude", "skills"),
+		"qoder":  filepath.Join(home, ".qoder", "skills"),
+		"zcode":  filepath.Join(home, ".zcode", "skills"),
+	} {
+		if got, err := resolveSkillTargetPath(target); err != nil || got != want {
+			t.Errorf("resolve non-universal %s = %s, %v; want %s", target, got, err, want)
+		}
+	}
+}
+
 func TestResolveSkillTargetPathCurrentDir(t *testing.T) {
 	// Test "." target returns current working directory
 	cwd, err := os.Getwd()
@@ -477,8 +509,12 @@ func TestAgentSkillPathsCoversSetupHomes(t *testing.T) {
 	for _, p := range agentSkillPaths {
 		paths[p] = true
 	}
+	legacyCleanupOnly := map[string]bool{
+		".github/skills": true, ".windsurf/skills": true,
+		".cline/skills": true, ".amp/skills": true,
+	}
 	for _, home := range skillSetupAgentHomes {
-		if !paths[home] {
+		if !paths[home] && !legacyCleanupOnly[home] {
 			t.Errorf("skillSetupAgentHomes entry %q has no matching agentSkillPaths value — "+
 				"add it to agentSkillPaths so users can address it via --target <name>", home)
 		}

internal/app/skill_setup.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"runtime"
 	"sort"
 	"strings"
 	"time"
@@ -23,22 +24,77 @@ import (
 // agree on the install footprint.
 var skillSetupAgentHomes = []string{
 	".agents/skills",
+	".config/agents/skills",
+	".gemini/antigravity/skills",
+	".gemini/antigravity-cli/skills",
+	".deepagents/agent/skills",
+	".firebender/skills",
+	".copilot/skills",
+	".config/opencode/skills",
+	".aider-desk/skills",
+	".astrbot/data/skills",
+	".autohand/skills",
+	".augment/skills",
+	".bob/skills",
 	".claude/skills",
-	".cursor/skills",
+	".openclaw/skills",
+	".codeartsdoer/skills",
+	".codebuddy/skills",
+	".codemaker/skills",
+	".codestudio/skills",
+	".commandcode/skills",
+	".continue/skills",
+	".snowflake/cortex/skills",
+	".config/crush/skills",
+	".config/devin/skills",
+	".factory/skills",
+	".forge/skills",
+	".config/goose/skills",
+	".grok/skills",
+	".hermes/skills",
+	".inferencesh/skills",
+	".jazz/skills",
+	".junie/skills",
+	".iflow/skills",
+	".kilocode/skills",
+	".config/kimchi/harness/skills",
+	".kiro/skills",
+	".kode/skills",
+	".lingma/skills",
+	".mcpjam/skills",
+	".minimax/skills",
+	".vibe/skills",
+	".moxby/skills",
+	".mux/skills",
+	".openhands/skills",
+	".ona/skills",
+	".pi/agent/skills",
 	".qoder/skills",
+	".qoder-cn/skills",
+	".qwen/skills",
+	".reasonix/skills",
+	".rovodev/skills",
+	".roo/skills",
+	".tabnine/agent/skills",
+	".terramind/skills",
+	".tinycloud/skills",
+	".trae/skills",
+	".trae-cn/skills",
+	".codeium/windsurf/skills",
+	".zcode/skills",
+	".zencoder/skills",
+	".neovate/skills",
+	".pochi/skills",
+	".adal/skills",
 	".qoderwork/skills",
+	// beta.6 compatibility roots: cleanup only.
+	".cursor/skills",
 	".gemini/skills",
 	".codex/skills",
-	".zcode/skills",
 	".github/skills",
 	".windsurf/skills",
-	".augment/skills",
 	".cline/skills",
 	".amp/skills",
-	".kiro/skills",
-	".trae/skills",
-	".openclaw/skills",
-	".hermes/skills",
 }
 
 const (
@@ -65,15 +121,20 @@ var (
 	skillSetupInteractive     = isInteractiveTerminal
 	skillSetupReadDir         = os.ReadDir
 	skillSetupStat            = os.Stat
+	skillSetupLstat           = os.Lstat
+	skillSetupGetenv          = os.Getenv
+	skillSetupSymlink         = os.Symlink
 	skillSetupExecutable      = os.Executable
 	skillSetupGetwd           = os.Getwd
 	skillSetupUserHomeDir     = os.UserHomeDir
 	skillSetupRemoveAll       = os.RemoveAll
 	skillSetupBackupAndRemove = upgrade.BackupAndRemoveSkillDir
+	skillSetupRestoreBackup   = upgrade.RestoreSkillPath
 	skillSetupMkdirAll        = os.MkdirAll
 	skillSetupWalk            = filepath.Walk
 	skillSetupRel             = filepath.Rel
 	skillSetupReadlink        = os.Readlink
+	skillSetupEvalSymlinks    = filepath.EvalSymlinks
 	skillSetupOpen            = os.Open
 	skillSetupOpenFile        = os.OpenFile
 	skillSetupWriteFile       = os.WriteFile
@@ -82,7 +143,10 @@ var (
 	skillSetupReadState       = skillstate.Read
 	skillSetupWriteState      = skillstate.Write
 	skillSetupRemoveState     = skillstate.Remove
+	skillSetupPublishPath     = upgrade.PublishSkillPathNoReplace
+	skillSetupRollbackPaths   = upgrade.RollbackSkillPathPublications
 	skillSetupNow             = time.Now
+	skillSetupFoldPathCase    = runtime.GOOS == "windows"
 )
 
 type skillSetupBackup struct {
@@ -91,9 +155,11 @@ type skillSetupBackup struct {
 }
 
 type skillSetupTargetPlan struct {
-	Destination string
-	Backups     []skillSetupBackup
-	CleanupOnly bool
+	Destination   string
+	CanonicalBase string
+	Backups       []skillSetupBackup
+	CleanupOnly   bool
+	LinkCanonical bool
 }
 
 type skillSetupPlan struct {
@@ -149,8 +215,9 @@ multi 模式支持按产品挑选：
     备份失败时保留原目录并跳过该目标，绝不静默删除。
   · 所有将被移除的目录都会在确认前逐条列出。
 
-不带 --mode 时进入交互式询问；不带 --target 时铺到检测到的具体 Agent 目录；
-未检测到具体 Agent 时才回退到 ~/.agents/skills，避免同一 Agent 扫描两份 Skill。
+不带 --mode 时进入交互式询问；Skill 统一安装到 ~/.agents/skills。
+DWS 会自动适配本机上检测到的 Agent；共享安装方式不可用时会自动改用兼容安装，
+无需用户手动处理，也不会让同一个 Skill 重复出现。
 skill 源默认取二进制内嵌的版本（升级二进制即升级 skill）；--source / DWS_SKILL_SOURCE 可显式覆盖。`,
 		Example: `  dws skill setup --mode multi --target claude --dry-run
   dws skill setup --mode multi --target claude`,
@@ -243,7 +310,6 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 			}
 		}
 	}
-
 	// filtered 决定 multi 安装的清理语义：带 -s/--skill 或 -x/--exclude
 	// 时保持 additive（不动未列出的 sibling）；全量安装与 install.sh /
 	// install.js 对齐，清掉不在 bundle 内且有明确 DWS 所有权记录的过期 Skill。
@@ -316,6 +382,17 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 	if err != nil {
 		return err
 	}
+	if mode == skillSetupModeMulti && len(migrateEventMiscTargets) > 0 {
+		retiredNames := append([]string(nil), multiSkillNames...)
+		if installsEventMiscCompanion && !containsSkillName(retiredNames, multiMiscSkill) {
+			retiredNames = append(retiredNames, multiMiscSkill)
+		}
+		if retireErr := retireMigratedUniversalSkills(migrateEventMiscTargets, retiredNames, out); retireErr != nil {
+			// Retiring an obsolete universal copy installs nothing; report it and
+			// keep the successful installation rather than failing the run.
+			fmt.Fprintf(errOut, "  ⚠️  %v\n", retireErr)
+		}
+	}
 	if skipped > 0 {
 		return fmt.Errorf(
 			"Skill 安装不完整（mode=%s, installed=%d, skipped=%d）；修复失败原因后请重试 setup，或运行普通 upgrade 全量刷新预制 Skill",
@@ -350,7 +427,9 @@ func runSkillSetup(cmd *cobra.Command, _ []string) error {
 		}
 	}
 	fmt.Fprintf(out, "\n✅ Skill 安装完成（mode=%s, installed=%d, skipped=%d）\n", mode, installed, skipped)
-	fmt.Fprintln(out, "ℹ️  若 Agent 会话已打开，请重启 Agent 或重新加载 Skills 后再验证路由。")
+	fmt.Fprintln(out, "   统一安装位置：~/.agents/skills")
+	fmt.Fprintln(out, "   已自动适配本机上检测到的 Agent")
+	fmt.Fprintln(out, "ℹ️  下一步：请重启已打开的 Agent，使新 Skills 生效。")
 	return nil
 }
 
@@ -910,8 +989,9 @@ func isSkillSourceRoot(path, mode string) bool {
 }
 
 // resolveSkillSetupTargets returns the list of absolute Agent home destinations.
-// If target == "all", returns every agent home whose parent directory exists.
-// Otherwise returns the single matching home (whether or not it currently exists).
+// The canonical ~/.agents/skills destination is always first. If target ==
+// "all", detected concrete Agent roots follow it. A specific target follows
+// canonical as well so unknown/future Agents retain the universal copy.
 //
 // 末段约定：
 //   - mono  → <agent-home>/dws   （单 skill，整个 src 拷成一个 dws 目录）
@@ -923,15 +1003,88 @@ func resolveSkillSetupTargets(target, mode string) ([]string, error) {
 	}
 
 	target = strings.ToLower(strings.TrimSpace(target))
+	canonical := agentHomeForMode(filepath.Join(home, skillSetupAgentHomes[0]), mode)
 	if target == "" || target == "all" {
 		return detectExistingAgentHomes(home, mode), nil
 	}
 
-	rel, ok := agentSkillPaths[target]
+	if reason, unsupported := unsupportedGlobalAgentTargets[target]; unsupported {
+		return nil, errors.New(reason)
+	}
+	_, ok := agentSkillPaths[target]
 	if !ok {
 		return nil, fmt.Errorf("不支持的 --target 值: %s（可选 all, %s）", target, supportedTargets())
 	}
-	return []string{agentHomeForMode(filepath.Join(home, rel), mode)}, nil
+	dest := agentHomeForMode(resolveSkillSetupBase(home, target), mode)
+	if sameSkillSetupPath(dest, canonical) {
+		return []string{canonical}, nil
+	}
+	return []string{canonical, dest}, nil
+}
+
+func resolveOpenClawSetupBase(home string) string {
+	for _, name := range []string{".openclaw", ".clawdbot", ".moltbot"} {
+		base := filepath.Join(home, name)
+		if info, err := skillSetupStat(base); err == nil && info.IsDir() {
+			return filepath.Join(base, "skills")
+		}
+	}
+	return filepath.Join(home, ".openclaw", "skills")
+}
+
+func resolveSkillSetupBase(home, target string) string {
+	switch target {
+	case "claude", "claude-code":
+		if custom := strings.TrimSpace(skillSetupGetenv("CLAUDE_CONFIG_DIR")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "codex":
+		if custom := strings.TrimSpace(skillSetupGetenv("CODEX_HOME")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "hermes", "hermes-agent":
+		if custom := strings.TrimSpace(skillSetupGetenv("HERMES_HOME")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "autohand-code":
+		if custom := strings.TrimSpace(skillSetupGetenv("AUTOHAND_HOME")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "grok":
+		if custom := strings.TrimSpace(skillSetupGetenv("GROK_HOME")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "mistral-vibe":
+		if custom := strings.TrimSpace(skillSetupGetenv("VIBE_HOME")); custom != "" {
+			return filepath.Join(custom, "skills")
+		}
+	case "openclaw":
+		return resolveOpenClawSetupBase(home)
+	case "opencode", "amp", "replit", "universal", "crush", "devin", "goose", "kimchi":
+		configHome := strings.TrimSpace(skillSetupGetenv("XDG_CONFIG_HOME"))
+		if configHome == "" {
+			configHome = filepath.Join(home, ".config")
+		}
+		switch target {
+		case "opencode":
+			return filepath.Join(configHome, "opencode", "skills")
+		case "amp", "replit", "universal":
+			return filepath.Join(configHome, "agents", "skills")
+		case "crush":
+			return filepath.Join(configHome, "crush", "skills")
+		case "devin":
+			return filepath.Join(configHome, "devin", "skills")
+		case "goose":
+			return filepath.Join(configHome, "goose", "skills")
+		case "kimchi":
+			return filepath.Join(configHome, "kimchi", "harness", "skills")
+		}
+	case "github", "github-copilot":
+		return filepath.Join(home, ".copilot", "skills")
+	case "windsurf":
+		return filepath.Join(home, ".codeium", "windsurf", "skills")
+	}
+	return filepath.Join(home, agentSkillPaths[target])
 }
 
 // agentHomeForMode appends the mode-specific tail segment to an agent home base.
@@ -943,79 +1096,141 @@ func agentHomeForMode(base, mode string) string {
 }
 
 func detectExistingAgentHomes(home, mode string) []string {
-	var specific []string
+	canonical := agentHomeForMode(filepath.Join(home, skillSetupAgentHomes[0]), mode)
+	dests := []string{canonical}
+	canonicalKey := skillSetupPathKey(canonical)
+	seen := map[string]bool{canonicalKey: true}
+	addDetected := func(rel, base string) {
+		detectedDir := filepath.Dir(base)
+		switch filepath.ToSlash(filepath.Clean(rel)) {
+		case ".config/kimchi/harness/skills", ".tabnine/agent/skills":
+			detectedDir = filepath.Dir(filepath.Dir(base))
+		case ".zcode/skills":
+			// Application bundles are machine-scoped detection signals. Keep this
+			// independent of HOME so setup matches npm, Shell, and PowerShell.
+			if info, err := skillSetupStat(filepath.Join(string(filepath.Separator), "Applications", "ZCode.app")); err == nil && info.IsDir() {
+				detectedDir = ""
+			}
+		case ".minimax/skills":
+			if info, err := skillSetupStat(filepath.Join(string(filepath.Separator), "Applications", "MiniMax Code.app")); err == nil && info.IsDir() {
+				detectedDir = ""
+			}
+		}
+		if detectedDir != "" {
+			if info, err := skillSetupStat(detectedDir); err != nil || !info.IsDir() {
+				return
+			}
+		}
+		dest := agentHomeForMode(base, mode)
+		key := skillSetupPathKey(dest)
+		if !seen[key] {
+			seen[key] = true
+			dests = append(dests, dest)
+		}
+	}
 	for i, rel := range skillSetupAgentHomes {
 		if i == 0 {
 			continue
 		}
 		base := filepath.Join(home, rel)
-		parent := filepath.Dir(base)
-		if info, err := skillSetupStat(parent); err != nil || !info.IsDir() {
-			continue
+		switch filepath.ToSlash(filepath.Clean(rel)) {
+		case ".claude/skills":
+			base = resolveSkillSetupBase(home, "claude-code")
+		case ".codex/skills":
+			base = resolveSkillSetupBase(home, "codex")
+		case ".hermes/skills":
+			base = resolveSkillSetupBase(home, "hermes-agent")
+		case ".autohand/skills":
+			base = resolveSkillSetupBase(home, "autohand-code")
+		case ".grok/skills":
+			base = resolveSkillSetupBase(home, "grok")
+		case ".vibe/skills":
+			base = resolveSkillSetupBase(home, "mistral-vibe")
+		case ".openclaw/skills":
+			base = resolveSkillSetupBase(home, "openclaw")
+		case ".config/opencode/skills":
+			base = resolveSkillSetupBase(home, "opencode")
+		case ".config/agents/skills":
+			base = resolveSkillSetupBase(home, "amp")
+		case ".config/crush/skills":
+			base = resolveSkillSetupBase(home, "crush")
+		case ".config/devin/skills":
+			base = resolveSkillSetupBase(home, "devin")
+		case ".config/goose/skills":
+			base = resolveSkillSetupBase(home, "goose")
+		case ".config/kimchi/harness/skills":
+			base = resolveSkillSetupBase(home, "kimchi")
 		}
-		specific = append(specific, agentHomeForMode(base, mode))
+		addDetected(rel, base)
 	}
-	if len(specific) > 0 {
-		return specific
+	for _, target := range []string{"github-copilot", "windsurf"} {
+		addDetected(agentSkillPaths[target], resolveSkillSetupBase(home, target))
 	}
-	return []string{agentHomeForMode(filepath.Join(home, skillSetupAgentHomes[0]), mode)}
+	return dests
 }
 
-func genericSkillCleanupTarget(dests []string, managed map[string]bool) (*skillSetupTargetPlan, error) {
-	// Derive HOME from a concrete Agent destination instead of resolving it a
-	// second time. The destinations were already resolved from HOME by the
-	// caller, and a later/transient UserHomeDir failure must not turn an
-	// otherwise valid setup plan into an error. Direct/custom destinations that
-	// do not match a known concrete Agent root have no generic-root migration.
-	home := ""
-	for _, dest := range dests {
-		base := dest
-		if filepath.Base(dest) == "dws" {
-			base = filepath.Dir(dest)
-		}
-		base = filepath.Clean(base)
-		for i, rel := range skillSetupAgentHomes {
-			if i == 0 {
-				continue
-			}
-			suffix := filepath.Clean(filepath.FromSlash(rel))
-			needle := string(filepath.Separator) + suffix
-			if strings.HasSuffix(base, needle) {
-				home = strings.TrimSuffix(base, needle)
-				break
-			}
-		}
-		if home != "" {
-			break
-		}
+func skillSetupBaseForMode(dest, mode string) string {
+	if mode == skillSetupModeMono {
+		return filepath.Dir(dest)
 	}
-	if home == "" {
-		return nil, nil
-	}
-	genericBase := filepath.Join(home, ".agents", "skills")
+	return dest
+}
 
-	target := &skillSetupTargetPlan{Destination: genericBase, CleanupOnly: true}
-	add := func(path, reason string) {
-		if info, statErr := skillSetupStat(path); statErr == nil && info.IsDir() {
-			target.Backups = append(target.Backups, skillSetupBackup{Path: path, Reason: reason})
+func isUniversalSkillSetupBase(base string) bool {
+	cleanBase := filepath.Clean(base)
+	if custom := strings.TrimSpace(skillSetupGetenv("CODEX_HOME")); custom != "" && sameSkillSetupPath(cleanBase, filepath.Join(custom, "skills")) {
+		return true
+	}
+	if custom := strings.TrimSpace(skillSetupGetenv("XDG_CONFIG_HOME")); custom != "" {
+		if sameSkillSetupPath(cleanBase, filepath.Join(custom, "agents", "skills")) ||
+			sameSkillSetupPath(cleanBase, filepath.Join(custom, "opencode", "skills")) {
+			return true
 		}
 	}
-	add(filepath.Join(genericBase, "dws"), skillSetupBackupMutual)
-	entries, readErr := skillSetupReadDir(genericBase)
-	if readErr != nil && !errors.Is(readErr, os.ErrNotExist) {
-		return nil, fmt.Errorf("扫描通用 Skill 根目录失败 %s: %w", genericBase, readErr)
-	}
-	for _, entry := range entries {
-		path := filepath.Join(genericBase, entry.Name())
-		if entry.IsDir() && isManagedDWSMultiSkillDir(path, managed) {
-			target.Backups = append(target.Backups, skillSetupBackup{Path: path, Reason: skillSetupBackupStale})
+	base = filepath.ToSlash(cleanBase)
+	for rel := range map[string]bool{
+		".config/agents/skills": true, ".gemini/antigravity/skills": true,
+		".gemini/antigravity-cli/skills": true, ".codex/skills": true,
+		".cursor/skills": true, ".deepagents/agent/skills": true,
+		".firebender/skills": true, ".gemini/skills": true,
+		".copilot/skills": true, ".config/opencode/skills": true,
+		// beta.6 compatibility roots are cleanup-only.
+		".github/skills": true, ".windsurf/skills": true,
+		".cline/skills": true, ".amp/skills": true,
+	} {
+		if strings.HasSuffix(base, "/"+rel) {
+			return true
 		}
 	}
-	if len(target.Backups) == 0 {
-		return nil, nil
+	return false
+}
+
+func sameSkillSetupPath(left, right string) bool {
+	return skillSetupPathKey(left) == skillSetupPathKey(right)
+}
+
+func skillSetupPathKey(path string) string {
+	clean := filepath.Clean(path)
+	if skillSetupFoldPathCase {
+		clean = strings.ToLower(clean)
 	}
-	sort.Slice(target.Backups, func(i, j int) bool { return target.Backups[i].Path < target.Backups[j].Path })
-	return target, nil
+	return clean
+}
+
+func canonicalSkillSetupBase(dests []string, mode string) string {
+	for _, dest := range dests {
+		base := filepath.ToSlash(filepath.Clean(skillSetupBaseForMode(dest, mode)))
+		if strings.HasSuffix(base, "/.agents/skills") {
+			return skillSetupBaseForMode(dest, mode)
+		}
+	}
+	return ""
+}
+
+func samePhysicalSkillSetupPath(left, right string) bool {
+	leftReal, leftErr := skillSetupEvalSymlinks(left)
+	rightReal, rightErr := skillSetupEvalSymlinks(right)
+	return leftErr == nil && rightErr == nil && sameSkillSetupPath(leftReal, rightReal)
 }
 
 func buildSkillSetupPlan(mode, src string, dests, multiSkillNames []string, filtered bool) (*skillSetupPlan, error) {
@@ -1030,10 +1245,26 @@ func buildSkillSetupPlan(mode, src string, dests, multiSkillNames []string, filt
 	}
 	sort.Strings(plan.MultiSkillNames)
 	sortedDests := append([]string(nil), dests...)
-	sort.Strings(sortedDests)
+	sort.Slice(sortedDests, func(i, j int) bool {
+		leftCanonical := strings.HasSuffix(filepath.ToSlash(filepath.Clean(skillSetupBaseForMode(sortedDests[i], mode))), "/.agents/skills")
+		rightCanonical := strings.HasSuffix(filepath.ToSlash(filepath.Clean(skillSetupBaseForMode(sortedDests[j], mode))), "/.agents/skills")
+		if leftCanonical != rightCanonical {
+			return leftCanonical
+		}
+		return sortedDests[i] < sortedDests[j]
+	})
 	managedNames := currentManagedSkillNames()
+	canonicalBase := canonicalSkillSetupBase(sortedDests, mode)
 	for _, dest := range sortedDests {
-		target := skillSetupTargetPlan{Destination: dest}
+		base := skillSetupBaseForMode(dest, mode)
+		target := skillSetupTargetPlan{Destination: dest, CanonicalBase: canonicalBase}
+		if canonicalBase != "" && filepath.Clean(base) != filepath.Clean(canonicalBase) {
+			if isUniversalSkillSetupBase(base) {
+				target.CleanupOnly = true
+			} else {
+				target.LinkCanonical = true
+			}
+		}
 		seen := map[string]bool{}
 		add := func(path, reason string) {
 			if seen[path] {
@@ -1077,26 +1308,22 @@ func buildSkillSetupPlan(mode, src string, dests, multiSkillNames []string, filt
 			}
 		}
 		for _, path := range replacements {
-			info, statErr := skillSetupStat(path)
+			if target.LinkCanonical && samePhysicalSkillSetupPath(path, filepath.Join(target.CanonicalBase, filepath.Base(path))) {
+				continue
+			}
+			_, statErr := skillSetupLstat(path)
 			if statErr != nil {
 				if errors.Is(statErr, os.ErrNotExist) {
 					continue
 				}
 				return nil, fmt.Errorf("检查将被替换的 Skill 失败 %s: %w", path, statErr)
 			}
-			if info.IsDir() {
-				add(path, skillSetupBackupReplace)
-			}
+			add(path, skillSetupBackupReplace)
 		}
 		sort.Slice(target.Backups, func(i, j int) bool { return target.Backups[i].Path < target.Backups[j].Path })
-		plan.Targets = append(plan.Targets, target)
-	}
-	cleanupTarget, cleanupErr := genericSkillCleanupTarget(sortedDests, managedNames)
-	if cleanupErr != nil {
-		return nil, cleanupErr
-	}
-	if cleanupTarget != nil {
-		plan.Targets = append(plan.Targets, *cleanupTarget)
+		if !target.CleanupOnly || len(target.Backups) > 0 {
+			plan.Targets = append(plan.Targets, target)
+		}
 	}
 	return plan, nil
 }
@@ -1140,6 +1367,33 @@ func configureEventMiscMigrationPlan(plan *skillSetupPlan, targets []string, ins
 	}
 }
 
+func retireMigratedUniversalSkills(targets, names []string, out io.Writer) error {
+	home, err := skillSetupUserHomeDir()
+	if err != nil {
+		return fmt.Errorf("无法解析 HOME 以退役 universal Agent 旧副本: %w", err)
+	}
+	seen := map[string]bool{}
+	var victims []skillSetupBackup
+	for _, target := range targets {
+		if !isUniversalSkillSetupBase(target) {
+			continue
+		}
+		for _, name := range names {
+			path := filepath.Join(target, name)
+			if seen[path] {
+				continue
+			}
+			seen[path] = true
+			victims = append(victims, skillSetupBackup{Path: path, Reason: skillSetupBackupReplace})
+		}
+	}
+	sort.Slice(victims, func(i, j int) bool { return victims[i].Path < victims[j].Path })
+	if _, err := backupSkillSetupTarget(home, victims, out); err != nil {
+		return fmt.Errorf("退役 universal Agent Event/misc 旧副本失败，已回滚: %w", err)
+	}
+	return nil
+}
+
 func renderSkillSetupPlan(out io.Writer, plan *skillSetupPlan) {
 	fmt.Fprintf(out, "📦 将安装 skill：\n  mode: %s\n  source: %s\n", plan.Mode, plan.Source)
 	if plan.Mode == skillSetupModeMulti {
@@ -1148,12 +1402,14 @@ func renderSkillSetupPlan(out io.Writer, plan *skillSetupPlan) {
 			fmt.Fprintf(out, "    · %s\n", name)
 		}
 	}
-	fmt.Fprintln(out, "  destinations:")
+	fmt.Fprintln(out, "  安装与适配位置:")
 	for _, target := range plan.Targets {
 		if target.CleanupOnly {
-			fmt.Fprintf(out, "    - %s (仅迁移旧的通用 DWS 副本)\n", target.Destination)
+			fmt.Fprintf(out, "    - %s（移除该 Agent 中的旧版 DWS Skills，改用统一安装位置）\n", target.Destination)
+		} else if target.LinkCanonical {
+			fmt.Fprintf(out, "    - %s（自动配置此 Agent 使用统一安装位置）\n", target.Destination)
 		} else {
-			fmt.Fprintf(out, "    - %s\n", target.Destination)
+			fmt.Fprintf(out, "    - %s（统一安装位置）\n", target.Destination)
 		}
 	}
 	fmt.Fprintln(out, "  将备份并移除（先保存到 ~/.dws/skill-backups/）：")
@@ -1324,8 +1580,12 @@ func installMultiSkillsWithEventMigration(
 	}
 
 	migrationSet := make(map[string]struct{}, len(migrationTargets))
+	physicalMigrationTargets := make([]string, 0, len(migrationTargets))
 	for _, dest := range migrationTargets {
 		migrationSet[dest] = struct{}{}
+		if !isUniversalSkillSetupBase(dest) {
+			physicalMigrationTargets = append(physicalMigrationTargets, dest)
+		}
 	}
 	var ordinaryTargets []string
 	for _, dest := range dests {
@@ -1334,23 +1594,47 @@ func installMultiSkillsWithEventMigration(
 		}
 	}
 
-	if len(ordinaryTargets) > 0 {
+	var canonicalTargets, otherOrdinaryTargets []string
+	for _, dest := range ordinaryTargets {
+		base := filepath.ToSlash(filepath.Clean(skillSetupBaseForMode(dest, skillSetupModeMulti)))
+		if strings.HasSuffix(base, "/.agents/skills") {
+			canonicalTargets = append(canonicalTargets, dest)
+		} else {
+			otherOrdinaryTargets = append(otherOrdinaryTargets, dest)
+		}
+	}
+	installOrdinary := func(names, targets []string) error {
+		if len(targets) == 0 {
+			return nil
+		}
 		var n, nSkipped int
-		n, nSkipped, err = skillSetupInstallMulti(src, skillNames, ordinaryTargets, out, errOut, filtered)
+		n, nSkipped, err = skillSetupInstallMulti(src, names, targets, out, errOut, filtered)
 		installed += n
 		skipped += nSkipped
 		if err != nil {
-			return installed, skipped, err
+			return err
 		}
 		if nSkipped > 0 {
-			return installed, skipped, fmt.Errorf("multi Skill 安装不完整（skipped=%d）；已保留折叠版 Event/misc，未执行迁移", nSkipped)
+			return fmt.Errorf("multi Skill 安装不完整（skipped=%d）；已保留折叠版 Event/misc，未执行迁移", nSkipped)
 		}
+		return nil
+	}
+	canonicalNames := append([]string(nil), skillNames...)
+	if !containsSkillName(canonicalNames, multiMiscSkill) {
+		canonicalNames = append(canonicalNames, multiMiscSkill)
+		sort.Strings(canonicalNames)
+	}
+	if err := installOrdinary(canonicalNames, canonicalTargets); err != nil {
+		return installed, skipped, err
+	}
+	if err := installOrdinary(skillNames, otherOrdinaryTargets); err != nil {
+		return installed, skipped, err
 	}
 
 	// The folded pair is excluded from the ordinary best-effort installer. All
 	// other selected skills (especially dingtalk-shared) must succeed before the
 	// old Event route is touched.
-	for _, dest := range migrationTargets {
+	for _, dest := range physicalMigrationTargets {
 		if cleanupErr := cleanupMutualExclusion(dest, skillSetupModeMulti, out, errOut); cleanupErr != nil {
 			return installed, skipped + len(skillNames), cleanupErr
 		}
@@ -1361,9 +1645,9 @@ func installMultiSkillsWithEventMigration(
 			prerequisiteNames = append(prerequisiteNames, name)
 		}
 	}
-	if len(prerequisiteNames) > 0 {
+	if len(prerequisiteNames) > 0 && len(physicalMigrationTargets) > 0 {
 		var n, nSkipped int
-		n, nSkipped, err = skillSetupInstallMulti(src, prerequisiteNames, migrationTargets, out, errOut, true)
+		n, nSkipped, err = skillSetupInstallMulti(src, prerequisiteNames, physicalMigrationTargets, out, errOut, true)
 		installed += n
 		skipped += nSkipped
 		if err != nil {
@@ -1374,7 +1658,7 @@ func installMultiSkillsWithEventMigration(
 		}
 	}
 
-	migrated, migrationErr := migrateEventMiscAtomically(src, migrationTargets, out, errOut)
+	migrated, migrationErr := migrateEventMiscAtomically(src, physicalMigrationTargets, out, errOut)
 	installed += migrated
 	if migrationErr != nil {
 		return installed, skipped, migrationErr
@@ -1646,9 +1930,32 @@ func stageSkillSetupTarget(plan *skillSetupPlan, target skillSetupTargetPlan) (s
 			err = errors.Join(err, fmt.Errorf("清理 Skill staging 失败 %s: %w", stageRoot, cleanupErr))
 		}
 	}()
+	realStageParent, realParentErr := skillSetupEvalSymlinks(stageParent)
+	if realParentErr != nil {
+		return stageRoot, nil, fmt.Errorf("解析 Agent Skill 物理目录失败 %s: %w", stageParent, realParentErr)
+	}
 
 	stageOne := func(src, dest string) error {
 		stagedDir := filepath.Join(stageRoot, filepath.Base(dest))
+		if target.LinkCanonical {
+			canonicalTarget := filepath.Join(target.CanonicalBase, filepath.Base(dest))
+			if samePhysicalSkillSetupPath(dest, canonicalTarget) {
+				return nil
+			}
+			realCanonicalTarget, realTargetErr := skillSetupEvalSymlinks(canonicalTarget)
+			if realTargetErr != nil {
+				return fmt.Errorf("解析 canonical Skill 失败 %s: %w", canonicalTarget, realTargetErr)
+			}
+			relTarget, relErr := skillSetupRel(realStageParent, realCanonicalTarget)
+			if relErr != nil {
+				return fmt.Errorf("计算 Skill 相对链接失败 %s: %w", canonicalTarget, relErr)
+			}
+			if linkErr := skillSetupSymlink(relTarget, stagedDir); linkErr != nil {
+				return fmt.Errorf("创建 Skill 链接失败 %s -> %s: %w", stagedDir, relTarget, linkErr)
+			}
+			staged = append(staged, skillSetupStagedDir{staged: stagedDir, dest: dest})
+			return nil
+		}
 		if err := skillSetupMkdirAll(stagedDir, 0o755); err != nil {
 			return fmt.Errorf("创建 Skill staging 目录失败 %s: %w", stagedDir, err)
 		}
@@ -1675,16 +1982,11 @@ func stageSkillSetupTarget(plan *skillSetupPlan, target skillSetupTargetPlan) (s
 
 // restoreSkillSetupTarget removes a partially published replacement and
 // restores every original directory from its exact backup path.
-func restoreSkillSetupTarget(published []string, backups []skillSetupBackedUpDir) error {
-	var restoreErr error
-	for i := len(published) - 1; i >= 0; i-- {
-		if err := skillSetupRemoveAll(published[i]); err != nil {
-			restoreErr = errors.Join(restoreErr, fmt.Errorf("移除失败发布目录 %s: %w", published[i], err))
-		}
-	}
+func restoreSkillSetupTarget(published []upgrade.SkillPathPublication, backups []skillSetupBackedUpDir) error {
+	restoreErr := skillSetupRollbackPaths(published)
 	for i := len(backups) - 1; i >= 0; i-- {
 		item := backups[i]
-		if _, err := skillSetupStat(item.original); err == nil {
+		if _, err := skillSetupLstat(item.original); err == nil {
 			restoreErr = errors.Join(restoreErr, fmt.Errorf("恢复目标仍存在 %s；备份保留于 %s", item.original, item.backup))
 			continue
 		} else if !errors.Is(err, os.ErrNotExist) {
@@ -1695,7 +1997,7 @@ func restoreSkillSetupTarget(published []string, backups []skillSetupBackedUpDir
 			restoreErr = errors.Join(restoreErr, fmt.Errorf("创建 Skill 恢复目录失败 %s: %w；备份保留于 %s", filepath.Dir(item.original), err, item.backup))
 			continue
 		}
-		if err := skillSetupPublishRename(item.backup, item.original); err != nil {
+		if err := skillSetupRestoreBackup(item.backup, item.original); err != nil {
 			restoreErr = errors.Join(restoreErr, fmt.Errorf("恢复原 Skill 失败 %s: %w；备份保留于 %s", item.original, err, item.backup))
 		}
 	}
@@ -1728,45 +2030,53 @@ func backupSkillSetupTarget(home string, planned []skillSetupBackup, out io.Writ
 }
 
 func publishSkillSetupTarget(staged []skillSetupStagedDir, backups []skillSetupBackedUpDir) error {
-	published := make([]string, 0, len(staged))
+	published := make([]upgrade.SkillPathPublication, 0, len(staged))
 	for _, item := range staged {
-		// Record before rename so rollback also removes a destination created by
-		// a platform-specific partial failure.
-		published = append(published, item.dest)
-		if err := skillSetupPublishRename(item.staged, item.dest); err != nil {
+		publication, err := skillSetupPublishPath(item.staged, item.dest)
+		if err != nil {
 			publishErr := fmt.Errorf("发布 Skill 失败 %s: %w", item.dest, err)
 			if restoreErr := restoreSkillSetupTarget(published, backups); restoreErr != nil {
 				return errors.Join(publishErr, fmt.Errorf("Skill setup 回滚不完整: %w", restoreErr))
 			}
 			return publishErr
 		}
+		published = append(published, publication)
 	}
 	return nil
 }
 
 func executeSkillSetupPlan(plan *skillSetupPlan, out, errOut io.Writer) (installed, skipped int, err error) {
 	home, homeErr := skillSetupUserHomeDir()
-	perTarget := 1
-	if plan.Mode == skillSetupModeMulti {
-		perTarget = len(plan.MultiSkillNames)
+	hasCanonicalDependents := false
+	for _, candidate := range plan.Targets {
+		if candidate.CanonicalBase != "" && !sameSkillSetupPath(skillSetupBaseForMode(candidate.Destination, plan.Mode), candidate.CanonicalBase) {
+			hasCanonicalDependents = true
+			break
+		}
 	}
 	for _, target := range plan.Targets {
+		perTarget := 1
+		if plan.Mode == skillSetupModeMulti {
+			perTarget = len(plan.MultiSkillNames)
+		}
+		isCanonical := target.CanonicalBase != "" && sameSkillSetupPath(skillSetupBaseForMode(target.Destination, plan.Mode), target.CanonicalBase)
 		if target.CleanupOnly {
-			if skipped > 0 {
-				continue
-			}
+			// Nothing is installed below a universal root, so a stale copy that
+			// resists retirement must not count as a skipped install: any skipped
+			// count fails the whole setup, even when every real target succeeded.
 			if homeErr != nil {
-				fmt.Fprintf(errOut, "  ✗ 无法解析 HOME，保留通用 Skill 副本 %s: %v\n", target.Destination, homeErr)
-				skipped++
+				fmt.Fprintf(errOut, "  ⚠️  无法解析 HOME，保留 universal Agent 旧副本 %s: %v\n", target.Destination, homeErr)
 				continue
 			}
 			if _, cleanupErr := backupSkillSetupTarget(home, target.Backups, out); cleanupErr != nil {
-				fmt.Fprintf(errOut, "  ✗ 通用 Skill 副本迁移失败，已回滚 %s: %v\n", target.Destination, cleanupErr)
-				skipped++
+				fmt.Fprintf(errOut, "  ⚠️  universal Agent 旧副本迁移失败，已回滚，可手动删除 %s: %v\n", target.Destination, cleanupErr)
 			}
 			continue
 		}
 		if len(target.Backups) > 0 && homeErr != nil {
+			if isCanonical && hasCanonicalDependents {
+				return installed, skipped + perTarget, fmt.Errorf("无法解析 HOME，canonical Skill 刷新中止 %s: %w", target.Destination, homeErr)
+			}
 			if plan.Mode == skillSetupModeMono {
 				fmt.Fprintf(errOut, "  ✗ 无法解析 HOME，跳过刷新（保留原目录） %s: %v\n", target.Destination, homeErr)
 			} else {
@@ -1777,7 +2087,16 @@ func executeSkillSetupPlan(plan *skillSetupPlan, out, errOut io.Writer) (install
 		}
 
 		stageRoot, staged, stageErr := stageSkillSetupTarget(plan, target)
+		if stageErr != nil && target.LinkCanonical {
+			fmt.Fprintf(errOut, "  ℹ️  %s 无法使用共享安装方式，正在自动改用兼容安装\n", target.Destination)
+			fallback := target
+			fallback.LinkCanonical = false
+			stageRoot, staged, stageErr = stageSkillSetupTarget(plan, fallback)
+		}
 		if stageErr != nil {
+			if isCanonical && hasCanonicalDependents {
+				return installed, skipped + perTarget, fmt.Errorf("canonical Skill staging 失败 %s: %w", target.Destination, stageErr)
+			}
 			fmt.Fprintf(errOut, "  ✗ Skill staging 失败，保留原集合 %s: %v\n", target.Destination, stageErr)
 			skipped += perTarget
 			continue
@@ -1787,6 +2106,9 @@ func executeSkillSetupPlan(plan *skillSetupPlan, out, errOut io.Writer) (install
 			if cleanupErr := skillSetupRemoveAll(stageRoot); cleanupErr != nil {
 				backupErr = errors.Join(backupErr, fmt.Errorf("清理 Skill staging 失败 %s: %w", stageRoot, cleanupErr))
 			}
+			if isCanonical && hasCanonicalDependents {
+				return installed, skipped + perTarget, fmt.Errorf("canonical Skill 备份失败，已执行回滚 %s: %w", target.Destination, backupErr)
+			}
 			fmt.Fprintf(errOut, "  ✗ Skill 备份失败，已执行回滚，跳过整个 Agent 目标 %s: %v\n", target.Destination, backupErr)
 			skipped += perTarget
 			continue
@@ -1797,7 +2119,19 @@ func executeSkillSetupPlan(plan *skillSetupPlan, out, errOut io.Writer) (install
 			if cleanupErr != nil {
 				publishErr = errors.Join(publishErr, fmt.Errorf("清理 Skill staging 失败 %s: %w", stageRoot, cleanupErr))
 			}
-			fmt.Fprintf(errOut, "  ✗ Skill 发布失败，已执行回滚，跳过整个 Agent 目标 %s: %v\n", target.Destination, publishErr)
+			if isCanonical && hasCanonicalDependents {
+				if errors.Is(publishErr, upgrade.ErrSkillPathPublicationUncertain) {
+					return installed, skipped + perTarget, fmt.Errorf("canonical Skill 发布状态不确定，目标可能属于并发写入并已保留 %s: %w", target.Destination, publishErr)
+				}
+				return installed, skipped + perTarget, fmt.Errorf("canonical Skill 发布失败，已执行回滚 %s: %w", target.Destination, publishErr)
+			}
+			if errors.Is(publishErr, upgrade.ErrSkillPathPublicationUncertain) {
+				// The destination may belong to a concurrent writer and was
+				// deliberately retained; the rollback refuses to displace it.
+				fmt.Fprintf(errOut, "  ✗ Skill 发布状态不确定，目标可能属于并发写入并已保留 %s: %v\n", target.Destination, publishErr)
+			} else {
+				fmt.Fprintf(errOut, "  ✗ Skill 发布失败，已执行回滚，跳过整个 Agent 目标 %s: %v\n", target.Destination, publishErr)
+			}
 			skipped += perTarget
 			continue
 		}
@@ -1836,7 +2170,7 @@ func staleMultiSkillVictimsWithError(dest string, keep []string, managed ...map[
 	}
 	var victims []string
 	for _, e := range entries {
-		if !e.IsDir() || keepSet[e.Name()] {
+		if (!e.IsDir() && e.Type()&os.ModeSymlink == 0) || keepSet[e.Name()] {
 			continue
 		}
 		if !isManagedDWSMultiSkillDir(filepath.Join(dest, e.Name()), managed...) {

internal/app/skill_setup_canonical_failures_test.go

@@ -0,0 +1,160 @@
+package app
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
+)
+
+func canonicalFailurePlan(t *testing.T) (string, *skillSetupPlan) {
+	t.Helper()
+	home := t.TempDir()
+	src := t.TempDir()
+	skill := filepath.Join(src, "dingtalk-chat")
+	if err := os.MkdirAll(skill, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(skill, "SKILL.md"), []byte("chat"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	canonical := filepath.Join(home, ".agents", "skills")
+	dependent := filepath.Join(home, ".claude", "skills")
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, src, []string{canonical, dependent}, []string{"dingtalk-chat"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return home, plan
+}
+
+func TestCrossPlatformCoverageSkillSetupCanonicalHomeBackupAndPublishFailures(t *testing.T) {
+	t.Run("home", func(t *testing.T) {
+		_, plan := canonicalFailurePlan(t)
+		canonical := filepath.Join(plan.Targets[0].Destination, "dingtalk-chat")
+		if err := os.MkdirAll(canonical, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		plan.Targets[0].Backups = []skillSetupBackup{{Path: canonical, Reason: skillSetupBackupReplace}}
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", errors.New("home denied") })
+		if _, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || !strings.Contains(err.Error(), "canonical Skill 刷新中止") {
+			t.Fatalf("home failure = %v", err)
+		}
+	})
+
+	t.Run("backup", func(t *testing.T) {
+		home, plan := canonicalFailurePlan(t)
+		victim := filepath.Join(plan.Targets[0].Destination, "dingtalk-chat")
+		if err := os.MkdirAll(victim, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		plan.Targets[0].Backups = []skillSetupBackup{{Path: victim, Reason: skillSetupBackupReplace}}
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) { return "", errors.New("backup denied") })
+		if _, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || !strings.Contains(err.Error(), "canonical Skill 备份失败") {
+			t.Fatalf("backup failure = %v", err)
+		}
+	})
+
+	t.Run("publish", func(t *testing.T) {
+		home, plan := canonicalFailurePlan(t)
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		testseam.Swap(t, &skillSetupPublishPath, func(string, string) (upgrade.SkillPathPublication, error) {
+			return upgrade.SkillPathPublication{}, errors.New("publish denied")
+		})
+		if _, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || !strings.Contains(err.Error(), "canonical Skill 发布失败") {
+			t.Fatalf("publish failure = %v", err)
+		}
+	})
+
+	t.Run("uncertain-publish", func(t *testing.T) {
+		home, plan := canonicalFailurePlan(t)
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		testseam.Swap(t, &skillSetupPublishPath, func(string, string) (upgrade.SkillPathPublication, error) {
+			return upgrade.SkillPathPublication{}, fmt.Errorf("并发写入: %w", upgrade.ErrSkillPathPublicationUncertain)
+		})
+		errOut := &bytes.Buffer{}
+		_, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, errOut)
+		if err == nil || !strings.Contains(err.Error(), "canonical Skill 发布状态不确定") {
+			t.Fatalf("uncertain publish = %v", err)
+		}
+		// The destination was deliberately retained, so the canonical error
+		// must not claim a rollback happened.
+		if strings.Contains(err.Error(), "回滚") {
+			t.Fatalf("uncertain error must not claim a rollback: %v", err)
+		}
+	})
+
+	t.Run("uncertain dependent target is retained and reported", func(t *testing.T) {
+		home, plan := canonicalFailurePlan(t)
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		originalPublish := skillSetupPublishPath
+		testseam.Swap(t, &skillSetupPublishPath, func(staged, destination string) (upgrade.SkillPathPublication, error) {
+			if strings.HasPrefix(destination, filepath.Join(home, ".claude")) {
+				return upgrade.SkillPathPublication{}, fmt.Errorf("并发写入: %w", upgrade.ErrSkillPathPublicationUncertain)
+			}
+			return originalPublish(staged, destination)
+		})
+		errOut := &bytes.Buffer{}
+		_, skipped, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, errOut)
+		if err != nil {
+			t.Fatalf("dependent uncertain publish = %v", err)
+		}
+		if skipped != 1 {
+			t.Fatalf("skipped = %d, want 1", skipped)
+		}
+		if !strings.Contains(errOut.String(), "发布状态不确定") || strings.Contains(errOut.String(), "已执行回滚") {
+			t.Fatalf("errOut = %q, want retained-destination notice", errOut.String())
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillSetupLinkResolutionFailures(t *testing.T) {
+	home, plan := canonicalFailurePlan(t)
+	canonicalTarget := filepath.Join(plan.Targets[0].Destination, "dingtalk-chat")
+	if err := os.MkdirAll(canonicalTarget, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(canonicalTarget, "SKILL.md"), []byte("chat"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	linked := plan.Targets[1]
+
+	t.Run("physical-parent", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupEvalSymlinks, func(path string) (string, error) {
+			if path == linked.Destination {
+				return "", errors.New("parent denied")
+			}
+			return filepath.EvalSymlinks(path)
+		})
+		if _, _, err := stageSkillSetupTarget(plan, linked); err == nil || !strings.Contains(err.Error(), "物理目录") {
+			t.Fatalf("physical parent error = %v", err)
+		}
+	})
+
+	t.Run("canonical-target", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupEvalSymlinks, func(path string) (string, error) {
+			if path == canonicalTarget {
+				return "", errors.New("canonical denied")
+			}
+			return filepath.EvalSymlinks(path)
+		})
+		if _, _, err := stageSkillSetupTarget(plan, linked); err == nil || !strings.Contains(err.Error(), "解析 canonical") {
+			t.Fatalf("canonical target error = %v", err)
+		}
+	})
+
+	t.Run("relative-path", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupRel, func(string, string) (string, error) { return "", errors.New("relative denied") })
+		if _, _, err := stageSkillSetupTarget(plan, linked); err == nil || !strings.Contains(err.Error(), "相对链接") {
+			t.Fatalf("relative path error = %v", err)
+		}
+	})
+
+	_ = home
+}

internal/app/skill_setup_canonical_test.go

@@ -0,0 +1,395 @@
+package app
+
+import (
+	"bytes"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageSkillSetupCanonicalTargetsAndAgentCapabilities(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupAgentHomes, []string{
+		".agents/skills", ".codex/skills", ".claude/skills", ".openclaw/skills",
+	})
+	for _, parent := range []string{".codex", ".claude", ".openclaw"} {
+		if err := os.MkdirAll(filepath.Join(home, parent), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	dests, err := resolveSkillSetupTargets("all", skillSetupModeMulti)
+	if err != nil {
+		t.Fatal(err)
+	}
+	canonical := filepath.Join(home, ".agents", "skills")
+	if len(dests) != 4 || dests[0] != canonical {
+		t.Fatalf("targets = %v", dests)
+	}
+
+	src := t.TempDir()
+	for _, name := range []string{"dingtalk-chat", "dingtalk-shared"} {
+		dir := filepath.Join(src, 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)
+		}
+	}
+	oldCodex := filepath.Join(home, ".codex", "skills", "dingtalk-chat")
+	if err := os.MkdirAll(oldCodex, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oldCodex, "SKILL.md"), []byte("beta.6"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	claudeSkills := filepath.Join(home, ".claude", "skills")
+	if err := os.MkdirAll(claudeSkills, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(claudeSkills, "dingtalk-chat"), []byte("unexpected file"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink("missing-target", filepath.Join(claudeSkills, "dingtalk-shared")); err != nil {
+		t.Fatal(err)
+	}
+
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, src, dests, []string{"dingtalk-chat", "dingtalk-shared"}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	installed, skipped, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{})
+	if err != nil || skipped != 0 || installed != 6 { // canonical + two linked Agents, two Skills each
+		t.Fatalf("execute = installed %d skipped %d err %v", installed, skipped, err)
+	}
+	if _, err := os.Lstat(oldCodex); !os.IsNotExist(err) {
+		t.Fatalf("Codex duplicate remains: %v", err)
+	}
+	for _, name := range []string{"dingtalk-chat", "dingtalk-shared"} {
+		if _, err := os.Stat(filepath.Join(canonical, name, "SKILL.md")); err != nil {
+			t.Fatalf("canonical %s missing: %v", name, err)
+		}
+		for _, agent := range []string{".claude", ".openclaw"} {
+			link := filepath.Join(home, agent, "skills", name)
+			info, err := os.Lstat(link)
+			if err != nil || info.Mode()&os.ModeSymlink == 0 {
+				t.Fatalf("link %s = %#v, %v", link, info, err)
+			}
+		}
+	}
+	// Re-running setup must recognize the existing links as already correct;
+	// canonical refreshes in place without turning links into copied trees.
+	plan, err = buildSkillSetupPlan(skillSetupModeMulti, src, dests, []string{"dingtalk-chat", "dingtalk-shared"}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{}); err != nil {
+		t.Fatal(err)
+	}
+	for _, agent := range []string{".claude", ".openclaw"} {
+		info, err := os.Lstat(filepath.Join(home, agent, "skills", "dingtalk-chat"))
+		if err != nil || info.Mode()&os.ModeSymlink == 0 {
+			t.Fatalf("idempotent setup replaced %s link: %#v, %v", agent, info, err)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupDetectsShallowAndApplicationAgents(t *testing.T) {
+	// Keep the destination HOME synthetic: app-bundle detection is deliberately
+	// machine-scoped and must not depend on the selected installation HOME.
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupGetenv, func(string) string { return "" })
+	for _, dir := range []string{filepath.Join(home, ".config", "kimchi"), filepath.Join(home, ".tabnine")} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	sentinel := filepath.Join(home, "app-sentinel")
+	if err := os.MkdirAll(sentinel, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	appInfo, err := os.Stat(sentinel)
+	if err != nil {
+		t.Fatal(err)
+	}
+	zcodeApp := filepath.Join(string(filepath.Separator), "Applications", "ZCode.app")
+	minimaxApp := filepath.Join(string(filepath.Separator), "Applications", "MiniMax Code.app")
+	originalStat := skillSetupStat
+	testseam.Swap(t, &skillSetupStat, func(path string) (os.FileInfo, error) {
+		if path == zcodeApp || path == minimaxApp {
+			return appInfo, nil
+		}
+		return originalStat(path)
+	})
+	dests := detectExistingAgentHomes(home, skillSetupModeMulti)
+	for _, target := range []string{
+		filepath.Join(home, ".config", "kimchi", "harness", "skills"),
+		filepath.Join(home, ".tabnine", "agent", "skills"),
+		filepath.Join(home, ".zcode", "skills"),
+		filepath.Join(home, ".minimax", "skills"),
+	} {
+		if !containsSkillName(dests, target) {
+			t.Errorf("detected targets %v missing %s", dests, target)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupCustomRootsAliasesAndUniversalTargets(t *testing.T) {
+	home := t.TempDir()
+	customClaude := filepath.Join(t.TempDir(), "claude")
+	customCodex := filepath.Join(t.TempDir(), "codex")
+	customHermes := filepath.Join(t.TempDir(), "hermes")
+	for _, root := range []string{customClaude, customCodex, customHermes, filepath.Join(home, ".moltbot"), filepath.Join(home, ".copilot"), filepath.Join(home, ".config", "opencode"), filepath.Join(home, ".config", "agents"), filepath.Join(home, ".codeium", "windsurf")} {
+		if err := os.MkdirAll(root, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupGetenv, func(name string) string {
+		switch name {
+		case "CLAUDE_CONFIG_DIR":
+			return customClaude
+		case "CODEX_HOME":
+			return customCodex
+		case "HERMES_HOME":
+			return customHermes
+		default:
+			return ""
+		}
+	})
+
+	dests, err := resolveSkillSetupTargets("all", skillSetupModeMulti)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{
+		filepath.Join(home, ".agents", "skills"),
+		filepath.Join(customClaude, "skills"),
+		filepath.Join(customCodex, "skills"),
+		filepath.Join(customHermes, "skills"),
+		filepath.Join(home, ".moltbot", "skills"),
+		filepath.Join(home, ".copilot", "skills"),
+		filepath.Join(home, ".config", "opencode", "skills"),
+		filepath.Join(home, ".config", "agents", "skills"),
+		filepath.Join(home, ".codeium", "windsurf", "skills"),
+	} {
+		found := false
+		for _, got := range dests {
+			if sameSkillSetupPath(got, want) {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("resolved targets %v missing %s", dests, want)
+		}
+	}
+	if !isUniversalSkillSetupBase(filepath.Join(customCodex, "skills")) || !isUniversalSkillSetupBase(filepath.Join(home, ".config", "opencode", "skills")) || !isUniversalSkillSetupBase(filepath.Join(home, ".config", "agents", "skills")) {
+		t.Fatal("custom Codex, OpenCode, and Amp must be universal cleanup-only targets")
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupCanonicalFailureStopsDependentTargets(t *testing.T) {
+	home := t.TempDir()
+	canonical := filepath.Join(home, ".agents", "skills")
+	claude := filepath.Join(home, ".claude", "skills")
+	if err := os.MkdirAll(claude, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	oldClaude := filepath.Join(claude, "dingtalk-chat")
+	if err := os.MkdirAll(oldClaude, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oldClaude, "SKILL.md"), []byte("old remains"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	src := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(src, "dingtalk-chat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "dingtalk-chat", "SKILL.md"), []byte("new"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, src, []string{canonical, claude}, []string{"dingtalk-chat"}, true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { return errors.New("canonical copy denied") })
+	if _, _, err := executeSkillSetupPlan(plan, &bytes.Buffer{}, &bytes.Buffer{}); err == nil || !strings.Contains(err.Error(), "canonical") {
+		t.Fatalf("canonical failure = %v", err)
+	}
+	body, readErr := os.ReadFile(filepath.Join(oldClaude, "SKILL.md"))
+	if readErr != nil || string(body) != "old remains" {
+		t.Fatalf("dependent Claude target changed: %q, %v", body, readErr)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupCanonicalCopyFallbackMessage(t *testing.T) {
+	home := t.TempDir()
+	canonical := filepath.Join(home, ".agents", "skills")
+	claude := filepath.Join(home, ".claude", "skills")
+	src := t.TempDir()
+	skillSrc := filepath.Join(src, "dingtalk-chat")
+	if err := os.MkdirAll(skillSrc, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(skillSrc, "SKILL.md"), []byte("chat"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupSymlink, func(string, string) error { return errors.New("links unavailable") })
+
+	plan, err := buildSkillSetupPlan(
+		skillSetupModeMulti,
+		src,
+		[]string{canonical, claude},
+		[]string{"dingtalk-chat"},
+		false,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out, errOut bytes.Buffer
+	installed, skipped, err := executeSkillSetupPlan(plan, &out, &errOut)
+	if err != nil || installed != 2 || skipped != 0 {
+		t.Fatalf("execute = installed %d skipped %d err %v", installed, skipped, err)
+	}
+	if !strings.Contains(errOut.String(), "自动改用兼容安装") {
+		t.Fatalf("human-readable fallback message missing: %s", errOut.String())
+	}
+	info, err := os.Lstat(filepath.Join(claude, "dingtalk-chat"))
+	if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		t.Fatalf("copy fallback = %#v, %v", info, err)
+	}
+}
+
+func TestCrossPlatformCoverageUpstreamAgentEnumerationAndEffectiveRoots(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillUserHomeDir, func() (string, error) { return home, nil })
+	testseam.Swap(t, &skillSetupGetenv, func(string) string { return "" })
+
+	expected := map[string]string{
+		"aider-desk": ".aider-desk/skills", "amp": ".config/agents/skills",
+		"antigravity": ".gemini/antigravity/skills", "antigravity-cli": ".gemini/antigravity-cli/skills",
+		"astrbot": ".astrbot/data/skills", "autohand-code": ".autohand/skills",
+		"augment": ".augment/skills", "bob": ".bob/skills", "claude-code": ".claude/skills",
+		"openclaw": ".openclaw/skills", "cline": ".agents/skills", "codearts-agent": ".codeartsdoer/skills",
+		"codebuddy": ".codebuddy/skills", "codemaker": ".codemaker/skills", "codestudio": ".codestudio/skills",
+		"codex": ".codex/skills", "command-code": ".commandcode/skills", "continue": ".continue/skills",
+		"cortex": ".snowflake/cortex/skills", "crush": ".config/crush/skills", "cursor": ".cursor/skills",
+		"deepagents": ".deepagents/agent/skills", "devin": ".config/devin/skills", "dexto": ".agents/skills",
+		"droid": ".factory/skills", "firebender": ".firebender/skills", "forgecode": ".forge/skills",
+		"gemini-cli": ".gemini/skills", "github-copilot": ".copilot/skills", "goose": ".config/goose/skills",
+		"grok": ".grok/skills", "hermes-agent": ".hermes/skills", "inference-sh": ".inferencesh/skills",
+		"jazz": ".jazz/skills", "junie": ".junie/skills", "iflow-cli": ".iflow/skills",
+		"kilo": ".kilocode/skills", "kimchi": ".config/kimchi/harness/skills", "kimi-code-cli": ".agents/skills",
+		"kiro-cli": ".kiro/skills", "kode": ".kode/skills", "lingma": ".lingma/skills", "loaf": ".agents/skills",
+		"mcpjam": ".mcpjam/skills", "minimax-code": ".minimax/skills", "mistral-vibe": ".vibe/skills",
+		"moxby": ".moxby/skills", "mux": ".mux/skills", "opencode": ".config/opencode/skills",
+		"openhands": ".openhands/skills", "ona": ".ona/skills", "pi": ".pi/agent/skills",
+		"qoder": ".qoder/skills", "qoder-cn": ".qoder-cn/skills", "qwen-code": ".qwen/skills",
+		"replit": ".config/agents/skills", "reasonix": ".reasonix/skills", "rovodev": ".rovodev/skills",
+		"roo": ".roo/skills", "tabnine-cli": ".tabnine/agent/skills", "terramind": ".terramind/skills",
+		"tinycloud": ".tinycloud/skills", "trae": ".trae/skills", "trae-cn": ".trae-cn/skills",
+		"universal": ".config/agents/skills", "warp": ".agents/skills", "windsurf": ".codeium/windsurf/skills",
+		"zed": ".agents/skills", "zcode": ".zcode/skills", "zencoder": ".zencoder/skills",
+		"zenflow": ".zencoder/skills", "neovate": ".neovate/skills", "pochi": ".pochi/skills", "adal": ".adal/skills",
+	}
+	if got := len(expected) + len(unsupportedGlobalAgentTargets); got != 76 {
+		t.Fatalf("upstream agent enumeration = %d, want 76", got)
+	}
+	for target, rel := range expected {
+		mapped, ok := agentSkillPaths[target]
+		if !ok || filepath.Clean(mapped) != filepath.Clean(rel) {
+			t.Errorf("agent %s map = %q, want %q", target, mapped, rel)
+		}
+		if got := resolveSkillSetupBase(home, target); !sameSkillSetupPath(got, filepath.Join(home, filepath.FromSlash(rel))) {
+			t.Errorf("agent %s effective root = %q, want %q", target, got, filepath.Join(home, rel))
+		}
+	}
+	for _, target := range []string{"eve", "promptscript"} {
+		if _, err := resolveSkillSetupTargets(target, skillSetupModeMulti); err == nil {
+			t.Errorf("%s unexpectedly resolved a global setup root", target)
+		}
+		if _, err := resolveSkillTargetPath(target); err == nil {
+			t.Errorf("%s unexpectedly resolved a marketplace install root", target)
+		}
+	}
+	if got := supportedTargets(); !strings.Contains(got, "eve") || !strings.Contains(got, "promptscript") {
+		t.Fatalf("supported targets omit no-global upstream agents: %s", got)
+	}
+
+	custom := map[string]string{
+		"AUTOHAND_HOME": filepath.Join(home, "autohand-home"), "CLAUDE_CONFIG_DIR": filepath.Join(home, "claude-home"),
+		"CODEX_HOME": filepath.Join(home, "codex-home"), "GROK_HOME": filepath.Join(home, "grok-home"),
+		"HERMES_HOME": filepath.Join(home, "hermes-home"), "VIBE_HOME": filepath.Join(home, "vibe-home"),
+		"XDG_CONFIG_HOME": filepath.Join(home, "xdg"),
+	}
+	testseam.Swap(t, &skillSetupGetenv, func(name string) string { return custom[name] })
+	customCases := map[string]string{
+		"autohand-code": filepath.Join(custom["AUTOHAND_HOME"], "skills"),
+		"claude-code":   filepath.Join(custom["CLAUDE_CONFIG_DIR"], "skills"),
+		"codex":         filepath.Join(custom["CODEX_HOME"], "skills"),
+		"grok":          filepath.Join(custom["GROK_HOME"], "skills"),
+		"hermes-agent":  filepath.Join(custom["HERMES_HOME"], "skills"),
+		"mistral-vibe":  filepath.Join(custom["VIBE_HOME"], "skills"),
+		"amp":           filepath.Join(custom["XDG_CONFIG_HOME"], "agents", "skills"),
+		"replit":        filepath.Join(custom["XDG_CONFIG_HOME"], "agents", "skills"),
+		"universal":     filepath.Join(custom["XDG_CONFIG_HOME"], "agents", "skills"),
+		"crush":         filepath.Join(custom["XDG_CONFIG_HOME"], "crush", "skills"),
+		"devin":         filepath.Join(custom["XDG_CONFIG_HOME"], "devin", "skills"),
+		"goose":         filepath.Join(custom["XDG_CONFIG_HOME"], "goose", "skills"),
+		"kimchi":        filepath.Join(custom["XDG_CONFIG_HOME"], "kimchi", "harness", "skills"),
+		"opencode":      filepath.Join(custom["XDG_CONFIG_HOME"], "opencode", "skills"),
+	}
+	for target, want := range customCases {
+		if got := resolveSkillSetupBase(home, target); !sameSkillSetupPath(got, want) {
+			t.Errorf("custom %s root = %q, want %q", target, got, want)
+		}
+	}
+	for _, target := range []string{"codex", "amp", "opencode"} {
+		if !isUniversalSkillSetupBase(resolveSkillSetupBase(home, target)) {
+			t.Errorf("custom %s root not classified universal", target)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageOpenClawAliasPriority(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		dirs []string
+		want string
+	}{
+		{name: "default", want: ".openclaw"},
+		{name: "moltbot", dirs: []string{".moltbot"}, want: ".moltbot"},
+		{name: "clawdbot-before-moltbot", dirs: []string{".moltbot", ".clawdbot"}, want: ".clawdbot"},
+		{name: "openclaw-first", dirs: []string{".moltbot", ".clawdbot", ".openclaw"}, want: ".openclaw"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			for _, dir := range tc.dirs {
+				if err := os.MkdirAll(filepath.Join(home, dir), 0o755); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if got := resolveOpenClawSetupBase(home); got != filepath.Join(home, tc.want, "skills") {
+				t.Fatalf("OpenClaw root = %q", got)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupWindowsPathNormalization(t *testing.T) {
+	testseam.Swap(t, &skillSetupFoldPathCase, true)
+	if !sameSkillSetupPath(filepath.Join("Root", "Skills"), filepath.Join("root", "skills")) {
+		t.Fatal("case-insensitive platform path normalization failed")
+	}
+}

internal/app/skill_setup_cleanup_coverage_test.go

@@ -15,6 +15,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillprovenance"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/skillstate"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
 )
 
 func useManagedSkillNames(t *testing.T, names ...string) {
@@ -336,12 +337,12 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailuresRestoreOldSet(t *test
 					return originalBackup(homeDir, dir)
 				})
 			} else {
-				originalRename := skillSetupPublishRename
-				testseam.Swap(t, &skillSetupPublishRename, func(oldPath, newPath string) error {
+				originalPublish := skillSetupPublishPath
+				testseam.Swap(t, &skillSetupPublishPath, func(oldPath, newPath string) (upgrade.SkillPathPublication, error) {
 					if newPath == second && strings.HasPrefix(filepath.Base(filepath.Dir(oldPath)), ".dws-setup-set-") {
-						return failure
+						return upgrade.SkillPathPublication{}, failure
 					}
-					return originalRename(oldPath, newPath)
+					return originalPublish(oldPath, newPath)
 				})
 			}
 
@@ -432,8 +433,8 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 
 	t.Run("restore failure aggregation", func(t *testing.T) {
 		t.Run("remove published", func(t *testing.T) {
-			testseam.Swap(t, &skillSetupRemoveAll, func(string) error { return failure })
-			if err := restoreSkillSetupTarget([]string{"published"}, nil); !errors.Is(err, failure) {
+			testseam.Swap(t, &skillSetupRollbackPaths, func([]upgrade.SkillPathPublication) error { return failure })
+			if err := restoreSkillSetupTarget([]upgrade.SkillPathPublication{{Destination: "published"}}, nil); !errors.Is(err, failure) {
 				t.Fatalf("remove published error = %v", err)
 			}
 		})
@@ -445,14 +446,14 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 			}
 		})
 		t.Run("stat", func(t *testing.T) {
-			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, failure })
+			testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, failure })
 			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
 			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "检查 Skill 恢复目标失败") {
 				t.Fatalf("restore stat error = %v", err)
 			}
 		})
 		t.Run("mkdir", func(t *testing.T) {
-			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+			testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
 			testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return failure })
 			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
 			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "创建 Skill 恢复目录失败") {
@@ -460,9 +461,9 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 			}
 		})
 		t.Run("rename", func(t *testing.T) {
-			testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+			testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
 			testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
-			testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return failure })
+			testseam.Swap(t, &skillSetupRestoreBackup, func(string, string) error { return failure })
 			err := restoreSkillSetupTarget(nil, []skillSetupBackedUpDir{{original: "original", backup: "backup"}})
 			if !errors.Is(err, failure) || !strings.Contains(err.Error(), "恢复原 Skill 失败") {
 				t.Fatalf("restore rename error = %v", err)
@@ -479,10 +480,10 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 			}
 			return "", failure
 		})
-		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+		testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
 		testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
 		restoreErr := errors.New("restore failure")
-		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return restoreErr })
+		testseam.Swap(t, &skillSetupRestoreBackup, func(string, string) error { return restoreErr })
 		_, err := backupSkillSetupTarget("home", []skillSetupBackup{{Path: "first"}, {Path: "second"}}, io.Discard)
 		if !errors.Is(err, failure) || !errors.Is(err, restoreErr) {
 			t.Fatalf("backup rollback error = %v", err)
@@ -490,8 +491,11 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 	})
 
 	t.Run("publish rollback failure", func(t *testing.T) {
-		testseam.Swap(t, &skillSetupPublishRename, func(string, string) error { return failure })
-		testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+		testseam.Swap(t, &skillSetupPublishPath, func(string, string) (upgrade.SkillPathPublication, error) {
+			return upgrade.SkillPathPublication{}, failure
+		})
+		testseam.Swap(t, &skillSetupRestoreBackup, func(string, string) error { return failure })
+		testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
 		testseam.Swap(t, &skillSetupMkdirAll, func(string, os.FileMode) error { return nil })
 		err := publishSkillSetupTarget(
 			[]skillSetupStagedDir{{staged: "staged", dest: "dest"}},
@@ -530,12 +534,12 @@ func TestCrossPlatformCoverageSkillSetupTransactionFailureEdges(t *testing.T) {
 
 		t.Run("after publish failure", func(t *testing.T) {
 			plan := newPlan(t)
-			originalRename := skillSetupPublishRename
-			testseam.Swap(t, &skillSetupPublishRename, func(oldPath, newPath string) error {
+			originalPublish := skillSetupPublishPath
+			testseam.Swap(t, &skillSetupPublishPath, func(oldPath, newPath string) (upgrade.SkillPathPublication, error) {
 				if strings.HasPrefix(filepath.Base(filepath.Dir(oldPath)), ".dws-setup-set-") {
-					return failure
+					return upgrade.SkillPathPublication{}, failure
 				}
-				return originalRename(oldPath, newPath)
+				return originalPublish(oldPath, newPath)
 			})
 			originalRemoveAll := skillSetupRemoveAll
 			cleanupErr := errors.New("cleanup after publish failure")

internal/app/skill_setup_event_migration_universal_test.go

@@ -0,0 +1,139 @@
+package app
+
+import (
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// TestCrossPlatformCoverageSkillSetupEventMigrationRetiresUniversalFoldedCopies
+// pins the P0 fix: when a beta.6 folded dingtalk-misc (carrying the personal
+// Event route) exists only in a UNIVERSAL agent home (~/.codex/skills), the
+// Event/misc migration must not leave physical duplicates there. Universal
+// homes read ~/.agents/skills directly, so their old folded copies are retired
+// (backed up) and the split standalone event + clean misc land in canonical.
+func TestCrossPlatformCoverageSkillSetupEventMigrationRetiresUniversalFoldedCopies(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+
+	codexSkills := filepath.Join(home, ".codex", "skills")
+	writeFoldedEventMisc(t, codexSkills)
+	// beta.6 physical copies alongside the folded misc.
+	for _, name := range []string{multiEventSkill, multiSharedSkill} {
+		if err := os.MkdirAll(filepath.Join(codexSkills, name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(codexSkills, name, "SKILL.md"), []byte("beta6 "+name+"\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	canonical := filepath.Join(home, ".agents", "skills")
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{canonical, codexSkills}, "--skill", "event", "--yes")
+	if err != nil {
+		t.Fatalf("setup failed: %v\nstderr=%s\nstdout=%s", err, stderr, stdout)
+	}
+
+	// P0: the universal home must not retain any physical dingtalk-* copy.
+	for _, name := range []string{multiEventSkill, multiMiscSkill, multiSharedSkill} {
+		if _, err := os.Stat(filepath.Join(codexSkills, name)); !os.IsNotExist(err) {
+			t.Fatalf("universal .codex/skills still has physical %s (stat err=%v)", name, err)
+		}
+	}
+	// canonical owns the new standalone event + clean misc (+ shared).
+	for _, name := range []string{multiEventSkill, multiMiscSkill, multiSharedSkill} {
+		if _, err := os.Stat(filepath.Join(canonical, name, "SKILL.md")); err != nil {
+			t.Fatalf("canonical missing %s: %v", name, err)
+		}
+	}
+	if err := validateCleanEventMiscRoot(filepath.Join(canonical, multiMiscSkill)); err != nil {
+		t.Fatalf("canonical misc still contains folded Event content: %v", err)
+	}
+	if _, _, err := executeMultiSkillSetupTest(t, src, []string{canonical, codexSkills}, "--skill", "event", "--yes"); err != nil {
+		t.Fatalf("idempotent rerun failed: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupUnrelatedSelectionPreservesUniversalFoldedPair(t *testing.T) {
+	home := t.TempDir()
+	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+	canonical := filepath.Join(home, ".agents", "skills")
+	codexSkills := filepath.Join(home, ".codex", "skills")
+	writeFoldedEventMisc(t, codexSkills)
+	writeOldStandaloneEvent(t, codexSkills)
+	chat := filepath.Join(codexSkills, "dingtalk-chat")
+	if err := os.MkdirAll(chat, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(chat, "SKILL.md"), []byte("keep chat\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill, "dingtalk-doc"})
+	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{canonical, codexSkills}, "--skill", "doc", "--yes")
+	if err != nil {
+		t.Fatalf("selective doc install failed: %v\nstdout=%s\nstderr=%s", err, stdout, stderr)
+	}
+	if strings.Contains(stdout, "Event 原子迁移") {
+		t.Fatalf("unrelated selection migrated Event/misc: %s", stdout)
+	}
+	assertOldEventMiscPair(t, codexSkills)
+	if body, err := os.ReadFile(filepath.Join(chat, "SKILL.md")); err != nil || string(body) != "keep chat\n" {
+		t.Fatalf("unselected chat changed: body=%q err=%v", body, err)
+	}
+}
+
+func TestCrossPlatformCoverageSkillSetupUniversalRetirementFailures(t *testing.T) {
+	failure := errors.New("retirement denied")
+
+	t.Run("home", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", failure })
+		codex := filepath.Join(t.TempDir(), ".codex", "skills")
+		if err := retireMigratedUniversalSkills([]string{codex}, []string{multiEventSkill}, io.Discard); !errors.Is(err, failure) {
+			t.Fatalf("home failure = %v, want %v", err, failure)
+		}
+	})
+
+	t.Run("deduplicate", func(t *testing.T) {
+		home := t.TempDir()
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		codex := filepath.Join(home, ".codex", "skills")
+		if err := retireMigratedUniversalSkills(
+			[]string{codex, codex},
+			[]string{multiEventSkill, multiEventSkill},
+			io.Discard,
+		); err != nil {
+			t.Fatalf("deduplicated retirement failed: %v", err)
+		}
+	})
+
+	// Retiring an obsolete universal copy installs nothing, so its failure is
+	// surfaced as a warning and the successful installation is kept.
+	t.Run("backup failure warns without failing the command", func(t *testing.T) {
+		home := t.TempDir()
+		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return home, nil })
+		codex := filepath.Join(home, ".codex", "skills")
+		writeFoldedEventMisc(t, codex)
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiSharedSkill, multiMiscSkill})
+		testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) {
+			return "", failure
+		})
+		_, stderr, err := executeMultiSkillSetupTest(
+			t,
+			src,
+			[]string{filepath.Join(home, ".agents", "skills"), codex},
+			"--skill", "event", "--yes",
+		)
+		if err != nil {
+			t.Fatalf("retirement backup failure must not fail the command: %v", err)
+		}
+		if !strings.Contains(stderr, "退役 universal Agent") {
+			t.Fatalf("retirement backup failure must be reported, stderr = %q", stderr)
+		}
+	})
+}

internal/app/skill_setup_full_coverage_test.go

@@ -523,15 +523,45 @@ func TestCrossPlatformCoverageSkillSetupEventMigrationFailureBranches(t *testing
 		}
 	})
 
-	t.Run("ordinary and prerequisite install errors", func(t *testing.T) {
+	t.Run("ordinary install error", func(t *testing.T) {
+		src := writeMultiSkillSource(t, []string{multiEventSkill, multiMiscSkill})
+		copyCalls := 0
+		testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { copyCalls++; return fail })
+		migration := filepath.Join(t.TempDir(), "migration")
+		ordinary := filepath.Join(t.TempDir(), "ordinary")
+		if _, _, err := installMultiSkillsWithEventMigration(src, []string{multiEventSkill}, []string{migration, ordinary}, []string{migration}, true, io.Discard, io.Discard); err == nil || !strings.Contains(err.Error(), "未执行迁移") {
+			t.Fatalf("ordinary install failure = %v", err)
+		}
+		if copyCalls == 0 {
+			t.Fatal("ordinary staging failure seam was not exercised")
+		}
+	})
+
+	t.Run("canonical ordinary install error", func(t *testing.T) {
+		testseam.Swap(t, &skillSetupInstallMulti, func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) {
+			return 0, 0, fail
+		})
+		home := t.TempDir()
+		canonical := filepath.Join(home, ".agents", "skills")
+		universalMigration := filepath.Join(home, ".codex", "skills")
+		if _, _, err := installMultiSkillsWithEventMigration(
+			"src",
+			[]string{multiEventSkill},
+			[]string{canonical, universalMigration},
+			[]string{universalMigration},
+			true,
+			io.Discard,
+			io.Discard,
+		); !errors.Is(err, fail) {
+			t.Fatalf("canonical ordinary install failure = %v, want %v", err, fail)
+		}
+	})
+
+	t.Run("prerequisite install error", func(t *testing.T) {
 		testseam.Swap(t, &skillSetupInstallMulti, func(string, []string, []string, io.Writer, io.Writer, bool) (int, int, error) {
 			return 0, 0, fail
 		})
 		migration := filepath.Join(t.TempDir(), "migration")
-		ordinary := filepath.Join(t.TempDir(), "ordinary")
-		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill}, []string{migration, ordinary}, []string{migration}, true, io.Discard, io.Discard); !errors.Is(err, fail) {
-			t.Fatalf("ordinary install failure = %v", err)
-		}
 		if _, _, err := installMultiSkillsWithEventMigration("src", []string{multiEventSkill, multiMiscSkill, multiSharedSkill}, []string{migration}, []string{migration}, true, io.Discard, io.Discard); !errors.Is(err, fail) {
 			t.Fatalf("prerequisite install failure = %v", err)
 		}

internal/app/skill_setup_plan_test.go

@@ -48,16 +48,13 @@ func TestCrossPlatformCoverageSkillSetupPlanPreviewDeclineAndExecutionMatch(t *t
 	backupCalls, copyCalls := []string{}, 0
 	testseam.Swap(t, &skillSetupBackupAndRemove, func(_ string, path string) (string, error) {
 		backupCalls = append(backupCalls, path)
+		if err := os.RemoveAll(path); err != nil {
+			return "", err
+		}
 		return "backup", nil
 	})
 	testseam.Swap(t, &skillSetupCopyDir, func(string, string) error { copyCalls++; return nil })
 	testseam.Swap(t, &skillSetupWriteFile, func(string, []byte, os.FileMode) error { return nil })
-	testseam.Swap(t, &skillSetupPublishRename, func(src, dest string) error {
-		if err := os.RemoveAll(dest); err != nil {
-			return err
-		}
-		return os.Rename(src, dest)
-	})
 	dryRunCmd := skillSetupCoverageCommand(t, skillSetupModeMulti, false)
 	var dryRunOut bytes.Buffer
 	dryRunCmd.SetOut(&dryRunOut)
@@ -119,6 +116,9 @@ func TestCrossPlatformCoverageSkillSetupPlanPreviewDeclineAndExecutionMatch(t *t
 
 	// A filtered multi plan replaces only selected same-name skills and leaves
 	// unselected siblings out of the backup set.
+	if err := os.MkdirAll(filepath.Join(dest, "dws"), 0o755); err != nil {
+		t.Fatal(err)
+	}
 	filtered, err := buildSkillSetupPlan(skillSetupModeMulti, source, []string{dest}, []string{"dingtalk-a"}, true)
 	if err != nil {
 		t.Fatal(err)
@@ -149,55 +149,38 @@ func TestCrossPlatformCoverageSkillSetupMonoPlanIncludesSameNameTarget(t *testin
 func TestCrossPlatformCoverageSkillSetupGenericCleanupDerivesHomeFromConcreteTarget(t *testing.T) {
 	home := t.TempDir()
 	dest := filepath.Join(home, ".codex", "skills")
-	genericMono := filepath.Join(home, ".agents", "skills", "dws")
-	if err := os.MkdirAll(genericMono, 0o755); err != nil {
+	canonical := filepath.Join(home, ".agents", "skills")
+	oldCodex := filepath.Join(dest, "dingtalk-chat")
+	if err := os.MkdirAll(oldCodex, 0o755); err != nil {
 		t.Fatal(err)
 	}
 	testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) {
 		return "", errors.New("transient HOME failure")
 	})
 
-	plan, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-chat"}, true)
+	plan, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{canonical, dest}, []string{"dingtalk-chat"}, true)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if len(plan.Targets) != 2 || !plan.Targets[1].CleanupOnly || plan.Targets[1].Destination != filepath.Dir(genericMono) {
-		t.Fatalf("generic cleanup target = %#v", plan.Targets)
+	if len(plan.Targets) != 2 || !plan.Targets[1].CleanupOnly || plan.Targets[1].Destination != dest {
+		t.Fatalf("universal cleanup target = %#v", plan.Targets)
 	}
-	if len(plan.Targets[1].Backups) != 1 || plan.Targets[1].Backups[0].Path != genericMono {
-		t.Fatalf("generic cleanup backups = %#v", plan.Targets[1].Backups)
+	if len(plan.Targets[1].Backups) != 1 || plan.Targets[1].Backups[0].Path != oldCodex {
+		t.Fatalf("universal cleanup backups = %#v", plan.Targets[1].Backups)
 	}
 	var preview bytes.Buffer
 	renderSkillSetupPlan(&preview, plan)
-	if !strings.Contains(preview.String(), "仅迁移旧的通用 DWS 副本") {
-		t.Fatalf("generic cleanup preview missing: %s", preview.String())
+	if !strings.Contains(preview.String(), "改用统一安装位置") {
+		t.Fatalf("universal cleanup preview missing: %s", preview.String())
 	}
 
-	t.Run("managed multi and scan failure", func(t *testing.T) {
-		managedDir := filepath.Join(home, ".agents", "skills", "dingtalk-chat")
-		if err := os.MkdirAll(managedDir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-		target, targetErr := genericSkillCleanupTarget([]string{dest}, map[string]bool{"dingtalk-chat": true})
-		if targetErr != nil || target == nil || len(target.Backups) != 2 {
-			t.Fatalf("managed generic cleanup = %#v, %v", target, targetErr)
-		}
-		failure := errors.New("generic scan failure")
-		testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, failure })
-		if _, targetErr := genericSkillCleanupTarget([]string{dest}, nil); !errors.Is(targetErr, failure) {
-			t.Fatalf("generic scan error = %v", targetErr)
-		}
-		if _, planErr := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-chat"}, true); !errors.Is(planErr, failure) {
-			t.Fatalf("generic cleanup plan error = %v", planErr)
-		}
-	})
 }
 
 func TestCrossPlatformCoverageSkillSetupCleanupOnlyExecutionBranches(t *testing.T) {
 	failure := errors.New("cleanup failure")
 	cleanup := skillSetupTargetPlan{Destination: "generic", CleanupOnly: true, Backups: []skillSetupBackup{{Path: "old"}}}
 
-	t.Run("prior skip suppresses cleanup", func(t *testing.T) {
+	t.Run("cleanup runs even after an install skip", func(t *testing.T) {
 		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return t.TempDir(), nil })
 		plan := &skillSetupPlan{Mode: skillSetupModeMono, Source: "missing", Targets: []skillSetupTargetPlan{{Destination: "install"}, cleanup}}
 		installed, skipped, err := executeSkillSetupPlan(plan, io.Discard, io.Discard)
@@ -206,11 +189,14 @@ func TestCrossPlatformCoverageSkillSetupCleanupOnlyExecutionBranches(t *testing.
 		}
 	})
 
+	// A cleanup-only target installs nothing, so its failure is a warning and
+	// must never increment skipped — runSkillSetup turns any skipped count into
+	// a hard error and would fail an otherwise complete installation.
 	t.Run("home failure keeps generic copy", func(t *testing.T) {
 		testseam.Swap(t, &skillSetupUserHomeDir, func() (string, error) { return "", failure })
 		var stderr bytes.Buffer
 		_, skipped, err := executeSkillSetupPlan(&skillSetupPlan{Mode: skillSetupModeMono, Targets: []skillSetupTargetPlan{cleanup}}, io.Discard, &stderr)
-		if err != nil || skipped != 1 || !strings.Contains(stderr.String(), "保留通用 Skill 副本") {
+		if err != nil || skipped != 0 || !strings.Contains(stderr.String(), "保留 universal Agent 旧副本") {
 			t.Fatalf("cleanup HOME failure = (%d, %v, %q)", skipped, err, stderr.String())
 		}
 	})
@@ -220,7 +206,7 @@ func TestCrossPlatformCoverageSkillSetupCleanupOnlyExecutionBranches(t *testing.
 		testseam.Swap(t, &skillSetupBackupAndRemove, func(string, string) (string, error) { return "", failure })
 		var stderr bytes.Buffer
 		_, skipped, err := executeSkillSetupPlan(&skillSetupPlan{Mode: skillSetupModeMono, Targets: []skillSetupTargetPlan{cleanup}}, io.Discard, &stderr)
-		if err != nil || skipped != 1 || !strings.Contains(stderr.String(), "迁移失败") {
+		if err != nil || skipped != 0 || !strings.Contains(stderr.String(), "迁移失败") {
 			t.Fatalf("cleanup backup failure = (%d, %v, %q)", skipped, err, stderr.String())
 		}
 	})
@@ -247,11 +233,13 @@ func TestCrossPlatformCoverageSkillSetupPlanDeduplicatesAndFailsClosed(t *testin
 		t.Fatal(err)
 	}
 	testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, failure })
+	testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, failure })
 	if _, err := buildSkillSetupPlan(skillSetupModeMono, "source", []string{monoDest}, nil, false); err == nil || !strings.Contains(err.Error(), "\u68c0\u67e5\u5c06\u88ab\u66ff\u6362") {
 		t.Fatalf("replacement stat error = %v", err)
 	}
 
 	testseam.Swap(t, &skillSetupStat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
+	testseam.Swap(t, &skillSetupLstat, func(string) (os.FileInfo, error) { return nil, os.ErrNotExist })
 	testseam.Swap(t, &skillSetupReadDir, func(string) ([]os.DirEntry, error) { return nil, failure })
 	if _, err := buildSkillSetupPlan(skillSetupModeMulti, "source", []string{dest}, []string{"dingtalk-a"}, false); err == nil || !strings.Contains(err.Error(), "\u626b\u63cf\u8fc7\u671f") {
 		t.Fatalf("stale scan error = %v", err)

internal/app/skill_setup_publication_race_test.go

@@ -0,0 +1,85 @@
+package app
+
+import (
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/upgrade"
+)
+
+func TestCrossPlatformCoverageSkillSetupRollbackRetainsConcurrentReplacement(t *testing.T) {
+	home := t.TempDir()
+	base := filepath.Join(home, ".agents", "skills")
+	first := filepath.Join(base, "dingtalk-first")
+	second := filepath.Join(base, "dingtalk-second")
+	writeSkillSetupFile(t, first, "old first")
+	writeSkillSetupFile(t, second, "old second")
+	backups, err := backupSkillSetupTarget(home, []skillSetupBackup{{Path: first}, {Path: second}}, io.Discard)
+	if err != nil {
+		t.Fatal(err)
+	}
+	stageRoot := filepath.Join(base, ".stage")
+	stagedFirst := filepath.Join(stageRoot, "dingtalk-first")
+	stagedSecond := filepath.Join(stageRoot, "dingtalk-second")
+	writeSkillSetupFile(t, stagedFirst, "new first")
+	writeSkillSetupFile(t, stagedSecond, "new second")
+
+	failure := errors.New("injected second setup publication failure")
+	originalPublish := skillSetupPublishPath
+	calls := 0
+	testseam.Swap(t, &skillSetupPublishPath, func(staged, destination string) (upgrade.SkillPathPublication, error) {
+		calls++
+		if calls == 2 {
+			if err := os.RemoveAll(first); err != nil {
+				t.Fatal(err)
+			}
+			writeSkillSetupFile(t, first, "concurrent")
+			return upgrade.SkillPathPublication{}, failure
+		}
+		return originalPublish(staged, destination)
+	})
+
+	err = publishSkillSetupTarget([]skillSetupStagedDir{
+		{staged: stagedFirst, dest: first},
+		{staged: stagedSecond, dest: second},
+	}, backups)
+	if !errors.Is(err, failure) || !strings.Contains(err.Error(), "拒绝删除非本事务") {
+		t.Fatalf("setup transaction error = %v", err)
+	}
+	assertSkillSetupFile(t, first, "concurrent")
+	assertSkillSetupFile(t, second, "old second")
+	var firstBackup string
+	for _, item := range backups {
+		if item.original == first {
+			firstBackup = item.backup
+			break
+		}
+	}
+	if firstBackup == "" {
+		t.Fatal("first backup was not recorded")
+	}
+	assertSkillSetupFile(t, firstBackup, "old first")
+}
+
+func writeSkillSetupFile(t *testing.T, dir, content string) {
+	t.Helper()
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func assertSkillSetupFile(t *testing.T, dir, want string) {
+	t.Helper()
+	content, err := os.ReadFile(filepath.Join(dir, "SKILL.md"))
+	if err != nil || string(content) != want {
+		t.Fatalf("Skill content at %s = %q, %v; want %q", dir, content, err, want)
+	}
+}

internal/app/skill_setup_test.go

@@ -297,12 +297,12 @@ func TestResolveSkillSetupTargetsSingleAgent(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected err: %v", err)
 	}
-	if len(got) != 1 {
-		t.Fatalf("expected 1 dest, got %d", len(got))
+	if len(got) != 2 {
+		t.Fatalf("expected canonical + Claude, got %d", len(got))
 	}
 	want := filepath.Join(home, ".claude", "skills", "dws")
-	if filepath.Clean(got[0]) != filepath.Clean(want) {
-		t.Fatalf("expected %s, got %s", want, got[0])
+	if filepath.Clean(got[1]) != filepath.Clean(want) {
+		t.Fatalf("expected %s, got %s", want, got[1])
 	}
 }
 
@@ -321,12 +321,12 @@ func TestResolveSkillSetupTargetsMultiOmitsDwsTail(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected err: %v", err)
 	}
-	if len(got) != 1 {
-		t.Fatalf("expected 1 dest, got %d", len(got))
+	if len(got) != 2 {
+		t.Fatalf("expected canonical + Claude, got %d", len(got))
 	}
 	want := filepath.Join(home, ".claude", "skills")
-	if filepath.Clean(got[0]) != filepath.Clean(want) {
-		t.Fatalf("expected %s, got %s", want, got[0])
+	if filepath.Clean(got[1]) != filepath.Clean(want) {
+		t.Fatalf("expected %s, got %s", want, got[1])
 	}
 }
 
@@ -343,8 +343,8 @@ func TestCrossPlatformCoverageResolveSkillSetupTargetsPrefersSpecificAgentRoot(t
 		t.Fatal(err)
 	}
 	want := filepath.Join(home, ".codex", "skills")
-	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(want) {
-		t.Fatalf("targets = %v, want [%s]", got, want)
+	if len(got) != 2 || filepath.Clean(got[1]) != filepath.Clean(want) {
+		t.Fatalf("targets = %v, want canonical + %s", got, want)
 	}
 }
 
@@ -360,8 +360,8 @@ func TestCrossPlatformCoverageResolveSkillSetupTargetsDetectsZCode(t *testing.T)
 		t.Fatal(err)
 	}
 	want := filepath.Join(home, ".zcode", "skills")
-	if len(got) != 1 || filepath.Clean(got[0]) != filepath.Clean(want) {
-		t.Fatalf("targets = %v, want [%s]", got, want)
+	if len(got) != 2 || filepath.Clean(got[1]) != filepath.Clean(want) {
+		t.Fatalf("targets = %v, want canonical + %s", got, want)
 	}
 
 	explicit, err := resolveSkillSetupTargets("zcode", skillSetupModeMono)
@@ -369,8 +369,8 @@ func TestCrossPlatformCoverageResolveSkillSetupTargetsDetectsZCode(t *testing.T)
 		t.Fatal(err)
 	}
 	wantMono := filepath.Join(want, "dws")
-	if len(explicit) != 1 || filepath.Clean(explicit[0]) != filepath.Clean(wantMono) {
-		t.Fatalf("explicit zcode targets = %v, want [%s]", explicit, wantMono)
+	if len(explicit) != 2 || filepath.Clean(explicit[1]) != filepath.Clean(wantMono) {
+		t.Fatalf("explicit zcode targets = %v, want canonical + %s", explicit, wantMono)
 	}
 }
 
@@ -1055,12 +1055,11 @@ func TestCrossPlatformCoverageSkillSetupSelectiveEventMigratesOnlyFoldedTargets(
 	if err := os.WriteFile(filepath.Join(foldedHome, "dingtalk-chat", "SKILL.md"), []byte("keep sibling\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-
 	stdout, stderr, err := executeMultiSkillSetupTest(t, src, []string{freshHome, foldedHome}, "--skill", "event", "--yes")
 	if err != nil {
 		t.Fatalf("selective event setup failed: %v\nstderr=%s\nstdout=%s", err, stderr, stdout)
 	}
-	if !strings.Contains(stdout, "重新加载 Skills") {
+	if !strings.Contains(stdout, "请重启已打开的 Agent") {
 		t.Fatalf("completion should tell the user to reload skills: %s", stdout)
 	}
 

internal/app/upgrade.go

@@ -620,6 +620,9 @@ func runUpgrade(ctx context.Context, opts upgradeOptions) error {
 		for _, d := range succeeded {
 			fmt.Printf("         %s %s\n", ugDim("→"), ugCyan(shortenHome(d.Dir)))
 		}
+		for _, d := range result.RetireWarnings() {
+			fmt.Printf("       %s %s %s\n", ugYellow("⚠"), shortenHome(d.Dir), ugDim("旧副本未能迁移，可手动删除: "+d.Err.Error()))
+		}
 	} else {
 		fmt.Printf(" %s\n", ugGreen("✓"))
 	}

internal/app/upgrade_full_coverage_test.go

@@ -292,6 +292,12 @@ func TestCrossPlatformCoverageRunUpgradeAllStagesCoverage(t *testing.T) {
 			if stage == "install-failed-dir" {
 				return &upgradepkg.SkillUpgradeResult{Results: []upgradepkg.SkillDirResult{{Dir: "/failed", Status: upgradepkg.SkillDirFailed, Err: fail}}}, nil
 			}
+			if stage == "install-retire-warning" {
+				return &upgradepkg.SkillUpgradeResult{Results: []upgradepkg.SkillDirResult{
+					{Dir: "/ok", Status: upgradepkg.SkillDirOK},
+					{Dir: "/stale", Status: upgradepkg.SkillDirRetireWarning, Err: errors.New("retirement refused")},
+				}}, nil
+			}
 			return &upgradepkg.SkillUpgradeResult{Results: []upgradepkg.SkillDirResult{{Dir: "/ok", Status: upgradepkg.SkillDirOK}}}, nil
 		}
 	}
@@ -300,7 +306,7 @@ func TestCrossPlatformCoverageRunUpgradeAllStagesCoverage(t *testing.T) {
 		"ensure", "tag-error", "latest-error", "not-needed", "cancel", "find-binary", "temp-fallback", "temp-both",
 		"backup", "checksum-download", "checksum-read", "binary-download", "skills-download", "verify-binary", "verify-skills",
 		"extract-binary", "extract-tar", "binary-missing", "validate", "extract-skills", "skill-missing", "replace", "install", "install-failed-dir",
-		"success", "success-no-skills",
+		"success", "success-no-skills", "install-retire-warning",
 	} {
 		t.Run(stage, func(t *testing.T) {
 			configure(stage)
@@ -330,14 +336,14 @@ func TestCrossPlatformCoverageRunUpgradeAllStagesCoverage(t *testing.T) {
 				opts.skipSkills = true
 			}
 			err := runUpgrade(context.Background(), opts)
-			wantError := stage != "not-needed" && stage != "cancel" && stage != "backup" && stage != "checksum-download" && stage != "checksum-read" && stage != "success" && stage != "success-no-skills"
+			wantError := stage != "not-needed" && stage != "cancel" && stage != "backup" && stage != "checksum-download" && stage != "checksum-read" && stage != "success" && stage != "success-no-skills" && stage != "install-retire-warning"
 			if wantError && err == nil {
 				t.Fatalf("stage %s succeeded", stage)
 			}
 			if !wantError && err != nil {
 				t.Fatalf("stage %s failed: %v", stage, err)
 			}
-			if (stage == "success" || stage == "success-no-skills") && !rb.cleaned {
+			if (stage == "success" || stage == "success-no-skills" || stage == "install-retire-warning") && !rb.cleaned {
 				t.Fatal("successful upgrade did not clean backups")
 			}
 			if stage == "success" {

internal/auth/endpoints.go

@@ -113,10 +113,9 @@ const (
 	ClientIDPath            = "/cli/clientId"
 
 	// MCP OAuth endpoints (used when clientId is fetched from MCP).
-	MCPOAuthTokenPath     = "/oauth2/getToken"
-	MCPRefreshTokenPath   = "/oauth2/refreshToken"
-	MCPRevokeTokenPath    = "/oauth2/revokeToken"
-	MCPVendorAuthCodePath = "/oauth2/vendorAuthCode"
+	MCPOAuthTokenPath   = "/oauth2/getToken"
+	MCPRefreshTokenPath = "/oauth2/refreshToken"
+	MCPRevokeTokenPath  = "/oauth2/revokeToken"
 
 	// App-level access token endpoints (for dws api raw calls).
 

internal/auth/vendor_authcode.go

@@ -1,192 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package auth
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
-)
-
-const (
-	headerUserAccessToken = "x-user-access-token"
-	headerDWSClientID     = "x-dws-client-id"
-	headerDWSCLIVersion   = "x-dws-cli-version"
-
-	// VendorAuthCode default / documented portal expiresIn, used only when
-	// the success body omits a positive value. Callers must still prefer
-	// the response field.
-	DefaultVendorAuthCodeExpiresIn = 120
-
-	VendorAuthCodeParamError        = "PARAM_ERROR"
-	VendorAuthCodeVendorUnsupported = "VENDOR_UNSUPPORTED"
-	VendorAuthCodeTokenInvalid      = "TOKEN_INVALID"
-	VendorAuthCodeOrgMismatch       = "ORG_MISMATCH"
-	VendorAuthCodeUserNotInOrg      = "USER_NOT_IN_ORG"
-	VendorAuthCodeVendorNotEnabled  = "VENDOR_NOT_ENABLED"
-	VendorAuthCodeRateLimited       = "RATE_LIMITED"
-	VendorAuthCodeInternalError     = "INTERNAL_ERROR"
-)
-
-// VendorAuthCodeInput is a POST /oauth2/vendorAuthCode call. The body is
-// only vendor + corpId; redirectURI and domain must not be sent.
-type VendorAuthCodeInput struct {
-	AccessToken string
-	ClientID    string
-	CLIVersion  string
-	LoginRegion LoginRegion
-	Vendor      string
-	CorpID      string
-	HTTPClient  *http.Client
-	// BaseURL overrides MCPBaseURLForLoginRegion. Tests use it; production
-	// callers leave it empty.
-	BaseURL string
-}
-
-// VendorAuthCodeResult is the success VO from portal.
-type VendorAuthCodeResult struct {
-	AuthCode  string
-	ExpiresIn int
-}
-
-// VendorAuthCodeError is a portal business error carried in an HTTP 200
-// ServiceResult body (same envelope as /oauth2/getToken).
-type VendorAuthCodeError struct {
-	Code    string
-	Message string
-}
-
-func (e *VendorAuthCodeError) Error() string {
-	if e == nil {
-		return "vendorAuthCode failed"
-	}
-	if strings.TrimSpace(e.Message) != "" {
-		return fmt.Sprintf("vendorAuthCode %s: %s", e.Code, e.Message)
-	}
-	return fmt.Sprintf("vendorAuthCode %s", e.Code)
-}
-
-// Retryable reports whether DWS should retry this portal error once.
-func (e *VendorAuthCodeError) Retryable() bool {
-	if e == nil {
-		return false
-	}
-	switch e.Code {
-	case VendorAuthCodeTokenInvalid, VendorAuthCodeRateLimited, VendorAuthCodeInternalError:
-		return true
-	default:
-		return false
-	}
-}
-
-// FetchVendorAuthCode POSTs {vendor, corpId} to /oauth2/vendorAuthCode.
-// HTTP is expected to be 200; errors are read from body.errorCode.
-func FetchVendorAuthCode(ctx context.Context, in VendorAuthCodeInput) (*VendorAuthCodeResult, error) {
-	vendor := strings.ToLower(strings.TrimSpace(in.Vendor))
-	corpID := strings.TrimSpace(in.CorpID)
-	token := strings.TrimSpace(in.AccessToken)
-	clientID := strings.TrimSpace(in.ClientID)
-	if token == "" || clientID == "" || vendor == "" || corpID == "" {
-		return nil, &VendorAuthCodeError{
-			Code:    VendorAuthCodeParamError,
-			Message: "token, clientId, vendor and corpId are required",
-		}
-	}
-
-	base := strings.TrimRight(strings.TrimSpace(in.BaseURL), "/")
-	if base == "" {
-		base = strings.TrimRight(MCPBaseURLForLoginRegion(in.LoginRegion), "/")
-	}
-	endpoint := base + MCPVendorAuthCodePath
-
-	payload, err := json.Marshal(struct {
-		Vendor string `json:"vendor"`
-		CorpID string `json:"corpId"`
-	}{Vendor: vendor, CorpID: corpID})
-	if err != nil {
-		return nil, fmt.Errorf("marshaling vendorAuthCode request: %w", err)
-	}
-
-	req, err := oauthNewRequest(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
-	if err != nil {
-		return nil, fmt.Errorf("creating vendorAuthCode request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set(headerUserAccessToken, token)
-	req.Header.Set(headerDWSClientID, clientID)
-	if ver := strings.TrimSpace(in.CLIVersion); ver != "" {
-		req.Header.Set(headerDWSCLIVersion, ver)
-	}
-	applyEditionEnterpriseCredentialHeaders(req)
-
-	client := in.HTTPClient
-	if client == nil {
-		client = oauthHTTPClient
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, fmt.Errorf("sending vendorAuthCode request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	data, readErr := io.ReadAll(io.LimitReader(resp.Body, config.MaxResponseBodySize))
-	if resp.StatusCode != http.StatusOK {
-		if readErr != nil {
-			data = nil
-		}
-		return nil, &HTTPStatusError{
-			StatusCode:   resp.StatusCode,
-			responseBody: truncateBody(data, 200),
-		}
-	}
-	if readErr != nil {
-		return nil, fmt.Errorf("reading vendorAuthCode response: %w", readErr)
-	}
-	return parseVendorAuthCodeResponse(data)
-}
-
-func parseVendorAuthCodeResponse(body []byte) (*VendorAuthCodeResult, error) {
-	var resp struct {
-		AuthCode  string `json:"authCode"`
-		ExpiresIn int    `json:"expiresIn"`
-		Success   *bool  `json:"success"`
-		ErrorCode string `json:"errorCode"`
-		ErrorMsg  string `json:"errorMsg"`
-	}
-	if err := json.Unmarshal(body, &resp); err != nil {
-		return nil, fmt.Errorf("parsing vendorAuthCode response: %w", err)
-	}
-	if resp.ErrorCode != "" || resp.ErrorMsg != "" || (resp.Success != nil && !*resp.Success) {
-		code := strings.TrimSpace(resp.ErrorCode)
-		if code == "" {
-			code = VendorAuthCodeInternalError
-		}
-		return nil, &VendorAuthCodeError{Code: code, Message: resp.ErrorMsg}
-	}
-	authCode := strings.TrimSpace(resp.AuthCode)
-	if authCode == "" {
-		return nil, fmt.Errorf("vendorAuthCode response missing authCode")
-	}
-	expiresIn := resp.ExpiresIn
-	if expiresIn <= 0 {
-		expiresIn = DefaultVendorAuthCodeExpiresIn
-	}
-	return &VendorAuthCodeResult{AuthCode: authCode, ExpiresIn: expiresIn}, nil
-}

internal/auth/vendor_authcode_test.go

@@ -1,178 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package auth
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"net/http/httptest"
-	"strings"
-	"testing"
-)
-
-func TestFetchVendorAuthCodeSuccessEnvelope(t *testing.T) {
-	var gotBody map[string]string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.URL.Path != MCPVendorAuthCodePath {
-			t.Fatalf("path = %q, want %s", r.URL.Path, MCPVendorAuthCodePath)
-		}
-		if r.Method != http.MethodPost {
-			t.Fatalf("method = %s, want POST", r.Method)
-		}
-		if got := r.Header.Get("x-user-access-token"); got != "user-token" {
-			t.Fatalf("x-user-access-token = %q", got)
-		}
-		if got := r.Header.Get("x-dws-client-id"); got != "dws-client" {
-			t.Fatalf("x-dws-client-id = %q", got)
-		}
-		if got := r.Header.Get("x-dws-cli-version"); got != "1.2.3" {
-			t.Fatalf("x-dws-cli-version = %q", got)
-		}
-		if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
-			t.Fatalf("decode body: %v", err)
-		}
-		w.Header().Set("Cache-Control", "no-store")
-		_, _ = io.WriteString(w, `{"authCode":"tmp-code","expiresIn":120}`)
-	}))
-	defer srv.Close()
-
-	got, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		CLIVersion:  "1.2.3",
-		Vendor:      "SafeChat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	if err != nil {
-		t.Fatalf("FetchVendorAuthCode() = %v", err)
-	}
-	if got.AuthCode != "tmp-code" || got.ExpiresIn != 120 {
-		t.Fatalf("result = %+v", got)
-	}
-	if gotBody["vendor"] != "safechat" || gotBody["corpId"] != "dingxxxxxxxxxxxx" {
-		t.Fatalf("posted body = %v", gotBody)
-	}
-	if _, ok := gotBody["redirectURI"]; ok {
-		t.Fatalf("posted redirectURI, body = %v", gotBody)
-	}
-	if _, ok := gotBody["domain"]; ok {
-		t.Fatalf("posted domain, body = %v", gotBody)
-	}
-}
-
-func TestFetchVendorAuthCodeParsesAlways200ServiceResult(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusOK)
-		_, _ = io.WriteString(w, `{"success":false,"errorCode":"VENDOR_NOT_ENABLED","errorMsg":"not installed"}`)
-	}))
-	defer srv.Close()
-
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	var verr *VendorAuthCodeError
-	if !errors.As(err, &verr) || verr.Code != VendorAuthCodeVendorNotEnabled {
-		t.Fatalf("error = %v, want VENDOR_NOT_ENABLED", err)
-	}
-	if verr.Retryable() {
-		t.Fatal("VENDOR_NOT_ENABLED must not be retryable")
-	}
-}
-
-func TestFetchVendorAuthCodeRequiresLocalFields(t *testing.T) {
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{Vendor: "safechat", CorpID: "ding"})
-	var verr *VendorAuthCodeError
-	if !errors.As(err, &verr) || verr.Code != VendorAuthCodeParamError {
-		t.Fatalf("error = %v, want PARAM_ERROR", err)
-	}
-}
-
-func TestFetchVendorAuthCodeKeepsHTTPStatusOnNon200(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		http.Error(w, "oops", http.StatusBadGateway)
-	}))
-	defer srv.Close()
-
-	_, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	var statusErr *HTTPStatusError
-	if !errors.As(err, &statusErr) || statusErr.StatusCode != http.StatusBadGateway {
-		t.Fatalf("error = %v, want HTTP 502", err)
-	}
-}
-
-func TestParseVendorAuthCodeResponseDefaultsExpiresIn(t *testing.T) {
-	got, err := parseVendorAuthCodeResponse([]byte(`{"authCode":"x"}`))
-	if err != nil {
-		t.Fatalf("parse: %v", err)
-	}
-	if got.ExpiresIn != DefaultVendorAuthCodeExpiresIn {
-		t.Fatalf("expiresIn = %d, want %d", got.ExpiresIn, DefaultVendorAuthCodeExpiresIn)
-	}
-}
-
-func TestVendorAuthCodeErrorRetryable(t *testing.T) {
-	for _, code := range []string{VendorAuthCodeTokenInvalid, VendorAuthCodeRateLimited, VendorAuthCodeInternalError} {
-		if !(&VendorAuthCodeError{Code: code}).Retryable() {
-			t.Fatalf("%s should be retryable", code)
-		}
-	}
-	if (&VendorAuthCodeError{Code: VendorAuthCodeOrgMismatch}).Retryable() {
-		t.Fatal("ORG_MISMATCH must not be retryable")
-	}
-}
-
-func TestFetchVendorAuthCodeDoesNotSendBlankCLIVersionHeader(t *testing.T) {
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if got := r.Header.Get("x-dws-cli-version"); got != "" {
-			t.Fatalf("x-dws-cli-version = %q, want empty", got)
-		}
-		_, _ = io.WriteString(w, `{"authCode":"tmp-code","expiresIn":90}`)
-	}))
-	defer srv.Close()
-
-	got, err := FetchVendorAuthCode(context.Background(), VendorAuthCodeInput{
-		AccessToken: "user-token",
-		ClientID:    "dws-client",
-		Vendor:      "safechat",
-		CorpID:      "dingxxxxxxxxxxxx",
-		HTTPClient:  srv.Client(),
-		BaseURL:     srv.URL,
-	})
-	if err != nil {
-		t.Fatalf("FetchVendorAuthCode() = %v", err)
-	}
-	if got.ExpiresIn != 90 {
-		t.Fatalf("expiresIn = %d, want 90 from response", got.ExpiresIn)
-	}
-	if strings.Contains(got.AuthCode, "redirect") {
-		t.Fatalf("unexpected code %q", got.AuthCode)
-	}
-}

internal/cli/param_aliases_generated.go

@@ -1773,6 +1773,439 @@ var generatedParamAliases = []ParamAliasEntry{
 		},
 		Blocked: []string{"at-user-ids", "staff-id", "uid", "user", "user-id", "userid"},
 	},
+	{
+		CLIPath: "calendar +agenda",
+		Aliases: map[string]string{
+			"begin":            "start",
+			"calendar":         "calendar-id",
+			"calendar-book-id": "calendar-id",
+			"end-date":         "end",
+			"end-time":         "end",
+			"from":             "start",
+			"from-date":        "start",
+			"max-result":       "limit",
+			"max-results":      "limit",
+			"max-time":         "end",
+			"min-time":         "start",
+			"next-cursor":      "cursor",
+			"next-page-token":  "cursor",
+			"next-token":       "cursor",
+			"page-size":        "limit",
+			"page-token":       "cursor",
+			"per-page":         "limit",
+			"since":            "start",
+			"size":             "limit",
+			"start-date":       "start",
+			"start-time":       "start",
+			"take":             "limit",
+			"time-max":         "end",
+			"time-min":         "start",
+			"to":               "end",
+			"top":              "limit",
+		},
+		Blocked: []string{"acl-id", "count", "date", "event", "event-id", "id", "offset", "page", "room-id", "time"},
+	},
+	{
+		CLIPath: "calendar +attendee-list",
+		Aliases: map[string]string{
+			"calendar":          "calendar-id",
+			"calendar-book-id":  "calendar-id",
+			"calendar-event-id": "event",
+			"event-id":          "event",
+		},
+		Blocked:   []string{"acl-id", "room-id"},
+		Ambiguous: []string{"id"},
+	},
+	{
+		CLIPath: "calendar +book",
+		Aliases: map[string]string{
+			"attendee-names":    "with",
+			"begin":             "start",
+			"end-time":          "end",
+			"from":              "start",
+			"names":             "with",
+			"participant-names": "with",
+			"start-time":        "start",
+			"subject":           "title",
+			"summary":           "title",
+			"to":                "end",
+		},
+		Blocked: []string{"attendees", "calendar-id", "calendar-name", "date", "end-date", "name", "open-dingtalk-ids", "participants", "room-id", "room-ids", "room-name", "rooms", "start-date", "time", "time-max", "time-min", "user", "user-id", "user-ids", "users"},
+	},
+	{
+		CLIPath: "calendar +book-search",
+		Aliases: map[string]string{
+			"keyword":     "query",
+			"keywords":    "query",
+			"name":        "query",
+			"q":           "query",
+			"search":      "query",
+			"search-word": "query",
+		},
+		Blocked: []string{"subject", "text", "title"},
+	},
+	{
+		CLIPath: "calendar +cancel-event",
+		Aliases: map[string]string{
+			"calendar-event-id": "event",
+			"event-id":          "event",
+			"id":                "event",
+		},
+		Blocked: []string{"acl-id", "calendar-book-id", "calendar-id", "room-id"},
+	},
+	{
+		CLIPath: "calendar +conflicts",
+		Aliases: map[string]string{
+			"day-offset":      "in-days",
+			"days-from-today": "in-days",
+		},
+		Blocked: []string{"days", "duration", "end", "from", "start", "to"},
+	},
+	{
+		CLIPath: "calendar +create",
+		Aliases: map[string]string{
+			"attendee-ids":     "attendees",
+			"begin":            "start",
+			"calendar":         "calendar-id",
+			"calendar-book-id": "calendar-id",
+			"description":      "desc",
+			"end-time":         "end",
+			"freebusy":         "free-busy",
+			"from":             "start",
+			"room-id":          "rooms",
+			"room-ids":         "rooms",
+			"start-time":       "start",
+			"subject":          "title",
+			"summary":          "title",
+			"time-zone":        "timezone",
+			"to":               "end",
+			"tz":               "timezone",
+			"user-ids":         "attendees",
+			"users":            "attendees",
+		},
+		Blocked: []string{"acl-id", "attendee-name", "attendee-names", "calendar-name", "config", "date", "end-date", "event", "event-id", "field-description", "group-id", "id", "locale", "name", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "rich-text-desc", "room", "room-name", "start-date", "time", "time-max", "time-min", "utc-offset", "who", "with"},
+	},
+	{
+		CLIPath: "calendar +free",
+		Aliases: map[string]string{
+			"begin":       "start",
+			"end-date":    "end",
+			"end-time":    "end",
+			"from":        "start",
+			"from-date":   "start",
+			"max-time":    "end",
+			"min-time":    "start",
+			"name":        "who",
+			"person":      "who",
+			"person-name": "who",
+			"since":       "start",
+			"start-date":  "start",
+			"start-time":  "start",
+			"time-max":    "end",
+			"time-min":    "start",
+			"to":          "end",
+		},
+		Blocked: []string{"date", "time", "user", "user-id", "user-ids", "users", "with"},
+	},
+	{
+		CLIPath: "calendar +free-slots",
+		Aliases: map[string]string{
+			"day-offset":      "in-days",
+			"days-from-today": "in-days",
+			"end-hour":        "to",
+			"start-hour":      "from",
+		},
+		Blocked: []string{"days", "duration", "end", "end-time", "start", "start-time", "time-max", "time-min"},
+	},
+	{
+		CLIPath: "calendar +freebusy",
+		Aliases: map[string]string{
+			"begin":      "start",
+			"end-date":   "end",
+			"end-time":   "end",
+			"from":       "start",
+			"from-date":  "start",
+			"max-time":   "end",
+			"min-time":   "start",
+			"room-id":    "rooms",
+			"room-ids":   "rooms",
+			"since":      "start",
+			"start-date": "start",
+			"start-time": "start",
+			"time-max":   "end",
+			"time-min":   "start",
+			"to":         "end",
+			"user-ids":   "users",
+		},
+		Blocked: []string{"at-user-ids", "attendee-names", "date", "group-id", "location", "name", "names", "participant-names", "room", "room-name", "staff-id", "time", "uid", "user", "user-id", "userid", "who", "with"},
+	},
+	{
+		CLIPath: "calendar +get",
+		Aliases: map[string]string{
+			"calendar":          "calendar-id",
+			"calendar-book-id":  "calendar-id",
+			"calendar-event-id": "event",
+			"event-id":          "event",
+		},
+		Blocked:   []string{"acl-id", "room-id"},
+		Ambiguous: []string{"id"},
+	},
+	{
+		CLIPath: "calendar +invite",
+		Aliases: map[string]string{
+			"attendee-names":    "with",
+			"calendar-event-id": "event",
+			"event-id":          "event",
+			"id":                "event",
+			"names":             "with",
+			"participant-names": "with",
+		},
+		Blocked: []string{"acl-id", "attendees", "calendar-book-id", "calendar-id", "open-dingtalk-ids", "participants", "room-id", "user", "user-id", "user-ids", "users"},
+	},
+	{
+		CLIPath: "calendar +my-free",
+		Aliases: map[string]string{
+			"begin":      "start",
+			"end-date":   "end",
+			"end-time":   "end",
+			"from":       "start",
+			"from-date":  "start",
+			"max-time":   "end",
+			"min-time":   "start",
+			"since":      "start",
+			"start-date": "start",
+			"start-time": "start",
+			"time-max":   "end",
+			"time-min":   "start",
+			"to":         "end",
+		},
+		Blocked: []string{"date", "time"},
+	},
+	{
+		CLIPath: "calendar +reschedule",
+		Aliases: map[string]string{
+			"begin":             "start",
+			"calendar-event-id": "event",
+			"end-time":          "end",
+			"event-id":          "event",
+			"from":              "start",
+			"id":                "event",
+			"start-time":        "start",
+			"to":                "end",
+		},
+		Blocked: []string{"acl-id", "calendar-book-id", "calendar-id", "date", "end-date", "room-id", "start-date", "time", "time-max", "time-min"},
+	},
+	{
+		CLIPath: "calendar +room-find",
+		Aliases: map[string]string{
+			"begin":         "start",
+			"end-date":      "end",
+			"end-time":      "end",
+			"from":          "start",
+			"from-date":     "start",
+			"group":         "group-id",
+			"max-result":    "limit",
+			"max-results":   "limit",
+			"max-time":      "end",
+			"min-time":      "start",
+			"name":          "room-name",
+			"page-index":    "page",
+			"page-size":     "limit",
+			"per-page":      "limit",
+			"query":         "room-name",
+			"room-group-id": "group-id",
+			"since":         "start",
+			"size":          "limit",
+			"start-date":    "start",
+			"start-time":    "start",
+			"take":          "limit",
+			"time-max":      "end",
+			"time-min":      "start",
+			"to":            "end",
+			"top":           "limit",
+		},
+		Blocked: []string{"count", "cursor", "date", "location", "next-cursor", "page-token", "room", "room-id", "room-ids", "rooms", "time"},
+	},
+	{
+		CLIPath: "calendar +room-groups",
+		Aliases: map[string]string{
+			"max-result":  "limit",
+			"max-results": "limit",
+			"page-index":  "page",
+			"page-size":   "limit",
+			"per-page":    "limit",
+			"size":        "limit",
+			"take":        "limit",
+			"top":         "limit",
+		},
+		Blocked: []string{"count", "cursor", "page-token"},
+	},
+	{
+		CLIPath: "calendar +room-search",
+		Aliases: map[string]string{
+			"name":  "room-name",
+			"query": "room-name",
+		},
+		Blocked: []string{"group-id", "location", "room", "room-id", "room-ids", "rooms"},
+	},
+	{
+		CLIPath: "calendar +rsvp",
+		Aliases: map[string]string{
+			"calendar":          "calendar-id",
+			"calendar-book-id":  "calendar-id",
+			"calendar-event-id": "event",
+			"event-id":          "event",
+			"response":          "status",
+			"response-status":   "status",
+		},
+		Blocked:   []string{"acl-id", "availability", "done", "free-busy", "room-id", "state"},
+		Ambiguous: []string{"id"},
+	},
+	{
+		CLIPath: "calendar +search-event",
+		Aliases: map[string]string{
+			"begin":            "start",
+			"calendar":         "calendar-id",
+			"calendar-book-id": "calendar-id",
+			"end-date":         "end",
+			"end-time":         "end",
+			"from":             "start",
+			"from-date":        "start",
+			"keyword":          "query",
+			"keywords":         "query",
+			"max-result":       "limit",
+			"max-results":      "limit",
+			"max-time":         "end",
+			"min-time":         "start",
+			"next-cursor":      "cursor",
+			"next-page-token":  "cursor",
+			"next-token":       "cursor",
+			"page-size":        "limit",
+			"page-token":       "cursor",
+			"per-page":         "limit",
+			"q":                "query",
+			"search":           "query",
+			"search-word":      "query",
+			"since":            "start",
+			"size":             "limit",
+			"start-date":       "start",
+			"start-time":       "start",
+			"take":             "limit",
+			"time-max":         "end",
+			"time-min":         "start",
+			"to":               "end",
+			"top":              "limit",
+		},
+		Blocked: []string{"acl-id", "count", "date", "event", "event-id", "id", "name", "offset", "page", "page-index", "room-id", "subject", "text", "time", "title"},
+	},
+	{
+		CLIPath: "calendar +suggest-time",
+		Aliases: map[string]string{
+			"attendee-names":           "with",
+			"begin":                    "start",
+			"duration-minutes":         "duration",
+			"end-date":                 "end",
+			"end-time":                 "end",
+			"from":                     "start",
+			"from-date":                "start",
+			"max-time":                 "end",
+			"meeting-duration-minutes": "duration",
+			"min-time":                 "start",
+			"names":                    "with",
+			"participant-names":        "with",
+			"since":                    "start",
+			"start-date":               "start",
+			"start-time":               "start",
+			"time-max":                 "end",
+			"time-min":                 "start",
+			"to":                       "end",
+		},
+		Blocked: []string{"attendees", "date", "open-dingtalk-ids", "participants", "remind-minutes", "time", "user", "user-id", "user-ids", "users"},
+	},
+	{
+		CLIPath: "calendar +suggestion",
+		Aliases: map[string]string{
+			"begin":                    "start",
+			"duration-minutes":         "duration",
+			"end-date":                 "end",
+			"end-time":                 "end",
+			"from":                     "start",
+			"from-date":                "start",
+			"max-time":                 "end",
+			"meeting-duration-minutes": "duration",
+			"min-time":                 "start",
+			"since":                    "start",
+			"start-date":               "start",
+			"start-time":               "start",
+			"time-max":                 "end",
+			"time-min":                 "start",
+			"time-zone":                "timezone",
+			"to":                       "end",
+			"tz":                       "timezone",
+			"user-ids":                 "users",
+		},
+		Blocked: []string{"at-user-ids", "attendee-name", "attendee-names", "date", "locale", "name", "names", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "remind-minutes", "room-id", "room-ids", "room-name", "rooms", "staff-id", "time", "uid", "user", "user-id", "userid", "utc-offset", "who", "with"},
+	},
+	{
+		CLIPath: "calendar +update",
+		Aliases: map[string]string{
+			"add-user-ids":      "add-attendees",
+			"add-users":         "add-attendees",
+			"begin":             "start",
+			"calendar":          "calendar-id",
+			"calendar-book-id":  "calendar-id",
+			"calendar-event-id": "event",
+			"description":       "desc",
+			"end-time":          "end",
+			"event-id":          "event",
+			"freebusy":          "free-busy",
+			"from":              "start",
+			"remove-user-ids":   "remove-attendees",
+			"remove-users":      "remove-attendees",
+			"start-time":        "start",
+			"subject":           "title",
+			"summary":           "title",
+			"time-zone":         "timezone",
+			"to":                "end",
+			"tz":                "timezone",
+		},
+		Blocked:   []string{"acl-id", "attendee-name", "attendee-names", "calendar-name", "config", "date", "end-date", "field-description", "group-id", "locale", "name", "offset", "open-dingtalk-ids", "participant-name", "participant-names", "remind-minutes", "reminder-minutes", "rich-text-desc", "room-id", "room-ids", "room-name", "rooms", "start-date", "time", "time-max", "time-min", "utc-offset", "who", "with"},
+		Ambiguous: []string{"attendees", "id", "user-ids", "users"},
+	},
+	{
+		CLIPath: "calendar acl delete",
+		Blocked: []string{"calendar-book-id", "calendar-id", "event", "event-id", "room-id", "user-id"},
+	},
+	{
+		CLIPath: "calendar attachment add",
+		Blocked: []string{"attachments", "file", "file-id", "file-ids"},
+	},
+	{
+		CLIPath: "calendar attendee add",
+		Blocked: []string{"attendee-name", "attendee-names", "open-dingtalk-ids", "participant-name", "participant-names", "who", "with"},
+	},
+	{
+		CLIPath: "calendar attendee delete",
+		Blocked: []string{"attendee-name", "attendee-names", "open-dingtalk-ids", "participant-name", "participant-names", "who", "with"},
+	},
+	{
+		CLIPath: "calendar busy search",
+		Aliases: map[string]string{
+			"room-id": "rooms",
+		},
+		Blocked: []string{"attendee-name", "attendee-names", "group-id", "location", "name", "names", "participant-names", "room", "room-name", "who", "with"},
+	},
+	{
+		CLIPath: "calendar event create",
+		Aliases: map[string]string{
+			"reminder-minutes":        "remind-minutes",
+			"reminder-offset-minutes": "remind-minutes",
+			"room-id":                 "rooms",
+			"time-zone":               "timezone",
+			"tz":                      "timezone",
+		},
+		Blocked: []string{"at", "attendee-name", "attendee-names", "due", "duration", "group-id", "locale", "offset", "participant-name", "participant-names", "remind-at", "reminder-time", "room", "room-name", "utc-offset", "who", "with"},
+	},
 	{
 		CLIPath: "calendar event list",
 		Aliases: map[string]string{
@@ -1789,6 +2222,54 @@ var generatedParamAliases = []ParamAliasEntry{
 		},
 		Blocked: []string{"offset", "page", "time"},
 	},
+	{
+		CLIPath: "calendar event respond",
+		Aliases: map[string]string{
+			"response":        "status",
+			"response-status": "status",
+		},
+		Blocked: []string{"availability", "done", "free-busy", "state"},
+	},
+	{
+		CLIPath: "calendar event suggest",
+		Aliases: map[string]string{
+			"duration-minutes":         "duration",
+			"meeting-duration-minutes": "duration",
+			"time-zone":                "timezone",
+			"tz":                       "timezone",
+		},
+		Blocked: []string{"attendee-name", "attendee-names", "from", "locale", "name", "names", "offset", "open-dingtalk-ids", "participant-names", "remind-minutes", "to", "utc-offset", "who", "with"},
+	},
+	{
+		CLIPath: "calendar event update",
+		Aliases: map[string]string{
+			"time-zone": "timezone",
+			"tz":        "timezone",
+		},
+		Blocked: []string{"attendees", "group-id", "locale", "offset", "participants", "remind-minutes", "reminder-minutes", "room-id", "room-ids", "room-name", "rooms", "utc-offset"},
+	},
+	{
+		CLIPath: "calendar room add",
+		Aliases: map[string]string{
+			"room-id": "rooms",
+		},
+		Blocked: []string{"group-id", "location", "room", "room-name"},
+	},
+	{
+		CLIPath: "calendar room delete",
+		Aliases: map[string]string{
+			"room-id": "rooms",
+		},
+		Blocked: []string{"group-id", "location", "room", "room-name"},
+	},
+	{
+		CLIPath: "calendar room search",
+		Aliases: map[string]string{
+			"group":         "group-id",
+			"room-group-id": "group-id",
+		},
+		Blocked: []string{"location", "room", "room-id", "room-ids", "rooms"},
+	},
 	{
 		CLIPath: "chat +bot-find",
 		Aliases: map[string]string{
@@ -2941,7 +3422,7 @@ var generatedParamAliases = []ParamAliasEntry{
 			"uid":      "user",
 			"userid":   "user",
 		},
-		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "role-id", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
+		Blocked: []string{"at-user-ids", "conversation-ids", "dest-conversation-id", "group-id", "group-ids", "group-name", "name", "open-conversation-ids", "source", "src-conversation-id", "target", "to-user", "user-ids", "users"},
 	},
 	{
 		CLIPath: "chat group-role update",

internal/corecmd/corecmd.go

@@ -230,9 +230,10 @@ const (
 //   - Validate / PostMount — orchestration only; must not register business flags
 //     or assemble business params that belong in Flags/ConstParams.
 //
-// Exactly one of RunE / Invoke / Orchestrate must be set; New validates this at
-// construction time. corecmd stays dispatch-agnostic and never calls a backend:
-// the adapters (FromLeafSpec / FromShortcut) supply the body.
+// Exactly one of RunE / Invoke / ResultInvoke / Orchestrate must be set; New
+// validates this at construction time. corecmd stays dispatch-agnostic and
+// never calls a backend: the adapters (FromLeafSpec / FromShortcut) supply the
+// body.
 type Spec struct {
 	Use           string
 	Short         string
@@ -259,7 +260,8 @@ type Spec struct {
 	// backend call).
 	ConfirmFirst bool
 	// ConstParams are fixed toolArgs merged after flag assembly (e.g. precheckOnly).
-	// They are payload declaration, not user flags, and never satisfy Required.
+	// They are payload declaration, not user flags, never satisfy Required, and
+	// require an Invoke or ResultInvoke dispatcher that consumes assembled args.
 	ConstParams map[string]any
 	// Contract is the authoring-time leaf contract declaration (selection /
 	// interface / parameters / dry-run / identity). When non-empty, embed
@@ -371,7 +373,9 @@ func (c *Ctx) Yes() bool { return BoolFlag(c.cmd, "yes") }
 // malformed spec can never run the pipeline — write-confirmation prompt
 // included — and then silently exit 0 having done nothing.
 func New(spec Spec) *cobra.Command {
+	spec.ConstParams = cloneConstParams(spec.ConstParams)
 	validateDispatchDecl(spec)
+	validateConstParamsDecl(spec)
 	validateSafetySpec(spec)
 	validateContractDecl(spec)
 	validateInputSpecs(spec.Use, spec.Flags)
@@ -399,6 +403,7 @@ func New(spec Spec) *cobra.Command {
 	if spec.PostMount != nil {
 		spec.PostMount(cmd)
 	}
+	attachInterfaceBoolConstParams(cmd, spec.ConstParams)
 	if spec.OutputRollout != "" {
 		output.SetCommandRollout(cmd, spec.OutputRollout)
 	}
@@ -462,6 +467,17 @@ func New(spec Spec) *cobra.Command {
 	return cmd
 }
 
+func cloneConstParams(params map[string]any) map[string]any {
+	if params == nil {
+		return nil
+	}
+	frozen := make(map[string]any, len(params))
+	for key, value := range params {
+		frozen[key] = value
+	}
+	return frozen
+}
+
 // ConfirmFirstAnnotation marks commands whose Spec declared ConfirmFirst. The
 // delivery gate reads it to tell a declared guard-first command apart from an
 // accidental confirm-before-validate inversion: guard-first is only legitimate
@@ -537,6 +553,21 @@ func validateDispatchDecl(spec Spec) {
 	}
 }
 
+func validateConstParamsDecl(spec Spec) {
+	if len(spec.ConstParams) == 0 {
+		return
+	}
+	if spec.Invoke == nil && spec.ResultInvoke == nil {
+		panic(fmt.Sprintf("command %q ConstParams require Invoke or ResultInvoke", spec.Use))
+	}
+	for _, flag := range spec.Flags {
+		key := bindKey(flag)
+		if _, conflicts := spec.ConstParams[key]; conflicts {
+			panic(fmt.Sprintf("command %q ConstParams key %q conflicts with flag --%s", spec.Use, key, flag.Name))
+		}
+	}
+}
+
 // validateSafetySpec rejects partial safety declarations. A zero value remains
 // the historical read-only default, but once any field is authored all four
 // independent Schema dimensions must be explicit.

internal/corecmd/corecmd_test.go

@@ -26,6 +26,7 @@ import (
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contractfinal"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
 	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
 	"github.com/spf13/cobra"
 )
@@ -1415,17 +1416,23 @@ func TestCrossPlatformCoverageBuildArgsIntArgDefaultFloor(t *testing.T) {
 	}
 }
 
-func TestNewCommandMergesConstParams(t *testing.T) {
+func TestCrossPlatformCoverageNewCommandFreezesAndMergesConstParams(t *testing.T) {
 	var got map[string]any
+	declared := map[string]any{
+		"precheckOnly":      false,
+		"convThreadEnabled": true,
+	}
 	cmd := New(Spec{
 		Use:         "pub",
 		Flags:       []FlagSpec{{Name: "id", Usage: "ID", Bind: "versionId", Trim: true}},
-		ConstParams: map[string]any{"precheckOnly": false},
+		ConstParams: declared,
 		Invoke: func(_ *Ctx, toolArgs map[string]any) error {
 			got = toolArgs
 			return nil
 		},
 	})
+	declared["precheckOnly"] = true
+	declared["forgedAfterNew"] = true
 	_ = cmd.Flags().Set("id", "V1")
 	if err := cmd.RunE(cmd, nil); err != nil {
 		t.Fatal(err)
@@ -1436,6 +1443,95 @@ func TestNewCommandMergesConstParams(t *testing.T) {
 	if got["precheckOnly"] != false {
 		t.Fatalf("precheckOnly = %#v, want false", got["precheckOnly"])
 	}
+	if got["convThreadEnabled"] != true {
+		t.Fatalf("convThreadEnabled = %#v, want true", got["convThreadEnabled"])
+	}
+	if _, exists := got["forgedAfterNew"]; exists {
+		t.Fatalf("caller mutation leaked into dispatch args: %#v", got)
+	}
+	evidence := InterfaceBoolConstParams(cmd)
+	if !reflect.DeepEqual(evidence, map[string]bool{"convThreadEnabled": true, "precheckOnly": false}) {
+		t.Fatalf("bool ConstParams evidence = %#v", evidence)
+	}
+	if got["precheckOnly"] != evidence["precheckOnly"] {
+		t.Fatalf("dispatch/evidence drift: args=%#v evidence=%#v", got, evidence)
+	}
+}
+
+func TestCrossPlatformCoverageNewCommandDoesNotProjectMixedConstParamsEvidence(t *testing.T) {
+	var got map[string]any
+	cmd := New(Spec{
+		Use: "mixed",
+		ConstParams: map[string]any{
+			"convThreadEnabled": true,
+			"retryLimit":        3,
+		},
+		Invoke: func(_ *Ctx, toolArgs map[string]any) error {
+			got = toolArgs
+			return nil
+		},
+	})
+
+	if evidence := InterfaceBoolConstParams(cmd); evidence != nil {
+		t.Fatalf("mixed ConstParams evidence = %#v; want missing evidence", evidence)
+	}
+	if err := cmd.RunE(cmd, nil); err != nil {
+		t.Fatal(err)
+	}
+	if got["convThreadEnabled"] != true || got["retryLimit"] != 3 {
+		t.Fatalf("mixed ConstParams dispatch args = %#v", got)
+	}
+}
+
+func TestCrossPlatformCoverageNewCommandRejectsInvalidConstParamsDispatch(t *testing.T) {
+	mustPanic := func(name string, spec Spec, needle string) {
+		t.Helper()
+		defer func() {
+			r := recover()
+			if r == nil {
+				t.Fatalf("%s: expected panic", name)
+			}
+			if msg, _ := r.(string); !strings.Contains(msg, needle) {
+				t.Fatalf("%s: panic=%v, want %q", name, r, needle)
+			}
+		}()
+		New(spec)
+	}
+
+	mustPanic("RunE", Spec{
+		Use:         "run-e",
+		ConstParams: map[string]any{"fixed": true},
+		RunE:        func(*cobra.Command, []string) error { return nil },
+	}, "ConstParams require Invoke or ResultInvoke")
+	mustPanic("Orchestrate", Spec{
+		Use:         "orchestrate",
+		ConstParams: map[string]any{"fixed": true},
+		Orchestrate: func(*Ctx) error { return nil },
+	}, "ConstParams require Invoke or ResultInvoke")
+	mustPanic("explicit bind conflict", Spec{
+		Use:         "bind-conflict",
+		Flags:       []FlagSpec{{Name: "thread", Usage: "T", Bind: "convThreadEnabled"}},
+		ConstParams: map[string]any{"convThreadEnabled": true},
+		Invoke:      func(*Ctx, map[string]any) error { return nil },
+	}, "conflicts with flag --thread")
+	mustPanic("default bind conflict", Spec{
+		Use:         "default-bind-conflict",
+		Flags:       []FlagSpec{{Name: "fixed-value", Usage: "F"}},
+		ConstParams: map[string]any{"fixedValue": true},
+		Invoke:      func(*Ctx, map[string]any) error { return nil },
+	}, "conflicts with flag --fixed-value")
+
+	result := New(Spec{
+		Use:           "result",
+		OutputRollout: output.RolloutUnifiedActive,
+		ConstParams:   map[string]any{"fixed": true},
+		ResultInvoke: func(*Ctx, map[string]any) (output.CommandResult, error) {
+			return output.Success(nil), nil
+		},
+	})
+	if evidence := InterfaceBoolConstParams(result); !evidence["fixed"] {
+		t.Fatalf("ResultInvoke ConstParams evidence = %#v", evidence)
+	}
 }
 
 func TestCrossPlatformCoverageNewCommandConfirmFirstAnnotationAndOrder(t *testing.T) {

internal/corecmd/interface_const_params.go

@@ -0,0 +1,63 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package corecmd
+
+import (
+	"sync"
+
+	"github.com/spf13/cobra"
+)
+
+var interfaceBoolConstParamsRegistry sync.Map
+
+// attachInterfaceBoolConstParams records framework-owned ConstParams evidence.
+// Only a non-empty, entirely boolean declaration is representable in v1;
+// empty or mixed declarations remove any evidence for the command.
+func attachInterfaceBoolConstParams(cmd *cobra.Command, params map[string]any) {
+	if cmd == nil {
+		return
+	}
+	if len(params) == 0 {
+		interfaceBoolConstParamsRegistry.Delete(cmd)
+		return
+	}
+	bools := make(map[string]bool, len(params))
+	for key, value := range params {
+		boolValue, ok := value.(bool)
+		if !ok {
+			interfaceBoolConstParamsRegistry.Delete(cmd)
+			return
+		}
+		bools[key] = boolValue
+	}
+	interfaceBoolConstParamsRegistry.Store(cmd, bools)
+}
+
+// InterfaceBoolConstParams returns a clone of framework-owned boolean
+// ConstParams evidence. Callers cannot mutate the private registry.
+func InterfaceBoolConstParams(cmd *cobra.Command) map[string]bool {
+	if cmd == nil {
+		return nil
+	}
+	stored, ok := interfaceBoolConstParamsRegistry.Load(cmd)
+	if !ok {
+		return nil
+	}
+	params := stored.(map[string]bool)
+	clone := make(map[string]bool, len(params))
+	for key, value := range params {
+		clone[key] = value
+	}
+	return clone
+}

internal/corecmd/interface_const_params_test.go

@@ -0,0 +1,44 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package corecmd
+
+import (
+	"reflect"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestCrossPlatformCoverageInterfaceBoolConstParamsRegistryClonesAndDeletes(t *testing.T) {
+	attachInterfaceBoolConstParams(nil, map[string]any{"ignored": true})
+	if got := InterfaceBoolConstParams(nil); got != nil {
+		t.Fatalf("nil command evidence = %#v, want nil", got)
+	}
+
+	cmd := &cobra.Command{Use: "send"}
+	declared := map[string]any{"convThreadEnabled": true, "precheckOnly": false}
+	attachInterfaceBoolConstParams(cmd, declared)
+	declared["convThreadEnabled"] = false
+
+	want := map[string]bool{"convThreadEnabled": true, "precheckOnly": false}
+	got := InterfaceBoolConstParams(cmd)
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("registered bool ConstParams = %#v, want %#v", got, want)
+	}
+	got["convThreadEnabled"] = false
+	if again := InterfaceBoolConstParams(cmd); !reflect.DeepEqual(again, want) {
+		t.Fatalf("reader leaked mutable registry state: %#v", again)
+	}
+
+	attachInterfaceBoolConstParams(cmd, map[string]any{"convThreadEnabled": true, "retryLimit": 3})
+	if got := InterfaceBoolConstParams(cmd); got != nil {
+		t.Fatalf("mixed ConstParams retained evidence: %#v", got)
+	}
+
+	attachInterfaceBoolConstParams(cmd, map[string]any{"convThreadEnabled": true})
+	attachInterfaceBoolConstParams(cmd, nil)
+	if got := InterfaceBoolConstParams(cmd); got != nil {
+		t.Fatalf("empty ConstParams retained evidence: %#v", got)
+	}
+}

internal/event/personal/client_test.go

@@ -132,6 +132,7 @@ func TestClientCreateRuleBasedSubscriptionsUsesDocumentedRuleParam(t *testing.T)
 		{"oa_approval_task_finished", EventOAApprovalTaskFinished, RuleOptions{}, map[string]any{}},
 		{"oa_approval_task_redirected", EventOAApprovalTaskRedirected, RuleOptions{}, map[string]any{}},
 		{"oa_approval_instance_started", EventOAApprovalInstanceStarted, RuleOptions{}, map[string]any{}},
+		{"oa_approval_instance_cc", EventOAApprovalInstanceCC, RuleOptions{}, map[string]any{}},
 		{"oa_approval_instance_terminated", EventOAApprovalInstanceTerminated, RuleOptions{}, map[string]any{}},
 		{"oa_approval_instance_finished", EventOAApprovalInstanceFinished, RuleOptions{}, map[string]any{}},
 		{"read_group", EventReadGroup, RuleOptions{GroupID: "cid-1"}, map[string]any{"openConversationId": "cid-1"}},

internal/event/personal/output.go

@@ -180,6 +180,19 @@ type OAApprovalInstanceStartedOutput struct {
 	EventTime         int64  `json:"event_time" description:"审批实例事件业务时间" format:"timestamp_ms"`
 }
 
+type OAApprovalInstanceCCOutput struct {
+	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
+	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
+	Timestamp         int64  `json:"timestamp" description:"事件发生时间戳" format:"timestamp_ms"`
+	SubscribeID       string `json:"subscribe_id" description:"订阅 ID"`
+	ProcessInstanceID string `json:"process_instance_id" description:"审批实例 ID"`
+	ProcessCode       string `json:"process_code" description:"审批流程模板编码"`
+	Title             string `json:"title" description:"审批标题"`
+	Status            string `json:"status" description:"审批实例到达抄送节点时的状态"`
+	CreateTime        int64  `json:"create_time" description:"审批实例创建时间" format:"timestamp_ms"`
+	EventTime         int64  `json:"event_time" description:"审批抄送事件业务时间" format:"timestamp_ms"`
+}
+
 type OAApprovalInstanceTerminatedOutput struct {
 	Type              string `json:"type" description:"事件类型，固定为当前 event_key"`
 	EventID           string `json:"event_id" description:"事件 ID，可用于去重"`
@@ -667,6 +680,19 @@ func projectOAApprovalEvent(ev transport.Event, base baseEventOutput, raw json.R
 			CreateTime:        payload.Body.CreateTime,
 			EventTime:         payload.EventTime,
 		}, nil
+	case EventOAApprovalInstanceCC:
+		return OAApprovalInstanceCCOutput{
+			Type:              base.Type,
+			EventID:           base.EventID,
+			Timestamp:         base.Timestamp,
+			SubscribeID:       base.SubscribeID,
+			ProcessInstanceID: payload.Body.ProcessInstanceID,
+			ProcessCode:       payload.Body.ProcessCode,
+			Title:             payload.Body.Title,
+			Status:            payload.Body.Status,
+			CreateTime:        payload.Body.CreateTime,
+			EventTime:         payload.EventTime,
+		}, nil
 	case EventOAApprovalInstanceTerminated:
 		return OAApprovalInstanceTerminatedOutput{
 			Type:              base.Type,
@@ -871,6 +897,8 @@ func outputTypeForEvent(eventKey string) reflect.Type {
 		return reflect.TypeOf(OAApprovalTaskRedirectedOutput{})
 	case eventKey == EventOAApprovalInstanceStarted:
 		return reflect.TypeOf(OAApprovalInstanceStartedOutput{})
+	case eventKey == EventOAApprovalInstanceCC:
+		return reflect.TypeOf(OAApprovalInstanceCCOutput{})
 	case eventKey == EventOAApprovalInstanceTerminated:
 		return reflect.TypeOf(OAApprovalInstanceTerminatedOutput{})
 	case eventKey == EventOAApprovalInstanceFinished:
@@ -906,6 +934,7 @@ func isOAEvent(eventKey string) bool {
 		eventKey == EventOAApprovalTaskFinished ||
 		eventKey == EventOAApprovalTaskRedirected ||
 		eventKey == EventOAApprovalInstanceStarted ||
+		eventKey == EventOAApprovalInstanceCC ||
 		eventKey == EventOAApprovalInstanceTerminated ||
 		eventKey == EventOAApprovalInstanceFinished
 }

internal/event/personal/output_test.go

@@ -173,6 +173,8 @@ func personalOAData(eventKey string) string {
 		body["finishTime"] = int64(1785229199000)
 	case EventOAApprovalInstanceStarted:
 		body["status"] = "RUNNING"
+	case EventOAApprovalInstanceCC:
+		body["status"] = "RUNNING"
 	case EventOAApprovalInstanceTerminated:
 		body["status"] = "TERMINATED"
 		body["finishTime"] = int64(1785229199000)
@@ -521,6 +523,21 @@ func TestCrossPlatformCoverageProjectOutputOAEvents(t *testing.T) {
 				EventTime:         1785229199000,
 			},
 		},
+		{
+			eventKey: EventOAApprovalInstanceCC,
+			want: OAApprovalInstanceCCOutput{
+				Type:              EventOAApprovalInstanceCC,
+				EventID:           "oa-event",
+				Timestamp:         1785229200123,
+				SubscribeID:       "outer-sub",
+				ProcessInstanceID: "process-instance-1",
+				ProcessCode:       "PROC-TEST-1",
+				Title:             "测试审批",
+				Status:            "RUNNING",
+				CreateTime:        1785229100000,
+				EventTime:         1785229199000,
+			},
+		},
 		{
 			eventKey: EventOAApprovalInstanceTerminated,
 			want: OAApprovalInstanceTerminatedOutput{
@@ -785,6 +802,7 @@ func TestCrossPlatformCoverageProjectOutputRejectsInvalidOAPayloads(t *testing.T
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 	} {

internal/event/personal/registry.go

@@ -43,6 +43,7 @@ const (
 	EventOAApprovalTaskFinished       = "user_oa_approval_task_finished"
 	EventOAApprovalTaskRedirected     = "user_oa_approval_task_redirected"
 	EventOAApprovalInstanceStarted    = "user_oa_approval_instance_started"
+	EventOAApprovalInstanceCC         = "user_oa_approval_instance_cc"
 	EventOAApprovalInstanceTerminated = "user_oa_approval_instance_terminated"
 	EventOAApprovalInstanceFinished   = "user_oa_approval_instance_finished"
 )
@@ -323,6 +324,17 @@ var definitions = []Definition{
 		Auth:           map[string]any{"identity": "user"},
 		Public:         true,
 	},
+	{
+		EventKey:       EventOAApprovalInstanceCC,
+		DisplayName:    "审批单抄送",
+		Description:    "审批实例到达抄送节点，发送给被抄送人",
+		Category:       "oa",
+		RuleType:       "all",
+		Status:         StatusEnabled,
+		RequiredParams: nil,
+		Auth:           map[string]any{"identity": "user"},
+		Public:         true,
+	},
 	{
 		EventKey:       EventOAApprovalInstanceTerminated,
 		DisplayName:    "审批单终止",

internal/event/personal/registry_test.go

@@ -50,6 +50,7 @@ func TestCatalogEnabledEvents(t *testing.T) {
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 	}
@@ -65,6 +66,7 @@ func TestOAEventCatalogDefinitions(t *testing.T) {
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 	}
@@ -158,6 +160,7 @@ func TestSchemaDocumentsDefaultToTransportEnvelope(t *testing.T) {
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 	} {
@@ -509,6 +512,13 @@ func TestOAEventSchemaDocumentsMatchOutputDTO(t *testing.T) {
 				"process_code", "title", "status", "create_time", "event_time",
 			},
 		},
+		{
+			eventKey: EventOAApprovalInstanceCC,
+			properties: []string{
+				"type", "event_id", "timestamp", "subscribe_id", "process_instance_id",
+				"process_code", "title", "status", "create_time", "event_time",
+			},
+		},
 		{
 			eventKey: EventOAApprovalInstanceTerminated,
 			properties: []string{
@@ -633,6 +643,7 @@ func TestBuildRuleParamAllEvents(t *testing.T) {
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 	} {
@@ -845,6 +856,7 @@ func TestSupportsMessageFilter(t *testing.T) {
 		EventOAApprovalTaskFinished,
 		EventOAApprovalTaskRedirected,
 		EventOAApprovalInstanceStarted,
+		EventOAApprovalInstanceCC,
 		EventOAApprovalInstanceTerminated,
 		EventOAApprovalInstanceFinished,
 		"unknown_event",

internal/helpers/chat.go

@@ -27,6 +27,38 @@ import (
 	"github.com/spf13/cobra"
 )
 
+func resolveChatGroupRoleSetUserRoleIDs(cmd *cobra.Command) ([]string, error) {
+	roleIDChanged := cmd.Flags().Changed("role-id")
+	roleIDsChanged := cmd.Flags().Changed("role-ids")
+	switch {
+	case roleIDChanged && roleIDsChanged:
+		// PreRunE rejects callers that explicitly pass both flags. Reaching this
+		// branch means the hidden legacy flag was promoted to satisfy Cobra's
+		// required marker on the public canonical flag.
+		return parseCSVValues(mustGetFlag(cmd, "role-ids")), nil
+	case roleIDChanged:
+		roleIDs := parseCSVValues(mustGetFlag(cmd, "role-id"))
+		if len(roleIDs) == 0 {
+			return nil, apperrors.NewValidation("--role-id 不能为空")
+		}
+		if len(roleIDs) > 1 {
+			return nil, apperrors.NewValidation("--role-id 只允许指定一个群身份")
+		}
+		return roleIDs, nil
+	case roleIDsChanged:
+		return parseCSVValues(mustGetFlag(cmd, "role-ids")), nil
+	default:
+		return nil, apperrors.NewValidation("缺少必填参数 --role-id")
+	}
+}
+
+func prepareChatGroupRoleSetUserRoleID(cmd *cobra.Command) error {
+	if cmd.Flags().Changed("role-id") && cmd.Flags().Changed("role-ids") {
+		return apperrors.NewValidation("--role-id 与 --role-ids 不能同时指定")
+	}
+	return promoteLegacyChatString(cmd, "role-id", "role-ids")
+}
+
 // promoteLegacyChatString copies an explicitly supplied legacy flag into the
 // new canonical flag. Cobra validates MarkFlagRequired after PreRunE, and the
 // overwrite also preserves the migration rule that a legacy value wins when
@@ -7753,17 +7785,23 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 	chatGroupRoleSetUserCmd := &cobra.Command{
 		Use:   "set-user",
 		Short: "设置用户的群身份（覆盖该用户的全部群身份）",
-		Example: `  dws chat group-role set-user --conversation-id <openConversationId> --user <userId> --role-ids roleId1,roleId2
+		Example: `  dws chat group-role set-user --conversation-id <openConversationId> --user <userId> --role-id <openRoleId>
   # 查询人员: dws contact user search --keyword "姓名" --format json
   # 查询 role-id: dws chat group-role list --conversation-id <openConversationId>`,
+		PreRunE: func(cmd *cobra.Command, args []string) error {
+			return prepareChatGroupRoleSetUserRoleID(cmd)
+		},
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateRequiredFlags(cmd, "conversation-id", "role-ids"); err != nil {
+			if err := validateRequiredFlags(cmd, "conversation-id"); err != nil {
 				return err
 			}
 			if err := validateRequiredFlagWithAliases(cmd, "user", "userId"); err != nil {
 				return err
 			}
-			roleIDs := parseCSVValues(mustGetFlag(cmd, "role-ids"))
+			roleIDs, err := resolveChatGroupRoleSetUserRoleIDs(cmd)
+			if err != nil {
+				return err
+			}
 			user := flagOrFallback(cmd, "user", "userId")
 			toolArgs := map[string]any{
 				"openConversationId": flagOrFallback(cmd, "conversation-id", "group", "id", "chat"),
@@ -7798,13 +7836,13 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 			},
 			Selection: contract.SelectionSpec{
 				AgentSummary: "为指定群成员设置自定义角色",
-				UseWhen:      []string{"需要把一个或多个已有角色分配给成员时"},
+				UseWhen:      []string{"需要把一个已有角色分配给成员时"},
 				AvoidWhen:    []string{"创建新角色定义时使用 chat group-role add"},
-				Examples:     []string{"dws chat group-role set-user --conversation-id <openConversationId> --user <userId> --role-ids roleId1,roleId2"},
+				Examples:     []string{"dws chat group-role set-user --conversation-id <openConversationId> --user <userId> --role-id <openRoleId>"},
 			},
 			Parameters: []contract.ParamDecl{
 				{Name: "conversation-id", Property: "openConversationId"},
-				{Name: "role-ids", Property: "openRoleIds"},
+				{Name: "role-id", Property: "openRoleIds"},
 				{Name: "user", Property: "openDingTalkId"},
 			},
 		},
@@ -7814,8 +7852,11 @@ flow-status 取值：1=处理中(PROCESSING)，2=输入中(INPUTTING)，3=完成
 	chatGroupRoleSetUserCmd.Flags().String("user", "", "用户 userId（必填）")
 	chatGroupRoleSetUserCmd.Flags().String("userId", "", "--user 的别名")
 	_ = chatGroupRoleSetUserCmd.Flags().MarkHidden("userId")
-	chatGroupRoleSetUserCmd.Flags().String("role-ids", "", "群身份 openRoleId 列表，逗号分隔 (必填)，传空字符串则清除该用户所有群身份")
-	_ = chatGroupRoleSetUserCmd.MarkFlagRequired("role-ids")
+	chatGroupRoleSetUserCmd.Flags().String("role-id", "", "群身份 openRoleId，由 group-role list 返回 (必填)")
+	chatGroupRoleSetUserCmd.Flags().String("role-ids", "", "已隐藏的兼容参数：群身份 openRoleId 列表，逗号分隔")
+	_ = chatGroupRoleSetUserCmd.Flags().MarkHidden("role-ids")
+	corecmd.AnnotateFlagAlias(chatGroupRoleSetUserCmd, "role-ids", "role-id")
+	_ = chatGroupRoleSetUserCmd.MarkFlagRequired("role-id")
 
 	chatGroupRoleRemoveUserCmd := &cobra.Command{
 		Use:     "remove-user",

internal/helpers/chat_command_edges_test.go

@@ -243,6 +243,155 @@ func TestCrossPlatformCoverageChatGroupUpdateIconRejectsBlankMediaID(t *testing.
 	}
 }
 
+func TestChatGroupRoleSetUserAcceptsSingleRoleIDAndLegacyRoleIDs(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	tests := []struct {
+		name string
+		args []string
+		want []string
+	}{
+		{
+			name: "public single role id",
+			args: []string{"group-role", "set-user", "--group=cid", "--user=D1", "--role-id=r1"},
+			want: []string{"r1"},
+		},
+		{
+			name: "hidden legacy role ids",
+			args: []string{"group-role", "set-user", "--group=cid", "--user=D1", "--role-ids=r1,r2"},
+			want: []string{"r1", "r2"},
+		},
+		{
+			name: "hidden legacy empty role ids",
+			args: []string{"group-role", "set-user", "--group=cid", "--user=D1", "--role-ids="},
+			want: nil,
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			if err := runChatCoverageCommand(t, caller, tc.args...); err != nil {
+				t.Fatal(err)
+			}
+			if caller.calls != 1 {
+				t.Fatalf("tool calls = %d, want 1", caller.calls)
+			}
+			if got := caller.args["openRoleIds"]; !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("openRoleIds = %#v, want %#v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestChatGroupRoleSetUserRejectsConflictingRoleFlags(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	caller := &scriptedToolCaller{}
+	err := runChatCoverageCommand(t, caller,
+		"group-role", "set-user", "--group=cid", "--user=D1", "--role-id=r1", "--role-ids=r2")
+	if err == nil {
+		t.Fatal("set-user accepted --role-id with --role-ids, want validation error")
+	}
+	if !strings.Contains(err.Error(), "--role-id 与 --role-ids 不能同时指定") {
+		t.Fatalf("error = %v", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("tool calls = %d, want 0", caller.calls)
+	}
+}
+
+func TestChatGroupRoleSetUserRejectsMultiplePublicRoleIDs(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	caller := &scriptedToolCaller{}
+	err := runChatCoverageCommand(t, caller,
+		"group-role", "set-user", "--group=cid", "--user=D1", "--role-id=r1,r2")
+	if err == nil {
+		t.Fatal("set-user accepted multiple --role-id values, want validation error")
+	}
+	if !strings.Contains(err.Error(), "--role-id 只允许指定一个群身份") {
+		t.Fatalf("error = %v", err)
+	}
+	if caller.calls != 0 {
+		t.Fatalf("tool calls = %d, want 0", caller.calls)
+	}
+}
+
+func TestChatGroupRoleSetUserRejectsMissingOrEmptyPublicRoleID(t *testing.T) {
+	previousDeps, previousArgs := deps, os.Args
+	os.Args = []string{"dws", "chat"}
+	t.Cleanup(func() { deps, os.Args = previousDeps, previousArgs })
+
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "missing public role id",
+			args: []string{"group-role", "set-user", "--group=cid", "--user=D1"},
+			want: "role-id",
+		},
+		{
+			name: "empty public role id",
+			args: []string{"group-role", "set-user", "--group=cid", "--user=D1", "--role-id="},
+			want: "--role-id 不能为空",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			caller := &scriptedToolCaller{}
+			err := runChatCoverageCommand(t, caller, tc.args...)
+			if err == nil {
+				t.Fatal("set-user accepted a missing or empty --role-id, want validation error")
+			}
+			if !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v, want substring %q", err, tc.want)
+			}
+			if caller.calls != 0 {
+				t.Fatalf("tool calls = %d, want 0", caller.calls)
+			}
+		})
+	}
+}
+
+func TestChatGroupRoleSetUserRoleIDResolverDefensiveBranches(t *testing.T) {
+	newCommand := func(t *testing.T) *cobra.Command {
+		t.Helper()
+		cmd := &cobra.Command{}
+		cmd.Flags().String("role-id", "", "")
+		cmd.Flags().String("role-ids", "", "")
+		return cmd
+	}
+
+	t.Run("legacy flag without pre-run promotion", func(t *testing.T) {
+		cmd := newCommand(t)
+		if err := cmd.Flags().Set("role-ids", "r1,r2"); err != nil {
+			t.Fatal(err)
+		}
+		got, err := resolveChatGroupRoleSetUserRoleIDs(cmd)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if want := []string{"r1", "r2"}; !reflect.DeepEqual(got, want) {
+			t.Fatalf("role IDs = %#v, want %#v", got, want)
+		}
+	})
+
+	t.Run("no role flag", func(t *testing.T) {
+		_, err := resolveChatGroupRoleSetUserRoleIDs(newCommand(t))
+		if err == nil || !strings.Contains(err.Error(), "缺少必填参数 --role-id") {
+			t.Fatalf("error = %v, want missing --role-id validation", err)
+		}
+	})
+}
+
 func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T) {
 	previousDeps, previousArgs := deps, os.Args
 	os.Args = []string{"dws", "chat"}
@@ -293,7 +442,7 @@ func TestCrossPlatformCoverageChatCommandValidationAndSuccessEdges(t *testing.T)
 		{"group", "audit-join-validation", "--conversation-id=cid", "--record-id=1", "--applicant=D1", "--inviter=D2", "--status=AuditApprove", "--description=ok"},
 		{"mark-read", "--conversation-id=cid", "--message-id=mid"},
 		{"text", "translate", "--query=hello", "--to=zh_CN"},
-		{"group-role", "set-user", "--group=cid", "--user=D1", "--role-ids=r1"},
+		{"group-role", "set-user", "--group=cid", "--user=D1", "--role-id=r1"},
 		{"group-role", "remove-user", "--group=cid", "--user=D1", "--role-ids=r1"},
 		{"group-role", "query-user", "--group=cid", "--user=D1"},
 		{"group", "set-admin", "--group=cid", "--users=u1,D1"},
@@ -523,7 +672,7 @@ func TestCrossPlatformCoverageChatIMIDMigrationRequiredFlagErrors(t *testing.T)
 		{name: "role add missing conversation", path: []string{"group-role", "add"}, flag: map[string]string{"name": "role"}, want: "conversation-id"},
 		{name: "role update missing conversation", path: []string{"group-role", "update"}, flag: map[string]string{"role-id": "r1", "name": "role"}, want: "conversation-id"},
 		{name: "role remove missing conversation", path: []string{"group-role", "remove"}, flag: map[string]string{"role-id": "r1"}, want: "conversation-id"},
-		{name: "role set user missing conversation", path: []string{"group-role", "set-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"},
+		{name: "role set user missing conversation", path: []string{"group-role", "set-user"}, flag: map[string]string{"user": "D1", "role-id": "r1"}, want: "conversation-id"},
 		{name: "role remove user missing conversation", path: []string{"group-role", "remove-user"}, flag: map[string]string{"user": "D1", "role-ids": "r1"}, want: "conversation-id"},
 		{name: "role query user missing conversation", path: []string{"group-role", "query-user"}, flag: map[string]string{"user": "D1"}, want: "conversation-id"},
 		{name: "bots missing legacy group", path: []string{"group", "bots"}, want: "group"},

internal/helpers/framework2_changed_lines_coverage_test.go

@@ -58,6 +58,12 @@ func TestCrossPlatformCoverageFramework2MCPDataEdges(t *testing.T) {
 		t.Fatalf("decoded data=%#v err=%v", data, err)
 	}
 
+	InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{"count":7}`}}}})
+	data, err = CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil)
+	if err != nil || data.(map[string]any)["count"] != float64(7) {
+		t.Fatalf("legacy float64 number data=%#v err=%v", data, err)
+	}
+
 	InitDeps(&coverageErrorCaller{err: errors.New("transport failed")})
 	if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil {
 		t.Fatal("expected transport error")
@@ -73,6 +79,16 @@ func TestCrossPlatformCoverageFramework2MCPDataEdges(t *testing.T) {
 	if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil {
 		t.Fatal("expected invalid JSON error")
 	}
+
+	InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{} {}`}}}})
+	if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil || !strings.Contains(err.Error(), "存在多个 JSON 值") {
+		t.Fatalf("multiple JSON values error = %v", err)
+	}
+
+	InitDeps(&coverageErrorCaller{result: &edition.ToolResult{Content: []edition.ContentBlock{{Type: "text", Text: `{} {`}}}})
+	if _, err := CallMCPToolDataOnServer(context.Background(), "dev", "get_thing", nil); err == nil || !strings.Contains(err.Error(), "解析 get_thing 返回失败") {
+		t.Fatalf("trailing invalid JSON error = %v", err)
+	}
 }
 
 func TestCrossPlatformCoverageFramework2LegacyTextAdapter(t *testing.T) {

internal/helpers/helpers.go

@@ -6,6 +6,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 	"strings"
 	"time"
@@ -305,7 +306,14 @@ func CallMCPToolDataOnServer(ctx context.Context, serverID, toolName string, arg
 		return map[string]any{}, nil
 	}
 	var data any
-	if err := json.Unmarshal([]byte(text), &data); err != nil {
+	decoder := json.NewDecoder(strings.NewReader(text))
+	if err := decoder.Decode(&data); err != nil {
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", toolName, err))
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		if err == nil {
+			err = fmt.Errorf("存在多个 JSON 值")
+		}
 		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", toolName, err))
 	}
 	return data, nil

internal/helpers/recruit.go

@@ -0,0 +1,678 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/contract"
+	apperrors "github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/errors"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/output"
+)
+
+const (
+	recruitServerID      = "recruit"
+	recruitCreateJobTool = "create_job"
+	recruitGetJobTool    = "get_job_detail"
+	recruitListJobsTool  = "list_jobs"
+)
+
+var recruitDryRun = &contract.DryRunSpec{
+	PreviewKind: contract.DryRunPreviewRequest,
+	RemoteReads: false,
+}
+
+var (
+	recruitListResult = &contract.ResultSpec{
+		Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+		DataSchema: json.RawMessage(`{"type":"object","description":"当前页招聘职位查询结果；续页信息位于 meta.pagination","properties":{"jobs":{"type":"array","description":"当前页职位记录","items":{"type":"object","description":"招聘职位摘要","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}}},"additionalProperties":true}`),
+	}
+	recruitJobDetailResult = &contract.ResultSpec{
+		Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+		DataSchema: json.RawMessage(`{"type":"object","description":"招聘职位详情","properties":{"jobId":{"type":"string","description":"职位 ID"},"name":{"type":"string","description":"职位名称"},"description":{"type":"string","description":"职位描述"},"status":{"type":"number","description":"职位状态枚举值"}},"additionalProperties":true}`),
+	}
+	recruitCreateJobResult = &contract.ResultSpec{
+		Outcomes:   []contract.ResultOutcome{contract.ResultOutcomeSuccess, contract.ResultOutcomeFailure},
+		DataSchema: json.RawMessage(`{"type":"object","description":"招聘职位创建结果","properties":{"jobId":{"type":"string","description":"新创建的职位 ID"}},"required":["jobId"],"additionalProperties":true}`),
+	}
+)
+
+func recruitCursorPagination() *contract.PaginationSpec {
+	return &contract.PaginationSpec{Kind: contract.PaginationKindCursor, CursorParameter: "cursor"}
+}
+
+func newRecruitCommand() *cobra.Command {
+	contract.RegisterProductDecl(contract.ProductDecl{
+		ID: "recruit",
+		Selection: contract.ProductSelectionDecl{
+			AgentSummary: "查询和创建钉钉招聘职位",
+			UseWhen:      []string{"需要查询招聘职位列表、查看职位详情或创建职位时"},
+			AvoidWhen:    []string{"查询企业员工与组织架构使用 contact；查询人才池、职业历程或绩效使用 hrbrain"},
+		},
+	})
+
+	root := &cobra.Command{
+		Use:   "recruit",
+		Short: "钉钉招聘",
+		Long:  "查询和创建钉钉招聘中的职位信息。",
+		RunE:  groupRunE,
+	}
+	job := &cobra.Command{
+		Use:   "job",
+		Short: "招聘职位管理",
+		RunE:  groupRunE,
+	}
+	job.AddCommand(
+		newRecruitJobListCommand(),
+		newRecruitJobGetCommand(),
+		newRecruitJobCreateCommand(),
+	)
+	root.AddCommand(job)
+	return root
+}
+
+func newRecruitJobListCommand() *cobra.Command {
+	return NewLeafCommand(LeafSpec{
+		Use:           "list",
+		Short:         "查询招聘职位列表",
+		Long:          "按职位 ID、关键词、状态、创建人、职位性质等条件分页查询招聘职位。",
+		Example:       "  dws recruit job list --keyword Java --status open --size 20 --format json\n  dws recruit job list --job-ids JOB_ID_1,JOB_ID_2 --format json",
+		Server:        recruitServerID,
+		Tool:          recruitListJobsTool,
+		Safety:        recruitSafetyRead(),
+		OutputRollout: output.RolloutUnifiedActive,
+		Flags: []LeafFlag{
+			{Name: "job-ids", Usage: "职位 ID，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "jobIds"},
+			{Name: "required-edu", Usage: "学历要求枚举值", Kind: LeafInt, Bind: "requiredEdu"},
+			{Name: "status", Usage: "职位状态：draft/open/invalid/closed，多个值用逗号分隔", Bind: "statusList", Trim: true, OmitEmpty: true, Transform: transformRecruitStatuses},
+			{Name: "job-nature", Usage: "职位性质", Bind: "jobNature", Trim: true, OmitEmpty: true},
+			{Name: "campus", Usage: "是否为校园招聘", Kind: LeafBool, Bind: "campus"},
+			{Name: "start-modified-time", Usage: "修改时间范围起点", Bind: "startModifiedTime", Trim: true, OmitEmpty: true},
+			{Name: "end-modified-time", Usage: "修改时间范围终点", Bind: "endModifiedTime", Trim: true, OmitEmpty: true},
+			{Name: "creator-user-ids", Usage: "创建人 userId，多个值用逗号分隔", Kind: LeafStringSlice, Bind: "creatorUserIds"},
+			{Name: "keyword", Usage: "职位搜索关键词", Bind: "keyword", Trim: true, OmitEmpty: true},
+			{Name: "category", Usage: "职位分类", Bind: "category", Trim: true, OmitEmpty: true},
+			{Name: "cursor", Usage: "分页游标；首次查询不传，翻页时原样回填返回的 nextCursor", Bind: "cursor", Trim: true, OmitEmpty: true, Transform: transformRecruitCursor},
+			{Name: "size", Usage: "分页大小，默认 20", Kind: LeafInt, Bind: "size", Default: "20", ArgDefault: "20"},
+		},
+		Validate:   validateRecruitList,
+		ResultCall: recruitResultCall,
+		Contract: LeafContract{
+			Identity:    contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitListJobsTool, CanonicalPath: "recruit.list_jobs", CLIPath: "recruit job list", PrimaryCLIPath: "recruit job list"},
+			Description: "按条件分页查询招聘职位",
+			DryRun:      recruitDryRun,
+			Result:      recruitListResult,
+			Pagination:  recruitCursorPagination(),
+			Interface:   recruitMCPInterface(recruitListJobsTool),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "按关键词、状态、创建人等条件分页查询招聘职位",
+				UseWhen:      []string{"需要查找职位、筛选在招职位或取得 jobId 时"},
+				AvoidWhen:    []string{"已经持有明确 jobId 且需要完整详情时使用 recruit job get"},
+				Examples:     []string{`dws recruit job list --keyword "Java" --status open --size 20 --format json`},
+			},
+			Parameters: recruitListParamDecls(),
+		},
+	})
+}
+
+func recruitListToolArgs(args map[string]any) map[string]any {
+	params := map[string]any{"param": map[string]any{}, "size": args["size"]}
+	query := params["param"].(map[string]any)
+	for key, value := range args {
+		switch key {
+		case "cursor":
+			params[key] = value
+		case "size":
+		default:
+			query[key] = value
+		}
+	}
+	return params
+}
+
+func recruitResultCall(cmd *cobra.Command, tool string, args map[string]any) (output.CommandResult, error) {
+	toolArgs := args
+	if tool == recruitListJobsTool {
+		toolArgs = recruitListToolArgs(args)
+	}
+	if deps.Caller.DryRun() {
+		return output.Success(map[string]any{
+			"tool": tool, "arguments": toolArgs, "executed": false,
+		}, output.WithDryRun()), nil
+	}
+	data, err := callRecruitMCPToolData(cmd.Context(), tool, toolArgs)
+	if err != nil {
+		return nil, err
+	}
+	clean, err := recruitBusinessResultData(data, tool)
+	if err != nil {
+		return recruitResponseFailure(err), nil
+	}
+	switch tool {
+	case recruitListJobsTool:
+		listData, meta, err := recruitListResultData(clean)
+		if err != nil {
+			return recruitInvalidResponse(err), nil
+		}
+		return output.Success(listData, output.WithMeta(meta)), nil
+	case recruitGetJobTool, recruitCreateJobTool:
+		if err := validateRecruitJobResult(clean, tool, args); err != nil {
+			return recruitInvalidResponse(err), nil
+		}
+		return output.Success(clean), nil
+	default:
+		return recruitInvalidResponse(fmt.Errorf("不支持校验 %s 的业务结果", tool)), nil
+	}
+}
+
+func validateRecruitJobResult(data map[string]any, tool string, args map[string]any) error {
+	jobID, ok := data["jobId"].(string)
+	if !ok || strings.TrimSpace(jobID) == "" {
+		return fmt.Errorf("%s 返回值缺少非空字符串字段 jobId", tool)
+	}
+	if tool != recruitGetJobTool {
+		return nil
+	}
+	requestedJobID, ok := args["jobId"].(string)
+	if !ok || strings.TrimSpace(requestedJobID) == "" {
+		return fmt.Errorf("%s 请求缺少非空字符串字段 jobId", tool)
+	}
+	if strings.TrimSpace(jobID) != strings.TrimSpace(requestedJobID) {
+		return fmt.Errorf("%s 返回的 jobId %q 与请求的 jobId %q 不一致", tool, jobID, requestedJobID)
+	}
+	return nil
+}
+
+func callRecruitMCPToolData(ctx context.Context, tool string, args map[string]any) (any, error) {
+	text, err := callMCPToolReturnTextOnServer(ctx, recruitServerID, tool, args)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(text) == "" {
+		return map[string]any{}, nil
+	}
+	var data any
+	decoder := json.NewDecoder(strings.NewReader(text))
+	decoder.UseNumber()
+	if err := decoder.Decode(&data); err != nil {
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err))
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		if err == nil {
+			err = fmt.Errorf("存在多个 JSON 值")
+		}
+		return nil, apperrors.NewInternal(fmt.Sprintf("解析 %s 返回失败: %v", tool, err))
+	}
+	return data, nil
+}
+
+func recruitResponseFailure(err error) output.CommandResult {
+	var businessFailure *recruitBusinessFailure
+	if errors.As(err, &businessFailure) {
+		return output.Failure(&output.ErrorInfo{
+			Type: "api", Message: businessFailure.Error(),
+		})
+	}
+	return recruitInvalidResponse(err)
+}
+
+type recruitBusinessFailure struct {
+	message string
+}
+
+func (e *recruitBusinessFailure) Error() string {
+	return e.message
+}
+
+func recruitBusinessResultData(data any, tool string) (map[string]any, error) {
+	object, ok := data.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("%s 返回值必须是 JSON 对象", tool)
+	}
+	successValue, hasSuccess := object["success"]
+	resultValue, hasResult := object["result"]
+	if !hasSuccess && !hasResult {
+		return object, nil
+	}
+	if !hasSuccess || !hasResult {
+		return nil, fmt.Errorf("%s 返回的 Connector 信封必须同时包含 success 和 result", tool)
+	}
+	success, ok := successValue.(bool)
+	if !ok {
+		return nil, fmt.Errorf("%s 返回的 Connector 信封字段 success 必须是布尔值", tool)
+	}
+	if !success {
+		message, _ := object["message"].(string)
+		if strings.TrimSpace(message) == "" {
+			message = "Connector 返回 success=false"
+		}
+		return nil, &recruitBusinessFailure{message: fmt.Sprintf("%s 调用失败: %s", tool, message)}
+	}
+	result, ok := resultValue.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("%s 返回值的 result 必须是 JSON 对象", tool)
+	}
+	return result, nil
+}
+
+func recruitInvalidResponse(err error) output.CommandResult {
+	return output.Failure(&output.ErrorInfo{
+		Type: "api", Subtype: "invalid_response", Message: err.Error(),
+		Hint: "保留原始响应并停止后续操作；不要依据不完整结果继续处理。",
+	})
+}
+
+func recruitListResultData(data any) (any, *output.Meta, error) {
+	object, ok := data.(map[string]any)
+	if !ok {
+		return nil, nil, fmt.Errorf("%s 返回值必须是 JSON 对象", recruitListJobsTool)
+	}
+	// The Connector envelope has already been removed by recruitResultCall.
+	// Only normalize the list business payload here so fields named success or
+	// result inside that payload cannot be mistaken for another envelope.
+	hasMore, ok := object["hasMore"].(bool)
+	if !ok {
+		return nil, nil, fmt.Errorf("list_jobs 返回值缺少布尔字段 hasMore")
+	}
+	nextToken := ""
+	if hasMore {
+		if raw, exists := object["nextCursor"]; exists && raw != nil {
+			var err error
+			nextToken, err = normalizeRecruitNextCursor(raw)
+			if err != nil {
+				return nil, nil, err
+			}
+		}
+		if nextToken == "" {
+			return nil, nil, fmt.Errorf("list_jobs 返回 hasMore=true 但缺少 nextCursor")
+		}
+	}
+	clean := make(map[string]any, len(object))
+	for key, value := range object {
+		if key != "hasMore" && key != "nextCursor" {
+			clean[key] = value
+		}
+	}
+	if jobs, exists := clean["list"]; exists {
+		if _, alreadyNormalized := clean["jobs"]; !alreadyNormalized {
+			clean["jobs"] = jobs
+		}
+		delete(clean, "list")
+	}
+	pagination := &output.Pagination{EndpointExhausted: !hasMore, NextToken: nextToken, Pages: 1}
+	meta := &output.Meta{Pagination: pagination}
+	if jobs, exists := clean["jobs"].([]any); exists {
+		meta.Count = output.NewCount(len(jobs))
+		pagination.Items = len(jobs)
+	}
+	return clean, meta, nil
+}
+
+func normalizeRecruitNextCursor(raw any) (string, error) {
+	var value string
+	switch cursor := raw.(type) {
+	case string:
+		value = strings.TrimSpace(cursor)
+	case json.Number:
+		value = string(cursor)
+	case float64:
+		value = strconv.FormatFloat(cursor, 'f', -1, 64)
+	default:
+		return "", fmt.Errorf("list_jobs 的 nextCursor 必须是字符串或数字")
+	}
+	parsed, err := strconv.ParseInt(value, 10, 64)
+	if err != nil || parsed < 0 {
+		return "", fmt.Errorf("list_jobs 的 nextCursor 必须是可回填的非负十进制 int64 游标")
+	}
+	return strconv.FormatInt(parsed, 10), nil
+}
+
+func newRecruitJobGetCommand() *cobra.Command {
+	return NewLeafCommand(LeafSpec{
+		Use:           "get",
+		Short:         "查询招聘职位详情",
+		Long:          "根据职位 ID 查询招聘职位详情。",
+		Example:       "  dws recruit job get --job-id JOB_ID --format json",
+		Server:        recruitServerID,
+		Tool:          recruitGetJobTool,
+		Safety:        recruitSafetyRead(),
+		OutputRollout: output.RolloutUnifiedActive,
+		ResultCall:    recruitResultCall,
+		Flags: []LeafFlag{{
+			Name: "job-id", Usage: "职位 ID（必填）", Bind: "jobId", Trim: true,
+			Required: true, RequiredHint: "--job-id 为必填",
+		}},
+		Contract: LeafContract{
+			Identity:    contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitGetJobTool, CanonicalPath: "recruit.get_job_detail", CLIPath: "recruit job get", PrimaryCLIPath: "recruit job get"},
+			Description: "根据职位 ID 查询招聘职位详情",
+			DryRun:      recruitDryRun,
+			Result:      recruitJobDetailResult,
+			Interface:   recruitMCPInterface(recruitGetJobTool),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "获取指定招聘职位的完整信息",
+				UseWhen:      []string{"已经持有明确 jobId，需要查看职位详情时"},
+				AvoidWhen:    []string{"不知道 jobId 时先使用 recruit job list 查询"},
+				Examples:     []string{"dws recruit job get --job-id <JOB_ID> --format json"},
+			},
+			Parameters: []contract.ParamDecl{{Name: "job-id", Property: "jobId", Required: boolPtr(true), InterfaceType: "string"}},
+		},
+	})
+}
+
+func newRecruitJobCreateCommand() *cobra.Command {
+	return NewLeafCommand(LeafSpec{
+		Use:           "create",
+		Short:         "创建招聘职位",
+		Long:          "从 JSON 文件读取职位信息并创建招聘职位。该操作会写入远端招聘系统，执行前必须确认。",
+		Example:       "  dws recruit job create --from ./job.json --dry-run --format json\n  dws recruit job create --from ./job.json --format json",
+		Server:        recruitServerID,
+		Tool:          recruitCreateJobTool,
+		Safety:        recruitSafetyCreate(),
+		OutputRollout: output.RolloutUnifiedActive,
+		ResultCall:    recruitResultCall,
+		Flags: []LeafFlag{{
+			Name: "from", Usage: "职位 JSON 文件路径（必填）", Bind: "atsAddJobParam", Trim: true,
+			Required: true, RequiredHint: "--from 为必填", Transform: loadRecruitJobFile,
+		}},
+		Contract: LeafContract{
+			Identity:    contract.ToolIdentitySpec{ProductID: "recruit", Name: recruitCreateJobTool, CanonicalPath: "recruit.create_job", CLIPath: "recruit job create", PrimaryCLIPath: "recruit job create"},
+			Description: "从 JSON 文件创建招聘职位",
+			DryRun:      recruitDryRun,
+			Result:      recruitCreateJobResult,
+			Interface:   recruitMCPInterface(recruitCreateJobTool),
+			Selection: contract.SelectionSpec{
+				AgentSummary: "使用结构化 JSON 创建招聘职位",
+				UseWhen:      []string{"用户明确要求新建职位，并已准备或同意生成职位 JSON 时；文件必须包含 name、description、jobNature、requiredEdu、extData、creatorUserId；jobNature 固定为 FULL-TIME；creatorUserId 必须使用真实创建人 userId；ownerUserIds 可选"},
+				AvoidWhen:    []string{"仅查询职位时使用 recruit job list 或 recruit job get"},
+				Examples:     []string{"dws recruit job create --from ./job.json --dry-run --format json"},
+			},
+			Parameters: []contract.ParamDecl{{Name: "from", Property: "atsAddJobParam", Required: boolPtr(true), InterfaceType: "object", Description: "职位 JSON 文件；CLI 校验后原样作为 atsAddJobParam 对象发送；creatorUserId 为必填的创建人 userId，ownerUserIds 为可选的负责人 userId 字符串数组"}},
+		},
+	})
+}
+
+func recruitListParamDecls() []contract.ParamDecl {
+	return []contract.ParamDecl{
+		{Name: "job-ids", Property: "param.jobIds", InterfaceType: "array"},
+		{Name: "required-edu", Property: "param.requiredEdu", InterfaceType: "number"},
+		{Name: "status", Property: "param.statusList", InterfaceType: "array", Enum: []string{"draft", "open", "invalid", "closed"}},
+		{Name: "job-nature", Property: "param.jobNature", InterfaceType: "string"},
+		{Name: "campus", Property: "param.campus", InterfaceType: "boolean"},
+		{Name: "start-modified-time", Property: "param.startModifiedTime", InterfaceType: "string"},
+		{Name: "end-modified-time", Property: "param.endModifiedTime", InterfaceType: "string"},
+		{Name: "creator-user-ids", Property: "param.creatorUserIds", InterfaceType: "array"},
+		{Name: "keyword", Property: "param.keyword", InterfaceType: "string"},
+		{Name: "category", Property: "param.category", InterfaceType: "string"},
+		{Name: "cursor", Property: "cursor", InterfaceType: "number"},
+		{Name: "size", Property: "size", InterfaceType: "number"},
+	}
+}
+
+func recruitMCPInterface(tool string) *contract.InterfaceSpec {
+	return &contract.InterfaceSpec{
+		Mode:         contract.InterfaceModeMCP,
+		Availability: contract.InterfaceAvailable,
+		Ref:          &contract.InterfaceRefSpec{ProductID: recruitServerID, RPCName: tool},
+	}
+}
+
+func recruitSafetyRead() contract.SafetySpec {
+	return contract.SafetySpec{Effect: "read", Risk: "low", Confirmation: "not_required", Idempotency: "idempotent"}
+}
+
+func recruitSafetyCreate() contract.SafetySpec {
+	return contract.SafetySpec{Effect: "write", Risk: "medium", Confirmation: "user_required", Idempotency: "non_idempotent"}
+}
+
+func transformRecruitStatuses(raw string) (any, error) {
+	values := strings.Split(raw, ",")
+	statuses := make([]int, 0, len(values))
+	seen := make(map[int]bool, len(values))
+	lookup := map[string]int{"draft": 0, "open": 1, "invalid": 2, "closed": 3}
+	for _, value := range values {
+		name := strings.ToLower(strings.TrimSpace(value))
+		if name == "" {
+			continue
+		}
+		status, ok := lookup[name]
+		if !ok {
+			return nil, apperrors.NewValidation(fmt.Sprintf("--status 不支持 %q，可选 draft/open/invalid/closed", value))
+		}
+		if !seen[status] {
+			statuses = append(statuses, status)
+			seen[status] = true
+		}
+	}
+	return statuses, nil
+}
+
+func transformRecruitCursor(raw string) (any, error) {
+	value := strings.TrimSpace(raw)
+	cursor, err := strconv.ParseInt(value, 10, 64)
+	if err != nil || cursor < 0 {
+		return nil, apperrors.NewValidation("--cursor 必须是大于或等于 0 的整数")
+	}
+	return cursor, nil
+}
+
+func validateRecruitList(cmd *cobra.Command, _ []string) error {
+	size, _ := cmd.Flags().GetInt("size")
+	if cmd.Flags().Changed("size") && (size < 1 || size > 100) {
+		return apperrors.NewValidation("--size 必须在 1 到 100 之间")
+	}
+	requiredEdu, _ := cmd.Flags().GetInt("required-edu")
+	if cmd.Flags().Changed("required-edu") && (requiredEdu < 1 || requiredEdu > 9) {
+		return apperrors.NewValidation("--required-edu 必须在 1 到 9 之间")
+	}
+	return nil
+}
+
+func loadRecruitJobFile(path string) (any, error) {
+	data, err := os.ReadFile(strings.TrimSpace(path))
+	if err != nil {
+		return nil, fmt.Errorf("读取职位 JSON 失败: %w", err)
+	}
+	var job map[string]any
+	if err := json.Unmarshal(data, &job); err != nil {
+		return nil, apperrors.NewValidation(fmt.Sprintf("职位文件不是有效的 JSON 对象: %v", err))
+	}
+	if job == nil {
+		return nil, apperrors.NewValidation("职位 JSON 顶层必须是对象")
+	}
+	if err := validateRecruitJob(job); err != nil {
+		return nil, err
+	}
+	return job, nil
+}
+
+func validateRecruitJob(job map[string]any) error {
+	for _, name := range []string{"name", "description", "jobNature", "requiredEdu", "extData", "creatorUserId"} {
+		value, ok := job[name]
+		if !ok || value == nil || (isString(value) && strings.TrimSpace(value.(string)) == "") {
+			return apperrors.NewValidation(fmt.Sprintf("职位 JSON 缺少必填字段 %s", name))
+		}
+	}
+	for _, name := range []string{"name", "description", "jobNature"} {
+		if !isString(job[name]) {
+			return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是字符串", name))
+		}
+	}
+	if job["jobNature"].(string) != "FULL-TIME" {
+		return apperrors.NewValidation("职位 JSON 字段 jobNature 当前仅支持 FULL-TIME")
+	}
+	requiredEdu, ok := job["requiredEdu"].(float64)
+	if !ok {
+		return apperrors.NewValidation("职位 JSON 字段 requiredEdu 必须是数字")
+	}
+	if requiredEdu < 1 || requiredEdu > 9 || requiredEdu != float64(int(requiredEdu)) {
+		return apperrors.NewValidation("职位 JSON 字段 requiredEdu 必须是 1 到 9 的整数")
+	}
+
+	minSalary, hasMinSalary, err := optionalRecruitNumber(job, "minSalary")
+	if err != nil {
+		return err
+	}
+	maxSalary, hasMaxSalary, err := optionalRecruitNumber(job, "maxSalary")
+	if err != nil {
+		return err
+	}
+	if hasMinSalary && hasMaxSalary && minSalary > maxSalary {
+		return apperrors.NewValidation("职位 JSON 中 minSalary 不能大于 maxSalary")
+	}
+
+	for _, name := range []string{"province", "city", "district", "category"} {
+		if value, exists := job[name]; exists && value != nil && !isString(value) {
+			return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是字符串", name))
+		}
+	}
+	if value, exists := job["campus"]; exists && value != nil {
+		if _, ok := value.(bool); !ok {
+			return apperrors.NewValidation("职位 JSON 字段 campus 必须是布尔值")
+		}
+	}
+	if err := validateRecruitIdentityFields(job); err != nil {
+		return err
+	}
+	if err := validateRecruitAddress(job); err != nil {
+		return err
+	}
+	extData, ok := job["extData"].(map[string]any)
+	if !ok {
+		return apperrors.NewValidation("职位 JSON 字段 extData 必须是对象")
+	}
+	if err := validateRecruitExtData(extData); err != nil {
+		return err
+	}
+	return nil
+}
+
+func optionalRecruitNumber(values map[string]any, name string) (float64, bool, error) {
+	value, exists := values[name]
+	if !exists || value == nil {
+		return 0, false, nil
+	}
+	number, ok := value.(float64)
+	if !ok {
+		return 0, false, apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 %s 必须是数字", name))
+	}
+	return number, true, nil
+}
+
+func validateRecruitIdentityFields(job map[string]any) error {
+	if _, ok := job["creatorUserId"].(string); !ok {
+		return apperrors.NewValidation("职位 JSON 字段 creatorUserId 必须是非空字符串")
+	}
+	if value, exists := job["ownerUserIds"]; exists && value != nil {
+		ownerUserIDs, ok := value.([]any)
+		if !ok {
+			return apperrors.NewValidation("职位 JSON 字段 ownerUserIds 必须是字符串数组")
+		}
+		for _, owner := range ownerUserIDs {
+			ownerUserID, ok := owner.(string)
+			if !ok || strings.TrimSpace(ownerUserID) == "" {
+				return apperrors.NewValidation("职位 JSON 字段 ownerUserIds 只能包含非空字符串")
+			}
+		}
+	}
+	return nil
+}
+
+func validateRecruitAddress(job map[string]any) error {
+	value, exists := job["address"]
+	if !exists || value == nil {
+		return nil
+	}
+	address, ok := value.(map[string]any)
+	if !ok {
+		return apperrors.NewValidation("职位 JSON 字段 address 必须是对象")
+	}
+	for _, name := range []string{"name", "detail", "longitude", "latitude"} {
+		field, exists := address[name]
+		text, ok := field.(string)
+		if !exists || !ok || strings.TrimSpace(text) == "" {
+			return apperrors.NewValidation(fmt.Sprintf("职位 JSON 字段 address.%s 必须是非空字符串", name))
+		}
+	}
+	return nil
+}
+
+func validateRecruitExtData(extData map[string]any) error {
+	if value, exists := extData["headCount"]; exists && value != nil {
+		headCount, ok := value.(float64)
+		if !ok || headCount < 1 || headCount > 999 || headCount != float64(int(headCount)) {
+			return apperrors.NewValidation("职位 JSON 字段 extData.headCount 必须是 1 到 999 的整数")
+		}
+	}
+	if value, exists := extData["source"]; exists && value != nil && !isString(value) {
+		return apperrors.NewValidation("职位 JSON 字段 extData.source 必须是字符串")
+	}
+	if value, exists := extData["fullTimeExtData"]; exists && value != nil {
+		fullTime, ok := value.(map[string]any)
+		if !ok {
+			return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData 必须是对象")
+		}
+		if err := validateRecruitFullTimeExtData(fullTime); err != nil {
+			return err
+		}
+	}
+	if value, exists := extData["tags"]; exists && value != nil {
+		tags, ok := value.([]any)
+		if !ok {
+			return apperrors.NewValidation("职位 JSON 字段 extData.tags 必须是数组")
+		}
+		for _, value := range tags {
+			tag, ok := value.(map[string]any)
+			if !ok {
+				return apperrors.NewValidation("职位 JSON 字段 extData.tags 只能包含对象")
+			}
+			name, ok := tag["name"].(string)
+			if !ok || strings.TrimSpace(name) == "" {
+				return apperrors.NewValidation("职位 JSON 字段 extData.tags[].name 必须是非空字符串")
+			}
+		}
+	}
+	return nil
+}
+
+func validateRecruitFullTimeExtData(fullTime map[string]any) error {
+	salaryMonth, hasSalaryMonth, err := optionalRecruitNumber(fullTime, "salaryMonth")
+	if err != nil {
+		return err
+	}
+	if hasSalaryMonth && (salaryMonth < 12 || salaryMonth > 24 || salaryMonth != float64(int(salaryMonth))) {
+		return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.salaryMonth 必须是 12 到 24 的整数")
+	}
+	minExperience, hasMinExperience, err := optionalRecruitNumber(fullTime, "minJobExperience")
+	if err != nil {
+		return err
+	}
+	maxExperience, hasMaxExperience, err := optionalRecruitNumber(fullTime, "maxJobExperience")
+	if err != nil {
+		return err
+	}
+	if hasMinExperience && minExperience < 0 {
+		return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.minJobExperience 不能小于 0")
+	}
+	if hasMaxExperience && maxExperience < 0 {
+		return apperrors.NewValidation("职位 JSON 字段 extData.fullTimeExtData.maxJobExperience 不能小于 0")
+	}
+	if hasMinExperience && hasMaxExperience && minExperience > maxExperience {
+		return apperrors.NewValidation("职位 JSON 中 minJobExperience 不能大于 maxJobExperience")
+	}
+	return nil
+}
+
+func isString(value any) bool {
+	_, ok := value.(string)
+	return ok
+}

internal/helpers/register_products_test.go

@@ -31,7 +31,7 @@ func TestCrossPlatformCoveragePublicProductCommandsBuildCompleteUniqueTrees(t *t
 	for _, want := range []string{
 		"agoal", "aisearch", "aitable", "attendance", "calendar", "chat",
 		"contact", "devdoc", "ding", "doc", "drive", "live", "mail",
-		"markdown", "minutes", "oa", "report", "sheet", "todo", "wiki", "whiteboard",
+		"markdown", "minutes", "oa", "recruit", "report", "sheet", "todo", "wiki", "whiteboard",
 	} {
 		if !seenProducts[want] {
 			t.Errorf("public product %q was not registered", want)

internal/helpers/register_recruit.go

@@ -0,0 +1,11 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package helpers
+
+// 招聘是开源库显式维护的公开命令，不依赖生成式产品注册表。
+func init() {
+	RegisterPublic(func() Handler {
+		return wukongHandler{name: "recruit", buildFn: newRecruitCommand}
+	})
+}

internal/interfacesnapshot/command_migrations.go

@@ -0,0 +1,639 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package interfacesnapshot
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"reflect"
+	"strconv"
+	"strings"
+)
+
+const CommandMigrationManifestVersion = 1
+
+const (
+	CommandMigrationPending  = "pending"
+	CommandMigrationConsumed = "consumed"
+
+	CommandMigrationMove           = "command_move"
+	CommandMigrationFlagExtraction = "flag_extraction"
+)
+
+// CommandMigrationManifest governs compatibility-preserving surface moves that
+// cannot be represented as an in-command flag rename. The merge-base owns the
+// authorization; the candidate copy is only a lifecycle receipt.
+type CommandMigrationManifest struct {
+	Version    int                `json:"version"`
+	Migrations []CommandMigration `json:"migrations"`
+}
+
+type CommandMigration struct {
+	Kind        string                 `json:"kind"`
+	Legacy      CommandMigrationSide   `json:"legacy"`
+	Replacement CommandMigrationSide   `json:"replacement"`
+	LegacyFlag  CommandMigrationFlag   `json:"legacy_flag"`
+	Schema      CommandMigrationSchema `json:"schema"`
+	State       string                 `json:"state"`
+	Reason      string                 `json:"reason"`
+}
+
+type CommandMigrationSide struct {
+	Command string                `json:"command"`
+	Before  CommandMigrationState `json:"before"`
+	After   CommandMigrationState `json:"after"`
+}
+
+type CommandMigrationState struct {
+	Present  bool `json:"present"`
+	Runnable bool `json:"runnable,omitempty"`
+	Hidden   bool `json:"hidden,omitempty"`
+}
+
+type CommandMigrationFlag struct {
+	Name   string             `json:"name,omitempty"`
+	Before FlagMigrationState `json:"before"`
+	After  FlagMigrationState `json:"after"`
+}
+
+type CommandMigrationSchema struct {
+	ProductID         string                      `json:"product_id"`
+	SourceToolID      string                      `json:"source_tool_id"`
+	ReplacementToolID string                      `json:"replacement_tool_id"`
+	Parameters        []CommandParameterMigration `json:"parameters"`
+}
+
+type CommandParameterMigration struct {
+	From                string                      `json:"from"`
+	To                  string                      `json:"to,omitempty"`
+	ReplacementConstant *CommandReplacementConstant `json:"replacement_constant,omitempty"`
+}
+
+type CommandReplacementConstant struct {
+	Property string `json:"property"`
+	Value    bool   `json:"value"`
+}
+
+func ReadCommandMigrationManifest(r io.Reader) (CommandMigrationManifest, error) {
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return CommandMigrationManifest{}, fmt.Errorf("read command migration manifest: %w", err)
+	}
+	var manifest CommandMigrationManifest
+	decoder := json.NewDecoder(bytes.NewReader(data))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&manifest); err != nil {
+		return CommandMigrationManifest{}, err
+	}
+	if err := decoder.Decode(&struct{}{}); err != io.EOF {
+		if err == nil {
+			return CommandMigrationManifest{}, fmt.Errorf("command migration manifest contains trailing multiple JSON values")
+		}
+		return CommandMigrationManifest{}, fmt.Errorf("read trailing command migration manifest data: %w", err)
+	}
+	strict := json.NewDecoder(bytes.NewReader(data))
+	strict.UseNumber()
+	if err := validateLabeledMigrationJSONValue(strict, "$", reflect.TypeOf(CommandMigrationManifest{}), "command"); err != nil {
+		return CommandMigrationManifest{}, err
+	}
+	if err := manifest.Validate(); err != nil {
+		return CommandMigrationManifest{}, err
+	}
+	return manifest, nil
+}
+
+func (m CommandMigrationManifest) Validate() error {
+	if m.Version != CommandMigrationManifestVersion {
+		return fmt.Errorf("unsupported command migration manifest version %d (want %d)", m.Version, CommandMigrationManifestVersion)
+	}
+	if m.Migrations == nil {
+		return fmt.Errorf("command migration manifest migrations must be an array")
+	}
+	seen := make(map[string]bool, len(m.Migrations))
+	for index, migration := range m.Migrations {
+		if err := migration.validate(); err != nil {
+			return fmt.Errorf("command migration %d: %w", index, err)
+		}
+		if seen[migration.key()] {
+			return fmt.Errorf("command migration %d duplicates %s", index, migration.displayKey())
+		}
+		seen[migration.key()] = true
+	}
+	return nil
+}
+
+func (m CommandMigration) validate() error {
+	if m.Kind != CommandMigrationMove && m.Kind != CommandMigrationFlagExtraction {
+		return fmt.Errorf("invalid kind %q", m.Kind)
+	}
+	if !isExactCommandPath(m.Legacy.Command) || !isExactCommandPath(m.Replacement.Command) {
+		return fmt.Errorf("legacy and replacement must be exact command paths rooted at dws")
+	}
+	if m.Legacy.Command == m.Replacement.Command {
+		return fmt.Errorf("legacy and replacement command paths must differ")
+	}
+	if strings.TrimSpace(m.Reason) == "" || m.Reason != strings.TrimSpace(m.Reason) {
+		return fmt.Errorf("migration must include a non-empty trimmed reason")
+	}
+	if m.State != CommandMigrationPending && m.State != CommandMigrationConsumed {
+		return fmt.Errorf("invalid state %q", m.State)
+	}
+	for label, state := range map[string]CommandMigrationState{
+		"legacy before":      m.Legacy.Before,
+		"legacy after":       m.Legacy.After,
+		"replacement before": m.Replacement.Before,
+		"replacement after":  m.Replacement.After,
+	} {
+		if err := state.validate(label); err != nil {
+			return err
+		}
+	}
+	if !m.Legacy.Before.Present || !m.Legacy.Before.Runnable || m.Legacy.Before.Hidden ||
+		!m.Legacy.After.Present || !m.Legacy.After.Runnable {
+		return fmt.Errorf("legacy command must remain runnable and start visible")
+	}
+	if m.Replacement.Before.Present || !m.Replacement.After.Present || !m.Replacement.After.Runnable || m.Replacement.After.Hidden {
+		return fmt.Errorf("replacement command must migrate exactly from absent to visible runnable")
+	}
+	if err := m.Schema.validate(m.Kind); err != nil {
+		return err
+	}
+	switch m.Kind {
+	case CommandMigrationMove:
+		if strings.HasPrefix(m.Replacement.Command, m.Legacy.Command+" ") ||
+			strings.HasPrefix(m.Legacy.Command, m.Replacement.Command+" ") {
+			return fmt.Errorf("command_move legacy and replacement command paths must not have an ancestor relationship")
+		}
+		if !m.Legacy.After.Hidden {
+			return fmt.Errorf("command_move legacy command must migrate exactly from visible to hidden")
+		}
+		if m.LegacyFlag != (CommandMigrationFlag{}) {
+			return fmt.Errorf("command_move must not declare legacy_flag")
+		}
+		if m.Schema.SourceToolID != m.Schema.ReplacementToolID {
+			return fmt.Errorf("command_move must retain one stable Schema tool identity")
+		}
+	case CommandMigrationFlagExtraction:
+		if m.Legacy.After.Hidden || m.Legacy.Before != m.Legacy.After {
+			return fmt.Errorf("flag_extraction legacy command must remain visible and unchanged")
+		}
+		if err := m.LegacyFlag.validate(); err != nil {
+			return err
+		}
+		if m.Schema.SourceToolID == m.Schema.ReplacementToolID {
+			return fmt.Errorf("flag_extraction requires a distinct replacement Schema tool")
+		}
+		if m.LegacyFlag.Before.Type != "bool" || m.LegacyFlag.After.Type != "bool" {
+			return fmt.Errorf("flag_extraction legacy_flag must be an optional bool")
+		}
+		var extracted *CommandParameterMigration
+		constantCount := 0
+		for index := range m.Schema.Parameters {
+			parameter := &m.Schema.Parameters[index]
+			if parameter.ReplacementConstant == nil {
+				continue
+			}
+			constantCount++
+			if parameter.From == m.LegacyFlag.Name {
+				extracted = parameter
+			}
+		}
+		if constantCount != 1 {
+			return fmt.Errorf("flag_extraction must declare exactly one replacement constant")
+		}
+		if extracted == nil {
+			return fmt.Errorf("flag_extraction must map the exact extracted flag to replacement_constant")
+		}
+		if !extracted.ReplacementConstant.Value {
+			return fmt.Errorf("flag_extraction v1 replacement_constant must be true")
+		}
+		wantNoOpt := strconv.FormatBool(extracted.ReplacementConstant.Value)
+		if m.LegacyFlag.Before.NoOpt != wantNoOpt || m.LegacyFlag.After.NoOpt != wantNoOpt {
+			return fmt.Errorf("flag_extraction legacy_flag no_opt must equal replacement constant %q", wantNoOpt)
+		}
+	}
+	return nil
+}
+
+func (s CommandMigrationState) validate(label string) error {
+	if !s.Present {
+		if s.Runnable || s.Hidden {
+			return fmt.Errorf("%s absent state must not declare command attributes", label)
+		}
+		return nil
+	}
+	if !s.Runnable {
+		return fmt.Errorf("%s present state must be runnable", label)
+	}
+	return nil
+}
+
+func (f CommandMigrationFlag) validate() error {
+	if !isExactFlagName(f.Name) {
+		return fmt.Errorf("legacy_flag name must be an exact flag")
+	}
+	if err := f.Before.validate("legacy_flag before"); err != nil {
+		return err
+	}
+	if err := f.After.validate("legacy_flag after"); err != nil {
+		return err
+	}
+	if !f.Before.Present || !f.After.Present || f.Before.Hidden || !f.After.Hidden {
+		return fmt.Errorf("legacy_flag must migrate exactly from visible to hidden while remaining present")
+	}
+	if f.Before.Required || f.After.Required {
+		return fmt.Errorf("legacy_flag must remain optional before and after extraction")
+	}
+	before := f.Before
+	after := f.After
+	before.Hidden = false
+	after.Hidden = false
+	if before != after {
+		return fmt.Errorf("legacy_flag may change only hidden visibility")
+	}
+	return nil
+}
+
+func (s CommandMigrationSchema) validate(kind string) error {
+	for label, value := range map[string]string{
+		"product_id":          s.ProductID,
+		"source_tool_id":      s.SourceToolID,
+		"replacement_tool_id": s.ReplacementToolID,
+	} {
+		if !isExactSchemaIdentifier(value) {
+			return fmt.Errorf("schema %s must be an exact identifier", label)
+		}
+	}
+	if s.Parameters == nil {
+		return fmt.Errorf("schema parameters must be an array")
+	}
+	seenFrom := map[string]bool{}
+	seenTo := map[string]bool{}
+	seenConstantProperty := map[string]bool{}
+	for index, parameter := range s.Parameters {
+		if !isExactFlagName(parameter.From) {
+			return fmt.Errorf("schema parameter %d from must be an exact parameter name", index)
+		}
+		if seenFrom[parameter.From] {
+			return fmt.Errorf("schema parameter %d duplicates from %q", index, parameter.From)
+		}
+		seenFrom[parameter.From] = true
+		if kind == CommandMigrationMove {
+			if parameter.ReplacementConstant != nil {
+				return fmt.Errorf("command_move schema parameter %d must not declare replacement_constant", index)
+			}
+			if !isExactFlagName(parameter.To) || parameter.To == parameter.From {
+				return fmt.Errorf("command_move schema parameter %d requires a distinct exact to name", index)
+			}
+			if seenTo[parameter.To] {
+				return fmt.Errorf("schema parameter %d duplicates to %q", index, parameter.To)
+			}
+			seenTo[parameter.To] = true
+			continue
+		}
+		if kind != CommandMigrationFlagExtraction {
+			return fmt.Errorf("invalid command migration kind %q", kind)
+		}
+
+		hasTo := parameter.To != ""
+		hasConstant := parameter.ReplacementConstant != nil
+		if !hasTo && !hasConstant {
+			return fmt.Errorf("flag_extraction schema parameter %d requires an exact to or replacement_constant", index)
+		}
+		if hasTo && hasConstant {
+			return fmt.Errorf("flag_extraction schema parameter %d must declare exactly one target", index)
+		}
+		if hasTo {
+			if !isExactFlagName(parameter.To) {
+				return fmt.Errorf("flag_extraction schema parameter %d to must be an exact parameter name", index)
+			}
+			if seenTo[parameter.To] {
+				return fmt.Errorf("schema parameter %d duplicates to %q", index, parameter.To)
+			}
+			if seenConstantProperty[parameter.To] {
+				return fmt.Errorf("schema parameter %d duplicates parameter target %q", index, parameter.To)
+			}
+			seenTo[parameter.To] = true
+			continue
+		}
+		property := parameter.ReplacementConstant.Property
+		if !isExactSchemaIdentifier(property) {
+			return fmt.Errorf("flag_extraction schema parameter %d replacement_constant requires an exact property", index)
+		}
+		if seenConstantProperty[property] {
+			return fmt.Errorf("schema parameter %d duplicates replacement_constant property %q", index, property)
+		}
+		if seenTo[property] {
+			return fmt.Errorf("schema parameter %d duplicates parameter target %q", index, property)
+		}
+		seenConstantProperty[property] = true
+	}
+	return nil
+}
+
+func isExactSchemaIdentifier(value string) bool {
+	return value != "" && value == strings.TrimSpace(value) &&
+		!strings.ContainsAny(value, "*?[]{} /\\\t\r\n")
+}
+
+func (m CommandMigration) key() string {
+	return strings.Join([]string{m.Kind, m.Legacy.Command, m.Replacement.Command, m.Schema.ProductID, m.Schema.SourceToolID, m.Schema.ReplacementToolID}, "\x00")
+}
+
+func (m CommandMigration) displayKey() string {
+	return fmt.Sprintf("%s %q -> %q", m.Kind, m.Legacy.Command, m.Replacement.Command)
+}
+
+type commandMigrationPhase string
+
+const (
+	commandMigrationBefore  commandMigrationPhase = "before"
+	commandMigrationAfter   commandMigrationPhase = "after"
+	commandMigrationPartial commandMigrationPhase = "partial"
+)
+
+func AuthorizeCommandMigrations(
+	current Snapshot,
+	references map[string]Snapshot,
+	authority CommandMigrationManifest,
+	candidate CommandMigrationManifest,
+) ([]CommandMigration, error) {
+	if err := current.Validate(); err != nil {
+		return nil, fmt.Errorf("validate current interface snapshot: %w", err)
+	}
+	for label, snapshot := range references {
+		if err := snapshot.Validate(); err != nil {
+			return nil, fmt.Errorf("validate %s interface snapshot: %w", label, err)
+		}
+	}
+	if err := authority.Validate(); err != nil {
+		return nil, fmt.Errorf("validate approved command migrations: %w", err)
+	}
+	if err := candidate.Validate(); err != nil {
+		return nil, fmt.Errorf("validate candidate command migrations: %w", err)
+	}
+	type commandMoveTopologyCheck struct {
+		label    string
+		snapshot Snapshot
+		manifest CommandMigrationManifest
+	}
+	topologyChecks := []commandMoveTopologyCheck{
+		{label: "approved", snapshot: current, manifest: authority},
+		{label: "candidate", snapshot: current, manifest: candidate},
+	}
+	if mergeBase, _, ok := flagMigrationAuthoritySnapshot(references); ok {
+		topologyChecks = append(topologyChecks,
+			commandMoveTopologyCheck{label: "approved base", snapshot: mergeBase, manifest: authority},
+			commandMoveTopologyCheck{label: "candidate base", snapshot: mergeBase, manifest: candidate},
+		)
+	}
+	for _, check := range topologyChecks {
+		if err := validateCommandMoveLegacyLeaves(check.snapshot, check.manifest); err != nil {
+			return nil, fmt.Errorf("validate %s command migration topology: %w", check.label, err)
+		}
+	}
+	return evaluateCommandMigrationLifecycle(current, references, authority, candidate)
+}
+
+func validateCommandMoveLegacyLeaves(snapshot Snapshot, manifest CommandMigrationManifest) error {
+	commands := commandIndex(snapshot)
+	for _, migration := range manifest.Migrations {
+		if migration.Kind != CommandMigrationMove {
+			continue
+		}
+		if _, present := commands[migration.Legacy.Command]; !present {
+			continue
+		}
+		for _, command := range snapshot.Commands {
+			if strings.HasPrefix(command.Path, migration.Legacy.Command+" ") {
+				return fmt.Errorf("command_move legacy command %q must be a leaf", migration.Legacy.Command)
+			}
+		}
+	}
+	return nil
+}
+
+func evaluateCommandMigrationLifecycle(
+	current Snapshot,
+	references map[string]Snapshot,
+	authority CommandMigrationManifest,
+	candidate CommandMigrationManifest,
+) ([]CommandMigration, error) {
+	if len(authority.Migrations) == 0 && len(candidate.Migrations) == 0 {
+		return nil, nil
+	}
+	if _, ok := references["stable"]; !ok {
+		return nil, fmt.Errorf("command migration lifecycle requires a stable reference")
+	}
+	mergeBase, label, ok := flagMigrationAuthoritySnapshot(references)
+	if !ok {
+		return nil, fmt.Errorf("command migration lifecycle requires a main or merge-base reference")
+	}
+	authorityByKey := commandMigrationIndex(authority)
+	candidateByKey := commandMigrationIndex(candidate)
+	authorizations := make([]CommandMigration, 0, len(authority.Migrations))
+	for _, approved := range authority.Migrations {
+		basePhase := matchCommandMigrationPhase(mergeBase, approved)
+		wantBase := commandMigrationBefore
+		if approved.State == CommandMigrationConsumed {
+			wantBase = commandMigrationAfter
+		}
+		if basePhase != wantBase {
+			return nil, fmt.Errorf("approved command migration %s is %s in %s, want exact %s state for %s", approved.displayKey(), basePhase, label, wantBase, approved.State)
+		}
+		proposed, exists := candidateByKey[approved.key()]
+		if exists && !sameCommandMigrationApproval(approved, proposed) {
+			return nil, fmt.Errorf("candidate modified base-owned command migration %s", approved.displayKey())
+		}
+		currentPhase := matchCommandMigrationPhase(current, approved)
+		switch approved.State {
+		case CommandMigrationPending:
+			if !exists {
+				return nil, fmt.Errorf("candidate removed pending command migration %s", approved.displayKey())
+			}
+			switch currentPhase {
+			case commandMigrationBefore:
+				if proposed.State != CommandMigrationPending {
+					return nil, fmt.Errorf("candidate falsely consumed unchanged command migration %s", approved.displayKey())
+				}
+			case commandMigrationAfter:
+				if proposed.State != CommandMigrationConsumed {
+					return nil, fmt.Errorf("candidate completed command migration %s without marking it consumed", approved.displayKey())
+				}
+				authorizations = append(authorizations, approved)
+			default:
+				return nil, fmt.Errorf("candidate partially applied command migration %s", approved.displayKey())
+			}
+		case CommandMigrationConsumed:
+			if currentPhase != commandMigrationAfter {
+				return nil, fmt.Errorf("candidate drifted from consumed command migration %s", approved.displayKey())
+			}
+			allAfter := true
+			for _, reference := range references {
+				if matchCommandMigrationPhase(reference, approved) != commandMigrationAfter {
+					allAfter = false
+					break
+				}
+			}
+			if allAfter {
+				if exists {
+					return nil, fmt.Errorf("consumed command migration %s is stale after all references reached the after state", approved.displayKey())
+				}
+				continue
+			}
+			if !exists || proposed.State != CommandMigrationConsumed {
+				return nil, fmt.Errorf("candidate must retain consumed command migration %s until every reference reaches the after state", approved.displayKey())
+			}
+			authorizations = append(authorizations, approved)
+		}
+	}
+	for _, proposed := range candidate.Migrations {
+		if _, exists := authorityByKey[proposed.key()]; exists {
+			continue
+		}
+		if proposed.State != CommandMigrationPending {
+			return nil, fmt.Errorf("candidate-added command migration %s must start pending", proposed.displayKey())
+		}
+		if matchCommandMigrationPhase(mergeBase, proposed) != commandMigrationBefore {
+			return nil, fmt.Errorf("candidate-added command migration %s does not match the merge-base before state", proposed.displayKey())
+		}
+		if matchCommandMigrationPhase(current, proposed) != commandMigrationBefore {
+			return nil, fmt.Errorf("candidate-added command migration %s cannot authorize its own interface change", proposed.displayKey())
+		}
+	}
+	return authorizations, nil
+}
+
+func commandMigrationIndex(manifest CommandMigrationManifest) map[string]CommandMigration {
+	index := make(map[string]CommandMigration, len(manifest.Migrations))
+	for _, migration := range manifest.Migrations {
+		index[migration.key()] = migration
+	}
+	return index
+}
+
+func sameCommandMigrationApproval(left, right CommandMigration) bool {
+	left.State = ""
+	right.State = ""
+	return reflect.DeepEqual(left, right)
+}
+
+func matchCommandMigrationPhase(snapshot Snapshot, migration CommandMigration) commandMigrationPhase {
+	commands := commandIndex(snapshot)
+	legacy := commandMigrationStateForCommand(commands, migration.Legacy.Command)
+	replacement := commandMigrationStateForCommand(commands, migration.Replacement.Command)
+	before := legacy == migration.Legacy.Before && replacement == migration.Replacement.Before
+	after := legacy == migration.Legacy.After && replacement == migration.Replacement.After
+	if migration.Kind == CommandMigrationFlagExtraction {
+		command, exists := commands[migration.Legacy.Command]
+		flagState := FlagMigrationState{}
+		if exists {
+			flagState = flagMigrationStateForCommand(command, migration.LegacyFlag.Name)
+		}
+		before = before && flagState == migration.LegacyFlag.Before
+		after = after && flagState == migration.LegacyFlag.After
+		if replacement, replacementExists := commands[migration.Replacement.Command]; replacementExists {
+			after = after && commandMigrationReplacementConstantsMatch(replacement, migration)
+		} else {
+			after = false
+		}
+	}
+	if before {
+		return commandMigrationBefore
+	}
+	if after {
+		return commandMigrationAfter
+	}
+	return commandMigrationPartial
+}
+
+func commandMigrationReplacementConstantsMatch(command Command, migration CommandMigration) bool {
+	expected := make(map[string]bool)
+	for _, parameter := range migration.Schema.Parameters {
+		if parameter.ReplacementConstant == nil {
+			continue
+		}
+		expected[parameter.ReplacementConstant.Property] = parameter.ReplacementConstant.Value
+	}
+	return reflect.DeepEqual(command.BoolConstParams, expected)
+}
+
+func commandMigrationStateForCommand(commands map[string]Command, path string) CommandMigrationState {
+	command, exists := commands[path]
+	if !exists {
+		return CommandMigrationState{}
+	}
+	return CommandMigrationState{Present: true, Runnable: command.Runnable, Hidden: command.Hidden}
+}
+
+// CompareAllWithInterfaceMigrations applies both migration families to one
+// ordinary report, so the two ledgers cannot mask each other's unrelated
+// findings.
+func CompareAllWithInterfaceMigrations(
+	current Snapshot,
+	references map[string]Snapshot,
+	flagAuthority FlagMigrationManifest,
+	flagCandidate FlagMigrationManifest,
+	commandAuthority CommandMigrationManifest,
+	commandCandidate CommandMigrationManifest,
+) (Report, error) {
+	flagAuthorizations, err := AuthorizeFlagMigrations(current, references, flagAuthority, flagCandidate)
+	if err != nil {
+		return Report{}, err
+	}
+	commandAuthorizations, err := AuthorizeCommandMigrations(current, references, commandAuthority, commandCandidate)
+	if err != nil {
+		return Report{}, err
+	}
+	report := CompareAll(current, references)
+	for index := range report.Comparisons {
+		comparison := &report.Comparisons[index]
+		reference := references[comparison.Reference]
+		filtered := comparison.Blocking[:0]
+		for _, change := range comparison.Blocking {
+			if flagMigrationAuthorizesChange(current, reference, change, flagAuthorizations) ||
+				commandMigrationAuthorizesChange(current, reference, change, commandAuthorizations) {
+				continue
+			}
+			filtered = append(filtered, change)
+		}
+		comparison.Blocking = filtered
+		comparison.Compatible = len(filtered) == 0
+	}
+	report.Compatible = true
+	for _, comparison := range report.Comparisons {
+		if !comparison.Compatible {
+			report.Compatible = false
+			break
+		}
+	}
+	return report, nil
+}
+
+func commandMigrationAuthorizesChange(current, reference Snapshot, change Change, authorizations []CommandMigration) bool {
+	canonicalPath := acceptedPathIndex(reference)[change.Path]
+	if canonicalPath == "" {
+		canonicalPath = change.Path
+	}
+	for _, migration := range authorizations {
+		if canonicalPath != migration.Legacy.Command ||
+			matchCommandMigrationPhase(reference, migration) != commandMigrationBefore ||
+			matchCommandMigrationPhase(current, migration) != commandMigrationAfter {
+			continue
+		}
+		switch migration.Kind {
+		case CommandMigrationMove:
+			if change.Kind == "command_became_hidden" && change.Flag == "" {
+				return true
+			}
+		case CommandMigrationFlagExtraction:
+			if change.Kind == "flag_became_hidden" && change.Flag == migration.LegacyFlag.Name {
+				return true
+			}
+		}
+	}
+	return false
+}

internal/interfacesnapshot/command_migrations_test.go

@@ -0,0 +1,744 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0 (the "License");
+
+package interfacesnapshot
+
+import (
+	"errors"
+	"os"
+	"strings"
+	"testing"
+)
+
+type commandMigrationErrorReader struct{}
+
+func (commandMigrationErrorReader) Read([]byte) (int, error) {
+	return 0, errors.New("command migration read failure")
+}
+
+func TestApprovedCommandMigrationManifestRemainsValid(t *testing.T) {
+	manifest, err := os.Open("../../scripts/policy/interface-migrations/approved-command-migrations-v1.json")
+	if err != nil {
+		t.Fatalf("open approved command migration manifest: %v", err)
+	}
+	defer manifest.Close()
+	if _, err := ReadCommandMigrationManifest(manifest); err != nil {
+		t.Fatalf("approved command migration manifest is invalid: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageReadCommandMigrationManifestFailsClosed(t *testing.T) {
+	valid := commandMigrationManifestJSON()
+	if _, err := ReadCommandMigrationManifest(strings.NewReader(valid)); err != nil {
+		t.Fatalf("valid command migration manifest: %v", err)
+	}
+	validExtraction := flagExtractionCommandMigrationManifestJSON()
+	if _, err := ReadCommandMigrationManifest(strings.NewReader(validExtraction)); err != nil {
+		t.Fatalf("valid flag extraction command migration manifest: %v", err)
+	}
+	for _, test := range []struct {
+		input string
+		want  string
+	}{
+		{strings.Replace(valid, `"state": "pending"`, `"state": "pending", "allow": true`, 1), "unknown field"},
+		{strings.Replace(valid, `"state": "pending"`, `"state": "pending", "state": "consumed"`, 1), "duplicate field"},
+		{strings.Replace(valid, `"version": 1`, `"version": null`, 1), "must be"},
+		{strings.Replace(valid, "dws chat message old", "dws chat *", 1), "exact command paths"},
+		{strings.Replace(valid, `"kind": "command_move"`, `"kind": "anything"`, 1), "invalid kind"},
+		{`{"version":1,"migrations":null}`, "must be an array"},
+		{strings.Replace(validExtraction, `"replacement_constant":{"property":"convThreadEnabled","value":true}`, `"replacement_constant":null`, 1), "must be an object"},
+		{strings.Replace(validExtraction, `,"value":true`, ``, 1), `must be true`},
+		{strings.Replace(validExtraction, `"value":true`, `"value":"true"`, 1), "bool"},
+	} {
+		if _, err := ReadCommandMigrationManifest(strings.NewReader(test.input)); err == nil || !strings.Contains(err.Error(), test.want) {
+			t.Fatalf("ReadCommandMigrationManifest() error=%v, want %q", err, test.want)
+		}
+	}
+	if _, err := ReadCommandMigrationManifest(commandMigrationErrorReader{}); err == nil || !strings.Contains(err.Error(), "read failure") {
+		t.Fatalf("reader error=%v", err)
+	}
+	for _, input := range []string{valid + ` {}`, valid + ` {`} {
+		if _, err := ReadCommandMigrationManifest(strings.NewReader(input)); err == nil || !strings.Contains(err.Error(), "trailing") {
+			t.Fatalf("trailing input error=%v", err)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageCommandMigrationValidationEdges(t *testing.T) {
+	validMove := commandMigrationManifest(CommandMigrationPending).Migrations[0]
+	validExtraction := commandMigrationManifest(CommandMigrationPending).Migrations[1]
+
+	duplicate := CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{validMove, validMove}}
+	if err := duplicate.Validate(); err == nil || !strings.Contains(err.Error(), "duplicates") {
+		t.Fatalf("duplicate error=%v", err)
+	}
+	if err := (CommandMigrationManifest{Version: CommandMigrationManifestVersion}).Validate(); err == nil || !strings.Contains(err.Error(), "must be an array") {
+		t.Fatalf("nil migrations error=%v", err)
+	}
+
+	for _, test := range []struct {
+		name   string
+		mutate func(*CommandMigration)
+		want   string
+	}{
+		{"same command", func(m *CommandMigration) { m.Replacement.Command = m.Legacy.Command }, "must differ"},
+		{"empty reason", func(m *CommandMigration) { m.Reason = " " }, "non-empty trimmed"},
+		{"invalid state", func(m *CommandMigration) { m.State = "approved" }, "invalid state"},
+		{"invalid command state", func(m *CommandMigration) { m.Replacement.Before.Runnable = true }, "absent state"},
+		{"legacy contract", func(m *CommandMigration) { m.Legacy.Before.Hidden = true }, "remain runnable"},
+		{"replacement contract", func(m *CommandMigration) { m.Replacement.After.Hidden = true }, "absent to visible"},
+		{"schema contract", func(m *CommandMigration) { m.Schema.ProductID = "bad/id" }, "exact identifier"},
+		{"move not hidden", func(m *CommandMigration) { m.Legacy.After.Hidden = false }, "must migrate exactly"},
+		{"move flag", func(m *CommandMigration) { m.LegacyFlag.Name = "thread" }, "must not declare legacy_flag"},
+		{"move tool identity", func(m *CommandMigration) { m.Schema.ReplacementToolID = "chat.new" }, "stable Schema tool"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			migration := validMove
+			test.mutate(&migration)
+			if err := migration.validate(); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("validate error=%v, want %q", err, test.want)
+			}
+		})
+	}
+	for _, test := range []struct {
+		name   string
+		mutate func(*CommandMigration)
+		want   string
+	}{
+		{"legacy changed", func(m *CommandMigration) { m.Legacy.After.Hidden = true }, "remain visible"},
+		{"invalid legacy flag", func(m *CommandMigration) { m.LegacyFlag.Name = "bad name" }, "exact flag"},
+		{"same tool", func(m *CommandMigration) { m.Schema.ReplacementToolID = m.Schema.SourceToolID }, "distinct replacement"},
+		{"wrong parameter", func(m *CommandMigration) { m.Schema.Parameters[3].From = "other" }, "exact extracted flag"},
+		{"wrong type", func(m *CommandMigration) {
+			m.LegacyFlag.Before.Type = "string"
+			m.LegacyFlag.After.Type = "string"
+		}, "optional bool"},
+		{"wrong no opt", func(m *CommandMigration) {
+			m.LegacyFlag.Before.NoOpt = "false"
+			m.LegacyFlag.After.NoOpt = "false"
+		}, "no_opt"},
+		{"missing extracted mapping", func(m *CommandMigration) {
+			m.Schema.Parameters = m.Schema.Parameters[:3]
+		}, "exactly one replacement constant"},
+		{"duplicate extracted mapping", func(m *CommandMigration) {
+			m.Schema.Parameters = append(m.Schema.Parameters, m.Schema.Parameters[3])
+		}, "duplicates from"},
+		{"multiple constants", func(m *CommandMigration) {
+			m.Schema.Parameters[0] = CommandParameterMigration{
+				From: "name",
+				ReplacementConstant: &CommandReplacementConstant{
+					Property: "name",
+					Value:    true,
+				},
+			}
+		}, "exactly one replacement constant"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			migration := cloneCommandMigration(validExtraction)
+			test.mutate(&migration)
+			if err := migration.validate(); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("validate error=%v, want %q", err, test.want)
+			}
+		})
+	}
+	falseConstant := cloneCommandMigration(validExtraction)
+	falseConstant.Schema.Parameters[3].ReplacementConstant.Value = false
+	falseConstant.LegacyFlag.Before.NoOpt = "false"
+	falseConstant.LegacyFlag.After.NoOpt = "false"
+	if err := falseConstant.validate(); err == nil || !strings.Contains(err.Error(), "must be true") {
+		t.Fatalf("false replacement constant validation error=%v, want v1 true-only rejection", err)
+	}
+
+	for _, state := range []CommandMigrationState{
+		{Runnable: true},
+		{Present: true},
+	} {
+		if err := state.validate("state"); err == nil {
+			t.Fatalf("invalid command state accepted: %#v", state)
+		}
+	}
+
+	for _, test := range []struct {
+		name   string
+		mutate func(*CommandMigrationFlag)
+		want   string
+	}{
+		{"name", func(f *CommandMigrationFlag) { f.Name = "bad name" }, "exact flag"},
+		{"before state", func(f *CommandMigrationFlag) { f.Before = FlagMigrationState{Present: true} }, "requires type"},
+		{"after state", func(f *CommandMigrationFlag) { f.After = FlagMigrationState{Present: true} }, "requires type"},
+		{"visibility", func(f *CommandMigrationFlag) { f.After.Hidden = false }, "visible to hidden"},
+		{"attribute", func(f *CommandMigrationFlag) { f.After.Type = "string" }, "only hidden visibility"},
+	} {
+		t.Run("flag "+test.name, func(t *testing.T) {
+			flag := validExtraction.LegacyFlag
+			test.mutate(&flag)
+			if err := flag.validate(); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("flag validate error=%v, want %q", err, test.want)
+			}
+		})
+	}
+
+	validSchema := validMove.Schema
+	for _, test := range []struct {
+		name   string
+		kind   string
+		mutate func(*CommandMigrationSchema)
+		want   string
+	}{
+		{"identifier", CommandMigrationMove, func(s *CommandMigrationSchema) { s.ProductID = "bad/id" }, "exact identifier"},
+		{"nil parameters", CommandMigrationMove, func(s *CommandMigrationSchema) { s.Parameters = nil }, "must be an array"},
+		{"bad from", CommandMigrationMove, func(s *CommandMigrationSchema) { s.Parameters[0].From = "bad name" }, "exact parameter"},
+		{"duplicate from", CommandMigrationMove, func(s *CommandMigrationSchema) { s.Parameters = append(s.Parameters, s.Parameters[0]) }, "duplicates from"},
+		{"bad to", CommandMigrationMove, func(s *CommandMigrationSchema) { s.Parameters[0].To = s.Parameters[0].From }, "distinct exact"},
+		{"duplicate to", CommandMigrationMove, func(s *CommandMigrationSchema) {
+			s.Parameters = append(s.Parameters, CommandParameterMigration{From: "other", To: s.Parameters[0].To})
+		}, "duplicates to"},
+		{"move constant", CommandMigrationMove, func(s *CommandMigrationSchema) {
+			s.Parameters[0].ReplacementConstant = &CommandReplacementConstant{Property: "property", Value: true}
+		}, "must not declare replacement_constant"},
+		{"invalid kind", "anything", func(*CommandMigrationSchema) {}, "invalid command migration kind"},
+	} {
+		t.Run("schema "+test.name, func(t *testing.T) {
+			schema := validSchema
+			schema.Parameters = append([]CommandParameterMigration(nil), validSchema.Parameters...)
+			test.mutate(&schema)
+			if err := schema.validate(test.kind); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("schema validate error=%v, want %q", err, test.want)
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name   string
+		mutate func(*CommandMigrationSchema)
+		want   string
+	}{
+		{"missing target", func(s *CommandMigrationSchema) { s.Parameters[0].To = "" }, "requires an exact to or replacement_constant"},
+		{"both targets", func(s *CommandMigrationSchema) {
+			s.Parameters[0].ReplacementConstant = &CommandReplacementConstant{Property: "name", Value: true}
+		}, "exactly one target"},
+		{"bad to", func(s *CommandMigrationSchema) { s.Parameters[0].To = "bad name" }, "to must be an exact parameter name"},
+		{"bad constant property", func(s *CommandMigrationSchema) { s.Parameters[3].ReplacementConstant.Property = "bad/property" }, "exact property"},
+		{"duplicate parameter target", func(s *CommandMigrationSchema) { s.Parameters[1].To = s.Parameters[0].To }, "duplicates to"},
+		{"duplicate constant target", func(s *CommandMigrationSchema) {
+			s.Parameters[0] = CommandParameterMigration{From: "name", ReplacementConstant: &CommandReplacementConstant{Property: "convThreadEnabled", Value: true}}
+		}, "duplicates replacement_constant property"},
+		{"constant before parameter target", func(s *CommandMigrationSchema) {
+			s.Parameters[3].ReplacementConstant.Property = "name"
+			s.Parameters[0], s.Parameters[3] = s.Parameters[3], s.Parameters[0]
+		}, "duplicates parameter target"},
+		{"parameter target before constant", func(s *CommandMigrationSchema) {
+			s.Parameters[3].ReplacementConstant.Property = "name"
+		}, "duplicates parameter target"},
+	} {
+		t.Run("extraction schema "+test.name, func(t *testing.T) {
+			schema := cloneCommandMigration(validExtraction).Schema
+			test.mutate(&schema)
+			if err := schema.validate(CommandMigrationFlagExtraction); err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("schema validate error=%v, want %q", err, test.want)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageFlagExtractionRejectsRequiredLegacyFlag(t *testing.T) {
+	for _, test := range []struct {
+		name   string
+		mutate func(*CommandMigrationFlag)
+	}{
+		{"before required", func(flag *CommandMigrationFlag) { flag.Before.Required = true }},
+		{"after required", func(flag *CommandMigrationFlag) { flag.After.Required = true }},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			migration := commandMigrationManifest(CommandMigrationPending).Migrations[1]
+			test.mutate(&migration.LegacyFlag)
+
+			if err := migration.validate(); err == nil || !strings.Contains(err.Error(), "optional") {
+				t.Fatalf("required legacy flag validation error=%v, want optional-only rejection", err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageCommandMoveRejectsRunnableParent(t *testing.T) {
+	migration := commandMigrationManifest(CommandMigrationPending).Migrations[0]
+	migration.Legacy.Command = "dws agoal"
+	migration.Replacement.Command = "dws goal"
+	migration.Schema = CommandMigrationSchema{
+		ProductID:         "agoal",
+		SourceToolID:      "agoal.root",
+		ReplacementToolID: "agoal.root",
+		Parameters:        []CommandParameterMigration{},
+	}
+	authority := CommandMigrationManifest{
+		Version:    CommandMigrationManifestVersion,
+		Migrations: []CommandMigration{migration},
+	}
+	consumed := authority
+	consumed.Migrations = append([]CommandMigration(nil), authority.Migrations...)
+	consumed.Migrations[0].State = CommandMigrationConsumed
+
+	before := testSnapshot(
+		testCommand("dws"),
+		testCommand("dws agoal"),
+		testCommand("dws agoal strategy"),
+		testCommand("dws agoal strategy list"),
+	)
+	after := testSnapshot(
+		testCommand("dws"),
+		Command{Path: "dws agoal", Runnable: true, Hidden: true},
+		testCommand("dws goal"),
+	)
+
+	_, err := AuthorizeCommandMigrations(
+		after,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		authority,
+		consumed,
+	)
+	if err == nil || !strings.Contains(err.Error(), "must be a leaf") {
+		t.Fatalf("runnable parent command_move error=%v, want leaf-only rejection", err)
+	}
+}
+
+func TestCrossPlatformCoverageCommandMoveAllowsReplacementParent(t *testing.T) {
+	before := commandMigrationSnapshot(false, false)
+	after := commandMigrationSnapshot(true, false)
+	after.Commands = append(after.Commands, testCommand("dws chat topic new detail"))
+	pending := singleCommandMigrationManifest(CommandMigrationPending)
+	consumed := singleCommandMigrationManifest(CommandMigrationConsumed)
+	if err := validateCommandMoveLegacyLeaves(testSnapshot(testCommand("dws")), pending); err != nil {
+		t.Fatalf("absent legacy topology should remain a lifecycle concern: %v", err)
+	}
+
+	got, err := AuthorizeCommandMigrations(
+		after,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		pending,
+		consumed,
+	)
+	if err != nil {
+		t.Fatalf("replacement parent command_move was rejected: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("replacement parent command_move authorizations=%d, want 1", len(got))
+	}
+}
+
+func TestCrossPlatformCoverageCommandMoveRejectsAncestorOverlap(t *testing.T) {
+	for _, test := range []struct {
+		name        string
+		legacy      string
+		replacement string
+	}{
+		{
+			name:        "legacy ancestor",
+			legacy:      "dws chat message",
+			replacement: "dws chat message list",
+		},
+		{
+			name:        "replacement ancestor",
+			legacy:      "dws chat message list",
+			replacement: "dws chat message",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			migration := commandMigrationManifest(CommandMigrationPending).Migrations[0]
+			migration.Legacy.Command = test.legacy
+			migration.Replacement.Command = test.replacement
+
+			if err := migration.validate(); err == nil || !strings.Contains(err.Error(), "must not have an ancestor relationship") {
+				t.Fatalf("overlapping command_move error=%v, want ancestor-overlap rejection", err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageCommandMigrationLifecycleEdges(t *testing.T) {
+	before := commandMigrationSnapshot(false, false)
+	after := commandMigrationSnapshot(true, false)
+	partial := commandMigrationSnapshot(false, false)
+	partial.Commands = append(partial.Commands, testCommand("dws chat topic new"))
+	pending := singleCommandMigrationManifest(CommandMigrationPending)
+	consumed := singleCommandMigrationManifest(CommandMigrationConsumed)
+	empty := CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{}}
+
+	if got, err := AuthorizeCommandMigrations(before, map[string]Snapshot{}, empty, empty); err != nil || len(got) != 0 {
+		t.Fatalf("empty lifecycle=%#v, %v", got, err)
+	}
+	for _, test := range []struct {
+		name       string
+		current    Snapshot
+		references map[string]Snapshot
+		authority  CommandMigrationManifest
+		candidate  CommandMigrationManifest
+		want       string
+	}{
+		{"missing stable", before, map[string]Snapshot{"main": before}, pending, pending, "stable reference"},
+		{"missing base", before, map[string]Snapshot{"stable": before}, pending, pending, "main or merge-base"},
+		{"pending base after", after, map[string]Snapshot{"main": after, "stable": before}, pending, pending, "want exact before"},
+		{"modified approval", before, map[string]Snapshot{"main": before, "stable": before}, pending, modifiedCommandManifest(pending), "modified base-owned"},
+		{"pending removed", before, map[string]Snapshot{"main": before, "stable": before}, pending, empty, "removed pending"},
+		{"false consumed", before, map[string]Snapshot{"main": before, "stable": before}, pending, consumed, "falsely consumed"},
+		{"after pending receipt", after, map[string]Snapshot{"main": before, "stable": before}, pending, pending, "without marking it consumed"},
+		{"partial", partial, map[string]Snapshot{"main": before, "stable": before}, pending, consumed, "partially applied"},
+		{"consumed drift", before, map[string]Snapshot{"main": after, "stable": before}, consumed, consumed, "drifted from consumed"},
+		{"stale receipt", after, map[string]Snapshot{"main": after, "stable": after}, consumed, consumed, "stale after all references"},
+		{"early cleanup", after, map[string]Snapshot{"main": after, "stable": before}, consumed, empty, "must retain consumed"},
+		{"consumed back to pending", after, map[string]Snapshot{"main": after, "stable": before}, consumed, pending, "must retain consumed"},
+		{"candidate added consumed", after, map[string]Snapshot{"main": before, "stable": before}, empty, consumed, "must start pending"},
+		{"candidate base mismatch", before, map[string]Snapshot{"main": after, "stable": before}, empty, pending, "does not match"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := AuthorizeCommandMigrations(test.current, test.references, test.authority, test.candidate)
+			if err == nil || !strings.Contains(err.Error(), test.want) {
+				t.Fatalf("lifecycle error=%v, want %q", err, test.want)
+			}
+		})
+	}
+	if got, err := AuthorizeCommandMigrations(after, map[string]Snapshot{"main": after, "stable": before}, consumed, consumed); err != nil || len(got) != 1 {
+		t.Fatalf("retained consumed receipt=%#v, %v", got, err)
+	}
+	if got, err := AuthorizeCommandMigrations(after, map[string]Snapshot{"main": after, "stable": after}, consumed, empty); err != nil || len(got) != 0 {
+		t.Fatalf("cleaned stale receipt=%#v, %v", got, err)
+	}
+	if got, err := AuthorizeCommandMigrations(before, map[string]Snapshot{"main": before, "stable": before}, empty, pending); err != nil || len(got) != 0 {
+		t.Fatalf("candidate pending plan=%#v, %v", got, err)
+	}
+
+	invalidSnapshot := before
+	invalidSnapshot.SchemaVersion = 0
+	for _, test := range []struct {
+		name       string
+		current    Snapshot
+		references map[string]Snapshot
+		authority  CommandMigrationManifest
+		candidate  CommandMigrationManifest
+	}{
+		{"current", invalidSnapshot, map[string]Snapshot{"main": before}, empty, empty},
+		{"reference", before, map[string]Snapshot{"main": invalidSnapshot}, empty, empty},
+		{"authority", before, map[string]Snapshot{"main": before}, CommandMigrationManifest{}, empty},
+		{"candidate", before, map[string]Snapshot{"main": before}, empty, CommandMigrationManifest{}},
+	} {
+		t.Run("invalid "+test.name, func(t *testing.T) {
+			if _, err := AuthorizeCommandMigrations(test.current, test.references, test.authority, test.candidate); err == nil {
+				t.Fatal("invalid authorization input accepted")
+			}
+		})
+	}
+	invalidFlags := FlagMigrationManifest{}
+	validFlags := FlagMigrationManifest{Version: FlagMigrationManifestVersion, Migrations: []FlagMigration{}}
+	validCommands := CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{}}
+	if _, err := CompareAllWithInterfaceMigrations(before, map[string]Snapshot{"main": before}, invalidFlags, validFlags, validCommands, validCommands); err == nil {
+		t.Fatal("combined compare accepted invalid flag lifecycle")
+	}
+	if _, err := CompareAllWithInterfaceMigrations(before, map[string]Snapshot{"main": before}, validFlags, validFlags, CommandMigrationManifest{}, validCommands); err == nil {
+		t.Fatal("combined compare accepted invalid command lifecycle")
+	}
+	if commandMigrationAuthorizesChange(before, before, Change{Kind: "command_removed", Path: "dws unrelated"}, pending.Migrations) {
+		t.Fatal("unrelated command change was authorized")
+	}
+}
+
+func TestCrossPlatformCoverageCommandMigrationLifecycleAndExactFiltering(t *testing.T) {
+	before := commandMigrationSnapshot(false, false)
+	after := commandMigrationSnapshot(true, false)
+	pending := commandMigrationManifest(CommandMigrationPending)
+	consumed := commandMigrationManifest(CommandMigrationConsumed)
+	emptyFlags := FlagMigrationManifest{Version: FlagMigrationManifestVersion, Migrations: []FlagMigration{}}
+
+	report, err := CompareAllWithInterfaceMigrations(
+		after,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		emptyFlags,
+		emptyFlags,
+		pending,
+		consumed,
+	)
+	if err != nil {
+		t.Fatalf("governed command migration: %v", err)
+	}
+	if !report.Compatible {
+		t.Fatalf("exact command migration remained blocking: %#v", report.Comparisons)
+	}
+
+	unrelated := commandMigrationSnapshot(true, true)
+	report, err = CompareAllWithInterfaceMigrations(
+		unrelated,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		emptyFlags,
+		emptyFlags,
+		pending,
+		consumed,
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.Compatible || !hasChangeKind(report.Comparisons[0].Blocking, "flag_removed") {
+		t.Fatalf("unrelated flag removal was hidden: %#v", report.Comparisons)
+	}
+
+	emptyCommands := CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{}}
+	if _, err := AuthorizeCommandMigrations(
+		after,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		emptyCommands,
+		pending,
+	); err == nil || !strings.Contains(err.Error(), "cannot authorize its own interface change") {
+		t.Fatalf("candidate self-authorization error=%v", err)
+	}
+
+	partial := commandMigrationSnapshot(true, false)
+	partial.Commands = partial.Commands[:len(partial.Commands)-1]
+	if _, err := AuthorizeCommandMigrations(
+		partial,
+		map[string]Snapshot{"merge-base": before, "stable": before},
+		pending,
+		consumed,
+	); err == nil || !strings.Contains(err.Error(), "partially applied") {
+		t.Fatalf("partial command migration error=%v", err)
+	}
+}
+
+func TestCrossPlatformCoverageFlagExtractionRequiresReplacementConstantEvidence(t *testing.T) {
+	before := commandMigrationSnapshot(false, false)
+	after := commandMigrationSnapshot(true, false)
+	pending := flagExtractionCommandMigrationManifest(CommandMigrationPending)
+	consumed := flagExtractionCommandMigrationManifest(CommandMigrationConsumed)
+	empty := CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{}}
+	migration := pending.Migrations[0]
+
+	if phase := matchCommandMigrationPhase(before, migration); phase != commandMigrationBefore {
+		t.Fatalf("before phase=%s, want %s", phase, commandMigrationBefore)
+	}
+	if phase := matchCommandMigrationPhase(after, migration); phase != commandMigrationAfter {
+		t.Fatalf("after phase=%s, want %s", phase, commandMigrationAfter)
+	}
+
+	for _, test := range []struct {
+		name   string
+		values map[string]bool
+	}{
+		{name: "missing", values: nil},
+		{name: "wrong property", values: map[string]bool{"otherProperty": true}},
+		{name: "wrong value", values: map[string]bool{"convThreadEnabled": false}},
+		{name: "extra", values: map[string]bool{"convThreadEnabled": true, "otherProperty": true}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			current := withCommandBoolConstParams(after, "dws chat topic create", test.values)
+			if phase := matchCommandMigrationPhase(current, migration); phase != commandMigrationPartial {
+				t.Fatalf("phase=%s, want %s", phase, commandMigrationPartial)
+			}
+			if _, err := AuthorizeCommandMigrations(
+				current,
+				map[string]Snapshot{"merge-base": before, "stable": before},
+				pending,
+				consumed,
+			); err == nil || !strings.Contains(err.Error(), "partially applied") {
+				t.Fatalf("constant evidence lifecycle error=%v, want partial rejection", err)
+			}
+			if _, err := AuthorizeCommandMigrations(
+				current,
+				map[string]Snapshot{"merge-base": before, "stable": before},
+				empty,
+				pending,
+			); err == nil || !strings.Contains(err.Error(), "cannot authorize its own interface change") {
+				t.Fatalf("constant evidence self-authorization error=%v", err)
+			}
+		})
+	}
+}
+
+func commandMigrationManifestJSON() string {
+	return `{
+  "version": 1,
+  "migrations": [{
+    "kind": "command_move",
+    "legacy": {
+      "command": "dws chat message old",
+      "before": {"present": true, "runnable": true},
+      "after": {"present": true, "runnable": true, "hidden": true}
+    },
+    "replacement": {
+      "command": "dws chat topic new",
+      "before": {"present": false},
+      "after": {"present": true, "runnable": true}
+    },
+    "schema": {
+      "product_id": "chat",
+      "source_tool_id": "chat.old",
+      "replacement_tool_id": "chat.old",
+      "parameters": [{"from": "old-id", "to": "new-id"}]
+    },
+    "state": "pending",
+    "reason": "Reviewed command move."
+  }]
+}`
+}
+
+func flagExtractionCommandMigrationManifestJSON() string {
+	return `{
+  "version": 1,
+  "migrations": [{
+    "kind": "flag_extraction",
+    "legacy": {
+      "command": "dws chat group create",
+      "before": {"present": true, "runnable": true},
+      "after": {"present": true, "runnable": true}
+    },
+    "replacement": {
+      "command": "dws chat topic create",
+      "before": {"present": false},
+      "after": {"present": true, "runnable": true}
+    },
+    "legacy_flag": {
+      "name": "thread",
+      "before": {"present": true, "type": "bool", "no_opt": "true", "scope": "local"},
+      "after": {"present": true, "type": "bool", "hidden": true, "no_opt": "true", "scope": "local"}
+    },
+    "schema": {
+      "product_id": "chat",
+      "source_tool_id": "chat.create_group",
+      "replacement_tool_id": "chat.create_topic",
+      "parameters": [
+        {"from":"name","to":"name"},
+        {"from":"type","to":"type"},
+        {"from":"users","to":"users"},
+        {"from":"thread","replacement_constant":{"property":"convThreadEnabled","value":true}}
+      ]
+    },
+    "state": "pending",
+    "reason": "Reviewed flag extraction."
+  }]
+}`
+}
+
+func commandMigrationManifest(state string) CommandMigrationManifest {
+	move := CommandMigration{
+		Kind: CommandMigrationMove,
+		Legacy: CommandMigrationSide{
+			Command: "dws chat message old",
+			Before:  CommandMigrationState{Present: true, Runnable: true},
+			After:   CommandMigrationState{Present: true, Runnable: true, Hidden: true},
+		},
+		Replacement: CommandMigrationSide{
+			Command: "dws chat topic new",
+			Before:  CommandMigrationState{},
+			After:   CommandMigrationState{Present: true, Runnable: true},
+		},
+		Schema: CommandMigrationSchema{
+			ProductID:         "chat",
+			SourceToolID:      "chat.old",
+			ReplacementToolID: "chat.old",
+			Parameters:        []CommandParameterMigration{{From: "old-id", To: "new-id"}},
+		},
+		State:  state,
+		Reason: "Reviewed command move.",
+	}
+	extraction := CommandMigration{
+		Kind: CommandMigrationFlagExtraction,
+		Legacy: CommandMigrationSide{
+			Command: "dws chat group create",
+			Before:  CommandMigrationState{Present: true, Runnable: true},
+			After:   CommandMigrationState{Present: true, Runnable: true},
+		},
+		Replacement: CommandMigrationSide{
+			Command: "dws chat topic create",
+			Before:  CommandMigrationState{},
+			After:   CommandMigrationState{Present: true, Runnable: true},
+		},
+		LegacyFlag: CommandMigrationFlag{
+			Name:   "thread",
+			Before: FlagMigrationState{Present: true, Type: "bool", NoOpt: "true", Scope: "local"},
+			After:  FlagMigrationState{Present: true, Type: "bool", Hidden: true, NoOpt: "true", Scope: "local"},
+		},
+		Schema: CommandMigrationSchema{
+			ProductID:         "chat",
+			SourceToolID:      "chat.create_group",
+			ReplacementToolID: "chat.create_topic",
+			Parameters: []CommandParameterMigration{
+				{From: "name", To: "name"},
+				{From: "type", To: "type"},
+				{From: "users", To: "users"},
+				{
+					From: "thread",
+					ReplacementConstant: &CommandReplacementConstant{
+						Property: "convThreadEnabled",
+						Value:    true,
+					},
+				},
+			},
+		},
+		State:  state,
+		Reason: "Reviewed flag extraction.",
+	}
+	return CommandMigrationManifest{Version: CommandMigrationManifestVersion, Migrations: []CommandMigration{move, extraction}}
+}
+
+func flagExtractionCommandMigrationManifest(state string) CommandMigrationManifest {
+	manifest := commandMigrationManifest(state)
+	manifest.Migrations = manifest.Migrations[1:]
+	return manifest
+}
+
+func cloneCommandMigration(source CommandMigration) CommandMigration {
+	cloned := source
+	cloned.Schema.Parameters = append([]CommandParameterMigration(nil), source.Schema.Parameters...)
+	for index, parameter := range source.Schema.Parameters {
+		if parameter.ReplacementConstant == nil {
+			continue
+		}
+		constant := *parameter.ReplacementConstant
+		cloned.Schema.Parameters[index].ReplacementConstant = &constant
+	}
+	return cloned
+}
+
+func singleCommandMigrationManifest(state string) CommandMigrationManifest {
+	manifest := commandMigrationManifest(state)
+	manifest.Migrations = manifest.Migrations[:1]
+	return manifest
+}
+
+func modifiedCommandManifest(source CommandMigrationManifest) CommandMigrationManifest {
+	modified := source
+	modified.Migrations = append([]CommandMigration(nil), source.Migrations...)
+	modified.Migrations[0].Reason = "Modified reason."
+	return modified
+}
+
+func commandMigrationSnapshot(after, removeUnrelated bool) Snapshot {
+	oldFlags := []Flag{{Name: "old-id", Type: "string", Required: true}, {Name: "keep", Type: "string"}}
+	groupFlags := []Flag{{Name: "thread", Type: "bool", NoOpt: "true"}}
+	commands := []Command{
+		testCommand("dws"),
+		testCommand("dws chat group create", groupFlags...),
+		testCommand("dws chat message old", oldFlags...),
+	}
+	if after {
+		commands[1].LocalFlags[0].Hidden = true
+		commands[2].Hidden = true
+		if removeUnrelated {
+			commands[2].LocalFlags = commands[2].LocalFlags[:1]
+		}
+		topicCreate := testCommand("dws chat topic create")
+		topicCreate.BoolConstParams = map[string]bool{"convThreadEnabled": true}
+		commands = append(commands,
+			topicCreate,
+			testCommand("dws chat topic new", Flag{Name: "new-id", Type: "string", Required: true}),
+		)
+	}
+	return testSnapshot(commands...)
+}
+
+func withCommandBoolConstParams(snapshot Snapshot, path string, values map[string]bool) Snapshot {
+	cloned := snapshot
+	cloned.Commands = append([]Command(nil), snapshot.Commands...)
+	for index := range cloned.Commands {
+		if cloned.Commands[index].Path == path {
+			cloned.Commands[index].BoolConstParams = values
+			break
+		}
+	}
+	return cloned
+}

internal/interfacesnapshot/compare.go

@@ -71,6 +71,9 @@ func CompareAll(current Snapshot, references map[string]Snapshot) Report {
 //     alias),
 //   - flags accepted at each command path may not disappear, change type, or
 //     become required; an existing path may not gain a new required flag,
+//   - once bool ConstParams evidence exists, its exact property/value map is a
+//     durable contract; adding the first evidence to an older snapshot remains
+//     a silent bootstrap,
 //   - new commands and flags are allowed.
 //
 // The single exception to the type rule is an individually reviewed migration
@@ -153,6 +156,14 @@ func Compare(current, baseline Snapshot, reference string) Comparison {
 }
 
 func compareCommandContract(result *Comparison, acceptedPath string, oldCommand, newCommand Command) {
+	if len(oldCommand.BoolConstParams) > 0 && !reflect.DeepEqual(oldCommand.BoolConstParams, newCommand.BoolConstParams) {
+		result.Blocking = append(result.Blocking, Change{
+			Kind:   "bool_const_params_changed",
+			Path:   acceptedPath,
+			Before: fmt.Sprintf("%v", oldCommand.BoolConstParams),
+			After:  fmt.Sprintf("%v", newCommand.BoolConstParams),
+		})
+	}
 	if oldCommand.Runnable && !newCommand.Runnable {
 		result.Blocking = append(result.Blocking, Change{
 			Kind:   "command_became_non_runnable",

internal/interfacesnapshot/compare_test.go

@@ -135,6 +135,63 @@ func TestCrossPlatformCoverageCompareAllowsRenameWhenOldPathIsAlias(t *testing.T
 	}
 }
 
+func TestCrossPlatformCoverageCompareAllowsBoolConstParamsBootstrapAddition(t *testing.T) {
+	base := testSnapshot(
+		testCommand("dws"),
+		testCommand("dws send"),
+	)
+	current := testSnapshot(
+		testCommand("dws"),
+		testCommand("dws send"),
+	)
+	current.Commands[1].BoolConstParams = map[string]bool{"convThreadEnabled": true}
+
+	comparison := Compare(current, base, "base")
+	if !comparison.Compatible || len(comparison.Blocking) != 0 || len(comparison.Additions) != 0 {
+		t.Fatalf("ordinary Compare treated bootstrapped bool ConstParams evidence as a compatibility change: %#v", comparison)
+	}
+}
+
+func TestCrossPlatformCoverageCompareBlocksBoolConstParamsDriftAfterBootstrap(t *testing.T) {
+	base := testSnapshot(
+		testCommand("dws"),
+		testCommand("dws send"),
+	)
+	base.Commands[1].BoolConstParams = map[string]bool{"convThreadEnabled": true}
+
+	for _, test := range []struct {
+		name    string
+		current map[string]bool
+	}{
+		{name: "removed", current: nil},
+		{name: "value flipped", current: map[string]bool{"convThreadEnabled": false}},
+		{name: "extra key", current: map[string]bool{"convThreadEnabled": true, "other": false}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			current := testSnapshot(
+				testCommand("dws"),
+				testCommand("dws send"),
+			)
+			current.Commands[1].BoolConstParams = test.current
+
+			comparison := Compare(current, base, "base")
+			if comparison.Compatible {
+				t.Fatalf("historical bool ConstParams drift was accepted: %#v", comparison)
+			}
+			if len(comparison.Blocking) != 1 {
+				t.Fatalf("blocking=%#v, want exactly one durable contract change", comparison.Blocking)
+			}
+			change := comparison.Blocking[0]
+			if change.Kind != "bool_const_params_changed" || change.Path != "dws send" {
+				t.Fatalf("blocking=%#v, want bool_const_params_changed at dws send", comparison.Blocking)
+			}
+			if len(comparison.Additions) != 0 {
+				t.Fatalf("bool ConstParams drift also produced additions: %#v", comparison.Additions)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageCompareBlocksRemovedAlias(t *testing.T) {
 	base := testSnapshot(
 		testCommand("dws"),

internal/interfacesnapshot/migrations.go

@@ -91,22 +91,32 @@ func validateFlagMigrationJSONSchema(data []byte) error {
 }
 
 func validateMigrationJSONValue(decoder *json.Decoder, path string, schema reflect.Type) error {
+	return validateLabeledMigrationJSONValue(decoder, path, schema, "flag")
+}
+
+func validateLabeledMigrationJSONValue(decoder *json.Decoder, path string, schema reflect.Type, label string) error {
 	token, err := decoder.Token()
 	if err != nil {
-		return fmt.Errorf("read flag migration manifest value at %s: %w", path, err)
+		return fmt.Errorf("read %s migration manifest value at %s: %w", label, path, err)
+	}
+	for schema.Kind() == reflect.Pointer {
+		if token == nil {
+			return migrationJSONTypeError(path, schema.Elem(), token, label)
+		}
+		schema = schema.Elem()
 	}
 
 	switch schema.Kind() {
 	case reflect.Struct:
 		if delimiter, ok := token.(json.Delim); !ok || delimiter != '{' {
-			return migrationJSONTypeError(path, schema, token)
+			return migrationJSONTypeError(path, schema, token, label)
 		}
 		fields := migrationJSONFields(schema)
 		seen := make(map[string]bool, len(fields))
 		for decoder.More() {
 			keyToken, keyErr := decoder.Token()
 			if keyErr != nil {
-				return fmt.Errorf("read flag migration manifest field at %s: %w", path, keyErr)
+				return fmt.Errorf("read %s migration manifest field at %s: %w", label, path, keyErr)
 			}
 			// encoding/json guarantees object member names are string tokens.
 			key := keyToken.(string)
@@ -115,57 +125,58 @@ func validateMigrationJSONValue(decoder *json.Decoder, path string, schema refle
 				for canonical := range fields {
 					if strings.EqualFold(key, canonical) {
 						return fmt.Errorf(
-							"flag migration manifest contains non-canonical field %q at %s (want %q)",
+							"%s migration manifest contains non-canonical field %q at %s (want %q)",
+							label,
 							key,
 							path,
 							canonical,
 						)
 					}
 				}
-				return fmt.Errorf("flag migration manifest contains unknown field %q at %s", key, path)
+				return fmt.Errorf("%s migration manifest contains unknown field %q at %s", label, key, path)
 			}
 			if seen[key] {
-				return fmt.Errorf("flag migration manifest contains duplicate field %q at %s", key, path)
+				return fmt.Errorf("%s migration manifest contains duplicate field %q at %s", label, key, path)
 			}
 			seen[key] = true
-			if err := validateMigrationJSONValue(decoder, path+"."+key, fieldSchema); err != nil {
+			if err := validateLabeledMigrationJSONValue(decoder, path+"."+key, fieldSchema, label); err != nil {
 				return err
 			}
 		}
 		if _, closeErr := decoder.Token(); closeErr != nil {
-			return fmt.Errorf("close flag migration manifest object at %s: %w", path, closeErr)
+			return fmt.Errorf("close %s migration manifest object at %s: %w", label, path, closeErr)
 		}
 		return nil
 	case reflect.Slice:
 		if delimiter, ok := token.(json.Delim); !ok || delimiter != '[' {
-			return migrationJSONTypeError(path, schema, token)
+			return migrationJSONTypeError(path, schema, token, label)
 		}
 		for index := 0; decoder.More(); index++ {
-			if err := validateMigrationJSONValue(decoder, fmt.Sprintf("%s[%d]", path, index), schema.Elem()); err != nil {
+			if err := validateLabeledMigrationJSONValue(decoder, fmt.Sprintf("%s[%d]", path, index), schema.Elem(), label); err != nil {
 				return err
 			}
 		}
 		if _, closeErr := decoder.Token(); closeErr != nil {
-			return fmt.Errorf("close flag migration manifest array at %s: %w", path, closeErr)
+			return fmt.Errorf("close %s migration manifest array at %s: %w", label, path, closeErr)
 		}
 		return nil
 	case reflect.String:
 		if _, ok := token.(string); !ok {
-			return migrationJSONTypeError(path, schema, token)
+			return migrationJSONTypeError(path, schema, token, label)
 		}
 		return nil
 	case reflect.Int:
 		if _, ok := token.(json.Number); !ok {
-			return migrationJSONTypeError(path, schema, token)
+			return migrationJSONTypeError(path, schema, token, label)
 		}
 		return nil
 	case reflect.Bool:
 		if _, ok := token.(bool); !ok {
-			return migrationJSONTypeError(path, schema, token)
+			return migrationJSONTypeError(path, schema, token, label)
 		}
 		return nil
 	default:
-		return fmt.Errorf("flag migration manifest value at %s has unsupported Go schema type %s", path, schema)
+		return fmt.Errorf("%s migration manifest value at %s has unsupported Go schema type %s", label, path, schema)
 	}
 }
 
@@ -188,9 +199,10 @@ func migrationJSONFields(schema reflect.Type) map[string]reflect.Type {
 	return fields
 }
 
-func migrationJSONTypeError(path string, want reflect.Type, token json.Token) error {
+func migrationJSONTypeError(path string, want reflect.Type, token json.Token, label string) error {
 	return fmt.Errorf(
-		"flag migration manifest value at %s must be %s, got %s",
+		"%s migration manifest value at %s must be %s, got %s",
+		label,
 		path,
 		migrationJSONKindDescription(want),
 		migrationJSONTokenDescription(token),

internal/interfacesnapshot/snapshot.go

@@ -22,12 +22,13 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd/runtimeannotate"
 	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
-const SchemaVersion = 2
+const SchemaVersion = 3
 
 // FlagAliasOfAnnotation records a framework-originated reviewed relationship
 // between a retained compatibility flag and an exact canonical Cobra flag.
@@ -66,13 +67,14 @@ type Snapshot struct {
 // Command contains compatibility-relevant command metadata. Path always
 // includes the root command name (for example, "dws chat message send").
 type Command struct {
-	Path           string   `json:"path"`
-	Runnable       bool     `json:"runnable"`
-	Hidden         bool     `json:"hidden"`
-	Deprecated     string   `json:"deprecated,omitempty"`
-	Aliases        []string `json:"aliases"`
-	LocalFlags     []Flag   `json:"local_flags"`
-	InheritedFlags []Flag   `json:"inherited_flags"`
+	Path            string          `json:"path"`
+	Runnable        bool            `json:"runnable"`
+	Hidden          bool            `json:"hidden"`
+	Deprecated      string          `json:"deprecated,omitempty"`
+	Aliases         []string        `json:"aliases"`
+	LocalFlags      []Flag          `json:"local_flags"`
+	InheritedFlags  []Flag          `json:"inherited_flags"`
+	BoolConstParams map[string]bool `json:"bool_const_params,omitempty"`
 }
 
 // Flag contains the stable pflag contract visible at a command node.
@@ -126,14 +128,16 @@ func Capture(root *cobra.Command) Snapshot {
 		}
 		aliases = compactSorted(aliases)
 
+		boolConstParams := corecmd.InterfaceBoolConstParams(cmd)
 		snapshot.Commands = append(snapshot.Commands, Command{
-			Path:           path,
-			Runnable:       cmd.Runnable(),
-			Hidden:         cmd.Hidden,
-			Deprecated:     strings.TrimSpace(cmd.Deprecated),
-			Aliases:        aliases,
-			LocalFlags:     captureFlags(cmd.LocalFlags()),
-			InheritedFlags: captureFlags(cmd.InheritedFlags()),
+			Path:            path,
+			Runnable:        cmd.Runnable(),
+			Hidden:          cmd.Hidden,
+			Deprecated:      strings.TrimSpace(cmd.Deprecated),
+			Aliases:         aliases,
+			LocalFlags:      captureFlags(cmd.LocalFlags()),
+			InheritedFlags:  captureFlags(cmd.InheritedFlags()),
+			BoolConstParams: boolConstParams,
 		})
 
 		children := append([]*cobra.Command(nil), cmd.Commands()...)
@@ -198,6 +202,9 @@ func (s Snapshot) Validate() error {
 			return fmt.Errorf("interface snapshot contains duplicate command path %q", command.Path)
 		}
 		seenCommands[command.Path] = true
+		if command.BoolConstParams != nil && len(command.BoolConstParams) == 0 {
+			return fmt.Errorf("command %q must omit empty bool_const_params", command.Path)
+		}
 		if err := validateFlags(command.Path, "local", command.LocalFlags); err != nil {
 			return err
 		}

internal/interfacesnapshot/snapshot_test.go

@@ -17,6 +17,7 @@ import (
 	"bytes"
 	"encoding/json"
 	"reflect"
+	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
@@ -98,16 +99,105 @@ func TestCrossPlatformCoverageCaptureUsesStableNoiseRulesAndFlagScopes(t *testin
 
 func TestCrossPlatformCoverageReadRejectsUnknownSnapshotFields(t *testing.T) {
 	input := bytes.NewBufferString(`{
-  "schema_version": 2,
-  "rules": {"excluded_command_subtrees": [], "excluded_flags": []},
-  "commands": [],
-  "future_field": true
+	  "schema_version": 3,
+	  "rules": {"excluded_command_subtrees": [], "excluded_flags": []},
+	  "commands": [],
+	  "future_field": true
 }`)
 	if _, err := Read(input); err == nil {
 		t.Fatal("Read accepted an unknown field")
 	}
 }
 
+func TestCrossPlatformCoverageCaptureRoundTripsFrameworkBoolConstParams(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	leaf := corecmd.New(corecmd.Spec{
+		Use:         "send",
+		ConstParams: map[string]any{"convThreadEnabled": true, "precheckOnly": false},
+		Invoke:      func(*corecmd.Ctx, map[string]any) error { return nil },
+	})
+	root.AddCommand(leaf)
+
+	snapshot := Capture(root)
+	got := commandIndex(snapshot)["dws send"].BoolConstParams
+	want := map[string]bool{"convThreadEnabled": true, "precheckOnly": false}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("captured bool ConstParams = %#v, want %#v", got, want)
+	}
+
+	var encoded bytes.Buffer
+	if err := Write(&encoded, snapshot); err != nil {
+		t.Fatalf("Write: %v", err)
+	}
+	decoded, err := Read(bytes.NewReader(encoded.Bytes()))
+	if err != nil {
+		t.Fatalf("Read: %v", err)
+	}
+	if got := commandIndex(decoded)["dws send"].BoolConstParams; !reflect.DeepEqual(got, want) {
+		t.Fatalf("round-tripped bool ConstParams = %#v, want %#v", got, want)
+	}
+}
+
+func TestCrossPlatformCoverageCaptureIgnoresHandwrittenLegacyConstParamsAnnotations(t *testing.T) {
+	root := &cobra.Command{Use: "dws"}
+	direct := &cobra.Command{
+		Use: "direct",
+		Run: func(*cobra.Command, []string) {},
+		Annotations: map[string]string{
+			"dws.compat.bool_const_params":   `{"forged":true}`,
+			"dws.compat.const_params_origin": "corecmd.const_params.v1",
+		},
+	}
+	businessConstructor := func() *cobra.Command {
+		payloadKey := strings.Join([]string{"dws.compat.bool_", "const_params"}, "")
+		originKey := strings.Join([]string{"dws.compat.const_", "params_origin"}, "")
+		origin := strings.Join([]string{"corecmd.const_", "params.v1"}, "")
+		return &cobra.Command{
+			Use: "business",
+			Run: func(*cobra.Command, []string) {},
+			Annotations: map[string]string{
+				payloadKey: `{"forged":true}`,
+				originKey:  origin,
+			},
+		}
+	}
+	root.AddCommand(direct, businessConstructor())
+
+	snapshot := Capture(root)
+	if err := snapshot.Validate(); err != nil {
+		t.Fatalf("handwritten legacy annotations affected snapshot validity: %v", err)
+	}
+	for _, path := range []string{"dws direct", "dws business"} {
+		if got := commandIndex(snapshot)[path].BoolConstParams; got != nil {
+			t.Fatalf("%s forged bool ConstParams evidence = %#v", path, got)
+		}
+	}
+	var encoded bytes.Buffer
+	if err := Write(&encoded, snapshot); err != nil {
+		t.Fatalf("Write snapshot without forged evidence: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageReadRejectsMalformedBoolConstParams(t *testing.T) {
+	for _, payload := range []string{`{"fixed":"true"}`, `{}`} {
+		input := bytes.NewBufferString(`{
+		  "schema_version": 3,
+		  "rules": {"excluded_command_subtrees": [], "excluded_flags": []},
+		  "commands": [{
+		    "path": "dws send",
+		    "runnable": true,
+		    "aliases": [],
+		    "local_flags": [],
+		    "inherited_flags": [],
+		    "bool_const_params": ` + payload + `
+		  }]
+		}`)
+		if _, err := Read(input); err == nil {
+			t.Fatalf("Read accepted malformed bool_const_params %s", payload)
+		}
+	}
+}
+
 func TestCrossPlatformCoverageCaptureRoundTripsFrameworkFlagAlias(t *testing.T) {
 	if FlagAliasOfAnnotation != runtimeannotate.AnnotationFlagAliasOf {
 		t.Fatalf(

internal/keychain/coverage_edges_test.go

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

internal/keychain/keychain_darwin.go

@@ -237,26 +237,6 @@ func getSystemDEKReadOnly(service string) ([]byte, error) {
 	return key, err
 }
 
-func decodeSystemDEK(encodedKey string) ([]byte, bool) {
-	key, err := base64.StdEncoding.DecodeString(encodedKey)
-	return key, err == nil && len(key) == dekBytes
-}
-
-func readStoredSystemDEK(service string, runtime darwinKeychainRuntime) ([]byte, error) {
-	encodedKey, err := runtime.get(service, "dek")
-	if err == nil {
-		key, ok := decodeSystemDEK(encodedKey)
-		if ok {
-			return key, nil
-		}
-		return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
-	}
-	if errors.Is(err, keyring.ErrNotFound) {
-		return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
-	}
-	return nil, NewUnavailableError("read DEK from macOS Keychain", err)
-}
-
 func getSystemDEKReadOnlyWithRuntime(service string, runtime darwinKeychainRuntime) ([]byte, error, <-chan struct{}) {
 	if err := runtime.checkAvailable(); err != nil {
 		return nil, err, finishedDarwinKeychainWorker()
@@ -264,7 +244,18 @@ func getSystemDEKReadOnlyWithRuntime(service string, runtime darwinKeychainRunti
 
 	const operation = "read DEK from macOS Keychain"
 	worker := startDarwinKeychainWorker(operation, func() ([]byte, error) {
-		return readStoredSystemDEK(service, runtime)
+		encodedKey, err := runtime.get(service, "dek")
+		if err == nil {
+			key, decodeErr := base64.StdEncoding.DecodeString(encodedKey)
+			if decodeErr == nil && len(key) == dekBytes {
+				return key, nil
+			}
+			return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
+		}
+		if errors.Is(err, keyring.ErrNotFound) {
+			return nil, fmt.Errorf("read DEK from macOS Keychain: %w", ErrDEKMissing)
+		}
+		return nil, NewUnavailableError("read DEK from macOS Keychain", err)
 	})
 
 	return waitDarwinKeychainWorker(runtime.timeout, operation, worker)
@@ -285,30 +276,28 @@ func getOrCreateDEKWithRuntime(service string, runtime darwinKeychainRuntime) ([
 
 	const operation = "read or create DEK in macOS Keychain"
 	worker := startDarwinKeychainWorker(operation, func() ([]byte, error) {
-		key, err := readStoredSystemDEK(service, runtime)
+		// Try to get existing DEK from system Keychain
+		encodedKey, err := runtime.get(service, "dek")
 		if err == nil {
-			return key, nil
-		}
-		if !IsDEKMissing(err) {
-			return nil, err
+			key, decodeErr := base64.StdEncoding.DecodeString(encodedKey)
+			if decodeErr == nil && len(key) == dekBytes {
+				return key, nil
+			}
+		} else if !errors.Is(err, keyring.ErrNotFound) {
+			return nil, NewUnavailableError("read DEK from macOS Keychain", err)
 		}
 
-		// Generate a candidate only when the slot is empty or unreadable.
-		// Concurrent writers must not replace a DEK another process just stored.
-		key = make([]byte, dekBytes)
+		// Generate new DEK if not found or invalid
+		key := make([]byte, dekBytes)
 		if _, randErr := runtime.randRead(key); randErr != nil {
 			return nil, randErr
 		}
-		if setErr := runtime.set(service, "dek", base64.StdEncoding.EncodeToString(key)); setErr != nil {
-			existing, getErr := readStoredSystemDEK(service, runtime)
-			if getErr == nil {
-				return existing, nil
-			}
+
+		// Store in system Keychain
+		encodedKey = base64.StdEncoding.EncodeToString(key)
+		if setErr := runtime.set(service, "dek", encodedKey); setErr != nil {
 			return nil, NewUnavailableError("store DEK in macOS Keychain", setErr)
 		}
-		if existing, getErr := readStoredSystemDEK(service, runtime); getErr == nil {
-			return existing, nil
-		}
 		return key, nil
 	})
 

internal/msgcrypto/authcode.go

@@ -1,127 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"sync"
-	"time"
-)
-
-// DefaultAuthCodeTTL is the unconsumed-cache window for a freshly minted
-// vendor authCode. The portal issues codes with expiresIn=120s and they are
-// one-shot, so the default stays under that server window. Prefer not wrapping
-// PortalAuthCode in CachedAuthCode: mint in goProxy and discard after the key
-// request.
-const DefaultAuthCodeTTL = 90 * time.Second
-
-// ErrNoAuthCode means the provider returned an empty code without an error.
-var ErrNoAuthCode = errors.New("msgcrypto: auth code provider returned an empty code")
-
-// AuthCodeProvider yields a DingTalk 免登 authCode for key-server
-// authentication. DWS does not mint the code itself, so integrations inject an
-// implementation. The backend calls this only from the vendor goProxy
-// callback, never on every encrypt or decrypt.
-//
-// Implementations must be safe for concurrent use; the backend may call this
-// from a CGO callback while an encrypt or decrypt call is in flight.
-type AuthCodeProvider interface {
-	AuthCode(ctx context.Context) (string, error)
-}
-
-// CorpAuthCodeProvider mints a code for a specific organization. PortalAuthCode
-// implements this so goProxy can pass the C library's corpID. Domain and
-// redirectURI are never part of this call.
-type CorpAuthCodeProvider interface {
-	AuthCodeProvider
-	AuthCodeForCorp(ctx context.Context, corpID string) (string, error)
-}
-
-// AuthCodeFunc adapts a function to AuthCodeProvider.
-type AuthCodeFunc func(ctx context.Context) (string, error)
-
-// AuthCode calls f.
-func (f AuthCodeFunc) AuthCode(ctx context.Context) (string, error) { return f(ctx) }
-
-// StaticAuthCode returns a provider that always yields code. It is meant for
-// tests and manual integration runs; a static code stops working once the
-// server-side five-minute window closes.
-func StaticAuthCode(code string) AuthCodeProvider {
-	return AuthCodeFunc(func(context.Context) (string, error) {
-		if code == "" {
-			return "", ErrNoAuthCode
-		}
-		return code, nil
-	})
-}
-
-// CachedAuthCode memoises an AuthCodeProvider for a TTL so a burst of key
-// requests does not trigger one upstream call each.
-type CachedAuthCode struct {
-	provider AuthCodeProvider
-	ttl      time.Duration
-	now      func() time.Time
-
-	mu        sync.Mutex
-	code      string
-	expiresAt time.Time
-}
-
-// NewCachedAuthCode wraps provider with a TTL cache. A ttl of zero or less
-// selects DefaultAuthCodeTTL.
-func NewCachedAuthCode(provider AuthCodeProvider, ttl time.Duration) *CachedAuthCode {
-	if ttl <= 0 {
-		ttl = DefaultAuthCodeTTL
-	}
-	return &CachedAuthCode{provider: provider, ttl: ttl, now: time.Now}
-}
-
-// AuthCode returns the cached code when it is still fresh, otherwise fetches a
-// new one. A failed fetch leaves no stale value behind.
-func (c *CachedAuthCode) AuthCode(ctx context.Context) (string, error) {
-	if c.provider == nil {
-		return "", ErrNoAuthCodeProvider
-	}
-
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	if c.code != "" && c.now().Before(c.expiresAt) {
-		return c.code, nil
-	}
-
-	code, err := c.provider.AuthCode(ctx)
-	if err != nil {
-		c.code, c.expiresAt = "", time.Time{}
-		return "", fmt.Errorf("msgcrypto: fetch auth code: %w", err)
-	}
-	if code == "" {
-		c.code, c.expiresAt = "", time.Time{}
-		return "", ErrNoAuthCode
-	}
-
-	c.code = code
-	c.expiresAt = c.now().Add(c.ttl)
-	return code, nil
-}
-
-// Invalidate drops the cached code so the next AuthCode call refetches. The
-// backend calls this after the key server rejects a code.
-func (c *CachedAuthCode) Invalidate() {
-	c.mu.Lock()
-	c.code, c.expiresAt = "", time.Time{}
-	c.mu.Unlock()
-}

internal/msgcrypto/authcode_test.go

@@ -1,228 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-)
-
-// countingProvider hands out a fresh code per call and records how often it was
-// asked, so cache behaviour can be asserted.
-type countingProvider struct {
-	mu    sync.Mutex
-	calls int
-	code  string
-	err   error
-}
-
-func (p *countingProvider) AuthCode(context.Context) (string, error) {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	p.calls++
-	if p.err != nil {
-		return "", p.err
-	}
-	if p.code != "" {
-		return p.code, nil
-	}
-	return "code-" + string(rune('a'+p.calls-1)), nil
-}
-
-// callCount reports the number of upstream fetches.
-func (p *countingProvider) callCount() int {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	return p.calls
-}
-
-func TestAuthCodeFuncAdaptsFunction(t *testing.T) {
-	provider := AuthCodeFunc(func(context.Context) (string, error) { return "abc", nil })
-	code, err := provider.AuthCode(context.Background())
-	if err != nil || code != "abc" {
-		t.Fatalf("AuthCode() = %q, %v; want abc, nil", code, err)
-	}
-}
-
-func TestStaticAuthCodeReturnsCode(t *testing.T) {
-	code, err := StaticAuthCode("fixed").AuthCode(context.Background())
-	if err != nil || code != "fixed" {
-		t.Fatalf("AuthCode() = %q, %v; want fixed, nil", code, err)
-	}
-}
-
-func TestStaticAuthCodeRejectsEmptyCode(t *testing.T) {
-	_, err := StaticAuthCode("").AuthCode(context.Background())
-	if !errors.Is(err, ErrNoAuthCode) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCode", err)
-	}
-}
-
-func TestCachedAuthCodeReusesCodeWithinTTL(t *testing.T) {
-	provider := &countingProvider{code: "same"}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	for i := 0; i < 5; i++ {
-		code, err := cache.AuthCode(context.Background())
-		if err != nil {
-			t.Fatalf("AuthCode() #%d = %v", i+1, err)
-		}
-		if code != "same" {
-			t.Fatalf("AuthCode() #%d = %q, want same", i+1, code)
-		}
-	}
-	if got := provider.callCount(); got != 1 {
-		t.Fatalf("upstream called %d times, want 1 (the code must be cached)", got)
-	}
-}
-
-func TestCachedAuthCodeRefetchesAfterTTL(t *testing.T) {
-	provider := &countingProvider{}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	now := time.Now()
-	cache.now = func() time.Time { return now }
-
-	first, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("first AuthCode() = %v", err)
-	}
-
-	// Move past the TTL. The DingTalk code expires server-side, so a stale
-	// one must not be reused.
-	now = now.Add(time.Minute + time.Second)
-
-	second, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("second AuthCode() = %v", err)
-	}
-	if first == second {
-		t.Fatalf("AuthCode() returned the same code %q after the TTL expired", first)
-	}
-	if got := provider.callCount(); got != 2 {
-		t.Fatalf("upstream called %d times, want 2", got)
-	}
-}
-
-func TestCachedAuthCodeDefaultTTLIsUnderServerWindow(t *testing.T) {
-	// Portal vendorAuthCode expiresIn is 120s and the code is one-shot.
-	// The unconsumed-cache window must stay under that server lifetime.
-	if DefaultAuthCodeTTL >= 120*time.Second {
-		t.Fatalf("DefaultAuthCodeTTL = %v, want less than the 120s portal expiresIn", DefaultAuthCodeTTL)
-	}
-	cache := NewCachedAuthCode(&countingProvider{}, 0)
-	if cache.ttl != DefaultAuthCodeTTL {
-		t.Fatalf("ttl = %v, want DefaultAuthCodeTTL %v", cache.ttl, DefaultAuthCodeTTL)
-	}
-}
-
-func TestCachedAuthCodeNegativeTTLFallsBackToDefault(t *testing.T) {
-	cache := NewCachedAuthCode(&countingProvider{}, -time.Second)
-	if cache.ttl != DefaultAuthCodeTTL {
-		t.Fatalf("ttl = %v, want DefaultAuthCodeTTL %v", cache.ttl, DefaultAuthCodeTTL)
-	}
-}
-
-func TestCachedAuthCodePropagatesUpstreamError(t *testing.T) {
-	wantErr := errors.New("token service down")
-	cache := NewCachedAuthCode(&countingProvider{err: wantErr}, time.Minute)
-
-	_, err := cache.AuthCode(context.Background())
-	if !errors.Is(err, wantErr) {
-		t.Fatalf("AuthCode() = %v, want it to wrap %v", err, wantErr)
-	}
-}
-
-func TestCachedAuthCodeDoesNotCacheFailures(t *testing.T) {
-	provider := &countingProvider{err: errors.New("transient")}
-	cache := NewCachedAuthCode(provider, time.Minute)
-
-	if _, err := cache.AuthCode(context.Background()); err == nil {
-		t.Fatal("AuthCode() = nil error, want failure")
-	}
-
-	provider.mu.Lock()
-	provider.err = nil
-	provider.code = "recovered"
-	provider.mu.Unlock()
-
-	code, err := cache.AuthCode(context.Background())
-	if err != nil {
-		t.Fatalf("AuthCode() after recovery = %v", err)
-	}
-	if code != "recovered" {
-		t.Fatalf("AuthCode() = %q, want recovered (a failure must not be cached)", code)
-	}
-}
-
-func TestCachedAuthCodeRejectsEmptyUpstreamCode(t *testing.T) {
-	// A provider that reports success with no code is a bug upstream; the
-	// cache must surface it instead of caching an unusable value.
-	cache := NewCachedAuthCode(AuthCodeFunc(func(context.Context) (string, error) {
-		return "", nil
-	}), time.Minute)
-
-	if _, err := cache.AuthCode(context.Background()); !errors.Is(err, ErrNoAuthCode) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCode", err)
-	}
-}
-
-func TestCachedAuthCodeInvalidateForcesRefetch(t *testing.T) {
-	provider := &countingProvider{}
-	cache := NewCachedAuthCode(provider, time.Hour)
-
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("first AuthCode() = %v", err)
-	}
-	cache.Invalidate()
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("second AuthCode() = %v", err)
-	}
-	if got := provider.callCount(); got != 2 {
-		t.Fatalf("upstream called %d times, want 2 after Invalidate", got)
-	}
-}
-
-func TestCachedAuthCodeWithoutProviderReportsMissingProvider(t *testing.T) {
-	cache := NewCachedAuthCode(nil, time.Minute)
-	if _, err := cache.AuthCode(context.Background()); !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("AuthCode() = %v, want ErrNoAuthCodeProvider", err)
-	}
-}
-
-func TestCachedAuthCodeIsSafeForConcurrentUse(t *testing.T) {
-	// The backend may ask for a code from a CGO callback while another
-	// operation is in flight, so concurrent access must not race.
-	provider := &countingProvider{code: "shared"}
-	cache := NewCachedAuthCode(provider, time.Hour)
-
-	var wg sync.WaitGroup
-	for i := 0; i < 32; i++ {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			if code, err := cache.AuthCode(context.Background()); err != nil || code != "shared" {
-				t.Errorf("AuthCode() = %q, %v; want shared, nil", code, err)
-			}
-		}()
-	}
-	wg.Wait()
-
-	if got := provider.callCount(); got != 1 {
-		t.Fatalf("upstream called %d times, want 1", got)
-	}
-}

internal/msgcrypto/cipher_safechat.go

@@ -1,159 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// The constraint below must stay in sync with cipher_stub.go, which negates it
-// verbatim. It encodes the platforms the vendor ships a libsafechat.a for:
-// darwin and linux on amd64/arm64, plus windows/amd64. windows/arm64 is
-// deliberately excluded because the vendor has not delivered that static
-// library, and DWS does release that target.
-
-//go:build safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64))
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"sync"
-
-	safechat "safechat-go-sdk"
-)
-
-// BackendVersion identifies the compiled-in vendor SDK.
-const BackendVersion = "safechat " + safechat.Version
-
-// Available reports that this binary carries the SafeChat backend.
-func Available() bool { return true }
-
-// safechatCipher adapts the vendor client to Cipher.
-//
-// The vendor client serialises its own C calls internally, so this type adds no
-// further locking. Auth codes are minted only from AuthCodeHook, which the
-// vendor SDK calls inside goProxy when a key is actually missing.
-type safechatCipher struct {
-	client      *safechat.Client
-	codes       AuthCodeProvider
-	allowedHost string
-
-	mu          sync.Mutex
-	lastCodeErr error
-}
-
-// newBackend starts the vendor client against cfg's keystore.
-//
-// A warm keystore serves encrypt and decrypt without a key request, so no
-// authCode is fetched at open time. The hook runs only if goProxy fires.
-func newBackend(ctx context.Context, cfg Config) (Cipher, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-
-	var logf func(string, ...any)
-	if cfg.Debug {
-		logf = cfg.Logf
-	}
-
-	c := &safechatCipher{codes: cfg.AuthCode, allowedHost: cfg.AllowedRedirectHost}
-	client, err := safechat.New(safechat.Config{
-		DataPath:     cfg.KeystoreDir,
-		UserID:       cfg.UserID,
-		KeyServer:    cfg.KeyServer,
-		MaxRetry:     cfg.MaxRetry,
-		HTTPTimeout:  cfg.HTTPTimeout,
-		Logger:       newRedactingLogger(logf),
-		AuthCodeHook: c.authCodeHook,
-	})
-	if err != nil {
-		if errors.Is(err, safechat.ErrAlreadyInitialized) {
-			return nil, ErrAlreadyOpen
-		}
-		return nil, fmt.Errorf("msgcrypto: start safechat backend: %w", err)
-	}
-	c.client = client
-	return c, nil
-}
-
-// EncryptMessage encrypts plaintext and returns the vendor ciphertext.
-func (c *safechatCipher) EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	c.setLastCodeErr(nil)
-	out, err := c.client.EncryptMsg(corpID, staffID, plaintext)
-	if err != nil {
-		return nil, c.explain("encrypt", corpID, err)
-	}
-	return out, nil
-}
-
-// DecryptMessage decrypts a vendor ciphertext.
-func (c *safechatCipher) DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error) {
-	if err := ctx.Err(); err != nil {
-		return nil, err
-	}
-	c.setLastCodeErr(nil)
-	out, err := c.client.DecryptMsg(corpID, staffID, ciphertext)
-	if err != nil {
-		return nil, c.explain("decrypt", corpID, err)
-	}
-	return out, nil
-}
-
-// Close releases the vendor client.
-func (c *safechatCipher) Close() error {
-	c.client.Close()
-	return nil
-}
-
-// authCodeHook is invoked from goProxy immediately before the key request.
-// domain is compared locally and never forwarded to portal. The returned
-// code is used once by the SDK and is not stored on the client.
-func (c *safechatCipher) authCodeHook(corpID, domain string) (string, error) {
-	code, err := mintAuthCodeForProxy(c.codes, c.allowedHost, corpID, domain)
-	c.setLastCodeErr(err)
-	return code, err
-}
-
-func (c *safechatCipher) setLastCodeErr(err error) {
-	c.mu.Lock()
-	c.lastCodeErr = err
-	c.mu.Unlock()
-}
-
-func (c *safechatCipher) lastAuthCodeErr() error {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	return c.lastCodeErr
-}
-
-// explain turns a vendor error into an actionable one, folding in a failed
-// goProxy authCode mint and the admin-restricted case.
-func (c *safechatCipher) explain(op, corpID string, opErr error) error {
-	if c.client.IsBlocked(corpID) {
-		return fmt.Errorf("msgcrypto: %s blocked: the organization's key is restricted by its administrator: %w", op, opErr)
-	}
-
-	// A key fetch was needed but we had no usable code: that is the real
-	// cause, so report both.
-	if codeErr := c.lastAuthCodeErr(); codeErr != nil {
-		return fmt.Errorf("msgcrypto: %s failed and no usable auth code was available: %w (auth code error: %v)", op, opErr, codeErr)
-	}
-
-	if errors.Is(opErr, safechat.ErrMaxRetryExceeded) {
-		invalidateAuthCode(c.codes)
-		return fmt.Errorf("msgcrypto: %s failed: key material never became available: %w", op, opErr)
-	}
-
-	return fmt.Errorf("msgcrypto: %s failed: %w", op, opErr)
-}

internal/msgcrypto/cipher_safechat_test.go

@@ -1,161 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// Keep this constraint in sync with cipher_safechat.go.
-
-//go:build safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64))
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-// These tests exercise the real vendor backend, which means they link
-// libsafechat.a and initialise the C library. They never reach the key server:
-// an authCode is only spent when a key is actually fetched, and asserting that
-// encryption fails without one is exactly the behaviour we want pinned.
-
-func TestBackendIsReportedAvailable(t *testing.T) {
-	if !Available() {
-		t.Fatal("Available() = false in a safechat build")
-	}
-	if BackendVersion == "" {
-		t.Fatal("BackendVersion is empty in a safechat build")
-	}
-	if !strings.Contains(BackendVersion, "safechat") {
-		t.Fatalf("BackendVersion = %q, want it to name the vendor SDK", BackendVersion)
-	}
-}
-
-func TestOpenInitialisesCLibraryAndClosesCleanly(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v, want the C library to initialise", err)
-	}
-
-	if info, statErr := os.Stat(dir); statErr != nil || !info.IsDir() {
-		t.Fatalf("Open did not prepare the keystore dir: %v", statErr)
-	}
-
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-
-	// The slot must be free again, otherwise a second Open in the same
-	// process would be refused forever.
-	second, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("second Open() after Close = %v, want success", err)
-	}
-	if err := second.Close(); err != nil {
-		t.Fatalf("second Close() = %v", err)
-	}
-}
-
-func TestOpenRefusesConcurrentSecondCipher(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	first, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer first.Close()
-
-	_, err = Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrAlreadyOpen) {
-		t.Fatalf("second Open() = %v, want ErrAlreadyOpen (the C library keeps global state)", err)
-	}
-}
-
-func TestOpenHonoursCancelledContext(t *testing.T) {
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-
-	_, err := Open(ctx, Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, context.Canceled) {
-		t.Fatalf("Open() with a cancelled context = %v, want context.Canceled", err)
-	}
-}
-
-func TestEncryptWithoutUsableKeyReportsAuthCodeCause(t *testing.T) {
-	// A cold keystore forces a key request. With no reachable key server the
-	// operation must fail with a message that names the auth code, rather
-	// than a bare vendor return code.
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode: AuthCodeFunc(func(context.Context) (string, error) {
-			return "", errors.New("no code available in test")
-		}),
-		KeyServer: "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer cipher.Close()
-
-	_, err = cipher.EncryptMessage(context.Background(), "test-corp", "test-staff", []byte("hello"))
-	if err == nil {
-		t.Skip("the environment served a key without an auth code; nothing to assert")
-	}
-	if !strings.Contains(err.Error(), "auth code") {
-		t.Fatalf("EncryptMessage() = %v, want the error to name the auth code cause", err)
-	}
-}
-
-func TestCipherRejectsBadArgumentsBeforeCallingC(t *testing.T) {
-	cipher, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("placeholder-code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if err != nil {
-		t.Fatalf("Open() = %v", err)
-	}
-	defer cipher.Close()
-
-	if _, err := cipher.EncryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("EncryptMessage() with no corpID = %v, want ErrNoCorpID", err)
-	}
-	// The vendor SDK dereferences the first byte of the payload, so an empty
-	// slice must never reach it.
-	if _, err := cipher.DecryptMessage(context.Background(), "corp", "staff", nil); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("DecryptMessage() with no payload = %v, want ErrEmptyPayload", err)
-	}
-}

internal/msgcrypto/cipher_stub.go

@@ -1,34 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// The constraint below is the exact negation of the one in cipher_safechat.go;
-// change both together. This file covers every default DWS build: the release
-// binaries are cross-compiled with CGO_ENABLED=0, and windows/arm64 has no
-// vendor static library even when the tag is set.
-
-//go:build !(safechat && cgo && (((darwin || linux) && (amd64 || arm64)) || (windows && amd64)))
-
-package msgcrypto
-
-import "context"
-
-// BackendVersion is empty because no backend is compiled in.
-const BackendVersion = ""
-
-// Available reports that this binary has no SafeChat backend, so callers should
-// not offer message encryption.
-func Available() bool { return false }
-
-// newBackend always fails here. Open checks Available first, so this exists to
-// keep the package compiling and to fail safe if that check is ever bypassed.
-func newBackend(context.Context, Config) (Cipher, error) { return nil, ErrUnavailable }

internal/msgcrypto/goproxy_authcode.go

@@ -1,54 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import "context"
-
-// mintAuthCodeForProxy is the goProxy-only mint path. domain is compared
-// locally and never forwarded. A successful mint invalidates any unconsumed
-// cache so a one-shot code cannot be reused.
-func mintAuthCodeForProxy(codes AuthCodeProvider, allowedHost, corpID, domain string) (string, error) {
-	if err := matchRedirectHost(domain, allowedHost); err != nil {
-		return "", err
-	}
-	if codes == nil {
-		return "", ErrNoAuthCodeProvider
-	}
-
-	var (
-		code string
-		err  error
-	)
-	if provider, ok := codes.(CorpAuthCodeProvider); ok {
-		code, err = provider.AuthCodeForCorp(context.Background(), corpID)
-	} else {
-		code, err = codes.AuthCode(context.Background())
-	}
-	if err != nil {
-		invalidateAuthCode(codes)
-		return "", err
-	}
-	if code == "" {
-		invalidateAuthCode(codes)
-		return "", ErrNoAuthCode
-	}
-	invalidateAuthCode(codes)
-	return code, nil
-}
-
-func invalidateAuthCode(codes AuthCodeProvider) {
-	if invalidator, ok := codes.(interface{ Invalidate() }); ok {
-		invalidator.Invalidate()
-	}
-}

internal/msgcrypto/goproxy_authcode_test.go

@@ -1,99 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync"
-	"testing"
-	"time"
-)
-
-type corpCountingProvider struct {
-	mu    sync.Mutex
-	calls []string
-	code  string
-	err   error
-}
-
-func (p *corpCountingProvider) AuthCode(context.Context) (string, error) {
-	return p.AuthCodeForCorp(context.Background(), "")
-}
-
-func (p *corpCountingProvider) AuthCodeForCorp(_ context.Context, corpID string) (string, error) {
-	p.mu.Lock()
-	defer p.mu.Unlock()
-	p.calls = append(p.calls, corpID)
-	if p.err != nil {
-		return "", p.err
-	}
-	if p.code != "" {
-		return p.code, nil
-	}
-	return "code-for-" + corpID, nil
-}
-
-func TestMintAuthCodeForProxyUsesCorpProvider(t *testing.T) {
-	inner := &corpCountingProvider{}
-	code, err := mintAuthCodeForProxy(inner, "sso.anhei.test", "ding_corp", "https://sso.anhei.test/login")
-	if err != nil || code != "code-for-ding_corp" {
-		t.Fatalf("mint = %q, %v; want code-for-ding_corp, nil", code, err)
-	}
-	if len(inner.calls) != 1 || inner.calls[0] != "ding_corp" {
-		t.Fatalf("corpIDs = %v, want [ding_corp]", inner.calls)
-	}
-}
-
-func TestMintAuthCodeForProxyInvalidatesUnconsumedCache(t *testing.T) {
-	inner := &countingProvider{code: "once"}
-	cache := NewCachedAuthCode(inner, time.Hour)
-
-	if _, err := cache.AuthCode(context.Background()); err != nil {
-		t.Fatalf("seed cache: %v", err)
-	}
-	if got := inner.callCount(); got != 1 {
-		t.Fatalf("seed fetches = %d, want 1", got)
-	}
-
-	code, err := mintAuthCodeForProxy(cache, "sso.anhei.test", "ding_corp", "https://sso.anhei.test/login")
-	if err != nil || code != "once" {
-		t.Fatalf("mint = %q, %v; want once, nil", code, err)
-	}
-
-	// Cache was invalidated after spend; next mint hits upstream again.
-	if _, err := mintAuthCodeForProxy(cache, "sso.anhei.test", "ding_corp", "sso.anhei.test"); err != nil {
-		t.Fatalf("second mint: %v", err)
-	}
-	if got := inner.callCount(); got != 2 {
-		t.Fatalf("upstream calls = %d, want 2 (seed reused once, then refetch)", got)
-	}
-}
-
-func TestMintAuthCodeForProxyRejectsDomainMismatchWithoutFetching(t *testing.T) {
-	inner := &corpCountingProvider{code: "once"}
-	_, err := mintAuthCodeForProxy(inner, "sso.anhei.test", "ding_corp", "evil.example.test")
-	if !errors.Is(err, ErrRedirectHostMismatch) {
-		t.Fatalf("mint = %v, want ErrRedirectHostMismatch", err)
-	}
-	if got := len(inner.calls); got != 0 {
-		t.Fatalf("upstream called %d times on domain mismatch, want 0", got)
-	}
-}
-
-func TestMintAuthCodeForProxyRequiresProvider(t *testing.T) {
-	if _, err := mintAuthCodeForProxy(nil, "", "ding_corp", ""); !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("mint = %v, want ErrNoAuthCodeProvider", err)
-	}
-}

internal/msgcrypto/keyserver.go

@@ -1,83 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"fmt"
-	"net"
-	"net/url"
-	"strings"
-)
-
-// validateKeyServer requires an HTTPS URL with a host so the vendor C
-// library cannot pick the key-request destination.
-func validateKeyServer(raw string) error {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return ErrNoKeyServer
-	}
-	u, err := url.Parse(raw)
-	if err != nil || u.Host == "" || u.Scheme == "" {
-		return fmt.Errorf("%w: %q", ErrInvalidKeyServer, raw)
-	}
-	if !strings.EqualFold(u.Scheme, "https") {
-		return fmt.Errorf("%w: %q", ErrKeyServerNotHTTPS, raw)
-	}
-	if hostnameOf(raw) == "" {
-		return fmt.Errorf("%w: %q", ErrInvalidKeyServer, raw)
-	}
-	return nil
-}
-
-// matchRedirectHost compares the goProxy domain to AllowedRedirectHost.
-// Both sides are reduced to a hostname. An empty domain or an empty
-// allowed host skips the check; the domain is never sent to portal.
-func matchRedirectHost(domain, allowed string) error {
-	domain = strings.TrimSpace(domain)
-	allowed = strings.TrimSpace(allowed)
-	if domain == "" || allowed == "" {
-		return nil
-	}
-	got := hostnameOf(domain)
-	want := hostnameOf(allowed)
-	if got == "" || want == "" || got != want {
-		return fmt.Errorf("%w: got %q, want %q", ErrRedirectHostMismatch, got, want)
-	}
-	return nil
-}
-
-// hostnameOf returns the lower-cased hostname of a URL, host:port, or bare
-// host. Path, query, userinfo and port are ignored.
-func hostnameOf(raw string) string {
-	raw = strings.TrimSpace(raw)
-	if raw == "" {
-		return ""
-	}
-	if strings.Contains(raw, "://") {
-		u, err := url.Parse(raw)
-		if err == nil {
-			if host := strings.ToLower(u.Hostname()); host != "" {
-				return host
-			}
-		}
-	}
-	candidate := raw
-	if i := strings.IndexAny(candidate, "/?"); i >= 0 {
-		candidate = candidate[:i]
-	}
-	if host, _, err := net.SplitHostPort(candidate); err == nil {
-		return strings.ToLower(host)
-	}
-	return strings.ToLower(candidate)
-}

internal/msgcrypto/keyserver_test.go

@@ -1,77 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"errors"
-	"testing"
-)
-
-func TestValidateKeyServerAcceptsHTTPS(t *testing.T) {
-	if err := validateKeyServer("https://key.example.test/v1"); err != nil {
-		t.Fatalf("validateKeyServer() = %v, want nil", err)
-	}
-}
-
-func TestValidateKeyServerRejectsEmpty(t *testing.T) {
-	if err := validateKeyServer("  "); !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("validateKeyServer() = %v, want ErrNoKeyServer", err)
-	}
-}
-
-func TestValidateKeyServerRejectsHTTP(t *testing.T) {
-	if err := validateKeyServer("http://key.example.test"); !errors.Is(err, ErrKeyServerNotHTTPS) {
-		t.Fatalf("validateKeyServer() = %v, want ErrKeyServerNotHTTPS", err)
-	}
-}
-
-func TestValidateKeyServerRejectsBareHost(t *testing.T) {
-	if err := validateKeyServer("key.example.test"); !errors.Is(err, ErrInvalidKeyServer) {
-		t.Fatalf("validateKeyServer() = %v, want ErrInvalidKeyServer", err)
-	}
-}
-
-func TestMatchRedirectHostComparesHostOnly(t *testing.T) {
-	if err := matchRedirectHost("https://sso.anhei.test:443/login", "https://sso.anhei.test/path"); err != nil {
-		t.Fatalf("matchRedirectHost() = %v, want nil", err)
-	}
-	if err := matchRedirectHost("sso.anhei.test", "https://sso.anhei.test"); err != nil {
-		t.Fatalf("bare host match = %v, want nil", err)
-	}
-}
-
-func TestMatchRedirectHostSkipsWhenEitherSideEmpty(t *testing.T) {
-	if err := matchRedirectHost("", "https://sso.anhei.test"); err != nil {
-		t.Fatalf("empty domain = %v, want nil", err)
-	}
-	if err := matchRedirectHost("sso.anhei.test", ""); err != nil {
-		t.Fatalf("empty allowed host = %v, want nil", err)
-	}
-}
-
-func TestMatchRedirectHostRejectsMismatch(t *testing.T) {
-	err := matchRedirectHost("evil.example.test", "https://sso.anhei.test")
-	if !errors.Is(err, ErrRedirectHostMismatch) {
-		t.Fatalf("matchRedirectHost() = %v, want ErrRedirectHostMismatch", err)
-	}
-}
-
-func TestHostnameOfStripsPortAndPath(t *testing.T) {
-	if got := hostnameOf("https://SSO.Example.TEST:8443/login?x=1"); got != "sso.example.test" {
-		t.Fatalf("hostnameOf(url) = %q", got)
-	}
-	if got := hostnameOf("SSO.Example.TEST:8443/login"); got != "sso.example.test" {
-		t.Fatalf("hostnameOf(hostport) = %q", got)
-	}
-}

internal/msgcrypto/logger.go

@@ -1,96 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import "fmt"
-
-// redactingLogger satisfies the vendor SDK's logger interface while making it
-// impossible for the SDK to leak secrets into DWS output.
-//
-// This matters because the vendor SDK logs, at debug level, both the authCode
-// it sends to the key server and the raw key-server response body, which
-// carries key material. Rather than trying to enumerate and pattern-match
-// every sensitive field, we drop every string argument and keep only its
-// length. Numeric and boolean arguments pass through, so operators still get
-// the useful diagnostics: HTTP status, payload sizes, timings and return
-// codes. The format string is preserved so it stays clear which field was
-// elided.
-type redactingLogger struct {
-	logf func(format string, args ...any)
-}
-
-// newRedactingLogger returns a logger that forwards to logf, or nil when logf
-// is nil so the SDK skips logging entirely.
-func newRedactingLogger(logf func(format string, args ...any)) *redactingLogger {
-	if logf == nil {
-		return nil
-	}
-	return &redactingLogger{logf: logf}
-}
-
-// Debug forwards a redacted debug line.
-func (l *redactingLogger) Debug(msg string, args ...interface{}) { l.emit("debug", msg, args) }
-
-// Info forwards a redacted info line.
-func (l *redactingLogger) Info(msg string, args ...interface{}) { l.emit("info", msg, args) }
-
-// Error forwards a redacted error line.
-func (l *redactingLogger) Error(msg string, args ...interface{}) { l.emit("error", msg, args) }
-
-// emit rewrites args so no string value survives, then forwards the line.
-func (l *redactingLogger) emit(level, msg string, args []interface{}) {
-	if l == nil || l.logf == nil {
-		return
-	}
-	l.logf("safechat[%s] "+msg, append([]any{level}, redactArgs(args)...)...)
-}
-
-// redactArgs replaces every string-like argument with a length marker and
-// leaves other kinds intact.
-func redactArgs(args []interface{}) []any {
-	out := make([]any, 0, len(args))
-	for _, arg := range args {
-		out = append(out, redactArg(arg))
-	}
-	return out
-}
-
-// redactArg elides a single argument's contents when it could carry a secret.
-// Strings and byte slices are reduced to their length; errors are reduced to
-// their type so a wrapped body preview cannot slip through; everything else
-// (numbers, booleans, durations) is kept because it cannot carry key material.
-func redactArg(arg any) any {
-	switch v := arg.(type) {
-	case string:
-		return redactedValue(len(v))
-	case []byte:
-		return redactedValue(len(v))
-	case fmt.Stringer:
-		// time.Duration and friends are Stringers, but so are opaque types
-		// that may embed a payload. Keep durations, elide the rest.
-		if _, ok := arg.(interface{ Nanoseconds() int64 }); ok {
-			return v.String()
-		}
-		return redactedValue(len(v.String()))
-	case error:
-		return fmt.Sprintf("<%T redacted>", v)
-	default:
-		return v
-	}
-}
-
-// redactedValue renders the placeholder used in place of elided content.
-func redactedValue(n int) string {
-	return fmt.Sprintf("<redacted len=%d>", n)
-}

internal/msgcrypto/logger_test.go

@@ -1,157 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"errors"
-	"fmt"
-	"strings"
-	"testing"
-	"time"
-)
-
-// captureLogf collects emitted lines for assertions.
-func captureLogf(lines *[]string) func(string, ...any) {
-	return func(format string, args ...any) {
-		*lines = append(*lines, fmt.Sprintf(format, args...))
-	}
-}
-
-func TestNewRedactingLoggerReturnsNilWhenSinkIsNil(t *testing.T) {
-	// A nil logger makes the vendor SDK skip logging entirely, which is the
-	// safe default because it logs the authCode at debug level.
-	if got := newRedactingLogger(nil); got != nil {
-		t.Fatalf("newRedactingLogger(nil) = %v, want nil", got)
-	}
-}
-
-func TestRedactingLoggerHidesAuthCode(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	// This mirrors the vendor SDK's own debug line, which prints the code.
-	const secret = "abc123authcode"
-	logger.Debug("Code (auth_token, length=%d): %s", len(secret), secret)
-
-	if len(lines) != 1 {
-		t.Fatalf("got %d lines, want 1", len(lines))
-	}
-	if strings.Contains(lines[0], secret) {
-		t.Fatalf("log line leaked the auth code: %q", lines[0])
-	}
-	if !strings.Contains(lines[0], "redacted") {
-		t.Fatalf("log line = %q, want a redaction marker", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesKeyServerResponseBody(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	body := `{"key":"BASE64KEYMATERIAL==","keyVersion":3}`
-	logger.Debug("Body (length=%d): %s", len(body), body)
-
-	if strings.Contains(lines[0], "BASE64KEYMATERIAL") {
-		t.Fatalf("log line leaked key material: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesByteSlices(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Info("payload=%s", []byte("plaintext-message"))
-
-	if strings.Contains(lines[0], "plaintext-message") {
-		t.Fatalf("log line leaked a byte payload: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerHidesErrorText(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	// Vendor error strings can embed a response body preview.
-	logger.Error("request failed: %v", errors.New(`server said {"key":"LEAKED"}`))
-
-	if strings.Contains(lines[0], "LEAKED") {
-		t.Fatalf("log line leaked error contents: %q", lines[0])
-	}
-}
-
-func TestRedactingLoggerKeepsDiagnosticNumbers(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Debug("Status: %d (took %s), size=%d", 503, 1500*time.Millisecond, 4096)
-
-	line := lines[0]
-	for _, want := range []string{"503", "1.5s", "4096"} {
-		if !strings.Contains(line, want) {
-			t.Fatalf("log line = %q, want it to keep %q for diagnostics", line, want)
-		}
-	}
-}
-
-func TestRedactingLoggerLabelsLevel(t *testing.T) {
-	var lines []string
-	logger := newRedactingLogger(captureLogf(&lines))
-
-	logger.Debug("d")
-	logger.Info("i")
-	logger.Error("e")
-
-	if len(lines) != 3 {
-		t.Fatalf("got %d lines, want 3", len(lines))
-	}
-	for i, want := range []string{"debug", "info", "error"} {
-		if !strings.Contains(lines[i], want) {
-			t.Fatalf("line %d = %q, want level %q", i, lines[i], want)
-		}
-	}
-}
-
-func TestRedactingLoggerToleratesNilSinkAtEmit(t *testing.T) {
-	// Guard against a partially constructed logger being used.
-	var logger *redactingLogger
-	logger.Debug("must not panic %s", "value")
-}
-
-func TestRedactArgKeepsDurations(t *testing.T) {
-	if got := redactArg(2 * time.Second); got != "2s" {
-		t.Fatalf("redactArg(2s) = %v, want 2s", got)
-	}
-}
-
-func TestRedactArgElidesStrings(t *testing.T) {
-	got, ok := redactArg("secret").(string)
-	if !ok {
-		t.Fatalf("redactArg returned %T, want string", got)
-	}
-	if strings.Contains(got, "secret") {
-		t.Fatalf("redactArg = %q, want the value elided", got)
-	}
-	if !strings.Contains(got, "len=6") {
-		t.Fatalf("redactArg = %q, want the length preserved", got)
-	}
-}
-
-func TestRedactArgPassesThroughNumbers(t *testing.T) {
-	if got := redactArg(42); got != 42 {
-		t.Fatalf("redactArg(42) = %v, want 42", got)
-	}
-	if got := redactArg(true); got != true {
-		t.Fatalf("redactArg(true) = %v, want true", got)
-	}
-}

internal/msgcrypto/msgcrypto.go

@@ -1,297 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-// Package msgcrypto wraps the third-party SafeChat SDK so DWS can decrypt
-// DingTalk messages that an organization has encrypted with its own key
-// material, and encrypt outbound ones.
-//
-// The SafeChat backend links a prebuilt C static library and therefore needs
-// CGO. Because DWS ships CGO-free cross-compiled release binaries, the backend
-// is compiled only under the "safechat" build tag:
-//
-//	CGO_ENABLED=1 go build -tags safechat ./cmd
-//
-// Every other build gets a stub whose constructor fails with ErrUnavailable,
-// so callers must always handle that error rather than assume the capability
-// exists. Use Available to branch before offering the feature to a user.
-//
-// Key material is fetched from the vendor key server on demand, which requires
-// a DingTalk 免登 authCode supplied through AuthCodeProvider. DWS does not mint
-// that code itself; the caller injects a provider.
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"sync"
-	"time"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/pkg/config"
-)
-
-// Errors reported by this package. Callers are expected to test for
-// ErrUnavailable explicitly, because it is the normal outcome on every build
-// that does not enable the safechat tag.
-var (
-	// ErrUnavailable means this binary was built without the SafeChat
-	// backend, or for a platform the vendor does not ship a static library
-	// for (notably windows/arm64).
-	ErrUnavailable = errors.New("msgcrypto: SafeChat backend not built into this binary")
-
-	// ErrAlreadyOpen means a Cipher is already open. The underlying C
-	// library keeps global state, so only one may exist per process.
-	ErrAlreadyOpen = errors.New("msgcrypto: a cipher is already open in this process")
-
-	// ErrClosed is returned by a Cipher whose Close has already run.
-	ErrClosed = errors.New("msgcrypto: cipher is closed")
-
-	// ErrNoAuthCodeProvider means Config.AuthCode was nil. Without it the
-	// backend cannot fetch or rotate key material.
-	ErrNoAuthCodeProvider = errors.New("msgcrypto: config.AuthCode is required")
-
-	// ErrEmptyPayload means an encrypt or decrypt call got no bytes. The
-	// vendor SDK rejects empty input, so we reject it earlier with a
-	// clearer message.
-	ErrEmptyPayload = errors.New("msgcrypto: payload is empty")
-
-	// ErrNoCorpID means the caller omitted the organization id, which
-	// selects the key and therefore cannot be defaulted.
-	ErrNoCorpID = errors.New("msgcrypto: corpID is required")
-
-	// ErrNoKeyServer means Config.KeyServer was empty. The vendor C
-	// library would otherwise pick the key-request destination.
-	ErrNoKeyServer = errors.New("msgcrypto: config.KeyServer is required")
-
-	// ErrInvalidKeyServer means Config.KeyServer is not a usable URL.
-	ErrInvalidKeyServer = errors.New("msgcrypto: config.KeyServer is not a valid URL")
-
-	// ErrKeyServerNotHTTPS means Config.KeyServer is not https.
-	ErrKeyServerNotHTTPS = errors.New("msgcrypto: config.KeyServer must be an https URL")
-
-	// ErrRedirectHostMismatch means the domain goProxy received does not
-	// match Config.AllowedRedirectHost. The domain is never sent to portal.
-	ErrRedirectHostMismatch = errors.New("msgcrypto: goProxy domain host does not match AllowedRedirectHost")
-)
-
-// keystoreDirPerm keeps the key cache owner-only. The directory holds
-// organization key material, so it must not be group- or world-readable.
-const keystoreDirPerm fs.FileMode = 0o700
-
-// DefaultKeystoreDir returns the default key cache directory,
-// ~/.dws/safechat/keystore, honouring DWS_CONFIG_DIR like the rest of DWS.
-func DefaultKeystoreDir() string {
-	return filepath.Join(config.DefaultConfigDir(), "safechat", "keystore")
-}
-
-// Cipher encrypts and decrypts message payloads for one organization at a
-// time. Implementations are safe for concurrent use.
-type Cipher interface {
-	// EncryptMessage encrypts plaintext for corpID/staffID and returns the
-	// vendor ciphertext envelope.
-	EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error)
-
-	// DecryptMessage decrypts a vendor ciphertext envelope.
-	DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error)
-
-	// Close releases the backend and frees the process-wide slot so a later
-	// Open can succeed. Calling it twice is safe.
-	Close() error
-}
-
-// Config parameterises Open.
-type Config struct {
-	// KeystoreDir is where fetched keys are cached. Defaults to
-	// DefaultKeystoreDir. It is created with 0700 if missing.
-	KeystoreDir string
-
-	// UserID is an opaque local identifier. The vendor SDK stores it but
-	// does not use it for key selection; leave empty to let the SDK
-	// generate one.
-	UserID string
-
-	// AuthCode supplies the DingTalk 免登 authCode used to authenticate key
-	// requests. Required. The backend calls it only from the vendor goProxy
-	// callback (cold keystore or key-version rotation), never on every
-	// encrypt/decrypt.
-	AuthCode AuthCodeProvider
-
-	// KeyServer is the HTTPS URL of the vendor key service. Required: it
-	// replaces the host the closed-source C library would otherwise pick.
-	KeyServer string
-
-	// AllowedRedirectHost, when set, is compared to the domain the C
-	// library passes into goProxy. A mismatch fails that key fetch. It is
-	// a local check only; the domain is never sent to portal.
-	AllowedRedirectHost string
-
-	// MaxRetry bounds retries while a key is still being fetched. Zero
-	// selects the vendor default.
-	MaxRetry int
-
-	// HTTPTimeout bounds each key request. Zero selects the vendor default.
-	HTTPTimeout time.Duration
-
-	// Debug enables backend logging through a redacting logger. Off by
-	// default because the vendor SDK logs the authCode and raw key-server
-	// responses at debug level.
-	Debug bool
-
-	// Logf receives already-redacted backend log lines when Debug is set.
-	// Nil discards them.
-	Logf func(format string, args ...any)
-}
-
-// withDefaults returns cfg with empty optional fields filled in.
-func (cfg Config) withDefaults() Config {
-	if cfg.KeystoreDir == "" {
-		cfg.KeystoreDir = DefaultKeystoreDir()
-	}
-	return cfg
-}
-
-// validate reports whether cfg carries everything the backend needs.
-func (cfg Config) validate() error {
-	if cfg.AuthCode == nil {
-		return ErrNoAuthCodeProvider
-	}
-	if cfg.KeystoreDir == "" {
-		return errors.New("msgcrypto: config.KeystoreDir resolved to an empty path")
-	}
-	if err := validateKeyServer(cfg.KeyServer); err != nil {
-		return err
-	}
-	return nil
-}
-
-// prepareKeystore creates dir if needed and makes sure it is owner-only.
-// An existing directory with looser bits is tightened, because it caches key
-// material.
-func prepareKeystore(dir string) error {
-	if err := os.MkdirAll(dir, keystoreDirPerm); err != nil {
-		return fmt.Errorf("msgcrypto: create keystore dir: %w", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		return fmt.Errorf("msgcrypto: stat keystore dir: %w", err)
-	}
-	if !info.IsDir() {
-		return fmt.Errorf("msgcrypto: keystore path %s is not a directory", dir)
-	}
-	// Windows does not model POSIX bits, so only tighten where they apply.
-	if runtimeSupportsPOSIXPerm && info.Mode().Perm() != keystoreDirPerm {
-		if err := os.Chmod(dir, keystoreDirPerm); err != nil {
-			return fmt.Errorf("msgcrypto: restrict keystore dir permissions: %w", err)
-		}
-	}
-	return nil
-}
-
-// process holds the single-instance guard. The vendor C library keeps global
-// state, so a second concurrent Cipher would corrupt it.
-var process struct {
-	mu   sync.Mutex
-	open bool
-}
-
-// Open validates cfg, prepares the keystore and starts the backend.
-//
-// It returns ErrUnavailable when the backend was not compiled in, so callers
-// can degrade gracefully. Only one Cipher may be open per process; Close frees
-// the slot.
-func Open(ctx context.Context, cfg Config) (Cipher, error) {
-	cfg = cfg.withDefaults()
-	if err := cfg.validate(); err != nil {
-		return nil, err
-	}
-	if !Available() {
-		return nil, ErrUnavailable
-	}
-	if err := prepareKeystore(cfg.KeystoreDir); err != nil {
-		return nil, err
-	}
-
-	process.mu.Lock()
-	defer process.mu.Unlock()
-	if process.open {
-		return nil, ErrAlreadyOpen
-	}
-	backend, err := newBackend(ctx, cfg)
-	if err != nil {
-		return nil, err
-	}
-	process.open = true
-	return &trackedCipher{backend: backend}, nil
-}
-
-// trackedCipher releases the process-wide slot when the wrapped backend closes.
-type trackedCipher struct {
-	mu      sync.Mutex
-	backend Cipher
-}
-
-// EncryptMessage validates the payload and delegates to the backend.
-func (c *trackedCipher) EncryptMessage(ctx context.Context, corpID, staffID string, plaintext []byte) ([]byte, error) {
-	backend, err := c.live(corpID, plaintext)
-	if err != nil {
-		return nil, err
-	}
-	return backend.EncryptMessage(ctx, corpID, staffID, plaintext)
-}
-
-// DecryptMessage validates the payload and delegates to the backend.
-func (c *trackedCipher) DecryptMessage(ctx context.Context, corpID, staffID string, ciphertext []byte) ([]byte, error) {
-	backend, err := c.live(corpID, ciphertext)
-	if err != nil {
-		return nil, err
-	}
-	return backend.DecryptMessage(ctx, corpID, staffID, ciphertext)
-}
-
-// live returns the backend after checking the cipher is open and the arguments
-// are usable.
-func (c *trackedCipher) live(corpID string, payload []byte) (Cipher, error) {
-	if corpID == "" {
-		return nil, ErrNoCorpID
-	}
-	if len(payload) == 0 {
-		return nil, ErrEmptyPayload
-	}
-	c.mu.Lock()
-	defer c.mu.Unlock()
-	if c.backend == nil {
-		return nil, ErrClosed
-	}
-	return c.backend, nil
-}
-
-// Close closes the backend once and releases the process-wide slot.
-func (c *trackedCipher) Close() error {
-	c.mu.Lock()
-	backend := c.backend
-	c.backend = nil
-	c.mu.Unlock()
-	if backend == nil {
-		return nil
-	}
-
-	err := backend.Close()
-
-	process.mu.Lock()
-	process.open = false
-	process.mu.Unlock()
-	return err
-}

internal/msgcrypto/msgcrypto_test.go

@@ -1,345 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"io/fs"
-	"os"
-	"path/filepath"
-	"runtime"
-	"strings"
-	"sync"
-	"testing"
-)
-
-// fakeCipher stands in for a backend so the wrapper logic can be tested on
-// every platform, with or without the safechat tag.
-type fakeCipher struct {
-	mu         sync.Mutex
-	encrypted  [][]byte
-	decrypted  [][]byte
-	closeCount int
-	closeErr   error
-}
-
-func (f *fakeCipher) EncryptMessage(_ context.Context, _, _ string, plaintext []byte) ([]byte, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.encrypted = append(f.encrypted, plaintext)
-	return []byte("cipher:" + string(plaintext)), nil
-}
-
-func (f *fakeCipher) DecryptMessage(_ context.Context, _, _ string, ciphertext []byte) ([]byte, error) {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.decrypted = append(f.decrypted, ciphertext)
-	return []byte(strings.TrimPrefix(string(ciphertext), "cipher:")), nil
-}
-
-func (f *fakeCipher) Close() error {
-	f.mu.Lock()
-	defer f.mu.Unlock()
-	f.closeCount++
-	return f.closeErr
-}
-
-// newTrackedForTest wraps backend and claims the process slot the same way
-// Open does, so slot release can be asserted.
-func newTrackedForTest(t *testing.T, backend Cipher) *trackedCipher {
-	t.Helper()
-	process.mu.Lock()
-	process.open = true
-	process.mu.Unlock()
-	t.Cleanup(func() {
-		process.mu.Lock()
-		process.open = false
-		process.mu.Unlock()
-	})
-	return &trackedCipher{backend: backend}
-}
-
-func TestConfigWithDefaultsFillsKeystoreDir(t *testing.T) {
-	cfg := Config{}.withDefaults()
-	if cfg.KeystoreDir == "" {
-		t.Fatal("withDefaults left KeystoreDir empty")
-	}
-	if want := DefaultKeystoreDir(); cfg.KeystoreDir != want {
-		t.Fatalf("KeystoreDir = %q, want %q", cfg.KeystoreDir, want)
-	}
-}
-
-func TestConfigWithDefaultsKeepsExplicitKeystoreDir(t *testing.T) {
-	cfg := Config{KeystoreDir: "/custom/keys"}.withDefaults()
-	if cfg.KeystoreDir != "/custom/keys" {
-		t.Fatalf("KeystoreDir = %q, want /custom/keys", cfg.KeystoreDir)
-	}
-}
-
-func TestDefaultKeystoreDirHonoursConfigDirOverride(t *testing.T) {
-	t.Setenv("DWS_CONFIG_DIR", t.TempDir())
-	got := DefaultKeystoreDir()
-	if !strings.HasSuffix(got, filepath.Join("safechat", "keystore")) {
-		t.Fatalf("DefaultKeystoreDir() = %q, want it to end with safechat/keystore", got)
-	}
-	if !strings.HasPrefix(got, os.Getenv("DWS_CONFIG_DIR")) {
-		t.Fatalf("DefaultKeystoreDir() = %q, want it under DWS_CONFIG_DIR", got)
-	}
-}
-
-func TestConfigValidateRequiresAuthCodeProvider(t *testing.T) {
-	err := Config{KeystoreDir: "/tmp/keys"}.validate()
-	if !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("validate() = %v, want ErrNoAuthCodeProvider", err)
-	}
-}
-
-func TestConfigValidateAcceptsCompleteConfig(t *testing.T) {
-	cfg := Config{
-		KeystoreDir: "/tmp/keys",
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	}
-	if err := cfg.validate(); err != nil {
-		t.Fatalf("validate() = %v, want nil", err)
-	}
-}
-
-func TestConfigValidateRequiresKeyServer(t *testing.T) {
-	err := Config{KeystoreDir: "/tmp/keys", AuthCode: StaticAuthCode("code")}.validate()
-	if !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("validate() = %v, want ErrNoKeyServer", err)
-	}
-}
-
-func TestConfigValidateRejectsHTTPKeyServer(t *testing.T) {
-	err := Config{
-		KeystoreDir: "/tmp/keys",
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "http://key.example.test",
-	}.validate()
-	if !errors.Is(err, ErrKeyServerNotHTTPS) {
-		t.Fatalf("validate() = %v, want ErrKeyServerNotHTTPS", err)
-	}
-}
-
-func TestPrepareKeystoreCreatesOwnerOnlyDir(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "nested", "keystore")
-	if err := prepareKeystore(dir); err != nil {
-		t.Fatalf("prepareKeystore() = %v", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		t.Fatalf("stat: %v", err)
-	}
-	if !info.IsDir() {
-		t.Fatal("prepareKeystore did not create a directory")
-	}
-	if runtime.GOOS == "windows" {
-		return
-	}
-	if got := info.Mode().Perm(); got != keystoreDirPerm {
-		t.Fatalf("perm = %#o, want %#o", got, keystoreDirPerm)
-	}
-}
-
-func TestPrepareKeystoreTightensLoosePermissions(t *testing.T) {
-	if runtime.GOOS == "windows" {
-		t.Skip("POSIX permission bits are not modelled on Windows")
-	}
-	dir := filepath.Join(t.TempDir(), "keystore")
-	if err := os.MkdirAll(dir, fs.FileMode(0o755)); err != nil {
-		t.Fatalf("mkdir: %v", err)
-	}
-	if err := prepareKeystore(dir); err != nil {
-		t.Fatalf("prepareKeystore() = %v", err)
-	}
-	info, err := os.Stat(dir)
-	if err != nil {
-		t.Fatalf("stat: %v", err)
-	}
-	if got := info.Mode().Perm(); got != keystoreDirPerm {
-		t.Fatalf("perm = %#o, want %#o (key material must stay owner-only)", got, keystoreDirPerm)
-	}
-}
-
-func TestPrepareKeystoreRejectsFilePath(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "keystore")
-	if err := os.WriteFile(path, []byte("not a dir"), 0o600); err != nil {
-		t.Fatalf("write: %v", err)
-	}
-	err := prepareKeystore(path)
-	if err == nil {
-		t.Fatal("prepareKeystore() = nil, want an error for a non-directory path")
-	}
-}
-
-func TestOpenRejectsMissingAuthCodeProviderBeforeTouchingDisk(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	_, err := Open(context.Background(), Config{KeystoreDir: dir})
-	if !errors.Is(err, ErrNoAuthCodeProvider) {
-		t.Fatalf("Open() = %v, want ErrNoAuthCodeProvider", err)
-	}
-	if _, statErr := os.Stat(dir); !os.IsNotExist(statErr) {
-		t.Fatal("Open created the keystore dir despite an invalid config")
-	}
-}
-
-func TestOpenRejectsMissingKeyServerBeforeTouchingDisk(t *testing.T) {
-	dir := filepath.Join(t.TempDir(), "keystore")
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: dir,
-		AuthCode:    StaticAuthCode("code"),
-	})
-	if !errors.Is(err, ErrNoKeyServer) {
-		t.Fatalf("Open() = %v, want ErrNoKeyServer", err)
-	}
-	if _, statErr := os.Stat(dir); !os.IsNotExist(statErr) {
-		t.Fatal("Open created the keystore dir despite a missing KeyServer")
-	}
-}
-
-func TestOpenWithoutBackendReportsUnavailable(t *testing.T) {
-	if Available() {
-		t.Skip("this binary has the safechat backend compiled in")
-	}
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrUnavailable) {
-		t.Fatalf("Open() = %v, want ErrUnavailable", err)
-	}
-}
-
-func TestAvailableAgreesWithBackendVersion(t *testing.T) {
-	if Available() != (BackendVersion != "") {
-		t.Fatalf("Available() = %v but BackendVersion = %q; they must agree", Available(), BackendVersion)
-	}
-}
-
-func TestTrackedCipherRoundTripsThroughBackend(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-
-	ciphertext, err := cipher.EncryptMessage(context.Background(), "corp", "staff", []byte("hello"))
-	if err != nil {
-		t.Fatalf("EncryptMessage() = %v", err)
-	}
-	plaintext, err := cipher.DecryptMessage(context.Background(), "corp", "staff", ciphertext)
-	if err != nil {
-		t.Fatalf("DecryptMessage() = %v", err)
-	}
-	if string(plaintext) != "hello" {
-		t.Fatalf("round trip = %q, want hello", plaintext)
-	}
-}
-
-func TestTrackedCipherRejectsEmptyCorpID(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if _, err := cipher.EncryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("EncryptMessage() = %v, want ErrNoCorpID", err)
-	}
-	if _, err := cipher.DecryptMessage(context.Background(), "", "staff", []byte("x")); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("DecryptMessage() = %v, want ErrNoCorpID", err)
-	}
-}
-
-func TestTrackedCipherRejectsEmptyPayload(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if _, err := cipher.EncryptMessage(context.Background(), "corp", "staff", nil); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("EncryptMessage() = %v, want ErrEmptyPayload", err)
-	}
-	if _, err := cipher.DecryptMessage(context.Background(), "corp", "staff", []byte{}); !errors.Is(err, ErrEmptyPayload) {
-		t.Fatalf("DecryptMessage() = %v, want ErrEmptyPayload", err)
-	}
-}
-
-func TestTrackedCipherRejectsUseAfterClose(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-	if _, err := cipher.EncryptMessage(context.Background(), "corp", "staff", []byte("x")); !errors.Is(err, ErrClosed) {
-		t.Fatalf("EncryptMessage() after Close = %v, want ErrClosed", err)
-	}
-}
-
-func TestTrackedCipherCloseIsIdempotentAndClosesBackendOnce(t *testing.T) {
-	backend := &fakeCipher{}
-	cipher := newTrackedForTest(t, backend)
-	for i := 0; i < 3; i++ {
-		if err := cipher.Close(); err != nil {
-			t.Fatalf("Close() #%d = %v", i+1, err)
-		}
-	}
-	if backend.closeCount != 1 {
-		t.Fatalf("backend Close called %d times, want exactly 1", backend.closeCount)
-	}
-}
-
-func TestTrackedCipherCloseReleasesProcessSlot(t *testing.T) {
-	cipher := newTrackedForTest(t, &fakeCipher{})
-	if err := cipher.Close(); err != nil {
-		t.Fatalf("Close() = %v", err)
-	}
-	process.mu.Lock()
-	open := process.open
-	process.mu.Unlock()
-	if open {
-		t.Fatal("Close did not release the process slot, so a later Open would fail")
-	}
-}
-
-func TestTrackedCipherClosePropagatesBackendError(t *testing.T) {
-	wantErr := errors.New("backend close failed")
-	cipher := newTrackedForTest(t, &fakeCipher{closeErr: wantErr})
-	if err := cipher.Close(); !errors.Is(err, wantErr) {
-		t.Fatalf("Close() = %v, want %v", err, wantErr)
-	}
-	process.mu.Lock()
-	open := process.open
-	process.mu.Unlock()
-	if open {
-		t.Fatal("a failing backend Close must still release the process slot")
-	}
-}
-
-func TestOpenRefusesSecondCipherWhileOneIsOpen(t *testing.T) {
-	// The vendor C library keeps global state, so a second concurrent
-	// cipher must be refused rather than silently corrupt it.
-	process.mu.Lock()
-	process.open = true
-	process.mu.Unlock()
-	t.Cleanup(func() {
-		process.mu.Lock()
-		process.open = false
-		process.mu.Unlock()
-	})
-
-	if !Available() {
-		t.Skip("Open reports ErrUnavailable before reaching the single-instance guard")
-	}
-	_, err := Open(context.Background(), Config{
-		KeystoreDir: filepath.Join(t.TempDir(), "keystore"),
-		AuthCode:    StaticAuthCode("code"),
-		KeyServer:   "https://key.example.test",
-	})
-	if !errors.Is(err, ErrAlreadyOpen) {
-		t.Fatalf("Open() = %v, want ErrAlreadyOpen", err)
-	}
-}

internal/msgcrypto/perm_posix.go

@@ -1,20 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-//go:build !windows
-
-package msgcrypto
-
-// runtimeSupportsPOSIXPerm reports that the keystore directory's permission
-// bits are meaningful here, so prepareKeystore enforces owner-only access.
-const runtimeSupportsPOSIXPerm = true

internal/msgcrypto/perm_windows.go

@@ -1,21 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-//go:build windows
-
-package msgcrypto
-
-// runtimeSupportsPOSIXPerm reports that Windows does not model POSIX
-// permission bits, so prepareKeystore leaves the directory mode alone and
-// relies on the user profile ACL instead.
-const runtimeSupportsPOSIXPerm = false

internal/msgcrypto/portal_authcode.go

@@ -1,170 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"net/http"
-	"strings"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-)
-
-// VendorSafeChat is the first vendorAuthCode vendor.
-const VendorSafeChat = "safechat"
-
-// PortalAuthCode mints a one-shot 免登 authCode from portal
-// POST /oauth2/vendorAuthCode. It does not cache the code: goProxy spends it
-// immediately. Do not wrap this in CachedAuthCode.
-type PortalAuthCode struct {
-	ConfigDir  string
-	Vendor     string
-	CLIVersion string
-	HTTPClient *http.Client
-
-	clientID func() string
-	snapshot func(ctx context.Context, configDir string) (*auth.TokenData, error)
-	refresh  func(ctx context.Context, configDir, rejected string) (string, error)
-	fetch    func(ctx context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error)
-}
-
-// NewPortalAuthCode returns a provider that talks to portal with the current
-// login. cliVersion is sent as x-dws-cli-version; leave empty only when the
-// caller cannot know the CLI version.
-func NewPortalAuthCode(configDir, cliVersion string) *PortalAuthCode {
-	return &PortalAuthCode{
-		ConfigDir:  configDir,
-		Vendor:     VendorSafeChat,
-		CLIVersion: cliVersion,
-		clientID:   auth.ClientID,
-		snapshot: func(ctx context.Context, dir string) (*auth.TokenData, error) {
-			return auth.NewOAuthProvider(dir, nil).GetTokenSnapshot(ctx)
-		},
-		refresh: func(ctx context.Context, dir, rejected string) (string, error) {
-			return auth.NewOAuthProvider(dir, nil).ForceRefreshRejectedToken(ctx, rejected)
-		},
-		fetch: auth.FetchVendorAuthCode,
-	}
-}
-
-// AuthCode mints a code for the logged-in organization. Prefer AuthCodeForCorp
-// when goProxy already has a corpID.
-func (p *PortalAuthCode) AuthCode(ctx context.Context) (string, error) {
-	snap, err := p.loadSnapshot(ctx)
-	if err != nil {
-		return "", err
-	}
-	return p.AuthCodeForCorp(ctx, snap.CorpID)
-}
-
-// AuthCodeForCorp mints a one-shot code for corpID. The request body is only
-// vendor + corpId.
-func (p *PortalAuthCode) AuthCodeForCorp(ctx context.Context, corpID string) (string, error) {
-	corpID = strings.TrimSpace(corpID)
-	if corpID == "" {
-		return "", ErrNoCorpID
-	}
-	snap, err := p.loadSnapshot(ctx)
-	if err != nil {
-		return "", err
-	}
-	token := strings.TrimSpace(snap.AccessToken)
-	if token == "" {
-		return "", fmt.Errorf("msgcrypto: access token is empty")
-	}
-
-	result, err := p.fetchOnce(ctx, snap, token, corpID)
-	if err == nil {
-		return result.AuthCode, nil
-	}
-
-	var verr *auth.VendorAuthCodeError
-	if errors.As(err, &verr) && verr.Code == auth.VendorAuthCodeTokenInvalid {
-		refreshed, rerr := p.doRefresh(ctx, token)
-		if rerr == nil && refreshed != "" && refreshed != token {
-			result, err = p.fetchOnce(ctx, snap, refreshed, corpID)
-			if err == nil {
-				return result.AuthCode, nil
-			}
-		}
-		return "", err
-	}
-	if retryableVendorAuthCode(err) {
-		result, err = p.fetchOnce(ctx, snap, token, corpID)
-		if err == nil {
-			return result.AuthCode, nil
-		}
-	}
-	return "", err
-}
-
-func (p *PortalAuthCode) loadSnapshot(ctx context.Context) (*auth.TokenData, error) {
-	if p.snapshot == nil {
-		return nil, fmt.Errorf("msgcrypto: portal authCode snapshot loader is not configured")
-	}
-	snap, err := p.snapshot(ctx, p.ConfigDir)
-	if err != nil {
-		return nil, fmt.Errorf("msgcrypto: load access token: %w", err)
-	}
-	if snap == nil {
-		return nil, fmt.Errorf("msgcrypto: load access token: empty snapshot")
-	}
-	return snap, nil
-}
-
-func (p *PortalAuthCode) fetchOnce(ctx context.Context, snap *auth.TokenData, token, corpID string) (*auth.VendorAuthCodeResult, error) {
-	fetch := p.fetch
-	if fetch == nil {
-		fetch = auth.FetchVendorAuthCode
-	}
-	vendor := strings.TrimSpace(p.Vendor)
-	if vendor == "" {
-		vendor = VendorSafeChat
-	}
-	clientID := strings.TrimSpace(snap.ClientID)
-	if clientID == "" && p.clientID != nil {
-		clientID = strings.TrimSpace(p.clientID())
-	}
-	return fetch(ctx, auth.VendorAuthCodeInput{
-		AccessToken: token,
-		ClientID:    clientID,
-		CLIVersion:  p.CLIVersion,
-		LoginRegion: auth.LoginRegion(strings.TrimSpace(snap.LoginRegion)),
-		Vendor:      vendor,
-		CorpID:      corpID,
-		HTTPClient:  p.HTTPClient,
-	})
-}
-
-func (p *PortalAuthCode) doRefresh(ctx context.Context, rejected string) (string, error) {
-	if p.refresh == nil {
-		return "", fmt.Errorf("msgcrypto: token refresh is not configured")
-	}
-	return p.refresh(ctx, p.ConfigDir, rejected)
-}
-
-func retryableVendorAuthCode(err error) bool {
-	var verr *auth.VendorAuthCodeError
-	if errors.As(err, &verr) {
-		return verr.Retryable()
-	}
-	var statusErr *auth.HTTPStatusError
-	if errors.As(err, &statusErr) && statusErr != nil {
-		return statusErr.StatusCode == http.StatusTooManyRequests ||
-			statusErr.StatusCode >= http.StatusInternalServerError
-	}
-	return false
-}

internal/msgcrypto/portal_authcode_test.go

@@ -1,121 +0,0 @@
-// Copyright 2026 Alibaba Group
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-
-package msgcrypto
-
-import (
-	"context"
-	"errors"
-	"sync/atomic"
-	"testing"
-
-	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/auth"
-)
-
-func TestPortalAuthCodePostsVendorAndCorpOnly(t *testing.T) {
-	var got auth.VendorAuthCodeInput
-	p := &PortalAuthCode{
-		ConfigDir:  t.TempDir(),
-		Vendor:     VendorSafeChat,
-		CLIVersion: "1.2.3",
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{
-				AccessToken: "user-token",
-				ClientID:    "dws-client",
-				CorpID:      "ding_login",
-				LoginRegion: "",
-			}, nil
-		},
-		fetch: func(_ context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			got = in
-			return &auth.VendorAuthCodeResult{AuthCode: "tmp-code", ExpiresIn: 120}, nil
-		},
-	}
-
-	code, err := p.AuthCodeForCorp(context.Background(), "ding_target")
-	if err != nil || code != "tmp-code" {
-		t.Fatalf("AuthCodeForCorp() = %q, %v", code, err)
-	}
-	if got.Vendor != VendorSafeChat || got.CorpID != "ding_target" {
-		t.Fatalf("body vendor/corpId = %q/%q", got.Vendor, got.CorpID)
-	}
-	if got.AccessToken != "user-token" || got.ClientID != "dws-client" || got.CLIVersion != "1.2.3" {
-		t.Fatalf("headers token/client/version = %q/%q/%q", got.AccessToken, got.ClientID, got.CLIVersion)
-	}
-}
-
-func TestPortalAuthCodeRetriesOnceOnTokenInvalidAfterRefresh(t *testing.T) {
-	var calls atomic.Int32
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "stale", ClientID: "dws-client", CorpID: "ding"}, nil
-		},
-		refresh: func(context.Context, string, string) (string, error) {
-			return "fresh", nil
-		},
-		fetch: func(_ context.Context, in auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			n := calls.Add(1)
-			if in.AccessToken == "stale" {
-				return nil, &auth.VendorAuthCodeError{Code: auth.VendorAuthCodeTokenInvalid, Message: "expired"}
-			}
-			if in.AccessToken != "fresh" {
-				t.Fatalf("retry token = %q, want fresh", in.AccessToken)
-			}
-			if n != 2 {
-				t.Fatalf("fetch calls = %d, want 2", n)
-			}
-			return &auth.VendorAuthCodeResult{AuthCode: "new-code", ExpiresIn: 120}, nil
-		},
-	}
-
-	code, err := p.AuthCodeForCorp(context.Background(), "ding")
-	if err != nil || code != "new-code" {
-		t.Fatalf("AuthCodeForCorp() = %q, %v", code, err)
-	}
-	if calls.Load() != 2 {
-		t.Fatalf("fetch called %d times, want 2", calls.Load())
-	}
-}
-
-func TestPortalAuthCodeDoesNotRetryOrgMismatch(t *testing.T) {
-	var calls atomic.Int32
-	want := &auth.VendorAuthCodeError{Code: auth.VendorAuthCodeOrgMismatch, Message: "mismatch"}
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "tok", ClientID: "dws-client", CorpID: "ding"}, nil
-		},
-		fetch: func(context.Context, auth.VendorAuthCodeInput) (*auth.VendorAuthCodeResult, error) {
-			calls.Add(1)
-			return nil, want
-		},
-	}
-
-	_, err := p.AuthCodeForCorp(context.Background(), "other")
-	if !errors.Is(err, want) {
-		t.Fatalf("AuthCodeForCorp() = %v, want %v", err, want)
-	}
-	if calls.Load() != 1 {
-		t.Fatalf("fetch called %d times, want 1", calls.Load())
-	}
-}
-
-func TestPortalAuthCodeRequiresCorpID(t *testing.T) {
-	p := &PortalAuthCode{
-		snapshot: func(context.Context, string) (*auth.TokenData, error) {
-			return &auth.TokenData{AccessToken: "tok", ClientID: "id"}, nil
-		},
-	}
-	if _, err := p.AuthCodeForCorp(context.Background(), "  "); !errors.Is(err, ErrNoCorpID) {
-		t.Fatalf("AuthCodeForCorp() = %v, want ErrNoCorpID", err)
-	}
-}

internal/shortcut/chat/coverage_completion_test.go

@@ -437,7 +437,7 @@ func TestCrossPlatformCoverageUnifiedSendOptionalArgumentsAndErrors(t *testing.T
 	}{
 		{
 			name: "user group mentions",
-			args: []string{"--identity", "user", "--group", "cid", "--text", "x", "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2, "--at-all"},
+			args: []string{"--identity", "user", "--group", "cid", "--text", "@" + fixtureCurrentDOpenID + " <@" + fixtureCurrentDOpenID2 + "> x", "--at-open-dingtalk-ids", fixtureCurrentDOpenID + "," + fixtureCurrentDOpenID2, "--at-all"},
 			want: map[string]any{"atOpenDingTalkIds": []string{fixtureCurrentDOpenID, fixtureCurrentDOpenID2}, "atAll": true},
 		},
 		{
@@ -505,6 +505,69 @@ func TestCrossPlatformCoverageUnifiedSendOptionalArgumentsAndErrors(t *testing.T
 	}
 }
 
+func TestCrossPlatformCoverageMessagesSendRejectsMismatchedCurrentUserMentions(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    string
+		atIDs   string
+		atAll   bool
+		wantErr string
+	}{
+		{
+			name:    "declared member missing from body",
+			body:    "请查收",
+			atIDs:   fixtureCurrentDOpenID,
+			wantErr: "必须在正文中使用对应",
+		},
+		{
+			name:    "declared member only appears as a longer token prefix",
+			body:    "@" + fixtureCurrentDOpenID + "_suffix 请查收",
+			atIDs:   fixtureCurrentDOpenID,
+			wantErr: "必须在正文中使用对应",
+		},
+		{
+			name:    "body member missing from declaration",
+			body:    "<@" + fixtureCurrentDOpenID + "> 请查收",
+			wantErr: "必须同时通过 --at-open-dingtalk-ids 声明",
+		},
+		{
+			name:    "body at-all missing from declaration",
+			body:    "<@all> 请查收",
+			wantErr: "必须同时指定 --at-all",
+		},
+		{
+			name:    "bare body member missing from declaration",
+			body:    "@" + fixtureCurrentDOpenID + " 请查收",
+			wantErr: "必须同时通过 --at-open-dingtalk-ids 声明",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fake := &larkAlignmentCaller{}
+			helpers.InitDeps(fake)
+			root := newPlatformCoverageRoot()
+			args := []string{
+				"chat", "+messages-send", "--identity", "user",
+				"--group", "cid", "--markdown", tt.body, "--yes",
+			}
+			if tt.atIDs != "" {
+				args = append(args, "--at-open-dingtalk-ids", tt.atIDs)
+			}
+			if tt.atAll {
+				args = append(args, "--at-all")
+			}
+			root.SetArgs(args)
+			err := root.Execute()
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Fatalf("error = %v, want %q", err, tt.wantErr)
+			}
+			if len(fake.calls) != 0 {
+				t.Fatalf("invalid mention contract reached lower service: %#v", fake.calls)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageUnifiedSendUnsupportedIdentityGuard(t *testing.T) {
 	flags := append([]shortcut.Flag(nil), MessagesSend.Flags...)
 	for i := range flags {

internal/shortcut/chat/gap_fill_test.go

@@ -585,6 +585,119 @@ func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileFlow(t *testing.T)
 	}
 }
 
+func TestCrossPlatformCoverageMessagesSendCurrentUserDirectLocalFileUsesTransportSpecificTargets(t *testing.T) {
+	t.Chdir(t.TempDir())
+	if err := os.WriteFile("direct.bin", []byte("direct-file"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	uploadServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPut {
+			t.Errorf("upload method = %s", r.Method)
+		}
+		if _, err := io.Copy(io.Discard, r.Body); err != nil {
+			t.Error(err)
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+	t.Cleanup(uploadServer.Close)
+
+	tests := []struct {
+		name            string
+		targetArgs      []string
+		requestedType   string
+		wantOpenID      string
+		wantUserResolve bool
+	}{
+		{
+			name:          "explicit open id file",
+			targetArgs:    []string{"--open-dingtalk-id", fixtureCurrentDOpenID},
+			requestedType: "file",
+			wantOpenID:    fixtureCurrentDOpenID,
+		},
+		{
+			name:            "resolved user audio",
+			targetArgs:      []string{"--user", "user-id"},
+			requestedType:   "audio",
+			wantOpenID:      "D-resolved",
+			wantUserResolve: true,
+		},
+		{
+			name:          "explicit open id video",
+			targetArgs:    []string{"--open-dingtalk-id", fixtureCurrentDOpenID2},
+			requestedType: "video",
+			wantOpenID:    fixtureCurrentDOpenID2,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fake := &larkAlignmentCaller{responses: map[string]string{
+				"im/init_conversation_file_upload":   `{"resourceUrl":"` + uploadServer.URL + `","uploadKey":"upload-key"}`,
+				"im/commit_conversation_file_upload": `{"result":{"dentryId":31,"spaceId":41}}`,
+				"chat/send_personal_message":         `{"result":{"openMessageId":"sent-direct-file"}}`,
+			}}
+			helpers.InitDeps(fake)
+			root := newPlatformCoverageRoot()
+			var output bytes.Buffer
+			root.SetOut(&output)
+			args := []string{
+				"chat", "+messages-send", "--identity", "user",
+				"--msg-type", tt.requestedType,
+				"--file", "./direct.bin",
+				"--idempotency-key", "direct-" + tt.requestedType,
+				"--yes",
+			}
+			args = append(args, tt.targetArgs...)
+			root.SetArgs(args)
+			if err := root.Execute(); err != nil {
+				t.Fatal(err)
+			}
+
+			callOffset := 0
+			if tt.wantUserResolve {
+				if len(fake.calls) == 0 || fake.calls[0].product != "contact" ||
+					fake.calls[0].tool != "search_contact_by_key_word" {
+					t.Fatalf("resolution call = %#v", fake.calls)
+				}
+				callOffset = 1
+			}
+			if len(fake.calls) != callOffset+3 {
+				t.Fatalf("calls = %#v, want resolution plus init, commit, send", fake.calls)
+			}
+			initCall := fake.calls[callOffset]
+			commitCall := fake.calls[callOffset+1]
+			sendCall := fake.calls[callOffset+2]
+			for _, call := range []larkAlignmentCall{initCall, commitCall} {
+				if call.product != "im" || call.args["openDingTalkId"] != tt.wantOpenID {
+					t.Fatalf("upload call = %#v, want openDingTalkId %q", call, tt.wantOpenID)
+				}
+				if _, exists := call.args["receiverOpenDingTalkId"]; exists {
+					t.Fatalf("send-only receiver field leaked into upload call: %#v", call.args)
+				}
+			}
+			if initCall.tool != "init_conversation_file_upload" ||
+				commitCall.tool != "commit_conversation_file_upload" {
+				t.Fatalf("upload calls = %#v, %#v", initCall, commitCall)
+			}
+			if sendCall.product != "chat" || sendCall.tool != "send_personal_message" ||
+				sendCall.args["receiverOpenDingTalkId"] != tt.wantOpenID {
+				t.Fatalf("send call = %#v, want receiverOpenDingTalkId %q", sendCall, tt.wantOpenID)
+			}
+			if _, exists := sendCall.args["openDingTalkId"]; exists {
+				t.Fatalf("upload-only target field leaked into send call: %#v", sendCall.args)
+			}
+
+			var payload map[string]any
+			if err := json.Unmarshal(output.Bytes(), &payload); err != nil {
+				t.Fatal(err)
+			}
+			if payload["requestedMessageType"] != tt.requestedType ||
+				payload["effectiveMessageType"] != "file" {
+				t.Fatalf("output = %#v", payload)
+			}
+		})
+	}
+}
+
 func TestCrossPlatformCoverageMessagesSendCurrentUserLocalFileDryRunAndFailures(t *testing.T) {
 	t.Chdir(t.TempDir())
 	if err := os.WriteFile("fixture.bin", []byte("x"), 0o600); err != nil {

internal/shortcut/chat/lark_alignment_test.go

@@ -10,6 +10,7 @@ import (
 	"encoding/json"
 	"errors"
 	"reflect"
+	"strings"
 	"testing"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/helpers"
@@ -337,8 +338,15 @@ func TestCrossPlatformCoverageMessagesSendRoutesIdentitySpecificTransports(t *te
 				}
 			}
 			if tt.bodyKey == "content" {
+				rawContent := call.args[tt.bodyKey].(string)
+				if strings.Contains(rawContent, `\u003c`) || strings.Contains(rawContent, `\u003e`) {
+					t.Errorf("content = %q; current-user mention tokens must remain literal", rawContent)
+				}
+				if !strings.Contains(rawContent, "<@"+fixtureCurrentDOpenID+">") {
+					t.Errorf("content = %q; missing literal current-user mention token", rawContent)
+				}
 				var content map[string]string
-				if err := json.Unmarshal([]byte(call.args[tt.bodyKey].(string)), &content); err != nil {
+				if err := json.Unmarshal([]byte(rawContent), &content); err != nil {
 					t.Fatal(err)
 				}
 				if content["text"] != tt.body {

internal/shortcut/chat/unified_send.go

@@ -11,6 +11,7 @@ import (
 	"os"
 	"strings"
 	"time"
+	"unicode"
 	"unicode/utf8"
 
 	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/corecmd"
@@ -18,6 +19,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/helpers"
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/jsonutil"
 	"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"
@@ -181,6 +183,12 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 		if contentType != "text" && contentType != "markdown" && (len(atOpenIDs) > 0 || rt.Bool("at-all")) {
 			return apperrors.NewValidation("user image/file/audio/video 当前不接受 @ 参数")
 		}
+		if (group != "" || chatQuery != "") && (contentType == "text" || contentType == "markdown") {
+			if err := validateCurrentUserMentionConsistency(
+				messagesSendBody(rt), atOpenIDs, rt.Bool("at-all")); err != nil {
+				return err
+			}
+		}
 	case "bot":
 		if chatQuery != "" || userQuery != "" {
 			return apperrors.NewValidation("--identity bot 当前不接受 --chat-query 或 --user-query；请传真实群 ID 或批量用户 ID")
@@ -234,6 +242,89 @@ func validateMessagesSend(rt *shortcut.RuntimeContext) error {
 	return nil
 }
 
+func validateCurrentUserMentionConsistency(body string, atOpenIDs []string, atAll bool) error {
+	declared := make(map[string]struct{}, len(atOpenIDs))
+	for _, id := range atOpenIDs {
+		declared[id] = struct{}{}
+	}
+
+	missingPlaceholders := make([]string, 0)
+	for _, id := range atOpenIDs {
+		if !containsCurrentUserMentionToken(body, id) {
+			missingPlaceholders = append(missingPlaceholders, id)
+		}
+	}
+	if len(missingPlaceholders) > 0 {
+		return apperrors.NewValidation(fmt.Sprintf(
+			"--at-open-dingtalk-ids 中的成员必须在正文中使用对应 <@openDingTalkId> 占位符；缺少: %s",
+			strings.Join(missingPlaceholders, ","),
+		))
+	}
+
+	undeclared := make([]string, 0)
+	for _, id := range currentUserMentionBodyIDs(body) {
+		if _, ok := declared[id]; !ok {
+			undeclared = append(undeclared, id)
+		}
+	}
+	if len(undeclared) > 0 {
+		return apperrors.NewValidation(fmt.Sprintf(
+			"正文中的成员 <@openDingTalkId> 占位符必须同时通过 --at-open-dingtalk-ids 声明；未声明: %s",
+			strings.Join(undeclared, ","),
+		))
+	}
+	if !atAll && containsCurrentUserMentionToken(body, "all") {
+		return apperrors.NewValidation("正文中的 <@all> 占位符必须同时指定 --at-all")
+	}
+	return nil
+}
+
+func containsCurrentUserMentionToken(body, id string) bool {
+	placeholder := "@" + id
+	for searchFrom := 0; ; {
+		offset := strings.Index(body[searchFrom:], placeholder)
+		if offset < 0 {
+			return false
+		}
+		end := searchFrom + offset + len(placeholder)
+		if end == len(body) {
+			return true
+		}
+		next, _ := utf8.DecodeRuneInString(body[end:])
+		if !unicode.IsLetter(next) && !unicode.IsDigit(next) && next != '_' && next != '-' {
+			return true
+		}
+		searchFrom = end
+	}
+}
+
+func currentUserMentionBodyIDs(body string) []string {
+	ids := make([]string, 0)
+	for searchFrom := 0; ; {
+		offset := strings.IndexByte(body[searchFrom:], '@')
+		if offset < 0 {
+			break
+		}
+		start := searchFrom + offset + 1
+		end := start
+		for end < len(body) {
+			current := body[end]
+			if (current < 'a' || current > 'z') &&
+				(current < 'A' || current > 'Z') &&
+				(current < '0' || current > '9') {
+				break
+			}
+			end++
+		}
+		id := body[start:end]
+		if targetresolver.LooksLikeCurrentDOpenDingTalkID(id) {
+			ids = appendUniqueShortcutString(ids, id)
+		}
+		searchFrom = end
+	}
+	return ids
+}
+
 func executeMessagesSend(rt *shortcut.RuntimeContext) error {
 	identity := messagesSendIdentity(rt)
 	body := messagesSendBody(rt)
@@ -499,7 +590,7 @@ func resolvedUserMarkdownParams(
 	if target.GroupID != "" {
 		body = helpers.NormalizeMessageMentions(body, atOpenIDs, atAll, true)
 	}
-	content, _ := json.Marshal(map[string]string{"title": title, "text": body})
+	content, _ := jsonutil.Marshal(map[string]string{"title": title, "text": body})
 	params := rt.AddAIMessageTag(map[string]any{
 		"msgType": "markdown",
 		"content": string(content),
@@ -573,8 +664,10 @@ func executeMessagesSendUserFile(
 	if err != nil {
 		return err
 	}
-	targetArgs := map[string]any{}
-	addMessagesSendUserTarget(targetArgs, group, openID)
+	uploadTargetArgs := map[string]any{}
+	addMessagesSendUserUploadTarget(uploadTargetArgs, group, openID)
+	sendTargetArgs := map[string]any{}
+	addMessagesSendUserTarget(sendTargetArgs, group, openID)
 	idempotencyKey := messagesSendIdempotencyKey(rt)
 	if rt.DryRun() {
 		return rt.Output(map[string]any{
@@ -587,6 +680,7 @@ func executeMessagesSendUserFile(
 				{
 					"identity": "user",
 					"tool":     "init/commit_conversation_file_upload",
+					"target":   uploadTargetArgs,
 					"file": map[string]any{
 						"path":      rawPath,
 						"name":      meta.FileName,
@@ -598,7 +692,7 @@ func executeMessagesSendUserFile(
 					"tool":                 "send_personal_message",
 					"requestedMessageType": requestedType,
 					"effectiveMessageType": "file",
-					"target":               targetArgs,
+					"target":               sendTargetArgs,
 				},
 			},
 		})
@@ -607,7 +701,7 @@ func executeMessagesSendUserFile(
 		rt.Command().Context(), messagesSendFileUploadTimeout)
 	defer cancelUpload()
 	commitText, err := helpers.UploadConversationLocalFile(
-		uploadContext, targetArgs, meta, idempotencyKey)
+		uploadContext, uploadTargetArgs, meta, idempotencyKey)
 	if err != nil {
 		return err
 	}
@@ -653,6 +747,14 @@ func addMessagesSendUserTarget(params map[string]any, group, openID string) {
 	params["receiverOpenDingTalkId"] = openID
 }
 
+func addMessagesSendUserUploadTarget(params map[string]any, group, openID string) {
+	if group != "" {
+		params["openConversationId"] = group
+		return
+	}
+	params["openDingTalkId"] = openID
+}
+
 func nonEmptyStringCount(values ...string) int {
 	count := 0
 	for _, value := range values {

internal/upgrade/canonical_skills_test.go

@@ -0,0 +1,521 @@
+package upgrade
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageCanonicalSkillLayoutMigratesUniversalCopiesAndLinksOtherAgents(t *testing.T) {
+	home := withFakeHome(t)
+	testseam.Swap(t, &knownSkillDirs, []string{
+		".agents/skills", ".codex/skills", ".claude/skills", ".openclaw/skills",
+	})
+
+	for _, parent := range []string{".codex", ".claude", ".openclaw"} {
+		if err := os.MkdirAll(filepath.Join(home, parent), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// beta.6 wrote a physical copy into Codex. The canonical migration must
+	// remove it without treating a matching user/market name as DWS-owned.
+	oldCodex := filepath.Join(home, ".codex", "skills", "dingtalk-chat")
+	if err := os.MkdirAll(oldCodex, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oldCodex, "SKILL.md"), []byte("beta.6"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	multiRoot := writeMultiBundle(t, t.TempDir(), "dingtalk-chat", "dingtalk-shared")
+	result, err := UpgradeSkillLocationsWithOptions(multiRoot, SkillUpgradeOptions{Version: "1.0.58-beta.6"})
+	if err != nil || len(result.Failed()) != 0 {
+		t.Fatalf("upgrade = %#v, %v", result, err)
+	}
+
+	canonical := filepath.Join(home, ".agents", "skills")
+	for _, name := range []string{"dingtalk-chat", "dingtalk-shared"} {
+		if _, err := os.Stat(filepath.Join(canonical, name, "SKILL.md")); err != nil {
+			t.Fatalf("canonical %s missing: %v", name, err)
+		}
+		if _, err := os.Lstat(filepath.Join(home, ".codex", "skills", name)); !os.IsNotExist(err) {
+			t.Fatalf("universal Codex duplicate remains for %s: %v", name, err)
+		}
+		for _, agent := range []string{".claude", ".openclaw"} {
+			link := filepath.Join(home, agent, "skills", name)
+			info, err := os.Lstat(link)
+			if err != nil || info.Mode()&os.ModeSymlink == 0 {
+				t.Fatalf("%s link = %#v, %v", link, info, err)
+			}
+			if _, err := os.Stat(filepath.Join(link, "SKILL.md")); err != nil {
+				t.Fatalf("%s does not resolve canonical content: %v", link, err)
+			}
+		}
+	}
+	result, err = UpgradeSkillLocationsWithOptions(multiRoot, SkillUpgradeOptions{Version: "1.0.58-beta.6"})
+	if err != nil || len(result.Failed()) != 0 {
+		t.Fatalf("idempotent upgrade = %#v, %v", result, err)
+	}
+	for _, agent := range []string{".claude", ".openclaw"} {
+		info, err := os.Lstat(filepath.Join(home, agent, "skills", "dingtalk-chat"))
+		if err != nil || info.Mode()&os.ModeSymlink == 0 {
+			t.Fatalf("idempotent upgrade replaced %s link: %#v, %v", agent, info, err)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageCanonicalCustomRootsSymlinkedParentsAndLexicalVictims(t *testing.T) {
+	home := withFakeHome(t)
+	customCodex := filepath.Join(t.TempDir(), "codex")
+	customHermes := filepath.Join(t.TempDir(), "hermes")
+	externalClaude := filepath.Join(t.TempDir(), "claude")
+	for _, root := range []string{customCodex, customHermes, externalClaude, filepath.Join(home, ".clawdbot"), filepath.Join(home, ".codeium", "windsurf")} {
+		if err := os.MkdirAll(root, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := os.Symlink(externalClaude, filepath.Join(home, ".claude")); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &upgradeGetenv, func(name string) string {
+		switch name {
+		case "CODEX_HOME":
+			return customCodex
+		case "HERMES_HOME":
+			return customHermes
+		default:
+			return ""
+		}
+	})
+
+	oldCodex := filepath.Join(customCodex, "skills", "dingtalk-chat")
+	if err := os.MkdirAll(oldCodex, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(oldCodex, "SKILL.md"), []byte("beta.6"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	claudeBase := filepath.Join(home, ".claude", "skills")
+	if err := os.MkdirAll(claudeBase, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(claudeBase, "dingtalk-chat"), []byte("unexpected file"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink("missing-target", filepath.Join(claudeBase, "dingtalk-shared")); err != nil {
+		t.Fatal(err)
+	}
+
+	multiRoot := writeMultiBundle(t, t.TempDir(), "dingtalk-chat", "dingtalk-shared")
+	result, err := UpgradeSkillLocations(multiRoot)
+	if err != nil || len(result.Failed()) != 0 {
+		t.Fatalf("upgrade = %#v, %v", result, err)
+	}
+	if _, err := os.Lstat(oldCodex); !os.IsNotExist(err) {
+		t.Fatalf("custom CODEX_HOME duplicate remains: %v", err)
+	}
+	for _, base := range []string{
+		claudeBase,
+		filepath.Join(customHermes, "skills"),
+		filepath.Join(home, ".clawdbot", "skills"),
+		filepath.Join(home, ".codeium", "windsurf", "skills"),
+	} {
+		for _, name := range []string{"dingtalk-chat", "dingtalk-shared"} {
+			path := filepath.Join(base, name)
+			info, statErr := os.Lstat(path)
+			if statErr != nil || info.Mode()&os.ModeSymlink == 0 {
+				t.Fatalf("expected canonical link %s: %#v, %v", path, info, statErr)
+			}
+			body, readErr := os.ReadFile(filepath.Join(path, "SKILL.md"))
+			if readErr != nil || !strings.Contains(string(body), name) {
+				t.Fatalf("link %s does not resolve: %q, %v", path, body, readErr)
+			}
+		}
+	}
+}
+
+func TestCrossPlatformCoverageCanonicalSkillLinksFallBackToCopies(t *testing.T) {
+	home := withFakeHome(t)
+	testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills"})
+	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	testseam.Swap(t, &upgradeSymlink, func(string, string) error { return errors.New("links unavailable") })
+
+	multiRoot := writeMultiBundle(t, t.TempDir(), "dingtalk-chat")
+	result, err := UpgradeSkillLocations(multiRoot)
+	if err != nil || len(result.Failed()) != 0 {
+		t.Fatalf("upgrade = %#v, %v", result, err)
+	}
+	dest := filepath.Join(home, ".claude", "skills", "dingtalk-chat")
+	info, err := os.Lstat(dest)
+	if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+		t.Fatalf("copy fallback = %#v, %v", info, err)
+	}
+	if _, err := os.Stat(filepath.Join(dest, "SKILL.md")); err != nil {
+		t.Fatalf("copy fallback content missing: %v", err)
+	}
+}
+
+func TestCrossPlatformCoverageConfiguredRootsDetectShallowAndApplicationAgents(t *testing.T) {
+	// Keep the destination HOME synthetic: app-bundle detection is deliberately
+	// machine-scoped and must not depend on the selected installation HOME.
+	home := t.TempDir()
+	testseam.Swap(t, &upgradeGetenv, func(string) string { return "" })
+	for _, dir := range []string{filepath.Join(home, ".config", "kimchi"), filepath.Join(home, ".tabnine")} {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	sentinel := filepath.Join(home, "app-sentinel")
+	if err := os.MkdirAll(sentinel, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	appInfo, err := os.Stat(sentinel)
+	if err != nil {
+		t.Fatal(err)
+	}
+	zcodeApp := filepath.Join(string(filepath.Separator), "Applications", "ZCode.app")
+	minimaxApp := filepath.Join(string(filepath.Separator), "Applications", "MiniMax Code.app")
+	originalStat := upgradeStat
+	testseam.Swap(t, &upgradeStat, func(path string) (os.FileInfo, error) {
+		if path == zcodeApp || path == minimaxApp {
+			return appInfo, nil
+		}
+		return originalStat(path)
+	})
+	want := map[string]bool{
+		".config/kimchi/harness/skills": false,
+		".tabnine/agent/skills":         false,
+		".zcode/skills":                 false,
+		".minimax/skills":               false,
+	}
+	for _, root := range configuredSkillRoots(home) {
+		label := filepath.ToSlash(root.label)
+		if _, ok := want[label]; ok {
+			want[label] = skillRootDetectedBase(root)
+		}
+	}
+	for label, detected := range want {
+		if !detected {
+			t.Errorf("root %s was not detected", label)
+		}
+	}
+}
+
+func TestCrossPlatformCoverageConfiguredAgentRootsMatchUpstreamAndCustomHomes(t *testing.T) {
+	home := t.TempDir()
+	custom := map[string]string{
+		"AUTOHAND_HOME":     filepath.Join(home, "custom-autohand"),
+		"CLAUDE_CONFIG_DIR": filepath.Join(home, "custom-claude"),
+		"CODEX_HOME":        filepath.Join(home, "custom-codex"),
+		"GROK_HOME":         filepath.Join(home, "custom-grok"),
+		"HERMES_HOME":       filepath.Join(home, "custom-hermes"),
+		"VIBE_HOME":         filepath.Join(home, "custom-vibe"),
+		"XDG_CONFIG_HOME":   filepath.Join(home, "custom-xdg"),
+	}
+	testseam.Swap(t, &upgradeGetenv, func(name string) string { return custom[name] })
+	roots := configuredSkillRoots(home)
+	if len(roots) != len(knownSkillDirs) {
+		t.Fatalf("configured unique roots = %d, want %d", len(roots), len(knownSkillDirs))
+	}
+	byLabel := make(map[string]resolvedSkillRoot, len(roots))
+	for _, root := range roots {
+		if _, duplicate := byLabel[root.label]; duplicate {
+			t.Fatalf("duplicate configured label %s", root.label)
+		}
+		byLabel[root.label] = root
+	}
+	wants := map[string]string{
+		".autohand/skills":              filepath.Join(custom["AUTOHAND_HOME"], "skills"),
+		".claude/skills":                filepath.Join(custom["CLAUDE_CONFIG_DIR"], "skills"),
+		".codex/skills":                 filepath.Join(custom["CODEX_HOME"], "skills"),
+		".grok/skills":                  filepath.Join(custom["GROK_HOME"], "skills"),
+		".hermes/skills":                filepath.Join(custom["HERMES_HOME"], "skills"),
+		".vibe/skills":                  filepath.Join(custom["VIBE_HOME"], "skills"),
+		".config/agents/skills":         filepath.Join(custom["XDG_CONFIG_HOME"], "agents", "skills"),
+		".config/crush/skills":          filepath.Join(custom["XDG_CONFIG_HOME"], "crush", "skills"),
+		".config/devin/skills":          filepath.Join(custom["XDG_CONFIG_HOME"], "devin", "skills"),
+		".config/goose/skills":          filepath.Join(custom["XDG_CONFIG_HOME"], "goose", "skills"),
+		".config/kimchi/harness/skills": filepath.Join(custom["XDG_CONFIG_HOME"], "kimchi", "harness", "skills"),
+		".config/opencode/skills":       filepath.Join(custom["XDG_CONFIG_HOME"], "opencode", "skills"),
+	}
+	for label, want := range wants {
+		if got := byLabel[label].base; filepath.Clean(got) != filepath.Clean(want) {
+			t.Errorf("configured %s = %q, want %q", label, got, want)
+		}
+	}
+	for _, label := range []string{
+		".config/agents/skills", ".gemini/antigravity/skills", ".gemini/antigravity-cli/skills",
+		".codex/skills", ".cursor/skills", ".deepagents/agent/skills", ".firebender/skills",
+		".gemini/skills", ".copilot/skills", ".config/opencode/skills",
+	} {
+		if !byLabel[label].universal {
+			t.Errorf("%s not classified universal", label)
+		}
+	}
+	if !byLabel[".agents/skills"].canonical || byLabel[".claude/skills"].universal {
+		t.Fatal("canonical/non-universal classification drift")
+	}
+}
+
+func TestCrossPlatformCoverageUpgradeCanonicalFailureFailsFastUnconditionally(t *testing.T) {
+	for _, mode := range []string{"mono", "multi"} {
+		t.Run(mode, func(t *testing.T) {
+			withFakeHome(t)
+			// Canonical-only configuration (no non-universal dependents): a failed
+			// canonical publish must still fail the whole upgrade. Universal agents
+			// read canonical directly, so silently succeeding here would leave the
+			// machine without any usable Skill while reporting success.
+			testseam.Swap(t, &knownSkillDirs, []string{".agents/skills"})
+			testseam.Swap(t, &upgradeCopyDir, func(string, string) error { return errors.New("canonical denied") })
+
+			src := t.TempDir()
+			if mode == "mono" {
+				if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("mono"), 0o644); err != nil {
+					t.Fatal(err)
+				}
+			} else {
+				src = writeMultiBundle(t, src, "dingtalk-chat")
+			}
+			result, err := UpgradeSkillLocations(src)
+			if err == nil || !strings.Contains(err.Error(), "canonical Skill 安装失败") {
+				t.Fatalf("canonical publish failure must propagate an error, got (%v)", err)
+			}
+			if result == nil || len(result.Failed()) != 1 || len(result.Succeeded()) != 0 {
+				t.Fatalf("result = %#v", result)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageUpgradeOpenClawAliasPriority(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		dirs []string
+		want string
+	}{
+		{name: "default", want: ".openclaw"},
+		{name: "moltbot", dirs: []string{".moltbot"}, want: ".moltbot"},
+		{name: "clawdbot-before-moltbot", dirs: []string{".moltbot", ".clawdbot"}, want: ".clawdbot"},
+		{name: "openclaw-first", dirs: []string{".moltbot", ".clawdbot", ".openclaw"}, want: ".openclaw"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			for _, dir := range tc.dirs {
+				if err := os.MkdirAll(filepath.Join(home, dir), 0o755); err != nil {
+					t.Fatal(err)
+				}
+			}
+			if got := resolveOpenClawSkillBase(home); got != filepath.Join(home, tc.want, "skills") {
+				t.Fatalf("OpenClaw root = %q", got)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageUpgradeLinkStagingFailureEdges(t *testing.T) {
+	home := t.TempDir()
+	canonical := filepath.Join(home, ".agents", "skills")
+	dest := filepath.Join(home, ".claude", "skills")
+	if err := os.MkdirAll(filepath.Join(canonical, "dingtalk-chat"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	t.Run("mkdir", func(t *testing.T) {
+		testseam.Swap(t, &upgradeMkdirAll, func(string, os.FileMode) error { return errors.New("mkdir denied") })
+		if _, _, err := stageLinkedSkillSet(dest, canonical, ".stage-", []string{"dingtalk-chat"}); err == nil || !strings.Contains(err.Error(), "创建 Agent Skill 目录") {
+			t.Fatalf("mkdir failure = %v", err)
+		}
+	})
+	t.Run("temp", func(t *testing.T) {
+		testseam.Swap(t, &upgradeMkdirTemp, func(string, string) (string, error) { return "", errors.New("temp denied") })
+		if _, _, err := stageLinkedSkillSet(dest, canonical, ".stage-", []string{"dingtalk-chat"}); err == nil || !strings.Contains(err.Error(), "链接 staging") {
+			t.Fatalf("temp failure = %v", err)
+		}
+	})
+	t.Run("physical-parent", func(t *testing.T) {
+		testseam.Swap(t, &upgradeEvalSymlinks, func(path string) (string, error) {
+			if path == dest {
+				return "", errors.New("physical denied")
+			}
+			return filepath.EvalSymlinks(path)
+		})
+		if _, _, err := stageLinkedSkillSet(dest, canonical, ".stage-", []string{"dingtalk-chat"}); err == nil || !strings.Contains(err.Error(), "物理目录") {
+			t.Fatalf("physical failure = %v", err)
+		}
+	})
+	t.Run("canonical-target", func(t *testing.T) {
+		target := filepath.Join(canonical, "dingtalk-chat")
+		testseam.Swap(t, &upgradeEvalSymlinks, func(path string) (string, error) {
+			if path == target {
+				return "", errors.New("canonical denied")
+			}
+			return filepath.EvalSymlinks(path)
+		})
+		if _, _, err := stageLinkedSkillSet(dest, canonical, ".stage-", []string{"dingtalk-chat"}); err == nil || !strings.Contains(err.Error(), "解析 canonical") {
+			t.Fatalf("canonical failure = %v", err)
+		}
+	})
+	t.Run("relative-path", func(t *testing.T) {
+		testseam.Swap(t, &upgradeRel, func(string, string) (string, error) { return "", errors.New("relative denied") })
+		if _, _, err := stageLinkedSkillSet(dest, canonical, ".stage-", []string{"dingtalk-chat"}); err == nil || !strings.Contains(err.Error(), "相对链接") {
+			t.Fatalf("relative failure = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageUpgradeAgentBranchFailures(t *testing.T) {
+	for _, mode := range []string{"mono", "multi"} {
+		t.Run(mode, func(t *testing.T) {
+			makeSource := func(t *testing.T) string {
+				t.Helper()
+				src := t.TempDir()
+				if mode == "mono" {
+					if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("mono"), 0o644); err != nil {
+						t.Fatal(err)
+					}
+					return src
+				}
+				return writeMultiBundle(t, src, "dingtalk-chat")
+			}
+
+			t.Run("undetected-and-physical-alias", func(t *testing.T) {
+				home := withFakeHome(t)
+				testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills", ".qoder/skills"})
+				if err := os.MkdirAll(filepath.Join(home, ".qoder"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Symlink(filepath.Join(home, ".agents", "skills"), filepath.Join(home, ".qoder", "skills")); err != nil {
+					t.Fatal(err)
+				}
+				result, err := UpgradeSkillLocations(makeSource(t))
+				if err != nil {
+					t.Fatal(err)
+				}
+				if len(result.Results) < 3 || result.Results[1].Status != SkillDirSkipped || result.Results[2].Status != SkillDirSkipped {
+					t.Fatalf("skip branches = %#v", result.Results)
+				}
+			})
+
+			t.Run("universal-retire-failure", func(t *testing.T) {
+				home := withFakeHome(t)
+				testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".cursor/skills"})
+				victimBase := filepath.Join(home, ".cursor", "skills")
+				victim := filepath.Join(victimBase, "dws")
+				if mode == "multi" {
+					victim = filepath.Join(victimBase, "dingtalk-chat")
+				}
+				if err := os.MkdirAll(victim, 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if mode == "multi" {
+					useUpgradeManagedNames(t, "dingtalk-chat")
+				}
+				origRename := skillPathRenameNoReplace
+				testseam.Swap(t, &skillPathRenameNoReplace, func(src, dst string) (string, error) {
+					if src == victim {
+						return "", errors.New("retire denied")
+					}
+					return origRename(src, dst)
+				})
+				result, err := UpgradeSkillLocations(makeSource(t))
+				if err != nil {
+					t.Fatalf("retire failure must not fail the upgrade: %v", err)
+				}
+				if len(result.Failed()) != 0 {
+					t.Fatalf("retire failure must not count as an install failure: %#v", result.Failed())
+				}
+				warnings := result.RetireWarnings()
+				if len(warnings) != 1 || warnings[0].Err == nil {
+					t.Fatalf("retire warnings = %#v", warnings)
+				}
+				if len(result.Succeeded()) == 0 {
+					t.Fatalf("canonical must still be published: %#v", result)
+				}
+				if _, statErr := os.Lstat(victim); statErr != nil {
+					t.Fatalf("unretired copy must be preserved: %v", statErr)
+				}
+			})
+
+			t.Run("universal-retire-success", func(t *testing.T) {
+				home := withFakeHome(t)
+				testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".cursor/skills"})
+				victimBase := filepath.Join(home, ".cursor", "skills")
+				victim := filepath.Join(victimBase, "dws")
+				if mode == "multi" {
+					victim = filepath.Join(victimBase, "dingtalk-chat")
+					useUpgradeManagedNames(t, "dingtalk-chat")
+				}
+				if err := os.MkdirAll(victim, 0o755); err != nil {
+					t.Fatal(err)
+				}
+				result, err := UpgradeSkillLocations(makeSource(t))
+				if err != nil || len(result.Failed()) != 0 {
+					t.Fatalf("retire success = %#v, %v", result, err)
+				}
+				if _, err := os.Lstat(victim); !os.IsNotExist(err) {
+					t.Fatalf("universal victim remains: %v", err)
+				}
+			})
+
+			t.Run("victim-scan-and-fallback-copy-failures", func(t *testing.T) {
+				t.Run("victim-scan", func(t *testing.T) {
+					home := withFakeHome(t)
+					testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills"})
+					base := filepath.Join(home, ".claude", "skills")
+					if err := os.MkdirAll(base, 0o755); err != nil {
+						t.Fatal(err)
+					}
+					origReadDir := upgradeReadDir
+					testseam.Swap(t, &upgradeReadDir, func(path string) ([]os.DirEntry, error) {
+						if path == base {
+							return nil, errors.New("scan denied")
+						}
+						return origReadDir(path)
+					})
+					result, err := UpgradeSkillLocations(makeSource(t))
+					if err != nil || len(result.Failed()) != 1 {
+						t.Fatalf("victim scan = %#v, %v", result, err)
+					}
+				})
+
+				t.Run("fallback-copy", func(t *testing.T) {
+					home := withFakeHome(t)
+					testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills"})
+					base := filepath.Join(home, ".claude", "skills")
+					if err := os.MkdirAll(base, 0o755); err != nil {
+						t.Fatal(err)
+					}
+					testseam.Swap(t, &upgradeSymlink, func(string, string) error { return errors.New("link denied") })
+					origCopy := upgradeCopyDir
+					testseam.Swap(t, &upgradeCopyDir, func(src, dst string) error {
+						if strings.HasPrefix(filepath.Clean(dst), filepath.Clean(base)+string(filepath.Separator)) {
+							return errors.New("copy denied")
+						}
+						return origCopy(src, dst)
+					})
+					result, err := UpgradeSkillLocations(makeSource(t))
+					if err != nil || len(result.Failed()) != 1 {
+						t.Fatalf("fallback copy = %#v, %v", result, err)
+					}
+				})
+			})
+		})
+	}
+}
+
+func TestCrossPlatformCoverageUpgradeWindowsPathNormalizationAndRootDedup(t *testing.T) {
+	testseam.Swap(t, &upgradeFoldPathCase, true)
+	if got := skillRootPathKey(filepath.Join("Root", "Skills")); got != strings.ToLower(got) {
+		t.Fatalf("case-folded path key = %q", got)
+	}
+	testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills", ".claude/skills"})
+	if roots := configuredSkillRoots(t.TempDir()); len(roots) != 2 {
+		t.Fatalf("deduplicated roots = %#v", roots)
+	}
+}

internal/upgrade/coverage_edges_test.go

@@ -264,7 +264,7 @@ func TestCrossPlatformCoverageUpgradePathsAndSkillsEdges(t *testing.T) {
 	}
 	knownSkillDirs = []string{".agents/skills", ".real/skills", ".missing/skills", ".present/skills"}
 	result, err := UpgradeSkillLocations(source)
-	if err != nil || len(result.Succeeded()) != 1 || len(result.Failed()) != 0 {
+	if err != nil || len(result.Succeeded()) != 2 || len(result.Failed()) != 0 {
 		t.Fatalf("skill upgrade = %#v, %v", result, err)
 	}
 	knownSkillDirs = []string{".real/skills"}
@@ -579,7 +579,10 @@ func TestCrossPlatformCoverageUpgradePathInjectedFailures(t *testing.T) {
 	})
 	home := t.TempDir()
 	upgradeUserHomeDir = func() (string, error) { return home, nil }
-	knownSkillDirs = []string{".agents/skills"}
+	knownSkillDirs = []string{".agents/skills", ".claude/skills"}
+	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
 	calls := 0
 	upgradeCopyDir = func(src, dst string) error {
 		calls++
@@ -593,8 +596,8 @@ func TestCrossPlatformCoverageUpgradePathInjectedFailures(t *testing.T) {
 		t.Fatal(err)
 	}
 	result, err := UpgradeSkillLocations(source)
-	if err != nil || len(result.Succeeded()) != 1 || len(result.Results) != 1 {
-		t.Fatalf("replaced primary fallback = %#v, %v", result, err)
+	if err == nil || len(result.Failed()) != 1 || len(result.Succeeded()) != 0 {
+		t.Fatalf("canonical failure = %#v, %v", result, err)
 	}
 	failure := errors.New("ensure failed")
 	upgradeEnsureDir = func(string, os.FileMode) error { return failure }

internal/upgrade/paths.go

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"regexp"
 	"runtime"
 	"sort"
 	"strings"
@@ -35,46 +36,133 @@ const (
 //   - test/scripts/package_script_test.go                   expectedPackagedSkillTargets
 //   - scripts/release/verify-package-managers.sh            HOME_AGENT_PARENTS / HOME_SKILL_TARGETS
 //
-// The first entry (.agents/skills) is a generic fallback. It is used only
-// when no concrete Agent home is detected; otherwise publishing there would
-// duplicate every Skill for Agents (including Codex) that scan both roots.
-// Subsequent entries are updated when their parent directory already exists.
+// The first entry (.agents/skills) is the canonical global Skill directory,
+// following the universal .agents/skills convention.
+// Agents that understand the universal .agents convention read it directly;
+// detected non-universal Agents receive relative links to this canonical
+// copy (with a direct-copy fallback when links are unavailable).
 var knownSkillDirs = []string{
 	".agents/skills",
+	".config/agents/skills",
+	".gemini/antigravity/skills",
+	".gemini/antigravity-cli/skills",
+	".deepagents/agent/skills",
+	".firebender/skills",
+	".copilot/skills",
+	".config/opencode/skills",
+	".aider-desk/skills",
+	".astrbot/data/skills",
+	".autohand/skills",
+	".augment/skills",
+	".bob/skills",
 	".claude/skills",
-	".cursor/skills",
+	".openclaw/skills",
+	".codeartsdoer/skills",
+	".codebuddy/skills",
+	".codemaker/skills",
+	".codestudio/skills",
+	".commandcode/skills",
+	".continue/skills",
+	".snowflake/cortex/skills",
+	".config/crush/skills",
+	".config/devin/skills",
+	".factory/skills",
+	".forge/skills",
+	".config/goose/skills",
+	".grok/skills",
+	".hermes/skills",
+	".inferencesh/skills",
+	".jazz/skills",
+	".junie/skills",
+	".iflow/skills",
+	".kilocode/skills",
+	".config/kimchi/harness/skills",
+	".kiro/skills",
+	".kode/skills",
+	".lingma/skills",
+	".mcpjam/skills",
+	".minimax/skills",
+	".vibe/skills",
+	".moxby/skills",
+	".mux/skills",
+	".openhands/skills",
+	".ona/skills",
+	".pi/agent/skills",
 	".qoder/skills",
+	".qoder-cn/skills",
+	".qwen/skills",
+	".reasonix/skills",
+	".rovodev/skills",
+	".roo/skills",
+	".tabnine/agent/skills",
+	".terramind/skills",
+	".tinycloud/skills",
+	".trae/skills",
+	".trae-cn/skills",
+	".codeium/windsurf/skills",
+	".zcode/skills",
+	".zencoder/skills",
+	".neovate/skills",
+	".pochi/skills",
+	".adal/skills",
+	// DWS-only target retained for product compatibility.
 	".qoderwork/skills",
+	// beta.6 compatibility roots: cleanup only, never publish new copies.
+	".cursor/skills",
 	".gemini/skills",
 	".codex/skills",
-	".zcode/skills",
 	".github/skills",
 	".windsurf/skills",
-	".augment/skills",
 	".cline/skills",
 	".amp/skills",
-	".kiro/skills",
-	".trae/skills",
-	".openclaw/skills",
-	".hermes/skills",
+}
+
+// universalSkillDirs are concrete Agent directories whose current clients
+// natively scan ~/.agents/skills. Publishing another copy or link below these
+// roots makes the same Skill appear twice. Keep this classification aligned
+// with vercel-labs/skills' isUniversalAgent rule. Qoderwork is intentionally
+// non-universal because it is a DWS-specific integration absent upstream.
+var universalSkillDirs = map[string]bool{
+	".config/agents/skills":          true,
+	".gemini/antigravity/skills":     true,
+	".gemini/antigravity-cli/skills": true,
+	".codex/skills":                  true,
+	".cursor/skills":                 true,
+	".deepagents/agent/skills":       true,
+	".firebender/skills":             true,
+	".gemini/skills":                 true,
+	".copilot/skills":                true,
+	".config/opencode/skills":        true,
+	// beta.6 compatibility roots are cleanup-only as well.
+	".github/skills":   true,
+	".windsurf/skills": true,
+	".cline/skills":    true,
+	".amp/skills":      true,
 }
 
 var (
-	upgradeUserHomeDir     = os.UserHomeDir
-	upgradeExecutable      = os.Executable
-	upgradeEvalSymlinks    = filepath.EvalSymlinks
-	upgradeCopyDir         = copyDir
-	upgradeEnsureDir       = ensureDir
-	upgradeRemoveAll       = os.RemoveAll
-	upgradeMkdirAll        = os.MkdirAll
-	upgradeMkdirTemp       = os.MkdirTemp
-	upgradeReadDir         = os.ReadDir
-	upgradeStat            = os.Stat
-	upgradeBuildProvenance = skillprovenance.Build
-	upgradeReadSkillState  = skillstate.Read
-	upgradeBackupStamp     = func() string { return time.Now().UTC().Format("20060102-150405") }
-	upgradeWriteSkillState = skillstate.Write
-	upgradeNow             = time.Now
+	upgradeUserHomeDir                 = os.UserHomeDir
+	upgradeExecutable                  = os.Executable
+	upgradeEvalSymlinks                = filepath.EvalSymlinks
+	upgradeCopyDir                     = copyDir
+	upgradeEnsureDir                   = ensureDir
+	upgradeRemoveAll                   = os.RemoveAll
+	upgradeMkdirAll                    = os.MkdirAll
+	upgradeMkdirTemp                   = os.MkdirTemp
+	upgradeReadDir                     = os.ReadDir
+	upgradeStat                        = os.Stat
+	upgradeLstat                       = os.Lstat
+	upgradeSymlink                     = os.Symlink
+	upgradeRel                         = filepath.Rel
+	upgradeGetenv                      = os.Getenv
+	upgradeBuildProvenance             = skillprovenance.Build
+	upgradeReadSkillState              = skillstate.Read
+	upgradePublishSkillPath            = PublishSkillPathNoReplace
+	upgradeRollbackPublishedSkillPaths = RollbackSkillPathPublications
+	upgradeBackupStamp                 = func() string { return time.Now().UTC().Format("20060102-150405") }
+	upgradeWriteSkillState             = skillstate.Write
+	upgradeNow                         = time.Now
+	upgradeFoldPathCase                = runtime.GOOS == "windows"
 )
 
 // skillBackupSubdir is the user-level directory where skill directories are
@@ -85,43 +173,64 @@ const skillBackupSubdir = ".dws/skill-backups"
 
 // backupAndRemoveSkillDir moves dir into <homeDir>/.dws/skill-backups/
 // <stamp>/<rel> instead of destroying it, and returns the backup path. It is
-// fail-safe: a directory that cannot be backed up is NOT removed and the
+// fail-safe: a path that cannot be backed up is NOT removed and the
 // error is returned so the caller can surface it (and never install the
-// opposite layout next to it silently). Missing paths and regular files are
-// no-ops ("", nil).
+// opposite layout next to it silently). Missing paths are no-ops. Directories,
+// links (including dangling links), and ordinary files are all preserved:
+// an unexpected file at a managed destination must never be overwritten.
 func backupAndRemoveSkillDir(homeDir, dir string) (string, error) {
-	info, err := upgradeStat(dir)
+	_, err := upgradeLstat(dir)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return "", nil
 		}
 		return "", fmt.Errorf("检查技能目录失败 %s: %w", dir, err)
 	}
-	if !info.IsDir() {
-		return "", nil
-	}
 	rel, relErr := filepath.Rel(homeDir, dir)
 	if relErr != nil || rel == "." || strings.HasPrefix(rel, "..") {
 		rel = filepath.Base(dir)
 	}
 	name := strings.NewReplacer(string(filepath.Separator), "-", "/", "-").Replace(rel)
 	stamp := upgradeBackupStamp()
-	backupRoot := filepath.Join(homeDir, skillBackupSubdir, stamp)
-	target := filepath.Join(backupRoot, name)
-	for i := 1; ; i++ {
-		if _, err := os.Stat(target); os.IsNotExist(err) {
-			break
+	if err := upgradeMkdirAll(filepath.Join(homeDir, skillBackupSubdir), dirPermShared); err != nil {
+		return "", fmt.Errorf("创建备份根目录失败 %s: %w", filepath.Join(homeDir, skillBackupSubdir), err)
+	}
+	var backupRoot, target string
+	for i := 0; ; i++ {
+		candidate := stamp
+		if i > 0 {
+			candidate = fmt.Sprintf("%s-%d", stamp, i)
 		}
-		backupRoot = filepath.Join(homeDir, skillBackupSubdir, fmt.Sprintf("%s-%d", stamp, i))
-		target = filepath.Join(backupRoot, name)
 		if i > 1000 {
-			return "", fmt.Errorf("备份目录冲突无法解决: %s", target)
+			return "", fmt.Errorf("备份目录冲突无法解决: %s", filepath.Join(homeDir, skillBackupSubdir, candidate))
 		}
+		backupRoot = filepath.Join(homeDir, skillBackupSubdir, candidate)
+		target = filepath.Join(backupRoot, name)
+		if _, err := upgradeLstat(target); err == nil {
+			continue // payload name already taken in this stamp root
+		} else if !os.IsNotExist(err) {
+			return "", fmt.Errorf("检查备份目标失败 %s: %w", target, err)
+		}
+		if err := skillPathMkdir(backupRoot, dirPermShared); err == nil {
+			// We created the root: stamp ownership before any payload moves
+			// in, so an interrupted backup never leaves an unmarked
+			// (never-prunable) stamp behind.
+			if err := skillBackupWriteMarker(backupRoot); err != nil {
+				// Bounded cleanup: the root is empty and ours alone.
+				_ = skillPathRemove(backupRoot)
+				return "", fmt.Errorf("写入备份所有权标记失败 %s: %w", backupRoot, err)
+			}
+			break
+		} else if !os.IsExist(err) {
+			return "", fmt.Errorf("创建备份目录失败 %s: %w", backupRoot, err)
+		} else if skillBackupMarkerValid(backupRoot) {
+			break // proven ours: same-stamp payloads from this run reuse it
+		}
+		// A stamp-shaped directory we cannot prove ours must never be
+		// adopted — writing the marker or the payload into it would turn
+		// its foreign contents into prunable DWS backups.
 	}
-	if err := upgradeMkdirAll(backupRoot, dirPermShared); err != nil {
-		return "", fmt.Errorf("创建备份目录失败 %s: %w", backupRoot, err)
-	}
-	if err := upgradeRename(dir, target); err != nil {
+	if err := moveSkillPathRecoverably(dir, target); err != nil {
 		return "", fmt.Errorf("备份技能目录失败 %s: %w", dir, err)
 	}
 	// Keep the backup directory bounded; a prune failure must not fail the
@@ -151,13 +260,17 @@ const (
 	SkillDirSkipped                           // agent not detected, directory skipped
 	SkillDirBlacklisted                       // blacklisted, never touched
 	SkillDirFailed                            // installation attempted but failed
+	// SkillDirRetireWarning marks a universal Agent whose obsolete private copy
+	// could not be retired. Nothing is installed below such a root, so the
+	// leftover is reported without counting as an install failure.
+	SkillDirRetireWarning
 )
 
 // SkillDirResult holds the per-directory install result.
 type SkillDirResult struct {
 	Dir    string         // destination directory (e.g. ~/.claude/skills/dws)
 	Status SkillDirStatus // outcome
-	Err    error          // non-nil when Status == SkillDirFailed
+	Err    error          // non-nil when Status == SkillDirFailed or SkillDirRetireWarning
 }
 
 // SkillUpgradeResult aggregates the outcome of an UpgradeSkillLocations call.
@@ -187,6 +300,18 @@ func (r *SkillUpgradeResult) Failed() []SkillDirResult {
 	return out
 }
 
+// RetireWarnings returns universal Agent roots that still hold an obsolete
+// private copy because retiring it failed.
+func (r *SkillUpgradeResult) RetireWarnings() []SkillDirResult {
+	var out []SkillDirResult
+	for _, d := range r.Results {
+		if d.Status == SkillDirRetireWarning {
+			out = append(out, d)
+		}
+	}
+	return out
+}
+
 // UpgradeSkillLocations refreshes skills from extractedDir into agent homes.
 // extractedDir may be a multi-skill bundle root (subdirectories each containing
 // SKILL.md) or a legacy mono root (SKILL.md at its top level). Callers that
@@ -204,11 +329,13 @@ func (r *SkillUpgradeResult) Failed() []SkillDirResult {
 // `dws skill setup --mode mono` flow.
 //
 // Strategy (matches npm install.js installSkillsToHomes):
-//   - Concrete agent dirs (claude, cursor, codex, ...) are updated when their
-//     parent directory exists (e.g. ~/.codex/ exists => user has Codex)
-//   - ~/.agents/skills/ is used only when no concrete Agent is detected
+//   - ~/.agents/skills/ is always the canonical global store
+//   - universal Agents (Codex, Cursor, Gemini, Cline, Amp, Copilot) read the
+//     canonical store directly, so old agent-specific copies are retired
+//   - detected non-universal Agents receive relative links to canonical;
+//     filesystems that reject links receive a direct-copy fallback
 //   - ~/.real/ and other blacklisted paths are NEVER touched
-//   - If no location was updated at all, fall back to ~/.agents/skills/
+//   - canonical publication is mandatory and fails the upgrade loudly
 //
 // Opposite-mode leftovers are backed up to ~/.dws/skill-backups/ and then
 // removed so mono and multi never co-exist after an upgrade; a leftover that
@@ -277,9 +404,54 @@ func buildUpgradeProvenanceRecords(root string, names []string, version string)
 // backups are kept.
 const skillBackupKeep = 5
 
+// The ownership marker inside a stamp root. Every DWS surface writes the
+// exact same bytes (install.sh, install-skills.sh, install-event.sh,
+// install-devapp.sh, the PowerShell installers, and build/npm/install.js):
+// a stamp-shaped directory name alone is not ownership proof, because users
+// and unrelated tools can create 20260819-120000-shaped names. Counting or
+// deleting a backup root requires the marker to verify, and adopting an
+// existing root for a new backup requires it first.
+const (
+	skillBackupMarkerName    = ".dws-skill-backup"
+	skillBackupMarkerContent = "dws skill backup v1\n"
+)
+
+var (
+	skillBackupReadMarker = func(root string) (string, error) {
+		data, err := os.ReadFile(filepath.Join(root, skillBackupMarkerName))
+		return string(data), err
+	}
+	skillBackupWriteMarker = func(root string) error {
+		return os.WriteFile(filepath.Join(root, skillBackupMarkerName), []byte(skillBackupMarkerContent), 0o644)
+	}
+)
+
+// skillBackupMarkerValid reports whether root carries the ownership marker
+// with exactly the expected bytes; a missing, unreadable, or differently
+// worded marker means the directory is foreign data.
+func skillBackupMarkerValid(root string) bool {
+	body, err := skillBackupReadMarker(root)
+	return err == nil && body == skillBackupMarkerContent
+}
+
+// skillBackupStampRegexp matches only directory names DWS itself writes:
+// UTC YYYYmmdd-HHMMSS, with an optional -N collision suffix. Any other entry
+// in the backup root is foreign (user data, unrelated tooling) and must be
+// left untouched, so pruning is restricted to names it can prove DWS created.
+var skillBackupStampRegexp = regexp.MustCompile(`^[0-9]{8}-[0-9]{6}(-[0-9]+)?$`)
+
+// isSkillBackupStamp reports whether name is a DWS-created backup stamp.
+func isSkillBackupStamp(name string) bool {
+	return skillBackupStampRegexp.MatchString(name)
+}
+
 // pruneSkillBackups removes the oldest backup directories when more than
-// skillBackupKeep remain. Best-effort: a removal failure never aborts, but
-// pruning failures are reported so callers can warn the user.
+// skillBackupKeep remain. Only directories whose names match the DWS backup
+// stamp format AND whose ownership marker verifies are candidates; unknown
+// or unmarked directories — including stamp roots created before the
+// ownership marker existed — are foreign data and preserved. Best-effort:
+// a removal failure never aborts, but pruning failures are reported so
+// callers can warn the user.
 func pruneSkillBackups(homeDir string) error {
 	root := filepath.Join(homeDir, skillBackupSubdir)
 	entries, err := upgradeReadDir(root)
@@ -291,7 +463,12 @@ func pruneSkillBackups(homeDir string) error {
 	}
 	names := make([]string, 0, len(entries))
 	for _, e := range entries {
-		if e.IsDir() {
+		if !e.IsDir() || !isSkillBackupStamp(e.Name()) {
+			continue
+		}
+		// A stamp-shaped name alone is not ownership proof: only roots
+		// whose marker verifies are counted or deleted.
+		if skillBackupMarkerValid(filepath.Join(root, e.Name())) {
 			names = append(names, e.Name())
 		}
 	}
@@ -404,20 +581,15 @@ func uniqueSkillDirs(paths []string) []string {
 
 // restoreSkillSet removes any newly published directories, then restores all
 // original directories in reverse backup order.
-func restoreSkillSet(published []string, backups []backedUpSkillDir) error {
-	var restoreErr error
-	for i := len(published) - 1; i >= 0; i-- {
-		if err := upgradeRemoveAll(published[i]); err != nil {
-			restoreErr = errors.Join(restoreErr, fmt.Errorf("移除失败发布目录 %s: %w", published[i], err))
-		}
-	}
+func restoreSkillSet(published []SkillPathPublication, backups []backedUpSkillDir) error {
+	restoreErr := upgradeRollbackPublishedSkillPaths(published)
 	for i := len(backups) - 1; i >= 0; i-- {
 		backup := backups[i]
 		if err := upgradeMkdirAll(filepath.Dir(backup.original), dirPermShared); err != nil {
 			restoreErr = errors.Join(restoreErr, fmt.Errorf("创建 Skill 恢复目录 %s: %w", filepath.Dir(backup.original), err))
 			continue
 		}
-		if err := upgradeRename(backup.backup, backup.original); err != nil {
+		if err := moveSkillPathRecoverably(backup.backup, backup.original); err != nil {
 			restoreErr = errors.Join(restoreErr, fmt.Errorf("恢复原 Skill 失败 %s: %w", backup.original, err))
 		}
 	}
@@ -450,16 +622,17 @@ func publishStagedSkillSet(homeDir string, staged []stagedSkillDir, victims []st
 	if err != nil {
 		return err
 	}
-	published := make([]string, 0, len(staged))
+	published := make([]SkillPathPublication, 0, len(staged))
 	for _, skill := range staged {
-		if err := upgradeRename(skill.staged, skill.dest); err != nil {
-			publishErr := fmt.Errorf("发布 Skill 失败 %s: %w", skill.dest, err)
+		publication, publishErr := upgradePublishSkillPath(skill.staged, skill.dest)
+		if publishErr != nil {
+			publishErr := fmt.Errorf("发布 Skill 失败 %s: %w", skill.dest, publishErr)
 			if restoreErr := restoreSkillSet(published, backups); restoreErr != nil {
 				return errors.Join(publishErr, fmt.Errorf("恢复原 Skill 集合失败: %w", restoreErr))
 			}
 			return publishErr
 		}
-		published = append(published, skill.dest)
+		published = append(published, publication)
 	}
 	return nil
 }
@@ -517,100 +690,274 @@ func publishMultiUpgradeTarget(homeDir, destBase, multiRoot string, skills []str
 	return publishStagedSkillSet(homeDir, staged, victims)
 }
 
-func hasDetectedSpecificSkillRoot(homeDir string) bool {
-	for _, agentDir := range knownSkillDirs {
-		if isGenericSkillRoot(agentDir) || isBlacklisted(agentDir) {
-			continue
-		}
-		parentGate := filepath.Dir(filepath.Join(homeDir, agentDir))
-		if info, err := upgradeStat(parentGate); err == nil && info.IsDir() {
-			return true
-		}
-	}
-	return false
-}
-
 func isGenericSkillRoot(agentDir string) bool {
 	return filepath.Clean(agentDir) == filepath.Clean(".agents/skills")
 }
 
-func retireGenericSkillRoot(homeDir string, managed map[string]bool) error {
-	base := filepath.Join(homeDir, ".agents", "skills")
+func isUniversalSkillRoot(agentDir string) bool {
+	return universalSkillDirs[filepath.ToSlash(filepath.Clean(agentDir))]
+}
+
+type resolvedSkillRoot struct {
+	base      string
+	label     string
+	universal bool
+	canonical bool
+}
+
+func resolveOpenClawSkillBase(homeDir string) string {
+	for _, name := range []string{".openclaw", ".clawdbot", ".moltbot"} {
+		base := filepath.Join(homeDir, name)
+		if info, err := upgradeStat(base); err == nil && info.IsDir() {
+			return filepath.Join(base, "skills")
+		}
+	}
+	return filepath.Join(homeDir, ".openclaw", "skills")
+}
+
+func configuredSkillRoots(homeDir string) []resolvedSkillRoot {
+	var roots []resolvedSkillRoot
+	seen := map[string]bool{}
+	configHome := strings.TrimSpace(upgradeGetenv("XDG_CONFIG_HOME"))
+	if configHome == "" {
+		configHome = filepath.Join(homeDir, ".config")
+	}
+	add := func(base, label string, universal, canonical bool) {
+		key := skillRootPathKey(base)
+		if seen[key] {
+			return
+		}
+		seen[key] = true
+		roots = append(roots, resolvedSkillRoot{base: base, label: label, universal: universal, canonical: canonical})
+	}
+	for _, agentDir := range knownSkillDirs {
+		base := filepath.Join(homeDir, agentDir)
+		switch filepath.ToSlash(filepath.Clean(agentDir)) {
+		case ".claude/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("CLAUDE_CONFIG_DIR")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".codex/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("CODEX_HOME")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".hermes/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("HERMES_HOME")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".autohand/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("AUTOHAND_HOME")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".grok/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("GROK_HOME")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".vibe/skills":
+			if custom := strings.TrimSpace(upgradeGetenv("VIBE_HOME")); custom != "" {
+				base = filepath.Join(custom, "skills")
+			}
+		case ".openclaw/skills":
+			base = resolveOpenClawSkillBase(homeDir)
+		case ".config/agents/skills":
+			base = filepath.Join(configHome, "agents", "skills")
+		case ".config/opencode/skills":
+			base = filepath.Join(configHome, "opencode", "skills")
+		case ".config/crush/skills":
+			base = filepath.Join(configHome, "crush", "skills")
+		case ".config/devin/skills":
+			base = filepath.Join(configHome, "devin", "skills")
+		case ".config/goose/skills":
+			base = filepath.Join(configHome, "goose", "skills")
+		case ".config/kimchi/harness/skills":
+			base = filepath.Join(configHome, "kimchi", "harness", "skills")
+		}
+		add(base, agentDir, isUniversalSkillRoot(agentDir), isGenericSkillRoot(agentDir))
+	}
+	return roots
+}
+
+func skillRootDetectedBase(root resolvedSkillRoot) bool {
+	detectedDir := filepath.Dir(root.base)
+	switch filepath.ToSlash(filepath.Clean(root.label)) {
+	case ".config/kimchi/harness/skills":
+		detectedDir = filepath.Dir(filepath.Dir(root.base))
+	case ".tabnine/agent/skills":
+		detectedDir = filepath.Dir(filepath.Dir(root.base))
+	case ".zcode/skills":
+		// Application bundles are machine-scoped detection signals. Keep this
+		// independent of HOME so upgrade matches npm, Shell, and PowerShell.
+		if info, err := upgradeStat(filepath.Join(string(filepath.Separator), "Applications", "ZCode.app")); err == nil && info.IsDir() {
+			return true
+		}
+	case ".minimax/skills":
+		if info, err := upgradeStat(filepath.Join(string(filepath.Separator), "Applications", "MiniMax Code.app")); err == nil && info.IsDir() {
+			return true
+		}
+	}
+	info, err := upgradeStat(detectedDir)
+	return err == nil && info.IsDir()
+}
+
+func samePhysicalSkillRoot(left, right string) bool {
+	leftReal, leftErr := upgradeEvalSymlinks(left)
+	rightReal, rightErr := upgradeEvalSymlinks(right)
+	if leftErr != nil || rightErr != nil {
+		return false
+	}
+	return skillRootPathKey(leftReal) == skillRootPathKey(rightReal)
+}
+
+func skillRootPathKey(path string) string {
+	clean := filepath.Clean(path)
+	if upgradeFoldPathCase {
+		clean = strings.ToLower(clean)
+	}
+	return clean
+}
+
+func retireManagedSkillRoot(homeDir, base string, managed map[string]bool) error {
 	victims, err := managedMultiSkillVictims(base, managed)
 	if err != nil {
 		return err
 	}
 	victims = append(victims, filepath.Join(base, "dws"))
 	if _, err := backupSkillSet(homeDir, victims); err != nil {
-		return fmt.Errorf("迁移通用 Skill 根目录失败: %w", err)
+		return fmt.Errorf("迁移 Agent Skill 旧副本失败: %w", err)
 	}
 	return nil
 }
 
+func stageLinkedSkillSet(destBase, canonicalBase, prefix string, names []string) (stageRoot string, staged []stagedSkillDir, err error) {
+	if err := upgradeMkdirAll(destBase, dirPermShared); err != nil {
+		return "", nil, fmt.Errorf("创建 Agent Skill 目录失败 %s: %w", destBase, err)
+	}
+	stageRoot, err = upgradeMkdirTemp(destBase, prefix)
+	if err != nil {
+		return "", nil, fmt.Errorf("创建 Skill 链接 staging 失败 %s: %w", destBase, err)
+	}
+	defer func() {
+		if err != nil {
+			_ = upgradeRemoveAll(stageRoot)
+		}
+	}()
+	realDestBase, realErr := upgradeEvalSymlinks(destBase)
+	if realErr != nil {
+		return stageRoot, nil, fmt.Errorf("解析 Agent Skill 物理目录失败 %s: %w", destBase, realErr)
+	}
+	for _, name := range names {
+		target := filepath.Join(canonicalBase, name)
+		realTarget, targetErr := upgradeEvalSymlinks(target)
+		if targetErr != nil {
+			return stageRoot, nil, fmt.Errorf("解析 canonical Skill 失败 %s: %w", target, targetErr)
+		}
+		relTarget, relErr := upgradeRel(realDestBase, realTarget)
+		if relErr != nil {
+			return stageRoot, nil, fmt.Errorf("计算 Skill 相对链接失败 %s: %w", target, relErr)
+		}
+		stagedPath := filepath.Join(stageRoot, name)
+		if linkErr := upgradeSymlink(relTarget, stagedPath); linkErr != nil {
+			return stageRoot, nil, fmt.Errorf("创建 Skill 链接失败 %s -> %s: %w", stagedPath, relTarget, linkErr)
+		}
+		staged = append(staged, stagedSkillDir{staged: stagedPath, dest: filepath.Join(destBase, name)})
+	}
+	return stageRoot, staged, nil
+}
+
+func publishLinkedUpgradeTarget(homeDir, destBase, canonicalBase string, names []string, victims []string) error {
+	needed := make([]string, 0, len(names))
+	correct := make(map[string]bool, len(names))
+	for _, name := range names {
+		dest := filepath.Join(destBase, name)
+		canonical := filepath.Join(canonicalBase, name)
+		if samePhysicalSkillRoot(dest, canonical) {
+			correct[filepath.Clean(dest)] = true
+			continue
+		}
+		needed = append(needed, name)
+	}
+	filteredVictims := make([]string, 0, len(victims))
+	for _, victim := range victims {
+		if !correct[filepath.Clean(victim)] {
+			filteredVictims = append(filteredVictims, victim)
+		}
+	}
+	stageRoot, staged, err := stageLinkedSkillSet(destBase, canonicalBase, ".dws-link-set-", needed)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = upgradeRemoveAll(stageRoot) }()
+	return publishStagedSkillSet(homeDir, staged, filteredVictims)
+}
+
 // upgradeMonoSkillLocations is the legacy mono behavior: one dws/ directory
 // per agent home.
 func upgradeMonoSkillLocations(homeDir, skillSrc string) (*SkillUpgradeResult, error) {
 	result := &SkillUpgradeResult{}
 	managedNames := readManagedSkillNames(homeDir)
-	hasSpecificRoot := hasDetectedSpecificSkillRoot(homeDir)
+	canonicalBase := filepath.Join(homeDir, ".agents", "skills")
+	canonicalDest := filepath.Join(canonicalBase, "dws")
+	if err := publishMonoUpgradeTarget(homeDir, canonicalBase, skillSrc, managedNames); err != nil {
+		result.Results = append(result.Results, SkillDirResult{Dir: canonicalDest, Status: SkillDirFailed, Err: err})
+		// Canonical is the mandatory store: universal agents read it directly, so a
+		// failed canonical publish means nobody received the upgrade. Always fail
+		// loud — including universal-only machines — instead of reporting success
+		// with nothing installed.
+		return result, fmt.Errorf("canonical Skill 安装失败: %w", err)
+	}
+	result.Results = append(result.Results, SkillDirResult{Dir: canonicalDest, Status: SkillDirOK})
 
-	for _, agentDir := range knownSkillDirs {
-		destDir := filepath.Join(homeDir, agentDir, "dws")
-
-		if isBlacklisted(agentDir) {
+	for _, root := range configuredSkillRoots(homeDir) {
+		if root.canonical {
+			continue
+		}
+		destBase := root.base
+		destDir := filepath.Join(destBase, "dws")
+		if isBlacklisted(root.label) {
 			result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirBlacklisted})
 			continue
 		}
-		if isGenericSkillRoot(agentDir) && hasSpecificRoot {
+		if !skillRootDetectedBase(root) {
+			result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirSkipped})
 			continue
 		}
-
-		if !isGenericSkillRoot(agentDir) {
-			parentGate := filepath.Dir(filepath.Join(homeDir, agentDir))
-			if _, err := upgradeStat(parentGate); os.IsNotExist(err) {
+		if samePhysicalSkillRoot(destBase, canonicalBase) {
+			result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirSkipped})
+			continue
+		}
+		if root.universal {
+			if err := retireManagedSkillRoot(homeDir, destBase, managedNames); err != nil {
+				// Nothing is installed below a universal root, so a stale copy that
+				// resists retirement is a warning, not an install failure.
+				result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirRetireWarning, Err: err})
+			} else {
 				result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirSkipped})
+			}
+			continue
+		}
+		victims, victimErr := monoUpgradeVictims(destBase, destDir, managedNames)
+		if victimErr != nil {
+			result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirFailed, Err: victimErr})
+			continue
+		}
+		if err := publishLinkedUpgradeTarget(homeDir, destBase, canonicalBase, []string{"dws"}, victims); err != nil {
+			// An uncertain destination may belong to a concurrent writer.
+			// The copy fallback below would back that object aside and
+			// replace it — exactly what the sentinel forbids — so surface
+			// the uncertain state instead of retrying over it.
+			if errors.Is(err, ErrSkillPathPublicationUncertain) {
+				result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirFailed, Err: err})
+				continue
+			}
+			// Match the upstream installer: platforms/filesystems that reject
+			// links receive a direct copy rather than losing Agent support.
+			if copyErr := publishMonoUpgradeTarget(homeDir, destBase, skillSrc, managedNames); copyErr != nil {
+				result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirFailed, Err: errors.Join(err, copyErr)})
 				continue
 			}
 		}
-
-		if err := publishMonoUpgradeTarget(homeDir, filepath.Join(homeDir, agentDir), skillSrc, managedNames); err != nil {
-			result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirFailed, Err: err})
-			continue
-		}
 		result.Results = append(result.Results, SkillDirResult{Dir: destDir, Status: SkillDirOK})
 	}
-	if hasSpecificRoot && len(result.Succeeded()) > 0 {
-		genericBase := filepath.Join(homeDir, ".agents", "skills")
-		if err := retireGenericSkillRoot(homeDir, managedNames); err != nil {
-			result.Results = append(result.Results, SkillDirResult{Dir: genericBase, Status: SkillDirFailed, Err: err})
-		} else {
-			result.Results = append(result.Results, SkillDirResult{Dir: genericBase, Status: SkillDirSkipped})
-		}
-	}
-
-	// Fallback: if nothing succeeded, force the primary location. The multi
-	// leftovers under the primary base are the usual reason the primary
-	// install failed, so clean them first — failing loud like the multi
-	// fallback — instead of letting mono and multi co-exist marked OK.
-	if len(result.Succeeded()) == 0 && !hasSpecificRoot {
-		destBase := filepath.Join(homeDir, ".agents", "skills")
-		dest := filepath.Join(destBase, "dws")
-		if err := publishMonoUpgradeTarget(homeDir, destBase, skillSrc, managedNames); err != nil {
-			return result, fmt.Errorf("所有技能目录安装失败，回退到主目录也失败: %w", err)
-		}
-		// Replace the earlier failed entry for this dir (if any) or append a new one
-		replaced := false
-		for idx, r := range result.Results {
-			if r.Dir == dest {
-				result.Results[idx] = SkillDirResult{Dir: dest, Status: SkillDirOK}
-				replaced = true
-				break
-			}
-		}
-		if !replaced {
-			result.Results = append(result.Results, SkillDirResult{Dir: dest, Status: SkillDirOK})
-		}
-	}
 
 	// Best-effort: refresh the user-level mono cache so that
 	// `dws skill setup --mode mono` fallbacks stay on the upgraded version
@@ -633,61 +980,62 @@ func upgradeMultiSkillLocations(homeDir, multiRoot string, skills []string) (*Sk
 
 	result := &SkillUpgradeResult{}
 	managedNames := readManagedSkillNames(homeDir)
-	hasSpecificRoot := hasDetectedSpecificSkillRoot(homeDir)
+	canonicalBase := filepath.Join(homeDir, ".agents", "skills")
+	if err := publishMultiUpgradeTarget(homeDir, canonicalBase, multiRoot, skills, skillSet, managedNames); err != nil {
+		result.Results = append(result.Results, SkillDirResult{Dir: canonicalBase, Status: SkillDirFailed, Err: err})
+		// Canonical is the mandatory store (see the mono branch): fail loud even
+		// on universal-only machines instead of reporting success with nothing
+		// installed.
+		return result, fmt.Errorf("canonical Skill 安装失败: %w", err)
+	}
+	result.Results = append(result.Results, SkillDirResult{Dir: canonicalBase, Status: SkillDirOK})
 
-	for _, agentDir := range knownSkillDirs {
-		destBase := filepath.Join(homeDir, agentDir)
-
-		if isBlacklisted(agentDir) {
+	for _, root := range configuredSkillRoots(homeDir) {
+		if root.canonical {
+			continue
+		}
+		destBase := root.base
+		if isBlacklisted(root.label) {
 			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirBlacklisted})
 			continue
 		}
-		if isGenericSkillRoot(agentDir) && hasSpecificRoot {
+		if !skillRootDetectedBase(root) {
+			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirSkipped})
 			continue
 		}
-
-		if !isGenericSkillRoot(agentDir) {
-			parentGate := filepath.Dir(destBase)
-			if _, err := upgradeStat(parentGate); os.IsNotExist(err) {
+		if samePhysicalSkillRoot(destBase, canonicalBase) {
+			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirSkipped})
+			continue
+		}
+		if root.universal {
+			if err := retireManagedSkillRoot(homeDir, destBase, managedNames); err != nil {
+				// Nothing is installed below a universal root, so a stale copy that
+				// resists retirement is a warning, not an install failure.
+				result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirRetireWarning, Err: err})
+			} else {
 				result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirSkipped})
+			}
+			continue
+		}
+		victims, victimErr := multiUpgradeVictims(destBase, skillSet, skills, managedNames)
+		if victimErr != nil {
+			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirFailed, Err: victimErr})
+			continue
+		}
+		if err := publishLinkedUpgradeTarget(homeDir, destBase, canonicalBase, skills, victims); err != nil {
+			// An uncertain destination may belong to a concurrent writer;
+			// the copy fallback must not displace it (see the mono branch).
+			if errors.Is(err, ErrSkillPathPublicationUncertain) {
+				result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirFailed, Err: err})
+				continue
+			}
+			if copyErr := publishMultiUpgradeTarget(homeDir, destBase, multiRoot, skills, skillSet, managedNames); copyErr != nil {
+				result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirFailed, Err: errors.Join(err, copyErr)})
 				continue
 			}
 		}
-
-		if err := publishMultiUpgradeTarget(homeDir, destBase, multiRoot, skills, skillSet, managedNames); err != nil {
-			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirFailed, Err: err})
-			continue
-		}
 		result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirOK})
 	}
-	if hasSpecificRoot && len(result.Succeeded()) > 0 {
-		genericBase := filepath.Join(homeDir, ".agents", "skills")
-		if err := retireGenericSkillRoot(homeDir, managedNames); err != nil {
-			result.Results = append(result.Results, SkillDirResult{Dir: genericBase, Status: SkillDirFailed, Err: err})
-		} else {
-			result.Results = append(result.Results, SkillDirResult{Dir: genericBase, Status: SkillDirSkipped})
-		}
-	}
-
-	// Fallback: if nothing succeeded, force the primary location
-	if len(result.Succeeded()) == 0 && !hasSpecificRoot {
-		destBase := filepath.Join(homeDir, ".agents", "skills")
-		if err := publishMultiUpgradeTarget(homeDir, destBase, multiRoot, skills, skillSet, managedNames); err != nil {
-			return result, fmt.Errorf("所有技能目录安装失败，回退到主目录也失败: %w", err)
-		}
-		// Replace the earlier failed entry for this dir (if any) or append a new one
-		replaced := false
-		for idx, r := range result.Results {
-			if r.Dir == destBase {
-				result.Results[idx] = SkillDirResult{Dir: destBase, Status: SkillDirOK}
-				replaced = true
-				break
-			}
-		}
-		if !replaced {
-			result.Results = append(result.Results, SkillDirResult{Dir: destBase, Status: SkillDirOK})
-		}
-	}
 
 	// Best-effort: refresh the user-level caches so that `dws skill setup`
 	// fallbacks stay on the upgraded version. The release zip ships both
@@ -762,23 +1110,6 @@ func skillTreeHasRoot(dir string) bool {
 	return err == nil && !info.IsDir()
 }
 
-// cleanupMultiLeftovers backs up + removes every proven DWS-managed
-// multi-mode skill directory inside one agent home before mono is installed.
-// A missing base directory simply means no leftovers; any other read failure
-// is reported so mono never silently co-exists with multi. Removal is
-// reversible: each leftover is preserved under ~/.dws/skill-backups/ and a
-// backup failure aborts the removal for that home.
-func cleanupMultiLeftovers(homeDir, baseDir string) error {
-	victims, err := managedMultiSkillVictims(baseDir, readManagedSkillNames(homeDir))
-	if err != nil {
-		return err
-	}
-	if _, err := backupSkillSet(homeDir, victims); err != nil {
-		return fmt.Errorf("备份并清理 multi 残留失败: %w", err)
-	}
-	return nil
-}
-
 func managedMultiSkillVictims(baseDir string, managed ...map[string]bool) ([]string, error) {
 	entries, err := upgradeReadDir(baseDir)
 	if err != nil {
@@ -789,7 +1120,7 @@ func managedMultiSkillVictims(baseDir string, managed ...map[string]bool) ([]str
 	}
 	victims := make([]string, 0)
 	for _, e := range entries {
-		if !e.IsDir() || !isManagedMultiSkillDir(filepath.Join(baseDir, e.Name()), managed...) {
+		if (!e.IsDir() && e.Type()&os.ModeSymlink == 0) || !isManagedMultiSkillDir(filepath.Join(baseDir, e.Name()), managed...) {
 			continue
 		}
 		victims = append(victims, filepath.Join(baseDir, e.Name()))
@@ -797,24 +1128,6 @@ func managedMultiSkillVictims(baseDir string, managed ...map[string]bool) ([]str
 	return victims, nil
 }
 
-// cleanupOppositeModeLeftovers backs up + removes, inside one agent home, the
-// legacy mono directory (dws/) and every proven DWS-managed multi skill
-// directory that is not part of the new bundle. A dingtalk-* prefix alone is
-// not proof of ownership because market/user skills may use the same prefix.
-// Removal is reversible: each
-// directory is preserved under ~/.dws/skill-backups/ and a backup failure
-// aborts the removal for that home.
-func cleanupOppositeModeLeftovers(homeDir, destBase string, skillSet map[string]bool) error {
-	victims, err := oppositeModeSkillVictims(destBase, skillSet, readManagedSkillNames(homeDir))
-	if err != nil {
-		return err
-	}
-	if _, err := backupSkillSet(homeDir, victims); err != nil {
-		return fmt.Errorf("备份并清理对面模式残留失败: %w", err)
-	}
-	return nil
-}
-
 func oppositeModeSkillVictims(destBase string, skillSet map[string]bool, managed ...map[string]bool) ([]string, error) {
 	victims := []string{filepath.Join(destBase, "dws")}
 	entries, err := upgradeReadDir(destBase)
@@ -825,7 +1138,7 @@ func oppositeModeSkillVictims(destBase string, skillSet map[string]bool, managed
 		return nil, fmt.Errorf("读取技能目录失败 %s: %w", destBase, err)
 	}
 	for _, e := range entries {
-		if !e.IsDir() || skillSet[e.Name()] || !isManagedMultiSkillDir(filepath.Join(destBase, e.Name()), managed...) {
+		if (!e.IsDir() && e.Type()&os.ModeSymlink == 0) || skillSet[e.Name()] || !isManagedMultiSkillDir(filepath.Join(destBase, e.Name()), managed...) {
 			continue
 		}
 		victims = append(victims, filepath.Join(destBase, e.Name()))

internal/upgrade/paths_multi_test.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"runtime"
 	"strings"
 	"testing"
 
@@ -22,6 +23,16 @@ func withFakeHome(t *testing.T) string {
 	t.Helper()
 	home := t.TempDir()
 	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home, nil })
+	// Host-installed macOS apps must not make a fake HOME appear to have extra
+	// detected Agents. Tests that exercise application-based detection can
+	// override this seam explicitly.
+	testseam.Swap(t, &upgradeStat, func(path string) (os.FileInfo, error) {
+		applications := filepath.Join(string(filepath.Separator), "Applications")
+		if path == filepath.Join(applications, "ZCode.app") || path == filepath.Join(applications, "MiniMax Code.app") {
+			return nil, os.ErrNotExist
+		}
+		return os.Stat(path)
+	})
 	return home
 }
 
@@ -124,8 +135,7 @@ func TestCrossPlatformCoverageBundleSkillNamesLayouts(t *testing.T) {
 func TestCrossPlatformCoverageUpgradeSkillLocationsMulti(t *testing.T) {
 	home := withFakeHome(t)
 
-	// A concrete Agent root wins over the generic .agents fallback; .claude
-	// installs and .cursor is skipped.
+	// .agents is canonical; detected Claude receives links and Cursor is skipped.
 	agentsBase := filepath.Join(home, ".agents", "skills")
 	claudeBase := filepath.Join(home, ".claude", "skills")
 	for _, base := range []string{agentsBase, claudeBase} {
@@ -193,17 +203,19 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMulti(t *testing.T) {
 
 	// Succeeded entries report the agent home base in multi mode.
 	succeeded := result.Succeeded()
-	if len(succeeded) != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 (%v)", len(succeeded), result.Results)
+	if len(succeeded) != 2 {
+		t.Fatalf("Succeeded() len = %d, want 2 (%v)", len(succeeded), result.Results)
 	}
-	wantDirs := map[string]bool{claudeBase: true}
+	wantDirs := map[string]bool{agentsBase: true, claudeBase: true}
 	for _, d := range succeeded {
 		if !wantDirs[d.Dir] {
 			t.Errorf("unexpected succeeded dir %q", d.Dir)
 		}
 	}
-	if _, err := os.Stat(filepath.Join(agentsBase, "dws")); !os.IsNotExist(err) {
-		t.Fatalf("generic mono duplicate still visible: %v", err)
+	for _, name := range []string{"dingtalk-chat", "dws-shared"} {
+		if _, err := os.Stat(filepath.Join(agentsBase, name, "SKILL.md")); err != nil {
+			t.Fatalf("canonical Skill missing: %v", err)
+		}
 	}
 
 	// Multi cache refreshed under the fake home.
@@ -216,7 +228,7 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMulti(t *testing.T) {
 	}
 }
 
-func TestCrossPlatformCoverageUpgradeUsesAgentSpecificRootWithoutGenericDuplicate(t *testing.T) {
+func TestCrossPlatformCoverageUpgradeUsesCanonicalRootWithoutCodexDuplicate(t *testing.T) {
 	home := withFakeHome(t)
 	testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".codex/skills"})
 
@@ -241,12 +253,12 @@ func TestCrossPlatformCoverageUpgradeUsesAgentSpecificRootWithoutGenericDuplicat
 		t.Fatalf("UpgradeSkillLocationsWithOptions() = %#v, %v", result, err)
 	}
 
-	want := filepath.Join(codexBase, "dingtalk-chat", "SKILL.md")
+	want := filepath.Join(genericBase, "dingtalk-chat", "SKILL.md")
 	if _, err := os.Stat(want); err != nil {
-		t.Fatalf("canonical Codex Skill missing at %s: %v", want, err)
+		t.Fatalf("canonical Skill missing at %s: %v", want, err)
 	}
 	for _, duplicate := range []string{
-		filepath.Join(genericBase, "dingtalk-chat", "SKILL.md"),
+		filepath.Join(codexBase, "dingtalk-chat"),
 		filepath.Join(genericBase, "dws", "multi", "dingtalk-chat", "SKILL.md"),
 	} {
 		if _, err := os.Stat(duplicate); !os.IsNotExist(err) {
@@ -502,6 +514,9 @@ func TestUpgradeMonoCleansPreStateOfficialAndPreservesCustom(t *testing.T) {
 // mono-only package path).
 func TestCrossPlatformCoverageUpgradeSkillLocationsMonoFallbackAfterCopyFailure(t *testing.T) {
 	home := withFakeHome(t)
+	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
 	agentsBase := filepath.Join(home, ".agents", "skills")
 	if err := os.MkdirAll(filepath.Join(agentsBase, "dws"), 0o755); err != nil {
 		t.Fatal(err)
@@ -526,21 +541,15 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMonoFallbackAfterCopyFailure(
 	}
 
 	result, err := UpgradeSkillLocations(mono)
-	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v", err)
-	}
-	if failed := result.Failed(); len(failed) != 0 {
-		t.Fatalf("fallback should replace the failed entry with OK, got failed=%v", failed)
-	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 (%v)", got, result.Results)
+	if err == nil || len(result.Failed()) != 1 || len(result.Succeeded()) != 0 {
+		t.Fatalf("canonical copy failure = %#v, %v", result, err)
 	}
 	data, err := os.ReadFile(filepath.Join(agentsBase, "dws", "SKILL.md"))
 	if err != nil {
 		t.Fatalf("mono fallback install missing: %v", err)
 	}
-	if string(data) != "# mono" {
-		t.Errorf("mono content = %q, want refreshed package", data)
+	if string(data) != "old" {
+		t.Errorf("mono content = %q, want original preserved", data)
 	}
 }
 
@@ -574,22 +583,22 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMonoReadDirErrorFailsHome(t *
 	}
 
 	result, err := UpgradeSkillLocations(mono)
-	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v (fallback should not run: .claude succeeded)", err)
+	if err == nil {
+		t.Fatal("canonical read failure must fail the upgrade")
 	}
 	failed := result.Failed()
 	if len(failed) != 1 {
 		t.Fatalf("Failed() len = %d, want 1 (%v)", len(failed), result.Results)
 	}
-	wantDir := agentsBase
+	wantDir := filepath.Join(agentsBase, "dws")
 	if failed[0].Dir != wantDir || failed[0].Err == nil {
 		t.Fatalf("failed entry = %#v, want dir %q with non-nil err", failed[0], wantDir)
 	}
 	if !strings.Contains(failed[0].Err.Error(), "读取技能目录失败") {
 		t.Fatalf("failed err should mention the read failure, got %v", failed[0].Err)
 	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 (.claude)", got)
+	if got := len(result.Succeeded()); got != 0 {
+		t.Fatalf("Succeeded() len = %d, want 0", got)
 	}
 	// Mono must NOT have been laid down next to the unreadable multi state.
 	if _, err := os.Stat(filepath.Join(agentsBase, "dws")); !os.IsNotExist(err) {
@@ -603,6 +612,9 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMonoReadDirErrorFailsHome(t *
 // installing multi next to the stale skills.
 func TestCrossPlatformCoverageUpgradeSkillLocationsMultiFallbackCleanupFailure(t *testing.T) {
 	home := withFakeHome(t)
+	if err := os.MkdirAll(filepath.Join(home, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
 	agentsBase := filepath.Join(home, ".agents", "skills")
 	staleDir := filepath.Join(agentsBase, "dingtalk-stale")
 	if err := os.MkdirAll(staleDir, 0o755); err != nil {
@@ -613,10 +625,10 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMultiFallbackCleanupFailure(t
 	}
 	useUpgradeManagedNames(t, filepath.Base(staleDir))
 
-	origRename := upgradeRename
-	testseam.Swap(t, &upgradeRename, func(src, dst string) error {
+	origRename := skillPathRenameNoReplace
+	testseam.Swap(t, &skillPathRenameNoReplace, func(src, dst string) (string, error) {
 		if strings.Contains(src, "dingtalk-stale") {
-			return errors.New("injected backup failure")
+			return "", errors.New("injected backup failure")
 		}
 		return origRename(src, dst)
 	})
@@ -628,8 +640,8 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMultiFallbackCleanupFailure(t
 	if err == nil {
 		t.Fatal("multi fallback cleanup failure must return an error")
 	}
-	if !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("error should mention the fallback cleanup failure, got %v", err)
+	if !strings.Contains(err.Error(), "canonical Skill 安装失败") {
+		t.Fatalf("error should mention the canonical cleanup failure, got %v", err)
 	}
 	if failed := result.Failed(); len(failed) != 1 {
 		t.Fatalf("Failed() len = %d, want 1 (%v)", len(failed), result.Results)
@@ -643,8 +655,17 @@ func TestCrossPlatformCoverageUpgradeSkillLocationsMultiFallbackCleanupFailure(t
 	}
 }
 
+// seedSkillBackupMarker stamps a backup root as DWS-owned, the way every
+// install surface does before any payload moves in.
+func seedSkillBackupMarker(t *testing.T, root string) {
+	t.Helper()
+	if err := os.WriteFile(filepath.Join(root, skillBackupMarkerName), []byte(skillBackupMarkerContent), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
 // TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges pins the fail-safe
-// contract of the backup helper: non-dir paths are no-ops, a colliding backup
+// contract of the backup helper: all lexical paths are preserved, a colliding backup
 // target gets a numbered stamp, and any failure (mkdir / rename / unresolvable
 // collision) leaves the original directory untouched with an error.
 func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
@@ -654,8 +675,8 @@ func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
 	// backup. Inject it through the path seam so this branch is portable to
 	// Windows, where chmod-based permission failures are not reliable.
 	statFailurePath := filepath.Join(home, "stat-failure")
-	origStat := upgradeStat
-	testseam.Swap(t, &upgradeStat, func(path string) (os.FileInfo, error) {
+	origStat := upgradeLstat
+	testseam.Swap(t, &upgradeLstat, func(path string) (os.FileInfo, error) {
 		if path == statFailurePath {
 			return nil, errors.New("injected stat failure")
 		}
@@ -665,16 +686,16 @@ func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
 		t.Fatalf("stat failure = (%q, %v), want wrapped error", got, err)
 	}
 
-	// Regular file: no-op, no backup.
+	// Regular file: preserve it instead of allowing a later rename to overwrite it.
 	filePath := filepath.Join(home, "not-a-dir")
 	if err := os.WriteFile(filePath, []byte("x"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if got, err := backupAndRemoveSkillDir(home, filePath); got != "" || err != nil {
-		t.Fatalf("regular file = (%q, %v), want no-op", got, err)
+	if got, err := backupAndRemoveSkillDir(home, filePath); got == "" || err != nil {
+		t.Fatalf("regular file = (%q, %v), want backup", got, err)
 	}
-	if _, err := os.Stat(filePath); err != nil {
-		t.Fatalf("regular file must survive: %v", err)
+	if _, err := os.Stat(filePath); !os.IsNotExist(err) {
+		t.Fatalf("regular file must move into backup: %v", err)
 	}
 
 	// A skill directory outside home falls back to its basename instead of
@@ -722,6 +743,46 @@ func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
 		t.Fatalf("victim must be gone after backup, stat err=%v", err)
 	}
 
+	// A dangling link at the first backup target is still an occupied lexical
+	// path and must select a numbered target rather than being overwritten.
+	danglingVictim := filepath.Join(home, ".agents", "skills", "dangling-collision")
+	if err := os.MkdirAll(danglingVictim, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	danglingTaken := filepath.Join(home, skillBackupSubdir, "20260810-000000", ".agents-skills-dangling-collision")
+	if err := os.Symlink("missing-backup", danglingTaken); err == nil {
+		got, err = backupAndRemoveSkillDir(home, danglingVictim)
+		if err != nil {
+			t.Fatalf("backup with dangling collision error = %v", err)
+		}
+		want = filepath.Join(home, skillBackupSubdir, "20260810-000000-1", ".agents-skills-dangling-collision")
+		if got != want {
+			t.Fatalf("dangling collision backup path = %q, want %q", got, want)
+		}
+	} else if runtime.GOOS != "windows" {
+		t.Fatal(err)
+	}
+
+	// An unreadable target probe is not equivalent to a free path.
+	probeVictim := filepath.Join(home, "probe-victim")
+	if err := os.MkdirAll(probeVictim, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	probeTarget := filepath.Join(home, skillBackupSubdir, "20260810-000000", "probe-victim")
+	testseam.Swap(t, &upgradeLstat, func(path string) (os.FileInfo, error) {
+		if path == probeTarget {
+			return nil, errors.New("target probe denied")
+		}
+		return os.Lstat(path)
+	})
+	if _, err := backupAndRemoveSkillDir(home, probeVictim); err == nil || !strings.Contains(err.Error(), "检查备份目标失败") {
+		t.Fatalf("target probe error = %v", err)
+	}
+	if _, err := os.Stat(probeVictim); err != nil {
+		t.Fatalf("probe victim must survive target check failure: %v", err)
+	}
+	testseam.Swap(t, &upgradeLstat, os.Lstat)
+
 	// Unresolvable collision (>1000 numbered stamps taken) fails and keeps dir.
 	victim2 := filepath.Join(home, "victim2")
 	if err := os.MkdirAll(victim2, 0o755); err != nil {
@@ -749,7 +810,7 @@ func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
 		t.Fatal(err)
 	}
 	testseam.Swap(t, &upgradeMkdirAll, func(string, os.FileMode) error { return errors.New("mkdir denied") })
-	if _, err := backupAndRemoveSkillDir(home, victim3); err == nil || !strings.Contains(err.Error(), "创建备份目录失败") {
+	if _, err := backupAndRemoveSkillDir(home, victim3); err == nil || !strings.Contains(err.Error(), "创建备份根目录失败") {
 		t.Fatalf("mkdir error = %v", err)
 	}
 	if _, err := os.Stat(victim3); err != nil {
@@ -762,14 +823,14 @@ func TestCrossPlatformCoverageBackupAndRemoveSkillDirEdges(t *testing.T) {
 	if err := os.MkdirAll(victim4, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	testseam.Swap(t, &upgradeRename, func(string, string) error { return errors.New("rename denied") })
+	testseam.Swap(t, &skillPathRenameNoReplace, func(string, string) (string, error) { return "", errors.New("rename denied") })
 	if _, err := backupAndRemoveSkillDir(home, victim4); err == nil || !strings.Contains(err.Error(), "备份技能目录失败") {
 		t.Fatalf("rename error = %v", err)
 	}
 	if _, err := os.Stat(victim4); err != nil {
 		t.Fatalf("victim4 must survive rename failure: %v", err)
 	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
+	testseam.Swap(t, &skillPathRenameNoReplace, renameSkillPathNoReplace)
 }
 
 // TestCrossPlatformCoveragePruneSkillBackupsEdges pins the backup retention:
@@ -779,9 +840,11 @@ func TestCrossPlatformCoveragePruneSkillBackupsEdges(t *testing.T) {
 	home := t.TempDir()
 	root := filepath.Join(home, skillBackupSubdir)
 	for i := 0; i < skillBackupKeep+2; i++ {
-		if err := os.MkdirAll(filepath.Join(root, fmt.Sprintf("20260810-00000%d", i)), 0o755); err != nil {
+		stampDir := filepath.Join(root, fmt.Sprintf("20260810-00000%d", i))
+		if err := os.MkdirAll(stampDir, 0o755); err != nil {
 			t.Fatal(err)
 		}
+		seedSkillBackupMarker(t, stampDir)
 	}
 	if err := pruneSkillBackups(home); err != nil {
 		t.Fatalf("pruneSkillBackups() error = %v", err)
@@ -814,9 +877,11 @@ func TestCrossPlatformCoveragePruneSkillBackupsEdges(t *testing.T) {
 	// Removal failure is reported as the first error. Seed more than
 	// skillBackupKeep dirs again so the prune loop actually runs.
 	for i := 0; i < skillBackupKeep+2; i++ {
-		if err := os.MkdirAll(filepath.Join(root, fmt.Sprintf("20260811-00000%d", i)), 0o755); err != nil {
+		stampDir := filepath.Join(root, fmt.Sprintf("20260811-00000%d", i))
+		if err := os.MkdirAll(stampDir, 0o755); err != nil {
 			t.Fatal(err)
 		}
+		seedSkillBackupMarker(t, stampDir)
 	}
 	testseam.Swap(t, &upgradeRemoveAll, func(string) error { return errors.New("remove denied") })
 	if err := pruneSkillBackups(home); err == nil {
@@ -825,6 +890,86 @@ func TestCrossPlatformCoveragePruneSkillBackupsEdges(t *testing.T) {
 	testseam.Swap(t, &upgradeRemoveAll, os.RemoveAll)
 }
 
+// TestCrossPlatformCoveragePruneSkillBackupsPreservesUnknown pins that
+// pruneSkillBackups only retires directories whose names match the DWS backup
+// stamp format. Any foreign directory in the backup root must survive even when
+// more than skillBackupKeep stamped backups exist.
+func TestCrossPlatformCoveragePruneSkillBackupsPreservesUnknown(t *testing.T) {
+	home := t.TempDir()
+	root := filepath.Join(home, skillBackupSubdir)
+	for i := 0; i < skillBackupKeep+2; i++ {
+		stampDir := filepath.Join(root, fmt.Sprintf("20260910-00000%d", i))
+		if err := os.MkdirAll(stampDir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		seedSkillBackupMarker(t, stampDir)
+	}
+	// A collision-suffixed stamp is still a valid DWS backup and is eligible.
+	suffixed := filepath.Join(root, "20260910-000000-7")
+	if err := os.MkdirAll(suffixed, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	seedSkillBackupMarker(t, suffixed)
+	// Stamp-shaped names without a verifying marker are foreign data too:
+	// the name format alone proves nothing.
+	unmarked := filepath.Join(root, "20260901-000000")
+	if err := os.MkdirAll(unmarked, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(unmarked, "user-data.txt"), []byte("must survive"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	wrongMarker := filepath.Join(root, "20260902-000000")
+	if err := os.MkdirAll(wrongMarker, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(wrongMarker, skillBackupMarkerName), []byte("not dws"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	unknown := []string{
+		"user-personal-backup",
+		"20260910-000000-abc", // stamp-shaped but non-numeric suffix
+		"20260910-00000",      // too short
+		"notes",
+		"20260901-000000", // stamp-shaped but unmarked
+		"20260902-000000", // stamp-shaped but wrong marker content
+	}
+	for _, name := range unknown {
+		if err := os.MkdirAll(filepath.Join(root, name), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	if err := pruneSkillBackups(home); err != nil {
+		t.Fatalf("pruneSkillBackups() error = %v", err)
+	}
+
+	for _, name := range unknown {
+		if _, err := os.Stat(filepath.Join(root, name)); err != nil {
+			t.Errorf("unknown backup entry %s must be preserved, stat err=%v", name, err)
+		}
+	}
+	// Only marker-proven backups beyond skillBackupKeep are pruned; foreign
+	// entries (including unmarked stamp-shaped ones) are excluded from the
+	// count, so the proven total stays at skillBackupKeep.
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proven := 0
+	for _, e := range entries {
+		if isSkillBackupStamp(e.Name()) && skillBackupMarkerValid(filepath.Join(root, e.Name())) {
+			proven++
+		}
+	}
+	if proven != skillBackupKeep {
+		t.Errorf("marker-proven backups after prune = %d, want %d", proven, skillBackupKeep)
+	}
+	if data, err := os.ReadFile(filepath.Join(unmarked, "user-data.txt")); err != nil || string(data) != "must survive" {
+		t.Errorf("unmarked stamp-shaped data must survive, got %q, %v", data, err)
+	}
+}
+
 // TestCrossPlatformCoverageResolveSkillSrcLayouts pins every fallback branch of
 // the mono-source resolver and the multi-bundle child lookup.
 func TestCrossPlatformCoverageResolveSkillSrcLayouts(t *testing.T) {
@@ -888,88 +1033,27 @@ func TestCrossPlatformCoverageResolveSkillSrcLayouts(t *testing.T) {
 // TestCrossPlatformCoverageMonoUpgradeBackupAndFallbackEdges pins the mono
 // path's fail-loud backup semantics and every primary-fallback outcome.
 func TestCrossPlatformCoverageMonoUpgradeBackupAndFallbackEdges(t *testing.T) {
-	originalDirs := append([]string(nil), knownSkillDirs...)
-	t.Cleanup(func() { knownSkillDirs = originalDirs })
-
 	mono := t.TempDir()
 	if err := os.WriteFile(filepath.Join(mono, "SKILL.md"), []byte("# mono"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-
-	// Per-home backup failure marks that home failed; another home still wins.
 	home := withFakeHome(t)
-	knownSkillDirs = []string{".agents/skills", ".claude/skills"}
+	testseam.Swap(t, &knownSkillDirs, []string{".agents/skills", ".claude/skills"})
 	os.MkdirAll(filepath.Join(home, ".agents", "skills", "dws"), 0o755)
 	os.WriteFile(filepath.Join(home, ".agents", "skills", "dws", "SKILL.md"), []byte("old"), 0o644)
 	os.MkdirAll(filepath.Join(home, ".claude"), 0o755)
-	testseam.Swap(t, &upgradeRename, func(src, dst string) error {
+	testseam.Swap(t, &skillPathRenameNoReplace, func(src, dst string) (string, error) {
 		if strings.Contains(src, ".agents") {
-			return errors.New("backup denied")
+			return "", errors.New("backup denied")
 		}
-		return os.Rename(src, dst)
+		return renameSkillPathNoReplace(src, dst)
 	})
 	result, err := UpgradeSkillLocations(mono)
-	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v", err)
-	}
-	if failed := result.Failed(); len(failed) != 1 || failed[0].Err == nil {
-		t.Fatalf("failed = %v, want exactly 1 backup-failed home", failed)
+	if err == nil || len(result.Failed()) != 1 || len(result.Succeeded()) != 0 {
+		t.Fatalf("canonical backup failure = %#v, %v", result, err)
 	}
 	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dws", "SKILL.md")); err != nil {
-		t.Fatalf("failed home must keep its original dws/: %v", err)
-	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 (.claude)", got)
-	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
-
-	// Fallback cleanup failure: only a blacklisted home in the main loop, then
-	// the primary cleanup hits a stale dir whose backup fails.
-	home2 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home2, nil })
-	knownSkillDirs = []string{".real/skills"}
-	stale := filepath.Join(home2, ".agents", "skills", "dingtalk-stale")
-	os.MkdirAll(stale, 0o755)
-	useUpgradeManagedNames(t, filepath.Base(stale))
-	testseam.Swap(t, &upgradeRename, func(string, string) error { return errors.New("backup denied") })
-	if _, err := UpgradeSkillLocations(mono); err == nil || !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("fallback cleanup error = %v", err)
-	}
-	if _, err := os.Stat(stale); err != nil {
-		t.Fatalf("stale dir must survive failed cleanup: %v", err)
-	}
-
-	// Fallback backup failure of the primary dws/ itself.
-	home3 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home3, nil })
-	os.MkdirAll(filepath.Join(home3, ".agents", "skills", "dws"), 0o755)
-	if _, err := UpgradeSkillLocations(mono); err == nil || !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("fallback backup error = %v", err)
-	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
-
-	// Fallback copy failure: everything fails loud.
-	home4 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home4, nil })
-	testseam.Swap(t, &upgradeCopyDir, func(string, string) error { return errors.New("copy denied") })
-	if _, err := UpgradeSkillLocations(mono); err == nil || !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("fallback copy error = %v", err)
-	}
-	testseam.Swap(t, &upgradeCopyDir, copyDir)
-
-	// Fallback append (no prior entry for the primary dir): a blacklisted-only
-	// main loop leaves no primary entry, so the fallback appends a fresh OK.
-	home5 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home5, nil })
-	result, err = UpgradeSkillLocations(mono)
-	if err != nil {
-		t.Fatalf("fallback append error = %v", err)
-	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 appended primary", got)
-	}
-	if _, err := os.Stat(filepath.Join(home5, ".agents", "skills", "dws", "SKILL.md")); err != nil {
-		t.Fatalf("fallback append install missing: %v", err)
+		t.Fatalf("failed canonical home must keep its original dws/: %v", err)
 	}
 }
 
@@ -977,15 +1061,10 @@ func TestCrossPlatformCoverageMonoUpgradeBackupAndFallbackEdges(t *testing.T) {
 // path's blacklisted branch, per-skill backup/copy failures, and the primary
 // fallback outcomes (cleanup OK + backup/copy failure, fresh append).
 func TestCrossPlatformCoverageMultiUpgradeBackupAndFallbackEdges(t *testing.T) {
-	originalDirs := append([]string(nil), knownSkillDirs...)
-	t.Cleanup(func() { knownSkillDirs = originalDirs })
-
 	extract := t.TempDir()
 	multiRoot := writeMultiBundle(t, extract, "dingtalk-chat")
-
-	// Blacklisted entry is reported, non-blacklisted installs.
 	home := withFakeHome(t)
-	knownSkillDirs = []string{".real/skills", ".agents/skills"}
+	testseam.Swap(t, &knownSkillDirs, []string{".real/skills", ".agents/skills"})
 	os.MkdirAll(filepath.Join(home, ".agents"), 0o755)
 	result, err := UpgradeSkillLocations(multiRoot)
 	if err != nil {
@@ -1003,119 +1082,33 @@ func TestCrossPlatformCoverageMultiUpgradeBackupAndFallbackEdges(t *testing.T) {
 	if _, err := os.Stat(filepath.Join(home, ".real")); !os.IsNotExist(err) {
 		t.Fatalf("blacklisted home must never be touched, stat err=%v", err)
 	}
+	if _, err := os.Stat(filepath.Join(home, ".agents", "skills", "dingtalk-chat", "SKILL.md")); err != nil {
+		t.Fatalf("canonical install missing: %v", err)
+	}
+}
 
-	// A detected concrete Agent root wins over .agents. A failure while retiring
-	// the old generic copy is surfaced after the concrete root succeeds.
-	home2 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home2, nil })
-	knownSkillDirs = []string{".agents/skills", ".claude/skills"}
-	os.MkdirAll(filepath.Join(home2, ".agents", "skills", "dingtalk-chat"), 0o755)
-	os.MkdirAll(filepath.Join(home2, ".claude"), 0o755)
-	testseam.Swap(t, &upgradeRename, func(src, dst string) error {
-		if strings.Contains(src, ".agents") {
-			return errors.New("backup denied")
-		}
-		return os.Rename(src, dst)
-	})
-	result, err = UpgradeSkillLocations(multiRoot)
+// The production wrappers that used to bundle these two steps were removed as
+// dead code; the test keeps exercising the live building blocks they composed.
+func cleanupMultiLeftoversForTest(homeDir, baseDir string) error {
+	victims, err := managedMultiSkillVictims(baseDir, readManagedSkillNames(homeDir))
 	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v", err)
+		return err
 	}
-	if failed := result.Failed(); len(failed) != 1 || failed[0].Err == nil {
-		t.Fatalf("failed = %v, want 1 backup-failed home", failed)
+	if _, err := backupSkillSet(homeDir, victims); err != nil {
+		return fmt.Errorf("备份并清理 multi 残留失败: %w", err)
 	}
-	if _, err := os.Stat(filepath.Join(home2, ".agents", "skills", "dingtalk-chat")); err != nil {
-		t.Fatalf("failed home must keep its original skill: %v", err)
-	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
+	return nil
+}
 
-	// Per-skill copy failure on the concrete home fails that home; with no
-	// successful concrete target, the generic copy is left untouched.
-	home3 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home3, nil })
-	os.MkdirAll(filepath.Join(home3, ".claude"), 0o755)
-	testseam.Swap(t, &upgradeCopyDir, func(src, dst string) error {
-		if strings.Contains(dst, ".claude") {
-			return errors.New("copy denied")
-		}
-		return copyDir(src, dst)
-	})
-	result, err = UpgradeSkillLocations(multiRoot)
+func cleanupOppositeModeLeftoversForTest(homeDir, destBase string, skillSet map[string]bool) error {
+	victims, err := oppositeModeSkillVictims(destBase, skillSet, readManagedSkillNames(homeDir))
 	if err != nil {
-		t.Fatalf("UpgradeSkillLocations() error = %v", err)
+		return err
 	}
-	if failed := result.Failed(); len(failed) != 1 || failed[0].Err == nil {
-		t.Fatalf("failed = %v, want 1 copy-failed home", failed)
-	}
-	testseam.Swap(t, &upgradeCopyDir, copyDir)
-
-	// Fallback backup failure: the same-name bundle skill refresh is what
-	// fails (cleanup succeeds, the per-skill backup does not).
-	home4 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home4, nil })
-	knownSkillDirs = []string{".real/skills"}
-	os.MkdirAll(filepath.Join(home4, ".agents", "skills", "dingtalk-chat"), 0o755)
-	testseam.Swap(t, &upgradeRename, func(src, dst string) error {
-		if strings.Contains(src, "dingtalk-chat") {
-			return errors.New("backup denied")
-		}
-		return os.Rename(src, dst)
-	})
-	if _, err := UpgradeSkillLocations(multiRoot); err == nil || !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("fallback backup error = %v", err)
-	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
-
-	// Fallback copy failure.
-	home5 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home5, nil })
-	testseam.Swap(t, &upgradeCopyDir, func(string, string) error { return errors.New("copy denied") })
-	if _, err := UpgradeSkillLocations(multiRoot); err == nil || !strings.Contains(err.Error(), "回退到主目录也失败") {
-		t.Fatalf("fallback copy error = %v", err)
-	}
-	testseam.Swap(t, &upgradeCopyDir, copyDir)
-
-	// Fallback append: blacklisted-only main loop → fresh OK entry appended.
-	home6 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home6, nil })
-	result, err = UpgradeSkillLocations(multiRoot)
-	if err != nil {
-		t.Fatalf("fallback append error = %v", err)
-	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 appended primary (%v)", got, result.Results)
-	}
-	if _, err := os.Stat(filepath.Join(home6, ".agents", "skills", "dingtalk-chat", "SKILL.md")); err != nil {
-		t.Fatalf("fallback append install missing: %v", err)
-	}
-
-	// Fallback replace: the main loop fails the primary home on a transient
-	// copy error, the fallback retry succeeds and replaces the failed entry.
-	home7 := t.TempDir()
-	testseam.Swap(t, &upgradeUserHomeDir, func() (string, error) { return home7, nil })
-	knownSkillDirs = []string{".agents/skills"}
-	origCopy := upgradeCopyDir
-	attempts := 0
-	testseam.Swap(t, &upgradeCopyDir, func(src, dst string) error {
-		attempts++
-		if attempts == 1 {
-			return errors.New("transient copy failure")
-		}
-		return origCopy(src, dst)
-	})
-	result, err = UpgradeSkillLocations(multiRoot)
-	if err != nil {
-		t.Fatalf("fallback replace error = %v", err)
-	}
-	if got := len(result.Succeeded()); got != 1 {
-		t.Fatalf("Succeeded() len = %d, want 1 replaced primary (%v)", got, result.Results)
-	}
-	if failed := result.Failed(); len(failed) != 0 {
-		t.Fatalf("failed entry must be replaced by OK, got %v", failed)
-	}
-	if _, err := os.Stat(filepath.Join(home7, ".agents", "skills", "dingtalk-chat", "SKILL.md")); err != nil {
-		t.Fatalf("fallback replace install missing: %v", err)
+	if _, err := backupSkillSet(homeDir, victims); err != nil {
+		return fmt.Errorf("备份并清理对面模式残留失败: %w", err)
 	}
+	return nil
 }
 
 // TestCrossPlatformCoverageCleanupLeftoversEdges pins the cleanup helpers:
@@ -1127,40 +1120,40 @@ func TestCrossPlatformCoverageCleanupLeftoversEdges(t *testing.T) {
 
 	// Read failure (non-ENOENT) surfaces from both cleanups.
 	testseam.Swap(t, &upgradeReadDir, func(string) ([]os.DirEntry, error) { return nil, errors.New("read denied") })
-	if err := cleanupMultiLeftovers(home, base); err == nil || !strings.Contains(err.Error(), "读取技能目录失败") {
-		t.Fatalf("cleanupMultiLeftovers read error = %v", err)
+	if err := cleanupMultiLeftoversForTest(home, base); err == nil || !strings.Contains(err.Error(), "读取技能目录失败") {
+		t.Fatalf("cleanupMultiLeftoversForTest read error = %v", err)
 	}
-	if err := cleanupOppositeModeLeftovers(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "读取技能目录失败") {
-		t.Fatalf("cleanupOppositeModeLeftovers read error = %v", err)
+	if err := cleanupOppositeModeLeftoversForTest(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "读取技能目录失败") {
+		t.Fatalf("cleanupOppositeModeLeftoversForTest read error = %v", err)
 	}
 	testseam.Swap(t, &upgradeReadDir, os.ReadDir)
 
 	// Backup failure of a multi leftover aborts cleanupMultiLeftovers.
 	os.MkdirAll(filepath.Join(base, "dingtalk-stale"), 0o755)
 	useUpgradeManagedNames(t, "dingtalk-stale")
-	testseam.Swap(t, &upgradeRename, func(string, string) error { return errors.New("backup denied") })
-	if err := cleanupMultiLeftovers(home, base); err == nil || !strings.Contains(err.Error(), "备份并清理 multi 残留失败") {
+	testseam.Swap(t, &skillPathRenameNoReplace, func(string, string) (string, error) { return "", errors.New("backup denied") })
+	if err := cleanupMultiLeftoversForTest(home, base); err == nil || !strings.Contains(err.Error(), "备份并清理 multi 残留失败") {
 		t.Fatalf("cleanupMultiLeftovers backup error = %v", err)
 	}
 
 	// Backup failure of the mono leftover aborts the opposite-mode cleanup.
 	os.MkdirAll(filepath.Join(base, "dws"), 0o755)
-	if err := cleanupOppositeModeLeftovers(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "备份并清理对面模式残留失败") {
+	if err := cleanupOppositeModeLeftoversForTest(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "备份并清理对面模式残留失败") {
 		t.Fatalf("opposite cleanup mono backup error = %v", err)
 	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
+	testseam.Swap(t, &skillPathRenameNoReplace, renameSkillPathNoReplace)
 
 	// Backup failure of a stale (non-mono) skill aborts with its own message.
-	testseam.Swap(t, &upgradeRename, func(src, dst string) error {
+	testseam.Swap(t, &skillPathRenameNoReplace, func(src, dst string) (string, error) {
 		if strings.Contains(src, "dingtalk-stale") {
-			return errors.New("backup denied")
+			return "", errors.New("backup denied")
 		}
-		return os.Rename(src, dst)
+		return renameSkillPathNoReplace(src, dst)
 	})
-	if err := cleanupOppositeModeLeftovers(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "备份并清理对面模式残留失败") {
+	if err := cleanupOppositeModeLeftoversForTest(home, base, map[string]bool{}); err == nil || !strings.Contains(err.Error(), "备份并清理对面模式残留失败") {
 		t.Fatalf("opposite cleanup stale backup error = %v", err)
 	}
-	testseam.Swap(t, &upgradeRename, os.Rename)
+	testseam.Swap(t, &skillPathRenameNoReplace, renameSkillPathNoReplace)
 
 	// Success matrix: mono leftover + stale skill removed into backups, bundle
 	// skill and regular file preserved.
@@ -1168,7 +1161,7 @@ func TestCrossPlatformCoverageCleanupLeftoversEdges(t *testing.T) {
 	skillSet := map[string]bool{"dingtalk-keep": true}
 	os.MkdirAll(filepath.Join(base, "dingtalk-keep"), 0o755)
 	os.WriteFile(filepath.Join(base, "regular-file"), []byte("x"), 0o644)
-	if err := cleanupOppositeModeLeftovers(home, base, skillSet); err != nil {
+	if err := cleanupOppositeModeLeftoversForTest(home, base, skillSet); err != nil {
 		t.Fatalf("cleanupOppositeModeLeftovers() error = %v", err)
 	}
 	for _, gone := range []string{"dws", "dingtalk-stale"} {
@@ -1188,7 +1181,7 @@ func TestCrossPlatformCoverageCleanupLeftoversEdges(t *testing.T) {
 	}
 
 	// cleanupMultiLeftovers on a missing base is a no-op.
-	if err := cleanupMultiLeftovers(home, filepath.Join(home, "missing")); err != nil {
+	if err := cleanupMultiLeftoversForTest(home, filepath.Join(home, "missing")); err != nil {
 		t.Fatalf("missing base must be a no-op, got %v", err)
 	}
 }

internal/upgrade/skill_backup_ownership_test.go

@@ -0,0 +1,113 @@
+// Copyright 2026 Alibaba Group
+// Licensed under the Apache License, Version 2.0
+
+package upgrade
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+// TestCrossPlatformCoverageSkillBackupOwnership pins the backup ownership
+// contract: a stamp-shaped directory name alone proves nothing, so a backup
+// root this transaction writes into is either created fresh (mkdir claim,
+// marker stamped before any payload moves in) or an existing root whose
+// marker already verifies. A same-stamp foreign directory is never adopted —
+// writing the marker or the payload into it would turn its contents into
+// prunable DWS backups.
+func TestCrossPlatformCoverageSkillBackupOwnership(t *testing.T) {
+
+	t.Run("unproven stamp root is never adopted", func(t *testing.T) {
+		home := t.TempDir()
+		testseam.Swap(t, &upgradeBackupStamp, func() string { return "20260101-120000" })
+		foreign := filepath.Join(home, skillBackupSubdir, "20260101-120000")
+		if err := os.MkdirAll(foreign, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(foreign, "user-data.txt"), []byte("must survive"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		victim := filepath.Join(home, "skills", "dws")
+		seedUpgradeSkill(t, victim, "payload", false)
+		backup, err := backupAndRemoveSkillDir(home, victim)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if want := filepath.Join(home, skillBackupSubdir, "20260101-120000-1", "skills-dws"); backup != want {
+			t.Fatalf("backup = %s, want suffixed %s", backup, want)
+		}
+		assertUpgradeSkillContent(t, backup, "payload")
+		// The foreign root keeps its data and never receives our marker.
+		if data, readErr := os.ReadFile(filepath.Join(foreign, "user-data.txt")); readErr != nil || string(data) != "must survive" {
+			t.Fatalf("foreign data = %q, %v", data, readErr)
+		}
+		if _, statErr := os.Lstat(filepath.Join(foreign, skillBackupMarkerName)); !os.IsNotExist(statErr) {
+			t.Fatalf("foreign root must not receive the ownership marker, stat err=%v", statErr)
+		}
+		if !skillBackupMarkerValid(filepath.Dir(backup)) {
+			t.Fatal("the freshly claimed root must carry the ownership marker")
+		}
+	})
+
+	t.Run("same-stamp payloads reuse the proven root", func(t *testing.T) {
+		home := t.TempDir()
+		testseam.Swap(t, &upgradeBackupStamp, func() string { return "20260101-120000" })
+		first := filepath.Join(home, "skills", "dws")
+		second := filepath.Join(home, "agents", "claude", "dws")
+		seedUpgradeSkill(t, first, "first", false)
+		seedUpgradeSkill(t, second, "second", false)
+		backupA, err := backupAndRemoveSkillDir(home, first)
+		if err != nil {
+			t.Fatal(err)
+		}
+		backupB, err := backupAndRemoveSkillDir(home, second)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if filepath.Dir(backupA) != filepath.Dir(backupB) {
+			t.Fatalf("same-stamp backups split roots: %s vs %s", backupA, backupB)
+		}
+		root := filepath.Dir(backupA)
+		if !skillBackupMarkerValid(root) {
+			t.Fatal("reused root must keep a verifying marker")
+		}
+		assertUpgradeSkillContent(t, backupA, "first")
+		assertUpgradeSkillContent(t, backupB, "second")
+	})
+
+	t.Run("marker write failure refuses the backup and cleans the empty root", func(t *testing.T) {
+		home := t.TempDir()
+		victim := filepath.Join(home, "skills", "dws")
+		seedUpgradeSkill(t, victim, "payload", false)
+		testseam.Swap(t, &skillBackupWriteMarker, func(string) error { return errors.New("marker denied") })
+		_, err := backupAndRemoveSkillDir(home, victim)
+		if err == nil || !strings.Contains(err.Error(), "备份所有权标记失败") {
+			t.Fatalf("marker write failure = %v", err)
+		}
+		assertUpgradeSkillContent(t, victim, "payload")
+		entries, readErr := os.ReadDir(filepath.Join(home, skillBackupSubdir))
+		if readErr != nil {
+			t.Fatal(readErr)
+		}
+		if len(entries) != 0 {
+			t.Fatalf("empty unowned stamp root must be cleaned, left %v", entries)
+		}
+	})
+
+	t.Run("backup root creation failure surfaces", func(t *testing.T) {
+		home := t.TempDir()
+		victim := filepath.Join(home, "skills", "dws")
+		seedUpgradeSkill(t, victim, "payload", false)
+		testseam.Swap(t, &skillPathMkdir, func(string, os.FileMode) error { return os.ErrPermission })
+		_, err := backupAndRemoveSkillDir(home, victim)
+		if !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("root creation failure = %v", err)
+		}
+		assertUpgradeSkillContent(t, victim, "payload")
+	})
+}

internal/upgrade/skill_path_move.go

@@ -0,0 +1,363 @@
+package upgrade
+
+import (
+	"crypto/sha256"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+var (
+	skillPathRename           = func(src, dst string) error { return upgradeRename(src, dst) }
+	skillPathRenameNoReplace  = renameSkillPathNoReplace
+	skillPathCopy             = copySkillPathLexically
+	skillPathVerify           = verifySkillPathCopy
+	skillPathRemoveAll        = os.RemoveAll
+	skillPathMkdirAll         = os.MkdirAll
+	skillPathMkdirTemp        = os.MkdirTemp
+	skillPathChmod            = os.Chmod
+	skillPathLstat            = os.Lstat
+	skillPathMkdir            = os.Mkdir
+	skillPathLink             = os.Link
+	skillPathRemove           = os.Remove
+	skillPathReadDir          = os.ReadDir
+	skillPathFileIdentity     = skillPathFileIdentityImpl
+	skillPathFileIncarnation  = skillPathFileIncarnationImpl
+	skillPathSameFileIdentity = skillPathSameFileIdentityImpl
+	skillPathReadlink         = os.Readlink
+	skillPathSymlink          = os.Symlink
+	skillPathOpen             = os.Open
+	skillPathOpenFile         = os.OpenFile
+	skillPathCopyBytes        = io.Copy
+	skillPathSync             = func(file *os.File) error { return file.Sync() }
+	skillPathWalkDir          = filepath.WalkDir
+)
+
+// moveSkillPathRecoverably moves one managed Skill path without weakening the
+// backup contract when source and destination are on different filesystems.
+// The cross-device path publishes a fully copied and verified sibling staging
+// path before removing the source. Any failure before source removal leaves the
+// source intact; a removal failure deliberately leaves both verified copies.
+func moveSkillPathRecoverably(src, dst string) (err error) {
+	if _, statErr := skillPathLstat(dst); statErr == nil {
+		return fmt.Errorf("目标已存在: %s", dst)
+	} else if !os.IsNotExist(statErr) {
+		return fmt.Errorf("检查移动目标失败 %s: %w", dst, statErr)
+	}
+	if err := skillPathMkdirAll(filepath.Dir(dst), dirPermShared); err != nil {
+		return fmt.Errorf("创建移动目标目录失败 %s: %w", filepath.Dir(dst), err)
+	}
+	// moveSkillPathRecoverably is not a publication path; ignore any
+	// claim identity returned by the rename — no ownership check follows
+	// on this destination.
+	if _, renameErr := skillPathRenameNoReplace(src, dst); renameErr == nil {
+		return nil
+	} else if !isCrossDeviceError(renameErr) {
+		return fmt.Errorf("移动 Skill 路径失败 %s -> %s: %w", src, dst, renameErr)
+	}
+
+	stageRoot, err := skillPathMkdirTemp(filepath.Dir(dst), "."+filepath.Base(dst)+".cross-device-")
+	if err != nil {
+		return fmt.Errorf("创建跨设备 Skill staging 失败 %s: %w", dst, err)
+	}
+	stage := filepath.Join(stageRoot, "payload")
+	stageCleaned := false
+	defer func() {
+		if stageCleaned {
+			return
+		}
+		makeSkillPathTreeWritable(stageRoot)
+		if cleanupErr := skillPathRemoveAll(stageRoot); cleanupErr != nil {
+			err = errors.Join(err, fmt.Errorf("清理跨设备 Skill staging 失败 %s: %w", stageRoot, cleanupErr))
+		}
+	}()
+
+	if err := skillPathCopy(src, stage); err != nil {
+		return fmt.Errorf("复制跨设备 Skill staging 失败 %s: %w", stage, err)
+	}
+	if err := skillPathVerify(src, stage); err != nil {
+		return fmt.Errorf("校验跨设备 Skill staging 失败 %s: %w", stage, err)
+	}
+	stageInfo, err := skillPathLstat(stage)
+	if err != nil {
+		return fmt.Errorf("检查跨设备 Skill staging 失败 %s: %w", stage, err)
+	}
+	if stageInfo.IsDir() {
+		// Darwin refuses to rename a read-only directory even when both parent
+		// directories are writable. The exact source mode was verified above;
+		// temporarily add owner access for publication, then restore it before
+		// the final verification and before the source is removed.
+		if err := skillPathChmod(stage, stageInfo.Mode().Perm()|0o700); err != nil {
+			return fmt.Errorf("准备跨设备 Skill staging 发布失败 %s: %w", stage, err)
+		}
+	}
+	// Cross-device staging publishes via a self-owned staging directory,
+	// so the claim identity is not consulted; discard it.
+	if _, err := skillPathRenameNoReplace(stage, dst); err != nil {
+		return fmt.Errorf("发布跨设备 Skill 备份失败 %s: %w", dst, err)
+	}
+	if stageInfo.IsDir() {
+		if err := skillPathChmod(dst, stageInfo.Mode().Perm()); err != nil {
+			return fmt.Errorf("恢复已发布 Skill 目录权限失败 %s: %w", dst, err)
+		}
+	}
+	if err := skillPathVerify(src, dst); err != nil {
+		return fmt.Errorf("校验已发布 Skill 备份失败 %s: %w", dst, err)
+	}
+	if err := skillPathRemoveAll(stageRoot); err != nil {
+		return fmt.Errorf("清理已发布 Skill staging 失败 %s: %w", stageRoot, err)
+	}
+	stageCleaned = true
+	if err := removePublishedSkillSource(src); err != nil {
+		return fmt.Errorf("Skill 目标已发布但源路径删除失败（源 %s 与目标 %s 均保留）: %w", src, dst, err)
+	}
+	return nil
+}
+
+type skillPathDirMode struct {
+	path string
+	mode os.FileMode
+}
+
+func removePublishedSkillSource(src string) error {
+	dirModes, err := prepareSkillPathTreeRemoval(src)
+	if err != nil {
+		return err
+	}
+	removeErr := skillPathRemoveAll(src)
+	if removeErr == nil {
+		if _, statErr := skillPathLstat(src); os.IsNotExist(statErr) {
+			return nil
+		} else if statErr == nil {
+			removeErr = errors.New("源路径仍存在")
+		} else {
+			removeErr = fmt.Errorf("无法确认源路径已删除: %w", statErr)
+		}
+	}
+	return errors.Join(removeErr, restoreSkillPathDirModes(dirModes))
+}
+
+func prepareSkillPathTreeRemoval(root string) ([]skillPathDirMode, error) {
+	var modes []skillPathDirMode
+	err := skillPathWalkDir(root, func(path string, entry os.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		if !entry.IsDir() {
+			return nil
+		}
+		info, err := entry.Info()
+		if err != nil {
+			return err
+		}
+		mode := info.Mode().Perm()
+		if mode&0o700 == 0o700 {
+			return nil
+		}
+		if err := skillPathChmod(path, mode|0o700); err != nil {
+			return err
+		}
+		modes = append(modes, skillPathDirMode{path: path, mode: mode})
+		return nil
+	})
+	if err != nil {
+		return nil, errors.Join(err, restoreSkillPathDirModes(modes))
+	}
+	return modes, nil
+}
+
+func restoreSkillPathDirModes(modes []skillPathDirMode) error {
+	var restoreErr error
+	for i := len(modes) - 1; i >= 0; i-- {
+		item := modes[i]
+		if _, err := skillPathLstat(item.path); os.IsNotExist(err) {
+			continue
+		} else if err != nil {
+			restoreErr = errors.Join(restoreErr, err)
+			continue
+		}
+		if err := skillPathChmod(item.path, item.mode); err != nil {
+			restoreErr = errors.Join(restoreErr, fmt.Errorf("恢复源目录权限失败 %s: %w", item.path, err))
+		}
+	}
+	return restoreErr
+}
+
+func makeSkillPathTreeWritable(root string) {
+	// Best effort only: RemoveAll below remains the source of truth and its
+	// error is returned. This preparation lets it traverse read-only staging
+	// directories left by a copy or verification failure.
+	_ = skillPathWalkDir(root, func(path string, entry os.DirEntry, walkErr error) error {
+		if walkErr == nil && entry.IsDir() {
+			_ = skillPathChmod(path, 0o700)
+		}
+		return nil
+	})
+}
+
+// RestoreSkillPath restores a previously recorded backup using the same
+// rename-first, verified cross-device fallback as backup publication.
+func RestoreSkillPath(backup, original string) error {
+	return moveSkillPathRecoverably(backup, original)
+}
+
+func copySkillPathLexically(src, dst string) error {
+	info, err := skillPathLstat(src)
+	if err != nil {
+		return err
+	}
+	switch {
+	case info.IsDir():
+		// Staging must remain writable while children are copied. Restore the
+		// source mode only after the directory is complete so read-only Skill
+		// directories (for example 0555) can still be migrated lexically.
+		if err := skillPathMkdir(dst, 0o700); err != nil {
+			return err
+		}
+		entries, err := skillPathReadDir(src)
+		if err != nil {
+			return err
+		}
+		for _, entry := range entries {
+			if err := copySkillPathLexically(filepath.Join(src, entry.Name()), filepath.Join(dst, entry.Name())); err != nil {
+				return err
+			}
+		}
+		return os.Chmod(dst, info.Mode().Perm())
+	case info.Mode()&os.ModeSymlink != 0:
+		target, err := skillPathReadlink(src)
+		if err != nil {
+			return err
+		}
+		return skillPathSymlink(target, dst)
+	case info.Mode().IsRegular():
+		return copyRegularSkillFile(src, dst, info.Mode().Perm())
+	default:
+		return fmt.Errorf("不支持复制特殊 Skill 路径 %s（mode=%s）", src, info.Mode())
+	}
+}
+
+func copyRegularSkillFile(src, dst string, mode os.FileMode) (err error) {
+	in, err := skillPathOpen(src)
+	if err != nil {
+		return err
+	}
+	defer func() { err = errors.Join(err, in.Close()) }()
+	out, err := skillPathOpenFile(dst, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+	if err != nil {
+		return err
+	}
+	defer func() { err = errors.Join(err, out.Close()) }()
+	if _, err := skillPathCopyBytes(out, in); err != nil {
+		return err
+	}
+	if err := skillPathSync(out); err != nil {
+		return err
+	}
+	return os.Chmod(dst, mode)
+}
+
+func verifySkillPathCopy(src, dst string) error {
+	srcInfo, err := skillPathLstat(src)
+	if err != nil {
+		return err
+	}
+	dstInfo, err := skillPathLstat(dst)
+	if err != nil {
+		return err
+	}
+	if srcInfo.Mode()&os.ModeType != dstInfo.Mode()&os.ModeType {
+		return fmt.Errorf("路径类型不一致: %s (%s) != %s (%s)", src, srcInfo.Mode(), dst, dstInfo.Mode())
+	}
+	switch {
+	case srcInfo.IsDir():
+		if srcInfo.Mode().Perm() != dstInfo.Mode().Perm() {
+			return fmt.Errorf("目录权限不一致: %s (%s) != %s (%s)", src, srcInfo.Mode().Perm(), dst, dstInfo.Mode().Perm())
+		}
+		srcNames, err := skillPathEntryNames(src)
+		if err != nil {
+			return err
+		}
+		dstNames, err := skillPathEntryNames(dst)
+		if err != nil {
+			return err
+		}
+		if len(srcNames) != len(dstNames) {
+			return fmt.Errorf("目录项数量不一致: %s (%d) != %s (%d)", src, len(srcNames), dst, len(dstNames))
+		}
+		for i, name := range srcNames {
+			if name != dstNames[i] {
+				return fmt.Errorf("目录项不一致: %s != %s", name, dstNames[i])
+			}
+			if err := verifySkillPathCopy(filepath.Join(src, name), filepath.Join(dst, name)); err != nil {
+				return err
+			}
+		}
+		return nil
+	case srcInfo.Mode()&os.ModeSymlink != 0:
+		srcTarget, err := skillPathReadlink(src)
+		if err != nil {
+			return err
+		}
+		dstTarget, err := skillPathReadlink(dst)
+		if err != nil {
+			return err
+		}
+		if srcTarget != dstTarget {
+			return fmt.Errorf("符号链接目标不一致: %q != %q", srcTarget, dstTarget)
+		}
+		return nil
+	case srcInfo.Mode().IsRegular():
+		if srcInfo.Mode().Perm() != dstInfo.Mode().Perm() {
+			return fmt.Errorf("文件权限不一致: %s (%s) != %s (%s)", src, srcInfo.Mode().Perm(), dst, dstInfo.Mode().Perm())
+		}
+		if srcInfo.Size() != dstInfo.Size() {
+			return fmt.Errorf("文件大小不一致: %s (%d) != %s (%d)", src, srcInfo.Size(), dst, dstInfo.Size())
+		}
+		srcDigest, err := skillPathFileDigest(src)
+		if err != nil {
+			return err
+		}
+		dstDigest, err := skillPathFileDigest(dst)
+		if err != nil {
+			return err
+		}
+		if srcDigest != dstDigest {
+			return fmt.Errorf("文件内容摘要不一致: %s != %s", src, dst)
+		}
+		return nil
+	default:
+		return fmt.Errorf("不支持校验特殊 Skill 路径 %s（mode=%s）", src, srcInfo.Mode())
+	}
+}
+
+func skillPathEntryNames(dir string) ([]string, error) {
+	entries, err := skillPathReadDir(dir)
+	if err != nil {
+		return nil, err
+	}
+	names := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		names = append(names, entry.Name())
+	}
+	sort.Strings(names)
+	return names, nil
+}
+
+func skillPathFileDigest(path string) ([sha256.Size]byte, error) {
+	f, err := skillPathOpen(path)
+	if err != nil {
+		return [sha256.Size]byte{}, err
+	}
+	defer f.Close()
+	hash := sha256.New()
+	if _, err := skillPathCopyBytes(hash, f); err != nil {
+		return [sha256.Size]byte{}, err
+	}
+	var digest [sha256.Size]byte
+	copy(digest[:], hash.Sum(nil))
+	return digest, nil
+}

internal/upgrade/skill_path_move_errors_test.go

@@ -0,0 +1,529 @@
+package upgrade
+
+import (
+	"errors"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageSkillPathMoveSystemErrors(t *testing.T) {
+	t.Run("destination probe", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		original := skillPathLstat
+		testseam.Swap(t, &skillPathLstat, func(path string) (os.FileInfo, error) {
+			if path == dst {
+				return nil, os.ErrPermission
+			}
+			return original(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("destination parent", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		testseam.Swap(t, &skillPathMkdirAll, func(string, os.FileMode) error { return os.ErrPermission })
+		if err := moveSkillPathRecoverably(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("staging creation", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		testseam.Swap(t, &skillPathMkdirTemp, func(string, string) (string, error) { return "", os.ErrPermission })
+		if err := moveSkillPathRecoverably(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("failed staging cleanup", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		testseam.Swap(t, &skillPathCopy, func(string, string) error { return errors.New("copy failed") })
+		testseam.Swap(t, &skillPathRemoveAll, func(string) error { return errors.New("cleanup failed") })
+		err := moveSkillPathRecoverably(src, dst)
+		if err == nil || !strings.Contains(err.Error(), "copy failed") || !strings.Contains(err.Error(), "cleanup failed") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("missing copied staging", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		testseam.Swap(t, &skillPathCopy, func(string, string) error { return nil })
+		testseam.Swap(t, &skillPathVerify, func(string, string) error { return nil })
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "检查跨设备") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	for _, tc := range []struct {
+		name string
+		path func(src, dst string) string
+		want string
+	}{
+		{name: "prepare staging mode", path: func(_, dst string) string { return filepath.Join(filepath.Dir(dst), "payload") }, want: "准备跨设备"},
+		{name: "restore published mode", path: func(_, dst string) string { return dst }, want: "恢复已发布"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			src, dst := makeSkillMoveFixture(t)
+			forceCrossDeviceRename(t, src, dst)
+			original := skillPathChmod
+			testseam.Swap(t, &skillPathChmod, func(path string, mode os.FileMode) error {
+				if tc.name == "prepare staging mode" && strings.HasSuffix(path, string(filepath.Separator)+"payload") {
+					return errors.New("chmod failed")
+				}
+				if tc.name == "restore published mode" && path == dst {
+					return errors.New("chmod failed")
+				}
+				return original(path, mode)
+			})
+			if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("error = %v", err)
+			}
+		})
+	}
+
+	t.Run("published staging cleanup", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		original := skillPathRemoveAll
+		testseam.Swap(t, &skillPathRemoveAll, func(path string) error {
+			if strings.Contains(filepath.Base(path), ".cross-device-") {
+				return errors.New("cleanup failed")
+			}
+			return original(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "清理已发布") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("source deletion cannot be confirmed", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		removalAttempted := false
+		originalLstat := skillPathLstat
+		originalRemove := skillPathRemoveAll
+		testseam.Swap(t, &skillPathRemoveAll, func(path string) error {
+			if path == src {
+				removalAttempted = true
+				return nil
+			}
+			return originalRemove(path)
+		})
+		testseam.Swap(t, &skillPathLstat, func(path string) (os.FileInfo, error) {
+			if path == src && removalAttempted {
+				return nil, os.ErrPermission
+			}
+			return originalLstat(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillPathPermissionRestorationErrors(t *testing.T) {
+	t.Run("source preparation error", func(t *testing.T) {
+		testseam.Swap(t, &skillPathWalkDir, func(string, fs.WalkDirFunc) error {
+			return errors.New("prepare failed")
+		})
+		if err := removePublishedSkillSource("ignored"); err == nil || !strings.Contains(err.Error(), "prepare failed") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("walk error", func(t *testing.T) {
+		testseam.Swap(t, &skillPathWalkDir, func(root string, fn fs.WalkDirFunc) error {
+			return fn(root, nil, errors.New("walk failed"))
+		})
+		if _, err := prepareSkillPathTreeRemoval("ignored"); err == nil || !strings.Contains(err.Error(), "walk failed") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("writable mode preparation", func(t *testing.T) {
+		entry := skillPathModeDirEntry{mode: os.ModeDir | 0o500}
+		testseam.Swap(t, &skillPathWalkDir, func(root string, fn fs.WalkDirFunc) error {
+			return fn(root, entry, nil)
+		})
+		var chmodMode os.FileMode
+		testseam.Swap(t, &skillPathChmod, func(_ string, mode os.FileMode) error {
+			chmodMode = mode
+			return nil
+		})
+		modes, err := prepareSkillPathTreeRemoval("source")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if chmodMode != 0o700 || len(modes) != 1 || modes[0].path != "source" || modes[0].mode != 0o500 {
+			t.Fatalf("prepared mode = %v, records = %#v", chmodMode, modes)
+		}
+	})
+
+	t.Run("writable mode preparation chmod error", func(t *testing.T) {
+		entry := skillPathModeDirEntry{mode: os.ModeDir | 0o500}
+		testseam.Swap(t, &skillPathWalkDir, func(root string, fn fs.WalkDirFunc) error {
+			return fn(root, entry, nil)
+		})
+		testseam.Swap(t, &skillPathChmod, func(string, os.FileMode) error {
+			return errors.New("chmod failed")
+		})
+		if _, err := prepareSkillPathTreeRemoval("source"); err == nil || !strings.Contains(err.Error(), "chmod failed") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("entry info error", func(t *testing.T) {
+		testseam.Swap(t, &skillPathWalkDir, func(root string, fn fs.WalkDirFunc) error {
+			return fn(root, skillPathErrorDirEntry{}, nil)
+		})
+		if _, err := prepareSkillPathTreeRemoval("ignored"); err == nil || !strings.Contains(err.Error(), "info failed") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("missing restored directory", func(t *testing.T) {
+		if err := restoreSkillPathDirModes([]skillPathDirMode{{path: filepath.Join(t.TempDir(), "missing"), mode: 0o555}}); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("restore probe error", func(t *testing.T) {
+		testseam.Swap(t, &skillPathLstat, func(string) (os.FileInfo, error) { return nil, os.ErrPermission })
+		if err := restoreSkillPathDirModes([]skillPathDirMode{{path: "blocked", mode: 0o555}}); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("restore chmod error", func(t *testing.T) {
+		path := t.TempDir()
+		testseam.Swap(t, &skillPathChmod, func(string, os.FileMode) error { return os.ErrPermission })
+		if err := restoreSkillPathDirModes([]skillPathDirMode{{path: path, mode: 0o555}}); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillPathLexicalCopyErrors(t *testing.T) {
+	t.Run("source lstat", func(t *testing.T) {
+		if err := copySkillPathLexically(filepath.Join(t.TempDir(), "missing"), "unused"); !os.IsNotExist(err) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("destination mkdir", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.Mkdir(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(dst, []byte("occupied"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := copySkillPathLexically(src, dst); err == nil {
+			t.Fatal("expected mkdir failure")
+		}
+	})
+
+	t.Run("source readdir", func(t *testing.T) {
+		root := t.TempDir()
+		src := filepath.Join(root, "src")
+		if err := os.Mkdir(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &skillPathReadDir, func(string) ([]os.DirEntry, error) { return nil, os.ErrPermission })
+		if err := copySkillPathLexically(src, filepath.Join(root, "dst")); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("nested copy", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.Mkdir(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "child"), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		original := skillPathLstat
+		testseam.Swap(t, &skillPathLstat, func(path string) (os.FileInfo, error) {
+			if filepath.Base(path) == "child" {
+				return nil, os.ErrPermission
+			}
+			return original(path)
+		})
+		if err := copySkillPathLexically(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("readlink", func(t *testing.T) {
+		root := t.TempDir()
+		src := filepath.Join(root, "link")
+		if err := os.Symlink("target", src); err != nil {
+			t.Skipf("symlink unavailable: %v", err)
+		}
+		testseam.Swap(t, &skillPathReadlink, func(string) (string, error) { return "", os.ErrPermission })
+		if err := copySkillPathLexically(src, filepath.Join(root, "dst")); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("special path", func(t *testing.T) {
+		testseam.Swap(t, &skillPathLstat, func(string) (os.FileInfo, error) {
+			return skillPathFakeInfo{mode: os.ModeNamedPipe}, nil
+		})
+		if err := copySkillPathLexically("special", "dst"); err == nil || !strings.Contains(err.Error(), "特殊") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("regular open", func(t *testing.T) {
+		if err := copyRegularSkillFile(filepath.Join(t.TempDir(), "missing"), "dst", 0o600); !os.IsNotExist(err) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("regular destination open", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.WriteFile(src, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(dst, []byte("occupied"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := copyRegularSkillFile(src, dst, 0o600); err == nil {
+			t.Fatal("expected exclusive create failure")
+		}
+	})
+
+	for _, tc := range []struct {
+		name string
+		swap func(*testing.T)
+	}{
+		{name: "copy", swap: func(t *testing.T) {
+			testseam.Swap(t, &skillPathCopyBytes, func(io.Writer, io.Reader) (int64, error) { return 0, errors.New("copy failed") })
+		}},
+		{name: "sync", swap: func(t *testing.T) {
+			testseam.Swap(t, &skillPathSync, func(*os.File) error { return errors.New("sync failed") })
+		}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+			if err := os.WriteFile(src, []byte("x"), 0o600); err != nil {
+				t.Fatal(err)
+			}
+			tc.swap(t)
+			if err := copyRegularSkillFile(src, dst, 0o600); err == nil || !strings.Contains(err.Error(), tc.name) {
+				t.Fatalf("error = %v", err)
+			}
+		})
+	}
+}
+
+func TestCrossPlatformCoverageSkillPathVerificationErrors(t *testing.T) {
+	root := t.TempDir()
+
+	t.Run("source and destination lstat", func(t *testing.T) {
+		if err := verifySkillPathCopy(filepath.Join(root, "missing-src"), "dst"); !os.IsNotExist(err) {
+			t.Fatalf("source error = %v", err)
+		}
+		src := filepath.Join(root, "source")
+		if err := os.WriteFile(src, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, filepath.Join(root, "missing-dst")); !os.IsNotExist(err) {
+			t.Fatalf("destination error = %v", err)
+		}
+	})
+
+	t.Run("directory and file modes", func(t *testing.T) {
+		for _, tc := range []struct {
+			name string
+			src  os.FileMode
+			dst  os.FileMode
+		}{
+			{name: "directory", src: os.ModeDir | 0o700, dst: os.ModeDir | 0o755},
+			{name: "file", src: 0o600, dst: 0o644},
+		} {
+			t.Run(tc.name, func(t *testing.T) {
+				src, dst := "src", "dst"
+				testseam.Swap(t, &skillPathLstat, func(path string) (os.FileInfo, error) {
+					if path == src {
+						return skillPathFakeInfo{mode: tc.src}, nil
+					}
+					return skillPathFakeInfo{mode: tc.dst}, nil
+				})
+				if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "权限") {
+					t.Fatalf("error = %v", err)
+				}
+			})
+		}
+	})
+
+	t.Run("directory read errors", func(t *testing.T) {
+		for _, failDest := range []bool{false, true} {
+			t.Run(map[bool]string{false: "source", true: "destination"}[failDest], func(t *testing.T) {
+				base := t.TempDir()
+				src, dst := filepath.Join(base, "src"), filepath.Join(base, "dst")
+				if err := os.Mkdir(src, 0o700); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Mkdir(dst, 0o700); err != nil {
+					t.Fatal(err)
+				}
+				original := skillPathReadDir
+				testseam.Swap(t, &skillPathReadDir, func(path string) ([]os.DirEntry, error) {
+					if (path == dst) == failDest {
+						return nil, os.ErrPermission
+					}
+					return original(path)
+				})
+				if err := verifySkillPathCopy(src, dst); !errors.Is(err, os.ErrPermission) {
+					t.Fatalf("error = %v", err)
+				}
+			})
+		}
+	})
+
+	t.Run("nested mismatch", func(t *testing.T) {
+		base := t.TempDir()
+		src, dst := filepath.Join(base, "src"), filepath.Join(base, "dst")
+		if err := os.Mkdir(src, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(dst, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "child"), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(filepath.Join(dst, "child"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "类型") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("symlink reads", func(t *testing.T) {
+		base := t.TempDir()
+		src, dst := filepath.Join(base, "src"), filepath.Join(base, "dst")
+		if err := os.Symlink("one", src); err != nil {
+			t.Skipf("symlink unavailable: %v", err)
+		}
+		if err := os.Symlink("one", dst); err != nil {
+			t.Fatal(err)
+		}
+		for _, failDest := range []bool{false, true} {
+			t.Run(map[bool]string{false: "source", true: "destination"}[failDest], func(t *testing.T) {
+				original := skillPathReadlink
+				testseam.Swap(t, &skillPathReadlink, func(path string) (string, error) {
+					if (path == dst) == failDest {
+						return "", os.ErrPermission
+					}
+					return original(path)
+				})
+				if err := verifySkillPathCopy(src, dst); !errors.Is(err, os.ErrPermission) {
+					t.Fatalf("error = %v", err)
+				}
+			})
+		}
+	})
+
+	t.Run("file digest opens", func(t *testing.T) {
+		base := t.TempDir()
+		src, dst := filepath.Join(base, "src"), filepath.Join(base, "dst")
+		if err := os.WriteFile(src, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(dst, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		for _, failDest := range []bool{false, true} {
+			t.Run(map[bool]string{false: "source", true: "destination"}[failDest], func(t *testing.T) {
+				original := skillPathOpen
+				testseam.Swap(t, &skillPathOpen, func(path string) (*os.File, error) {
+					if (path == dst) == failDest {
+						return nil, os.ErrPermission
+					}
+					return original(path)
+				})
+				if err := verifySkillPathCopy(src, dst); !errors.Is(err, os.ErrPermission) {
+					t.Fatalf("error = %v", err)
+				}
+			})
+		}
+	})
+
+	t.Run("special path", func(t *testing.T) {
+		fake := skillPathFakeInfo{mode: os.ModeNamedPipe}
+		testseam.Swap(t, &skillPathLstat, func(string) (os.FileInfo, error) { return fake, nil })
+		if err := verifySkillPathCopy("src", "dst"); err == nil || !strings.Contains(err.Error(), "特殊") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("entry names", func(t *testing.T) {
+		if _, err := skillPathEntryNames(filepath.Join(root, "missing-dir")); !os.IsNotExist(err) {
+			t.Fatalf("error = %v", err)
+		}
+	})
+
+	t.Run("digest open and read", func(t *testing.T) {
+		if _, err := skillPathFileDigest(filepath.Join(root, "missing-file")); !os.IsNotExist(err) {
+			t.Fatalf("open error = %v", err)
+		}
+		file := filepath.Join(root, "digest-file")
+		if err := os.WriteFile(file, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		testseam.Swap(t, &skillPathCopyBytes, func(io.Writer, io.Reader) (int64, error) { return 0, errors.New("read failed") })
+		if _, err := skillPathFileDigest(file); err == nil || !strings.Contains(err.Error(), "read failed") {
+			t.Fatalf("read error = %v", err)
+		}
+	})
+}
+
+type skillPathFakeInfo struct {
+	mode os.FileMode
+}
+
+func (skillPathFakeInfo) Name() string           { return "fake" }
+func (skillPathFakeInfo) Size() int64            { return 0 }
+func (info skillPathFakeInfo) Mode() os.FileMode { return info.mode }
+func (skillPathFakeInfo) ModTime() time.Time     { return time.Time{} }
+func (info skillPathFakeInfo) IsDir() bool       { return info.mode.IsDir() }
+func (skillPathFakeInfo) Sys() any               { return nil }
+
+type skillPathErrorDirEntry struct{}
+
+func (skillPathErrorDirEntry) Name() string               { return "broken" }
+func (skillPathErrorDirEntry) IsDir() bool                { return true }
+func (skillPathErrorDirEntry) Type() os.FileMode          { return os.ModeDir }
+func (skillPathErrorDirEntry) Info() (os.FileInfo, error) { return nil, errors.New("info failed") }
+
+type skillPathModeDirEntry struct {
+	mode os.FileMode
+}
+
+func (skillPathModeDirEntry) Name() string            { return "directory" }
+func (skillPathModeDirEntry) IsDir() bool             { return true }
+func (entry skillPathModeDirEntry) Type() os.FileMode { return entry.mode.Type() }
+func (entry skillPathModeDirEntry) Info() (os.FileInfo, error) {
+	return skillPathFakeInfo{mode: entry.mode}, nil
+}

internal/upgrade/skill_path_move_test.go

@@ -0,0 +1,451 @@
+package upgrade
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/DingTalk-Real-AI/dingtalk-workspace-cli/internal/testseam"
+)
+
+func TestCrossPlatformCoverageSkillPathCrossDeviceMove(t *testing.T) {
+	t.Run("directory file and lexical links", func(t *testing.T) {
+		root := t.TempDir()
+		t.Cleanup(func() { makeSkillPathTreeWritable(root) })
+		src := filepath.Join(root, "external", "dingtalk-chat")
+		dst := filepath.Join(root, "home", ".dws", "skill-backups", "stamp", "dingtalk-chat")
+		if err := os.MkdirAll(filepath.Join(src, "references"), 0o750); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("chat\n"), 0o640); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "references", "guide.md"), []byte("guide\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		linksCreated := true
+		if err := os.Symlink("SKILL.md", filepath.Join(src, "skill-link")); err != nil {
+			if runtime.GOOS != "windows" {
+				t.Fatal(err)
+			}
+			linksCreated = false
+		}
+		if linksCreated {
+			if err := os.Symlink("missing.md", filepath.Join(src, "dangling-link")); err != nil {
+				t.Fatal(err)
+			}
+		}
+
+		forceCrossDeviceRename(t, src, dst)
+		if err := moveSkillPathRecoverably(src, dst); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := os.Lstat(src); !os.IsNotExist(err) {
+			t.Fatalf("source must be removed: %v", err)
+		}
+		if got, err := os.ReadFile(filepath.Join(dst, "SKILL.md")); err != nil || string(got) != "chat\n" {
+			t.Fatalf("copied file = %q, %v", got, err)
+		}
+		if info, err := os.Stat(filepath.Join(dst, "SKILL.md")); err != nil {
+			t.Fatalf("copied file stat = %v, %v", info, err)
+		} else if runtime.GOOS != "windows" && info.Mode().Perm() != 0o640 {
+			t.Fatalf("copied file mode = %v; want 0640", info.Mode().Perm())
+		}
+		if linksCreated {
+			for name, want := range map[string]string{"skill-link": "SKILL.md", "dangling-link": "missing.md"} {
+				info, err := os.Lstat(filepath.Join(dst, name))
+				if err != nil || info.Mode()&os.ModeSymlink == 0 {
+					t.Fatalf("%s must remain a symlink: %v, %v", name, info, err)
+				}
+				if got, err := os.Readlink(filepath.Join(dst, name)); err != nil || got != want {
+					t.Fatalf("%s target = %q, %v; want %q", name, got, err, want)
+				}
+			}
+		}
+		assertNoCrossDeviceStage(t, dst)
+	})
+
+	t.Run("regular file root", func(t *testing.T) {
+		root := t.TempDir()
+		src := filepath.Join(root, "source-file")
+		dst := filepath.Join(root, "backup", "source-file")
+		if err := os.WriteFile(src, []byte("state"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		forceCrossDeviceRename(t, src, dst)
+		if err := moveSkillPathRecoverably(src, dst); err != nil {
+			t.Fatal(err)
+		}
+		if got, err := os.ReadFile(dst); err != nil || string(got) != "state" {
+			t.Fatalf("backup file = %q, %v", got, err)
+		}
+	})
+
+	t.Run("read-only directory mode is restored after copying children", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX directory permission semantics are unavailable")
+		}
+		root := t.TempDir()
+		t.Cleanup(func() { makeSkillPathTreeWritable(root) })
+		src := filepath.Join(root, "external", "dingtalk-chat")
+		dst := filepath.Join(root, "backup", "dingtalk-chat")
+		if err := os.MkdirAll(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("read only\n"), 0o444); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chmod(src, 0o555); err != nil {
+			t.Fatal(err)
+		}
+		forceCrossDeviceRename(t, src, dst)
+		if err := moveSkillPathRecoverably(src, dst); err != nil {
+			t.Fatal(err)
+		}
+		if info, err := os.Stat(dst); err != nil || info.Mode().Perm() != 0o555 {
+			t.Fatalf("copied directory mode = %v, %v", info, err)
+		}
+		if got, err := os.ReadFile(filepath.Join(dst, "SKILL.md")); err != nil || string(got) != "read only\n" {
+			t.Fatalf("copied read-only file = %q, %v", got, err)
+		}
+	})
+
+	t.Run("rollback uses the same cross-device contract", func(t *testing.T) {
+		root := t.TempDir()
+		backup := filepath.Join(root, "home", ".dws", "skill-backups", "stamp", "dingtalk-chat")
+		original := filepath.Join(root, "external", "claude", "skills", "dingtalk-chat")
+		if err := os.MkdirAll(backup, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(backup, "SKILL.md"), []byte("old"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		forceCrossDeviceRename(t, backup, original)
+		if err := RestoreSkillPath(backup, original); err != nil {
+			t.Fatal(err)
+		}
+		if got, err := os.ReadFile(filepath.Join(original, "SKILL.md")); err != nil || string(got) != "old" {
+			t.Fatalf("restored content = %q, %v", got, err)
+		}
+		if _, err := os.Lstat(backup); !os.IsNotExist(err) {
+			t.Fatalf("backup must be consumed after verified restore: %v", err)
+		}
+	})
+}
+
+func TestCrossPlatformCoverageSkillPathCrossDeviceFailures(t *testing.T) {
+	t.Run("non cross-device rename never copies", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		copied := false
+		testseam.Swap(t, &skillPathRenameNoReplace, func(string, string) (string, error) { return "", os.ErrPermission })
+		testseam.Swap(t, &skillPathCopy, func(string, string) error { copied = true; return nil })
+		if err := moveSkillPathRecoverably(src, dst); !errors.Is(err, os.ErrPermission) {
+			t.Fatalf("error = %v", err)
+		}
+		if copied {
+			t.Fatal("permission failure must not enter cross-device copy fallback")
+		}
+		assertSkillSourcePreserved(t, src)
+	})
+
+	for _, tc := range []struct {
+		name   string
+		copy   func(string, string) error
+		verify func(string, string) error
+	}{
+		{name: "copy failure", copy: func(string, string) error { return errors.New("copy failed") }},
+		{name: "verification failure", verify: func(string, string) error { return errors.New("verify failed") }},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			src, dst := makeSkillMoveFixture(t)
+			forceCrossDeviceRename(t, src, dst)
+			if tc.copy != nil {
+				testseam.Swap(t, &skillPathCopy, tc.copy)
+			}
+			if tc.verify != nil {
+				testseam.Swap(t, &skillPathVerify, tc.verify)
+			}
+			if err := moveSkillPathRecoverably(src, dst); err == nil {
+				t.Fatal("expected failure")
+			}
+			assertSkillSourcePreserved(t, src)
+			if _, err := os.Lstat(dst); !os.IsNotExist(err) {
+				t.Fatalf("formal backup must not publish: %v", err)
+			}
+			assertNoCrossDeviceStage(t, dst)
+		})
+	}
+
+	t.Run("staging publish failure", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		originalRename := skillPathRenameNoReplace
+		testseam.Swap(t, &skillPathRenameNoReplace, func(from, to string) (string, error) {
+			if from == src && to == dst {
+				return "", testCrossDeviceError()
+			}
+			if to == dst {
+				return "", errors.New("publish failed")
+			}
+			return originalRename(from, to)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "publish failed") {
+			t.Fatalf("error = %v", err)
+		}
+		assertSkillSourcePreserved(t, src)
+		assertNoCrossDeviceStage(t, dst)
+	})
+
+	t.Run("published verification failure preserves both", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		calls := 0
+		testseam.Swap(t, &skillPathVerify, func(string, string) error {
+			calls++
+			if calls == 2 {
+				return errors.New("published verify failed")
+			}
+			return nil
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "published verify failed") {
+			t.Fatalf("error = %v", err)
+		}
+		assertSkillSourcePreserved(t, src)
+		if _, err := os.Lstat(dst); err != nil {
+			t.Fatalf("verified backup candidate must remain: %v", err)
+		}
+		assertNoCrossDeviceStage(t, dst)
+	})
+
+	t.Run("source removal failure preserves both", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		originalRemove := skillPathRemoveAll
+		testseam.Swap(t, &skillPathRemoveAll, func(path string) error {
+			if path == src {
+				return errors.New("remove failed")
+			}
+			return originalRemove(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "均保留") {
+			t.Fatalf("error = %v", err)
+		}
+		assertSkillSourcePreserved(t, src)
+		if _, err := os.Lstat(dst); err != nil {
+			t.Fatalf("formal backup must remain: %v", err)
+		}
+	})
+
+	t.Run("read-only source mode is restored after removal failure", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX directory permission semantics are unavailable")
+		}
+		src, dst := makeSkillMoveFixture(t)
+		if err := os.Chmod(src, 0o555); err != nil {
+			t.Fatal(err)
+		}
+		forceCrossDeviceRename(t, src, dst)
+		originalRemove := skillPathRemoveAll
+		testseam.Swap(t, &skillPathRemoveAll, func(path string) error {
+			if path == src {
+				return errors.New("remove failed")
+			}
+			return originalRemove(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "均保留") {
+			t.Fatalf("error = %v", err)
+		}
+		if info, err := os.Stat(src); err != nil || info.Mode().Perm() != 0o555 {
+			t.Fatalf("source directory mode after failed removal = %v, %v", info, err)
+		}
+		if err := os.Chmod(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("source permission preparation failure preserves both", func(t *testing.T) {
+		if runtime.GOOS == "windows" {
+			t.Skip("POSIX directory permission semantics are unavailable")
+		}
+		src, dst := makeSkillMoveFixture(t)
+		if err := os.Chmod(src, 0o555); err != nil {
+			t.Fatal(err)
+		}
+		forceCrossDeviceRename(t, src, dst)
+		originalChmod := skillPathChmod
+		testseam.Swap(t, &skillPathChmod, func(path string, mode os.FileMode) error {
+			if path == src {
+				return errors.New("chmod failed")
+			}
+			return originalChmod(path, mode)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "chmod failed") {
+			t.Fatalf("error = %v", err)
+		}
+		if err := originalChmod(src, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("lying remover is detected", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		forceCrossDeviceRename(t, src, dst)
+		originalRemove := skillPathRemoveAll
+		testseam.Swap(t, &skillPathRemoveAll, func(path string) error {
+			if path == src {
+				return nil
+			}
+			return originalRemove(path)
+		})
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "仍存在") {
+			t.Fatalf("error = %v", err)
+		}
+		assertSkillSourcePreserved(t, src)
+	})
+
+	t.Run("same-filesystem fast path", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		if err := moveSkillPathRecoverably(src, dst); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := os.Lstat(src); !os.IsNotExist(err) {
+			t.Fatalf("source still exists: %v", err)
+		}
+	})
+
+	t.Run("existing destination is never overwritten", func(t *testing.T) {
+		src, dst := makeSkillMoveFixture(t)
+		if err := os.MkdirAll(dst, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := moveSkillPathRecoverably(src, dst); err == nil || !strings.Contains(err.Error(), "目标已存在") {
+			t.Fatalf("error = %v", err)
+		}
+		assertSkillSourcePreserved(t, src)
+	})
+}
+
+func TestCrossPlatformCoverageVerifySkillPathCopyMismatches(t *testing.T) {
+	t.Run("type", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.WriteFile(src, []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(dst, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "类型") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+	t.Run("directory entries", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.Mkdir(src, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Mkdir(dst, 0o700); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(src, "one"), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "数量") {
+			t.Fatalf("error = %v", err)
+		}
+		if err := os.WriteFile(filepath.Join(dst, "two"), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "目录项") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+	t.Run("file size and digest", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.WriteFile(src, []byte("same"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(dst, []byte("longer"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "大小") {
+			t.Fatalf("error = %v", err)
+		}
+		if err := os.WriteFile(dst, []byte("diff"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "摘要") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+	t.Run("symlink target", func(t *testing.T) {
+		root := t.TempDir()
+		src, dst := filepath.Join(root, "src"), filepath.Join(root, "dst")
+		if err := os.Symlink("one", src); err != nil {
+			if runtime.GOOS == "windows" {
+				t.Skip("symlink creation unavailable")
+			}
+			t.Fatal(err)
+		}
+		if err := os.Symlink("two", dst); err != nil {
+			t.Fatal(err)
+		}
+		if err := verifySkillPathCopy(src, dst); err == nil || !strings.Contains(err.Error(), "链接目标") {
+			t.Fatalf("error = %v", err)
+		}
+	})
+}
+
+func forceCrossDeviceRename(t *testing.T, src, dst string) {
+	t.Helper()
+	originalRename := skillPathRenameNoReplace
+	testseam.Swap(t, &skillPathRenameNoReplace, func(from, to string) (string, error) {
+		if from == src && to == dst {
+			return "", testCrossDeviceError()
+		}
+		return originalRename(from, to)
+	})
+}
+
+func makeSkillMoveFixture(t *testing.T) (string, string) {
+	t.Helper()
+	root := t.TempDir()
+	t.Cleanup(func() { makeSkillPathTreeWritable(root) })
+	src := filepath.Join(root, "external", "dingtalk-chat")
+	dst := filepath.Join(root, "home", ".dws", "skill-backups", "stamp", "dingtalk-chat")
+	if err := os.MkdirAll(src, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(src, "SKILL.md"), []byte("old"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return src, dst
+}
+
+func assertSkillSourcePreserved(t *testing.T, src string) {
+	t.Helper()
+	if got, err := os.ReadFile(filepath.Join(src, "SKILL.md")); err != nil || string(got) != "old" {
+		t.Fatalf("source content = %q, %v", got, err)
+	}
+}
+
+func assertNoCrossDeviceStage(t *testing.T, dst string) {
+	t.Helper()
+	entries, err := os.ReadDir(filepath.Dir(dst))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return
+		}
+		t.Fatal(err)
+	}
+	prefix := "." + filepath.Base(dst) + ".cross-device-"
+	for _, entry := range entries {
+		if strings.HasPrefix(entry.Name(), prefix) {
+			t.Fatalf("cross-device staging leaked: %s", entry.Name())
+		}
+	}
+}

internal/upgrade/skill_path_move_unix.go

@@ -0,0 +1,12 @@
+//go:build !windows
+
+package upgrade
+
+import (
+	"errors"
+	"syscall"
+)
+
+func isCrossDeviceError(err error) bool {
+	return errors.Is(err, syscall.EXDEV)
+}

internal/upgrade/skill_path_move_unix_test.go

@@ -0,0 +1,16 @@
+//go:build !windows
+
+package upgrade
+
+import (
+	"os"
+	"syscall"
+)
+
+func testCrossDeviceError() error {
+	return &os.LinkError{Op: "rename", Old: "src", New: "dst", Err: syscall.EXDEV}
+}
+
+func testNoReplaceUnsupportedErrors() []error {
+	return []error{syscall.EINVAL, syscall.ENOSYS, errNoReplaceRenameUnsupported}
+}