提示：AI 结果必须带引用；若证据不足会提示“未找到可靠证据”。

下载 Markdown

mac-tools — PRD & Tech Spec（可直接开工版）v0.3

版本：v0.3
日期：2026-03-01
适用仓库：/Users/Zhuanz/work-space/mac-tools

0. 基本信息

产品名：mac-tools
平台：macOS 13+
形态：主窗口 App（Dashboard），菜单栏小组件放入 v1.1
默认语言：中文（后续可扩展 i18n）
数据策略：本地存储，不上传（除非用户主动开启匿名统计）
设计原则：可解释、可控、可回滚、默认保守

1. 版本规划

1.1 v1.0（MVP）

Monitoring
- CPU / Memory / Disk / Network / Battery（笔记本）
- Top Processes（CPU/内存前 N）
- Dashboard + Detail
- 30 分钟内存级历史（滑动窗口）
Cleaner
- 扫描：用户级缓存/日志/下载大文件/废纸篓统计
- 执行：默认隔离区（可回滚）
- 报告：明细/失败原因/一键撤销
Uninstaller
- App 列表 + 拖入卸载
- 残留扫描（bundleId + 常见目录规则）
- 默认仅勾选低风险残留
- 执行 + 报告 + 回滚
Settings
- 刷新频率/告警开关/白名单/删除策略

1.2 v1.1（增强）

历史持久化（24h/7d）
菜单栏小组件
定时清理（安全项）
温度/风扇/功耗（受权限与机型限制）

2. 成功指标（验收 KPI）

监控刷新 1s：App 自身 CPU 开销目标 < 2%（空闲时）
大目录扫描：10 万文件级别可扫描，不阻塞 UI，必须可取消
清理/卸载：
- 100% 生成报告
- 默认策略不误删（高风险默认不勾）
- 隔离区模式支持一键撤销

3. 信息架构（IA）

Dashboard
Monitoring
- CPU
- Memory
- Disk
- Network
- Battery（仅笔记本显示）
- Processes
Cleaner
- Scan Results
- Quarantine
Uninstaller
- Apps
- Uninstall History
Settings
About

4. 模块 A：Monitoring

4.1 指标（v1.0 必做）

CPU
- 总使用率
- Load Average（1/5/15）
- 分核心（可选）
- Top CPU Processes
Memory
- 总/已用/可用
- Memory Pressure（绿/黄/红）
- Swap
- Top Memory Processes
Disk
- 总容量/可用空间
- 读写速率（MB/s）
- Top Directories（用户目录）
Network
- 上/下行实时速率
- 会话累计流量
Battery（笔记本）
- 电量
- 充电状态
- 健康/循环（可取则展示）

4.2 采样策略

默认刷新：1s（可选 0.5/1/2/5）
历史缓存：30 分钟滑动窗口
进程榜采样：默认 2s（减少自身干扰）
告警：
- CPU > 90% 持续 60s
- Memory Pressure 红
- Disk 可用 < 10%

4.3 告警冷却与恢复阈值（v0.3 新增）

CPU 恢复：< 70% 持续 30s
Disk 恢复：> 15%
同类告警冷却：5 分钟
告警行为：toast + 可跳转目标页面

4.4 UI 组件

MetricCard
LineChart
SegmentedControl
ProcessTable
DetailHeader
HistoryRange（1/5/15/30 分钟，前端筛选）

5. 模块 B：Cleaner

5.1 分类（v1.0）

User Caches（低）~/Library/Caches/**
User Logs（低）~/Library/Logs/**
Saved Application State（中）~/Library/Saved Application State/**
Downloads Large Files（中）~/Downloads，默认阈值 > 200MB
Trash（提示）仅统计，引导清空

v1.0 不做系统级默认删除，系统级仅展示或需显式开关。

5.2 状态机

S0 Idle
S1 Scanning（可取消）
S2 Results
S3 Confirm（中高风险二次确认）
S4 Executing
S5 Report

5.3 删除策略（强制）

默认：Quarantine
- 目录：~/Library/Application Support/mac-tools/Quarantine/<batchId>/...
- 同卷优先 move；跨卷 copy+delete
- 保留原路径映射
可选：Trash
- deletionMode = quarantine | trash
- 默认 quarantine

5.4 白名单（必须）

规则类型：exact、prefix
匹配时机：扫描前过滤（减少无意义 I/O）
存储：SQLite

6. 模块 C：Uninstaller

6.1 App 发现

扫描：/Applications、~/Applications
字段：icon/name/version/bundleId/appSize(lastUsed 可选)
能力：搜索、排序、拖入 .app

6.2 残留扫描规则

用户级规则
- Preferences（低）
- Application Support（中）
- Caches（低）
- Logs（低）
- Saved State（中）
- Containers（中）
- Group Containers（高，默认不勾）
系统级规则（高）
- /Library/** 仅展示，默认不删

6.3 匹配置信度（v0.3 新增）

exact：bundleId 精确命中
strong：AppName + 目录结构双命中
fuzzy：弱关联/模糊匹配

默认勾选矩阵：

风险	exact	strong	fuzzy
low	勾选	勾选	不勾
medium	勾选	配置可控（默认勾）	不勾
high	不勾	不勾	不勾

6.4 卸载状态机

U0 Select App
U1 Scan Residues
U2 Review
U3 Confirm（高风险二次确认）
U4 Execute（先本体后残留）
U5 Report（支持回滚）

7. Settings

Monitoring
- refreshInterval：0.5/1/2/5
- enableAlerts：on/off
- historyWindow：30min
Cleaner
- deletionMode：quarantine（default）/ trash
- downloadsThresholdMB：默认 200
- whitelist 管理
Uninstaller
- defaultSelectPolicy（低/中/高风险）
- showSystemLevelResidues：默认 off
Privacy
- analytics：默认 off
- 清除本地数据（仅历史与报告）

8. 数据模型

8.1 MonitoringSample

ts: Int64
cpuUsage: Double
load1/load5/load15: Double
memUsed/memFree/memPressure: Double/enum
diskFree/diskReadMBps/diskWriteMBps: Double
netUpKBps/netDownKBps: Double
batteryPct/isCharging: optional

8.2 FileItem

id: UUID
category: enum
path: String
sizeBytes: Int64
risk: enum（low/medium/high）
reason: String
selected: Bool
lastModified: optional

8.3 OperationReport

id: UUID
type: enum（clean/uninstall）
startedAt/endedAt
totalSelectedBytes/totalFreedBytes
itemsSucceeded
itemsFailed
rollbackAvailable
quarantineBatchId

8.4 WhitelistRule

id: UUID
type: enum（exact/prefix）
value: String
note: optional
createdAt

8.5 v0.3 新增模型

ScanSession
ResidueMatch（含 confidence）
QuarantineManifest
OperationItemResult
SchemaVersion

9. 权限与系统限制

Full Disk Access：深目录扫描时检测并引导
管理员权限：系统级删除前检测
SIP 受限目录：提示不可写
降级策略：无权限时仍可使用可访问能力，并明确“受限扫描”

10. 错误处理规范

E_PERMISSION
E_IN_USE
E_NOT_FOUND
E_IO
E_UNKNOWN

UI：简短原因 + 展开详情 + 复制失败列表（路径+错误）

11. QA 验收用例（v1.0）

Monitoring

打开应用 3 秒内渲染 Dashboard。
1s 刷新运行 30 分钟无明显内存增长。
与活动监视器趋势一致。
Top Processes 排序正确。

Cleaner

~/Library/Caches 扫描结果与总大小合理。
清理后报告完整，失败项有原因。
隔离区回滚可恢复原路径，冲突可处理。

Uninstaller

/Applications App 可卸载到隔离区/废纸篓。
残留扫描至少覆盖 Preferences/Caches/Application Support。
Group Containers 默认不勾，且二次确认生效。
卸载报告可回滚（本体 + 低风险残留）。

v0.3 补充

扫描取消后状态正确，不进入执行。
执行取消后报告含已成功/未执行/失败。
同卷 move 与跨卷 copy+delete 都可回滚。
fuzzy 命中默认不勾且 reason 清晰。
告警冷却期内不重复弹窗。
权限受限时展示受限扫描且功能不崩溃。

12. 决策冻结（v1.0）

技术栈：SwiftUI + AppKit bridge + Swift Concurrency + SQLite。
发布形态：DMG（Developer ID 签名 + Notarization），默认非沙盒。
默认删除策略：quarantine。
系统级目录：v1.0 仅扫描展示，默认不执行删除。

13. 架构基线

MonitoringEngine
ScanEngine
RuleEngine
ExecutionEngine
ReportStore
PermissionCenter
SettingsStore

14. 扫描边界（强约束）

默认不跟随符号链接。
默认不递归 .app 包内部。
用户目录内隐藏项可扫描，但结果需标注。
并发上限固定（建议 4），UI 结果批量节流刷新（建议 200ms）。
大扫描必须流式产出且可取消。

15. 执行事务模型

预校验 -> 本体 -> 残留 -> 报告落盘。
扫描取消：cancelled，不进入执行。
执行取消：仅停止未开始项，已执行项可回滚。
回滚按清单逆序；冲突支持 skip/overwrite/rename。
同一批次回滚具备幂等性。

16. 性能预算

空闲监控 1s 刷新：CPU < 2%
30 分钟历史缓存：固定容量环形缓冲
扫描 10 万文件：主线程不阻塞，可取消响应 < 500ms
报告落盘：中等规模 < 1s

17. 输出物（v1.0 必须可见）

扫描结果页：每项必填 reason。
操作报告：成功/失败/错误码/建议动作可追溯。
隔离区页面：按 batch 展示、支持回滚。

18. 开工前 Checklist

数据库 schema 冻结并建迁移策略。
状态机（scan/execute/rollback）流程图冻结。
错误码与系统错误映射表冻结。
权限引导文案冻结。
基准性能脚本与数据样本准备完成。