mac-dev-cleanup本地 Web 控制台
自包含零依赖仪表盘：查看状态、改配置、触发只读扫描；小屏自动切换卡片视图，无横向滚动。
AI Skill · Codex / Trae 兼容
对 AI 说一句话，
对 AI 说一句话，
清出 Mac 里沉睡的空间。
mac-dev-cleanup 是一个由 AI 代理驱动的 macOS 开发者缓存清理 Skill：代理读取内置 SKILL.md 后调用 Python 脚本，自动扫描、分级并安全清理——真实清理先进废纸篓，随时可还原。
13识别类别
3风险级别
100%可恢复清理
0运行时依赖
$ 你 ➜ 请帮我把这个 skill 快速下载并安装使用：
克隆 yancongya/mac-dev-cleanup 到 ~/.codex/skills/
→ git clone … ~/.codex/skills/mac-dev-cleanup
→ python3 scripts/mac_dev_cleanup.py scan
✓ 扫描完成（只读，未删除任何文件）
77 项候选 · 7.3G 可清理 · 15.5G 待确认
manual 级别永不自动删除，等你逐条确认
$
global-cacheapp-cacheapp-logproject-generatedlog-filetemp-browsertemp-filetest-artifactscreenshotlarge-dirlarge-filestale-depsstale-model
// 01 — 工作方式
你说一句话，剩下的交给代理
不需要记任何命令。Skill 的意义就在于：意图由你表达，执行由代理与脚本完成。
01
自然语言下达指令
在 Codex / Trae 等代理对话里说一句「清理我的开发缓存」，或粘贴快速开始里的安装 Prompt。
02
代理读取 SKILL.md
代理据此理解何时调用、如何调用，以及不可逾越的安全边界（个人文件、源码、.git 永不触碰）。
03
脚本执行并报告
内置 Python 脚本完成扫描、风险分级与清理；真实清理先进废纸篓，附操作清单可一键还原。
// 02 — 特性
为「安全地放权给 AI」而设计
AI 负责省事，工程化负责兜底：每一层都有明确的安全边界。
AI 代理驱动的 Skill
本仓库就是一个 Skill：内含 SKILL.md 清单。你用自然语言下达指令，代理读取清单后调用内置 Python 脚本，自动扫描、分级并清理——无需记忆任何命令。
广覆盖识别
识别 13 类目标：全局/应用缓存与日志、项目生成物、测试产物、截图、大目录/大文件、stale 依赖与模型。
三级风险模型
safe / aggressive / manual。manual 项（截图、大文件、模型等）永不自动删除，仅报告待你确认。
Stale 项目识别
以「源码 mtime + 最后 git commit」判定项目闲置（默认 90 天），自动标记 stale-deps / stale-model。
先进入废纸篓
真实清理把候选移入 ~/.Trash/mac-dev-cleanup/<op-id>/ 并写入操作清单，可一键还原，绝不使用裸 rm。
配置化
单一 config.json 管理阈值、扫描根、排除项；Web 设置面板可视化编辑并原子写入。
APFS 感知
清理后空间未必立即释放——APFS 快照会占位。文档说明重启释放机制与正确验证姿势（df -h ~）。
// 03 — 风险级别
先扫描，再按级别分级处理
清理前务必先跑只读扫描；不同模式对各级别的处理策略不同。
| 级别 | 行为 | 典型示例 |
|---|---|---|
| safe | clean-safe 与 clean-aggressive（加 --apply）均删除 | __pycache__、pip/npm/uv 缓存、playwright 临时文件、项目日志、覆盖率 |
| aggressive | 仅 clean-aggressive（加 --apply）删除 | node_modules、.venv、build、dist、Codex/Trae 缓存、大应用缓存/日志、stale-deps |
| manual | 任何模式都不自动删除，报告中标为「待确认」 | 截图、大目录、归档、dump、个人大文件、stale-model |
// 04 — 快速开始
一条 Prompt，跑完完整链路
复制给 AI 代理，即可自动完成「下载 → 安装 → 只读扫描验证」；也可手动安装。
STEP 0 · 推荐
快速下载并使用 Skill
复制整段 → 粘贴给 AI 代理代理会自动：克隆仓库 → 安装到 skills 目录 → 跑一次只读扫描做安装验证 → 向你汇报结果。
请帮我把这个 skill 快速下载并安装使用：把仓库 https://github.com/yancongya/mac-dev-cleanup.git 克隆到 ~/.codex/skills/mac-dev-cleanup，然后运行 scan 做一次只读扫描作为安装验证，告诉我能清理多少空间、有哪些需要我确认的项目。如果缺少 Python 或权限不足，也请说明。
STEP 1
手动安装
复制到终端执行git clone https://github.com/yancongya/mac-dev-cleanup.git ~/.codex/skills/mac-dev-cleanup
STEP 2
调用 Skill
安装后 · 复制给 AI 代理用 mac-dev-cleanup 这个 skill 帮我扫描并清理开发缓存：先只做只读扫描，再列出可清理项让我确认后再执行。
// 05 — 配置
单一 config.json，代理与 Web 共用
用户可调项集中在 config.json；脚本每次运行读取，缺失则写入默认值；安全边界硬编码、不可被配置削弱。
{
"stale_days": 90,
"thresholds": {
"app_cache_min_mb": 50,
"app_log_min_mb": 10,
"large_dir_mb": 100,
"large_file_mb": 50
},
"scan_roots": ["~/工作/开发", "~/Desktop/OH-WorkSpace", "~/Documents", "~/Developer", "~/dev", "~/workspace"],
"personal_roots": ["~/Desktop", "~/Pictures", "~/Downloads"],
"exclude_paths": [],
"protected_projects": [],
"trash_retention_days": 30
}
# 只读扫描
python3 ~/.codex/skills/mac-dev-cleanup/scripts/mac_dev_cleanup.py scan
# 安全清理：先干跑，再 --apply 真清理（进废纸篓）
python3 ~/.codex/skills/mac-dev-cleanup/scripts/mac_dev_cleanup.py clean-safe
python3 ~/.codex/skills/mac-dev-cleanup/scripts/mac_dev_cleanup.py clean-safe --apply
# 查看配置 / 启动本地 Web 控制台
python3 ~/.codex/skills/mac-dev-cleanup/scripts/mac_dev_cleanup.py --show-config
python3 ~/.codex/skills/mac-dev-cleanup/scripts/web_server.py
// 06 — 安全须知
清理有风险，兜底要到位
请先在废纸篓里留存一段时间再清空；受保护范围永不被扫描或删除。
APFS 快照占位：macOS 删除大文件后
df 可能不变——系统更新快照 com.apple.os.update-* 与 Time Machine 本地快照会占用容器空间。重启是最可靠的释放方式，不要因为 df 没变就以为清理失败。验证请用 df -h ~（而非 df /，后者在现代 macOS 上是只读系统卷）。
受保护、永不被扫描/删除的范围：个人媒体与文档、应用支持数据、源代码、.git、包 lockfile、用户自建资源；项目遍历时跳过 .git/.svn/.hg；系统目录（Application Support、Containers、Mobile Documents、Music、Movies、Trash 等）不进入。
扫描根：项目目录递归
个人根：仅顶层（截图/大文件）
应用根：仅 ≥50M 缓存 / ≥10M 日志
临时根：/tmp、/var/folders