mac-disk-clean — macOS 磁盘清理 skill (Claude Code Skill)

cleanable-categories.md

可清理类别速查表

扫描时主动找这些类别。每类给出:典型路径、判断方法、安全等级、清理命令。不确定某项是什么时,先 ls/du 看内容再下结论。

🟢 安全:重建型缓存

删了零影响,工具/应用下次自动重新生成。

语言编译缓存(通常是最大头)

项目	路径	命令
Go 编译缓存	~/Library/Caches/go-build	go clean -cache
Go 模块缓存	~/go/pkg/mod	go clean -modcache
Rust Cargo	~/.cargo/registry/cache、~/.cargo/registry/src	rm -rf ~/.cargo/registry/cache ~/.cargo/registry/src
JetBrains 索引	~/Library/Caches/JetBrains	rm -rf ~/Library/Caches/JetBrains

判断: 这类目录能单挑几十 G(go-build 见过 52G)。go/cargo 命令清更干净;直接 rm 也行。重建需要重新编译/联网下载,但代码和配置完全不碰。

包管理器缓存

项目	路径	命令
npm	~/.npm/_cacache、~/.npm/_npx	npm cache clean --force(再 rm -rf ~/.npm/_npx)
pip	~/Library/Caches/pip	pip cache purge 或 pip3 cache purge(pip 可能不存在,试 pip3)
Homebrew	~/Library/Caches/Homebrew	brew cleanup --prune=all(比直接 rm 干净,清旧版本依赖)
node-gyp	~/Library/Caches/node-gyp	rm -rf ~/Library/Caches/node-gyp

注意: _npx 是 npx 临时跑过的包缓存,能单独占几百 M,npm cache clean 不清它,要单独 rm。

浏览器缓存(非用户数据)

项目	路径
Chrome 缓存	~/Library/Caches/Google/Chrome

关键区分: Caches/Google 是网页缓存,可删;Application Support/Google/Chrome 含登录态/书签/历史/Profile,不要整目录删,里面 Profile 1 等是用户数据。建议用户在浏览器内清缓存更安全。

App 日志(持续写但无价值)

典型:~/Library/Application Support/<App>/log*、~/Library/Application Support/<App>/*/logs

见过的大户:钉钉 gaea.log(单文件 270M)、钉钉直播 dinglive/logs(385M)、Trae logs、豆包输入法 Log。

命令: rm -rf <logdir>/* —— 删内容保留空目录,App 下次正常写。

🟡 较安全:重建有轻微代价

删了能用,但要联网重下或重新构建。

项目	路径	代价
node_modules	项目里 */node_modules	需 npm install 重装,几十秒到几分钟
Playwright 浏览器	~/Library/Caches/ms-playwright	需 npx playwright install 重下
账号资源缓存	~/Library/Application Support/<App>/*_v3/EAppFiles、resource_cache	小程序/资源文件,下次打开重下
App 缩略图缓存	~/Library/Caches/<App>/thumbnails	重新生成

建议: 先确认对应项目/工具当前不在用,再删。

🟠 需判断:依赖使用习惯

必须问用户"还用不用",别替他决定。

Docker 虚拟磁盘

• 路径:~/Library/Containers/com.docker.docker/Data/vms/*/Docker.raw
• 特点:文件只增不减,删镜像后体积也不缩。见过的 3.5G+。
• 不用了:直接删 .raw,或 Docker Desktop 里 "Clean / Purge data"。
• 还在用:启动 Docker 跑 docker system prune -a --volumes 清未用镜像/卷(防膨胀,不缩文件)。

Colima / 其他 VM

• ~/.colima/*.raw、~/.colima/*.qcow2 —— 同理,不用了删镜像文件。

AI 工具会话历史

• Codex:~/.codex/sessions(见过 3.1G)、~/.codex/archived_sessions、~/.codex/computer-use、~/.codex/generated_images
• Claude:~/.claude、~/Library/Application Support/Claude*
• 判断:用户需要翻旧会话吗?不需要就能清。

iOS 设备备份

• 路径:~/Library/Application Support/MobileSync/Backup
• 常常几十 G,是手机整机备份。删前确认用户不需要恢复旧设备。

🔴 谨慎:用户个人数据

默认建议保留,除非用户明确说不要。删前最好再问一次。

项目	路径
聊天记录数据库	~/Library/Application Support/DingTalkMac/*_v3/DBFiles、微信 com.tencent.xinWeChat
下载文件夹	~/Downloads
账号配置/UserStorage	*_v3/UserStorage、*_v3/config
文档	~/Documents

微信/钉钉类: 建议用户在 App 内的"存储管理"清,会比直接删文件安全(保留账号配置)。

隐形大户:主动搜的命令

这些类别目录名不显眼,容易漏。扫描时主动 find:

# 崩溃报告堆积(Electron 应用)
find ~/Library -iname "Crashpad" -o -iname "KSCrash"
find ~/Library -path "*/Crashpad/pending" -name "*.dmp" | head

# 自动更新残留(下载没清的安装包)
find ~/Library -iname "*update*" -o -iname "*ShipIt*" -o -iname "*updater*"

# 失控日志
find ~/Library -type f -iname "*.log*" -size +50M
find ~/Library -type d -iname "log*"

# 大虚拟磁盘镜像
find ~/Library/Containers ~/.colima -name "*.raw" -o -name "*.qcow2"

崩溃报告堆积(重点案例)

~/Library/Application Support/<ElectronApp>/Crashpad/pending/ 里的 .dmp 文件,是应用崩溃后生成的转储,本应上传到崩溃统计服务器后移到 completed/。但上传失败时会无限堆积:

• 见过 Codex 桌面端堆了 65535 份(目录项上限)、9.9G,全是同一种崩溃。
• 判断是否还在涨:看 pending/ 里文件的 mtime 最新一份,对比当前时间。停了就是死数据。
• 清理:rm -rf <App Support>/<App>/Crashpad/pending,应用下次崩溃会重建目录。连根删整个 Crashpad 也行。

验证清理效果

每轮删前后都量一下,给用户看到实际回收:

du -sh <dir>   # 删前
rm -rf <dir>/*
du -sh <dir>   # 删后(应接近 0)

汇总时算累计回收量,让用户有进度感。

SKILL.md

name	mac-disk-clean
description	诊断和清理 macOS 磁盘空间。扫描整个磁盘找出占用大户,按安全等级分类给出清理建议,等用户确认后再执行。Use whenever the user mentions disk space, 磁盘满了, 磁盘占用, 清理磁盘, 清理缓存, storage full, out of space, 想清理, 占了太多空间, or wants to free up disk space on a Mac — even if they don't explicitly say "skill".

macOS 磁盘清理

帮用户回收 macOS 磁盘空间。核心是交互式流程:扫描 → 分类建议 → 等用户逐项确认 → 只执行被确认的项。

关键原则(必读)

1. 绝不擅自删除。 每一轮都要先展示发现了什么、建议怎么处理,然后停下来等用户回复。用户说"执行"或"可以"之后,才动手删。这是这个 skill 的灵魂。

2. 按安全等级分类。 同样是占空间,"Go 编译缓存"和"微信聊天数据库"风险天差地别。永远把每一项标成绿/黄/橙/红,让用户一眼看出哪些无脑删、哪些要想想。

3. 先量体积再下结论。 一个目录可能名字叫 Caches 但里面是用户数据。永远 du + ls 看过实际内容,再判断它能不能删。不要只凭目录名下结论。

4. 大小要对得上账。 如果数据卷用了 367G 但扫出来的目录加起来只有 80G,说明漏了大头——继续往下钻,不要拿着残缺数据给建议。

5. 删前留目录。 删 App 日志/缓存时用 rm -rf <dir>/* 保留空目录本身,不要连目录一起删,避免 App 下次启动报错。

工作流程

第 1 步:摸清全局

并行跑这几个只读命令(都是安全的,不修改任何东西):

df -h                                              # 总体使用率,定位是哪个卷紧张
du -sh ~/* ~/.[!.]* 2>/dev/null | sort -hr | head -25   # home 目录所有顶层项(含隐藏)
du -sh /Applications /Library /private/var 2>/dev/null | sort -hr   # 系统级大头

• macOS 的用户数据实际挂在 /System/Volumes/Data,看这个卷的 Used 和 Capacity。
• home 顶层扫描能抓到最大的几个目录,通常 ~/Library 是大头。

第 2 步:钻进大头,逐层分解

对第 1 步发现的大目录(通常 ~/Library 几十 G),继续往下 du -sh <dir>/* | sort -hr。带着目的钻:

• ~/Library/Caches/* —— 大多可清,但要分类
• ~/Library/Application Support/* —— App 数据,需逐个看里面有啥
• ~/go/pkg、~/.npm 等 —— 语言工具链缓存
• ~/.codex、~/.claude 等 —— AI 工具历史

不要一次扫所有子目录(太慢)。先扫顶层,挑最大的几个往下钻。

第 3 步:识别"隐形"类别

经验上,这些类别最容易被忽略但占用巨大,主动去找:

类别	怎么找	说明
崩溃报告堆积	find ~/Library -iname "Crashpad" -o -iname "*.dmp"	Electron 应用崩溃后 dump 堆在 pending/ 不上传,能堆到几十 G
自动更新残留包	find ~/Library -iname "*update*" -o -iname "*ShipIt*" -o -iname "*updater*"	下载完没清的 .pkg/.zip/.dmg,飞书、UU、ZCode 等都中招
失控的日志	find ~/Library -iname "log*" -type d; find ~/Library -size +50M -iname "*.log"	钉钉 gaea.log 能单文件 270M,持续写
语言编译缓存	go clean -cache 候选、~/.cargo、~/.npm、~/Library/Caches/JetBrains	重建型缓存,最安全的大头
Docker/VM 磁盘镜像	find ~/Library/Containers/com.docker.docker -name "*.raw"	.raw 文件只增不减,3G+ 常见
废纸篓	du -sh ~/.Trash	容易忘

完整的可清理类别清单和判断标准见 references/cleanable-categories.md——不确定某类东西是什么、能不能删时去查。

第 4 步:整理建议(分类呈现)

把发现整理成分级清单,这是给用户决策的核心。每项给:路径、大小、性质、为什么能清、风险。

用 emoji 标安全等级,用户扫一眼就知道:

• 🟢 安全 —— 纯缓存/编译产物/日志,删了 App 自动重建,零风险。例:Go build cache、npm cache、浏览器缓存、App 日志。
• 🟡 较安全 —— 重建型但有轻微代价。例:模块缓存(需联网重下)、IDE 索引(重启重建)、node_modules(需 npm install)。需用户知道"下次会重新生成"。
• 🟠 需判断 —— 涉及使用习惯。例:Docker 镜像(还用不用?)、Playwright 浏览器(还做自动化吗?)、AI 工具会话历史(要不要翻旧账?)。
• 🔴 谨慎 —— 用户个人数据。例:聊天记录数据库、下载文件夹、账号配置。默认建议保留,除非用户明确说不要。

建议执行命令要给完整、可直接复制的 rm 命令,带正确的路径转义(macOS 路径常有空格)。

第 5 步:停下来,等用户

这是最关键的一步。 展示完建议后,明确停下来,问用户:

要我直接执行 🟢 那几项吗?还是 🟠/🔴 那些你想先看看内容?

不要连珠炮式问太多问题。通常一个聚焦的问题就够了。

第 6 步:执行被确认的项

用户回复后:

• 只执行用户点名同意的项,不要"顺便"多删。
• 删前后都 du -sh 量一下,给出实际回收量,让用户看到效果。
• 命令失败(如 pip 不存在)不要硬撞,换替代方案(pip3 / 直接 rm),并在结果里说明。
• 执行完汇总:本轮回收多少、累计回收多少、还剩哪些大头没动。

第 7 步:提议下一轮(可选)

一轮清完,主动说"还有 X、Y 这些大头没动,要不要继续"。但不强推,用户说"先这样"就停。

实操要点

• 并行扫描: 第 1 步、第 2 步的独立 du/find 命令放在同一条消息里并行跑,省时间。
• glob 会爆: 目录里有几万文件时 ls *.dmp 会报 "Argument list too long",改用 find ... -exec stat 或 find ... | wc -l。
• du 慢: 扫 ~/Library 可能要一两分钟,设 timeout 到 300000ms。先扫顶层 maxdepth 3 探路,再针对性钻。
• macOS 路径有空格: Application Support、com.docker.docker 等,命令里用引号或转义 \ 。
• 数据卷: macOS Catalina+ 把用户数据放 /System/Volumes/Data,df -h 看这个卷的 Used 才是真实占用;根 / 的数字是只读系统卷,会误导。

何时不用这个 skill

• 用户只是想知道"磁盘用了多少"——直接 df -h 回答,不需要走完整流程。
• 用户明确指定要删某个具体文件——直接删,不用扫描建议。
• Linux/Windows 环境——这个 skill 是 macOS 专用的,路径和命令假设 darwin。