File Cleaner

系统文件清理工具，帮助用户扫描、识别和清理大文件与垃圾文件。

核心功能

1. 大文件扫描

扫描指定目录，找出占用空间的大文件（默认 >10MB）。

python3 scripts/find_large_files.py <directory> [options]

选项：

• --min-size <MB> – 最小文件大小（默认: 10）
• --max-results <N> – 最大结果数（默认: 100）
• --show <N> – 显示的文件数（默认: 20）
• --export <path> – 导出结果到 JSON

示例：

# 扫描 home 目录的大文件
python3 scripts/find_large_files.py ~

# 扫描大于 50MB 的文件
python3 scripts/find_large_files.py ~ --min-size 50

# 导出结果
python3 scripts/find_large_files.py ~ --export large_files.json

2. 垃圾文件扫描

扫描并识别各类垃圾文件：临时文件、缓存、日志、备份等。

python3 scripts/find_garbage.py <directory> [options]

垃圾文件类别：

• temp_files – 临时文件（.tmp, .temp, .bak, .swp, .DS_Store）
• cache_files – 缓存文件（pycache, *.pyc, .cache）
• log_files – 日志文件（*.log）
• backup_files – 备份文件（.backup, .old）
• build_artifacts – 构建产物（dist, build, .next, out）
• editor_temp – 编辑器临时文件（.swo, .swn）
• download_temp – 下载临时文件（.crdownload, .part）

选项：

• --categories <cat1> <cat2> – 指定扫描类别（默认: 全部）
• --show <N> – 每个类别显示的文件数（默认: 10）
• --export <path> – 导出结果到 JSON
• --script <path> – 生成清理脚本

示例：

# 扫描所有垃圾文件
python3 scripts/find_garbage.py ~

# 只扫描缓存和临时文件
python3 scripts/find_garbage.py ~ --categories cache_files temp_files

# 导出结果
python3 scripts/find_garbage.py ~ --export garbage_scan.json

# 生成清理脚本
python3 scripts/find_garbage.py ~ --script cleanup.sh

3. 交互式清理

基于扫描结果，提供交互式界面让用户选择要清理的文件。

python3 scripts/clean_interactive.py <scan_result.json> [options]

选项：

• --type <garbage|large> – 扫描结果类型（默认: garbage）
• --dry-run – 预演模式，不实际删除文件

示例：

# 清理垃圾文件
python3 scripts/clean_interactive.py garbage_scan.json

# 清理大文件
python3 scripts/clean_interactive.py large_files.json --type large

# 预演模式（测试）
python3 scripts/clean_interactive.py garbage_scan.json --dry-run

工作流程

标准流程：扫描 → 导出 → 清理

# 步骤 1: 扫描垃圾文件
python3 scripts/find_garbage.py ~ --export /tmp/garbage_scan.json

# 步骤 2: 交互式清理
python3 scripts/clean_interactive.py /tmp/garbage_scan.json

快速流程：直接清理（推荐）

对于垃圾文件，可以直接生成清理脚本：

# 生成清理脚本
python3 scripts/find_garbage.py ~ --script cleanup.sh

# 检查脚本（确认要删除的文件）
cat cleanup.sh

# 执行清理
bash cleanup.sh

大文件流程：分析 → 选择性清理

对于大文件，推荐使用交互式清理：

# 扫描大文件
python3 scripts/find_large_files.py ~ --export /tmp/large_files.json

# 交互式选择删除
python3 scripts/clean_interactive.py /tmp/large_files.json --type large

安全特性

自动排除

以下目录和文件会自动排除，避免误删：

• 系统目录：/proc, /sys, /dev, /usr, /bin等
• 版本控制：.git, .svn, .hg
• Python 环境：venv, .venv, env

垃圾文件分类

垃圾文件分为两类：

🟢 安全删除（自动标记）：

• 临时文件
• 缓存文件
• 备份文件
• 构建产物
• 编辑器临时文件

🟡 需要确认（需手动检查）：

• 日志文件（可能用于调试）
• 下载临时文件（可能未完成）

预演模式

使用 --dry-run 测试清理操作，不实际删除：

python3 scripts/clean_interactive.py scan.json --dry-run

使用建议

定期清理

建议每月执行一次文件清理：

# 每月清理脚本
python3 scripts/find_garbage.py ~ --export /tmp/monthly_scan.json
python3 scripts/clean_interactive.py /tmp/monthly_scan.json

磁盘空间不足

当磁盘空间不足时：

# 1. 找出最大的文件
python3 scripts/find_large_files.py ~ --min-size 100 --show 20

# 2. 清理垃圾文件
python3 scripts/find_garbage.py ~ --script cleanup.sh
bash cleanup.sh

项目清理

清理开发项目目录：

# 清理构建产物和缓存
python3 scripts/find_garbage.py ~/projects \
  --categories build_artifacts cache_files \
  --script project_cleanup.sh

注意事项

⚠️ 使用前必读：

1. 先预览再删除

   • 使用 --dry-run 测试
   • 查看扫描结果后再确认

2. 重要文件备份

   • 删除前备份重要数据
   • 日志文件可能包含重要信息

3. 权限问题

   • 某些文件可能需要 sudo 权限
   • 无权限的文件会自动跳过

4. 不可恢复

   • 删除操作不可撤销
   • 建议使用 trash 命令而不是直接删除

脚本说明

find_large_files.py

扫描大文件，输出文件列表和总大小。自动排除系统目录和版本控制目录。

find_garbage.py

识别 7 种垃圾文件类型，分类统计，标记安全删除状态。可生成自动清理脚本。

clean_interactive.py

交互式清理界面，支持按类别选择、批量操作、预演模式。显示文件详情和总大小。

示例场景

场景 1：磁盘空间告急

# 快速找出大文件
python3 scripts/find_large_files.py ~ --min-size 500 --show 10

场景 2：开发环境清理

# 清理所有构建产物
python3 scripts/find_garbage.py ~/projects \
  --categories build_artifacts cache_files \
  --export dev_cleanup.json

python3 scripts/clean_interactive.py dev_cleanup.json

场景 3：定期维护

# 完整扫描
python3 scripts/find_garbage.py ~ --export monthly_scan.json
python3 scripts/find_large_files.py ~ --export large_files.json

# 分别处理
python3 scripts/clean_interactive.py monthly_scan.json
python3 scripts/clean_interactive.py large_files.json --type large

故障排除

权限错误

# 使用 sudo（谨慎）
sudo python3 scripts/find_large_files.py /

扫描太慢

# 限制扫描深度（只扫描指定目录）
python3 scripts/find_large_files.py ~/Downloads --max-results 50

JSON 导出失败

# 确保目录存在
mkdir -p /tmp
python3 scripts/find_garbage.py ~ --export /tmp/scan.json