你的自动化。同样的原生引擎。

从已安装的应用开始

本指南适用于 Mac。iPhone 和 iPad 版 DiskPress for Files 没有 CLI 或持续文件夹监控。iPhone 和 iPad 自动化请见 Apple 快捷指令流程及其 iOS 要求。

Mac App Store 和 Setapp 版本包含相同的 CLI 功能。选择下载方式。CLI 就是应用包内的可执行文件，没有单独的命令行下载。这些示例使用位于 /Applications/DiskPress.app 的 Mac App Store 副本。如果你的副本位于别处，请调整路径。

"/Applications/DiskPress.app/Contents/MacOS/DiskPress" --help

Setapp 请使用其安装目录内的可执行文件，应用包名称和位置可能不同。Mac App Store 与 Setapp 版本的设置和授权相互独立，因此请配置你实际调用的版本。内置 --help 会使用该安装的可执行文件路径显示示例。

1. 打开该副本的 DiskPress，前往设置，然后选择已授权路径。
2. 添加命令应能读写的具体文件或文件夹。对于压缩文件，请授权其所在文件夹。
3. 选择 optimize 前，先用 scan 检查所选内容。

命令

将这些命令放在可执行文件路径之后。只有 scan 和 optimize 接受目标路径，每次请求最多 500 个。

paths 表示权限。locations 表示保存的优化目标，两者不能互换。配置修改和新增授权仍需在应用设置中完成。

选项

--json 和 --quiet 适用于上述全部八个命令。报告命令不接受目标路径，也不接受 --gui 或 --ignore-exclusions。

优化过程说明

首次重复检查可能更久

当设置和保存位置模式允许两种操作时，DiskPress 会在一次运行中结合两种技术。大文件夹的首次重复检查可能耗时较长，即使文件已压缩也一样。后续运行会复用未改变文件的缓存指纹，重启 DiskPress 后也保留。匹配文件在替换前仍会验证内容和元数据。

DiskPress 也会在同次优化中复用扫描结果，并记住未从压缩中受益且未改变的文件。跳过再次压缩不代表这些文件不参与去重检查。

保存位置模式也适用于 CLI 目标

在应用的位置表中选择优化模式。CLI 优化遵守该模式，包括单独传入或使用 --ignore-exclusions 的文件。

• 压缩 + 去重允许结合两种技术。
• 仅压缩允许压缩，不允许去重。
• 仅去重允许去重，不允许压缩。
• 禁用阻止匹配文件的两种操作。

最具体的匹配位置优先。保存的文件覆盖包含它的文件夹，子文件夹覆盖父文件夹，包括已禁用的父文件夹。非递归文件夹规则仅涵盖该文件夹及直接子项。保存位置之外的文件遵守通用设置和安全检查。

去重同时需要兼容的位置模式和全局设置。要全局禁用，请在设置中关闭"对相同文件去重"。这不会为仅去重或禁用位置启用压缩。没有每次命令仅压缩标志，也没有修改位置模式的 CLI 命令。CLI 不显示首次去重确认，即使使用 --gui 也一样。

locations --json 报告 enabled，但目前不包含每个位置的优化模式。settings.deduplicationEnabled 是全局开关，不是位置模式。需要确认允许哪些操作时，请检查位置表。

近期文件保护不延迟 CLI 请求

近期文件保护会在保存位置优化中延迟处理最近修改的文件，包括自动监控和立即优化。CLI scan 和 optimize 是明确的一次性请求，不采用该延迟，有无 --gui 都一样。目标是保存位置时也如此。

recentFileProtectionSeconds 设置表示保存位置的延迟，不是 CLI 等待时间。请在生成文件的程序完成写入后安排命令。活跃写入检测、文件变化检查和验证仍然有效。

关联应用仍保护其位置

如果保存位置有关联应用，应用运行时会跳过该位置的文件。单独通过 CLI 指定的文件也适用，--ignore-exclusions 无法绕过。优化前请退出关联应用。

locations --json 包含带有 bundleIdentifier、path 和 name 的 linkedApplication，未配置时为 null。这描述的是保存的关联，不是应用当前运行状态。初步 scan 不保证文件在实际优化中通过所有检查。见关联应用常见问题。

实用示例

为方便当前终端会话，可将可执行文件路径保存到变量。这不会安装命令或修改 shell 配置。

DISKPRESS="/Applications/DiskPress.app/Contents/MacOS/DiskPress"

检查权限与设置

"$DISKPRESS" --version
"$DISKPRESS" paths --json
"$DISKPRESS" settings --json
"$DISKPRESS" locations --json

只扫描，不优化

这些示例使用已完成数据的文件夹。请替换为你计划优化的具体、稳定文件夹，并先授权。扫描不会预测最终压缩率，某些兼容检查只在实际优化时执行。

"$DISKPRESS" scan --json -- "$HOME/Documents/Completed Data"

运行一次优化

这会改变所选文件夹中支持文件的存储方式，可能增加磁盘写入。避免反复优化频繁出现新文件或修改的位置。安排命令前请阅读 SSD 写入指南。

"$DISKPRESS" optimize --json --quiet -- "$HOME/Documents/Completed Data"

需要时显示进度

"$DISKPRESS" optimize --gui -- "$HOME/Documents/Completed Data"

读取结果

"$DISKPRESS" overview --json
"$DISKPRESS" savings --json
"$DISKPRESS" activity --limit 20 --json

命令结果描述已完成的任务，保存位置总量可能仍在刷新。将总量视为最新前，请检查 savings.refreshing 和测量日期。

理解输出

可读进度写入标准错误，最终摘要写入标准输出。使用 --json 时，标准输出是每行一个独立 JSON 对象的流。应按 NDJSON 解析，而不是单个大型 JSON 文档。

• 事件包含 schemaVersion、requestID、sequence 和 event。当前架构版本为 1。
• 事件类型为 progress、result 和 error。进度采用采样，因此序列号可能有间隔。
• 最终事件包含 exitCode 和 message。result 事件可能表示部分成功或取消，因此也要检查退出代码。
• CLI 标签、帮助和生成的消息使用英文。已保存记录和共享诊断保留原始文本。可选进度窗口遵循应用语言。
• 自动化请使用 JSON 字段名、提供的结构化原因代码和退出代码。不要匹配翻译后的文本或可读消息。

扫描与优化结果

scan 返回 totalFiles、eligibleFiles、potentialDeduplicationFiles、logicalBytes、allocatedBytes、alreadySavedBytes，以及采用的 minimumFileBytes 和 maximumFileBytes。潜在去重候选不代表确认的重复文件或节省预测。

扫描 reasons 包含 code、count 和 message。原因可能重叠，排除的文件夹只计一次，因为不会枚举其内容。

optimize 返回 targets、totalFiles、processedFiles、compressedFiles、deduplicatedFiles、skippedFiles、failedFiles，以及初始 scan 摘要和布尔值 cancelled。顶层 reasons 是最近的可读跳过或错误摘要，不是完整逐文件历史。单个结果请读取 activity。

其他结果计数包括 alreadyCompressedFiles、insufficientSavingsFiles 和 noBenefitFiles。它们用于解释结果，不是应加入任务总数的额外文件。

节省量以 compressionSavedBytes、estimatedDeduplicationSavedBytes 和 totalEstimatedSavedBytes 表示，大小数值单位是字节。压缩和去重可能作用于同一文件，因此不能相加两种文件数来计算不同的已优化文件数。去重节省是共享存储估算，不保证空闲空间等量增加。零节省也可能是成功结果。

将进度视为快照

每个进度事件描述最新状态，不是应累加到上个事件的增量。进度条使用阶段计数，整体任务使用全任务计数。

小屏幕上可横向滚动表格，查看完整参考。

查找和分组重复文件可能在没有活动文件名时持续一段时间。新快照无当前项时，应清除旧文件标签。不要假设阶段顺序固定，或某阶段达到总数就表示整个命令结束。只有最终事件和进程退出才能确认完成。

并非所有测量都是实时扫描

locations、savings 和 overview 读取保存的测量，不扫描目标文件、请求新权限或开始监控。它们包含 readAt、dataSource、locationCount、enabledLocationCount 和 savings。日期采用 UTC 的 ISO 8601 格式。

缺失与过期不同

• measurementAvailable 表示位置有已保存测量。未知位置数值为 null，而不是零。
• measurementStale 标记刷新失败后保留的测量。DiskPress 保留上次成功值，不替换为零。有关背景请读取 measurementError 和 measuredAt。
• 任一位置未测量或测量过期时，savings.complete 为 false。unmeasuredLocationCount、staleLocationCount 和 oldestMeasurementAt 描述覆盖范围与时间。
• 保存位置的 statusSource 为 last_saved，其状态不是对目标的新扫描。

当前节省量涵盖已测量的保存位置，包括禁用位置，重叠文件只计一次。位置可能有非零大小却没有计入节省，因为共享文件已在别处计算。最近节省量描述已完成的优化。不要把活动记录加到当前总量，也不要假设每条记录都是不同文件。

Catalina 无法测量当前去重节省量。deduplicationMeasurementAvailable 为 false，相关值为 null。去重仍可运行，最近节省量可包含其完成的工作。

位置可用性与授权

locations --json 的每条记录包含 availability，值为 available、unavailable、stale_bookmark、missing 或 invalid_authorization。这些是保存状态，不是新的权限检查，与 paths 输出中的布尔值 available 不同。

invalid_authorization 表示保存路径的项目不再匹配最初授权的文件或文件夹，例如恢复备份之后。请在 DiskPress 检查目标，移除保存位置并重新添加，为当前项目授权。移除位置不会删除文件。不要尝试绕过标识检查。

优化后的刷新

优化后，DiskPress 在后台刷新保存位置的节省量。CLI 可能在只读刷新完成前返回最终结果。报告提供 savings.refreshing 和 savings.refreshError。也请检查测量日期和覆盖标志，因为刷新结束不代表每个位置都测量成功。

主进程等待命令和刷新完成，不启用定期监控。单独的选择 scan 或报告命令不会请求刷新。需要单独更新保存测量时，请使用应用概览中的重新扫描。

存储与监控

savings 和 overview 也包含过去 24 小时、7 天、30 天的 recentSavings。overview 添加主卷的 storage 和 monitoring。磁盘容量在请求时查询，独立于保存文件测量。

monitoring.enabled 是保存的偏好，不表示 CLI 已启动监控。显示实时状态前请检查 monitoring.serviceRunning 和 monitoring.liveStatusAvailable。实时状态不可用时，实时进度字段为 null。

查看设置与活动

settings --json 返回 settings 对象，包含 deduplicationEnabled、scanHiddenSystemFiles、recentFileProtectionSeconds、monitoringEnabled 和 scanIntervalSeconds。读取不会更改它们。

压缩阈值以 minimumFileBytes、maximumFileBytes、minimumCompressionSavingsFraction 和 minimumCompressionSavingsBytes 报告。这些设置描述压缩适用性，不保证每个文件都能节省空间。

settings.performance 包含 level、batteryLevel、separatePowerSettings 和 pauseMonitoringOnBattery。配置值为 low_cpu、balanced、fast 或 fastest。当前电源和 macOS 会影响实际性能级别。

这些配置也适用于 CLI 优化。最快模式按 Mac 性能核心数调整并行任务，必要时改用物理核心数。低 CPU 模式在大文件处理期间和文件之间都调节节奏，并不是固定 CPU 百分比上限。

settings.exclusions 包含带类型的规则，字段为 id、enabled、type、target、pattern、description 和 extensions。类型有 file_type、wildcard、regular_expression 和 file_group。规则针对 file_name 或 full_path。文件组包含其扩展名。

默认排除包含 databases 组。启用时也涵盖已识别的数据库伴随文件，如 database.sqlite-wal、database.sqlite-shm 和 database.sqlite-journal。报告的 extensions 列表只有基本数据库扩展名，不包含所有伴随文件名模式。请读取规则并用 scan 检查排除结果。避免覆盖活动数据库的排除。

分页读取保留结果

activity --json 返回 GUI 和 CLI 的 activity.records，最新在前。每条记录包含 id、date、path、name、outcome、originalAllocatedBytes、resultAllocatedBytes、savedBytes、durationSeconds、detail 和 locationID。结果类型为 compressed、deduplicated、skipped、failed 或 recovered。

继续读取时，将返回的 activity.nextBefore 原值传给 --before，直到 activity.hasMore 为 false。默认每页 50 条，--limit 接受 1 至 500。大记录可能缩短一页，因此应遵循游标而非记录数。新记录不会移动现有游标。

已清除或过期游标会返回错误，请不带 --before 重新开始。活动是保留历史，不是完整文件清单。多条记录可能属于同一文件，缺少记录不能证明文件从未被优化。

退出代码与安全取消

Ctrl+C、SIGTERM、取消或关闭进度窗口都会请求安全停止。请等待进程完成。已优化的文件保持优化。丢失终端客户端或断开输出管道也会取消工作。

在应用中移除正在参与 CLI 优化的保存位置，也可能取消该运行。即使未按 Ctrl+C，CLI 也会报告取消。进度可显示 phase 为 cancelling，cancelled 为 true。最终取消结果的 exitCode 为 130，cancelled 为 true。完成的优化保留，直到进程退出才完全停止。

如果标准输出无法接收最终结果，进程退出代码仍是权威依据。不要用 head 等命令故意截断正在运行的优化输出。只需最终结果时，请用 --quiet。

主进程崩溃后不会重放已接受的请求。退出代码 75 不证明文件没有改变。如果结果无法送达，请先查看活动和恢复消息，再决定是否重试。

合理的 AI 代理工作流程

DiskPress 提供命令，代理决定如何调用，因此请给它明确的边界。以下是可用的起始指令。

读取我安装的 DiskPress 可执行文件的 --version 和 --help。
权限、设置和命令均使用同一版本。
使用 --json 检查路径、设置和位置。
遵守保存位置模式，CLI 报告不提供这些模式。
如果流程依赖某个模式，请让我在位置中确认。
仅扫描我明确选择的文件或文件夹。
记住 CLI 请求不采用近期文件保护。
解释适用性，并在优化前征求同意。
遵守关联应用保护，等待文件写入结束。
不要授予权限或使用提升权限。
除非我明确要求，否则不要覆盖排除规则。
使用最终 JSON 事件和退出代码报告任务结果。
取消后等待进程退出，包括由应用发起的停止。
报告保存总量前，检查 refreshing、过期标志和日期。
缺少最终结果或恢复出错时，重试前查看活动。

在 -- 后将每条路径作为独立参数传入。切勿把未转义的文件名拼入 shell 命令。如果缺少权限，请让用户在 DiskPress 授权路径，不要循环重试或使用 sudo。

出现警告或失败后，读取活动了解逐文件原因。成功运行可能零节省，安全跳过不一定是错误。恢复错误时保留文件并报告消息。请求取消后等待进程退出。

权限与安全仍然适用

优化开始前，所有目标必须具备可用的保存读写授权。任一目标缺少访问权限，命令会在优化其他目标前失败。CLI 不会打开权限选择器、授予访问或绕过受保护路径。所选文件夹可覆盖子项，但授权一个文件不会授权同级文件。

paths --json 返回 authorizations，包含 path、directory、access 和 available。访问值为 readWrite。授权不可用时，可能需要重新连接卷，或在同一 DiskPress 版本中重新授权路径。

应用和 CLI 使用相同的压缩去重引擎、验证、恢复、排除配置和适用文件限制。应用与可执行文件仍不支持。去重只在同一兼容文件系统内分组，不跨卷。明确覆盖排除也不会关闭安全检查、关联应用保护或保存位置模式限制。

终端扫描和优化在当前 macOS 登录会话中一次运行一个，共享应用的 CPU 调度、恢复和统计。只读统计、设置和活动命令可在任务进行时运行。没有 CLI 命令可启用守护进程、修改设置或撤销已完成存储变更。

保留独立备份。自动化重要数据前，请阅读验证与恢复常见问题。