Mole 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

Mole 是面向 macOS 的开源命令行清理与系统维护工具，命令入口为 mo。根据 README，它覆盖磁盘清理、应用卸载、磁盘分析、维护操作和实时状态监控；另有独立的 Mac 与 Windows 原生应用，原生应用与通过 Homebrew 安装的 CLI 并非同一产品。

仓库资料显示，项目主要语言为 Shell，许可证为 GPL-3.0，默认分支为 main。提供的 GitHub 元信息记录为 74,296 Stars、2,669 Forks；这些是资料中的仓库数据，不代表具体版本的兼容性或运行效果。

• macOS CLI 要求 macOS 12 或更新版本，支持 Intel 与 Apple Silicon。
• 安全预览可使用 --dry-run；README 明确提示多个命令具有删除文件的能力。
• 仓库同时包含 Windows CLI 与 Linux CLI 的安装入口，但其说明位于各自分支文档中。

定位与目标用户

本项目定位为终端中的本机维护工具，将若干清理和诊断操作集中到 mo 命令中。README 将其描述为结合清理、卸载、磁盘查看与系统状态工作流的工具，而不是单一的缓存删除脚本。

目标使用者包括需要检查磁盘占用、清理应用残留，或希望从终端执行基础系统维护的 Mac 用户。由于命令会处理本地文件，使用者应能识别待处理内容，并在执行删除类操作前审阅预览结果。

项目还提供 Windows 与 Linux CLI 文档入口，但本文重点依据 README 中明确给出的 macOS CLI 信息。各平台原生应用的功能、限制和许可信息，官方仓库未提供该信息，建议以最新 README 为准。

核心功能

各子命令针对不同的本地维护对象；触发方式是执行对应的 mo 子命令，具体扫描规则和输出细节应以运行时界面及 README 为准。以下说明仅陈述资料明确列出的用途，不推断未披露的内部算法。

对于会删除内容的命令，预览不是实际执行结果的替代品，而是供操作者核对候选对象的步骤。README 还提供 mo history 与 mo history --json 用于查看历史，但没有在所给资料中说明历史记录保存位置或保留策略。

系统架构与关键模块

从仓库资料可确认的外部结构，是一个 Shell 主语言项目，提供统一命令入口和多个子命令；Go 模块清单则表明项目同时包含 Go 模块及 TUI（终端用户界面）相关依赖。仅凭这些资料不能完整还原进程边界、模块目录或各命令的实现语言。

命令入口与操作边界

用户通过 mo 进入交互菜单或直接调用子命令，例如 mo clean、mo analyze 和 mo status。清理、卸载和维护操作各自有对应的命令入口，部分操作支持 --dry-run；这提供了按任务检查和执行的边界，但 README 未说明所有子命令是否共享同一套扫描器或执行引擎。

交互式磁盘分析

README 将磁盘分析描述为交互式 TUI，可查看磁盘使用情况、发现大文件并浏览目录。Go 模块清单列出 Bubble Tea 与 Lip Gloss，这些依赖名称与终端界面功能相符；依赖清单本身不能证明它们分别用于哪些页面或具体组件，因此这里不将其描述为已确认的模块映射。

系统状态采集

mo status 面向 CPU、内存、磁盘 I/O、网络和进程状态提供实时展示。Go 模块清单包含 github.com/shirou/gopsutil/v4，但提供的材料没有说明它与哪些指标采集路径直接对应，也未披露权限差异、平台适配细节或采样频率。

仓库目录树、内部 API、模块依赖图和执行流程文档均未包含在资料中。官方仓库未提供该信息，建议以最新 README 为准。

依赖与运行环境

macOS CLI 的最低系统版本和处理器支持范围在 README 中有明确说明。Go 模块清单还记录了 Go 版本及若干依赖，但这并不等同于已确认每位 CLI 用户都必须自行安装 Go；Homebrew 和脚本安装路径均由 README 提供。

Windows 与 Linux CLI 的 README 分别位于 windows 和 linux 分支入口。其具体系统版本、依赖条件及功能差异，官方仓库未提供该信息，建议以最新 README 为准。

快速开始

最小使用闭环是安装 CLI、执行一个无删除副作用的版本查询，并进入交互菜单确认命令可用。以下命令来自 README；Homebrew 安装需要本机已有可用的 Homebrew 环境，该前置条件的安装方法不在所给资料范围内。

# 1. 安装 Mole CLI
brew install mole

# 2. 查看已安装版本
mo --version

# 3. 打开交互式菜单
mo

其中，mo --version 输出已安装版本，mo 启动交互菜单。若要尝试清理功能，先执行预览命令并检查结果，不要把首次验证直接设为实际删除操作。

# 预览深度清理候选项，不执行删除
mo clean --dry-run

# 查看可用命令帮助
mo --help

预览命令本身不会完成实际清理；只有确认输出中的项目符合预期后，操作者才应决定是否执行实际命令。README 说明 Mole 会在需要管理员权限时请求权限，并建议不要以 sudo 运行 Mole。

配置说明

README 资料中可确认的配置入口主要是白名单、项目扫描路径和安装前缀，没有提供配置文件字段或环境变量清单。下表将这些入口与缺失项分开列出，避免把命令行选项误写成环境变量。

白名单和路径设置的交互方式、持久化格式及重置方法没有在所给资料中说明。实际配置时，应以对应子命令显示的界面和当前 README 为准，不要从表格中的默认值栏推断未记录的行为。

进阶用法

进阶使用的重点是将预览、路径范围和安装来源纳入操作流程。下面列出的命令均来自 README，适用于本机维护；清理范围仍应由操作者逐项核对。

按任务预览

多个会更改或删除内容的命令支持 --dry-run。预览后可以再加 --debug 获取清理过程的详细日志，或使用历史查询检查已有操作记录。

# 分别预览应用卸载、系统优化和项目产物清理
mo uninstall --dry-run
mo optimize --dry-run
mo purge --dry-run

# 预览清理并显示详细日志
mo clean --dry-run --debug

# 查看操作历史及 JSON 格式结果
mo history
mo history --json

限定磁盘分析路径

磁盘分析命令可接收目标路径，README 示例分别面向外部卷和用户拥有的临时目录。限定路径有助于把检查目标表达清楚，但资料未说明所有路径类型是否均可访问，也未声明输出会包含哪些元数据。

# 分析外部卷
mo analyze /Volumes

# 检查用户拥有的临时目录
mo analyze /private/tmp

安装来源与更新策略

脚本支持指定发布标签或使用 main 安装开发分支代码。README 明确指出 main 包含尚未发布的代码，可能有粗糙之处；latest 是旧别名，实际指向 main，并不表示最新稳定版本。

若希望避免日常更新时因安装位置要求管理员密码，README 给出将脚本安装到用户目录并调整 PATH 的做法。需要修改系统所有者文件的命令仍可能请求管理员权限。

可观测性与运维

CLI 的运行观察入口包括实时状态页面、操作历史、帮助信息和版本查询。它们分别用于查看当前机器指标、回顾操作记录、查阅命令选项及确认安装版本；资料未声明远程监控、指标导出、告警或集中管理能力。

• mo status：查看 CPU、内存、磁盘 I/O、网络流量与进程状态。
• mo history：查看操作历史；mo history --json 请求 JSON 格式输出。
• mo --help 与 mo --version：查看帮助和已安装版本。
• mo update：更新 Mole；脚本安装可用 mo update --nightly 跟踪最新未发布的 main 构建。
• mo completion：设置 Shell Tab 补全。

运维时应记录安装来源、是否跟踪开发分支以及清理操作使用的预览结果。上述记录建议属于根据本文作者的经验判断；README 未提供组织级运维规范、日志保留期限或自动化调度指南。

安全与合规边界

Mole 会访问并可能删除本机文件，安全边界主要落在路径校验、系统位置保护、操作者确认和权限提升上。README 表示，当工具无法确认某项内容可安全更改时，会跳过或拒绝处理。

• 对 clean、uninstall、purge、installer、slim 和 remove，README 建议先使用 --dry-run；需要进一步检查时可加入 --debug。
• 不要使用 sudo 启动 Mole；README 说明需要管理员权限的操作会自行请求。
• 操作前应核对目标路径、应用名称和候选文件，尤其是在系统维护与应用卸载场景中。
• 清理个人或组织设备前，应确认自己有权管理相关数据，并遵守设备所属组织的数据保留政策。

后两项属于根据本文作者的经验判断。README 未提供企业数据分类、隐私数据处理规范、审计合规认证或集中审批机制；此类要求应由设备所有者按本地政策评估。

许可证与商用条款

仓库元信息与 LICENSE 文件表明，项目使用 GNU General Public License（GNU 通用公共许可证）版本 3，即 GPL-3.0。GPL-3.0 不因软件免费提供而禁止收费分发；不过，复制、修改和分发时须遵守许可证正文规定的条件。

LICENSE 前言说明，许可证允许用户运行未修改程序，并规定分发或修改相关作品时的义务；具体义务取决于你如何传播程序、提供源代码及处理修改版本。商用本身不能仅凭许可证名称判断全部法律义务，使用者应依据实际分发方式阅读完整 LICENSE。

若分发程序副本或基于项目制作并分发修改版本，须按 GPL-3.0 的适用条款处理许可证文本、版权信息、源代码提供及修改版本标识等事项。许可证的具体适用范围与履行方式，以仓库 LICENSE 为准；该说明不构成法律意见。

局限性与已知限制

已确认的限制集中在平台版本门槛、开发分支稳定性和部分功能信息缺失。下列未披露项目不应被当作产品保证或缺陷结论。

• macOS CLI 要求 macOS 12 或更新版本；低于该版本的支持情况没有由资料确认。
• 通过 Homebrew 安装的是 CLI，不包含独立的 Mac 原生应用。
• 安装 main 会获取未发布代码；README 提醒该分支可能存在粗糙之处。
• 性能基准、清理速度、空间回收量、资源开销、支持文件数量及错误率均未在资料中提供。
• 历史记录的保存位置、保留时长、状态指标采样周期和输出接口未在资料中提供。
• 各平台的完整功能对照、应用兼容清单及故障恢复机制未在资料中提供。

对于上述空缺，官方仓库未提供该信息，建议以最新 README 为准。不能据此推定功能不存在，也不能推定未说明的能力已经获得支持。

适合谁 / 不适合谁

是否采用该工具，应由操作对象、平台版本、权限流程和维护方式决定。以下信号仅依据仓库明确公开的命令与行为整理，适用于使用前的筛选。

适合的使用者

• 使用 macOS 12 或更新版本，且需要在 Intel 或 Apple Silicon Mac 上运行 CLI 的个人用户。
• 希望从终端检查磁盘目录、大文件、应用卸载残留或项目构建产物，并愿意在执行前审阅预览结果的人。
• 需要通过 mo status 查看本机 CPU、内存、磁盘 I/O、网络和进程状态的人。
• 能自行判断要处理的本地文件，并接受需要时由工具请求管理员权限的设备维护者。
• 需要阅读或修改 GPL-3.0 项目源码，并愿意按许可证条件分发修改版本的开发者。

不适合的使用者

• 运行低于 macOS 12 的 Mac，且将兼容性视为硬性要求的使用者。
• 需要无人值守、批量审批、企业集中策略或服务等级承诺，但要求这些能力已由项目明确保证的团队；资料未提供相关保证。
• 不能接受本机清理命令触及文件，或无法审阅预览结果的设备使用者。
• 只需要独立 Mac 原生应用，却误将 brew install mole 当作原生应用安装来源的用户；README 说明该命令只安装 CLI。
• 不能接受 GPL-3.0 分发条件，且计划对项目修改版本进行分发的组织；应先评估许可证义务。

常见问题与排查（FAQ / Troubleshooting）

排查时先区分安装来源、平台版本和实际调用的命令，再对照帮助与预览输出。资料没有给出完整错误码表或故障诊断手册，因此以下回答只覆盖 README 明确提及的情形。

为什么安装 Homebrew 包后没有 Mac 图形应用？

brew install mole 安装的是免费开源 CLI。README 将 Mole for Mac 描述为单独下载的原生应用，因此不能把 CLI 安装结果当作原生应用已安装的证据。

命令需要管理员权限时应如何处理？

不要以 sudo 运行 Mole。README 说明需要管理员权限的操作会请求管理员权限；若某项操作被拒绝或跳过，先确认目标路径与当前用户权限，不要通过扩大执行范围来替代检查。

如何确认删除类操作将处理哪些内容？

先运行对应的 --dry-run，检查候选项；必要时加 --debug 查看清理的详细日志。README 还建议使用 mo history 查看历史记录，但未说明历史记录的完整保留策略。

如何判断安装的是稳定发布版本还是开发分支？

可以查看安装时采用的来源，并运行 mo --version 查询已安装版本。README 指出，脚本参数 main 安装默认分支的未发布代码，latest 是指向 main 的旧别名，并非最新稳定版。

脚本安装时如何减少后续更新对管理员密码的依赖？

README 示例将安装位置设为用户拥有的 $HOME/.local/bin，并把该目录加入 PATH。系统所有者文件相关操作仍可能请求管理员权限，调整安装目录并不能取消该权限边界。

遇到未记录的错误或功能差异怎么办？

先运行 mo --help 查看当前版本提供的命令，再核对对应平台 README 与安装分支。错误码、日志文件路径、支持矩阵及自动修复步骤，官方仓库未提供该信息，建议以最新 README 为准。

项目地址与资源

以下链接均来自仓库资料，用于查阅源码、CLI 文档及项目官方入口。Windows 与 Linux CLI 文档分别位于对应分支的 README 页面。

• Mole GitHub 仓库
• Mole 官方网站与文档
• Mole Windows CLI 文档
• Mole Linux CLI 文档
• Mole 发布版本页面
• Mole Agent 安装说明
• Mole README
• Mole GPL-3.0 许可证文本