1. 项目概述一个真正懂AI开发的Mac清理工具如果你是一名在Mac上折腾AI开发的程序员那你一定对硬盘空间被无声吞噬的痛楚深有体会。今天要聊的这个项目MacSweep就是为解决这个痛点而生的。它不是另一个CleanMyMac也不是OnyX的翻版而是一个由开发者写给开发者的、真正理解现代AI工作流的清理工具。它的核心很简单用一行bash脚本精准地清理那些传统清理工具根本“看不见”的垃圾——比如你拉取的几十GB的Ollama模型文件、Claude Desktop和Cursor IDE堆积如山的缓存、以及各种AI工具卸载后残留的配置和日志。我最初发现它是因为我的256GB MacBook Pro在安装了Ollama、尝试了几个大语言模型后系统盘直接飙红。用遍了市面上的清理工具它们都只能清理常规的浏览器缓存和系统日志对~/.ollama/models/blobs/目录下那几十个GB的模型文件视而不见。MacSweep的出现让我第一次找回了被AI工具“吃掉”的几十GB空间。它免费、开源、无任何遥测、100%本地运行这些特性在当下显得尤为珍贵。无论你是刚入门AI的开发者还是硬盘常年告急的重度用户这个工具都能让你对Mac的存储空间有全新的掌控感。2. 核心设计理念与差异化优势2.1 为什么现有的清理工具都“失明”了传统的Mac清理工具其清理逻辑大多停留在五到十年前的应用生态。它们擅长处理~/Library/Caches、浏览器缓存、邮件附件这些通用型垃圾。然而过去几年以AI为核心的开发工具链爆炸式增长完全绕开了传统的应用沙盒和缓存管理机制。以Ollama为例它默认将模型文件存储在用户主目录下的隐藏文件夹.ollama中。这些.bin或.gguf格式的模型文件动辄数GB甚至数十GB在系统看来它们就是普通的用户数据文件而非“缓存”或“垃圾”。同样像Cursor、Claude Desktop这类基于Electron或本地服务的AI工具它们的会话日志、索引缓存、临时模型数据也都散落在~/Library/Application Support/或~/.config/的各个角落。对于CleanMyMac这类商业软件来说识别并安全清理这些特定于某个开源命令行工具或某个新兴IDE的数据其维护成本和风险太高因此它们选择性地“忽略”了这片领域。MacSweep的设计哲学就是填补这片空白。它不追求大而全而是追求“精准打击”。它的模块化设计尤其是独立的ai模块就是专门为识别和清理这些新兴AI工具的数据而构建的。这背后是一个简单的逻辑工具的开发者社区最了解自己的工具会产生什么垃圾。MacSweep作为一个开源项目可以快速响应社区需求为新的AI工具添加清理规则这是任何闭源商业软件都无法比拟的敏捷性。2.2 隐私与安全的底层设计在数据即黄金的时代一个清理工具本身是否可信比它能清理多少空间更重要。MacSweep在隐私和安全上的设计堪称“偏执”。零遥测与100%本地化整个项目就是一个523行的Bash脚本和一个静态HTML仪表盘。你可以用任何文本编辑器打开macsweep.sh从头到尾审阅每一行代码。它没有任何网络请求不收集任何使用数据不依赖任何外部API。所有配置YAML格式和历史记录JSON格式都明文存储在本地~/.config/macsweep/目录下。这意味着即使你断网它也能完美工作且你的所有操作记录都不会离开你的电脑。“安全第一”的操作模式这是我在实际使用中最欣赏的一点。它默认采用“交互式”运行即每进行一个可能具有破坏性的操作比如删除某个目录前都会请求你的确认。更关键的是它引入了--dry-run干跑模式。在这个模式下工具会模拟整个清理过程详细列出每一个将要被删除的文件和目录以及预计能释放的空间但不会执行任何实际的删除操作。这给了用户一个绝对安全的“预览”机会。对于最高风险的操作比如删除Ollama的模型文件或重置Docker的数据MacSweep设置了双重保险首先这些操作被归类为“深度清理”Deep Clean其次你必须显式地加上--deep参数才能解锁这些功能。即使使用了--deep在非--auto自动模式下它依然会要求你二次确认。这种层层递进的安全机制有效防止了误操作。权限最小化原则整个脚本运行在用户权限下从不请求sudo权限。它的清理范围严格限定在用户的主目录~内绝不会触碰/System、/Library系统级或/Applications里的内容。这从根源上杜绝了因权限过高而误删系统文件的风险。3. 详细安装与初始化配置3.1 一键安装与背后原理官方推荐的一键安装命令非常简洁/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/royaluniondesign-sys/MacSweep/main/install.sh)这条命令做了以下几件事下载安装脚本使用curl从GitHub仓库拉取install.sh脚本。-fsSL参数组合确保了安静、跟随重定向、安全的下载。执行安装脚本通过/bin/bash -c来执行下载的脚本内容。我建议在运行前可以先看一眼这个安装脚本做到心中有数curl -fsSL https://raw.githubusercontent.com/royaluniondesign-sys/MacSweep/main/install.sh你会发现这个安装脚本本身也很简单。它的核心逻辑是定位主脚本找到项目中的cli/macsweep.sh。选择安装路径优先尝试安装到/usr/local/bin需要该目录有写权限如果失败例如在有些严格管理的企业环境则回退到用户本地目录~/.local/bin并提示用户将该目录加入PATH。创建配置目录在~/.config/macsweep/下创建必要的目录结构并写入默认的config.yaml配置文件。部署仪表盘将web-ui/目录下的单文件HTML仪表盘复制到配置目录中。整个安装过程不依赖Homebrew、Node.js或任何其他包管理器真正做到开箱即用。安装完成后直接在终端输入macsweep --version验证即可。3.2 手动安装与自定义部署对于网络环境特殊或者希望完全掌控安装过程的用户手动安装是更好的选择。git clone https://github.com/royaluniondesign-sys/MacSweep.git cd MacSweep # 你可以在此处审查所有代码 sudo cp cli/macsweep.sh /usr/local/bin/macsweep chmod x /usr/local/bin/macsweep mkdir -p ~/.config/macsweep cp -r web-ui ~/.config/macsweep/dashboard cp config.example.yaml ~/.config/macsweep/config.yaml手动安装让你有机会在复制文件前仔细阅读macsweep.sh的每一行代码这也是开源软件的魅力所在。你可以清楚地看到所有它打算访问的路径和将要执行的操作。3.3 初始配置解读与调优安装后配置文件位于~/.config/macsweep/config.yaml。理解默认配置是安全使用的第一步。version: 1 modules: system_caches: true browser_caches: true dev_tools: true ai_tools: true # 核心模块控制是否清理AI工具缓存 containers: true duplicates: true downloads: true schedule: enabled: false # 默认不启用定时任务 frequency: weekly day: sunday time: 03:00 notifications: enabled: true disk_warning_threshold: 90 # 磁盘使用超过90%时触发警告 deep_clean: ollama_models: false # 危险操作默认关闭需--deep开启 docker_reset: false # 危险操作默认关闭需--deep开启 exclude: paths: - ~/Documents/Important # 排除重要目录永不清理 extensions: - .important # 排除特定后缀文件配置调优建议首次使用建议先将ai_tools和deep_clean下的选项设为false仅启用system_caches、browser_caches等相对安全的模块进行初体验。排除列表务必在exclude.paths中添加你绝对不想被触碰的目录比如代码仓库、工作文档、创意素材库的路径。这是防止误删的最终保险。通知阈值disk_warning_threshold可以根据你的硬盘容量和使用习惯调整。对于256GB的硬盘可能设置为85%更敏感对于1TB的硬盘90%或95%可能更合适。4. 核心功能模块深度解析与实操4.1 AI工具清理模块精准定位“空间杀手”这是MacSweep的灵魂功能。我们深入看一下ai模块具体追踪哪些路径以及背后的考量。Ollama (~/.ollama/models/blobs/): 这是模型二进制文件的存储地。重要提示默认清理无--deep参数只会清理日志和临时文件不会动blobs里的模型。只有使用--deep时才会扫描并询问是否删除未使用的模型层layer。实际上Ollama自身有ollama rm model-name命令来删除模型MacSweep的--deep模式提供了一种批量和自动化的可能性但需极其谨慎。Claude Desktop (~/Library/Application Support/Claude/Cache/): Anthropic官方桌面应用产生的缓存主要是对话历史、附件预览等随时间积累可达数GB。Cursor (~/.cursor/Cache/): 这个基于VS Code的AI IDE会缓存大量的语法树、索引和模型推理中间数据清理它通常能安全回收几个GB空间。OpenCode / Gemini CLI等: 这些工具通常处于快速迭代中其缓存目录结构可能变化。MacSweep的社区驱动模式能较快跟进。如果遇到它未覆盖的新兴AI工具你可以手动将其缓存路径添加到配置文件的exclude列表以防误删或者向项目提交PR。实操心得运行macsweep --modulesai --dry-run是我每周的例行检查。它能清晰地列出每个AI工具缓存的大小。我发现自己经常忘记关闭Claude Desktop导致其会话缓存快速增长。通过这个命令我可以直观地看到是哪个工具成了“空间大户”从而决定是清理缓存还是审视自己的使用习惯。4.2 开发工具与容器清理dev和containers模块对于全栈或后端开发者至关重要。npm/pip缓存包管理器的缓存旨在加速二次安装但长期不清理会变得非常庞大。MacSweep的清理逻辑类似于npm cache clean --force和pip cache purge但以统一的方式执行。Xcode DerivedData每个iOS/macOS项目编译都会在这里生成大量中间文件。Xcode本身提供了清理功能在Preferences Locations里但MacSweep将其自动化了。Docker/Podman这是释放空间的“大招”。docker system prune -a命令可以清理所有未使用的镜像、容器、网络和卷但MacSweep做得更谨慎。它的containers模块在默认模式下只清理一些日志和临时层。真正的“大扫除”对应docker system prune被放在了deep_clean.docker_reset选项下并且需要--deep参数。关键安全机制脚本会先检查Docker Daemon是否在运行docker info如果正在运行则会跳过清理避免对正在使用的容器造成影响。注意事项在清理Docker前务必确保所有重要的容器数据已经通过Volume或绑定挂载bind mount持久化到了主机目录。清理镜像会迫使你下次运行容器时重新拉取可能会花费一些时间。4.3 系统、浏览器及杂项清理system_caches、browser_caches、duplicates、downloads这几个模块提供了基础的清理能力类似于一个轻量级的、可脚本化的CleanMyMac核心功能。浏览器缓存覆盖了Chrome、Safari、Firefox、Brave和Arc。清理是安全的但会导致下次打开网站时重新加载部分资源首次加载可能会稍慢。下载文件夹清理这是一个非常实用的功能。它基于文件“年龄”进行清理.dmg和.pkg安装包超过30天.zip压缩包超过60天。这个逻辑很合理因为安装包在运行后通常就不再需要而压缩包可能包含需要长期保存的归档。你可以根据自身习惯在配置中调整这些天数。5. 命令行与仪表盘的高级用法5.1 CLI命令组合实战指南MacSweep的CLI设计非常符合Unix哲学命令可以灵活组合。场景一安全初探与针对性清理# 第一步全面分析不执行任何删除 macsweep --analyze # 输出类似AI Tools: 26.4 GB, Containers: 18.1 GB, System Caches: 5.3 GB... # 第二步针对最大头AI工具进行干跑预览 macsweep --modulesai --dry-run # 仔细阅读输出确认将要删除的文件列表你是否真的不需要。 # 第三步执行清理假设你确认了 macsweep --modulesai --auto # 使用--auto跳过确认提示适合在确认无误后快速执行。场景二深度清理与数据备份# 计划进行深度清理包括Ollama未用模型和Docker系统 # 1. 首先备份你的Ollama模型列表如果需要 ollama list # 2. 干跑预览深度清理的影响 macsweep --deep --dry-run # 注意观察输出中关于Ollama models和Docker的部分。 # 3. 交互式执行深度清理会多次要求确认 macsweep --deep # 对于每一个危险操作脚本都会停下来问你“Are you sure? (y/N)”。场景三集成到自动化脚本或CI/CD# 静默模式运行仅清理开发和容器缓存适用于夜间自动化任务 macsweep --modulesdev,containers --auto --silent # --silent参数使得脚本没有任何输出只通过退出码表示状态0成功非0失败。 # 在GitHub Actions的自托管Mac Runner上可以作为前置步骤 # .github/workflows/ci.yml 片段 - name: Cleanup disk space if: runner.os macOS run: | macsweep --modulescaches,dev --auto --silent || echo Cleanup completed (or had nothing to do)5.2 Web仪表盘可视化的空间管理虽然CLI强大但Web仪表盘提供了更直观的管理界面。通过macsweep --ui命令打开。仪表盘主页以一个环形图直观展示各类型文件占用的空间比例。下方有“立即清理”按钮和清理历史记录。这个视图能让你快速了解空间被谁占用了。模块管理在这里你可以图形化地启用或禁用每一个清理模块。更棒的是每个模块旁边会显示“预计可释放”的空间大小这个数据来源于最近一次--analyze的结果。你可以像点菜一样勾选你想清理的类别。计划任务这是将MacSweep从手动工具升级为自动管家的关键。你可以设置每日、每周或每月在特定时间比如凌晨3点自动运行清理。启用后它会为你创建一个macOS的LaunchAgent~/Library/LaunchAgents/com.macsweep.daemon.plist。这个守护进程只会在预定时间触发一次macsweep --auto --silent命令完成后就退出没有常驻内存的开销。历史记录所有手动或自动的清理操作都会被记录包括时间、清理的模块和释放的空间大小。这个日志对于追踪空间变化趋势、或者排查“我的文件怎么不见了”的问题非常有帮助。个人体会我通常用CLI做一次性的深度检查和清理而将每周日的凌晨设置为自动清理浏览器缓存和系统日志。仪表盘的历史记录功能让我能验证自动任务是否如期运行。6. 安全模型、排错与高级技巧6.1 深入理解安全边界与“后悔药”即使工具设计得再安全误操作的风险依然存在。理解MacSweep的安全边界和恢复可能性至关重要。什么是MacSweep绝对不会做的这是它的安全红线不碰系统文件绝不删除/System、/private、/Library系统级或/Applications下的任何内容。不碰用户核心数据默认配置和逻辑下它不会进入~/Documents~/Pictures~/Movies等标准用户文件夹去删除你的文档、照片、视频。不请求高级权限整个脚本以当前用户权限运行无法删除需要root权限的系统文件。不联网没有任何数据上报或检查更新的网络请求。“后悔药”在哪里MacSweep本身不提供回收站或撤销功能因为它直接调用rm -rf。但我们可以利用macOS和工具自身的特性来构建安全网Time Machine这是最强大的后悔药。确保你的Time Machine备份是开启的。一旦误删可以从时间点恢复。Dry-Run是黄金准则在执行任何不带--dry-run的命令前养成先干跑预览的习惯。把输出仔细看一遍。配置排除列表在config.yaml的exclude.paths中提前加入你的工作目录、项目文件夹等重要路径。这是最主动的防护。审计日志每次运行无论是否实际删除MacSweep都会在~/.config/macsweep/logs/目录下生成一个带时间戳的日志文件。里面记录了它扫描过的所有路径和执行的每一个操作。如果发生意外这是第一手的调查资料。6.2 常见问题与排查实录在实际使用和与社区交流中我遇到过一些典型问题这里分享排查思路。问题一运行macsweep命令提示“command not found”。原因安装路径未加入系统的PATH环境变量。排查执行echo $PATH检查是否包含/usr/local/bin或~/.local/bin。解决如果安装在/usr/local/bin通常PATH已包含。若没有在~/.zshrc如果使用Zsh或~/.bash_profile如果使用Bash中添加export PATH/usr/local/bin:$PATH然后重启终端或执行source ~/.zshrc。如果安装在~/.local/bin则需要手动添加该路径到PATH。问题二仪表盘macsweep --ui无法打开或显示空白。原因浏览器因本地文件安全策略阻止加载本地JavaScript模块。排查直接使用命令行打开HTML文件open ~/.config/macsweep/dashboard/index.html。查看浏览器控制台Developer Tools是否有CORS或模块加载错误。解决最简便的方法是使用一个简单的本地HTTP服务器来托管这个仪表盘文件。在终端进入仪表盘目录并运行python3 -m http.server 8080 --directory ~/.config/macsweep/dashboard然后在浏览器中访问http://localhost:8080。你也可以将这一步封装成一个简单的别名或脚本。问题三清理后某个应用程序如浏览器启动变慢或出现异常。原因清理了该应用的缓存导致首次启动时需要重建缓存。排查这通常是预期内的行为。检查MacSweep的历史日志确认清理了该应用的缓存目录。解决无需特别处理应用在正常使用一段时间后会重新生成缓存。如果某个应用的缓存你不想被清理可以在配置文件的exclude.paths中添加其缓存目录的完整路径。问题四计划任务没有按预期执行。原因LaunchAgent的配置、权限或加载可能有问题。排查检查plist文件是否存在ls -la ~/Library/LaunchAgents/com.macsweep.daemon.plist检查其是否被加载launchctl list | grep macsweep查看系统日志log show --predicate subsystem com.apple.launchd --last 1h | grep -i macsweep解决可以尝试手动卸载再重新启用计划macsweep --scheduleoff macsweep --scheduleweekly --time03:00确保你的Mac在计划任务时间点没有休眠。如果休眠了LaunchAgent会在下次唤醒后执行。6.3 高级技巧扩展与自定义MacSweep的开源性允许你对其进行扩展以适应你的特殊需求。技巧一添加自定义清理规则假设你使用一个叫MyAITool的新工具它的缓存位于~/.myaitool/cache。你可以通过修改本地的macsweep.sh脚本来添加支持。找到module_ai()函数在适当位置添加类似下面的代码块# 在 module_ai 函数内 local myai_cache$HOME/.myaitool/cache if [[ -d $myai_cache ]]; then log_info Found MyAITool cache if do_clean $myai_cache MyAITool cache; then # 可选删除后执行一些额外命令比如重置应用状态 # command_to_reset_myaitool fi fi重要提示修改前备份原脚本并且清楚自己在做什么。更好的方式是为项目提交Pull Request让所有用户受益。技巧二与环境变量集成MacSweep支持环境变量覆盖配置这在容器化或临时性任务中很有用。# 一次性清理跳过所有确认并启用深度清理模式 MACSWEEP_AUTO1 MACSWEEP_DEEP1 macsweep --modulesai,containers # 使用自定义配置文件路径 MACSWEEP_CONFIG/path/to/my_config.yaml macsweep --dry-run技巧三与cron结合实现更灵活的定时任务虽然MacSweep自带了LaunchAgent调度但有些用户可能更喜欢传统的cron。你可以创建一个cron任务例如每天凌晨2点清理开发缓存# 编辑当前用户的crontab crontab -e # 添加一行 0 2 * * * /usr/local/bin/macsweep --modulesdev,caches --auto --silent ~/.macsweep_cron.log 21这样你就可以在自定义的日志文件~/.macsweep_cron.log中查看每次自动运行的结果。经过几个月的深度使用MacSweep已经成了我Mac维护工具箱中不可或缺的一员。它解决了一个非常具体且迫切的痛点——管理AI时代开发工具产生的“数据废气”。它的成功不在于功能有多繁杂而在于定位足够精准设计足够克制安全机制足够完善。对于一个523行的Bash脚本能达到如此实用度和完成度我对其开发团队充满敬意。如果你也受困于Mac存储空间尤其是被各种AI和开发工具缓存所占据那么花十分钟尝试一下MacSweep很可能会有意想不到的收获。记住第一次使用时务必带上--dry-run这个“安全绳”。