wecom-cleaner

企业微信本地缓存清理工具（交互式 CLI/TUI）。

• 软件名：wecom-cleaner
• npm 包：@mison/wecom-cleaner
• 命令名：wecom-cleaner
• 仓库：https://github.com/MisonL/wecom-cleaner

定位：手动清理默认立即释放空间；自动服务按规则治理到期缓存，并用服务专用回收站承接自动任务的可恢复需求。

v2 cutover:

• 主 CLI 入口已切换为 inspect / plan / apply / verify / recover / service / update / skills
• 旧顶层旗标（如 --cleanup-monthly、--doctor）已从公共接口移除
• skills 报告脚本当前作为兼容壳层保留，主控制面以 v2 CLI 和 agent-json 为准

目录

• 项目定位
• 功能总览
• 能力边界
• 安装与运行
• Agent Skills 安装
• 常用参数
• 数据与审计文件
• 开发与质量门禁
• 测试矩阵
• 发布与打包
• FAQ

项目定位

wecom-cleaner 解决的是“本地缓存空间治理”问题，不改变服务端数据。

设计原则：

• 手动优先释放：交互模式默认直接删除，执行前强确认，不留手动备份。
• 自动服务隔离：服务模式默认先进服务专用回收站，再按服务回收站策略二次清理。
• 可审计：关键分支会写入状态码与删除方式，便于追踪与复盘。
• 渐进增强：有 Zig 核心则加速，无则自动回退 Node。

功能总览

| 模块 | 是否可执行删除 | 说明 | | ------------------ | -------------- | --------------------------------------------------------- | | 年月清理（默认） | 是 | 按账号 + 年月 + 类型筛选缓存，交互模式默认直接删除。 | | 会话分析 | 否 | 只读分析目录/体积分布，不做删除。 | | 全量空间治理 | 是 | 分级治理高占用缓存目录，交互模式默认直接删除。 | | 回收站治理 | 是 | 按策略清理手动回收站或服务回收站历史批次，支持 dry-run。 | | 恢复回收站批次 | 是 | 基于索引恢复手动/服务回收站批次，支持覆盖/重命名/跳过。 | | 自动服务 | 是 | 通过 macOS launchd 按登录 + 定时 + 低空间阈值自动治理。 | | 系统自检（doctor） | 否 | 检查目录权限、账号发现、核心可用性、回收站与服务状态。 | | 交互配置 | 否 | 配置根目录、主题、文件存储目录、外部自动探测等。 |

关键能力

1. 多账号支持

• 自动识别 Profiles 下账号目录。
• 账号以 用户名 | 企业名 | 短ID 显示，可多选。
• 支持账号别名，修正常见不可读字段。

2. 文件存储目录识别

• 支持默认路径、手动配置路径、自动探测路径。
• 自动探测采用“结构 + 缓存特征”联合识别（如 */WXWork Files/Caches、*/WXWork Files/File、*/WXWork Files/Image + 企业微信缓存类别/月目录信号），不依赖目录名且降低误判。
• 自动探测结果默认预选，执行前可手动取消；同时保留确认提示，避免误纳入无关目录。

3. 删除与恢复链路

• 交互模式下，年月清理/全量治理默认直接删除，执行前会明确提示“不可恢复”并要求确认词。
• 非交互模式默认保持保守：只有显式传 --delete-mode direct --direct-delete-ack DIRECT_DELETE --yes 才会直删。
• 选择 --delete-mode recycle 时，仍会写入回收站与 index.jsonl，并支持按批次恢复。
• 恢复时做路径边界校验（含 realpath 防符号链接越界）。

4. 自动服务与服务回收站

• 自动服务通过 macOS launchd 运行，不使用常驻 daemon。
• 默认触发时机：登录后一次 + 每日 09:30 / 13:30 / 18:30。
• 服务模式默认先移到 service-recycle-bin/，再按“保留天数 + 最少保留批次 + 容量阈值”治理。
• 当系统磁盘可用空间低于阈值时，会按最旧批次优先清理服务回收站。

5. Zig 核心与自动修复

• 有可用 Zig 核心时自动启用加速。
• 不可用时自动回退 Node，功能不受影响。
• 可按 manifest 下载并校验 SHA256 后修复核心。

6. 可观测性与并发安全

• doctor 模式可输出人类可读报告，或通过 --output agent-json 输出面向 Agent 的结构化结果。
• doctor 模式为只读体检：不会自动创建状态目录/回收区，也不会触发 Zig 自动修复下载。
• 多实例并发默认加锁；检测到陈旧锁会优先自动恢复，异常场景可用 --force 兜底清理。

7. 自主升级体系

• 启动后按“早/午/晚”三时段检查更新（默认开启）。
• 版本源优先 npmjs，失败自动回退 GitHub Release。
• 检查更新会同时校验 Agent skills 是否与主程序版本匹配。
• 交互模式发现新版本时可直接选择升级方式：
  • npm 升级（默认）
  • GitHub 脚本升级
• 程序升级完成后默认联动同步 skills，避免“程序已升级但 skills 仍旧版”。
• 无交互模式可用 --sync-skills 单独修复 skills 版本绑定。

能力边界

企业微信会话数据库为私有/加密格式，当前无法稳定建立“会话名 -> 本地缓存目录”的强映射。

因此：

• 支持按“年月目录”执行清理。
• 支持按“会话维度”做只读分析。
• 不提供“按会话自动删除”。

安装与运行

方式一：直接运行

npx @mison/wecom-cleaner

方式二：本地开发

npm install
npm run build:native
npm run dev

全菜单 smoke 回归

npm run e2e:smoke

说明：

• 脚本会在 /tmp/wecom-e2e-* 构造隔离夹具，不触碰真实企业微信目录。
• 覆盖开始菜单与关键分支：年月清理、会话分析、全量治理、回收区治理、恢复、系统自检、设置。
• 可用 npm run e2e:smoke -- --keep 保留日志与测试目录。

Agent Skills 安装

内置技能：wecom-cleaner-agent（用于 Codex/Agent 无交互调用）。

推荐方式（npmjs，最稳定）：

npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install

常用参数：

• --target <dir>：自定义安装目录（默认 $CODEX_HOME/skills 或 ~/.codex/skills）
• --force：覆盖已存在技能目录
• --dry-run：仅预演，不落盘
• status 子命令：检查 skills 与主程序版本是否匹配
• sync 子命令：等价 install --force，用于升级 skills

示例：

npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --force
npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill install --target ~/.codex/skills
npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill status --json
npx --yes --package=@mison/wecom-cleaner wecom-cleaner-skill sync

GitHub 备选方式（无 npm 包依赖）：

curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash

若需安装指定版本标签（例如 v1.3.4）：

curl -fsSL https://raw.githubusercontent.com/MisonL/wecom-cleaner/main/scripts/install-skill.sh | bash -s -- --ref v1.3.4

Agent 侧统一任务入口脚本（位于 skills/wecom-cleaner-agent/scripts/）：

• cleanup_monthly_report.sh：年月清理任务卡片（预演/执行/复核）
• analysis_report.sh：会话分析（只读）任务卡片
• space_governance_report.sh：全量空间治理任务卡片
• restore_batch_report.sh：批次恢复任务卡片
• recycle_maintain_report.sh：回收区治理任务卡片
• doctor_report.sh：系统自检任务卡片
• check_update_report.sh：检查更新任务卡片
• upgrade_report.sh：程序升级任务卡片（默认预演）

常用参数

运行方式：

• 不带参数：进入交互菜单（TUI）。
• 带参数：进入无交互执行（默认输出 JSON，适合 AI Agent）。
• 带参数但需交互：可追加 --interactive 强制进入交互流程（支持配合 --mode 直达功能）。
• 完整契约文档：docs/NON_INTERACTIVE_SPEC.md。

公共 v2 子命令

• inspect footprint
• inspect doctor
• plan monthly-cleanup
• plan space-governance
• apply <plan-id>
• verify <run-id>
• recover restore <batchId>
• recover recycle
• service install|status|run|uninstall
• update check
• update apply <npm|github-script>
• skills status|sync

无交互安全规则

• 破坏性动作（清理/治理/恢复/回收站治理）默认 dry-run。
• 显式真实执行需带 --yes。
• 若传 --dry-run false 但未传 --yes，将直接退出（退出码 3）。
• 非交互直删需额外显式传：--delete-mode direct --direct-delete-ack DIRECT_DELETE。

常用无交互示例

# 年月清理（默认 dry-run）
wecom-cleaner plan monthly-cleanup \
  --accounts current \
  --cutoff-month 2024-02 \
  --categories files,images \
  --output agent-json

# 年月清理（真实执行：先 plan，再 apply）
wecom-cleaner plan monthly-cleanup \
  --accounts all \
  --months 2023-01,2023-02 \
  --categories files \
  --output agent-json

wecom-cleaner apply <plan-id> \
  --ack APPLY \
  --state-root <path> \
  --output agent-json

# 年月清理（复核）
wecom-cleaner verify <run-id> \
  --state-root <path> \
  --output agent-json

# 全量空间治理（预演）
wecom-cleaner plan space-governance \
  --suggested-only true \
  --tiers safe,caution \
  --output agent-json

# 回收区治理（按策略预演）
wecom-cleaner recover recycle --output agent-json

# 回收区治理（真实执行）
wecom-cleaner recover recycle --ack RECYCLE --output agent-json

# 批次恢复（冲突策略：重命名，默认预演）
wecom-cleaner recover restore 20260226-105009-ffa098 --conflict rename --output agent-json

# 批次恢复（真实执行）
wecom-cleaner recover restore 20260226-105009-ffa098 --conflict rename --ack RESTORE --output agent-json

# 系统自检（默认 JSON 输出）
wecom-cleaner inspect doctor --output agent-json

# 检查更新（不执行升级）
wecom-cleaner update check --output text

# 执行升级（npm 默认方式）
wecom-cleaner update apply npm --ack UPGRADE --output agent-json

# 执行升级（GitHub 托管脚本方式）
wecom-cleaner update apply github-script --upgrade-version 1.3.4 --ack UPGRADE --output agent-json

# 单独同步 skills（修复版本不匹配）
wecom-cleaner skills sync --skill-sync-method npm --ack SKILLS_SYNC --output agent-json

# 安装自动服务
wecom-cleaner service install \
  --accounts all \
  --categories files,images,videos \
  --service-retain-days 180 \
  --service-trigger-times 09:30,13:30,18:30 \
  --output agent-json

# 查看自动服务状态
wecom-cleaner service status --output agent-json

# 手动触发一次自动服务任务
wecom-cleaner service run --ack SERVICE_RUN --output agent-json

输出与兼容参数

• --output json|text|agent-json：无交互输出格式，默认 json。
• --json：兼容别名，等价于 --output json。
• --delete-mode direct|recycle|service_recycle：删除方式。
• --direct-delete-ack DIRECT_DELETE：非交互直删确认词。
• --recycle-scope manual|service|all：回收站治理范围。
• --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：确认执行升级动作（无此参数将拒绝执行升级）。
• --upgrade-sync-skills true|false：升级后是否联动同步 skills（默认 true）。
• --skill-sync-method npm|github-script：skills 同步方式（默认 npm）。
• --skill-sync-ref <x.y.z>：skills 同步版本标签（通常与程序版本一致）。
• --service-retain-days <days>：自动服务保留天数。
• --service-delete-mode service_recycle|direct：自动服务删除方式。
• --service-direct-delete-ack SERVICE_DIRECT_DELETE：服务直删确认词。
• --service-recycle-retention-days <days>：服务回收站保留天数。
• --service-recycle-min-keep-batches <n>：服务回收站至少保留批次数。
• --service-recycle-threshold-gb <n>：服务回收站容量阈值。
• --service-low-space-threshold-gb <n>：系统低空间绝对阈值。
• --service-low-space-threshold-percent <n>：系统低空间百分比阈值。
• --service-trigger-times HH:MM,HH:MM,HH:MM：自动服务定时点。
• --service-cooldown-minutes <n>：自动服务冷却窗口。

各动作关键统计字段（JSON）

cleanup-monthly

• summary.matchedTargets：命中目标数
• summary.matchedBytes：命中目标总字节
• summary.hasWork / summary.noTarget：是否存在可执行目标
• summary.successCount / skippedCount / failedCount
• summary.reclaimedBytes：预计或实际释放字节
• summary.batchId：真实执行批次号（dry-run 为预演批次）
• summary.matchedMonthStart / matchedMonthEnd：本次命中的月份区间
• summary.rootPathCount：涉及的清理根目录数量
• summary.accountCount / monthCount / categoryCount / externalRootCount
• summary.cutoffMonth：截止月份（当使用 --cutoff-month 时）
• summary.runTaskMode / summary.taskDecision：阶段协议模式与决策（仅 --run-task）

cleanup-monthly 还会在 data.report 中返回可展示明细：

• data.report.matched.categoryStats：按类别统计（条目数、体积）
• data.report.matched.monthStats：按月份统计（条目数、体积）
• data.report.matched.rootStats：按根目录统计（条目数、体积）
• data.report.matched.topPaths：按体积 Top 路径样例
• data.report.executed.byCategory/byMonth/byRoot：真实执行落地统计（成功/跳过/失败 + 体积）
• data.protocolVersion：任务协议版本
• data.taskPhases：阶段执行明细（预演/执行/复核，或单阶段摘要）
• data.taskCard：面向用户与 Agent 的任务卡片聚合结果
• data.scanDebug：扫描诊断（当 --scan-debug summary|full）

analysis-only

• summary.targetCount / totalBytes：命中目录数与总体积
• summary.accountCount / matchedAccountCount / categoryCount / monthBucketCount：维度汇总（范围账号数 vs 实际命中账号数）
• data.accountsSummary / categoriesSummary / monthsSummary：分布统计
• data.report.matched：统一的类别/月份/根目录/路径样例统计结构

space-governance

• summary.matchedTargets / matchedBytes
• summary.successCount / skippedCount / failedCount / reclaimedBytes
• summary.tierCount / targetTypeCount / rootPathCount
• data.report.matched.byTier/byTargetType/byAccount/byRoot/topPaths
• data.report.executed.byCategory/byMonth/byRoot/topPaths（真实执行时）

restore-batch

• summary.batchId / entryCount / matchedBytes
• summary.successCount / skippedCount / failedCount / restoredBytes
• summary.scopeCount / categoryCount / rootPathCount
• data.report.matched.byScope/byCategory/byMonth/byRoot/topEntries
• data.report.executed.byScope/byCategory/byMonth/byRoot/topEntries（真实执行时）

recycle-maintain

• summary.candidateCount / selectedByAge / selectedBySize
• summary.deletedBatches / deletedBytes / failedBatches
• summary.remainingBatches / remainingBytes
• data.report.before / after / thresholdBytes / overThreshold
• data.report.selectedCandidates / operations

doctor

• summary.overall / pass / warn / fail
• data.checks：逐项体检结论（pass/warn/fail）
• data.metrics：账号数、回收区占用、外部存储等关键指标
• data.runtime：运行时环境信息

check-update

• summary.checked：是否完成检查
• summary.hasUpdate：是否发现新版本
• summary.currentVersion / latestVersion
• summary.source：npm 或 github
• summary.channel：stable 或 pre
• summary.skillsStatus / summary.skillsMatched
• summary.skillsInstalledVersion / summary.skillsBoundAppVersion
• data.update：检查详情（含 errors、checkReason、checkedAt）
• data.skills：skills 绑定详情（状态、目录、建议）

upgrade

• summary.executed：是否执行了升级命令
• summary.method：npm 或 github-script
• summary.targetVersion：目标版本
• summary.status：升级命令退出码
• data.upgrade.command：实际执行命令
• summary.skillSyncStatus / summary.skillSyncMethod / summary.skillSyncTargetVersion
• summary.skillsStatusBefore / summary.skillsStatusAfter
• data.skillSync：skills 同步命令结果

sync-skills

• summary.method：skills 同步方式（npm / github-script）
• summary.status：dry_run / synced / failed / mismatch_after_sync
• summary.skillsStatusBefore / summary.skillsStatusAfter
• data.before / data.after：同步前后 skills 绑定详情
• data.skillSync：执行命令与退出码

service-status

• summary.installed：是否已安装自动服务
• summary.loginLoaded / summary.scheduleLoaded：登录触发与定时触发是否已载入
• summary.nextRunAt：下一次计划执行时间
• summary.deleteMode / summary.retainDays / summary.triggerTimes

service-run

• summary.triggerSource：service_login / service_schedule / service_manual
• summary.deleteMode：服务删除方式
• summary.matchedTargets / matchedBytes
• summary.reclaimedBytes：本轮处理源缓存释放空间
• summary.serviceRecycleDeletedBatches / serviceRecycleDeletedBytes
• summary.lowSpaceTriggered / lowSpaceDeletedBatches / lowSpaceDeletedBytes

全局参数

• --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>：按来源筛选探测目录（默认 all，优先减少漏扫；可按需收窄）
• --theme <auto|light|dark>：Logo 主题
• --interactive：即使携带参数也进入交互流程（可配合 --mode）
• --force：锁异常场景下强制清理并继续（兜底参数，通常无需）
• --run-task preview|execute|preview-execute-verify：阶段任务协议（推荐无交互自动化调用）
• --scan-debug off|summary|full：附加扫描诊断信息

--theme 可选值

• auto：自动判断终端主题
• light：亮色
• dark：暗色

额外环境变量

• WECOM_CLEANER_NATIVE_AUTO_REPAIR=true|false：Zig 自动修复总开关（默认 true）
• WECOM_CLEANER_NATIVE_BASE_URL=<url>：核心下载基地址
• 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）

数据与审计文件

默认状态目录：~/.wecom-cleaner-state

• config.json：交互配置
• account-aliases.json：账号别名
• index.jsonl：删除/恢复流水审计
• recycle-bin/：手动回收站
• service-recycle-bin/：自动服务专用回收站
• service-config.json：自动服务配置
• service-state.json：自动服务最近运行状态
• latest-task.json：最近一次任务摘要（供首页驾驶舱与 Agent 协议复用）
• .wecom-cleaner.lock：运行锁文件（防并发误操作）

index.jsonl 常见字段：

• scope：cleanup_monthly 或 space_governance
• deleteMode：direct / recycle / service_recycle
• recycleScope：manual / service / null
• triggerSource：interactive / cli / service_*
• tier：safe / caution / protected
• status：success、dry_run、skipped_*、failed
• error_type：错误分类（如 path_not_found、path_validation_failed、permission_denied）

回收区治理审计（action=recycle_maintain）常见字段：

• selected_by_age：按年龄规则选中的批次数
• selected_by_size：按容量规则补选的批次数
• remaining_bytes：治理后回收区总占用

常见越界拦截原因（skipped_invalid_path.invalid_reason）：

• source_outside_profile_root
• source_outside_governance_root
• source_symlink_escape
• recycle_symlink_escape
• missing_allowed_root
• missing_recycle_root
• source_path_unresolvable
• recycle_path_unresolvable

开发与质量门禁

# 语法检查
npm run check

# 单元测试
npm run test

# 覆盖率报告
npm run test:coverage

# 覆盖率门禁（lines/statements >= 75%，functions >= 80%，branches >= 60%）
npm run test:coverage:check

# 格式化与风格检查
npm run format
npm run format:check

发布前推荐全量门禁：

npm run format:check
npm run check
npm run test:coverage:check
npm run release:gate
npm run e2e:smoke -- --keep
npm run pack:tgz:dry-run

当前基线（主分支）：

• 单元测试：107/107 通过。
• 覆盖率：statements 87.66%，branches 74.38%，functions 92.47%，lines 87.66%。
• 全菜单 smoke：通过（含恢复冲突分支与 doctor JSON 分支）。

测试矩阵

• 场景矩阵与断言模板见：docs/TEST_MATRIX.md
• 新增动作或输出字段时，需同步更新矩阵并补对应测试。

发布与打包

prepack 会自动执行：

• npm run build:native:release
• npm run check

默认构建两个 macOS 核心：

• native/bin/darwin-x64/wecom-cleaner-core
• native/bin/darwin-arm64/wecom-cleaner-core

说明：native/bin/ 为构建产物目录，不纳入 Git 版本管理。

本地交付包（无作用域前缀）建议：

npm run pack:tgz

输出示例：wecom-cleaner-<version>.tgz

正式发布（GitHub Release + npm）

# 推荐：一键发布（以后统一用这个）
npm run release:ship

# 仅预演（不真正发布）
npm run release:ship:dry-run

# 可选：跳过 npm 或 GitHub 发布（例如仅补传附件）
npm run release:ship -- --skip-npm
npm run release:ship -- --skip-github

建议发布前确认登录状态：

• gh auth status
• npm whoami

跨平台构建示例：

# 按当前机器平台
./native/zig/build.sh

# 发布前构建 macOS 双架构
npm run build:native:release

# 指定目标编译（示例）
TARGET_OS=darwin TARGET_ARCH=arm64 ./native/zig/build.sh
TARGET_OS=windows TARGET_ARCH=x64 ./native/zig/build.sh

FAQ

1) “Zig加速:已就绪” 和 “已生效” 有什么区别？

• 已就绪：检测到 Zig 核心，但当前仅在菜单阶段，还没进入扫描。
• 已生效：已经进入扫描，且本次实际使用 Zig。

2) 为什么显示 “Node回退”？

检测到 Zig 核心，但本次运行探针失败或运行异常，已自动切回 Node，功能可继续使用。

3) 会不会误删企业文档？

默认策略不会把普通业务文档目录（例如 WeDrive/<企业名>/...）纳入治理规则；执行前还有分级提示、确认和回收区兜底。

全量空间治理 目前还会显式建模并分级展示以下 macOS 目录，便于和“聊天缓存”主线区分：

• Documents/Profiles/*/Publishsys/pkg
• Library/Application Support/WXDrive/*
• Library/Application Support/Wedoc/cache
• Library/Application Support/WeMail/*
• Library/Application Support/CEF/User Data
• Library/Application Support/com.tencent.WeWorkMac
• Library/Application Support/CrashReporter
• Library/Application Support/WXWork/VoipRecords
• Library/HTTPStorages
• Library/WebKit/WebsiteData
• Library/WebKit/WebsiteDataStore
• Library/Preferences
• Library/WecomPrivate
• Library/Cookies
• Documents/Network
• Documents/local_en
• Documents/local_storage_index.db
• Documents/VoipNNModel

另外，WeDrive/<企业名> 这类微盘业务目录现在也会在全量空间治理中显式展示，但默认按受保护对象处理，不纳入自动删除范围。

如果你希望我提供“按你当前机器目录结构定制的一键安全清理方案”，可以直接给我一份 --dry-run 输出。