System Cache Cleaner
安全地清理 Windows 系统与多语言开发缓存，并定位大文件。核心原则是
先只读扫描 → 交互式报告审阅 → 显式确认 → 回收站删除（可恢复），
绝不未经确认就删除任何文件。
Overview
本 skill 提供三个脚本与一个参考文档：
scripts/scan.py— 只读扫描，输出scan_results.json（绝不删除）。scripts/generate_report.py— 把扫描结果生成为自包含的交互式 HTML 报告。scripts/clean.py— 按报告执行清理，默认移入回收站，仅接受报告中存在的路径。references/cache_locations.md— 各缓存路径、风险等级与清理行为的详细参考。
所有脚本仅依赖 Python 标准库，使用受管 Python 运行：
C:\Users\HW\.workbuddy\binaries\python\versions\3.13.12\python.exe
⚠️ 强制安全流程（任何清理都必须遵守）
- 永远先扫描，再谈删除。 不要让用户跳过扫描。
- 先展示报告，再删除。 用
generate_report.py生成 HTML 并在浏览器打开，
让用户勾选。 - 删除前必须显式确认。 在执行
clean.py之前，向用户列出将要清理的
每一项路径，并用粗体警告：
"⚠️ 此操作可能导致不可逆的数据丢失！" - 默认走回收站（可恢复）。 不使用
rm -rf/del /S /Q，不启用
--permanent，除非用户明确要彻底删除。 - 拒绝报告外路径。
clean.py会自动拒绝任何不在扫描报告中的路径；
若脚本报错退出，先排查，不要强行绕过。 - 大文件格外谨慎。 大文件可能是用户个人数据；只有用户在报告里逐条勾选、
并确认后，才纳入清理。
Workflow
Step 1 — 扫描（只读）
在用户工作区或临时目录运行 scan.py：
PY="C:/Users/HW/.workbuddy/binaries/python/versions/3.13.12/python.exe"
$PY "C:/Users/HW/.workbuddy/skills/system-cache-cleaner/scripts/scan.py" \
--out <工作区>/scan_results.json \
--large-threshold-mb 500
可选参数：
- --no-large：跳过扫描大文件（更快）。
- --large-roots C:\Users\HW,D:\projects：指定大文件扫描根（逗号分隔）。
- --large-max-depth 3：大文件扫描最大深度（默认 3）。
- --project-roots C:\Users\HW\projects：限定 node_modules / Python 缓存搜索范围。
扫描完成后，向用户简要汇报可清理总量（类别可回收 + 大文件）。
Step 2 — 生成交互式报告
$PY "C:/Users/HW/.workbuddy/skills/system-cache-cleaner/scripts/generate_report.py" \
--scan <工作区>/scan_results.json \
--out <工作区>/cleanup_report.html
用 present_files 打开 cleanup_report.html，让用户在浏览器中：
- 展开各分类，查看每项路径、大小、创建/修改时间、风险徽章；
- 勾选要清理的项（大文件默认折叠，需逐条确认）；
- 点击「复制清理指令」，把所选内容（JSON）粘贴回对话。
Step 3 — 确认并执行清理
收到用户粘贴的清理指令（或口头指定类别）后：
- 再次列出将清理的路径，并给出粗体不可逆警告。
- 用户明确确认后，运行
clean.py：
$PY "C:/Users/HW/.workbuddy/skills/system-cache-cleaner/scripts/clean.py" \
--scan <工作区>/scan_results.json \
--categories win_temp,maven_repo \
--paths "C:/Users/HW/bigfile.iso" \
--dry-run # 先 dry-run 预览
确认无误后，去掉 --dry-run 真正执行。说明：
- --categories：按类别 id 清理（见 references/cache_locations.md）。
- --paths：显式路径（必须在报告中）。
- --include-large：把报告中所有大文件一并清理（谨慎使用）。
- --permanent：彻底删除（不可恢复，仅用户明确要求时启用）。
- 报告成功/失败数量；提醒用户已移入回收站、可从回收站恢复。
⚠️ 沙箱删除限制与自执行脚本（重要）
在部分 WorkBuddy 运行环境中，删除工作区之外的文件会被安全层拦截
（日志 SAFE_DELETE_FAIL_CLOSED / windows-sandbox-recycle-bin-unavailable），导致
clean.py 实际执行时静默失败、文件不被动到。这不是 bug，是环境在保护你的个人文件。
遇到这种情况，用 --self-cmd 让用户在自己终端完成清理：
$PY "C:/Users/HW/.workbuddy/skills/system-cache-cleaner/scripts/clean.py" \
--scan <工作区>/scan_results.json \
--categories fnm_residue,win_temp \
--paths "D:/work_code/python/llm-test/venv" \
--self-cmd
该命令不会删除任何东西，而是生成一份 <scan>_self_clean.ps1 脚本，仅包含扫描报告
中允许的路径。把脚本路径告诉用户，让其在【自己】的 PowerShell/CMD 运行：
powershell -ExecutionPolicy Bypass -File "<工作区>/scan_results_self_clean.ps1"
- 该脚本用系统
py/python 调用clean.py，走真实 Windows 回收站（可恢复）； - 清理系统目录（Prefetch / SoftwareDistribution / WER）失败时用管理员身份运行；
- 运行前可先打开脚本确认将删除的路径。
> 判断依据：若 clean.py 在某次执行后目标路径仍全部存在、且无明显输出，多半是沙箱拦截，
> 改用 --self-cmd 即可。
常见用户请求 → 处理
- "清理开发缓存"：扫描后建议勾选
maven_repo、gradle_cache、pip_cache、
python_caches、python_venv、go_modcache、node_npm_cache、node_pnpm_cache、
node_yarn_cache、node_modules（medium 风险项会提示需重新下载/安装或重建 venv）。 - "清理系统垃圾"：建议
win_temp、win_thumbnails、浏览器缓存（均为 low）。 - "清理 fnm 残留"：
scan.py会自动识别fnm_multishells中 PID 已退出的"死"残留
（活跃 shell 环境会被保留），类别fnm_residue，风险 low，常可释放数 GB~数十 GB。 - "找一下大文件"：运行带
--large-*的扫描，在报告里展示大文件清单。 - "清理 C 盘 / 磁盘清理"：推荐预设——只扫用户目录、避免整个系统盘全盘遍历导致极慢：
$PY "C:/Users/HW/.workbuddy/skills/system-cache-cleaner/scripts/scan.py" \
--out <工作区>/scan_results_cdrive.json \
--project-roots "C:\Users\HW" \
--large-roots "C:\Users\HW" \
--large-threshold-mb 300 \
--large-max-depth 3
> 注意：不要用 --large-roots C:\ 全盘扫（极慢且易触及个人文件/系统目录）。
> C 盘系统缓存（Prefetch/SoftwareDistribution/WER）需管理员权限，清理时以管理员运行脚本。
参考
详细缓存路径、风险等级与清理行为见 references/cache_locations.md。
