最近，我和 Codex 一起做了一个 macOS 磁盘空间工具，叫 SpaceJudge，现在已经开源。
它想解决的问题很简单：电脑的空间越来越少，我想知道到底被谁占了；找到一个很大的目录以后，我还想知道，应该怎么安全地处理它。
SpaceJudge 用嵌套的方块展示文件和目录的占用。你可以逐层往里看，也可以把选中的范围和扫描摘要交给 Codex，让它继续核查、制定清理方案。工具本身只读扫描，不删除文件，也不自动清理。
图中是专门准备的测试文件，不是个人磁盘数据。方块的面积表示占用，颜色只用于区分目录，不代表是否可以删除。本文介绍的是 v0.5.2 测试版。
#为什么想做这个工具
开发者的电脑里，很容易积累各种东西：项目的构建产物、依赖、模拟器、应用缓存，还有 Docker 的数据。
它们不一定出现在一个显眼的位置。等磁盘快满了，再去 Finder 里逐个检查文件夹，还是挺费劲的。
我喜欢 SpaceSniffer、GrandPerspective 这类工具的思路：把占用变成一张图。一个目录占得多不多，不必先读完一堆数字，看看方块的面积就知道了。
其实在 2024 年，我就写过一篇 GrandPerspective 的使用介绍。那时关注的是如何直观地找到大目录；这次，我想再往后走一步，把空间浏览和后续的核查、清理建议连接起来。
所以，SpaceJudge 的第一步不是做复杂的 AI 功能，而是把这个基础体验做好：界面简单，能逐层浏览，扫描时逐步看到结果，处理完以后可以刷新。
但“看见大目录”和“知道怎么清理”，仍然是两回事。尤其是应用数据、数据库、虚拟磁盘，看到它很大，并不意味着可以直接删掉。这也是我希望它能和 Agent 配合的原因。
#先选范围，再看最大的方块
打开软件，会先看到一个启动页。可以选择用户目录、Macintosh HD，也可以只扫描一个自己关心的文件夹，然后在系统选择窗口中确认范围。
第一次体验，我建议先选一个熟悉的小目录。没必要一上来就扫描整个磁盘，也不用为了查看一个项目，先收集电脑上所有文件的信息。
扫描过程中，已经发现的结果会逐步显示出来。想继续查看时，主要就是这几个操作：
- 单击目录方块，选中并原位展开。
- 双击进入目录，查看里面的占用。
- 用面包屑、返回或上一级，回到外层。
- 悬停看完整名称，右键查看信息或在 Finder 中定位。
文件夹少的时候，逐项看就很清楚。项目特别多时，如果把每个小文件都画成一个方块，画面会变成一堆碎片。因此，SpaceJudge 提供“概览”和“详细”两档显示，并适当合并密集的小项目。想进一步查看，可以进入目录或打开项目列表。
底部只保留一小条容量信息，显示所在磁盘的总容量、已用和剩余，同时标出当前目录的大小。磁盘剩余多少，与眼前这个目录有多大，是两个不同的问题。 扫描到的目录总量，也不一定能对齐整个磁盘的已用空间。
#找到了大目录，然后呢
举个例子：你发现 Docker 相关目录非常大。空间图已经告诉你问题集中在哪里，但接下来，是删缓存、移除镜像，还是整理某个容器里的数据？哪些东西会影响正在使用的环境？
仅凭目录名称和大小，工具不能替你做这个判断。
现在可以对文件或目录打开右键菜单，选择“用 Codex 分析…”。SpaceJudge 会先展示一个可检查的清理方案草稿，而不是直接把请求发出去。
这张图展示的是尚未发送的草稿，不是模型已经给出的清理结论。
我希望提供给 Agent 的，不只是“帮我分析一下这个目录”这句话，而是它真正需要的上下文：
- 这次要处理哪个范围，是否提供准确路径。
- 扫描是什么时候做的，已知占用和主要子项是什么。
- 数据有没有权限限制、未完成或截断的情况。
- SpaceJudge 有哪些只读工具，应该怎样补充核查。
- 目标是给出具体清理建议，同时说明前提、风险、备份和执行后的验证方式。
准确路径可以关闭，但关闭以后，Agent 就需要先和你确认位置。即使提供了路径，也不等于授权它清理，更不能只根据文件名判断“这个肯定可以删”。
点击“打开 Codex 草稿”后，需要在另行安装的 Codex 桌面应用里审阅并确认发送。SpaceJudge 不要求再单独登录，也不复制 Codex 的凭据。没有安装 Codex，可以复制草稿；单独使用空间图也完全没问题。
这里有一个重要的分工：SpaceJudge 提供占用事实，Agent 继续核查和提建议，用户决定是否执行。 删除、停止服务、重置、清理数据等操作，都需要另行明确授权。Codex 使用它自己的工具权限，SpaceJudge 的只读设计并不能限制外部 Agent 的行为。
以 Docker 为例，合理的建议应该先确认实际使用的环境和对象依赖，优先考虑应用自己的管理入口，而不是直接删除它的整个数据目录。空间图中的占用，也不能当成必然可回收的容量。
#处理完以后，刷新继续看
在其他工具里处理完目录后，回到 SpaceJudge，按 ⌘R，或点击顶部的刷新按钮。
刷新时会保留旧图和当前浏览位置，在后台重新扫描。完成后更新结果，尽量回到原来正在看的目录，并显示扫描范围的占用变化。
演示中只是把一个测试文件移到了扫描范围之外，所以范围占用减少了 8.4 MB。没有删除文件，也没有因此释放磁盘空间。
目前刷新会重扫最初选择的整个扫描范围，不是只重扫眼前的子目录。失败或取消刷新，不会用一个失败的新结果覆盖旧图。
我觉得这一步很重要。清理不该停在“命令执行成功”上，还应该回来看看：目标目录的占用有没有变化，磁盘可用空间有没有变化，接下来值得看的是哪个目录。
#给人一张图，给 Agent 一个工具
图形界面适合人来浏览；对本机 Agent 来说，CLI 往往更直接。
测试安装包自带原生命令行工具。安装到默认位置后，可以这样查看帮助，以及用户目录所在卷的容量：
sj_cli="/Applications/SpaceJudge.app/Contents/Helpers/spacejudge-agent-cli"
"$sj_cli" --help
"$sj_cli" volume --root "$HOME"这里的 volume 只查询所在卷的容量，不会自动扫描整个用户目录。
CLI 还支持对明确的目录重新扫描、查询进度、列出直接子项、寻找大项和查看扫描问题。容量同时提供精确字节与十进制 GB，方便程序处理，也方便人阅读。每次扫描使用自己的本地快照；CLI 的扫描不会自动更新 GUI，回到应用后仍然需要刷新。
项目另外提供可选的本地 MCP 适配器，供支持这类工具的客户端接入。它需要额外配置和目录授权，不是打开软件的前置条件，也不是让 ChatGPT 网页自动访问本机磁盘。具体命令和接入方式见 项目使用说明。
这不是说 Agent 有了工具，就一定能正确清理磁盘。它只是少了一些猜测：可以按范围拿到结构化的占用信息，必要时重新核查，而不是把一次截图当成完整、实时的事实。真实模型的建议质量仍需要继续验证。
#一分钟看看实际操作
下面是实际应用窗口录制的演示，约 51 秒，带中文字幕、没有音频，可以直接播放。流程是：选择范围、查看空间图、进入目录、准备 Codex 草稿、刷新结果。
演示使用合成测试文件，操作等待时间已经剪去，不是扫描速度测试。Codex 部分只展示未发送的草稿，也没有演示自动清理。
#下载与当前边界
源码和安装包都放在 GitHub 上，项目采用 MIT 许可证：
当前要求 macOS 14 或更高版本。DMG 包含 Apple Silicon 和 Intel 架构，但实机验收主要在 Apple Silicon 上完成，Intel 和其他 Mac 的下载安装体验还需要验证。下载时请选择发布页 Assets 中的 .dmg，源码压缩包不是可直接安装的应用。
这是未经过 Apple 公证的测试版，不是正式发行版。 安装包使用本地临时签名，不是 Developer ID 签名，首次打开可能被 macOS 拦截。只有确认来源可信时，才按 Apple 的单应用批准说明，在“系统设置 → 隐私与安全”中处理。不要为了安装它关闭系统安全保护；受管理的电脑也可能不允许打开。
还有几件事，使用前最好知道：
- 扫描读取文件系统元数据，不读取普通文件内容、不修改扫描对象；会在本机保存扫描快照，普通扫描不上传。
- 把草稿交给 Agent 时，可能包含文件名和路径，应先检查。公开截图或日志前也要注意隐私。
- 权限不足、取消扫描等情况会造成不完整结果；没有扫到的内容不等于没有占用。
- APFS 的共享块、克隆和快照等因素，会影响实际可释放空间。父目录和子目录的大小也不能重复相加。
- 目前没有实时变化监听、自动清理或一键删除，也没有做可用于宣传的跨工具性能对比。
底层使用 Swift、SwiftUI / AppKit、Core Graphics 和 SQLite。原生扫描、增量展示、快照查询和清晰的安全边界，是目前的实现重点。源码里保留了设计文档、测试和构建说明，后面可以继续完善。
对我来说，SpaceJudge 的方向很明确：先把空间看清楚，再把问题和上下文交给合适的工具，最后由自己做决定。
如果你也经常面对“这个目录怎么这么大，但我又不敢乱删”的问题，可以试试。欢迎反馈实际使用中的问题，也欢迎一起参与这个开源项目。
有问题请留言~
在 GitHub 查看讨论