需要在 macOS 上清理系统/用户缓存…

用 PureMac 这个免费开源的 SwiftUI 清理工具替代 CleanMyMac，清理缓存、日志、邮件附件、Xcode/Homebrew 垃圾和 APFS 可清除空间，并支持定时自动清理。

适用场景

解决思路

1. 用 Homebrew 安装：运行 `brew tap momenbasel/tap`，再运行 `brew install --cask puremac`。
2. 直接下载安装：从 GitHub Releases 下载最新 `.app`，解压后拖入 `/Applications`。
3. 从源码构建：先 `brew install xcodegen`，然后 `git clone https://github.com/momenbasel/PureMac.git`，`cd PureMac`，`xcodegen generate`，再运行 `xcodebuild -project PureMac.xcodeproj -scheme PureMac -configuration Release -derivedDataPath build build`，最后 `open build/Build/Products/Release/PureMac.app`。
4. 确认环境要求：macOS 13.0+、Swift 5.9、Xcode 15+。
5. 按项目结构定位代码：`PureMac/App/PureMacApp.swift` 是入口；`Views/ContentView.swift`、`ScanView.swift`、`CategoryDetailView.swift`、`SettingsView.swift` 是界面；`Models/CleanCategory.swift`、`ScanResult.swift` 是模型；`Services/ScannerService.swift`、`CleanerService.swift`、`SchedulerService.swift`、`PurgeableService.swift` 是服务；`Utilities/FileSizeFormatter.swift` 是工具；`project.yml`、`CONTRIBUTING.md` 是配置/贡献文件。
6. 清理类别与路径：System Junk 对应 `/Library/Caches`、`/Library/Logs`、`/tmp`、`~/Library/Logs`；User Cache 对应 `~/Library/Caches` 和 npm/pip/yarn/pnpm caches；Mail Attachments 对应 `~/Library/Mail Downloads`；Trash 对应 `~/.Trash`；Large & Old Files 对应 `~/Downloads`、`~/Documents`、`~/Desktop` 中 >100 MB 或 >1 year old 的文件；Purgeable Space 对应 APFS Time Machine snapshots via `tmutil`；Xcode Junk 对应 `DerivedData`、`Archives`、`CoreSimulator/Caches`；Homebrew Cache 对应 `~/Library/Caches/Homebrew`。
7. 处理 Large & Old Files 时永远不要自动选中，必须让用户在清理前显式选择。
8. 新增清理类别时，在 `CleanCategory.swift` 的 `enum CleanCategory` 中添加 case（如 `gradleCache` 对应 `Gradle Cache`），并在 `iconName` 的 `switch` 中返回新图标名（如 `archivebox`）。
9. 在 `ScannerService.swift` 的 `scanCategory(_:)` 中添加新 case，指定要扫描的路径（如 `~/.gradle/caches`），调用 `scanPaths`。
10. 实现/复用 `scanPaths`：用 `FileManager.default.enumerator(at:includingPropertiesForKeys:options:)` 遍历 URL，读取 `.fileSizeKey` 和 `.contentModificationDateKey`，跳过隐藏文件，汇总 `totalBytes` 并返回 `ScanResult`。
11. 在 `CleanerService.swift` 的 `clean(_:selectedFiles:)` 中处理删除：如果传入 `selectedFiles` 就只删除这些 URL，否则删除 `result.files` 中所有 URL；逐个用 `FileManager.default.removeItem(at:)` 删除，累加释放字节数；单文件失败只记录错误并继续，不中止整个过程。
12. 在 Settings → Schedule tab 配置定时清理；可选间隔为 `hourly`、`3h`、`6h`、`12h`、`daily`、`weekly`、`biweekly`、`monthly`。
13. 用 `@AppStorage` 持久化设置：`schedulingEnabled`（Bool，默认 false）、`cleaningInterval`（String，默认 `daily`）、`autoCleanAfterScan`（Bool，默认 false）、`autoPurgePurgeable`（Bool，默认 false）。
14. 在 `SchedulerService.swift` 中实现调度：`scheduleIfNeeded()` 先 invalidate 旧 timer，若 `schedulingEnabled` 为 false 则返回；根据 `cleaningInterval` 映射到秒数（`hourly=3600`、`3h=10800`、`6h=21600`、`12h=43200`、`daily=86400`、`weekly=604800`、`biweekly=1209600`、`monthly=2592000`），用 `Timer.scheduledTimer(withTimeInterval:repeats:)` 周期触发 `runScheduledClean()`。
15. `runScheduledClean()` 遍历 `CleanCategory.allCases`，跳过 `.largeOldFiles`；如果 `autoCleanAfterScan` 为 true，则扫描每个类别并调用 cleaner 清理；如果 `autoPurgePurgeable` 为 true，则调用 `PurgeableService.shared.purge()`。
16. 程序化启用定时清理：设置 `cleaningInterval`（如 `weekly`）、`autoCleanAfterScan`、`autoPurgePurgeable`、`schedulingEnabled`，然后调用 `scheduleIfNeeded()`。
17. 用 `tmutil` 删除本地 Time Machine 快照来处理 Purgeable Space；这是唯一需要提升权限的操作。
18. `PurgeableService.listSnapshots()` 运行 `tmutil listlocalsnapshots /`，按行分割并过滤 `com.apple.TimeMachine` 前缀的快照。
19. `PurgeableService.purge()` 先列出快照，再对每个快照运行 `tmutil deletelocalsnapshots <snapshot>`。
20. shell 执行封装：用 `Process` 启动 `/bin/bash`，参数为 `-c` 和 command，标准输出接到 `Pipe`，在 `terminationHandler` 中读取数据并返回字符串；运行失败时抛出错误。
21. Xcode Junk 清理路径为 `~/Library/Developer/Xcode/DerivedData`、`~/Library/Developer/Xcode/Archives`、`~/Library/Developer/CoreSimulator/Caches`；扫描这些路径后删除其内容，但不要删除目录本身。
22. 实现扫描进度视图：在 `ScanView` 中用 `@StateObject` 创建 `ScannerService`，用 `@State` 保存 `results` 和 `isScanning`；用户点 Smart Scan 时执行 `runScan()`，遍历 `CleanCategory.allCases`，对每个类别调用 `scanner.scanCategory` 并追加结果，扫描时显示 `ProgressView`。
23. 实现文件检查器：在 `CategoryDetailView` 中传入 `result`，用 `@State` 保存 `selected: Set<URL>` 和 `cleaned`；用 `List` 展示 `result.files`，显示文件名和 `ByteCountFormatter` 格式化后的大小；工具栏提供 Clean Selected，调用 `CleanerService.clean(result, selectedFiles: selected)`，当 `selected` 为空时禁用按钮。
24. 配置项通过 `UserDefaults` / `@AppStorage` 读写；可用 `UserDefaults.standard.set` 写入，key 如 `schedulingEnabled`、`cleaningInterval`。
25. 重新生成 Xcode 工程：运行 `xcodegen generate`。
26. 构建 Release：运行 `xcodebuild -project PureMac.xcodeproj -scheme PureMac -configuration Release -derivedDataPath build build`。
27. 运行测试：运行 `xcodebuild test -project PureMac.xcodeproj -scheme PureMac -destination 'platform=macOS'`。
28. 打开构建产物：运行 `open build/Build/Products/Release/PureMac.app`。
29. 贡献流程：Fork 并 clone 仓库，运行 `xcodegen generate` 生成 `.xcodeproj`，创建 feature 分支（如 `git checkout -b feature/gradle-cache-cleaning`），遵循 `ScannerService` / `CleanerService` 现有模式。
30. 贡献硬性约束：绝不添加网络调用、分析 SDK 或任何 telemetry；Large & Old Files 绝不能自动选中删除；向 `main` 开 PR；更多见 `CONTRIBUTING.md`。
31. 排错：`xcodegen: command not found` 运行 `brew install xcodegen`。
32. 排错：App 被 Gatekeeper 拦截；release build 已 notarized，若从源码构建可运行 `xattr -cr PureMac.app`。
33. 排错：Purgeable scan 返回 0 bytes；表示没有本地 Time Machine 快照，若 TM 关闭则正常。
34. 排错：Xcode paths not found；表示 Xcode 尚未使用或 DerivedData 已被清空。
35. 排错：`tmutil` 要求密码；Purgeable purge 可能提示管理员凭据，这是 macOS 预期行为。
36. 排错：定时清理未触发；确保 app 正在运行（它不是后台守护进程），并检查 Settings → Schedule。
37. 安全保证：绝不删除系统关键文件或应用 bundle；只移除缓存、日志、临时文件和用户选定项；Large & Old Files 需用户显式选择；Purgeable 只针对 APFS Time Machine 快照而非空闲空间；常规清理全部使用 `FileManager.removeItem(at:)`，不使用 `rm -rf` shell 调用。

适用边界 · 注意事项

• 不适用于非 macOS 环境，或需要清理 Windows/Linux 的场景。
• 如果要求清理工具以后台守护进程方式常驻并定时执行，PureMac 的定时清理需要 app 正在运行，不适用。
• 如果必须自动删除大文件/旧文件，PureMac 强制用户手动选择 Large & Old Files，不适用。