@mison/wecom-cleaner 1.2.1 → 1.3.0

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.0`）：
 
 ```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.0
 ```
 
 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>`
 
 ### 无交互安全规则
 
@@ -230,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
 ```
 
 ### 输出与兼容参数
@@ -240,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）
 
@@ -302,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 根目录
@@ -327,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`）
 
 ## 数据与审计文件
 
@@ -395,8 +438,8 @@ npm run pack:tgz:dry-run
 
 当前基线（主分支）：
 
-- 单元测试：`91/91` 通过。
-- 覆盖率：`statements 88.49%`，`branches 75.01%`，`functions 95.02%`，`lines 88.49%`。
+- 单元测试：`100/100` 通过。
+- 覆盖率：`statements 87.63%`，`branches 74.03%`，`functions 92.47%`，`lines 87.63%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
 ## 测试矩阵
@@ -439,18 +482,19 @@ npm run pack:tgz
 npm run pack:release-assets
 
 # 2) 推送主分支与标签
+VERSION="1.3.0"
 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/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

@@ -24,6 +24,8 @@
 - `restore`
 - `recycle_maintain`
 - `doctor`
+- `check_update`
+- `upgrade`
 
 ### 维度 C：范围组合
 
@@ -94,13 +96,15 @@
 4. `restore`：`skip/overwrite/rename` 三冲突策略
 5. `recycle_maintain`：`disabled` / `no_candidate` / `partial_failed`
 6. `doctor`：只读模式不创建状态目录
-7. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
+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`
+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/native/manifest.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "version": "1.2.1",
+  "version": "1.3.0",
   "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": "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.1/wecom-cleaner-core-v1.2.1-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.1",
+  "version": "1.3.0",
   "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,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. 退出码约定

package/skills/wecom-cleaner-agent/scripts/check_update_report.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+用法：
+  check_update_report.sh [--channel stable|pre] [--root <path>] [--state-root <path>]
+
+说明：
+  - 执行“检查更新（只读）”，不做任何安装动作。
+  - 输出用户可读任务卡片。
+EOF
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "错误：缺少 jq，请先安装（brew install jq）。" >&2
+  exit 2
+fi
+
+if ! command -v wecom-cleaner >/dev/null 2>&1; then
+  echo "错误：未找到 wecom-cleaner 命令，请先安装 @mison/wecom-cleaner。" >&2
+  exit 2
+fi
+
+CHANNEL="stable"
+ROOT=""
+STATE_ROOT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --channel | --upgrade-channel)
+      CHANNEL="${2:-stable}"
+      shift 2
+      ;;
+    --root)
+      ROOT="${2:-}"
+      shift 2
+      ;;
+    --state-root)
+      STATE_ROOT="${2:-}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "错误：未知参数 $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+case "$CHANNEL" in
+  stable | pre) ;;
+  *)
+    echo "错误：--channel 只能是 stable 或 pre" >&2
+    exit 2
+    ;;
+esac
+
+REPORT_JSON="$(mktemp -t wecom-check-update.XXXX.json)"
+REPORT_ERR="$(mktemp -t wecom-check-update.XXXX.err)"
+trap 'rm -f "$REPORT_JSON" "$REPORT_ERR"' EXIT
+
+cmd=(--check-update --output json --upgrade-channel "$CHANNEL")
+if [[ -n "$ROOT" ]]; then
+  cmd+=(--root "$ROOT")
+fi
+if [[ -n "$STATE_ROOT" ]]; then
+  cmd+=(--state-root "$STATE_ROOT")
+fi
+
+if ! wecom-cleaner "${cmd[@]}" >"$REPORT_JSON" 2>"$REPORT_ERR"; then
+  err_head="$(head -n 3 "$REPORT_ERR" 2>/dev/null || true)"
+  echo "执行失败：${err_head:-未知错误}" >&2
+  exit 1
+fi
+
+checked="$(jq -r '.summary.checked // false' "$REPORT_JSON")"
+has_update="$(jq -r '.summary.hasUpdate // false' "$REPORT_JSON")"
+current_version="$(jq -r '.summary.currentVersion // "-"' "$REPORT_JSON")"
+latest_version="$(jq -r '.summary.latestVersion // "-"' "$REPORT_JSON")"
+source_used="$(jq -r '.summary.source // "none"' "$REPORT_JSON")"
+channel_used="$(jq -r '.summary.channel // "stable"' "$REPORT_JSON")"
+skipped_by_user="$(jq -r '.summary.skippedByUser // false' "$REPORT_JSON")"
+duration_ms="$(jq -r '.meta.durationMs // 0' "$REPORT_JSON")"
+warnings_count="$(jq -r '(.warnings // []) | length' "$REPORT_JSON")"
+errors_count="$(jq -r '(.errors // []) | length' "$REPORT_JSON")"
+
+source_label="$source_used"
+case "$source_used" in
+  npm) source_label="npmjs" ;;
+  github) source_label="GitHub Release" ;;
+  none) source_label="不可用" ;;
+esac
+
+channel_label="稳定版"
+if [[ "$channel_used" == "pre" ]]; then
+  channel_label="预发布"
+fi
+
+if [[ "$checked" != "true" ]]; then
+  conclusion="检查失败，请稍后重试。"
+elif [[ "$has_update" == "true" ]]; then
+  if [[ "$skipped_by_user" == "true" ]]; then
+    conclusion="检测到新版本，但该版本已被设置为跳过提醒。"
+  else
+    conclusion="检测到新版本，可按你确认后升级。"
+  fi
+else
+  conclusion="当前已是最新版本。"
+fi
+
+printf '\n=== 更新检查结果（给用户）===\n'
+printf -- '- 执行结论：%s\n' "$conclusion"
+printf -- '- 本次只做版本检查，不会改动你的数据或本机安装。\n'
+
+printf '\n版本信息\n'
+printf -- '- 当前版本：%s\n' "$current_version"
+printf -- '- 最新版本：%s\n' "$latest_version"
+printf -- '- 检查通道：%s\n' "$channel_label"
+printf -- '- 信息来源：%s（先 npm，失败再回退 GitHub）\n' "$source_label"
+printf -- '- 用户跳过提醒：%s\n' "$( [[ "$skipped_by_user" == "true" ]] && printf '是' || printf '否' )"
+
+if [[ "$has_update" == "true" && "$skipped_by_user" != "true" ]]; then
+  printf '\n建议下一步（需你确认后执行）\n'
+  printf -- '- 默认升级方式（npm）：wecom-cleaner --upgrade npm --upgrade-version %s --upgrade-yes\n' "$latest_version"
+  printf -- '- 备选方式（GitHub 脚本）：wecom-cleaner --upgrade github-script --upgrade-version %s --upgrade-yes\n' "$latest_version"
+fi
+
+printf '\n运行状态\n'
+printf -- '- 耗时：%s ms\n' "$duration_ms"
+printf -- '- 告警：%s\n' "$warnings_count"
+printf -- '- 错误：%s\n' "$errors_count"
+
+printf '\n指标释义\n'
+printf -- '- 当前版本：你本机 wecom-cleaner 版本。\n'
+printf -- '- 最新版本：按所选通道可获取的最新可用版本。\n'
+printf -- '- 用户跳过提醒：表示该版本是否被标记为“暂不提醒”。\n'