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を渡すこと——先回りしてユーザーに代わって--confirmを指定してはならない。 - アプリケーションが動作中の可能性がある場合、そのデータを移動してはならない。
storops migrate planはRequiresAppClosedフラグを立てる。storops migrate executeはその場合、明示的な--app-closedの確認なしでは実行を拒否する。ユーザーにアプリを閉じるよう伝えること——閉じていると決めつけたり、自分でプロセスを強制終了してはならない。 - 大規模で再ダウンロード可能なAIモデル/キャッシュデータ（Hugging Face キャッシュ、Ollama/LM Studio のモデルなど）については、ユーザーが承認する前に必ず結果を明確に伝える（「これは再ダウンロードが必要になります」）。
- ユーザーが価値があると判断したものについては、削除よりも移行を優先する。削除は再利用可能または使い捨て可能なデータに対してのみ。大規模なモデルやプロジェクトデータで使い捨てできないものは「削除」ではなく「移動」として提示すること。
- アプリケーション自身の設定による再配置をジャンクションより優先する。
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は、gdu が見つからなかったために StorOps が低速なduバックエンドにフォールバックした場合のみ非 null になる。会話の中で一度だけユーザーに言及する（例：「ところで、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を実行する。 - 結果を項目ごとに報告する（削除済み / スキップ / 失敗）と、回収された合計容量。
failed項目（例：使用中のファイル）は報告するが、強制的に再試行はしない。
ワークフロー：「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 <migrate execute 出力からのパス>を実行し、各チェックの PASS/FAIL を報告する。FAIL の場合は停止し、正確に何が一致しなかったかを説明する——検証失敗を「解決」するために残ったデータを削除してはならない。
ワークフロー：「<パス>を削除/移動しても安全か？」
単に storops identify <path> を実行し、Category、Deletable、Migratable、CleanupRisk、Consequence、推奨アクションをそのまま伝える——これは直接的な決定論的な答えであり、ルールベースが実際に言っていること以上に解説を加えたり、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 を参照してください。