AgentSkillsCN

file-cleaner

系统文件清理工具。扫描并识别大文件、垃圾文件（如临时文件、缓存、日志、备份等），提供交互式清理界面，方便用户自主选择删除内容。当用户需要释放磁盘空间、整理系统文件、查找大文件、清除垃圾文件，或进一步优化存储资源时，可使用此技能。

SKILL.md
--- frontmatter
name: file-cleaner
description: 系统文件清理工具。扫描和识别大文件、垃圾文件（临时文件、缓存、日志、备份等），提供交互式清理界面让用户选择删除。当用户需要清理磁盘空间、整理系统文件、查找大文件、删除垃圾文件或释放存储空间时使用此技能。

File Cleaner

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

核心功能

1. 大文件扫描

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

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

选项：

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

示例：

bash
# 扫描 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. 垃圾文件扫描

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

bash
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> - 生成清理脚本

示例：

bash
# 扫描所有垃圾文件
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. 交互式清理

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

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

选项：

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

示例：

bash
# 清理垃圾文件
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

工作流程

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

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

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

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

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

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

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

# 执行清理
bash cleanup.sh

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

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

bash
# 扫描大文件
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 测试清理操作，不实际删除：

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

使用建议

定期清理

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

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

磁盘空间不足

当磁盘空间不足时：

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

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

项目清理

清理开发项目目录：

bash
# 清理构建产物和缓存
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：磁盘空间告急

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

场景 2：开发环境清理

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

python3 scripts/clean_interactive.py dev_cleanup.json

场景 3：定期维护

bash
# 完整扫描
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

故障排除

权限错误

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

扫描太慢

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

JSON 导出失败

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