@mison/wecom-cleaner 1.2.0 → 1.2.1

package/README.md

@@ -27,6 +27,7 @@
 - [常用参数](#常用参数)
 - [数据与审计文件](#数据与审计文件)
 - [开发与质量门禁](#开发与质量门禁)
+- [测试矩阵](#测试矩阵)
 - [发布与打包](#发布与打包)
 - [FAQ](#faq)
 
@@ -158,10 +159,10 @@ GitHub 备选方式（无 npm 包依赖）：
 curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash
 ```
 
-若需安装指定版本标签（例如 `v1.1.0`）：
+若需安装指定版本标签（例如 `v1.2.1`）：
 
 ```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.2.1
 ```
 
 Agent 侧统一任务入口脚本（位于 `skills/wecom-cleaner-agent/scripts/`）：
@@ -384,19 +385,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%`。
+- 单元测试：`91/91` 通过。
+- 覆盖率：`statements 88.49%`，`branches 75.01%`，`functions 95.02%`，`lines 88.49%`。
 - 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。
 
+## 测试矩阵
+
+- 场景矩阵与断言模板见：[`docs/TEST_MATRIX.md`](./docs/TEST_MATRIX.md)
+- 新增动作或输出字段时，需同步更新矩阵并补对应测试。
+
 ## 发布与打包
 
 `prepack` 会自动执行：
@@ -423,26 +430,27 @@ 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) 推送主分支与标签
 git push origin main
-git tag v1.2.0
-git push origin v1.2.0
+git tag v1.2.1
+git push origin v1.2.1
 
 # 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 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
 
 # 4) 发布 npm
 npm publish --access public

package/docs/TEST_MATRIX.md

@@ -0,0 +1,106 @@
+# 测试矩阵（稳定性与极端场景）
+
+本文用于约束 `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`
+
+### 维度 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. Agent 报告脚本：成功、无目标、失败三态退出码与卡片完整性
+
+## 当前门禁（执行顺序）
+
+1. `npm run check`
+2. `npm run test:coverage:check`
+3. `shellcheck skills/wecom-cleaner-agent/scripts/*.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/native/manifest.json

@@ -1,16 +1,16 @@
 {
   "schemaVersion": 1,
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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"
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.1/wecom-cleaner-core-v1.2.1-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"
+      "url": "https://github.com/MisonL/wecom-cleaner/releases/download/v1.2.1/wecom-cleaner-core-v1.2.1-darwin-arm64"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/wecom-cleaner",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "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/scripts/cleanup_monthly_report.sh

@@ -190,7 +190,7 @@ run_cmd_to_file() {
   if ! wecom-cleaner "${cmd_parts[@]}" >"$output_file" 2>"$err_file"; then
     local err_head
     err_head="$(head -n 3 "$err_file" 2>/dev/null || true)"
-    echo "执行失败（dry-run=$dry_run）：${err_head:-未知错误}" >&2
+    echo "执行失败（dry-run=${dry_run}）：${err_head:-未知错误}" >&2
     return 1
   fi
 }
@@ -275,6 +275,7 @@ if [[ -z "$selected_categories_human" ]]; then
 fi
 
 printf '\n=== 清理结果（给用户）===\n'
+printf -- '- 执行结论：%s（%s）\n' "$conclusion" "$reason"
 if [[ "$executed" == "true" ]]; then
   printf -- '- 已完成：已清理 %s 项聊天缓存，释放 %s。\n' "$execute_success" "$(human_bytes "$execute_reclaimed")"
 elif [[ "$preview_matched" -eq 0 ]]; then
@@ -287,6 +288,7 @@ printf -- '- 你的目标：清理 %s 及之前的企业微信聊天缓存。\n'
 printf '\n你关心的范围\n'
 printf -- '- 账号：%s（识别到 %s 个账号）\n' "$account_scope_label" "$scope_accounts"
 printf -- '- 数据类型：%s\n' "$selected_categories_human"
+printf -- '- 筛选月份桶：%s，筛选类别数：%s\n' "$scope_months" "$scope_categories"
 if [[ -n "$matched_month_start" && -n "$matched_month_end" ]]; then
   printf -- '- 实际命中月份：%s ~ %s\n' "$matched_month_start" "$matched_month_end"
 else
@@ -300,6 +302,7 @@ printf -- '- 命中字节：%s（命中目录当前大小）\n' "$(human_bytes "
 printf -- '- 预计释放：%s（预演估算）\n' "$(human_bytes "$preview_reclaimed")"
 if [[ "$executed" == "true" ]]; then
   printf -- '- 实际释放：%s（真实执行结果）\n' "$(human_bytes "$execute_reclaimed")"
+  printf -- '- 执行明细：成功 %s / 跳过 %s / 失败 %s\n' "$execute_success" "$execute_skipped" "$execute_failed"
   printf -- '- 清理批次：%s（可用于恢复）\n' "$execute_batch"
   printf -- '- 复核结果：剩余可清理 %s 项\n' "$verify_matched"
 else
@@ -431,6 +434,13 @@ if [[ "$executed" == "true" ]]; then
   fi
 fi
 
+printf '\n运行状态\n'
+printf -- '- 扫描引擎：%s\n' "$engine"
+printf -- '- 总耗时：%s ms\n' "$duration_total"
+printf -- '- 告警：%s\n' "$warnings_total"
+printf -- '- 错误：%s\n' "$errors_total"
+printf -- '- 预演失败项：%s\n' "$preview_failed"
+
 if [[ "$warnings_total" -gt 0 || "$errors_total" -gt 0 ]]; then
   printf '\n异常与提示\n'
   printf -- '- 告警：%s\n' "$warnings_total"

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

@@ -143,7 +143,7 @@ run_cmd_to_file() {
   fi
   if ! wecom-cleaner "${cmd_parts[@]}" >"$output_file" 2>"$err_file"; then
     err_head="$(head -n 3 "$err_file" 2>/dev/null || true)"
-    echo "执行失败（dry-run=$dry_run）：${err_head:-未知错误}" >&2
+    echo "执行失败（dry-run=${dry_run}）：${err_head:-未知错误}" >&2
     return 1
   fi
 }

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

@@ -145,7 +145,7 @@ run_cmd_to_file() {
   fi
   if ! wecom-cleaner "${cmd_parts[@]}" >"$output_file" 2>"$err_file"; then
     err_head="$(head -n 3 "$err_file" 2>/dev/null || true)"
-    echo "执行失败（dry-run=$dry_run）：${err_head:-未知错误}" >&2
+    echo "执行失败（dry-run=${dry_run}）：${err_head:-未知错误}" >&2
     return 1
   fi
 }

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

@@ -173,7 +173,7 @@ run_cmd_to_file() {
   fi
   if ! wecom-cleaner "${cmd_parts[@]}" >"$output_file" 2>"$err_file"; then
     err_head="$(head -n 3 "$err_file" 2>/dev/null || true)"
-    echo "执行失败（dry-run=$dry_run）：${err_head:-未知错误}" >&2
+    echo "执行失败（dry-run=${dry_run}）：${err_head:-未知错误}" >&2
     return 1
   fi
 }
@@ -241,6 +241,7 @@ warnings_total=$((warnings_preview + warnings_exec + warnings_verify))
 errors_total=$((errors_preview + errors_exec + errors_verify))
 
 printf '\n=== 全量空间治理结果（给用户）===\n'
+printf -- '- 执行结论：%s（%s）\n' "$conclusion" "$reason"
 if [[ "$executed" == "true" ]]; then
   printf -- '- 已完成：已治理 %s 项空间目标，释放 %s。\n' "$execute_success" "$(human_bytes "$execute_reclaimed")"
 elif [[ "$matched_targets" -eq 0 ]]; then
@@ -263,6 +264,7 @@ printf -- '- 命中体积：%s\n' "$(human_bytes "$matched_bytes")"
 printf -- '- 预计释放：%s\n' "$(human_bytes "$preview_reclaimed")"
 if [[ "$executed" == "true" ]]; then
   printf -- '- 实际释放：%s\n' "$(human_bytes "$execute_reclaimed")"
+  printf -- '- 执行明细：成功 %s / 跳过 %s / 失败 %s\n' "$execute_success" "$execute_skipped" "$execute_failed"
   printf -- '- 清理批次：%s（可用于恢复）\n' "$execute_batch"
   printf -- '- 复核结果：剩余可治理 %s 项\n' "$verify_matched"
 else

package/src/recycle-maintenance.js

@@ -51,8 +51,23 @@ function isPathWithinRoot(rootPath, targetPath) {
   return !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
-function resolveBatchRootFromEntries(recycleRoot, batch) {
+async function safeRealpath(targetPath) {
+  try {
+    return await fs.realpath(targetPath);
+  } catch {
+    return null;
+  }
+}
+
+async function resolveBatchRootFromEntries(recycleRoot, batch) {
   const recycleRootAbs = path.resolve(String(recycleRoot || ''));
+  const recycleRootReal = await safeRealpath(recycleRootAbs);
+  if (!recycleRootReal) {
+    return {
+      ok: false,
+      invalidReason: 'missing_recycle_root',
+    };
+  }
   const entries = Array.isArray(batch?.entries) ? batch.entries : [];
   if (entries.length === 0) {
     return {
@@ -78,6 +93,19 @@ function resolveBatchRootFromEntries(recycleRoot, batch) {
         invalidReason: 'recycle_path_outside_recycle_root',
       };
     }
+    const recyclePathReal = await safeRealpath(recyclePathAbs);
+    if (!recyclePathReal) {
+      return {
+        ok: false,
+        invalidReason: 'recycle_path_unresolvable',
+      };
+    }
+    if (!isPathWithinRoot(recycleRootReal, recyclePathReal)) {
+      return {
+        ok: false,
+        invalidReason: 'recycle_path_symlink_escape',
+      };
+    }
 
     const batchRootAbs = path.dirname(recyclePathAbs);
     if (!isPathWithinRoot(recycleRootAbs, batchRootAbs)) {
@@ -92,7 +120,20 @@ function resolveBatchRootFromEntries(recycleRoot, batch) {
         invalidReason: 'batch_root_is_recycle_root',
       };
     }
-    rootSet.add(batchRootAbs);
+    const batchRootReal = await safeRealpath(batchRootAbs);
+    if (!batchRootReal) {
+      return {
+        ok: false,
+        invalidReason: 'batch_root_unresolvable',
+      };
+    }
+    if (!isPathWithinRoot(recycleRootReal, batchRootReal)) {
+      return {
+        ok: false,
+        invalidReason: 'batch_root_symlink_escape',
+      };
+    }
+    rootSet.add(batchRootReal);
   }
 
   if (rootSet.size !== 1) {
@@ -282,7 +323,7 @@ export async function maintainRecycleBin({ indexPath, recycleRoot, policy, dryRu
       onProgress(i + 1, selected.candidates.length);
     }
 
-    const resolvedBatchRoot = resolveBatchRootFromEntries(recycleRoot, batch);
+    const resolvedBatchRoot = await resolveBatchRootFromEntries(recycleRoot, batch);
     if (!resolvedBatchRoot.ok) {
       summary.failBatches += 1;
       summary.operations.push({