一个面向中文用户的 macOS 终端清理工具。默认 dry-run，永不
rm -rf，一切先走废纸篓。
mac-cleanup 是一个跑在终端里的 macOS 安全清理工具。它扫描常见的可回收空间（开发缓存、浏览器缓存、旧下载、Xcode 中间产物等），按风险分级展示，由你逐项确认后移动到废纸篓——不调用 rm，不绕过废纸篓，不自动执行任何破坏性操作。
设计目标只有一句话：256GB 的 Mac，清理空间的时候不应该让人提心吊胆。
$ python3 main.py
╭───────────────────── 欢迎 ─────────────────────╮
│ Mac 安全清理工具 │
│ 本工具只通过「移动到废纸篓」方式清理，永不调用 rm。
│ │
│ 当前模式：DRY-RUN（演练模式） │
│ 本次运行 不会移动或删除任何文件 │
│ 如需真实清理，请退出后使用： │
│ python main.py --apply │
╰────────────────────────────────────────────────╯
磁盘容量：228.27GB 已使用：225.42GB 可用：2.85GB
256GB MacBook 是个尴尬的容量。Xcode 一装，Homebrew 一开，node_modules 一长，可用空间就一直在 10GB 上下徘徊。
我用过的清理方案大致是这两类：
- 商业 App（CleanMyMac、Sensei 等）：界面好看，订阅制，闭源。不知道它到底删了什么、是否能恢复。
- 「复制这段到终端」式脚本：很多直接
rm -rf几个目录，没有 dry-run，没有日志，删完不可逆。
想要一个写得像项目而不是脚本的东西：模块化、有日志、有路径校验、默认 dry-run、所有动作都走废纸篓、所有破坏性操作都要明确确认。mac-cleanup 就是这个东西。
- ✅ 终端交互，全中文界面
- ✅ 默认 dry-run，看清楚再决定
- ✅ 风险三级（安全 / 中等 / 高），分级控制
- ✅ 内置 13 类清理规则：npm / yarn / pip / Homebrew / Xcode / 浏览器 / Slack / Discord / Spotify / Adobe / iOS 模拟器 / 废纸篓 / 旧下载等
- ✅ 大文件分析（>=1GB，仅展示）
- ✅ 全部删除走
send2trash，可在 Finder 恢复 - ✅ JSONL 删除日志，可审计
- ✅ 路径白名单 + 黑名单双校验，扫描时和执行前各一次
- ✅ Apple Silicon / Intel 双架构
- ✅ macOS Ventura / Sonoma / Sequoia
清理流程穿过 6 道关卡，缺一则操作终止：
| # | 关卡 | 实现位置 | 作用 |
|---|---|---|---|
| 1 | 风险分类 | categories.py |
SAFE / MEDIUM / HIGH 三级。HIGH 永不进入删除流程；MEDIUM 默认锁定 |
| 2 | 路径白名单 | safety.py |
解析后路径必须严格位于 $HOME 之内 |
| 3 | 路径黑名单 | safety.py |
等于或包含 ~/Documents、~/Desktop、~/Library、~/.ssh、Keychains、iCloud Drive、Photos Library 等任一项 → 拒绝 |
| 4 | dry-run 默认 | cli.py |
不加 --apply，第 6 步整段跳过 |
| 5 | YES 二次确认 | cli.py |
必须精确输入大写 YES；中风险还需先输入 continue |
| 6 | 执行前复检 | cleaner.py |
调用 send2trash 之前再跑一次 is_safe_to_delete |
不会做的事：
- ❌ 不调用
rm、rm -rf、os.remove、shutil.rmtree - ❌ 不绕过废纸篓
- ❌ 不触碰
~/Documents/~/Desktop/~/Pictures/~/Movies - ❌ 不触碰 iCloud Drive、Photos Library、Keychains、SSH 密钥
- ❌ 不在缺少
--apply时执行任何真实删除 - ❌ 不在缺少
YES时移动任何文件
git clone https://github.com/<your-name>/mac-cleanup.git
cd mac-cleanup
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt仓库里有 setup.sh，可放在桌面运行：
chmod +x setup.sh
./setup.sh会在 ~/Desktop/mac-cleanup 写入全部源码、创建虚拟环境、装好依赖。
python3 main.py会完整跑一遍 扫描 → 选择 → 输入 YES 的流程，但任何 YES 都不会真正移动文件。所有「将要删除」的路径会写入 dry-run 日志，便于事后审查。
python3 main.py --apply启用真实执行。仍然：
- 默认只能选「安全」分类
- 每次操作前要看完完整路径清单和汇总
- 必须输入
YES才会动手 - 全部走
send2trash，文件落到废纸篓，可手动恢复
python3 main.py --apply --allow-medium解锁中风险分类（~/Library/Caches 合集、废纸篓、Spotify 缓存、30 天未访问的 Downloads 等）。执行前会额外要求输入 continue，然后才进入 YES 确认。
| 等级 | 默认行为 | 例子 |
|---|---|---|
| 🟢 安全 | --apply 后可选 |
npm / yarn / pip / Homebrew / Xcode DerivedData / Xcode 旧日志 / 浏览器缓存 / 用户日志 |
| 🟡 中等 | 锁定，需 --allow-medium + continue + YES |
~/Library/Caches 全集、废纸篓、Slack/Discord/Telegram/Spotify 缓存、30 天未访问的 Downloads、DMG 安装包、iOS 模拟器/DeviceSupport、Adobe 缓存 |
| 🔴 高风险 | 永远只展示，工具内无法清理 | iPhone 本地备份 |
某台 256GB MBP 上，仅 SAFE 分类一轮：
npm 缓存 3.79 GB
浏览器缓存 2.04 GB
Xcode DerivedData 492 MB
Homebrew 下载缓存 289 MB
pip 缓存 201 MB
用户日志 38 MB
────────────────────────────────
合计 ~6.8 GB
再加上 --allow-medium：
+ 用户缓存合集 5.80 GB
+ 30 天未访问 Downloads 6.18 GB
+ DMG 安装包 3.83 GB
+ iOS 模拟器 3.73 GB
────────────────────────────────
总计可释放 ~26 GB
每次会话写入两个文件：
~/.mac-cleanup/logs/
├── session-YYYYMMDD.log # 标准日志
└── deletions-YYYYMMDD-HHMMSS.jsonl # 每个被处理项一行
JSONL 每条记录的 phase 字段可能是：
| phase | 含义 |
|---|---|
dry-run |
dry-run 模式下的演练记录 |
attempt |
真实模式即将调用 send2trash |
trashed |
成功移动到废纸篓 |
rejected |
被安全规则拒绝 |
failed |
系统层面失败（权限、占用） |
所有「删除」实际是「移动到废纸篓」：
- 访达 → 废纸篓
- 右键文件 → 放回原处
只要没清空废纸篓，恢复永远可行。
mac-cleanup/
├── main.py # CLI 入口（argparse）
├── requirements.txt
├── setup.sh # 一键安装脚本
└── cleanup/
├── cli.py # 中文终端 UI（rich）
├── scanner.py # 扫描引擎（只读）
├── cleaner.py # 执行删除（send2trash）
├── analyzer.py # 大文件分析
├── categories.py # 分类定义 + 风险分级
├── safety.py # 路径校验
├── logger.py # 文件日志 + JSONL 流水
└── utils.py # 通用工具
- Phase 1 — 终端 MVP（当前版本）
- Phase 2 — 重复文件检测、目录树可视化、单元测试覆盖 safety 模块
- Phase 3 — PyQt6 图形界面
- Phase 4 —
.app打包、代码签名、公证
MIT