你的自動化。同樣的原生引擎。

從已安裝的 App 開始

本指南適用於 Mac。iPhone 和 iPad 版 DiskPress for Files 沒有 CLI 或持續資料夾監控。iPhone 和 iPad 自動化請見 Apple 捷徑流程及其 iOS 需求。

Mac App Store 和 Setapp 版本包含相同的 CLI 功能。選擇下載方式。CLI 就是 App 套件內的執行檔，沒有單獨的命令列下載。這些範例使用位於 /Applications/DiskPress.app 的 Mac App Store 副本。如果你的副本位於別處，請調整路徑。

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

Setapp 請使用其安裝目錄內的執行檔，App 套件名稱和位置可能不同。Mac App Store 與 Setapp 版本的設定和授權相互獨立，因此請設定你實際呼叫的版本。內建 --help 會使用該安裝的執行檔路徑顯示範例。

1. 開啟該副本的 DiskPress，前往設定，然後選擇已授權路徑。
2. 加入命令應能讀寫的特定檔案或資料夾。對於壓縮檔案，請授權其所在資料夾。
3. 選擇 optimize 前，先用 scan 檢查所選內容。

命令

將這些命令放在執行檔路徑之後。只有 scan 和 optimize 接受目標路徑，每次請求最多 500 個。

paths 表示權限。locations 表示儲存的最佳化目標，兩者不能互換。設定修改和新增授權仍需在 App 設定中完成。

選項

--json 和 --quiet 適用於上述全部八個命令。報告命令不接受目標路徑，也不接受 --gui 或 --ignore-exclusions。

最佳化過程說明

首次重複檢查可能更久

當設定和儲存位置模式允許兩種操作時，DiskPress 會在一次執行中結合兩種技術。大資料夾的首次重複檢查可能耗時較長，即使檔案已壓縮也一樣。後續執行會重用未變更檔案的快取指紋，重新啟動 DiskPress 後也保留。符合的檔案在替換前仍會驗證內容和中繼資料。

DiskPress 也會在同次最佳化中重用掃描結果，並記住未從壓縮中受益且未變更的檔案。略過再次壓縮不代表這些檔案不參與重複資料刪減檢查。

儲存位置模式也適用於 CLI 目標

在 App 的位置表格中選擇最佳化模式。CLI 最佳化遵守該模式，包括個別傳入或使用 --ignore-exclusions 的檔案。

• 壓縮 + 重複資料刪減允許結合兩種技術。
• 僅壓縮允許壓縮，不允許重複資料刪減。
• 僅重複資料刪減允許重複資料刪減，不允許壓縮。
• 停用阻止符合檔案的兩種操作。

最具體的符合位置優先。儲存的檔案覆寫包含它的資料夾，子資料夾覆寫父資料夾，包括已停用的父資料夾。非遞迴資料夾規則僅涵蓋該資料夾及直接子項。儲存位置之外的檔案遵守一般設定和安全檢查。

重複資料刪減同時需要相容的位置模式和全域設定。要全域停用，請在設定中關閉"刪減相同檔案重複資料"。這不會為僅重複資料刪減或停用位置啟用壓縮。沒有每次命令僅壓縮旗標，也沒有修改位置模式的 CLI 命令。CLI 不顯示首次重複資料刪減確認，即使使用 --gui 也一樣。

locations --json 報告 enabled，但目前不包含每個位置的最佳化模式。settings.deduplicationEnabled 是全域開關，不是位置模式。需要確認允許哪些操作時，請檢查位置表格。

近期檔案保護不延遲 CLI 請求

近期檔案保護會在儲存位置最佳化中延遲處理最近修改的檔案，包括自動監控和立即最佳化。CLI scan 和 optimize 是明確的單次請求，不採用該延遲，有無 --gui 都一樣。目標是儲存位置時也如此。

recentFileProtectionSeconds 設定表示儲存位置的延遲，不是 CLI 等待時間。請在產生檔案的程式完成寫入後安排命令。活躍寫入偵測、檔案變更檢查和驗證仍然有效。

連結 App 仍保護其位置

如果儲存位置有連結 App，App 執行時會略過該位置的檔案。個別透過 CLI 指定的檔案也適用，--ignore-exclusions 無法繞過。最佳化前請結束連結 App。

locations --json 包含帶有 bundleIdentifier、path 和 name 的 linkedApplication，未設定時為 null。這描述的是儲存的關聯，不是 App 目前執行狀態。初步 scan 不保證檔案在實際最佳化中通過所有檢查。見連結 App 常見問題。

實用範例

為方便目前終端機工作階段，可將執行檔路徑儲存到變數。這不會安裝命令或修改 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 標籤、說明和產生的訊息使用英文。已儲存記錄和共用診斷保留原始文字。可選進度視窗遵循 App 語言。
• 自動化請使用 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 或報告命令不會要求更新。需要單獨更新儲存測量時，請使用 App 概覽中的重新掃描。

儲存空間與監控

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、取消或關閉進度視窗都會要求安全停止。請等待程序完成。已最佳化的檔案保持最佳化。失去終端機用戶端或中斷輸出管線也會取消工作。

在 App 中移除正在參與 CLI 最佳化的儲存位置，也可能取消該執行。即使未按 Ctrl+C，CLI 也會報告取消。進度可顯示 phase 為 cancelling，cancelled 為 true。最終取消結果的 exitCode 為 130，cancelled 為 true。完成的最佳化保留，直到程序結束才完全停止。

如果標準輸出無法接收最終結果，程序結束代碼仍是判斷依據。不要用 head 等命令刻意截斷正在執行的最佳化輸出。只需最終結果時，請用 --quiet。

主程序當機後不會重播已接受的請求。結束代碼 75 不證明檔案沒有改變。如果結果無法送達，請先查看活動和復原訊息，再決定是否重試。

合理的 AI 代理工作流程

DiskPress 提供命令，代理決定如何呼叫，因此請給它明確的界線。以下是可用的起始指令。

讀取我安裝的 DiskPress 執行檔的 --version 和 --help。
權限、設定和命令均使用同一版本。
使用 --json 檢查路徑、設定和位置。
遵守儲存位置模式，CLI 報告不提供這些模式。
如果流程依賴某個模式，請讓我在位置中確認。
僅掃描我明確選擇的檔案或資料夾。
記住 CLI 請求不採用近期檔案保護。
說明適用性，並在最佳化前徵求同意。
遵守連結 App 保護，等待檔案寫入結束。
不要授予權限或使用提升權限。
除非我明確要求，否則不要覆寫排除規則。
使用最終 JSON 事件和結束代碼報告工作結果。
取消後等待程序結束，包括由 App 發起的停止。
報告儲存總量前，檢查 refreshing、過期旗標和日期。
缺少最終結果或復原出錯時，重試前查看活動。

在 -- 後將每條路徑作為獨立引數傳入。切勿把未跳脫的檔名拼入 shell 命令。如果缺少權限，請讓使用者在 DiskPress 授權路徑，不要迴圈重試或使用 sudo。

出現警告或失敗後，讀取活動了解逐檔案原因。成功執行可能零節省，安全略過不一定是錯誤。復原錯誤時保留檔案並報告訊息。要求取消後等待程序結束。

權限與安全仍然適用

最佳化開始前，所有目標必須具備可用的儲存讀寫授權。任一目標缺少存取權限，命令會在最佳化其他目標前失敗。CLI 不會開啟權限選擇器、授予存取或繞過受保護路徑。所選資料夾可涵蓋子項，但授權一個檔案不會授權同層檔案。

paths --json 傳回 authorizations，包含 path、directory、access 和 available。存取值為 readWrite。授權無法使用時，可能需要重新連接卷宗，或在同一 DiskPress 版本中重新授權路徑。

App 和 CLI 使用相同的壓縮與重複資料刪減引擎、驗證、復原、排除設定和適用檔案限制。App 與執行檔仍不支援。重複資料刪減只在同一相容檔案系統內分組，不跨卷宗。明確覆寫排除也不會關閉安全檢查、連結 App 保護或儲存位置模式限制。

終端機掃描和最佳化在目前 macOS 登入工作階段中一次執行一個，共享 App 的 CPU 排程、復原和統計。唯讀統計、設定和活動命令可在工作進行時執行。沒有 CLI 命令可啟用常駐程式、修改設定或復原已完成儲存變更。

保留獨立備份。自動化重要資料前，請閱讀驗證與復原常見問題。