@mison/wecom-cleaner 1.2.1 → 1.3.2

package/README.md

@@ -92,6 +92,15 @@
 - `doctor` 模式为只读体检：不会自动创建状态目录/回收区，也不会触发 Zig 自动修复下载。
 - 多实例并发默认加锁；检测到陈旧锁会优先自动恢复，异常场景可用 `--force` 兜底清理。
 
+7. 自主升级体系
+
+- 启动后按“早/午/晚”三时段检查更新（默认开启）。
+- 版本源优先 npmjs，失败自动回退 GitHub Release。
+- 交互模式发现新版本时可直接选择升级方式：
+  - npm 升级（默认）
+  - GitHub 脚本升级
+- 无交互模式仅提示不阻断任务执行。
+
 ## 能力边界
 
 企业微信会话数据库为私有/加密格式，当前无法稳定建立“会话名 -> 本地缓存目录”的强映射。
@@ -159,10 +168,10 @@ GitHub 备选方式（无 npm 包依赖）：
 curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash
 ```
 
-若需安装指定版本标签（例如 `v1.2.1`）：
+若需安装指定版本标签（例如 `v1.3.2`）：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.2.1
+curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.3.2
 ```
 
 Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`）：
@@ -173,6 +182,8 @@ Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`
 - `restore_batch_report.sh`：批次恢复任务卡片
 - `recycle_maintain_report.sh`：回收区治理任务卡片
 - `doctor_report.sh`：系统自检任务卡片
+- `check_update_report.sh`：检查更新任务卡片
+- `upgrade_report.sh`：程序升级任务卡片（默认预演）
 
 ## 常用参数
 
@@ -191,6 +202,8 @@ Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`
 - `--restore-batch <batchId>`
 - `--recycle-maintain`
 - `--doctor`
+- `--check-update`
+- `--upgrade <npm|github-script>`
 
 ### 无交互安全规则
 
@@ -225,21 +238,38 @@ wecom-cleaner --space-governance \
 # 回收区治理（按策略执行）
 wecom-cleaner --recycle-maintain --dry-run false --yes
 
+# 年月清理（三阶段协议：预演 -> 执行 -> 复核）
+wecom-cleaner --cleanup-monthly --accounts all --cutoff-month 2024-04 --run-task preview-execute-verify --yes
+
 # 批次恢复（冲突策略：重命名）
 wecom-cleaner --restore-batch 20260226-105009-ffa098 --conflict rename
 
 # 系统自检（默认 JSON 输出）
 wecom-cleaner --doctor
+
+# 检查更新（不执行升级）
+wecom-cleaner --check-update --output text
+
+# 执行升级（npm 默认方式）
+wecom-cleaner --upgrade npm --upgrade-yes
+
+# 执行升级（GitHub 托管脚本方式）
+wecom-cleaner --upgrade github-script --upgrade-version 1.3.2 --upgrade-yes
 ```
 
 ### 输出与兼容参数
 
 - `--output json|text`：无交互输出格式，默认 `json`。
 - `--json`：兼容别名，等价于 `--output json`。
+- `--run-task preview|execute|preview-execute-verify`：阶段任务协议（推荐给 Agent）。
+- `--scan-debug off|summary|full`：扫描诊断信息输出等级。
 - `--mode`：兼容参数，建议迁移到动作参数（如 `--cleanup-monthly`）。
 - `--save-config`：将本次全局配置参数写回 `config.json`。
 - `--help` / `-h`：输出命令帮助并退出。
 - `--version` / `-v`：输出版本号并退出。
+- `--upgrade-channel stable|pre`：升级检查通道（稳定版/预发布）。
+- `--upgrade-version <x.y.z>`：指定升级目标版本。
+- `--upgrade-yes`：确认执行升级动作（无此参数将拒绝执行升级）。
 
 ### 各动作关键统计字段（JSON）
 
@@ -255,6 +285,7 @@ wecom-cleaner --doctor
 - `summary.rootPathCount`：涉及的清理根目录数量
 - `summary.accountCount` / `monthCount` / `categoryCount` / `externalRootCount`
 - `summary.cutoffMonth`：截止月份（当使用 `--cutoff-month` 时）
+- `summary.runTaskMode` / `summary.taskDecision`：阶段协议模式与决策（仅 `--run-task`）
 
 `cleanup-monthly` 还会在 `data.report` 中返回可展示明细：
 
@@ -263,6 +294,9 @@ wecom-cleaner --doctor
 - `data.report.matched.rootStats`：按根目录统计（条目数、体积）
 - `data.report.matched.topPaths`：按体积 Top 路径样例
 - `data.report.executed.byCategory/byMonth/byRoot`：真实执行落地统计（成功/跳过/失败 + 体积）
+- `data.taskPhases`：阶段执行明细（预演/执行/复核）
+- `data.taskCard`：面向用户的任务卡片聚合结果
+- `data.scanDebug`：扫描诊断（当 `--scan-debug summary|full`）
 
 #### `analysis-only`
 
@@ -302,6 +336,23 @@ wecom-cleaner --doctor
 - `data.metrics`：账号数、回收区占用、外部存储等关键指标
 - `data.runtime`：运行时环境信息
 
+#### `check-update`
+
+- `summary.checked`：是否完成检查
+- `summary.hasUpdate`：是否发现新版本
+- `summary.currentVersion` / `latestVersion`
+- `summary.source`：`npm` 或 `github`
+- `summary.channel`：`stable` 或 `pre`
+- `data.update`：检查详情（含 `errors`、`checkReason`、`checkedAt`）
+
+#### `upgrade`
+
+- `summary.executed`：是否执行了升级命令
+- `summary.method`：`npm` 或 `github-script`
+- `summary.targetVersion`：目标版本
+- `summary.status`：升级命令退出码
+- `data.upgrade.command`：实际执行命令
+
 ### 全局参数
 
 - `--root <path>`：Profile 根目录
@@ -313,6 +364,8 @@ wecom-cleaner --doctor
 - `--theme <auto|light|dark>`：Logo 主题
 - `--interactive`：即使携带参数也进入交互流程（可配合 `--mode`）
 - `--force`：锁异常场景下强制清理并继续（兜底参数，通常无需）
+- `--run-task preview|execute|preview-execute-verify`：阶段任务协议（推荐无交互自动化调用）
+- `--scan-debug off|summary|full`：附加扫描诊断信息
 
 ### `--theme` 可选值
 
@@ -327,6 +380,7 @@ wecom-cleaner --doctor
 - `WECOM_CLEANER_NATIVE_DOWNLOAD_TIMEOUT_MS=<ms>`：下载超时（默认 `15000`）
 - `WECOM_CLEANER_NATIVE_PROBE_TIMEOUT_MS=<ms>`：核心探针超时（默认 `3000`，最小 `500`）
 - `WECOM_CLEANER_EXTERNAL_AUTO_DETECT=true|false`：外部存储自动探测总开关
+- `WECOM_CLEANER_AUTO_UPDATE=true|false`：自主升级自动检查总开关（默认 `true`）
 
 ## 数据与审计文件
 
@@ -395,8 +449,8 @@ npm run pack:tgz:dry-run
 
 当前基线（主分支）：
 
-- 单元测试：`91/91` 通过。
-- 覆盖率：`statements 88.49%`，`branches 75.01%`，`functions 95.02%`，`lines 88.49%`。
+- 单元测试：`107/107` 通过。
+- 覆盖率：`statements 87.66%`，`branches 74.38%`，`functions 92.47%`，`lines 87.66%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
 ## 测试矩阵
@@ -439,18 +493,19 @@ npm run pack:tgz
 npm run pack:release-assets
 
 # 2) 推送主分支与标签
+VERSION="1.3.2"
 git push origin main
-git tag v1.2.1
-git push origin v1.2.1
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
 
 # 3) 发布 GitHub Release（附 npm 包 + 双架构核心附件）
-gh release create v1.2.1 \
-  --title "v1.2.1" \
-  --notes-file docs/releases/v1.2.1.md \
-  wecom-cleaner-1.2.1.tgz \
-  dist/release/wecom-cleaner-core-v1.2.1-darwin-x64 \
-  dist/release/wecom-cleaner-core-v1.2.1-darwin-arm64 \
-  dist/release/wecom-cleaner-core-v1.2.1-SHA256SUMS.txt
+gh release create "v${VERSION}" \
+  --title "v${VERSION}" \
+  --notes-file "docs/releases/v${VERSION}.md" \
+  "wecom-cleaner-${VERSION}.tgz" \
+  "dist/release/wecom-cleaner-core-v${VERSION}-darwin-x64" \
+  "dist/release/wecom-cleaner-core-v${VERSION}-darwin-arm64" \
+  "dist/release/wecom-cleaner-core-v${VERSION}-SHA256SUMS.txt"
 
 # 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.1.0` 基线：`statements 86.57%`，`branches 73.96%`，`functions 93.25%`，`lines 86.57%`。
+- `v1.3.2` 基线：`statements 87.66%`，`branches 74.38%`，`functions 92.47%`，`lines 87.66%`。
 
 4. 端到端回归
 
@@ -142,17 +142,17 @@ npm run pack:tgz:dry-run
 
 1. 版本与产物
 
-- `package.json` / `package-lock.json`：`1.1.0`
-- `native/manifest.json`：版本与 `baseUrl` 对齐 `v1.1.0`
+- `package.json` / `package-lock.json`：`1.3.2`
+- `native/manifest.json`：版本与 `baseUrl` 对齐当前发布标签
 - 默认打包双架构核心：`darwin-x64` + `darwin-arm64`
 
 2. GitHub Release
 
 ```bash
 git push origin main
-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
+git tag v1.3.2
+git push origin v1.3.2
+gh release create v1.3.2 --title "v1.3.2" --notes-file docs/releases/v1.3.2.md wecom-cleaner-1.3.2.tgz
 ```
 
 3. npm 发布

package/docs/NON_INTERACTIVE_SPEC.md

@@ -20,6 +20,8 @@
 - `--restore-batch <batchId>`
 - `--recycle-maintain`
 - `--doctor`
+- `--check-update`
+- `--upgrade <npm|github-script>`
 
 若缺少动作或动作冲突，退出码为 `2`。
 
@@ -32,6 +34,10 @@
 - 默认 `dry-run`（不执行真实删除/恢复）。
 - 真实执行需显式传 `--yes`。
 - 若传 `--dry-run false` 且未传 `--yes`，退出码为 `3`。
+- 可通过 `--run-task` 启用阶段协议：
+  - `preview`：仅预演阶段。
+  - `execute`：仅真实执行阶段（破坏性动作需 `--yes`）。
+  - `preview-execute-verify`：预演 -> 真实执行 -> 同条件复核（预演命中 `0` 时自动跳过执行与复核）。
 
 ## 4. 输出协议
 
@@ -39,6 +45,8 @@
 
 - `--output json|text`（默认 `json`）
 - `--json` 为兼容别名（等价 `--output json`）
+- `--run-task preview|execute|preview-execute-verify`（推荐破坏性动作使用）
+- `--scan-debug off|summary|full`（默认 `off`）
 
 JSON 顶层字段：
 
@@ -50,6 +58,10 @@ JSON 顶层字段：
 - `errors`：错误数组（`code`、`message`、可选路径字段）
 - `data`：动作明细数据
 - `meta`：元信息（版本、耗时、引擎、时间戳等）
+- `data.userFacingSummary`：统一的用户侧结果摘要（范围 + 结果 + 关键分布）
+- `data.taskPhases`：阶段协议明细（仅在 `--run-task` 时返回）
+- `data.taskCard`：阶段任务卡片（仅在 `--run-task` 时返回）
+- `data.scanDebug`：扫描诊断信息（仅在 `--scan-debug summary|full` 时返回）
 
 `cleanup_monthly` 常见 `summary` 字段：
 
@@ -164,6 +176,32 @@ JSON 顶层字段：
 - `metrics`：关键计数与容量
 - `runtime`：平台与运行时信息
 
+`check_update` 常见 `summary` 字段：
+
+- `checked`
+- `hasUpdate`
+- `currentVersion` / `latestVersion`
+- `source`
+- `channel`
+- `skippedByUser`
+
+`check_update` 的 `data`：
+
+- `update`：更新检查详情（`checkedAt`、`checkReason`、`errors`、`upgradeMethods`）
+
+`upgrade` 常见 `summary` 字段：
+
+- `executed`
+- `method`
+- `targetVersion`
+- `status`
+- `command`
+
+`upgrade` 的 `data`：
+
+- `upgrade`：升级执行结果（stdout/stderr/exit status）
+- `update`：升级前检查结果（若有）
+
 ## 5. 退出码
 
 - `0`：执行成功（含 dry-run 成功）
@@ -183,6 +221,11 @@ JSON 顶层字段：
 - `--interactive`：强制交互模式（与无交互动作参数互斥使用时，优先按交互模式执行）
 - `--force`：锁异常场景下强制清理并继续（兜底参数）
 - `--save-config`：把本次全局参数落盘到 `config.json`
+- `--upgrade-channel <stable|pre>`：更新通道（稳定版/预发布）
+- `--upgrade-version <x.y.z>`：升级到指定版本
+- `--upgrade-yes`：确认执行升级（无此参数将拒绝执行升级）
+- `--run-task preview|execute|preview-execute-verify`：无交互阶段协议
+- `--scan-debug off|summary|full`：扫描诊断输出等级
 
 ## 7. 动作参数
 
@@ -234,6 +277,26 @@ JSON 顶层字段：
 
 - 无动作专属参数；只读执行，返回健康报告。
 
+### 7.7 `--check-update`
+
+- `--upgrade-channel <stable|pre>`（可选，默认读取配置）
+
+说明：
+
+- 手动触发版本检查，不执行升级动作。
+- 检测优先 npm，失败自动回退 GitHub。
+
+### 7.8 `--upgrade <npm|github-script>`
+
+- `--upgrade-version <x.y.z>`（可选；缺省时先检查更新并升级到最新）
+- `--upgrade-channel <stable|pre>`（可选）
+- `--upgrade-yes`（必填确认）
+
+说明：
+
+- `npm`：执行 `npm i -g @mison/wecom-cleaner@<version>`
+- `github-script`：执行 GitHub 托管脚本 `scripts/upgrade.sh`
+
 ## 8. 兼容参数
 
 - `--mode`：兼容旧调用，会映射到动作参数并附带 warning，建议迁移。

package/docs/TEST_MATRIX.md

@@ -24,6 +24,8 @@
 - `restore`
 - `recycle_maintain`
 - `doctor`
+- `check_update`
+- `upgrade`
 
 ### 维度 C：范围组合
 
@@ -37,6 +39,8 @@
 - dry-run（预演）
 - 真实执行（`--dry-run false --yes`）
 - 真实执行后复核（同条件二次运行）
+- 阶段协议（`--run-task preview|execute|preview-execute-verify`）
+- 扫描诊断（`--scan-debug summary|full`）
 
 ### 维度 E：异常与边界
 
@@ -90,17 +94,21 @@
 
 1. `cleanup_monthly`：`--cutoff-month` + `--output json` + dry-run（有目标 / 无目标）
 2. `cleanup_monthly`：真实执行 + 复核（复核命中应下降或归零）
-3. `space_governance`：`suggested-only` 与 `allow-recent-active` 组合
-4. `restore`：`skip/overwrite/rename` 三冲突策略
-5. `recycle_maintain`：`disabled` / `no_candidate` / `partial_failed`
-6. `doctor`：只读模式不创建状态目录
-7. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
+3. `cleanup_monthly`：`--run-task preview-execute-verify --yes`（阶段字段稳定）
+4. `cleanup_monthly`：`--scan-debug summary/full`（诊断字段稳定）
+5. `space_governance`：`suggested-only` 与 `allow-recent-active` 组合
+6. `restore`：`skip/overwrite/rename` 三冲突策略
+7. `recycle_maintain`：`disabled` / `no_candidate` / `partial_failed`
+8. `doctor`：只读模式不创建状态目录
+9. `check_update`：npm 正常 / npm 失败回退 GitHub / 全部失败
+10. `upgrade`：未确认拒绝、已是最新不执行、执行失败可返回非 0
+11. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
 
 ## 当前门禁（执行顺序）
 
 1. `npm run check`
 2. `npm run test:coverage:check`
-3. `shellcheck skills/wecom-cleaner-agent/scripts/*.sh`
+3. `shellcheck skills/wecom-cleaner-agent/scripts/*.sh scripts/upgrade.sh scripts/install-skill.sh scripts/release-gate.sh`
 4. `npm run e2e:smoke`
 
 说明：若新增动作/字段，需先补此文档矩阵与断言，再提交实现。

package/docs/releases/v1.3.0.md

@@ -0,0 +1,45 @@
+# v1.3.0 发布说明
+
+发布日期：2026-02-27
+
+## 亮点
+
+- 新增自主升级体系：支持检查更新、交互升级提示与双通道升级（npm / GitHub 脚本）。
+- 升级检查默认按“早/午/晚”三时段执行，减少重复打扰并保持版本新鲜度。
+- 无交互模式新增 `check_update` / `upgrade` 动作，适配 AI Agent 自动化流程。
+
+## 主要变更
+
+- 新增 `src/updater.js`：
+  - SemVer 比较与通道过滤（`stable` / `pre`）
+  - npm 优先、GitHub 回退的版本检查
+  - 升级命令执行与状态结构化
+- `wecom-cleaner-agent` 技能适配升级能力：
+  - 新增 `check_update_report.sh`（更新检查任务卡片）
+  - 新增 `upgrade_report.sh`（升级预演/执行任务卡片）
+- `src/cli.js` 接入升级全流程：
+  - 无交互：`--check-update`、`--upgrade`
+  - 交互：发现新版本后可选择升级方式、稍后提醒或跳过该版本
+- `src/config.js`/`src/doctor.js` 增强：
+  - 持久化 `selfUpdate` 配置
+  - doctor 新增升级配置检查项
+
+## 质量与修复
+
+- 修复 `scripts/install-skill.sh` 的 shellcheck 告警（SC2088）。
+- 修复 E2E start menu 用例与新增菜单项不一致的问题。
+- 修复 Zig `--ping` 返回版本与应用版本不一致的问题。
+- 发布门禁通过：`npm run release:gate`（含覆盖率门禁、shellcheck、e2e smoke、打包预演）。
+
+## 资产
+
+- npm 包：`wecom-cleaner-1.3.0.tgz`
+- GitHub Release 附件：
+  - `wecom-cleaner-core-v1.3.0-darwin-x64`
+  - `wecom-cleaner-core-v1.3.0-darwin-arm64`
+  - `wecom-cleaner-core-v1.3.0-SHA256SUMS.txt`
+
+SHA256：
+
+- `1ea550528055b97e26a76de7d33ca7c445f7dcedf36b21c0cfe1ef7e0f9841bf` `wecom-cleaner-core-v1.3.0-darwin-x64`
+- `2819be9b6108435d94f9a6f5cd0f4e219c335925239366f76fe8a22da023a736` `wecom-cleaner-core-v1.3.0-darwin-arm64`

package/docs/releases/v1.3.1.md

@@ -0,0 +1,31 @@
+# v1.3.1
+
+发布日期：2026-02-27
+
+## 重点更新
+
+- 新增无交互阶段协议 `--run-task`：
+  - `preview`：仅预演
+  - `execute`：仅执行
+  - `preview-execute-verify`：预演 -> 执行 -> 复核
+- 无交互 JSON 新增阶段产物：
+  - `data.taskPhases`：阶段明细（状态、耗时、命中/成功/失败统计）
+  - `data.taskCard`：用户视角任务卡片（范围、结论、分布）
+- 新增扫描诊断参数 `--scan-debug off|summary|full`：用于定位“扫描命中与预期不一致”问题。
+
+## CLI 与 Agent 协同
+
+- `--help` 已补充 `--run-task` 与 `--scan-debug`。
+- skills 文档与命令参考已同步：CLI 回退场景优先使用 `--run-task`，并读取 `taskCard/taskPhases`。
+
+## 测试与质量
+
+- 新增/更新：
+  - `test/config.test.js`：新增 `--run-task` / `--scan-debug` 参数解析覆盖。
+  - `test/cli-non-interactive.test.js`：新增阶段协议与扫描诊断覆盖。
+- 全量测试通过：`npm test`（107/107）。
+
+## 兼容性说明
+
+- 旧的无交互调用方式保持兼容（不传 `--run-task` 时行为不变）。
+- 文本输出保持原有动作卡片，新增阶段流程区块仅在 `--run-task` 时显示。

package/docs/releases/v1.3.2.md

@@ -0,0 +1,38 @@
+# v1.3.2
+
+发布日期：2026-02-27
+
+## 重点更新
+
+- 4 个破坏性 Agent 报告脚本统一改为 `--run-task` 单入口（预演 / 执行 / 复核一致语义）：
+  - `cleanup_monthly_report.sh`
+  - `space_governance_report.sh`
+  - `restore_batch_report.sh`
+  - `recycle_maintain_report.sh`
+- Zig 核心版本号改为构建期自动注入，不再手工写死。
+- `native/manifest.json` 升级到 `v1.3.2`，并同步 `darwin-x64`/`darwin-arm64` 双架构 SHA256。
+
+## 稳定性修复
+
+- 修复 4 个报告脚本在错误分支下的变量展开风险：失败场景稳定返回非 0，避免自动化流程误判成功。
+- 修复 Zig 核心 `--ping` 版本与包版本可能不一致的问题。
+
+## 文档同步
+
+- README、实施计划、技能命令参考、升级脚本示例统一更新到 `v1.3.2`。
+
+## 验证结果
+
+- 发布门禁全通过：`npm run release:gate`
+  - `format:check`
+  - `check`
+  - `test:coverage:check`
+  - `shellcheck(skills)`
+  - `e2e:smoke`
+  - `pack:tgz:dry-run`
+  - `pack:release-assets:dry-run`
+- 覆盖率基线（`test:coverage:check`）：
+  - `statements 87.66%`
+  - `branches 74.38%`
+  - `functions 92.47%`
+  - `lines 87.66%`

package/native/manifest.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "version": "1.2.1",
+  "version": "1.3.2",
   "targets": {
     "darwin-x64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "c703a8bdb6df39df776c6a3ab28b3553916d487cf7c38612989566b4ecea34c9",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.1/wecom-cleaner-core-v1.2.1-darwin-x64"
+      "sha256": "7cb303935b713397012e88431238fa3b44e416ba1ceb0b1a96f354f3c818108c",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.2/wecom-cleaner-core-v1.3.2-darwin-x64"
     },
     "darwin-arm64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "8d0a15efcb70a266e15c752212f15570c006a931681249d6cd41a1c438941f72",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.1/wecom-cleaner-core-v1.2.1-darwin-arm64"
+      "sha256": "93a33ae854e2dc7778865e3d59c048ba8f3d3ff3e3f3d19ec0906c316c18e503",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.2/wecom-cleaner-core-v1.3.2-darwin-arm64"
     }
   }
 }

package/native/zig/build.sh

@@ -2,6 +2,9 @@
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+PACKAGE_VERSION="$(node -p "JSON.parse(require('fs').readFileSync('${ROOT_DIR}/package.json', 'utf8')).version")"
+VERSION_ZIG_PATH="${ROOT_DIR}/native/zig/src/version.zig"
+printf 'pub const APP_VERSION = "%s";\n' "${PACKAGE_VERSION}" > "${VERSION_ZIG_PATH}"
 
 HOST_OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
 HOST_ARCH="$(uname -m)"

package/native/zig/src/main.zig

@@ -1,4 +1,5 @@
 const std = @import("std");
+const version_meta = @import("version.zig");
 
 fn isAbsPath(path: []const u8) bool {
     return std.fs.path.isAbsolute(path);
@@ -57,7 +58,7 @@ fn dirTreeSize(dir: *std.fs.Dir) !u64 {
 }
 
 fn printPing(writer: *std.Io.Writer) !void {
-    try writer.writeAll("{\"ok\":true,\"engine\":\"zig\",\"version\":\"1.1.0\"}\n");
+    try writer.print("{{\"ok\":true,\"engine\":\"zig\",\"version\":\"{s}\"}}\n", .{version_meta.APP_VERSION});
 }
 
 fn runDu(args: []const []const u8, writer: *std.Io.Writer) !void {

package/native/zig/src/version.zig

@@ -0,0 +1 @@
+pub const APP_VERSION = "1.3.2";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/wecom-cleaner",
-  "version": "1.2.1",
+  "version": "1.3.2",
   "description": "企业微信本地聊天缓存清理工具（交互式 CLI/TUI）",
   "author": "MisonL",
   "license": "MIT",

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

@@ -1,6 +1,6 @@
 ---
 name: wecom-cleaner-agent
-description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理或系统自检，并要求高效执行与结构化反馈时触发。
+description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当任务涉及企业微信缓存盘点、年月清理、全量空间治理、批次恢复、回收区治理、系统自检、检查更新或程序升级，并要求高效执行与结构化反馈时触发。
 ---
 
 # wecom-cleaner-agent
@@ -16,9 +16,11 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 1. 全程只用无交互命令（禁止直接运行 `wecom-cleaner` 进入 TUI）。
 2. 优先脚本入口，禁止手写三步命令流（除非脚本失败或缺失）。
 3. 破坏性动作（清理/治理/恢复/回收区治理）默认预演；真实执行必须有明确授权。
-4. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
-5. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
-6. 禁止在终端回显完整 JSON；只输出人类可读摘要。
+4. 回退到 CLI 时，破坏性动作必须使用 `--run-task` 协议（`preview` 或 `preview-execute-verify`），禁止手工串联多次命令。
+5. 升级动作默认只做检查或预演（`--execute false`）；真实升级必须有明确授权。
+6. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
+7. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
+8. 禁止在终端回显完整 JSON；只输出人类可读摘要。
 
 ## 动作到脚本映射（必须）
 
@@ -28,18 +30,25 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 - 恢复已删除批次：`scripts/restore_batch_report.sh`
 - 回收区治理：`scripts/recycle_maintain_report.sh`
 - 系统自检：`scripts/doctor_report.sh`
+- 检查更新：`scripts/check_update_report.sh`
+- 程序升级：`scripts/upgrade_report.sh`
 
 调用顺序：
 
 1. 先判断用户意图对应哪个动作。
 2. 直接调用对应脚本。
 3. 脚本失败时，才回退到 `wecom-cleaner --<action> --output json` 手工流程。
+4. 回退流程里优先读取 `data.taskCard` 与 `data.taskPhases`，再读取 `summary/data.report` 细节。
 
 ## 脚本调用约定
 
-- 默认 `--execute false`（仅预演）。
+- 默认 `--execute false`（仅预演 / 不落地）。
 - 用户明确“现在执行/开始清理/确认执行”时才传 `--execute true`。
 - 破坏性动作脚本内部会做：预演 ->（可选）真实执行 ->（可选）复核。
+- 升级脚本默认“检查 + 预演”；只有明确授权才执行真实升级。
+- CLI 回退时：
+  - 仅预演：`--run-task preview`
+  - 已授权执行：`--run-task preview-execute-verify --yes`
 
 推荐参数：
 

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

@@ -1,5 +1,5 @@
 interface:
   display_name: 'WeCom Cleaner Agent'
   short_description: '面向AI Agent的企业微信缓存清理与恢复无交互执行技能'
-  default_prompt: '请使用 $wecom-cleaner-agent 执行任务：按用户意图自动选择 scripts/ 下对应报告脚本（cleanup/analysis/space/restore/recycle/doctor），优先输出中文用户任务卡片；仅在脚本不可用时回退 wecom-cleaner --output json。'
+  default_prompt: '请使用 $wecom-cleaner-agent 执行任务：按用户意图自动选择 scripts/ 下对应报告脚本（cleanup/analysis/space/restore/recycle/doctor/check-update/upgrade），优先输出中文用户任务卡片；仅在脚本不可用时回退 wecom-cleaner --output json，并在破坏性动作中使用 --run-task（preview 或 preview-execute-verify）读取 data.taskCard/taskPhases。'
   brand_color: '#0EA5E9'