@mison/wecom-cleaner 1.2.0 → 1.3.0

package/README.md

@@ -27,6 +27,7 @@
 - [常用参数](#常用参数)
 - [数据与审计文件](#数据与审计文件)
 - [开发与质量门禁](#开发与质量门禁)
+- [测试矩阵](#测试矩阵)
 - [发布与打包](#发布与打包)
 - [FAQ](#faq)
 
@@ -91,6 +92,15 @@
 - `doctor` 模式为只读体检：不会自动创建状态目录/回收区，也不会触发 Zig 自动修复下载。
 - 多实例并发默认加锁；检测到陈旧锁会优先自动恢复，异常场景可用 `--force` 兜底清理。
 
+7. 自主升级体系
+
+- 启动后按“早/午/晚”三时段检查更新（默认开启）。
+- 版本源优先 npmjs，失败自动回退 GitHub Release。
+- 交互模式发现新版本时可直接选择升级方式：
+  - npm 升级（默认）
+  - GitHub 脚本升级
+- 无交互模式仅提示不阻断任务执行。
+
 ## 能力边界
 
 企业微信会话数据库为私有/加密格式，当前无法稳定建立“会话名 -> 本地缓存目录”的强映射。
@@ -158,10 +168,10 @@ GitHub 备选方式（无 npm 包依赖）：
 curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash
 ```
 
-若需安装指定版本标签（例如 `v1.1.0`）：
+若需安装指定版本标签（例如 `v1.3.0`）：
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.1.0
+curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.3.0
 ```
 
 Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`）：
@@ -172,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`：程序升级任务卡片（默认预演）
 
 ## 常用参数
 
@@ -190,6 +202,8 @@ Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`
 - `--restore-batch <batchId>`
 - `--recycle-maintain`
 - `--doctor`
+- `--check-update`
+- `--upgrade <npm|github-script>`
 
 ### 无交互安全规则
 
@@ -229,6 +243,15 @@ 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.1 --upgrade-yes
 ```
 
 ### 输出与兼容参数
@@ -239,6 +262,9 @@ wecom-cleaner --doctor
 - `--save-config`：将本次全局配置参数写回 `config.json`。
 - `--help` / `-h`：输出命令帮助并退出。
 - `--version` / `-v`：输出版本号并退出。
+- `--upgrade-channel stable|pre`：升级检查通道（稳定版/预发布）。
+- `--upgrade-version <x.y.z>`：指定升级目标版本。
+- `--upgrade-yes`：确认执行升级动作（无此参数将拒绝执行升级）。
 
 ### 各动作关键统计字段（JSON）
 
@@ -301,6 +327,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 根目录
@@ -326,6 +369,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`）
 
 ## 数据与审计文件
 
@@ -384,19 +428,25 @@ npm run format:check
 发布前推荐全量门禁：
 
 ```bash
+npm run format:check
 npm run check
 npm run test:coverage:check
-npm run format:check
+npm run release:gate
 npm run e2e:smoke -- --keep
 npm run pack:tgz:dry-run
 ```
 
 当前基线（主分支）：
 
-- 单元测试：`78/78` 通过。
-- 覆盖率：`statements 88.28%`，`branches 74.44%`，`functions 94.89%`，`lines 88.28%`。
+- 单元测试：`100/100` 通过。
+- 覆盖率：`statements 87.63%`，`branches 74.03%`，`functions 92.47%`，`lines 87.63%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
+## 测试矩阵
+
+- 场景矩阵与断言模板见：[`docs/TEST_MATRIX.md`](./docs/TEST_MATRIX.md)
+- 新增动作或输出字段时，需同步更新矩阵并补对应测试。
+
 ## 发布与打包
 
 `prepack` 会自动执行：
@@ -423,26 +473,28 @@ npm run pack:tgz
 
 ```bash
 # 1) 发布前检查
+npm run format:check
 npm run check
 npm run test:coverage:check
-npm run format:check
+npm run release:gate
 npm run e2e:smoke
 npm run pack:tgz
 npm run pack:release-assets
 
 # 2) 推送主分支与标签
+VERSION="1.3.0"
 git push origin main
-git tag v1.2.0
-git push origin v1.2.0
+git tag "v${VERSION}"
+git push origin "v${VERSION}"
 
 # 3) 发布 GitHub Release（附 npm 包 + 双架构核心附件）
-gh release create v1.2.0 \
-  --title "v1.2.0" \
-  --notes-file docs/releases/v1.2.0.md \
-  wecom-cleaner-1.2.0.tgz \
-  dist/release/wecom-cleaner-core-v1.2.0-darwin-x64 \
-  dist/release/wecom-cleaner-core-v1.2.0-darwin-arm64 \
-  dist/release/wecom-cleaner-core-v1.2.0-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/NON_INTERACTIVE_SPEC.md

@@ -20,6 +20,8 @@
 - `--restore-batch <batchId>`
 - `--recycle-maintain`
 - `--doctor`
+- `--check-update`
+- `--upgrade <npm|github-script>`
 
 若缺少动作或动作冲突，退出码为 `2`。
 
@@ -50,6 +52,7 @@ JSON 顶层字段：
 - `errors`：错误数组（`code`、`message`、可选路径字段）
 - `data`：动作明细数据
 - `meta`：元信息（版本、耗时、引擎、时间戳等）
+- `data.userFacingSummary`：统一的用户侧结果摘要（范围 + 结果 + 关键分布）
 
 `cleanup_monthly` 常见 `summary` 字段：
 
@@ -164,6 +167,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 +212,9 @@ JSON 顶层字段：
 - `--interactive`：强制交互模式（与无交互动作参数互斥使用时，优先按交互模式执行）
 - `--force`：锁异常场景下强制清理并继续（兜底参数）
 - `--save-config`：把本次全局参数落盘到 `config.json`
+- `--upgrade-channel <stable|pre>`：更新通道（稳定版/预发布）
+- `--upgrade-version <x.y.z>`：升级到指定版本
+- `--upgrade-yes`：确认执行升级（无此参数将拒绝执行升级）
 
 ## 7. 动作参数
 
@@ -234,6 +266,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

@@ -0,0 +1,110 @@
+# 测试矩阵（稳定性与极端场景）
+
+本文用于约束 `wecom-cleaner` 在复杂组合场景与极端输入下的行为一致性，避免“看似成功但语义错误”。
+
+## 目标
+
+- 覆盖高风险动作：年月清理、全量空间治理、恢复、回收区治理。
+- 锁定无交互契约：JSON 字段兼容、退出码语义稳定、text 卡片结论可读。
+- 验证边界安全：路径越界、符号链接逃逸、索引异常、权限失败、并发竞争。
+
+## 维度定义
+
+### 维度 A：入口
+
+- 交互模式（TUI）
+- 无交互 CLI（`--output json|text`）
+- Agent 脚本（`skills/wecom-cleaner-agent/scripts/*.sh`）
+
+### 维度 B：动作
+
+- `cleanup_monthly`
+- `analysis_only`
+- `space_governance`
+- `restore`
+- `recycle_maintain`
+- `doctor`
+- `check_update`
+- `upgrade`
+
+### 维度 C：范围组合
+
+- 账号：`current` / `all` / 指定 ID 集合
+- 月份：显式 `--months` / `--cutoff-month` / 自动窗口
+- 类别：默认 / 指定列表 / `all`
+- 文件存储目录来源：`preset` / `configured` / `auto` / `all`
+
+### 维度 D：执行模式
+
+- dry-run（预演）
+- 真实执行（`--dry-run false --yes`）
+- 真实执行后复核（同条件二次运行）
+
+### 维度 E：异常与边界
+
+- 路径越界（`../`、绝对路径、非法根目录）
+- 符号链接逃逸（raw 路径在根内，realpath 在根外）
+- 索引异常（损坏行、批次根不一致、异常 `batchId`）
+- 系统失败（`EACCES`、`ENOENT`、`ENOSPC`）
+- 并发锁冲突与陈旧锁恢复
+
+### 维度 F：规模
+
+- 小样本（< 50 目录）
+- 中样本（50~500 目录）
+- 大样本（> 500 目录，强调耗时与稳定性）
+
+## 关键断言模板（每个场景最少验证）
+
+### 1) 退出码
+
+- `0`：动作完成（可含业务失败明细）
+- `2`：参数/用法错误
+- `3`：真实执行缺少 `--yes`
+
+### 2) JSON 契约（无交互）
+
+必须存在且类型稳定：
+
+- `ok: boolean`
+- `action: string`
+- `dryRun: boolean | null`
+- `summary: object`
+- `warnings: array`
+- `errors: array`
+- `meta.durationMs: number`
+- `meta.engine: string`
+
+### 3) 业务语义
+
+- dry-run 不修改源目录
+- 真实执行删除采用“移动到回收区”，可按批次恢复
+- 无目标场景不得生成真实批次（或写入误导性“成功删除”）
+- 部分失败时必须可见失败统计与错误明细
+
+### 4) 审计一致性
+
+- `index.jsonl` 记录动作、状态、路径、错误类型
+- 越界/异常路径必须落审计（`error_type=PATH_VALIDATION_FAILED`）
+- 回收区治理异常批次不得触发越界删除
+
+## 最小必跑清单（回归基线）
+
+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. `check_update`：npm 正常 / npm 失败回退 GitHub / 全部失败
+8. `upgrade`：未确认拒绝、已是最新不执行、执行失败可返回非 0
+9. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
+
+## 当前门禁（执行顺序）
+
+1. `npm run check`
+2. `npm run test:coverage:check`
+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.2.1.md

@@ -0,0 +1,33 @@
+# v1.2.1 发布说明
+
+发布日期：2026-02-26
+
+## 亮点
+
+- 发布流程新增一键门禁：`npm run release:gate`，统一覆盖格式检查、语法检查、覆盖率门禁、Shell 脚本静态检查、E2E smoke 与打包预演。
+- 回收区治理安全性进一步增强：新增 `realpath` 级边界校验，拦截符号链接越界路径。
+- Agent 无交互脚本失败语义加固：失败时稳定返回非 0 退出码并输出可读错误原因，避免自动化误判成功。
+
+## 重要修复
+
+- 修复回收区治理的符号链接逃逸风险（`recycle_path_symlink_escape` / `batch_root_symlink_escape` 等）。
+- 修复 `recycle_maintain` 业务失败场景下无交互契约测试断言，确保“退出码 + JSON 输出”语义一致。
+- 修复报告脚本在 `set -u` 下错误分支变量展开异常，避免失败被错误吞掉。
+
+## 质量状态
+
+- 发布门禁：全部通过。
+- 单元测试：`91/91` 通过。
+- 覆盖率（门禁）：
+  - statements：`88.49%`
+  - branches：`75.01%`
+  - functions：`95.02%`
+  - lines：`88.49%`
+
+## 资产
+
+- npm 包：`wecom-cleaner-1.2.1.tgz`
+- GitHub Release 附件：
+  - `wecom-cleaner-core-v1.2.1-darwin-x64`
+  - `wecom-cleaner-core-v1.2.1-darwin-arm64`
+  - `wecom-cleaner-core-v1.2.1-SHA256SUMS.txt`

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/native/manifest.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "version": "1.2.0",
+  "version": "1.3.0",
   "targets": {
     "darwin-x64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "c703a8bdb6df39df776c6a3ab28b3553916d487cf7c38612989566b4ecea34c9",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.0/wecom-cleaner-core-v1.2.0-darwin-x64"
+      "sha256": "1ea550528055b97e26a76de7d33ca7c445f7dcedf36b21c0cfe1ef7e0f9841bf",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.0/wecom-cleaner-core-v1.3.0-darwin-x64"
     },
     "darwin-arm64": {
       "binaryName": "wecom-cleaner-core",
-      "sha256": "8d0a15efcb70a266e15c752212f15570c006a931681249d6cd41a1c438941f72",
-      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.0/wecom-cleaner-core-v1.2.0-darwin-arm64"
+      "sha256": "2819be9b6108435d94f9a6f5cd0f4e219c335925239366f76fe8a22da023a736",
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.3.0/wecom-cleaner-core-v1.3.0-darwin-arm64"
     }
   }
 }

package/native/zig/src/main.zig

@@ -57,7 +57,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.writeAll("{\"ok\":true,\"engine\":\"zig\",\"version\":\"1.3.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.2.0",
+  "version": "1.3.0",
   "description": "企业微信本地聊天缓存清理工具（交互式 CLI/TUI）",
   "author": "MisonL",
   "license": "MIT",
@@ -43,6 +43,7 @@
     "format:check": "prettier --check .",
     "check": "node --check src/*.js",
     "e2e:smoke": "bash scripts/e2e-smoke.sh",
+    "release:gate": "bash scripts/release-gate.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",

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,10 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 1. 全程只用无交互命令（禁止直接运行 `wecom-cleaner` 进入 TUI）。
 2. 优先脚本入口，禁止手写三步命令流（除非脚本失败或缺失）。
 3. 破坏性动作（清理/治理/恢复/回收区治理）默认预演；真实执行必须有明确授权。
-4. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
-5. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
-6. 禁止在终端回显完整 JSON；只输出人类可读摘要。
+4. 升级动作默认只做检查或预演（`--execute false`）；真实升级必须有明确授权。
+5. 若预演命中为 `0`，必须结束并说明“无需执行”，不得继续真实执行。
+6. 最终汇报必须是中文用户视角，先结论再细节，并解释关键指标含义。
+7. 禁止在终端回显完整 JSON；只输出人类可读摘要。
 
 ## 动作到脚本映射（必须）
 
@@ -28,6 +29,8 @@ 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`
 
 调用顺序：
 
@@ -37,9 +40,10 @@ description: 用于执行和编排 wecom-cleaner 的无交互 Agent 技能。当
 
 ## 脚本调用约定
 
-- 默认 `--execute false`（仅预演）。
+- 默认 `--execute false`（仅预演 / 不落地）。
 - 用户明确“现在执行/开始清理/确认执行”时才传 `--execute true`。
 - 破坏性动作脚本内部会做：预演 ->（可选）真实执行 ->（可选）复核。
+- 升级脚本默认“检查 + 预演”；只有明确授权才执行真实升级。
 
 推荐参数：
 

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。'
   brand_color: '#0EA5E9'

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

@@ -44,6 +44,23 @@ bash scripts/recycle_maintain_report.sh --execute true
 bash scripts/doctor_report.sh
 ```
 
+### 1.7 检查更新（只读）
+
+```bash
+bash scripts/check_update_report.sh --channel stable
+```
+
+### 1.8 程序升级
+
+```bash
+# 默认仅预演（不执行真实升级）
+bash scripts/upgrade_report.sh --method npm --execute false
+
+# 明确授权后执行真实升级
+bash scripts/upgrade_report.sh --method npm --execute true
+bash scripts/upgrade_report.sh --method github-script --version 1.3.0 --execute true
+```
+
 ## 2. 常用全局参数
 
 以上脚本都支持透传关键参数（按动作有所不同）：
@@ -80,6 +97,13 @@ wecom-cleaner --recycle-maintain --output json
 
 # 系统自检
 wecom-cleaner --doctor --output json
+
+# 检查更新
+wecom-cleaner --check-update --output json
+
+# 程序升级（必须带 --upgrade-yes）
+wecom-cleaner --upgrade npm --upgrade-yes --output json
+wecom-cleaner --upgrade github-script --upgrade-version 1.3.0 --upgrade-yes --output json
 ```
 
 ## 4. 退出码约定