故障排查

优先确定命令是跳过了某项操作、扫描结果不完整，还是真正执行失败。三者的排查方向不同。

白名单不可读取

现象：Mole 拒绝执行 clean、purge 或 optimize。

原因：保护配置未知时需要失败关闭。检查：

ls -ld ~/.config ~/.config/mole
ls -l ~/.config/mole/whitelist
ls -l ~/.config/mole/whitelist_optimize

不要通过删除白名单或绕过保护机制来“修复”扫描。

macOS 权限限制

Terminal 或所使用的终端模拟器可能没有读取某些 ~/Library 目录的权限。Full Disk Access 需要由用户在系统设置中手动授权，不能自动跳过 macOS TCC。授权前后重新运行只读扫描。

Xcode / Simulator 运行状态未知

CoreSimulatorService 启动和探测可能很慢；simctl 可能返回失败或超时。Mole 无法可靠确认进程状态时，会跳过对应清理。

xcode-select -p
xcrun simctl list devices
mo clean --dry-run --debug

不要因为 simctl 暂时没有列出设备，就认为 Runtime 无引用。

analyze --json 返回 0 但数据缺失

检查 JSON scan_status 而不仅是 Shell 退出码。partial 和 unavailable 表示结果不完整。

空间没有如预计增加

文件可能进入废纸篓、被快照引用，或者与克隆数据共享块。参见 APFS 计量。

mo purge 扫不到某工程

运行 mo purge --paths，增加更接近工程的根目录；默认深度和默认根路径有限。外置卷只有明确加入后才应被扫描。

命令找不到或选项不支持

先确认当前终端使用的是哪一份 Mole CLI，检查安装渠道、版本和实际帮助：

command -v mo
mo --version
mo --help
mo clean --help

不同安装渠道与旧版本的参数可能不同。优先以本机帮助为准，参阅 安装与更新 和 源码版本依据。