@mison/wecom-cleaner 1.0.0 → 1.1.0

package/README.md

@@ -23,6 +23,7 @@
 - [功能总览](#功能总览)
 - [能力边界](#能力边界)
 - [安装与运行](#安装与运行)
+- [Agent Skills 安装](#agent-skills-安装)
 - [常用参数](#常用参数)
 - [数据与审计文件](#数据与审计文件)
 - [开发与质量门禁](#开发与质量门禁)
@@ -63,7 +64,7 @@
 2. 文件存储目录识别
 
 - 支持默认路径、手动配置路径、自动探测路径。
-- 自动探测采用结构匹配（如 `*/WXWork Files/Caches`），不依赖目录名。
+- 自动探测采用“结构 + 缓存特征”联合识别（如 `*/WXWork Files/Caches` + 企业微信缓存类别/月目录信号），不依赖目录名且降低误判。
 - 自动探测结果默认不预选，需用户确认后纳入处理。
 
 3. 删除与恢复链路
@@ -86,9 +87,9 @@
 
 6. 可观测性与并发安全
 
-- `doctor` 模式可输出人类可读报告，或通过 `--json` 输出结构化结果。
+- `doctor` 模式可输出人类可读报告，或通过 `--output json` 输出结构化结果。
 - `doctor` 模式为只读体检：不会自动创建状态目录/回收区，也不会触发 Zig 自动修复下载。
-- 多实例并发默认加锁，检测到陈旧锁可交互清理或通过 `--force` 自动清理。
+- 多实例并发默认加锁；检测到陈旧锁会优先自动恢复，异常场景可用 `--force` 兜底清理。
 
 ## 能力边界
 
@@ -128,32 +129,117 @@ npm run e2e:smoke
 - 覆盖开始菜单与关键分支：年月清理、会话分析、全量治理、回收区治理、恢复、系统自检、设置。
 - 可用 `npm run e2e:smoke -- --keep` 保留日志与测试目录。
 
+## Agent Skills 安装
+
+内置技能：`wecom-cleaner-agent`（用于 Codex/Agent 无交互调用）。
+
+推荐方式（npmjs，最稳定）：
+
+```bash
+npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install
+```
+
+常用参数：
+
+- `--target <dir>`：自定义安装目录（默认 `$CODEX_HOME/skills` 或 `~/.codex/skills`）
+- `--force`：覆盖已存在技能目录
+- `--dry-run`：仅预演，不落盘
+
+示例：
+
+```bash
+npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --force
+npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --target ~/.codex/skills
+```
+
+GitHub 备选方式（无 npm 包依赖）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash
+```
+
+若需安装指定版本标签（例如 `v1.1.0`）：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.1.0
+```
+
 ## 常用参数
 
+运行方式：
+
+- 不带参数：进入交互菜单（TUI）。
+- 带参数：进入无交互执行（默认输出 JSON，适合 AI Agent）。
+- 带参数但需交互：可追加 `--interactive` 强制进入交互流程（支持配合 `--mode` 直达功能）。
+- 完整契约文档：[`docs/NON_INTERACTIVE_SPEC.md`](./docs/NON_INTERACTIVE_SPEC.md)。
+
+### 无交互动作参数（互斥，必须且只能一个）
+
+- `--cleanup-monthly`
+- `--analysis-only`
+- `--space-governance`
+- `--restore-batch <batchId>`
+- `--recycle-maintain`
+- `--doctor`
+
+### 无交互安全规则
+
+- 破坏性动作（清理/治理/恢复/回收区治理）默认 `dry-run`。
+- 显式真实执行需带 `--yes`。
+- 若传 `--dry-run false` 但未传 `--yes`，将直接退出（退出码 `3`）。
+
+### 常用无交互示例
+
 ```bash
-wecom-cleaner --root ~/Library/Containers/com.tencent.WeWorkMac/Data/Documents/Profiles
-wecom-cleaner --state-root ~/.wecom-cleaner-state
-wecom-cleaner --external-storage-root /Volumes/Data/MyWeComStorage
-wecom-cleaner --external-storage-auto-detect false
-wecom-cleaner --dry-run-default true
-wecom-cleaner --mode cleanup_monthly
-wecom-cleaner --mode space_governance
-wecom-cleaner --mode recycle_maintain
-wecom-cleaner --mode doctor
-wecom-cleaner --theme auto
-wecom-cleaner --json
-wecom-cleaner --force
+# 年月清理（默认 dry-run）
+wecom-cleaner --cleanup-monthly \
+  --accounts current \
+  --cutoff-month 2024-02 \
+  --categories files,images
+
+# 年月清理（真实执行）
+wecom-cleaner --cleanup-monthly \
+  --accounts all \
+  --months 2023-01,2023-02 \
+  --categories files \
+  --dry-run false \
+  --yes
+
+# 全量空间治理（仅建议项，真实执行）
+wecom-cleaner --space-governance \
+  --suggested-only true \
+  --tiers safe,caution \
+  --dry-run false \
+  --yes
+
+# 回收区治理（按策略执行）
+wecom-cleaner --recycle-maintain --dry-run false --yes
+
+# 批次恢复（冲突策略：重命名）
+wecom-cleaner --restore-batch 20260226-105009-ffa098 --conflict rename
+
+# 系统自检（默认 JSON 输出）
+wecom-cleaner --doctor
 ```
 
-### `--mode` 可选值
+### 输出与兼容参数
+
+- `--output json|text`：无交互输出格式，默认 `json`。
+- `--json`：兼容别名，等价于 `--output json`。
+- `--mode`：兼容参数，建议迁移到动作参数（如 `--cleanup-monthly`）。
+- `--save-config`：将本次全局配置参数写回 `config.json`。
+
+### 全局参数
 
-- `cleanup_monthly`
-- `analysis_only`
-- `space_governance`
-- `recycle_maintain`
-- `restore`
-- `doctor`
-- `settings`
+- `--root <path>`：Profile 根目录
+- `--state-root <path>`：状态目录
+- `--external-storage-root <path[,path...]>`：手动文件存储目录（配置层）
+- `--external-storage-auto-detect <true|false>`：外部存储自动探测总开关
+- `--external-roots <path[,path...]>`：本次动作临时覆盖的文件存储目录
+- `--external-roots-source <preset|configured|auto|all>`：按来源筛选探测目录（默认 `preset`）
+- `--theme <auto|light|dark>`：Logo 主题
+- `--interactive`：即使携带参数也进入交互流程（可配合 `--mode`）
+- `--force`：锁异常场景下强制清理并继续（兜底参数，通常无需）
 
 ### `--theme` 可选值
 
@@ -233,10 +319,10 @@ npm run e2e:smoke -- --keep
 npm run pack:tgz:dry-run
 ```
 
-当前基线（`v1.0.0`）：
+当前基线（`v1.1.0`）：
 
-- 单元测试：`47/47` 通过。
-- 覆盖率：`statements 85.65%`，`branches 70.99%`，`functions 91.39%`，`lines 85.65%`。
+- 单元测试：`68/68` 通过。
+- 覆盖率：`statements 86.57%`，`branches 73.96%`，`functions 93.25%`，`lines 86.57%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
 ## 发布与打包
@@ -271,14 +357,14 @@ npm run pack:tgz
 
 # 2) 推送主分支与标签
 git push origin main
-git tag v1.0.0
-git push origin v1.0.0
+git tag v1.1.0
+git push origin v1.1.0
 
 # 3) 发布 GitHub Release（附 tgz 包）
-gh release create v1.0.0 \
-  --title "v1.0.0" \
-  --notes-file docs/releases/v1.0.0.md \
-  wecom-cleaner-1.0.0.tgz
+gh release create v1.1.0 \
+  --title "v1.1.0" \
+  --notes-file docs/releases/v1.1.0.md \
+  wecom-cleaner-1.1.0.tgz
 
 # 4) 发布 npm
 npm publish --access public

package/docs/IMPLEMENTATION_PLAN.md

@@ -122,7 +122,7 @@
 - 使用 `c8` 输出覆盖率报告。
 - 门禁阈值：`lines/statements >= 75%`，`functions >= 80%`，`branches >= 60%`。
 - 命令：`npm run test:coverage` / `npm run test:coverage:check`。
-- `v1.0.0` 基线：`statements 85.65%`，`branches 70.99%`，`functions 91.39%`，`lines 85.65%`。
+- `v1.1.0` 基线：`statements 86.57%`，`branches 73.96%`，`functions 93.25%`，`lines 86.57%`。
 
 4. 端到端回归
 
@@ -138,21 +138,21 @@ npm run e2e:smoke -- --keep
 npm run pack:tgz:dry-run
 ```
 
-## 7. 发布执行（首个正式版）
+## 7. 发布执行（当前版本）
 
 1. 版本与产物
 
-- `package.json` / `package-lock.json`：`1.0.0`
-- `native/manifest.json`：版本与 `baseUrl` 对齐 `v1.0.0`
+- `package.json` / `package-lock.json`：`1.1.0`
+- `native/manifest.json`：版本与 `baseUrl` 对齐 `v1.1.0`
 - 默认打包双架构核心：`darwin-x64` + `darwin-arm64`
 
 2. GitHub Release
 
 ```bash
 git push origin main
-git tag v1.0.0
-git push origin v1.0.0
-gh release create v1.0.0 --title "v1.0.0" --notes-file docs/releases/v1.0.0.md wecom-cleaner-1.0.0.tgz
+git tag v1.1.0
+git push origin v1.1.0
+gh release create v1.1.0 --title "v1.1.0" --notes-file docs/releases/v1.1.0.md wecom-cleaner-1.1.0.tgz
 ```
 
 3. npm 发布

package/docs/NON_INTERACTIVE_SPEC.md

@@ -0,0 +1,115 @@
+# 无交互参数规范（AI Agent）
+
+本文档定义 `wecom-cleaner` 的无交互 CLI 契约，供 AI Agent/脚本稳定调用。
+
+## 1. 运行入口
+
+- `wecom-cleaner`（不带参数）：进入交互模式（TUI）。
+- `wecom-cleaner ...args`（带参数）：进入无交互模式。
+- `wecom-cleaner ...args --interactive`：即使带参数也强制进入交互模式（常用于本地调试/脚本回放）。
+
+## 2. 动作选择（必填且互斥）
+
+无交互模式必须且只能提供一个动作参数：
+
+- `--cleanup-monthly`
+- `--analysis-only`
+- `--space-governance`
+- `--restore-batch <batchId>`
+- `--recycle-maintain`
+- `--doctor`
+
+若缺少动作或动作冲突，退出码为 `2`。
+
+## 3. 安全确认与 dry-run
+
+破坏性动作：`cleanup-monthly`、`space-governance`、`restore-batch`、`recycle-maintain`。
+
+规则：
+
+- 默认 `dry-run`（不执行真实删除/恢复）。
+- 真实执行需显式传 `--yes`。
+- 若传 `--dry-run false` 且未传 `--yes`，退出码为 `3`。
+
+## 4. 输出协议
+
+无交互默认输出 JSON，可通过 `--output text` 切换文本。
+
+- `--output json|text`（默认 `json`）
+- `--json` 为兼容别名（等价 `--output json`）
+
+JSON 顶层字段：
+
+- `ok`：布尔
+- `action`：动作名
+- `dryRun`：布尔或 `null`
+- `summary`：动作摘要
+- `warnings`：字符串数组
+- `errors`：错误数组（`code`、`message`、可选路径字段）
+- `data`：动作明细数据
+- `meta`：元信息（版本、耗时、引擎、时间戳等）
+
+## 5. 退出码
+
+- `0`：执行成功（含 dry-run 成功）
+- `1`：执行失败（业务失败/运行失败）
+- `2`：参数错误或动作契约错误
+- `3`：缺少真实执行确认（`--yes`）
+
+## 6. 全局参数
+
+- `--root <path>`：Profile 根目录
+- `--state-root <path>`：状态目录
+- `--external-storage-root <path[,path...]>`：配置层手动文件存储目录
+- `--external-storage-auto-detect <true|false>`：自动探测开关
+- `--external-roots <path[,path...]>`：动作层临时覆盖文件存储目录
+- `--external-roots-source <preset|configured|auto|all>`：按来源筛选探测目录（默认 `preset`）
+- `--theme <auto|light|dark>`
+- `--interactive`：强制交互模式（与无交互动作参数互斥使用时，优先按交互模式执行）
+- `--force`：锁异常场景下强制清理并继续（兜底参数）
+- `--save-config`：把本次全局参数落盘到 `config.json`
+
+## 7. 动作参数
+
+### 7.1 `--cleanup-monthly`
+
+- `--accounts <all|current|id1,id2...>`
+- `--months <YYYY-MM,...>` 或 `--cutoff-month <YYYY-MM>`（二选一）
+- `--categories <all|key1,key2...>`
+- `--include-non-month-dirs <true|false>`
+- `--dry-run <true|false>`
+
+### 7.2 `--analysis-only`
+
+- `--accounts <all|current|id1,id2...>`
+- `--categories <all|key1,key2...>`
+
+### 7.3 `--space-governance`
+
+- `--accounts <all|current|id1,id2...>`
+- `--targets <targetId1,targetId2...>`
+- `--tiers <safe|caution|protected>`
+- `--suggested-only <true|false>`
+- `--allow-recent-active <true|false>`
+- `--dry-run <true|false>`
+
+### 7.4 `--restore-batch <batchId>`
+
+- `--conflict <skip|overwrite|rename>`（默认 `skip`）
+- `--dry-run <true|false>`
+
+### 7.5 `--recycle-maintain`
+
+- `--retention-enabled <true|false>`
+- `--retention-max-age-days <int>`
+- `--retention-min-keep-batches <int>`
+- `--retention-size-threshold-gb <int>`
+- `--dry-run <true|false>`
+
+### 7.6 `--doctor`
+
+- 无动作专属参数；只读执行，返回健康报告。
+
+## 8. 兼容参数
+
+- `--mode`：兼容旧调用，会映射到动作参数并附带 warning，建议迁移。

package/docs/releases/v1.1.0.md

@@ -0,0 +1,36 @@
+# wecom-cleaner v1.1.0
+
+本版本重点是：Agent 可安装技能能力正式内置、无交互调用链路更稳定、发布与验证流程完整收口。
+
+## 新增能力
+
+- 内置 Agent 技能：`skills/wecom-cleaner-agent`
+  - 包含 `SKILL.md`、`agents/openai.yaml`、`references/commands.md`
+- 新增技能安装命令：`wecom-cleaner-skill install`
+  - 支持 `--target`、`--force`、`--dry-run`
+- 新增 GitHub 一键安装脚本：`scripts/install-skill.sh`
+
+## 关键改进
+
+- 无交互协议正式化并文档化：`docs/NON_INTERACTIVE_SPEC.md`
+- 启动行为统一：无参数进交互、带参数走无交互
+- 无交互默认 JSON 输出，兼容 `--json`，并提示 `--mode` 迁移
+- Zig 核心版本统一到 `1.1.0`，manifest 与下载基地址同步到 `v1.1.0`
+
+## 修复与安全
+
+- 修复恢复 `dry-run + overwrite` 分支潜在实删问题
+- 修复回收区治理异常批次路径可能越界的问题
+- `scripts/install-skill.sh` 兼容 `--target` 指向不存在父目录
+- 强化路径白名单 + `realpath` 边界防护与审计落盘
+
+## 质量与验证
+
+- 单元测试：`68/68` 通过
+- 覆盖率：`statements 86.57%`，`branches 73.96%`，`functions 93.25%`，`lines 86.57%`
+- 全菜单 smoke：通过（含恢复冲突分支、doctor JSON、设置菜单）
+
+## 兼容性
+
+- 当前正式支持：macOS（x64 / arm64）
+- Windows 兼容仍在后续版本规划中

package/native/manifest.json

@@ -1,15 +1,15 @@
 {
   "schemaVersion": 1,
-  "version": "1.0.0",
-  "baseUrl": "https://raw.githubusercontent.com/MisonL/wecom-cleaner/v1.0.0/native/bin",
+  "version": "1.1.0",
+  "baseUrl": "https://raw.githubusercontent.com/MisonL/wecom-cleaner/v1.1.0/native/bin",
   "targets": {
     "darwin-x64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "14cfa26895101e7b71824e6bb9282f08a38f9dad72d4df2934094eb2ceefbad0"
+      "sha256": "d6bc4b2a7b96010889fc11502fe6d76d6f8d395e6df12c44dfc79aa58b17d53c"
     },
     "darwin-arm64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "fc33ce3fb44309170da8c2867d11eae552e2e9d3c95b8f0e5a8e8392bb630744"
+      "sha256": "f3babdfe69e83c2d0b99fe1ad525ea836e4f413c01ae2f31b569e35f2ba955f8"
     }
   }
 }

package/native/zig/src/main.zig

@@ -56,7 +56,7 @@ fn dirTreeSize(dir: *std.fs.Dir) !u64 {
 }
 
 fn printPing(writer: *std.Io.Writer) !void {
-    try writer.writeAll("{\"ok\":true,\"engine\":\"zig\",\"version\":\"1.0.0\"}\n");
+    try writer.writeAll("{\"ok\":true,\"engine\":\"zig\",\"version\":\"1.1.0\"}\n");
 }
 
 fn runDu(args: []const []const u8, writer: *std.Io.Writer) !void {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/wecom-cleaner",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "企业微信本地聊天缓存清理工具（交互式 CLI/TUI）",
   "author": "MisonL",
   "license": "MIT",
@@ -14,11 +14,13 @@
   "homepage": "https://github.com/MisonL/wecom-cleaner",
   "type": "module",
   "bin": {
-    "wecom-cleaner": "./src/cli.js"
+    "wecom-cleaner": "src/cli.js",
+    "wecom-cleaner-skill": "src/skill-cli.js"
   },
   "main": "./src/cli.js",
   "files": [
     "src",
+    "skills",
     "native",
     "README.md",
     "LICENSE",
@@ -43,7 +45,9 @@
     "e2e:smoke": "bash scripts/e2e-smoke.sh",
     "prepack": "npm run build:native:release && npm run check",
     "pack:tgz": "node scripts/pack-tgz.js",
-    "pack:tgz:dry-run": "node scripts/pack-tgz.js --dry-run"
+    "pack:tgz:dry-run": "node scripts/pack-tgz.js --dry-run",
+    "skill:install": "node src/skill-cli.js install",
+    "skill:path": "node src/skill-cli.js path"
   },
   "keywords": [
     "wecom",

package/skills/wecom-cleaner-agent/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wecom-cleaner-agent
+description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理或系统自检，并要求 JSON 输出解析与 dry-run 安全门槛时触发。
+---
+
+# wecom-cleaner-agent
+
+## 何时触发
+
+- 用户要清理企业微信本地缓存，且希望由 Agent 自动执行。
+- 用户要走无交互 CLI，返回可机读 JSON 结果。
+- 用户要执行以下任一能力：盘点、年月清理、全量治理、批次恢复、回收区治理、系统自检。
+
+## 默认执行策略
+
+1. 优先无交互模式，不进入 TUI。
+2. 先执行 `--doctor --output json` 做只读体检。
+3. 每次调用必须且只能提供一个动作参数。
+4. 破坏性动作先 dry-run，再根据用户确认决定真实执行。
+5. 每次执行都使用 `--output json`，按字段解析结果并汇报。
+
+## 动作契约
+
+无交互模式只能选一个动作：
+
+- `--cleanup-monthly`
+- `--analysis-only`
+- `--space-governance`
+- `--restore-batch <batchId>`
+- `--recycle-maintain`
+- `--doctor`
+
+退出码约定：
+
+- `0` 成功
+- `1` 业务失败或运行失败
+- `2` 参数错误或动作冲突
+- `3` 请求真实执行但缺少 `--yes`
+
+## 安全门槛
+
+- 未获明确授权前，不执行真实删除或真实恢复。
+- `cleanup-monthly`、`space-governance`、`restore-batch`、`recycle-maintain` 默认保持 dry-run。
+- 真实执行必须同时满足：
+  - 用户明确同意
+  - 命令显式携带 `--dry-run false --yes`
+  - 已确认处理范围（账号、月份/目标、类别、目录来源）
+
+## 输出解析规则
+
+- 必须使用 `--output json`。
+- 重点字段：
+  - `ok`：是否成功
+  - `action`：执行动作
+  - `dryRun`：是否预演
+  - `summary`：核心统计
+  - `warnings`：兼容或降级提示
+  - `errors`：错误详情（`code/message/path`）
+  - `meta`：版本、耗时、引擎
+- 判定逻辑：
+  - `ok=true`：输出关键统计并进入下一步
+  - `ok=false`：先汇总 `errors`，再给出修复后重试策略
+  - `warnings` 包含引擎回退时：标记为非阻塞风险并继续
+
+## 交互模式原则
+
+- 默认不使用 `--interactive`。
+- 仅当用户明确要求交互演示或人工选择时，才进入交互模式。
+
+## 参考资料
+
+- 常用命令模板：`references/commands.md`

package/skills/wecom-cleaner-agent/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: 'WeCom Cleaner Agent'
+  short_description: '面向AI Agent的企业微信缓存清理与恢复无交互执行技能'
+  default_prompt: '请使用 $wecom-cleaner-agent 对企业微信缓存执行一次先 dry-run 再确认执行的无交互清理流程。'
+  brand_color: '#0EA5E9'

package/skills/wecom-cleaner-agent/references/commands.md

@@ -0,0 +1,140 @@
+# wecom-cleaner 命令参考（Agent）
+
+## 1. 路径变量
+
+建议先在执行环境准备变量：
+
+```bash
+ROOT="/Users/<name>/Library/Containers/com.tencent.WeWorkMac/Data/Documents/Profiles"
+STATE="$HOME/.wecom-cleaner-state"
+```
+
+如需显式指定外部文件存储目录：
+
+```bash
+EXT="/Volumes/Data/WXWork_Data"
+```
+
+## 2. 只读动作
+
+系统体检：
+
+```bash
+wecom-cleaner --doctor --output json --root "$ROOT" --state-root "$STATE"
+```
+
+缓存盘点（按账号/类型）：
+
+```bash
+wecom-cleaner --analysis-only \
+  --accounts current \
+  --categories files,images,videos \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+## 3. 年月清理（先 dry-run）
+
+```bash
+wecom-cleaner --cleanup-monthly \
+  --accounts all \
+  --cutoff-month 2024-02 \
+  --categories files,images \
+  --include-non-month-dirs false \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+真实执行（仅用户明确授权后）：
+
+```bash
+wecom-cleaner --cleanup-monthly \
+  --accounts all \
+  --months 2023-01,2023-02 \
+  --categories files \
+  --dry-run false \
+  --yes \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+## 4. 全量空间治理（先 dry-run）
+
+```bash
+wecom-cleaner --space-governance \
+  --suggested-only true \
+  --tiers safe,caution \
+  --allow-recent-active false \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+真实执行：
+
+```bash
+wecom-cleaner --space-governance \
+  --targets <target1,target2> \
+  --dry-run false \
+  --yes \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+## 5. 批次恢复
+
+先查可恢复批次（通过审计或先执行 `--doctor`/`--analysis-only` 获取上下文），再恢复：
+
+```bash
+wecom-cleaner --restore-batch <batchId> \
+  --conflict rename \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+真实恢复：
+
+```bash
+wecom-cleaner --restore-batch <batchId> \
+  --conflict overwrite \
+  --dry-run false \
+  --yes \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+## 6. 回收区治理
+
+```bash
+wecom-cleaner --recycle-maintain \
+  --retention-enabled true \
+  --retention-max-age-days 30 \
+  --retention-min-keep-batches 20 \
+  --retention-size-threshold-gb 20 \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+真实治理：
+
+```bash
+wecom-cleaner --recycle-maintain \
+  --retention-enabled true \
+  --dry-run false \
+  --yes \
+  --output json \
+  --root "$ROOT" --state-root "$STATE"
+```
+
+## 7. 输出解析要点
+
+- 成功判定：`ok == true`
+- 失败详情：`errors[]`
+- 核心统计：`summary`（如 `successCount/skippedCount/failedCount/reclaimedBytes`）
+- 执行引擎：`meta.engine`
+
+## 8. 常见失败与处理
+
+- 退出码 `2`：动作参数冲突或缺失，检查是否只给了一个动作参数。
+- 退出码 `3`：缺少真实执行确认，补 `--yes` 或回退到 dry-run。
+- `errors.code=path_validation_failed`：路径越界/白名单不匹配，核对 `--root` 与目录范围。
+- `errors.code=permission_denied`：权限不足，调整目录权限后重试。