mac-cleanup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

macOS Cleanup

macOS 清理

An interactive, discovery-based macOS cleanup skill. Works on any Mac dev machine — detects installed tools, package managers, browsers, and dev directories rather than assuming a fixed setup.

一款基于主动检测的交互式macOS清理技能。适用于所有Mac开发机器——会检测已安装的工具、包管理器、浏览器和开发目录，而非预设固定环境。

Safety Rules

安全规则

These rules are non-negotiable. Follow them at all times:

Never delete without approval. Always show what will be deleted, its size, and get explicit user confirmation before executing any destructive command.

Never
rm -rf
app bundles. Use Finder via osascript to move apps to Trash:

osascript -e 'tell application "Finder" to delete POSIX file "/Applications/App.app"'

Never clear browser profile data (cookies, history, passwords in ~/Library/Application Support/). OS-level browser caches in ~/Library/Caches/ are safe to remove like any app cache.
Honor protected paths. Ask the user for any paths that should be skipped, and never touch them.
Never touch
.git
directories. Only clean merged branches (via
```
git branch -d
```
), never remove
```
.git
```
itself.
Never touch system directories.
```
/System
```
,
```
/Library
```
(root level),
```
/usr
```
,
```
/bin
```
,
```
/sbin
```
are off-limits.
Never use
sudo
unless the user explicitly asks for elevated privileges and understands why.
Keep a running tally. Track and display cumulative space freed after each action.
Default stale threshold: 90 days. Dev artifacts not modified in 90+ days are flagged as stale. The user can override this.
Confirm before bulk operations. Never run commands like
```
rm -rf ~/Downloads/*
```
without showing item count and total size.

这些规则不可协商，必须始终遵守：

未经批准绝不删除：在执行任何破坏性命令前，必须展示待删除内容、占用空间，并获得用户明确确认。

绝不使用
rm -rf
删除应用包：通过osascript调用Finder将应用移至废纸篓：

osascript -e 'tell application "Finder" to delete POSIX file "/Applications/App.app"'

绝不清理浏览器配置文件数据（~/Library/Application Support/中的Cookie、历史记录、密码等）。 ~/Library/Caches/中的系统级浏览器缓存可像其他应用缓存一样安全移除。
尊重受保护路径：询问用户是否有需要跳过的路径，且绝不触碰这些路径。
绝不触碰
.git
目录：仅清理已合并分支（通过
```
git branch -d
```
），绝不删除
```
.git
```
本身。
绝不触碰系统目录：
```
/System
```
、根目录下的
```
/Library
```
、
```
/usr
```
、
```
/bin
```
、
```
/sbin
```
均为禁区。
绝不默认使用
sudo
：除非用户明确要求提升权限并理解原因。
持续统计空间：每次操作后跟踪并显示累计释放的空间。
默认过期阈值：90天：超过90天未修改的开发产物将被标记为过期，用户可自定义该阈值。
批量操作前需确认：在执行
```
rm -rf ~/Downloads/*
```
这类命令前，必须展示项目数量和总占用空间，获得用户同意。

Workflow

工作流程

1. Discover & Configure

1. 检测与配置

Before scanning, gather context about the system:

Run
```
uname -m
```
to detect architecture (Apple Silicon vs Intel — determines Homebrew prefix)
Detect the Homebrew prefix:
```
/opt/homebrew
```
(Apple Silicon) or
```
/usr/local
```
(Intel)

Check which package managers are installed:

which brew npm pnpm yarn bun uv pip3 cargo go pyenv

Scan
```
/Applications/
```
for installed browsers

Identify dev directories — check common locations:

~/developer

~/Developer

~/dev

~/projects

~/Projects

~/src

~/code

~/workspace

~/repos

Ask the user:
- Are there additional dev directories to scan?
- Should the stale threshold be something other than 90 days?

Note: The scan script's tool detection (

shutil.which()

) is authoritative — it may find tools that the shell's

which

misses due to PATH differences.

扫描前，先收集系统上下文信息：

运行
```
uname -m
```
检测架构（Apple Silicon vs Intel——决定Homebrew路径前缀）
检测Homebrew前缀：Apple Silicon为
```
/opt/homebrew
```
，Intel为
```
/usr/local
```

检查已安装的包管理器：

which brew npm pnpm yarn bun uv pip3 cargo go pyenv

扫描
```
/Applications/
```
目录查找已安装浏览器

识别开发目录——检查常见位置：

~/developer

~/Developer

~/dev

~/projects

~/Projects

~/src

~/code

~/workspace

~/repos

询问用户：
- 是否有额外的开发目录需要扫描？
- 是否需要修改过期阈值（默认90天）？

注意：扫描脚本的工具检测（

shutil.which()

）是权威的——它可能发现因PATH差异导致shell的

which

命令无法找到的工具。

2. Scan

2. 扫描

Run the scan script with the discovered configuration:

bash

uv run .agents/skills/mac-cleanup/scripts/scan.py \
  --dev-dirs <discovered_dirs> \
  --stale-days <threshold> \
  --skip <protected_paths>

uv

is not available, fall back to

python3

The script runs all checks in parallel and outputs a JSON report to stdout. Read the full JSON output to understand what's on the system.

If the scan script is unavailable or fails, fall back to manual commands:

```
df -h /
```
— overall disk usage

du -sh ~/Library/Caches ~/Library/Logs ~/.cache ~/.npm ~/.Trash ~/Downloads

— quick size survey

Check package manager caches individually (see
```
references/cleanup-catalog.md
```
)

使用检测到的配置运行扫描脚本：

bash

uv run .agents/skills/mac-cleanup/scripts/scan.py \
  --dev-dirs <discovered_dirs> \
  --stale-days <threshold> \
  --skip <protected_paths>

若

uv

不可用， fallback至

python3

。

脚本会并行运行所有检查，并将JSON报告输出至标准输出。读取完整的JSON输出以了解系统状态。

若扫描脚本不可用或运行失败， fallback至手动命令：

```
df -h /
```
—— 整体磁盘使用情况

du -sh ~/Library/Caches ~/Library/Logs ~/.cache ~/.npm ~/.Trash ~/Downloads

—— 快速空间统计

单独检查包管理器缓存（参见
```
references/cleanup-catalog.md
```
）

3. Present Findings

3. 展示检测结果

Show the user a summary table grouped by category. Include:

Category	Item	Size	Risk	Status
Package caches	Homebrew	3.2 GB	safe	12 stale items
System caches	~/Library/Caches	8.1 GB	moderate	Top: Xcode (4 GB)
Dev artifacts	node_modules (5 stale)	2.3 GB	safe	>90 days old
Docker	Images + containers	15 GB	moderate	8 unused images
Trash	~/.Trash	1.2 GB	moderate
Downloads	~/Downloads	4.5 GB	high	127 items

Sort by size (largest first). Flag risk levels:

safe — always reclaimable, rebuilds automatically
moderate — reclaimable but may need re-download or rebuild time
high — potential data loss, needs careful review

向用户展示按类别分组的汇总表格，包含以下列：

类别	项目	大小	风险	状态
包管理器缓存	Homebrew	3.2 GB	安全	12项过期内容
系统缓存	~/Library/Caches	8.1 GB	中等	占用最大：Xcode（4 GB）
开发产物	node_modules（5项过期）	2.3 GB	安全	超过90天未修改
Docker	镜像 + 容器	15 GB	中等	8个未使用镜像
废纸篓	~/.Trash	1.2 GB	中等
下载目录	~/Downloads	4.5 GB	高	127个项目

按大小排序（从大到小），标记风险等级：

安全 —— 可随时回收，会自动重建
中等 —— 可回收，但可能需要重新下载或重建时间
高 —— 存在数据丢失风险，需仔细检查

4. Clean Up Interactively

4. 交互式清理

Before starting, ask the user if there are paths that should be protected/skipped during cleanup.

Walk through categories from safest to riskiest. For each:

Show exactly what will be deleted and its size
Show the command that will run
Get user approval
Execute the command
Report space freed

Consult

references/cleanup-catalog.md

for the correct detection, cleanup command, and dry-run command for each category.

Order of operations (safest first):

Package manager caches (brew, npm, pnpm, yarn, bun, uv, pip, cargo, go)
System logs (
```
~/Library/Logs
```
)
Stale dev artifacts (node_modules, .venv, build dirs older than threshold)
Python bytecode caches (
```
__pycache__
```
,
```
.pytest_cache
```
, etc.)
Merged git branches
System caches (
```
~/Library/Caches
```
— per-subdirectory, with breakdown)
Docker (show
```
docker system df
```
, ask about aggressiveness level)
Homebrew — unused formulae/casks (list installed as a table with
```
| App | Size | Description |
```
using
```
brew info --json
```
for descriptions and sizes, ask which are unused)
Trash
Downloads (show largest files, never bulk-delete without review)
Application uninstall (if user wants — quit first, use Finder, clean support files)

App uninstall procedure:

Get bundle ID:

mdls -name kMDItemCFBundleIdentifier /Applications/AppName.app

Quit the app if running

Move to Trash via Finder:

osascript -e 'tell application "Finder" to delete POSIX file "/Applications/AppName.app"'

Clean support files in these locations (use the bundle ID):

```
~/Library/Application Support/<AppName>
```
```
~/Library/Caches/<bundleid>
```
```
~/Library/Preferences/<bundleid>.plist
```
```
~/Library/HTTPStorages/<bundleid>
```
```
~/Library/Logs/<AppName>
```
```
~/Library/Containers/<bundleid>
```
```
~/Library/Group Containers/<bundleid>
```

~/Library/Saved Application State/<bundleid>.savedState

```
~/Library/WebKit/<bundleid>
```

开始前，询问用户是否有需要在清理过程中保护/跳过的路径。

从最安全到风险最高的类别依次处理。每个类别需执行以下步骤：

展示待删除的具体内容及占用空间
展示将要运行的命令
获取用户批准
执行命令
报告释放的空间

参考

references/cleanup-catalog.md

获取每个类别的正确检测方式、清理命令和试运行命令。

操作顺序（从最安全到最危险）：

包管理器缓存（brew, npm, pnpm, yarn, bun, uv, pip, cargo, go）
系统日志（
```
~/Library/Logs
```
）
过期开发产物（node_modules, .venv,超过阈值的构建目录）
Python字节码缓存（
```
__pycache__
```
,
```
.pytest_cache
```
等）
已合并的Git分支
系统缓存（
```
~/Library/Caches
```
——按子目录拆分展示）
Docker（展示
```
docker system df
```
，询问清理强度）
Homebrew——未使用的公式/应用（使用
```
brew info --json
```
获取描述和大小，以表格
```
| 应用 | 大小 | 描述 |
```
列出已安装内容，询问哪些是未使用的）
废纸篓
下载目录（展示最大文件，绝不未经检查批量删除）
应用卸载（若用户需要——先退出应用，使用Finder，清理支持文件）

应用卸载流程：

获取包ID：

mdls -name kMDItemCFBundleIdentifier /Applications/AppName.app

若应用正在运行则退出

通过Finder移至废纸篓：

osascript -e 'tell application "Finder" to delete POSIX file "/Applications/AppName.app"'

清理以下位置的支持文件（使用包ID）：

```
~/Library/Application Support/<AppName>
```
```
~/Library/Caches/<bundleid>
```
```
~/Library/Preferences/<bundleid>.plist
```
```
~/Library/HTTPStorages/<bundleid>
```
```
~/Library/Logs/<AppName>
```
```
~/Library/Containers/<bundleid>
```
```
~/Library/Group Containers/<bundleid>
```

~/Library/Saved Application State/<bundleid>.savedState

```
~/Library/WebKit/<bundleid>
```

5. Report

5. 报告

After all cleanup actions are complete, show:

Before/after disk comparison: free space before vs after
Actions taken: list every action with space freed
Total space freed: cumulative sum
Declined items: what was skipped and why, with suggestions for future cleanup
Maintenance tips: suggest scheduling periodic cleanup for categories that grow back

所有清理操作完成后，展示以下内容：

清理前后磁盘对比：清理前与清理后的可用空间
执行的操作：列出每一项操作及释放的空间
总释放空间：累计释放的空间总和
未执行的项目：跳过的内容及原因，同时提供未来清理建议
维护建议：建议定期清理会持续增长的类别

Edge Cases

边缘情况

Docker not running: Docker images/containers can use 10+ GB. Ask the user: "Docker is installed but not running. Want to start Docker Desktop to check for reclaimable space?" If yes:
```
open -a Docker
```
, wait for daemon readiness (poll
```
docker info
```
up to 30s). If no: flag prominently in report: "Docker skipped (not running) — restart and re-run to check."
No dev directories found: Skip dev artifact scan. Ask the user if they have dev work in a non-standard location.
Intel Mac: Use
```
/usr/local
```
for Homebrew prefix. All other commands work the same.
Command failures: Log the error, skip that category, continue with the rest. Report all errors at the end.
Nothing to clean: Report that the system is already in good shape. Show current disk usage.
Scan script missing: Fall back to manual
```
du
```
/
```
df
```
commands as described in Step 2.
Large ML caches:
```
~/.cache/huggingface
```
or similar can be huge. Flag these specifically and warn about re-download costs.

Docker未运行：Docker镜像/容器可能占用10GB以上空间。询问用户： "Docker已安装但未运行。是否启动Docker Desktop以检查可回收空间？" 若同意：
```
open -a Docker
```
，等待守护进程就绪（轮询
```
docker info
```
最多30秒）。若拒绝：在报告中显著标记："Docker已跳过（未运行）——重启后重新运行可检查空间。"
未找到开发目录：跳过开发产物扫描。询问用户是否在非标准位置存放开发工作内容。
Intel Mac：Homebrew前缀使用
```
/usr/local
```
。其他命令操作一致。
命令执行失败：记录错误，跳过该类别，继续处理其余内容。在报告末尾列出所有错误。
无内容可清理：报告系统状态良好，展示当前磁盘使用情况。
扫描脚本缺失：fallback至步骤2中描述的手动
```
du
```
/
```
df
```
命令。
大型ML缓存：
```
~/.cache/huggingface
```
或类似目录可能占用大量空间。需特别标记并提醒重新下载的成本。

Anti-Patterns

反模式

Do NOT do any of the following:

rm -rf /
or any variation targeting the root filesystem
Delete
.git
directories — only clean merged branches
Use
sudo
by default — only when the user explicitly requests it and for a specific reason
Bulk-delete
~/Library/Application Support
— this contains critical app data. Only remove entries for apps the user has confirmed they uninstalled.
Run recursive finds on huge system directories like
```
~/Library/Application Support
```
or
```
~/Library/Containers
```
— these can be enormous and slow. Only check specific subdirectories.
Delete Xcode derived data without warning — it can be very large but takes time to rebuild. Always flag the size and rebuild cost.
Clear browser caches programmatically — this can corrupt browser state. Always direct users to browser settings.
Force-prune Docker volumes — these may contain database data. Always show volume names and get explicit approval.

禁止执行以下操作：

rm -rf /
或任何针对根文件系统的变体命令
删除
.git
目录 —— 仅清理已合并分支
默认使用
sudo
—— 仅当用户明确要求且有具体原因时使用
批量删除
~/Library/Application Support
—— 该目录包含关键应用数据。仅删除用户确认已卸载应用的对应条目。
在大型系统目录（如
~/Library/Application Support
或
~/Library/Containers
）中执行递归查找 —— 这些目录可能非常庞大且缓慢。仅检查特定子目录。
未警告就删除Xcode派生数据 —— 该数据可能占用大量空间，但重建需要时间。必须标记其大小和重建成本。
通过程序清理浏览器缓存 —— 这可能损坏浏览器状态。应引导用户通过浏览器设置操作。
强制清理Docker卷 —— 卷中可能包含数据库数据。必须展示卷名并获得用户明确批准。