disk-cleaner

磁盘空间清理（跨平台）

何时使用

• 磁盘告警 / 空间不足，需要释放空间
• 用户点名要清 npm / pip / yarn / pnpm / brew / apt 缓存、临时文件、IDE 缓存
• 用户想知道"空间被谁吃了"

核心原则

1. 两道确认。先由用户勾选"删哪些"，再展开每项的完整路径/大小/分级/删除代价，用户二次确认后才动手。脚本绝不自动全删。
2. 先扫描，后删除。清单出来前不碰任何文件。
3. 白名单 + 发现双通道。已知软件的缓存走白名单，未知缓存靠启发式扫描找出来。
4. 发现项默认只报告。启发式扫出的陌生目录进清单但不会自动删，需用户主动勾选。
5. 只删可再生缓存。配置、代码、聊天记录、数据库一律不动。
6. 软链逃逸防护。删除前用 realpath 解析符号链接，校验真实路径严格落在允许根区（带分隔符边界，杜绝前缀绕过）；删除时绝不跟随软链，遇到软链只删链接本身。

四层架构

快速开始

脚本在 scripts/ 下，默认就是只读扫描：

python scripts/clean_cache.py --dry-run        # 只出清单，不删（最安全，推荐先跑）
python scripts/clean_cache.py                  # 出清单 → 勾选 → 看详情 → 确认 → 删除
python scripts/clean_cache.py --pick 1,3,5     # 指定序号（仍会展开详情要你确认）
python scripts/clean_cache.py --pick g --force # 跳过二次确认，仅在已核对过时使用
python scripts/clean_cache.py --json           # 机器可读输出，供上层解析

删除前会展开选中项的完整信息，确认无误后输入 y 才执行：

======================================================================
 待删除 2 项，预计释放 1.20 GB
======================================================================
  1. uv/cache
     路径  C:\Users\xxx\AppData\Local\uv\cache
     大小  518.56 MB      分级  发现项      来源  启发式扫描
     说明  启发式扫描得出，未经人工验证，请核对路径后再删
----------------------------------------------------------------------
  合计 1.20 GB      当前可用 59.53 GB      删除后预计 60.73 GB
----------------------------------------------------------------------
  确认删除？输入 y 执行，其他任意键取消:

--force 可跳过这道确认，只用于已经核对过、要放进定时任务的场景。--json 模式只输出清单不删除，不受影响。

勾选语法（交互输入或 --pick）：

常用参数：--tier yellow（清单里加入"需重下"项）、--min-size 100（只列 ≥100MB）、--keep-temp-days 7、--no-discover（只查白名单）、--no-temp、--no-trash。

Windows 用户双击 scripts/clean.bat 直接进入交互勾选。

分级说明

禁止删除（会出事）

脚本内置 FORBIDDEN_PARTS 与 assert_safe() 双重拦截，命中即拒绝并打印警告。

三平台缓存根区

详见 references/platform-paths.md。

空间分析方法（找大头）

脚本负责清，找大头可以配合系统命令：

# Linux / macOS
du -sh ~/.cache/* ~/Library/Caches/* 2>/dev/null | sort -rh | head -20

# Windows（Git Bash）
du -sh "$LOCALAPPDATA"/*/ "$APPDATA"/*/ 2>/dev/null | sort -rh | head -20

⚠️ 不要对 /c/Windows、/System、/usr 跑 du —— 文件量太大，跑十几分钟还拖慢整机。

本机环境坑

1. PowerShell stdout 可能被吞（只回 exit code）。要结果就 Out-File 到文件再读。
2. $env:APPDATA 在部分 Shell 里为空（LOCALAPPDATA 正常）。脚本已从 LOCALAPPDATA 反推，勿改回 os.path.expandvars 单依赖。
3. 删除方式选择：
   • PowerShell Remove-Item -Recurse -Force → 大目录会被 [safe-delete][SAFE_DELETE_BULK_GUARD_ERROR] 拦下
   • bash rm 常被包装成 safe-delete → 慢且进回收站，绕过用 /usr/bin/rm
   • 最快最稳：[System.IO.Directory]::Delete($p, $true)
   • npm cache clean --force 可能卡在 genie-trash ETIMEDOUT → 直接删目录
4. .bat 必须纯 ASCII。cmd 按 GBK 读 bat，UTF-8 中文注释会被当命令执行，报"不是内部或外部命令"。
5. Windows 长路径：深目录要 \\?\ 前缀（脚本已内置 long_path()）。
6. WPS addons 文件极多：别用资源管理器打开（会卡死），删前必须退出 WPS 及 wpscloudsvr.exe。
7. Git Bash 的 du 很慢：扫大目录放后台跑。
8. 清空回收站：C 盘回收站里的文件不删不会释放空间，脚本末尾默认清一次（--no-trash 可关）。

扩展清理项

编辑 scripts/clean_cache.py 的 TARGETS：

# (名称, 路径模式, 分级, 占用进程, 适用平台)
("我的缓存", "~/.cache/myapp", TIER_GREEN, None, None),              # 全平台
("Windows 专用", r"%LOCALAPPDATA%\App\Cache", TIER_GREEN, None, ["windows"]),
("要先退出的", r"%APPDATA%\App\cache", TIER_GREEN, ["app.exe"], ["windows"]),

路径支持 ~、%ENV%、$HOME、* 通配符。平台填 None 表示全平台。 IDE_SCAN / ELECTRON_SCAN 控制 IDE 与 Electron 应用的通配扫描范围。

参考

• scripts/clean_cache.py — 主程序（四层架构都在里面）
• scripts/clean.bat — Windows 双击入口（纯 ASCII）
• references/platform-paths.md — 三平台路径对照 + 各平台特有清理项
• references/cleanup-catalog.md — 已知软件清单、分级表、禁止清单