macos-cleaner

智能分析 macOS 磁盘使用情况并提供可执行的清理建议以回收存储空间。此技能遵循安全第一的原则：彻底分析，呈现清晰的发现，并在执行任何删除操作前要求明确的用户确认。

目标用户：具有基本技术知识的用户，了解文件系统但需要指导哪些内容在 macOS 上可以安全删除。

1. 安全第一，绝不绕过：在没有明确用户确认的情况下，绝不执行危险命令（rm -rf、mo clean 等）。没有捷径，没有变通方法。
2. 价值优于虚荣：您的目标不是最大化清理空间。您的目标是识别什么是真正无用的 vs 有价值的缓存。为了显示大数字而清除 50GB 有用缓存是有害的。
3. 网络环境意识：许多用户（尤其是中国）的网络缓慢/不可靠。重新下载缓存可能需要数小时。一个节省 30 分钟下载时间的缓存是值得保留的。
4. 必须进行影响分析：每个清理建议必须包含"删除后会发生什么"列。绝不要在不解释后果的情况下仅列出项目。
5. 耐心优于速度：磁盘扫描可能需要 5-10 分钟。绝不中断或跳过慢速操作。定期向用户报告进度。
6. 用户执行清理：分析完成后，提供清理命令让用户自己运行。不要自动执行清理。
7. 保守默认：如有疑问，不要删除。倾向于谨慎。

绝对禁止：

• ❌ 绝不自动在用户目录上运行 rm -rf
• ❌ 绝不在没有预览试运行的情况下运行 mo clean
• ❌ 绝不使用 docker volume prune -f 或 docker system prune -a --volumes
• ❌ 绝不为节省时间跳过分析步骤
• ❌ 绝不在 Mole 命令后附加 --help（除了 mo --help）
• ❌ 绝不建议删除有用的缓存只是为了夸大清理数字

```

用户报告磁盘空间问题

↓

快速诊断

↓

┌──────┴──────┐

│ │

立即清理 深度分析

│ (继续下方)

│ │

└──────┬──────┘

↓

呈现发现

↓

用户确认

↓

执行清理

↓

验证结果

```

主要工具：使用 Mole 进行磁盘分析。它提供全面的、分类的结果。

1.1 预检检查

```bash

# 检查 Mole 安装和版本

which mo && mo --version

# 如果未安装

brew install tw93/tap/mole

# 检查更新（Mole 经常更新）

brew info tw93/tap/mole | head -5

# 如果过时则升级

brew upgrade tw93/tap/mole

```

1.2 选择分析方法

重要：使用 mo analyze 作为主要分析工具，而不是 mo clean --dry-run。

| 命令 | 目的 | 使用时机 |

|---------|---------|----------|

| mo analyze | 交互式磁盘使用浏览器（TUI 树视图） | 主要：了解什么占用了空间 |

| mo clean --dry-run | 预览清理类别 | 次要：仅在 mo analyze 之后查看清理预览 |

为什么优先使用 mo analyze：

• 专用的磁盘分析工具，具有交互式树导航
• 允许深入到特定目录
• 显示实际的磁盘使用细分，而不仅仅是清理类别
• 对于理解存储消耗更有信息量

1.3 通过 tmux 运行分析

重要：Mole 需要 TTY。从 Claude Code 使用时始终使用 tmux。

关键时间说明：主目录扫描很慢（对于大目录需要 5-10 分钟或更长时间）。提前告知用户并耐心等待。

```bash

# 创建 tmux 会话

tmux new-session -d -s mole -x 120 -y 40

# 运行磁盘分析（主要工具 - 交互式 TUI）

tmux send-keys -t mole 'mo analyze' Enter

# 等待扫描 - 耐心等待！

# 主目录扫描通常需要 5-10 分钟

# 定期向用户报告进度

sleep 60 && tmux capture-pane -t mole -p

# 使用箭头键导航 TUI

tmux send-keys -t mole Down # 移动到下一项

tmux send-keys -t mole Enter # 展开/选择项目

tmux send-keys -t mole 'q' # 完成后退出

```

替代方案：清理预览（在 mo analyze 之后使用）

```bash

# 运行试运行预览（安全 - 无删除）

tmux send-keys -t mole 'mo clean --dry-run' Enter

# 等待扫描（每 30 秒向用户报告进度）

# 耐心等待！大目录需要 5-10 分钟

sleep 30 && tmux capture-pane -t mole -p

```

1.4 进度报告

定期向用户报告扫描进度：

```

📊 磁盘分析进行中...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⏱️ 已用时间：2 分钟

当前状态：

✅ 应用程序：49.5 GB（完成）

✅ 系统库：10.3 GB（完成）

⏳ 主目录：扫描中...（这可能需要 5-10 分钟）

⏳ 应用库：待处理

我正在耐心等待扫描完成。

将在 30 秒后再次报告...

```

1.5 呈现最终发现

扫描完成后，呈现结构化结果：

```

📊 磁盘空间分析（通过 Mole）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

可用空间：27 GB

🧹 可恢复空间（试运行预览）：

➤ 用户必备项

• 用户应用缓存： 16.67 GB

• 用户应用日志： 102.3 MB

• 废纸篓： 642.9 MB

➤ 浏览器缓存

• Chrome 缓存： 1.90 GB

• Safari 缓存： 4 KB

➤ 开发工具

• uv 缓存： 9.96 GB

• npm 缓存： （已检测）

• Docker 缓存： （已检测）

• Homebrew 缓存： （已检测）

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

总可恢复：~30 GB

⚠️ 这是试运行预览。未删除任何文件。

```

系统地扫描以下类别。参考 references/cleanup_targets.md 获取详细说明。

类别 1：系统和应用缓存

要分析的位置：

• ~/Library/Caches/* - 用户应用缓存
• /Library/Caches/* - 系统范围缓存（需要 sudo）
• ~/Library/Logs/* - 应用日志
• /var/log/* - 系统日志（需要 sudo）

分析脚本：

```bash

scripts/analyze_caches.py --user-only

```

安全级别：🟢 通常可以安全删除（应用会重新生成缓存）

要保留的例外：

• 浏览器运行时的浏览器缓存
• IDE 缓存（可能会减慢下次启动）
• 包管理器缓存（Homebrew、pip、npm）

类别 2：应用残留

要分析的位置：

• ~/Library/Application Support/* - 应用数据
• ~/Library/Preferences/* - 偏好设置文件
• ~/Library/Containers/* - 沙盒应用数据

分析方法：

1. 列出 /Applications 中已安装的应用
2. 与 ~/Library/Application Support 交叉引用
3. 识别孤立项（应用已卸载但数据保留）

分析脚本：

```bash

scripts/find_app_remnants.py

```

安全级别：🟡 需要谨慎

• ✅ 安全：明确已卸载应用的文件夹
• ⚠️ 先检查：您很少使用的应用的文件夹
• ❌ 保留：活动应用数据

类别 3：大文件和重复项

分析脚本：

```bash

scripts/analyze_large_files.py --threshold 100MB --path ~

```

查找重复项（可选，资源密集型）：

```bash

# 如果安装了 fdupes 则使用

if command -v fdupes &> /dev/null; then

fdupes -r ~/Documents ~/Downloads

fi

```

呈现发现：

```

📦 大文件（>100MB）：

━━━━━━━━━━━━━━━━━━━━━━━━

1. movie.mp4 4.2 GB ~/Downloads
2. dataset.csv 1.8 GB ~/Documents/data
3. old_backup.zip 1.5 GB ~/Desktop

...

🔁 重复文件：

• screenshot.png（3 个副本） 每个 15 MB
• document_v1.docx（2 个副本） 每个 8 MB

```

安全级别：🟡 需要用户判断

类别 4：开发环境清理

目标：

• Docker：镜像、容器、卷、构建缓存
• Homebrew：缓存、旧版本
• Node.js：node_modules、npm 缓存
• Python：pip 缓存、__pycache__、venv
• Git：存档项目中的 .git 文件夹

分析脚本：

```bash

scripts/analyze_dev_env.py

```

示例发现：

```

🐳 Docker 资源：

• 未使用的镜像： 12 GB
• 已停止的容器： 2 GB
• 构建缓存： 8 GB
• 孤立的卷： 3 GB

总潜在： 25 GB

📦 包管理器：

• Homebrew 缓存： 5 GB
• npm 缓存： 3 GB
• pip 缓存： 1 GB

总潜在： 9 GB

🗂️ 旧项目：

• archived-project-2022/.git 500 MB
• old-prototype/.git 300 MB

```

清理命令（需要确认）：

```bash

# Homebrew 清理（安全）

brew cleanup -s

# npm _npx 仅限（安全 - 临时包）

rm -rf ~/.npm/_npx

# pip 缓存（谨慎使用）

pip cache purge

```

Docker 清理 - 需要特殊处理：

⚠️ 绝不使用这些命令：

```bash

# ❌ 危险 - 无确认删除所有卷

docker volume prune -f

docker system prune -a --volumes

```

✅ 正确方法 - 逐卷确认：

```bash

# 1. 列出所有卷

docker volume ls

# 2. 确定每个卷属于哪个项目

docker volume inspect

# 3. 要求用户确认要删除的每个项目

# 示例："您想删除 'ragflow' 项目的所有卷吗？"

# 4. 仅在确认后删除特定卷

docker volume rm ragflow_mysql_data ragflow_redis_data

```

安全级别：🟢 Homebrew/npm 清理，🔴 Docker 卷需要按项目确认

Mole（https://github.com/tw93/Mole）是一个用于全面 macOS 清理的命令行界面（CLI）工具。它为缓存、日志、开发工具等提供基于交互式终端的分析和清理。

关键要求：

1. TTY 环境：Mole 需要 TTY 进行交互式命令。从 Claude Code 或脚本运行时使用 tmux。
2. 版本检查：使用前始终验证 Mole 是最新的。
3. 安全的帮助命令：只有 mo --help 是安全的。不要在其他命令后附加 --help。

安装检查和升级：

```bash

# 检查是否安装并获取版本

which mo && mo --version

# 如果未安装

brew install tw93/tap/mole

# 检查更新

brew info tw93/tap/mole | head -5

# 如果需要则升级

brew upgrade tw93/tap/mole

```

使用 tmux 与 Mole 一起使用（Claude Code 必需）：

```bash

# 创建 tmux 会话以获得 TTY 环境

tmux new-session -d -s mole -x 120 -y 40

# 运行分析（安全，只读）

tmux send-keys -t mole 'mo analyze' Enter

# 等待扫描（耐心 - 大目录可能需要 5-10 分钟）

sleep 60

# 捕获结果

tmux capture-pane -t mole -p

# 完成后清理

tmux kill-session -t mole

```

可用命令（来自 mo --help）：

| 命令 | 安全性 | 说明 |

|---------|--------|-------------|

| mo --help | ✅ 安全 | 查看所有命令（唯一安全的帮助） |

| mo analyze | ✅ 安全 | 磁盘使用浏览器（只读） |

| mo status | ✅ 安全 | 系统健康监控 |

| mo clean --dry-run | ✅ 安全 | 预览清理（无删除） |

| mo clean | ⚠️ 危险 | 实际删除文件 |

| mo purge | ⚠️ 危险 | 删除项目工件 |

| mo uninstall | ⚠️ 危险 | 删除应用程序 |

参考指南：

详见 references/mole_integration.md 获取详细的 tmux 工作流程和故障排除。

关键：为了全面分析，您必须执行多层探索，而不仅仅是顶层扫描。本节记录了导航 Mole TUI 的经过验证的工作流程。

导航命令

```bash

# 创建会话

tmux new-session -d -s mole -x 120 -y 40

# 开始分析

tmux send-keys -t mole 'mo analyze' Enter

# 等待初始扫描

sleep 8 && tmux capture-pane -t mole -p

# 导航键（通过 tmux 发送）

tmux send-keys -t mole Enter # 进入/展开选定目录

tmux send-keys -t mole Left # 返回父目录

tmux send-keys -t mole Down # 移动到下一项

tmux send-keys -t mole Up # 移动到上一项

tmux send-keys -t mole 'q' # 退出 TUI

# 捕获当前视图

tmux capture-pane -t mole -p

```

多层探索工作流程

步骤 1：顶层概览

```bash

# 启动 mo analyze，等待初始菜单

tmux send-keys -t mole 'mo analyze' Enter

sleep 8 && tmux capture-pane -t mole -p

# 示例输出：

# 1. 主目录 289.4 GB (58.5%)

# 2. 应用库 145.2 GB (29.4%)

# 3. 应用程序 49.5 GB (10.0%)

# 4. 系统库 10.3 GB (2.1%)

```

步骤 2：进入最大目录（主目录）

```bash

tmux send-keys -t mole Enter

sleep 10 && tmux capture-pane -t mole -p

# 示例输出：

# 1. 库 144.4 GB (49.9%)

# 2. 工作区 52.0 GB (18.0%)

# 3. .cache 19.3 GB (6.7%)

# 4. 应用程序 17.0 GB (5.9%)

# ...

```

步骤 3：深入特定目录

```bash

# 进入 .cache（第 3 项：Down Down Enter）

tmux send-keys -t mole Down Down Enter

sleep 5 && tmux capture-pane -t mole -p

# 示例输出：

# 1. uv 10.3 GB (55.6%)

# 2. modelscope 5.5 GB (29.5%)

# 3. huggingface 887.8 MB (4.7%)

```

步骤 4：返回并探索另一个分支

```bash

# 返回父目录

tmux send-keys -t mole Left

sleep 2

# 导航到不同目录

tmux send-keys -t mole Down Down Down Down Enter # 进入 .npm

sleep 5 && tmux capture-pane -t mole -p

```

步骤 5：深入库

```bash

# 返回主目录，然后进入库

tmux send-keys -t mole Left

tmux send-keys -t mole Up Up Up Up Up Up Enter # 进入库

sleep 10 && tmux capture-pane -t mole -p

# 示例输出：

# 1. 应用支持 37.1 GB

# 2. 容器 35.4 GB

# 3. 开发者 17.8 GB ← Xcode 在这里

# 4. 缓存 8.2 GB

```

推荐的探索路径

为了全面分析，请遵循此探索树：

```

mo analyze

├── 主目录（进入）

│ ├── 库（进入）

│ │ ├── 开发者（进入） → Xcode/DerivedData、iOS DeviceSupport

│ │ ├── 缓存（进入） → Playwright、JetBrains 等

│ │ └── 应用支持（进入） → 应用数据

│ ├── .cache（进入） → uv、modelscope、huggingface

│ ├── .npm（进入） → _cacache、_npx

│ ├── 下载（进入） → 待审查的大文件

│ ├── .Trash（进入） → 确认废纸篓内容

│ └── miniconda3/其他开发工具（进入） → 检查最后使用时间

├── 应用库 → 通常与 ~/Library 重叠

└── 应用程序 → 已安装的应用

```

时间预期

| 目录 | 扫描时间 | 说明 |

|-----------|-----------|-------|

| 顶层菜单 | 5-8 秒 | 快速 |

| 主目录 | 5-10 分钟 | 大型，请耐心 |

| ~/Library | 3-5 分钟 | 许多小文件 |

| 子目录 | 2-30 秒 | 根据大小变化 |

完整会话示例

```bash

# 1. 创建会话

tmux new-session -d -s mole -x 120 -y 40

# 2. 开始分析并获取概览

tmux send-keys -t mole 'mo analyze' Enter

sleep 8 && tmux capture-pane -t mole -p

# 3. 进入主目录

tmux send-keys -t mole Enter

sleep 10 && tmux capture-pane -t mole -p

# 4. 进入 .cache 查看开发缓存

tmux send-keys -t mole Down Down Enter

sleep 5 && tmux capture-pane -t mole -p

# 5. 返回主目录，然后到 .npm

tmux send-keys -t mole Left

sleep 2

tmux send-keys -t mole Down Down Down Down Enter

sleep 5 && tmux capture-pane -t mole -p

# 6. 返回主目录，进入库

tmux send-keys -t mole Left

sleep 2

tmux send-keys -t mole Up Up Up Up Up Up Enter

sleep 10 && tmux capture-pane -t mole -p

# 7. 进入开发者查看 Xcode

tmux send-keys -t mole Down Down Down Enter

sleep 5 && tmux capture-pane -t mole -p

# 8. 进入 Xcode

tmux send-keys -t mole Enter

sleep 5 && tmux capture-pane -t mole -p

# 9. 进入 DerivedData 查看项目

tmux send-keys -t mole Enter

sleep 5 && tmux capture-pane -t mole -p

# 10. 清理

tmux kill-session -t mole

```

探索的关键见解

经过多层探索后，您将发现：

1. 哪些项目正在使用 DerivedData - 具体项目名称
2. 哪些缓存实际上很大 - uv vs npm vs 其他
3. 文件年龄 - Mole 显示">3mo"、">7mo"、">1yr"标记
4. 特定卷及其用途 - Docker 项目数据
5. 可以清理的下载 - 旧的 dmgs、重复文件

关键：以下项目通常建议清理，但在大多数情况下不应删除。它们提供的显著价值超过了它们占用的空间。

要保留的项目（反模式）

| 项目 | 大小 | 为什么不删除 | 删除的实际影响 |

|------|------|-------------------|------------------------|

| Xcode DerivedData | 10+ GB | 构建缓存每次完整重新构建节省 10-30 分钟 | 下次构建需要额外 10-30 分钟 |

| npm _cacache | 5+ GB | 下载的包在本地缓存 | npm install 重新下载所有内容（中国 30分钟-2小时） |

| ~/.cache/uv | 10+ GB | Python 包缓存 | 每个 Python 项目从 PyPI 重新安装依赖 |

| Playwright 浏览器 | 3-4 GB | 自动化测试的浏览器二进制文件 | 每次重新下载 2GB+（30分钟-1小时） |

| iOS DeviceSupport | 2-3 GB | 设备调试所需 | 连接设备时从 Apple 重新下载 |

| Docker 已停止的容器 | <500 MB | 可能随时使用 docker start 重新启动 | 丢失容器状态，需要重新创建 |

| ~/.cache/huggingface | 变化 | AI 模型缓存 | 重新下载大模型（数小时） |

| ~/.cache/modelscope | 变化 | AI 模型缓存（中国） | 同上 |

| JetBrains 缓存 | 1+ GB | IDE 索引和缓存 | IDE 需要 5-10 分钟重新索引 |

为什么这很重要

虚荣陷阱：显示"清理了 50GB！"感觉很爽，但：

• 用户接下来花费 2 小时重新下载 npm 包
• 下次 Xcode 构建需要 30 分钟而不是 30 秒
• AI 项目失败因为模型需要重新下载

正确心态："我发现了 50GB 缓存。以下是为什么其中大部分实际上有价值应该保留..."

什么实际上可以安全删除

| 项目 | 为什么安全 | 影响 |

|------|----------|--------|

| 废纸篓 | 用户已删除这些文件 | 无 - 用户的决定 |

| Homebrew 旧版本 | 被新版本替换 | 罕见：无法回滚到旧版本 |

| npm _npx | 临时 npx 执行 | 轻微：npx 下次使用时重新下载 |

| 孤立应用残留 | 应用已卸载 | 无 - 应用不存在 |

| 特定未使用的 Docker 卷 | 项目确认已放弃 | 无 - 如果真的已放弃 |

每个清理报告必须遵循此格式并包含影响分析：

```markdown

分类图例

| 符号 | 含义 |

|--------|---------|

| 🟢 | 绝对安全 - 无负面影响，真正未使用 |

| 🟡 | 需要权衡 - 有用缓存，删除有成本 |

| 🔴 | 不要删除 - 包含有价值的数据或正在使用 |

发现

| 项目 | 大小 | 分类 | 是什么 | 删除后影响 |

|------|------|----------------|------------|-------------------|

| 废纸篓 | 643 MB | 🟢 | 您删除的文件 | 无 |

| npm _npx | 2.1 GB | 🟢 | 临时 npx 包 | 轻微重新下载 |

| npm _cacache | 5 GB | 🟡 | 包缓存 | 30分钟-2小时重新下载 |

| DerivedData | 10 GB | 🟡 | Xcode 构建缓存 | 10-30分钟重新构建 |

| Docker 卷 | 11 GB | 🔴 | 项目数据库 | 数据丢失 |

建议

仅标记为 🟢 的项目建议清理。

标记为 🟡 的项目需要您根据使用模式进行判断。

标记为 🔴 的项目需要每项明确确认。

```

经过多层探索后，使用此经过验证的模板呈现发现：

```markdown

分析日期：YYYY-MM-DD

使用工具：Mole CLI + 多层目录探索

分析原则：安全第一，价值优于虚荣

---

总览

| 区域 | 总占用 | 关键发现 |

|------|--------|----------|

| 主目录 | XXX GB | 库占一半(XXX GB) |

| 应用库 | XXX GB | 与主目录/库重叠统计 |

| 应用程序 | XXX GB | 应用本体 |

---

🟢 绝对安全可删除（约 X.X GB）

| 项目 | 大小 | 位置 | 删除后影响 | 清理命令 |

|------|------|------|-----------|---------|

| 废纸篓 | XXX MB | ~/.Trash | 无 - 您已决定删除的文件 | 清空废纸篓 |

| npm _npx | X.X GB | ~/.npm/_npx | 下次 npx 命令重新下载 | rm -rf ~/.npm/_npx |

| Homebrew 旧版本 | XX MB | /opt/homebrew | 无 - 已被新版本替代 | brew cleanup --prune=0 |

废纸篓内容预览：

• [列出主要文件]

---

🟡 需要您确认的项目

#### 1. [项目名] (X.X GB) - [状态描述]

| 子目录 | 大小 | 最后使用 |

|--------|------|----------|

| [子目录1] | X.X GB | >X个月 |

| [子目录2] | X.X GB | >X个月 |

问题：[需要用户回答的问题]

---

#### 2. Downloads 中的旧文件 (X.X GB)

| 文件/目录 | 大小 | 年龄 | 建议 |

|-----------|------|------|------|

| [文件1] | X.X GB | - | [建议] |

| [文件2] | XXX MB | >X个月 | [建议] |

建议：手动检查 Downloads，删除已不需要的文件。

---

#### 3. 停用的 Docker 项目 Volumes

| 项目前缀 | 可能包含的数据 | 需要您确认 |

|---------|--------------|-----------|

| project1_* | MySQL、Redis | 还在用吗？ |

| project2_* | Postgres | 还在用吗？ |

注意：我不会使用 docker volume prune -f，只会在您确认后删除特定项目的 volumes。

---

🔴 不建议删除的项目（有价值的缓存）

| 项目 | 大小 | 为什么要保留 |

|------|------|-------------|

| Xcode DerivedData | XX GB | [项目名]的编译缓存，删除后下次构建需要X分钟 |

| npm _cacache | X.X GB | 所有下载过的 npm 包，删除后需要重新下载 |

| ~/.cache/uv | XX GB | Python 包缓存，重新下载在中国网络下很慢 |

| [其他有价值的缓存] | X.X GB | [保留原因] |

---

📋 其他发现

| 项目 | 大小 | 说明 |

|------|------|------|

| OrbStack/Docker | XX GB | 正常的 VM/容器占用 |

| [其他发现] | X.X GB | [说明] |

---

推荐操作

立即可执行（无需确认）：

```bash

# 1. 清空废纸篓 (XXX MB)

# 手动：Finder → 清空废纸篓

# 2. npm _npx (X.X GB)

rm -rf ~/.npm/_npx

# 3. Homebrew 旧版本 (XX MB)

brew cleanup --prune=0

```

预计释放：~X.X GB

---

需要您确认后执行：

1. [项目1] - [确认问题]
2. [项目2] - [确认问题]
3. Docker 项目 - 告诉我哪些项目确定不用了

```

报告质量检查清单

在呈现报告之前，验证：

• [ ] 每个项目都有"删除后影响"说明
• [ ] 🟢 项目真正安全（废纸篓、_npx、旧版本）
• [ ] 🟡 项目需要用户决定（年龄信息、使用模式）
• [ ] 🔴 项目解释为什么要保留
• [ ] Docker 卷按项目列出，而不是全面清理
• [ ] 考虑网络环境（中国 = 重新下载慢）
• [ ] 没有建议删除有用的缓存只是为了夸大数字
• [ ] 清晰的操作项和确切的命令

将发现格式化为具有风险级别的可执行建议：

```markdown

# macOS 清理建议

总可恢复空间：~XX GB

当前使用率：XX%

🟢 可以安全执行（低风险）

这些可以安全删除，将根据需要重新生成：

1. 清空废纸篓（~12 GB）

- 位置：~/.Trash

- 命令：rm -rf ~/.Trash/*

1. 清除系统缓存（~45 GB）

- 位置：~/Library/Caches

- 命令：rm -rf ~/Library/Caches/*

- 注意：应用下次启动可能会稍微慢一些

1. 删除 Homebrew 缓存（~5 GB）

- 命令：brew cleanup -s

🟡 建议审查（中等风险）

删除前审查这些项目：

1. 大文件下载（~38 GB）

- 位置：~/Downloads

- 操作：手动审查并删除不需要的文件

- 文件：[列出前 10 个最大文件]

1. 应用残留（~8 GB）

- 应用：[列出检测到的已卸载应用]

- 位置：[列出路径]

- 操作：在删除数据前确认应用真的已卸载

🔴 除非确定否则保留（高风险）

仅在您知道自己在做什么时才删除：

1. Docker 卷（~3 GB）

- 可能包含重要数据

- 使用以下命令审查：docker volume ls

1. Time Machine 本地快照（~XX GB）

- 自动备份，需要空间时将删除

- 检查命令：tmutil listlocalsnapshots /

```

关键：没有明确的用户确认绝不执行删除操作。

交互式确认流程：

```python

# 来自 scripts/safe_delete.py 的示例

def confirm_delete(path: str, size: str, description: str) -> bool:

"""

请求用户确认删除。

参数：

path：文件/目录路径

size：人类可读的大小

description：此文件/目录是什么

返回：

如果用户确认则为 True，否则为 False

"""

print(f"\n🗑️ 确认删除")

print(f"━━━━━━━━━━━━━━━━━━")

print(f"路径： {path}")

print(f"大小： {size}")

print(f"说明：{description}")

response = input("\n删除此项目？[y/N]：").strip().lower()

return response == 'y'

```

对于批量操作：

```python

def batch_confirm(items: list) -> list:

"""

显示所有项目，请求批量确认。

返回用户批准的项目列表。

"""

print("\n📋 要删除的项目：")

print("━━━━━━━━━━━━━━━━━━")

for i, item in enumerate(items, 1):

print(f"{i}. {item['path']} ({item['size']})")

print("\n选项：")

print(" 'all' - 删除所有项目")

print(" '1,3,5' - 按编号删除特定项目")

print(" 'none' - 取消")

response = input("\n您的选择：").strip().lower()

if response == 'none':

return []

elif response == 'all':

return items

else:

# 解析数字

indices = [int(x.strip()) - 1 for x in response.split(',')]

return [items[i] for i in indices if 0 <= i < len(items)]

```

清理后，验证结果并报告：

```bash

# 比较之前/之后

df -h /

# 计算恢复的空间

#（由 scripts/cleanup_report.py 处理）

```

报告格式：

```

✅ 清理完成！

之前：已使用 450 GB（90%）

之后： 已使用 385 GB（77%）

━━━━━━━━━━━━━━━━━━━━━━━━

已恢复：65 GB

细分：

• 系统缓存： 45 GB
• 下载： 12 GB
• Homebrew 缓存： 5 GB
• 应用残留： 3 GB

⚠️ 注意：

• 某些应用首次启动可能需要更长时间
• 除非您有 Time Machine 备份，否则无法恢复已删除的项目
• 建议每月运行此清理一次

💡 维护提示：

• 设置自动 Homebrew 清理：每周 brew cleanup
• 每月审查 Downloads 文件夹
• 在 Finder 偏好设置中启用"自动清空废纸篓"

```

始终保留

没有明确的用户指示绝不删除这些：

• ~/Documents、~/Desktop、~/Pictures 内容
• 活动项目目录
• 数据库文件（.db、.sqlite）
• 活动应用的配置文件
• SSH 密钥、凭据、证书
• Time Machine 备份

需要 Sudo 确认

这些操作需要提升的权限。要求用户手动运行命令：

• 清除 /Library/Caches（系统范围）
• 清除 /var/log（系统日志）
• 清除 /private/var/folders（系统临时）

示例提示：

```

⚠️ 此操作需要管理员权限。

请手动运行此命令：

sudo rm -rf /Library/Caches/*

⚠️ 您将被要求输入密码。

```

备份建议

在执行任何 >10GB 的清理之前，建议：

```

💡 安全提示：

在清理 XX GB 之前，考虑创建 Time Machine 备份。

快速备份检查：

tmutil latestbackup

如果没有最近备份，运行：

tmutil startbackup

```

"Operation not permitted"错误

macOS 可能由于 SIP（系统完整性保护）而阻止删除某些系统文件。

解决方案：不要强制操作。这些保护是为了安全而存在的。

缓存删除后应用崩溃

罕见但可能。解决方案：重新启动应用，它将重新生成必要的缓存。

Docker 清理删除重要数据

预防：清理前始终列出 Docker 卷：

```bash

docker volume ls

docker volume inspect

```

scripts/

• analyze_caches.py - 扫描和分类缓存目录
• find_app_remnants.py - 检测孤立的应用数据
• analyze_large_files.py - 使用智能过滤查找大文件
• analyze_dev_env.py - 扫描开发环境资源
• safe_delete.py - 带确认的交互式删除
• cleanup_report.py - 生成之前/之后报告

references/

• cleanup_targets.md - 每个清理目标的详细说明
• mole_integration.md - 如何与此技能一起使用 Mole
• safety_rules.md - 绝不删除的内容的综合列表

示例 1：快速缓存清理

用户请求："我的 Mac 空间不足，你能帮助吗？"

工作流程：

1. 运行快速诊断
2. 将系统缓存识别为快速胜利
3. 呈现发现："~/Library/Caches 中有 45 GB"
4. 解释："这些可以安全删除，应用会重新生成它们"
5. 请求确认
6. 执行：rm -rf ~/Library/Caches/*
7. 报告："已恢复 45 GB"

示例 2：开发环境清理

用户请求："我是开发人员，我的磁盘满了"

工作流程：

1. 运行 scripts/analyze_dev_env.py
2. 呈现 Docker + npm + Homebrew 发现
3. 解释每个类别
4. 提供清理命令和说明
5. 让用户执行（不要自动执行 Docker 清理）
6. 验证结果

示例 3：查找大文件

用户请求："什么占用了这么多空间？"

工作流程：

1. 运行 scripts/analyze_large_files.py --threshold 100MB
2. 呈现前 20 个大文件及其上下文
3. 分类：视频、数据集、档案、磁盘映像
4. 让用户决定删除什么
5. 执行已确认的删除
6. 建议存档到外部驱动器

1. 从保守开始：从明显安全的目标（缓存、废纸篓）开始
2. 解释一切：用户应该了解他们正在删除的内容
3. 显示示例：列出每个类别的 3-5 个示例文件
4. 尊重用户节奏：不要匆忙进行确认
5. 记录结果：始终显示之前/之后的磁盘使用情况
6. 教育：在最终报告中包含维护提示
7. 集成工具：为更喜欢 GUI 的用户建议 Mole

• 用户想要自动/静默清理（违反安全第一原则）
• 用户需要 Windows/Linux 清理（macOS 特定技能）
• 用户磁盘使用率 <10%（无需清理）
• 用户想要清理需要禁用 SIP 的系统文件（安全风险）

在这些情况下，解释局限性并建议替代方案。