storops 是做什麼的？
了解你的儲存空間去向。理解原因。移動重要的資料。清理不必要的部分。
StorOps 既非磁碟掃描工具，也非磁碟清理工具。WizTree 已經能回答「什麼佔用了空間」——而 StorOps 回答了這些東西是什麼、它們是否安全可碰觸，並在使用者同意後安全地執行清理或遷移。完整設計原理請見 docs/DESIGN.md。
此文件定義了代理在使用 StorOps 時應如何行為——而不僅僅是哪些命令存在。建議優先遵循以下工作流程，而非隨意呼叫命令；使用者無需知道命令名稱。
不可協商規則
- 分析先行。在提出任何建議之前，務必先掃描/檢查/識別，絕不能直接跳到寫入操作。
- 所有操作預設為唯讀。
storops scan、storops inspect、storops search、storops identify、storops cleanup plan和storops migrate plan絕不會修改檔案系統——可以直接執行，無需事先詢問。 - 切勿僅從路徑名稱猜測其用途。只有
storops identify（由rules/*.yaml支援）才能判定類別/風險/可刪除性。若某路徑沒有匹配規則，則回傳unknown/critical——應將其視為「不可碰觸」，而不是基於資料夾名稱進行推理。 - 切勿將名稱中包含「cache」或「temp」的資料視為可刪除的授權。只能處理
storops identify/storops cleanup plan實際分類的內容。 - 高風險路徑（Windows、Program Files、未知系統檔案、使用者文件）絕不提供刪除或遷移選項。這在程式碼中已強制執行（
src/storops/core/risk.py中的assert_not_critical），不僅是慣例——不要試圖繞過它。 - 每個寫入操作（
storops cleanup execute、storops migrate execute）都需要使用者先明確逐項確認，且 CLI 本身拒絕在沒有--confirm的情況下執行。先顯示計畫，等待使用者真正的「是」，然後傳入--confirm——絕不能預先代表使用者執行。 - 如果應用程式可能正在執行，請勿移動其資料。
storops migrate plan會標記RequiresAppClosed；在這種情況下，storops migrate execute拒絕在沒有明確的--app-closed確認下執行。請告知使用者關閉應用程式——不要假定已關閉，也不要自己終止進程。 - 對於大型、可重新下載的 AI 模型/快取資料（Hugging Face 快取、Ollama/LM Studio 模型等），在納入使用者批准的項目之前，務必明確說明後果（「這需要重新下載」）。
- 對於使用者認為有價值的任何資料，優先選擇遷移而非刪除。刪除僅適用於可回收/可拋棄的資料；大型模型或專案資料若不應拋棄，應提供「移動」而非「刪除」選項。
- 優先使用應用程式自身的配置重新定位，而非使用目錄連結（Junction）。
storops migrate plan已編碼此優先順序——不要僅因為目錄連結看起來更簡單而覆蓋它。 - 每次遷移後務必驗證（對
storops migrate execute產生的結果檔案執行storops verify）。如果驗證失敗，請直接說明並停止——絕不要為了「清理」失敗的驗證而刪除或進一步修改任何內容。 - 不要讓掃描後端（Windows 上的 WizTree，Linux/macOS 上的 gdu/du）成為你推理中的硬性依賴。如果後端完全缺失，CLI 會顯示明確錯誤，指出取得位置（WizTree：https://diskanalyzer.com/ 或
$env:STOROPS_WIZTREE_PATH；gdu：https://github.com/dundee/gdu 或$env:STOROPS_GDU_PATH）——將此資訊轉達給使用者，而不是嘗試以其他方式繞過。 - 在 Linux/macOS 上，每個讀取/計畫層級命令（
scan/inspect/search/cleanup plan/migrate plan）的--json結果都包含Backend和BackendAdvice欄位。BackendAdvice僅在 StorOps 因找不到gdu而回退到較慢的du後端時才非空。在每次對話中向使用者提一次（例如「順便一提，安裝 gdu 可以讓這些掃描明顯更快」）——不要在每個命令上都重複，也不要在 Windows 上或當其值為null時提及。
工作流程：「我的磁碟為什麼滿了？」
- 執行
storops scan C:\（或使用者提到的磁碟機），查看頂層消耗者和可用空間。 - 對於任何大型且未識別或含糊的項目，執行
storops inspect深入了解其實際內容。 - 對每個值得注意的項目，使用
storops identify進行交叉比對（scan/inspect 已附加身份和建議操作，但若使用者針對單一路徑提問，可直接呼叫它）。 - 呈現一個分層摘要：它是什麼、有多大，以及建議操作（KEEP / DELETE / MOVE / CHECK）及其原因和風險。
- 在此階段絕不刪除或移動任何內容——這純屬診斷。
工作流程：「清理磁碟空間」/「刪除 X」
- 確保目標已經被掃描/識別（如果還沒，先執行上述掃描工作流程）。
- 執行
storops cleanup plan（預設--max-risk low；僅在使用者明確表示可以接受中/高風險項目時才提高風險級別）。此命令會產生一個逐項列出的 JSON 計畫——尚未刪除任何內容。 - 按風險層級分組呈現計畫，包含每個項目的大小、應用程式和後果（明確說明中/高風險的後果，例如「可能需要重新下載」）。顯示總可回收空間。
- 要求使用者確認。如果使用者只需要一部分，則使用更嚴格的
--max-risk重新產生，或指出應跳過的項目——不要在未明確告知使用者變更內容的情況下手動編輯計畫檔案中的Approved標記。 - 僅在使用者確認後，執行
storops cleanup execute --plan-file <path> --confirm。 - 報告每個項目的結果（已刪除 / 已跳過 / 失敗）和總回收空間。若項目失敗（例如檔案正在使用中），則報告該項目，而不強制重試。
工作流程：「將 X 遷移到另一個磁碟機」
- 識別來源路徑（如果尚未從掃描中得知，則執行
storops identify）。如果路徑不可遷移（Migratable），則說明原因（例如關鍵系統路徑，或沒有已知的遷移路徑），而不是自行臨時湊合。 - 執行
storops migrate plan <source> <destination>。此命令決定方法（應用程式配置變更，或目錄連結作為備用方案），並產生有序步驟列表——尚未移動任何內容。 - 呈現計畫：來源、目標、大小、方法，以及應用程式是否需要先關閉。如果
RequiresAppClosed，明確要求使用者先關閉應用程式再繼續。 - 要求使用者確認整個計畫。
- 執行
storops migrate execute --plan-file <path> --confirm（一旦使用者確認應用程式已關閉，則加上--app-closed）。此命令會複製資料、驗證檔案數量/大小是否與來源相符，然後才移除原始資料——對於目錄連結方法，還會重新連結舊路徑。 - 如果方法是應用程式配置變更（而非目錄連結），則告知使用者需要進行的確切配置變更（來自計畫的
MigrationHint）——StorOps 本身不會編輯任意應用程式配置檔案。 - 執行
storops verify --result-file <path from migrate execute output>並報告每個檢查項目的 PASS/FAIL。如果 FAIL，則停止並準確描述哪些項目不符——絕不要為了「解決」驗證失敗而刪除剩餘資料。
工作流程：「刪除/移動 安全嗎？」
只需執行 storops identify <path> 並逐字傳達類別、可刪除性、可遷移性、清理風險、後果以及建議操作——這是直接、確定性的答案；不要對規則庫的實際內容進行修飾，也不要對 unknown 結果進行猜測。
命令參考
| 層級 | 命令 | 確認 |
|---|---|---|
| 讀取 | storops scan、storops inspect、storops search、storops identify | 無 |
| 計畫 | storops cleanup plan、storops migrate plan | 無（僅產生計畫檔案） |
| 寫入 | storops cleanup execute、storops migrate execute | 需要 --confirm（以及需要時加上 --app-closed） |
| 驗證 | storops verify | 無（唯讀重新檢查） |
每個命令都支援 --json 以輸出機器可讀的格式。以 python -m storops <command> ... 或（如果已透過 pip install 安裝）storops <command> ... 的方式呼叫。
請參閱 README.md 了解設定/需求，以及 rules/README.md 了解識別背後的規則結構。