功能文档

概览

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)

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

「启动项」视图会列出 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 里属于 root 的 App 时，本次运行期间只需授权一次管理员，之后不再重复要密码。「启动项」视图里，能匹配到稳定 launchd 服务的登录项和已通过校验的 LaunchAgents / LaunchDaemons 由 Mole 直接切换；macOS 后台任务管理里没有清晰句柄的条目，则跳转到对应的系统设置页面。

优化 (Mercury)

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

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

安全门控会跳过不合适的任务，每项任务只在确有需要时才执行，DNS 或网络栈重置不属于默认维护集合。

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

分析 (Jupiter)

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

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

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

状态 (Sun)

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

下方进程列表每秒更新，五列（名称、PID、CPU、能耗、内存）都支持点击排序，再点一次切换升降序。左键点某行打开它的解释面板，右键点某行可以固定或取消固定（固定的进程跨刷新、跨重启都留在顶部，方便一直盯着同一个 App）、终止（先发 TERM，必要时回退到 KILL）、复制可执行文件路径。电池卡片里最耗电的那一行也能直接点开，跳到对应进程的解释面板。

菜单栏 HUD

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

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

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

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

诊断

点窗口左上角的 Mole logo，选 运行诊断。Mole 生成只读的精简报告，覆盖 Mac 型号、macOS 版本、权限、近期操作、显示器、外接卷、网络、安全状态和运行环境。点 复制报告 可以贴到聊天；点 复制终端命令，在终端运行后会生成完整支持包，可以发邮件给我排查。

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

设置

设置有三个分页。通用：界面语言（重启后生效）、开机时启动、隐藏 Dock 图标、许可证激活与设备管理，以及完全磁盘访问的快捷入口。工具：缓存删除（「永久」是缓存的默认项，也可以改成「废纸篓」）和保护清单（白名单）。电池养护在支持的 Mac 上运行时把内置电池保持在 75% 到 80%，减缓老化，需一次管理员授权。菜单栏：开启菜单栏监视器、选择小动物角色或切到指标读数、选择两行指标内容、在支持设备上配置风扇行为，给「唤出 Mole / 保持常亮 / 擦屏幕」分别录制快捷键，开关擦屏输入保护（需要 macOS 的「辅助功能」权限），开关隐私提醒和屏幕常亮提醒。许可证激活也可随时用 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 默认的优化任务不同。支持 --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 内置诊断功能，可检测常见问题。点窗口左上角的 Mole logo，选 运行诊断 打开。各项检测的详细说明见 帮助页面。

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

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