Wipecraft 的工作原理

日常使用

你的工作原地不动

存有进行中工作的行会被锁定。你能看到它们，但无法选择。

• Claude Code 或 Codex 运行时：它打开的会话、它在过去 24 小时内更改的所有内容，以及它所在的 worktree。
• Cursor 打开时，Cursor 的缓存。
• 有未提交更改的 worktree、过去 7 天内有更改的 worktree，或提交不在主分支或远程仓库上的 worktree。
• 已启动的模拟器。
• Claude Desktop 的当前沙盒镜像。

默认不选中任何内容。“选择推荐项”只会选中“可放心移除”和“会再出现”中的项目，绝不会选中“由你决定”中的项目。

扫描只读取。有一项测试会在完整扫描前后比较测试主目录下的每个文件，并在命令行的 scan 和 status 之后再比较一次。

7 天的反悔时间

没有任何 App 会重新创建的文件，在你移除时会进入同一磁盘上的隔离区。每一行都显示“剩余 N 天”和“恢复”按钮。7 天后，隔离区会在 Wipecraft 下次打开或运行每日检查时自动清空。如果你今天就需要这些空间，“立即清空”会在第二次确认后释放它。

有三类操作不经过隔离区。

• 对应 App 会自行重新创建的缓存、日志和临时文件会被直接移除。它们无法恢复，行或卡片会在你确认之前说明这一点。Wipecraft 只对已知会被 App 重新创建的文件夹和文件这样做。凡是不确定会由哪个 App 重新创建的内容，一律进入隔离区。
• worktree 通过 git 移除，其分支保留在仓库中。
• 少数工具命令标为“不可撤销”，Wipecraft 会说明是哪些命令，并再次询问你。

有些缓存会留在隔离区，因为对应工具不会自行把它们找回来：JetBrains 和 Android Studio 的缓存（其中也包含 IDE 的本地历史记录）、Maven 和 Go 模块，以及 Library/Caches 中的工具数据，例如 Poetry 环境、Playwright 和 Cypress 浏览器以及 llama.cpp 模型。

会话历史记录不会被删除，而是移入可恢复的压缩归档。

有内容变大时会通知你

“监控”默认关闭，由你决定是否开启。开启后，菜单栏中会显示一个图标，Wipecraft 每天在你选择的时间检查一次。出现以下情况时会通知你：

• 某个项目在 7 天内增长 2 GB 或以上，
• 磁盘可用空间不足 10%，
• 1 GB 或以上的 worktree 或模拟器已 7 天未被使用，
• 上次时间机器备份已超过 7 天。

退出 App，一切都会停止。

你设定的规则与筛选

清理规则是可选的。在你于“设置 > 自动清理”中添加规则之前，没有任何规则。

• 规则指定来源、项目需未使用的天数（7 到 365）和最小大小。
• 每日检查后，符合规则的项目会移到隔离区或归档，并由一条通知告诉你数量。
• 规则会跳过已锁定的行。规则从不运行命令，从不移除 worktree，也从不执行任何无法撤销的操作。被直接移除的缓存不属于计划清理；规则只会选取移到隔离区或归档的项目。
• 规则只在“监控”开启时运行。
• 没有许可证时，规则不会移动任何内容。如果某条规则本来会移动内容，Wipecraft 每天会告诉你一次清理未运行。

每个结果列表都可以按项目未被使用的时长、来源和安全级别筛选。筛选会隐藏行，并将它们移出所选内容。

从不碰未推送的工作

对于 git 仓库仍然存在的 worktree，只有当它的提交在别处也有一份时，才会建议移除。唯一的例外是仓库已不存在的 worktree，见最后一点。

• 它的提交必须在主分支或某个远程分支上。否则该行会被锁定，原因为 “其提交尚未进入主分支或远程仓库。”
• 上次推送之后的新提交会让它保持锁定。
• squash 合并会在主分支上产生新的提交，因此该分支自己的提交永远不会出现在主分支上。如果 GitHub 显示该分支的 pull request 已合并，Wipecraft 会解除这一项锁定。它通过你自己的 gh 登录查询，仅在已安装 gh 且已登录时进行，你也可以在“设置 > 隐私”中关闭它。未提交的更改仍会锁定该 worktree。
• 在移除 worktree 之前，Wipecraft 会再检查一次。如果提交已不在主分支或远程仓库上，或者 pull request 不再显示为已合并，它不会移除任何内容。
• 主仓库已被移动或删除的 worktree 无法由 git 检查。Wipecraft 仅在它 30 天（默认值）无更改后才会提供它，并将整个文件夹移到隔离区，可用“恢复”找回。

移除 worktree 时保留你的 .env

git worktree remove 会删除整个文件夹，包括 git 忽略的文件：.env、本地数据库和编辑器设置。Wipecraft 会先把这些文件移出来。

• 移除 worktree 之前，Wipecraft 会将其中被忽略且不属于构建产物的文件移到隔离区，保留 7 天。构建产物（如 node_modules 和 target）会随 worktree 一起删除。
• 在你确认之前，该行会显示有多少个文件会进入隔离区。
• 如果 git 拒绝移除该 worktree，Wipecraft 会把这些文件放回原处。
• “恢复”会重新创建这些文件原先所在的文件夹。
• 这些文件从不单独提供。构建产物作为单独的一行提供，已锁定的 worktree 也是如此。

可在终端和 Claude Code 中使用

命令行。 Wipecraft 在 App 内附带了 wipecraft 命令。“设置 > 通用 > 命令行工具”会显示将它链接到 PATH 的那一行命令。

• wipecraft scan 和 wipecraft status 列出可释放的内容，加上 --json 时输出带版本号的 JSON。它们不做任何更改。
• wipecraft clean 显示它将要做什么。在你加上 --apply 之前，不会有任何更改。
• 加上 --apply 后，wipecraft clean 对你指定的每个项目执行与 App 相同的操作：对应 App 会重新创建的缓存、日志和临时文件会被直接移除且无法恢复（计划中会写明“Would remove directly”），其他文件移到隔离区，会话历史记录进入归档，已完成的 worktree 在其被忽略且不属于构建产物的文件移到隔离区之后，通过 git worktree remove 移除。删除日志会记录每项操作。--all-safe 只选择会移到隔离区的项目。它需要与 App 相同的许可证。
• 它会拒绝已锁定的行，以及自扫描以来发生变化的行。它不执行标为“不可撤销”的操作，而是提示你打开 App。
• wipecraft quarantine list 显示隔离区中的内容，wipecraft quarantine restore <id> 会将某个条目放回原处。两者都不需要许可证。
• 如果 App 或另一个终端正在移动文件，该命令会停止并提示 Wipecraft 正忙，不移动任何内容。
• 它可以输出 zsh、bash 和 fish 的补全脚本。

Claude Code 插件。 该插件添加两个命令和两个会话钩子。

• /wipecraft:status 汇总 wipecraft scan --json 的结果。/wipecraft:tidy 先显示试运行结果，只有在你于对话中同意后才运行 --apply。
• 会话开始时，如果可释放的空间超过 1 GB，它会在会话中添加一行。这行内容来自上次刷新时保存的摘要，因此会话从不需要等待扫描。如果没有过去 24 小时内的摘要，它不输出任何内容，并在后台刷新摘要。
• 会话在某个链接的 worktree 中结束时，它会用一行输出该 worktree 的状态。
• 整理已完成的 worktree 默认关闭。它是“设置 > 智能体”中的一个开关。
• 开关打开后，会话结束并经过短暂延迟，wipecraft clean 会在后台运行，且只针对该会话的 worktree。它经过与命令相同的检查，仍处于锁定状态的 worktree 会保留。

其他智能体（MCP）。 wipecraft mcp 是一个服务器，Claude Code、Codex、Cursor 和其他智能体可以在你的 Mac 上启动它。它只通过标准输入和输出通信；其源代码不使用网络连接，也不监听任何端口。

• 智能体可以读取总计、列出和解释项目，以及查看隔离区中的内容。这些请求不做任何更改。
• 在你于“设置 > 智能体”中打开“允许智能体通过 MCP 清理”之前，无法通过智能体进行清理。
• 打开后，除非智能体要求应用，否则请求只显示计划。应用需要许可证，并会跳过已锁定的行。对智能体指定的每个 ID，它执行与 wipecraft clean --apply 相同的操作：对应 App 会重新创建的缓存、日志和临时文件会被直接移除且无法恢复，其他文件移到隔离区，会话历史记录进入归档，已完成的 worktree 通过 git 移除。工具说明会告诉智能体哪些项目无法恢复，以便它在应用之前告知你。移除时间机器本地快照这类标为“不可撤销”的操作，仍然会被拒绝。
• “设置 > 智能体”列出了 Claude Code、Codex 和 Cursor 的设置文本。Wipecraft 只显示这些文本，不更改任何智能体的设置。

它能找到什么

每一行都会说明它是什么、有多大，以及移除后会怎样。如果某项内容可以找回，也会说明如何找回。

Claude Code、Codex、worktree 以及下面的开发者工具会在开启“开发者模式”后显示。参见常见问题。

AI 智能体和 AI App

• Claude Code。 会话历史记录，按项目和月份分组。它们会被归档，而不是删除。此外还有文件历史、shell 快照、调试日志和插件。
• Codex。 会话、已归档的会话，以及线程历史和日志数据库。这些全部会被归档，而不是删除。此外还有生成的图像和缓存。
• Claude Desktop。 VM 包。当前沙盒镜像会显示并锁定。它的压缩副本和遗留的温启动数据只在 Claude Desktop 关闭时提供。还有缓存。
• Cursor。 它的缓存。
• 本地模型。 Ollama、LM Studio、Hugging Face 缓存、PyTorch 缓存和 Whisper 模型，并显示大小和上次使用时间。
• Git worktree。 来自任何智能体，或来自你自己：你个人文件夹中 git 仓库的 worktree，以及 .claude/worktrees 中的文件夹。每个都显示其分支、大小、上次更改时间，以及单独列出的 git 忽略的文件。worktree 按创建它们的工具分组：Claude Code、Codex、Cursor 或其他。分组依据文件夹或分支名称。
• Worktree 遗留项。 主仓库已被移动或删除的文件夹会列出，git 中那些文件夹已不存在的 worktree 记录也会列出。移除这些记录会运行 git worktree prune，它不删除任何文件。如果某条记录的文件夹只是被移动而非删除，它会保持锁定，该行会提示运行 git worktree repair。

开发者工具

• Xcode。 每个项目的构建数据、归档、设备支持文件、预览和模块缓存。Xcode 打开的项目会被锁定。
• 模拟器。 每台设备及其大小和上次使用时间。“移除设备”和“抹掉内容”是两个单独的操作。运行时镜像只在没有模拟器使用时才会提供。
• 软件包缓存。 npm、pnpm、Yarn、pip、Homebrew、CocoaPods、Swift Package Manager、Gradle 和 Cargo，以及 Bun、uv、conda、Go 和 Maven。
• 构建产物。 30 天未更改的项目中的 node_modules。还有 .venv、target、.next、build、dist、Pods 和 .build 等文件夹，但仅当项目有其标记文件（例如 Cargo.toml 或 package.json）、git 忽略该文件夹，且项目 30 天未更改时才会列出。这 30 天可以更改。在项目文件夹中启动的编程智能体或编辑器，在运行期间会锁定该项目。
• 编辑器。 VS Code、JetBrains IDE 和 Android Studio 的缓存和日志。对应的编辑器运行时，它们会被锁定。属于旧版 IDE 的文件夹会注明这一点。
• Android。 模拟器（虚拟设备）和 SDK 系统镜像。模拟器会移到隔离区；当有模拟器正在运行或其锁定文件存在时，它会被锁定。系统镜像在有设备使用时会被锁定，Wipecraft 无法读取某个设备的设置时也会被锁定。
• Docker。 Docker 运行时的镜像和卷。容器正在使用的镜像或卷会被锁定。还有当前没有构建在使用的构建缓存；移除它会运行 docker builder prune --all --force，此操作无法撤销。OrbStack 的数据文件夹会显示大小，Wipecraft 不会移除它。

系统数据

系统设置中的“储存空间”面板只为“系统数据”显示一个数字。Wipecraft 从磁盘的已用空间出发，把每个已用字节分成四部分：macOS、App、你的文件和系统数据。这四部分加起来等于已用空间。

系统数据又分为五组。每组都有一种颜色和一句话的说明。

• Mac 需要这些。 交换文件、系统数据库，以及 App 为自己保留的数据。会显示，但绝不会建议移除。
• 可放心移除。 对应 App 会自行重新创建的缓存、日志和临时文件。
• 会再出现。 可以移除，但随着使用会重新填满，例如浏览器缓存和软件包缓存。
• 由你决定。 不会自行回来的东西的唯一副本，例如本地模型、模拟器、worktree、Docker 镜像和会话历史记录。卡片会说明每一项是什么，以及你上次使用它是什么时候。它们会进入隔离区（7 天内可以撤销），或进入归档（可以恢复）。
• macOS 未显示。 减去 Wipecraft 能识别的所有内容之后剩下的部分，并附有原因：完全磁盘访问权限已关闭、只有管理员才能读取的文件夹，或 APFS 的额外开销与克隆文件。

卡片上的废纸篓只会移除安全的内容：“可放心移除”和“会再出现”中未被锁定的项目。它绝不会动“由你决定”中的项目，被 App 打开的项目会保持锁定。卡片会先翻转过来，说明将发生什么，以及能否撤销。

时间机器本地快照在这些分组之外，逐个列出，并显示日期。macOS 不报告本地快照的大小，因此 Wipecraft 不做估算。移除快照会标为“不可撤销”，并且每次都会要求输入管理员密码。

部分文件夹需要完全磁盘访问权限。没有该权限时，你的用户文件夹仍会被扫描，概览会说明哪些文件夹无法统计。

撤销的方式

对应工具不会自行找回的缓存不属于第一行。它们会进入隔离区：JetBrains 和 Android Studio 的缓存、Maven 和 Go 模块，以及 Library/Caches 中的工具数据，例如 Poetry 环境、Playwright 和 Cypress 浏览器以及 llama.cpp 模型。

不可撤销的操作有：移除时间机器本地快照、删除模拟器运行时、抹掉模拟器内容、移除 Docker 镜像或卷，以及移除 Docker 构建缓存。

对于仓库存在的 worktree，Wipecraft 只在它处于干净状态时才建议移除：没有已跟踪文件被更改，没有未被 git 忽略的未跟踪文件，7 天内没有更改（默认值；可在“设置”中更改），且它的提交在主分支或远程仓库上。主仓库已不存在的 worktree 无法由 git 检查。它会在 30 天（默认值）无更改后提供，并作为整个文件夹进入隔离区。它被 git 忽略的文件（构建产物、依赖项）也是单独的一行，会进入隔离区。即使 worktree 本身已锁定（例如因为有未提交的更改），这一行也可能会提供。

隔离区在同一磁盘上移动文件，因此空间会在清空时释放。隔离区界面会同时显示两个数字：“在隔离区中”和“立即清空可释放”。

每项操作都会写入本地删除日志：时间、内容、大小以及操作类型。你可以在“设置”中将其导出为 CSV。

隐私的 10 条原则

1. 无需账户。
2. App 不收集遥测或使用情况分析数据。
3. Wipecraft 不会把任何文件名或路径发送到任何地方。你自己连接的编程智能体会在你的 Mac 上通过本地连接接收扫描结果。该智能体如何处理这些结果，由其提供方负责。
4. 扫描读取此 Mac 上的大小、日期和工具状态（git、simctl、Docker）。它不上传任何内容。
5. App 只为两件事发起网络请求：你的许可证（如果你激活了许可证，并以你的 Mac 名称作为激活标签）和更新检查。另有一项可选检查通过你自己的 gh 登录进行，仅在已安装 gh 且已登录时进行。你可以在 “设置”中关闭它，之后 gh 不会再运行。
6. 崩溃报告默认关闭。如果你开启它，只有在 App 崩溃时才会发送，且不含文件名或路径（Sentry，欧盟区域）。
7. 除非你开启“监控”，否则没有任何内容在后台运行；开启后，菜单栏图标会显示它处于开启状态。唯一的其他情况是 Claude Code 插件（如果你安装了它）：它的钩子会在会话开始或结束时运行 wipecraft。
8. 不安装任何管理员辅助程序。只有在移除快照时才会要求输入管理员密码，且每次都会要求。wipecraft 命令以你自己的权限运行，不运行管理员命令。
9. 删除日志保留在你的 Mac 上，由你自己导出。
10. 你的许可证密钥保存在你的钥匙串中。wipecraft 命令从那里读取它来检查许可证。

完整详情：wipecraft.app/privacy/zh-Hans