FolderMind · AI 开发环境清理管家

一款面向普通用户与开发者的 macOS 清理工具：自动扫描开发环境中的可清理空间（模拟器、构建缓存、AI 工具残留、系统缓存、项目构建产物、下载大文件、重复文件、Docker 空间等），分级展示风险，一键安全清理。清理一律移入废纸篓，可随时恢复。

当前版本：V2.4.1（仅支持 Apple 芯片 Mac / macOS 14+，arm64）

---

功能特性

🧹 一键清理（主界面）

• 空间总览：可回收 / 可一键 / 需谨慎 / 运行中 四项 KPI + 较上次扫描的空间变化
• 9 类可清理项：

  类别	说明	风险级
  模拟器	iOS Simulator 设备（运行中自动保护）/ Android AVD	safe / protected
  构建缓存	Xcode DerivedData / Archives / iOS DeviceSupport / Simulator Runtimes	caution
  AI 工具残留	/.claude、/.cursor 等 AI Agent 配置与历史	caution
  系统缓存	~/Library/Caches 大目录 + Homebrew 缓存	safe
  项目构建产物	node_modules / .build / venv / Pods 等	safe
  下载大文件	≥1GB，或 ≥200MB 且超 180 天未动	caution
  重复文件	同名 + 同大小 + 抽样哈希确认	caution
  废纸篓	占用统计 + 永久清空（强确认）	caution
  Docker 空间	docker system df 汇总 + prune -af（不清数据卷，强确认）	caution

• 一键智能清理：只处理安全级项，全部进废纸篓；单项清理带影响说明 + 确认对话框
• 运行中项保护：正在运行的模拟器等只展示、不清理

🔌 系统体检（第二 Tab）

• 隐私与权限：完全磁盘访问检测 + 一键跳转系统设置
• 开机启动项：用户/系统 LaunchAgents 与 LaunchDaemons，标记失效项（程序已不存在）与损坏 plist
• 卸载残留：Application Support / Preferences / Caches / Logs 疑似残留，lint 风格风险分级（低/中/高 + 原因说明）；三通道匹配（bundleID / 显示名 / 可执行文件名）+ 运行中 App 保护 + 系统服务白名单，绝不误删在用 App 数据

🔁 找回与防复发

• 清理历史：记录每次清理（时间/名称/大小/来源/废纸篓位置），支持单条/全部恢复（冲突自动加后缀）
• 空间趋势：每次扫描落库空间快照，Hero 卡显示"较上次 +N GB"
• 防复发通知：可回收空间反弹 ≥1GB 时通知（可选）
• 每周自动清理：只清安全级、进废纸篓（可选）

⚙️ 设置

• 9 项扫描范围开关 + 系统缓存阈值（100MB~1GB）
• 每周自动清理 / 防复发通知 / 开机启动（SMAppService）/ 关于

🎨 设计

• 遵循 Apple HIG 的 macOS 原生图标；统一设计系统（FMDesign）：数据分级用颜色说话、危险操作永远有解释、数字是主角
• 深色/浅色模式自适应

---

安全底线（不可变设计原则）

1. 清理一律移废纸篓，绝不直接删除（废纸篓清空与 Docker prune 是唯二的"永久删除"，均需强确认且文案明示）
2. 运行中/受保护项只展示不清理
3. 风险分级只增不减：拿不准的归中/高风险
4. 恢复操作覆盖冲突：目标已存在时自动加 (1) 后缀，绝不覆盖
5. 卸载残留绝不误删：在用 App（运行中 / 三通道匹配 / 系统服务白名单）的数据目录一律跳过

---

技术栈与结构

• 语言：Swift 5.9 + SwiftUI + AppKit（@Observable 状态管理）
• 构建：SwiftPM（FolderMindCore 纯逻辑库 + FolderMindApp 应用层）
• 存储：SQLite3（sqlite3 C API，projects / cleanup_history / space_snapshots 三张表）
• 最低系统：macOS 14.0（arm64）

FolderMind/
├── Sources/
│   ├── FolderMindCore/          # 纯逻辑层（可独立单测）
│   │   ├── Models/              # JunkItem / CleanupHistoryRecord / SpaceSnapshot / Project
│   │   └── Services/
│   │       ├── DevelopmentJunkScanner.swift   # 9 类垃圾扫描 + CleanupEngine（清理/恢复）
│   │       ├── SystemInspector.swift          # 开机启动项 + 卸载残留 + 风险分级
│   │       ├── ProjectDiscovery.swift         # 全盘项目发现（供构建产物分类）
│   │       └── PersistenceStore.swift         # SQLite 持久层
│   └── FolderMindApp/           # SwiftUI 应用层
│       ├── AppState.swift       # 全局状态（扫描/清理/历史/趋势/设置）
│       ├── PrivacyChecker.swift # 完全磁盘访问检测
│       └── Views/               # CleanupDashboard / SystemHealth / CleanupHistory / Settings / SpaceAnalysis
├── Tests/FolderMindCoreTests/   # 23 个单元测试
├── scripts/package.sh           # 打包脚本（.app + DMG）
└── scripts/generate_icon.swift  # 图标生成
docs/                            # PRD / 设计规范 / 评审文档
TASKS.md                         # 开发任务清单与版本历史

---

构建与测试

# 构建（release）
swift build -c release --disable-sandbox

# 运行单元测试（23 个）
swift test --disable-sandbox

# 打包 DMG（参数：版本号 构建号）
./scripts/package.sh 2.4.1 15
# 产物：build/FolderMind-V2.4.1-Installer.dmg

测试含废纸篓相关用例（移入废纸篓/恢复），请在普通终端环境运行（部分受限沙箱环境会拒绝废纸篓操作）。

---

分发说明

• 当前构建为 ad-hoc 签名（非 Developer ID）且未公证：收到 DMG 的一方首次打开时若提示"无法验证开发者"，需 右键 → 打开 → 仍要打开（或终端执行 xattr -dr com.apple.quarantine /Applications/FolderMind.app）
• 正式对外分发建议：申请 Apple Developer 账号 → Developer ID 签名 → notarytool 公证 → stapler 贴票
• 仅 arm64（Apple 芯片）；如需支持 Intel Mac 需构建 universal 二进制

---

文档

• docs/FolderMind-PRD-V1.5-补充.md / docs/FolderMind-PRD-V1.3-AI学习.md — 早期产品 PRD（V1.x 项目健康方向，V2.1 起已转向纯清理工具）
• docs/UI-Design-V2.3.md — 设计规范
• docs/评审-*.md — 功能完整性 / 链路完整性评审
• TASKS.md — 完整开发任务清单与版本历史