Tidemark 使用说明

开始使用

Tidemark 是一款免费的开源磁盘清理应用，用于查找开发过程中积累的缓存、依赖、构建产物、AI 模型以及长期未使用的应用，并安全地清理它们。扫描不会删除任何内容，清理必须经过确认窗口才会执行。

安装

打开 Tidemark_<版本>_aarch64.dmg，将 Tidemark.app 拖到“应用程序”文件夹。
首次运行时，如果 macOS 以“身份不明的开发者”为由阻止打开，请在 Finder 中按住 Control 键点按应用 › 选择 打开。
系统要求：Apple Silicon Mac，macOS 11 或更高版本。

界面布局

位置	功能
顶栏	界面标签（清理候选 / 已安装应用 / 容量地图）、磁盘可用空间仪表、重新扫描，以及终端、设置、询问 AI 图标
左侧边栏	各类别合计和筛选（风险、项目闲置时间、更新远程 git 信息）
中间列表	找到的项目，以及搜索框、批量选择按钮
右侧详情面板	点击项目后打开。显示路径、大小、说明、恢复方法和文件夹内容
底栏	所选项目数和预计释放量、是否移到废纸篓、清理

首次运行时，点击 开始扫描。上次的扫描结果会被保存，下次启动时直接显示，顶部状态栏会显示这是何时扫描的结果。

清理候选

在清理候选界面中，选择扫描找到的项目，经确认窗口后进行清理。

扫描

顶栏的 重新扫描 会重新查找全部内容。将鼠标悬停在侧边栏的类别上会出现刷新图标，点击它只重新扫描该类别。
扫描过程中会显示进度，可以用 取消扫描 停止。

AI 工具和模型清理

Hugging Face 按 HF_HUB_CACHE → HF_HOME/hub → XDG_CACHE_HOME/huggingface/hub → 默认路径查找，仅显示模型、数据集和 Space。使用共享存储时，删除模型文件夹可能几乎无法释放空间，建议使用 hf cache delete。
Ollama 优先使用 OLLAMA_MODELS，单个模型请通过 ollama rm <模型> 删除。LM Studio 按主目录指针 → ~/.lmstudio → 旧版 ~/.cache/lm-studio 的顺序查找模型文件夹。
Claude 桌面版和 Windsurf 缓存以及 Whisper 模型使用专用规则。常规 ~/.cache 清理排除 LM Studio 主目录、Hugging Face 主目录和 Whisper，并保护登录令牌和密钥。

浏览器缓存和个人数据清理

Chrome、Edge、Brave、Arc、Firefox、Safari、Opera 和 Vivaldi 仅清理缓存文件夹，不与通用应用缓存重复。保留 Cookie、登录信息、历史记录、书签和扩展程序数据。出现运行中警告时请先退出浏览器。离线页面可能需要重新下载。
Mail 附件下载副本属于注意项目。保留邮箱（~/Library/Mail）和服务器原件；请先将下载副本中的修改另存。
iOS/iPadOS 备份逐个显示为危险项目，不包含在安全项目选择中。备份可能是恢复设备所需的唯一副本，请确认是否有 iCloud 等其他备份。清空废纸篓后无法恢复。
无法访问的 Safari、Mail 和设备备份路径会被跳过。必要时请在 macOS 设置中允许完全磁盘访问权限，然后重新扫描。

风险

标记	含义
安全	重新下载或重新构建即可生成的数据。通常可以直接删除
注意	重新下载需要时间，或可能连同部分设置一起丢失的数据
危险	难以重新获取或可能包含用户数据的数据。清理时会单独要求确认

项目旁的 ⚠ 标记表示警告（例如：相关程序正在运行）。将鼠标悬停在上面即可查看内容。

筛选与搜索

在侧边栏中按类别、风险、项目闲置时间（30、90、180 天以上）进行筛选。
列表上方的搜索框（⌘F）会在名称和路径中查找，并高亮匹配的文字。输入多个词时，只保留全部包含这些词的项目，按 Esc 清除。
选择安全项目 只选择没有警告的安全项目。

详情面板

点击项目后在右侧打开。

显示说明和恢复方法（删除后如何重新生成），以及清理方式（官方命令或直接删除）。
可以展开查看文件夹内容，删除对象会带有 删除 标记。
可以执行 在 Finder 中显示、在内置或外部终端中打开、重新计算、询问 AI。

预检查

对于 Docker 未使用数据、不可用的 iOS 模拟器、Homebrew 缓存等通过命令清理的项目，会预先计算实际能释放的空间。列表中会像 约 13.4 GB / 56.4 GB 这样同时显示预计释放量和总大小。

git 检查

项目文件夹（node_modules、target 等）会同时显示 git 仓库状态。

✓ 已合并 / 已保留在远程：代码已在远程，清理是安全的。
需检查 git：存在未提交的更改或未推送的提交。
打开侧边栏中的 更新远程信息（git fetch） 后，从下次扫描起会先获取最新的远程分支再进行判断。

执行清理

用项目前的复选框进行选择。底栏会显示所选数量和预计释放量。
如有需要，打开 移到废纸篓。此时需要清空废纸篓才会释放空间。旧文件清理和执行命令的项目会被立即删除。
点击 清理 后，确认窗口中会列出清理对象。如果包含危险项目，必须勾选同意后 立即清理 才会启用。
完成后会显示摘要，包括释放的空间、磁盘可用空间的变化以及失败的项目。

已安装应用

已安装应用界面可以删除长期未使用的应用及其残留文件，并管理全局安装的包。应用扫描只使用应用信息和本 Mac 的记录，不使用网络或 AI。

应用列表

上次使用时间来自 macOS 的启动记录；没有记录时，根据应用数据的修改时间推测（根据应用数据推测）。
大小是应用本体与残留文件（设置、缓存、数据）的合计。
在工具栏中可以使用闲置时间（90 天、180 天、1 年以上）、排序（按大小排序 / 最久未使用优先）、隐藏 Apple 应用 和搜索。
带有 运行中 标记的应用请先退出再删除。

删除应用及残留文件

点击应用后，详情面板会列出残留文件。Bundle ID 或 Team ID 匹配的项目是确定的残留文件，仅名称相同的项目会标记为 推测。
点击 删除应用及残留文件，选择删除方式以及要一并删除的残留文件。推测 项目和与其他应用共享的项目默认不选。
移到废纸篓的应用和残留文件可以从废纸篓恢复。

删除方式	适用情况
移到废纸篓（推荐）	大多数应用
Homebrew zap	通过 Homebrew cask 安装的应用。运行 `brew uninstall --cask --zap` 后，将剩余的残留文件移到废纸篓
开发者卸载工具	应用自带专用卸载程序时。卸载过程由该工具执行

已卸载应用的残留数据

工具栏中的已卸载应用的残留数据标签会按应用分组，显示已删除的应用在 ~/Library 中留下的设置、缓存和容器。

只要已安装的应用（包括应用内的辅助程序）、Spotlight、Homebrew cask 或正在运行的进程中有任何一个仍拥有该项，就不会列出。无法确定时选择不显示。
最近 30 天内修改过的项目以及属于 Apple 和通用更新程序的项目会被排除。
默认只勾选缓存、网页数据和窗口状态；设置和容器需要手动选择。自动启动项仅显示，不可删除。
移到废纸篓会在移动前重新检查每个路径，可以从废纸篓恢复。
如果大小显示为大小未知 · 需要完全磁盘访问权限，请通过打开完全磁盘访问设置允许 Tidemark。
想保留的应用可点忽略将其移出列表，可通过下方的取消忽略重新显示。

管理员删除保管库

通过 .pkg 安装或从 App Store 下载的系统（root）所有应用，在删除时 macOS 会要求输入管理员密码。

这类应用会被移到 /Library/Application Support/Tidemark Trash，而不是废纸篓。
保管库中有项目时，列表上方会显示提示，必须点击 清空保管库 才会释放空间。
清空之前，可以在 Finder 中取出以恢复（需要管理员密码）。

全局包

工具栏的 全局包 标签汇集了通过 Homebrew、npm/pnpm/yarn/bun 全局、pipx、uv tool、cargo install 安装的包，以及 npx 缓存。

检查更新 会检查 Homebrew、npm、pnpm 包的新版本。包括 brew update 在内会使用网络，但不做任何更改。
打开 仅新版本 后，只显示有更新的包。
升级（单个）或 全部升级 会在内置终端中使用各包管理器的官方命令执行，可以直接看到进度并输入密码。主版本号可能会变化。
删除包同样使用包管理器的官方命令（brew uninstall、npm uninstall -g 等）执行。作为其他包的 依赖项 安装的包，Homebrew 可能会拒绝删除。
npx 缓存是 npx 运行时下载的包。即使移到废纸篓，下次用 npx 运行时也会重新下载。

容量地图

容量地图以与大小成比例的矩形（树状图）显示哪些文件夹占用了空间。

点击 分析主文件夹 或 分析整个磁盘（/）。分析主文件夹可能需要几分钟。
点击文件夹矩形即可进入该文件夹。点击顶部路径（面包屑）返回上级文件夹。
右侧列表按大小顺序显示当前文件夹的子文件夹和文件，可以在终端中打开或 询问 AI。

操作	效果
`⌘` + 滚轮	放大、缩小
`⌘` + 拖动	移动放大后的地图
`原始大小` / `返回完整地图`	重置缩放 / 返回基准文件夹

黄色虚线边框表示该文件夹在清理候选中。
iCloud 等云同步文件夹和其他宗卷会被跳过以避免下载文件，跳过的列表会单独显示。
小于 1MB 的文件夹会合并计算。分析结果会被保存，可用 重新分析 重新计算。

大文件

在容量地图 → 大文件中选择大文件、旧下载或重复下载，然后点击扫描。最小大小可选100MB、250MB、500MB、1GB或5GB，时间可选30、90、180或365天。旧下载仅列出 ~/Downloads 的顶层项目，文件夹还会检查内部项目的最新修改时间。支持搜索、排序和取消。重复文件至少为1MB，并通过大小、前64KB及完整SHA-256确认。

个人文件默认不选中，仅在重复组中保留最旧的原文件候选并选中副本。请先确认数量、总大小和列表，移入废纸篓前会再次检查文件信息。Library、音乐数据、程序包、链接、其他宗卷、未下载的云端项目，以及无法完整检查的文件夹均被跳过。结果只保留在内存中。如果访问被拒绝，请在系统设置 → 隐私与安全性 → 文件与文件夹中允许Tidemark，然后重新扫描。

AI 工具

以只读方式查看 AI 工具的磁盘用量、可重新下载的缓存、正在运行的 AI 进程的 CPU 和内存，以及受支持的 GPU 使用率。展开工具可查看缓存、模型和用户数据的路径与大小，并通过在 Finder 中显示打开位置。用户数据不会被标记为缓存，此界面不会删除文件或终止进程。

首次打开标签页时会显示已保存的测量结果；仅在没有记录时自动测量。可以使用重新测量和取消。标签页可见时，进程信息约每 3 秒刷新一次，也可以暂停。CPU 按核心计算，可能超过 100%；RSS 内存可能低于实际用量。共享数据可能导致各模型用量之和高于实际磁盘用量。无法获取 GPU 信息时会隐藏该信息。

服务器

按进程显示监听中的 TCP 端口。点击“刷新”，按端口或名称搜索，或仅显示向网络开放的端口。“仅此 Mac”表示环回地址；“向网络开放”表示绑定到其他设备可能访问的地址，与防火墙是否允许访问无关。常见端口用途仅供参考。

展开命令行和父进程链后选择“结束”，并在弹窗中确认。开始时间、可执行文件或用户发生变化时会取消操作。发送 SIGTERM 后最多等待五秒，仍在运行时才提供单独确认的 SIGKILL 强制结束，可能丢失未保存的工作。
Tidemark 及其祖先进程、其他用户、macOS 组件、Docker 和受管理服务不能直接结束。安全信息不足时也不显示结束按钮。
在系统设置 › 通用 › 隔空投送与接力中关闭隔空播放接收器。Docker 容器使用显示的 docker stop <名称> 停止。Homebrew 按钮在内置终端准备 brew services stop <formula>，按 Enter 后才执行。
launchd 管理的进程可能重新启动，请在服务设置中停止。Ollama.app 的子服务器应通过菜单栏退出 Ollama。开发监视器存在时，可在确认框中选择同时结束父进程；默认仅结束子进程，结束父进程也可能影响其他工作。

询问 AI

可以向已安装使用的 AI 代理 CLI 询问当前正在查看的项目。AI 无法删除，只能提出建议。支持的代理：Claude Code（claude）、Codex（codex）、Gemini CLI（gemini）、Cursor CLI（cursor-agent）、OpenCode（opencode）。

提问方法

点击顶栏最右侧的闪光图标、详情面板中的 询问 AI，或选择项目后点击底栏的 询问 AI。
选择代理并输入问题。也可以点击适合当前界面的推荐问题（例如：“这个文件夹是哪个程序创建的？”）来填入。
点击 在终端中开始 后，代理会在内置终端中运行。当前界面和所选项目的信息会一并提供；对话期间切换界面或更改选择时，会根据最新状态回答。

AI 使用 Tidemark 的显示语言回答。代理以本机 CLI 的形式运行，因此登录和费用遵循各 CLI 的设置。

AI 审查徽章

AI 审查项目后，结果会保留在列表和详情面板中。

徽章	含义
可以清理	认为删除没有问题
确认后清理	建议确认内容后再删除
建议保留	建议保留

详情面板中的 AI 审查卡片还会显示依据、清理时可能出现的问题以及恢复方法。这只是 AI 的意见，是否清理请自行判断。

AI 清理建议

AI 建议清理时，界面顶部会显示 AI 建议清理 N 个项目 提示，选择不会自动改变。
点击 查看 后，建议的项目会放入确认窗口，必须勾选已亲自确认建议理由后才能清理。
AI 可能会被扫描文件中的文字误导，请亲自确认项目。不需要时点击 忽略。

终端与快捷键

界面下方内置了终端，可以直接查看项目，或运行 AI 代理、升级包。

用顶栏的终端图标打开和关闭。详情面板中的 终端 会在该项目的文件夹中打开新终端。
标签栏中的 + 会在同一文件夹中打开新终端，标签上的 × 会结束该 shell。
拖动终端上边缘可调整高度，双击则恢复默认高度。

快捷键	效果
`⌘F`	移到当前界面的搜索框
`Esc`（在搜索框中）	清除搜索词
`⌘+` / `⌘-` / `⌘0`	界面放大 / 缩小 / 原始大小（光标在终端中时同样有效）
`⌘` + 滚轮、`⌘` + 拖动	容量地图放大、移动

在 Windows 和 Linux 上，用 Ctrl 代替 ⌘。界面缩放比例和终端高度会被保存，下次启动时保持不变。

设置

用顶栏的齿轮图标打开。更改的值会立即生效，下次启动时保持不变。

项目	选项	默认值
主题	跟随系统 / 浅色 / 深色	跟随系统（跟随 macOS、Windows 的浅色或深色模式）
语言	跟随系统 / 한국어 / English / 日本語 / 简体中文	跟随系统（列表中没有的语言使用英语）
AI 代理	各代理是否启用、默认代理、可执行文件路径	启用所有已安装的代理

菜单栏与自动重新扫描

在菜单栏中显示默认关闭。开启后，关闭窗口仍会继续运行。菜单显示可用空间、上次扫描和可清理空间，并提供打开 Tidemark、立即扫描和退出。Dock 图标会保留。
登录时启动默认关闭，仅适用于 macOS 13 及以上的已签名应用。状态来自 macOS；若需要批准，请在系统设置中允许。登录启动时，仅在菜单栏模式开启的情况下隐藏窗口。
自动重新扫描清理候选默认为手动，可选择每6小时、每天或每周。仅在应用运行、无其他任务且使用交流电源时刷新。无法确认电源状态时跳过。扫描不会删除文件或发送通知。

语言

更改语言后界面会立即重新绘制。已生成的扫描警告和检查说明从下次扫描起以新语言显示。
跟随系统 使用启动时的系统语言。在 macOS 上为 系统设置 › 通用 › 语言与地区 中的首选语言。

AI 代理

Tidemark 只检查可执行文件是否存在，以及 --version 能否运行。用 重新检查 重新检测。
如果在 PATH 中找不到，请在路径栏中直接填写可执行文件（例如：/opt/homebrew/bin/claude），然后点击 应用。
登录或模型设置问题，请用 在终端中运行 直接启动 CLI 进行确认。

赞助

可以通过设置窗口底部的 赞助 支持 Tidemark 的开发。

应用更新

自动检查默认开启。启动时，距上次检查满24小时后只请求GitHub的版本信息文件，也可点击立即检查。只有点击更新才会下载；签名、公证和校验值验证通过后，点击安装并重启安装。清理期间无法重启。如果应用位置或验证问题阻止自动安装，请点击打开发布页面手动下载。用户数据会保留。

安全机制

Tidemark 在删除前会显示将要删除的内容，并在以下情况下不删除或再次确认。

机制	内容
只读扫描	扫描只查找并计算大小。清理必须经过确认窗口才会执行
受保护路径	拒绝删除主文件夹、桌面、文稿、系统文件夹及其上级路径
优先使用官方清理命令	优先使用工具提供的方法，如 `npm cache clean`、`uv cache clean`、`docker system prune`
链接与其他宗卷	不跟随符号链接，不跨越到其他文件系统。硬链接只计算一次，并单独显示共享容量
项目标识文件	只有包含 package.json、Cargo.toml、pyvenv.cfg 等文件的文件夹才会被视为项目清理对象
git 检查	显示未提交的更改和未推送的提交。调用 git 时会关闭仓库配置中的命令执行路径（`core.fsmonitor` 等）
危险项目确认	包含危险项目或 AI 建议时，必须在确认窗口中单独勾选才能执行
废纸篓	打开移到废纸篓后可以恢复。删除应用的默认方式也是废纸篓（root 所有的应用为管理员删除保管库）
防止路径替换	在 macOS 和 Linux 上，旧文件删除基于文件夹句柄（`openat`/`unlinkat`）执行
清理记录	在 `clean-log.jsonl` 中记录何时清理了什么

CLI 用法

同一引擎也可以通过终端命令 tidemark 使用。没有 --yes 时，clean 只显示计划（dry-run），不删除任何内容。

安装（从仓库）：cargo install --path crates/cli

命令	功能	主要选项
`tidemark scan`	扫描可清理的项目	`--root <文件夹>`、`--no-projects`、`--no-rules`、`--min-mb <MB>`（默认 1）、`--git-fetch`、`--json`
`tidemark clean`	清理项目	scan 选项 + `--rule <id>`（可多次指定）、`--max-risk safe\|caution\|danger`、`--unused-days <N>`、`--include-warned`、`--trash`、`--yes`
`tidemark rules`	适用于当前操作系统的规则列表	—
`tidemark map [文件夹]`	按文件夹显示容量（默认：主文件夹，最多 2 层）	基准文件夹（例如：`/`、`~/Desktop`）
`tidemark apps`	已安装应用的上次使用时间、大小、残留文件	`--unused-days <N>`、`--no-apple`、`--json`
`tidemark outdated`	有新版本的全局包（Homebrew、npm、pnpm）	—

# 仅扫描（不删除任何内容）
tidemark scan

# 查看安全项目的清理计划（dry-run）
tidemark clean --max-risk safe

# 将超过 90 天未使用的项目的 node_modules 移到废纸篓
tidemark clean --rule project:node_modules --unused-days 90 --trash --yes

# 只实际清理一条规则
tidemark clean --rule npm-cache --yes

输出语言跟随操作系统语言，可以像 TIDEMARK_LANG=en tidemark scan 这样更改（ko、en、ja、zh）。规则 id 可用 tidemark rules 查看。

自定义清理规则

要添加默认规则中没有的缓存或关闭默认规则，请创建 rules.toml。在 macOS 上位于 ~/Library/Application Support/tidemark/rules.toml（其他操作系统为 <config_dir>/tidemark/rules.toml）。

格式与默认规则文件（crates/infra/rules/default.toml）相同。
使用相同的 id 会覆盖默认规则，用 disabled = true 关闭默认规则。
更改后需要重新扫描才会生效。自定义规则的名称和说明不会被翻译，按填写的原样显示。

# 添加新规则
[[rules]]
id = "my-tool-cache"
name = "My Tool 缓存"
category = "package_cache"
risk = "safe"
description = "my-tool 下载的文件。"
restore = "下次运行时会重新下载。"
paths = { macos = ["~/Library/Caches/my-tool"], linux = ["~/.cache/my-tool"] }
mode = "contents"

# 关闭默认规则（id、name、category、risk 始终必填）
[[rules]]
id = "yarn-cache"
name = "Yarn 缓存"
category = "package_cache"
risk = "safe"
disabled = true

字段	含义
`id`、`name`	规则标识和界面上显示的名称。与 category、risk 一起为必填项
`category`	`package_cache`、`project_deps`、`build_cache`、`ai_tool`、`ai_model`、`ide`、`container`、`temp`、`logs`、`app_cache`、`trash`
`risk`	`safe` \| `caution` \| `danger`
`paths`	按 `all`、`unix`、`macos`、`linux`、`windows` 指定的路径。可以使用 `~`、`$VAR`、`${VAR}`、`%VAR%` 支持单层配置文件目录的 ``，不支持递归 `` 或多个 `` 目录层。
`paths.priority`, `paths.pointer`, `paths.first_existing`	`priority` 使用首个可展开的路径。`pointer = { file, suffix }` 读取文件中的主目录并添加后缀；`first_existing = true` 选择首个存在的默认文件夹。
`mode`	`whole`（删除路径）\| `contents`（删除内容）\| `children`（按子项显示）\| `aged_files`（仅旧文件）
`min_age_days`、`include`、`exclude`	`aged_files` 的天数和相对根目录的 glob，以及 `children` 的候选名称 glob。`contents` 的 `exclude` 列出相对根目录的子路径。
`command`	官方清理命令 `{ program, args }`。如果有，则先执行
`fallback_delete`	没有命令或命令失败时直接删除（默认 true）
`inspect`	执行前检查释放量：`simctl-unavailable` \| `docker-prune` \| `brew-cleanup`
`partial`	命令只清理部分内容（显示的容量为最大值）
`processes`	正在运行时要发出警告的进程名称

数据位置与故障排除

Tidemark 的数据全部只保存在本机，在 macOS 上位于 ~/Library/Application Support/tidemark/。

文件	内容
`last-scan.json`	上次清理候选扫描结果
`apps.json`	已安装应用和全局包的扫描结果
`disk-map.json`	容量地图分析结果
`ai-reviews.json`	AI 审查结果
`ui.json`	主题、语言、界面缩放比例、终端高度、AI 代理设置
`clean-log.jsonl`	清理记录
`rules.toml`	自定义清理规则（仅在创建后存在）

如果存在旧名称（Storage Clear）的 storage-clear 文件夹，首次运行时会自动迁移到 tidemark。

常见问题

清理后可用空间没有增加。

如果打开了 移到废纸篓 进行清理，需要清空废纸篓。以管理员权限删除的应用需要点击 清空保管库。
像 pnpm 存储这样与其他位置通过硬链接共享的文件，删除后也不会增加空间。列表中会显示为 硬链接共享。
如果存在 Time Machine 本地快照，macOS 显示的可用空间可能会延迟增加。

在询问 AI 中找不到代理。

Tidemark 启动时会获取登录 shell 的 PATH 来查找 claude、codex。如果仍然找不到，请在设置中直接指定可执行文件路径。

更改语言后，部分文字仍以旧语言显示。

扫描警告、预检查说明和 git 状态备注会以扫描时的语言保存。重新扫描 后会切换为新语言。

扫描结果与实际情况不符。

顶部状态栏中的 上次扫描结果 · N 天前 表示当前显示的是已保存的结果。清理前 重新扫描 即可获得准确结果。

首次打开时因“身份不明的开发者”而无法打开。

这是尚未经过 Apple 公证的版本。在 Finder 中按住 Control 键点按应用 › 选择 打开，允许一次后即可正常打开。