功能文档

概览

Mole 有 Mac App 和 CLI 两种使用方式，覆盖相近的清理类别，也遵循同样保守的安全原则与保护列表，但能力范围并不完全相同。CLI 免费开源，采用 GPL-3.0 许可证。Mac App 是原生 SwiftUI 应用，一次购买 $19，包含永久更新，无订阅；它用原生方式执行 Mac 工作流，CLI 额外提供几个终端专属命令。

Mac App

安装

从首页下载 DMG，或通过 Homebrew 安装：brew install --cask mole-app。

清理 (Earth)

扫描 10 个类别：App 缓存、系统缓存与日志、开发工具（Xcode、npm、pip、Gradle）、AI 工具（ChatGPT、Claude、Codex、Copilot、Cursor、Antigravity）、浏览器（Chrome、Edge、Arc、Safari、Firefox）、云存储客户端、设计工具（Adobe、Figma、Sketch）、通讯工具（Slack、Discord、微信、Zoom）和杂项临时文件。废纸篓单独列在末尾。

审查列表按删除影响排序：可再生缓存在前，用户可见状态在后，废纸篓始终最末。硬链接感知意味着跨工具共享的文件（uv、pnpm）不会重复计算。默认永久删除缓存，让释放的空间和标题里的数字一致。设置里一个开关可以把所有操作改为移到废纸篓。

默认需要审查：重建成本较高的包缓存（npm、yarn、pnpm、bun、CocoaPods、Gradle、Maven），以及无需下载依赖即可重建的项目产物（build、dist、target、.build、.next、DerivedData、__pycache__、coverage）。Mac App 不会列出 node_modules、Pods、venv 等下载依赖目录，因为重新生成需要网络，也可能无法还原锁文件对应的状态。需要审查的项目默认不勾选；想保留可恢复的余地，可在设置 → 维护 → 缓存删除方式中选择「移到废纸篓」。

软件 (Mars)

Software 把应用更新、启动项管理和卸载清理放在一起。Updates 视图会检查 Sparkle、Homebrew Cask / Formula、Mac App Store 应用，支持的更新可在 App 内安装；macOS 要求跳转时会明确打开 App Store。

Startup 视图会列出 Login Items、Launch Agents、Launch Daemons 和后台项。支持的条目可以直接停用，也可以显示文件位置；Apple 管理的条目会引导到系统设置。

卸载时选择要移除的 App，Mole 会在十五个以上的 Library 子目录里查找残留，包括 Application Support、Caches、Preferences、Logs、Launch Agents、Launch Daemons、Login Items、Containers、Group Containers、Saved Application State 和 Input Methods。Dock 条目会自动清理，模糊或弱匹配的残留会保留在列表中但默认不勾选，方便先审查。

更新尽量在 App 内完成：Sparkle 和 Homebrew Cask 都在 Mole 里直接装；Mac App Store 走 CommerceKit，授权或超时失败时再回退到 App Store；其他 App 会被打开，交给它们自己的更新器接手。Cmd 点击可以把多个 App 加进同一批卸载，单项失败的会保留在列表里方便重试。

卸载根目录 /Applications/*.app 的 root 所有 bundle 时，本次运行期间只需授权一次管理员，之后不再重复要密码。Startup 视图里，能匹配到稳定 launchd 服务的登录项和已通过校验的 LaunchAgents / LaunchDaemons 由 Mole 直接切换；macOS 后台任务管理里没有清晰句柄的条目，则跳转到对应的系统设置页面。

优化 (Mercury)

默认维护任务，一键执行。非管理员任务静默运行，需要管理员权限的任务会合并到一次授权里。

Optimize 会先执行一段可见的「修复小毛病」流程，重启 Dock、输入法切换、iCloud Drive 同步、隔空投送、聚焦、通知中心等能自行恢复的系统服务。深度任务包括：重建 Quick Look、字体缓存和 Launch Services 垃圾回收；压缩 SQLite 数据库；清理 saved state、隔离事件和通知历史；修复损坏的偏好设置、Launch Agent、共享文件列表和孤立 Spotlight 规则；审查登录项；运行 periodic maintenance。

安全门控会跳过不合适的任务：浏览器打开时跳过字体缓存重建；DNS 或网络栈重置不属于默认维护集合。

检测到 VPN 活跃、蓝牙 HID 或音频、外接显示器或音频设备时，Optimize 也会主动跳过会改设备状态的任务；被跳过项在结果面板里给出原因，方便复核执行清单。

分析 (Jupiter)

整盘 Treemap 可视化。逐层下钻任意目录，查看每个层级的大小；密集或相近大小的项目会合并成摘要块，避免地图变成一屏碎片。

无法获取大小的条目（权限受限目录、TCC 保护容器）会显示重试选项，而非静默丢弃。根级保护目录（/、/Users、/Applications）不可删除。扫描结果缓存 24 小时，方便快速回看。

Treemap 上单击某个目录就能下钻进去，上方的路径栏可以跳回任意一级。左侧列表和真实 Treemap 色块都保留条目操作：打开或在 Finder 中显示，右键「移到废纸篓」并确认；摘要块只用于概览。Treemap 上每个色块的面积按字节比例分配，所以占空间最大的那几个永远在视觉上最显眼。

状态 (Sun)

一块 bento 面板集中展示健康评分、CPU、GPU、内存、电池或温度、磁盘、网络，以及根据硬件切换的风扇或温度卡片；每项指标附带 60 秒迷你图，支持的 Mac 会显示自动、降温、强冷三种风扇控制。

下方进程列表每秒更新。点击列头（名称、CPU、内存）排序。点击某行将它置顶，刷新时保持可见，方便持续监控特定进程。

五列（名称、PID、CPU、Power、内存）都支持点击排序，再点一次切换升降序。右键某行可以选择 Pin/取消置顶（跨刷新、跨重启都保留）、Terminate（先发 TERM，必要时回退到 KILL）、复制可执行文件路径。Battery 卡片里的 Top Drain 行可以直接点开，跳到对应进程的解释面板。

菜单栏 HUD

常驻 macOS 菜单栏的可选监视器，可以选择实时指标、精简图标，或随系统负载变化的小动物运动；弹层顶部显示健康评分加 chip / 内存 / macOS / 运行时间，下面是硬件卡片、支持设备上的风扇控制、Top 5 CPU 进程，以及 Clean Watch 累计统计。

弹层底部是常用工具：摄像头或麦克风被占用时会有隐私指示灯，Keep Screen On 可选时长（1 小时 / 4 小时 / 不限），Clean Screen 会把屏幕变成纯色，方便擦屏幕和键盘（可选辅助功能输入锁）；检测到可弹出的外接磁盘或磁盘镜像时，这里也会出现 Eject 按钮。全局快捷键随处唤出 Mole，隐藏 Dock 图标后即成纯菜单栏 App，整体在设置 → 菜单栏中配置。

按应用关闭隐私提醒。通知里出现应用名时，将鼠标移到 macOS 通知上，选择「不再提醒此应用」。之后可在「设置 → 菜单栏 → 通知 → 不再提醒的应用」恢复。纯摄像头提醒不会显示应用名，因为 macOS 不提供占用摄像头的应用身份，所以 Mole 不会给这类通知显示按应用关闭操作。

显示模式可在「小动物动画」和「双行指标」之间切换。两行指标可以分别从 CPU、内存、温度、磁盘、网络里挑选一项独立显示。小动物角色只是外观差异，不影响指标采样。

诊断

菜单栏 Help → 运行诊断…。Mole 生成只读的精简报告，覆盖 Mac 型号、macOS 版本、权限、近期操作、显示器、外接卷、网络、安全状态和运行环境。点 复制报告 可以贴到聊天；点 复制终端命令 可以生成完整支持包并私发邮件排查。

诊断检测五种状况：完全磁盘访问缺失、内存压力偏高、磁盘使用超过 90%、操作日志不可写、近期操作失败。每种状况链接到对应的 帮助页面 解决步骤。

设置

设置有三个分页。通用：界面语言（重启后生效）、开机时启动、隐藏 Dock 图标、许可证激活与设备管理，以及完全磁盘访问的快捷入口。维护：缓存删除方式（永久删除，缓存的默认项，或移到废纸篓）和保护清单（白名单）。电池养护在支持的 Mac 上运行时把内置电池保持在 75% 到 80%，减缓老化，需一次管理员授权。菜单栏：开启菜单栏监视器、选择小动物角色或切到指标读数、选择两行指标内容、在支持设备上配置风扇行为，给「菜单栏开关 / Keep Screen On / Clean Screen」分别录制快捷键，开关 Clean Screen 的辅助功能输入锁，开关隐私指示和 Keep Screen On 通知。许可证激活也可随时用 Cmd + Shift + L 打开。

CLI

安装

通过 Homebrew：brew install mole。通过脚本：curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash。运行 mo 打开交互菜单，或直接使用子命令。

共享命令（Mac App 也有）

mo clean

和 Mac App 相同的 10 类深度清理。支持 --dry-run 预览、--debug 详细日志、--whitelist 管理受保护缓存。自动跳过运行中 App 的缓存。

mo uninstall

交互式 App 选择 + 残留检测。显示 App 大小、bundle ID 和最后使用日期。查找和 Mac App 相同的十五类以上残留目录。支持 --dry-run。

mo optimize

运行 CLI 维护任务，需要管理员权限的任务会提示输入密码。它的具体任务集合可能和 Mac App 默认 Optimize 列表不同。支持 --whitelist 排除特定任务。

mo analyze

终端内交互式 Treemap。方向键或 Vim 键位（h/j/k/l）导航。可直接从地图删除文件。支持 --json 输出和自定义路径，如 mo analyze /Volumes 分析外置硬盘。

mo status

实时系统面板：CPU、GPU、内存、磁盘 I/O、网络、电池、温度、运行时间、健康评分和 Top 进程，附带 60 秒迷你图。支持 --json 输出，方便管道到其他工具。

CLI 独有命令

mo purge

查找项目目录里的旧构建产物：node_modules、target、.build、build、dist、venv。扫描可配置的路径（默认：~/Projects、~/GitHub、~/dev）。7 天内的项目标记为 "Recent"，默认不选中。支持 --dry-run 和 --paths 配置扫描目录。

mo installer

发现下载、桌面、Homebrew 缓存、iCloud 和邮件附件中的 .dmg、.pkg、.zip 安装包。按来源标注每个文件。支持 --dry-run。

mo touchid

为 sudo 命令启用 Touch ID。mo touchid enable 开启，mo touchid disable 关闭。支持 --dry-run。

工具命令

mo completion

设置 Bash 和 Zsh 的 Tab 自动补全。自动检测当前 Shell 并更新对应配置文件。

mo update

自更新到最新稳定版。--nightly 更新到 main 分支最新未发布构建（仅脚本安装）。--force 重新安装当前版本。

mo remove

从系统卸载 Mole CLI，包括配置文件和 Shell 集成。支持 --dry-run。

安全

CLI 和 Mac App 共享相同的安全原则：

路径保护。内置拒绝列表覆盖系统关键目录、用户目录核心结构，以及已知缓存位置之外的任何路径。符号链接在操作前会被解析和验证。

进程感知。运行中 App 的缓存在清理时被跳过。浏览器打开时不会清理其缓存。

许可证门控。Mac App 中每个破坏性工具（清理、卸载、优化、从分析页面删除）可免费使用 2 次，之后需要有效许可证。扫描始终免费。

白名单。CLI（~/.config/mole/whitelist）和 Mac App 都支持保护特定缓存或优化任务，使其在未来运行中被跳过。

操作日志。每次删除都记录在 ~/Library/Logs/mole/operations.log。Mac App 的诊断面板会检查日志健康状态并报告近期失败。

先预览。CLI 在每个破坏性命令上支持 --dry-run。Mac App 在任何操作前显示完整文件列表和字节数。

排错

Mac App 内置诊断功能，可检测常见问题。从菜单栏 Help → 运行诊断… 打开。各项检测的详细说明见 帮助页面。

CLI 在任何命令后加 --debug 可查看详细日志。操作日志位于 ~/Library/Logs/mole/operations.log。如果命令静默失败，检查系统设置中是否已授予完全磁盘访问权限。

反馈问题见帮助页面的 反馈问题 部分。