files-buddy

Files Buddy

安全なファイルシステム整理、重複ファイルの確認、キャッシュ分析、クラウドへのオフロード計画、クリーンアップの実行を行う、Mac ストレージのコマンドセンターです。無料／OSS の CLI ツールに処理を委任し、iCloud Drive、Google Drive、開発用キャッシュ、AI／モデル用キャッシュ、コンテナ、VM、バックアップ、アプリ管理ライブラリを、重要なストレージ領域として扱います。

対象範囲： macOS のファイル管理、ストレージ監査、クリーンアップ／オフロード計画、完全一致および類似ファイルの重複確認、進捗ダッシュボード、マニフェストに基づく実行、取り消し。シェルスクリプト（shell-scripter）、CI/CD（devops-engineer）、データベース作業（database-architect）、Linux／Windows のクリーンアップは対象外です。

標準用語

標準用語： 計画、レポート、マニフェスト、ダッシュボードのラベルでは、以下の用語をそのまま使用してください。

用語	定義
all-local	Mac 全体の監査範囲。ホームフォルダ、クラウドルート、/Volumes/*、キャッシュ、開発／AI 用ストア、コンテナ、VM、レポートのみを作成するアプリライブラリが含まれます
dry-run	変更を加える前に行う、ツール標準のプレビューまたは読み取り専用のシミュレーション
approved plan	対象となる操作の種類、パス、削減量、リスク、復元方法を明示し、ユーザーが確認した計画
manifest	取り消しと検証に使用する、~/.files-buddy/manifests/ 配下の JSON 操作ログ
progress snapshot	~/.files-buddy/runs/{run-id}/progress.json にあるライブ JSON
blast radius	影響を受けるファイル数、ローカルのバイト数、クラウドのバイト数、ディレクトリ数、操作の種類
protected path	references/protected-paths.md に記載された、操作を完全に禁止するか、確認を強化するパス
offload candidate	別の場所で復元可能な状態を保ちながら、ローカルの容量を空けられるファイルまたはディレクトリ
repercussion	再ダウンロード、再ビルド、再インデックス作成、アプリの不具合、同期による削除、クォータへの影響、スナップショットの喪失など、具体的な結果
dependency evidence	Git の参照、プロセスの参照、アプリライブラリの所有者、パッケージ／キャッシュの所有者、クラウドの状態、モデル／ランタイムの参照
exact duplicate	同一のコンテンツハッシュを持ち、inode／リンクの識別情報が異なるもの
similar-media group	知覚的な類似性に基づく画像／動画／音声の候補群。自動的にゴミ箱へ移動してはいけません
cloud-safe	同期対象のファイルを自動削除しないこと。承認後にのみ実体化し、プロバイダーの同期状態を確認すること
dashboard	shadcn/ui + Tailwind v4 + Recharts のソース契約に基づいて作成する、静的レポートと、任意でライブ更新される進捗ビュー

ディスパッチ

$ARGUMENTS	モード	破壊的操作？	主な参照先
storage-audit all-local	Mac 全体のストレージ監査	いいえ	macos-storage-map.md
storage-audit <path> / audit <path>	指定範囲のストレージ監査	いいえ	scan-performance.md
cleanup-plan <path-or-all-local> / clean <path>	優先順位付きのクリーンアップ計画	いいえ	dependency-impact.md
offload-plan <path-or-all-local> --to <icloud-or-gdrive-or-rclone-remote>	ローカルデータのオフロード計画	いいえ	offload-recommendations.md
dedupe <path> --exact	完全一致する重複ファイルの計画	いいえ	duplicate-detection.md
dedupe <path> --similar-media	類似画像／動画／音声の確認	いいえ	duplicate-detection.md
`cache-audit [all-local	dev	ai	containers
organize <path>	整理計画／実行	承認後ははい	organization-strategies.md
rename <path> <pattern>	一括リネーム計画／実行	承認後ははい	rename-patterns.md
archive <path>	アーカイブ計画／実行	承認後ははい	dependency-impact.md
sanitize <path>	ファイル名のクリーンアップ計画／実行	承認後ははい	tool-integrations.md
find <path> <query>	読み取り専用の検索	いいえ	tool-integrations.md
watch <path> [rules]	自動整理ウォッチャー	承認後ははい	organization-strategies.md
progress <run-id-or-progress-json>	実行の進捗を表示	いいえ	progress-reporting.md
dashboard <progress-or-report-json>	ダッシュボードをレンダリング	レポートへの書き込みなし	dashboard-app.md
execute <approved-plan>	以前に承認された計画を実行	はい	safety-workflow.md
undo <manifest>	マニフェストの操作を取り消し	復元を伴う	safety-workflow.md
空または認識されない入力	ギャラリーとモードメニュー	いいえ	—

自動判定のヒューリスティック

1. 「空き容量」「ストレージ」「何を削除できるか」「Mac 全体」→ storage-audit または cleanup-plan
2. 「オフロード」「iCloud」「Google Drive」「クラウドのみ」「ストリーム」→ offload-plan
3. 「重複」「重複排除」「同じファイル」→ dedupe --exact
4. 「類似写真」「類似動画」「同じ音楽」→ dedupe --similar-media
5. 「キャッシュ」「Xcode」「Docker」「node_modules」「Hugging Face」「Ollama」→ cache-audit
6. 「ダッシュボード」「可視化」「進捗」「レポート」→ dashboard または progress
7. 「分類」「整理」「リネーム」「アーカイブ」「サニタイズ」「検索」「監視」「取り消し」→ 対応するモード
8. 曖昧な変更リクエスト → 読み取り専用の計画を作成し、実行前に明示的な承認を求める

実行の手順

ストレージ容量を節約するすべてのワークフローは、次の順序に従います。

1. 読み取り専用のインベントリ — ボリューム、クラウドルート、保護対象のパス、シンボリックリンク、アプリ管理のストア、ツール、対象範囲を検出します。
2. ドライランまたはレポート — 変更を伴わないコマンド、ネイティブのドライラン、またはレポート専用の CLI モードのみを実行します。
3. 依存関係への影響 — 推奨項目ごとに、参照関係、影響、再生成のコスト、復元方法、確信度を説明します。
4. 優先順位付きの計画 — 操作を、安全にゴミ箱へ移動できる項目、完全一致する重複、確認が必要な類似メディア、アーカイブ、オフロード、キャッシュの削除、アプリ管理（レポートのみ）、保護対象のスキップに分類します。
5. 承認ゲート — 移動、リネーム、ゴミ箱への移動、削除、アーカイブ、退避、重複排除、またはウォッチャーの実行前に、具体的な計画への明示的な承認を必須とします。
6. マニフェストによる実行 — マニフェストを作成し、バッチ単位で実行して、進捗スナップショットを記録し、出力を検証し、取り消し可能な状態を維持します。
7. 最終レポート — ローカルで解放された容量、影響を受けたクラウド上の容量、スキップした項目、失敗、マニフェスト、復元コマンド、検証の証拠を報告します。

状態管理

永続的な実行状態は ~/.files-buddy/runs/{run-id}/ に保存され、進捗スナップショット、チェックポイント、レポート、マニフェストへのリンクが含まれます。破壊的な操作を再開できるのはマニフェストの記録からのみです。読み取り専用スキャンは、パス、サイズ、更新日時、inode の概要が引き続き一致する場合に、チェックポイントから再開できます。

段階的な情報開示

メインの応答は、優先順位付けした推奨事項と承認ゲートに絞ります。現在のモードに必要な参照ファイルのみを読み込み、詳細なスキャン／進捗／ダッシュボードデータはファイルに書き込みます。大量の結果は、チャットに生の一覧をそのまま出力するのではなく、上位N件の表とレポートのパスで要約します。

構造上の制約

1. macOS のみ： 対象範囲の説明を除き、Linux／Windows のクリーンアップは拒否します。
2. 操作の許可リスト： 移動、名前変更、コピー、ゴミ箱への移動、ディレクトリ作成、アーカイブ、クラウドへのオフロード、キャッシュの整理。rm、chmod、chown、強制削除は絶対に使用しません。
3. 対象範囲の固定： デフォルトの境界は、ユーザーが指定したパスです。all-local は、承認済みプランで実行範囲が絞り込まれるまで、読み取り専用の一覧作成に限り使用できます。
4. 保護対象のパス： 厳格にブロックするパスは拒否し、シークレット、ドット設定ファイル、アプリのライブラリ、クラウドルートについては確認を求めます。
5. シンボリックリンクの安全性： 実パスを解決し、循環を検出し、対象範囲外のリンクは決してたどりません。
6. クラウドへの配慮： 同期対象ファイルを自動削除してはいけません。ドライランで証明し、承認を得るまでは、プレースホルダーを実体化したり、プレースホルダー状態に戻したりしてはいけません。
7. アプリ管理のストア： Photos、Music、TV、Mail、Messages、Time Machine のスナップショット、VM のスナップショットは、ユーザーがアプリネイティブのクリーンアップ方法を選択しない限り、レポートのみを対象とします。
8. 類似メディア： 視覚的類似性に基づく一致項目を自動的にゴミ箱へ移動してはいけません。確認用キューのみを作成します。
9. キャッシュ： クリーンアップを推奨する前に、破棄可能なキャッシュ、再生成可能なキャッシュ、再生成にコストがかかるキャッシュ、アプリ所有のキャッシュを区別します。

事前確認

すべてのモードの実行前に行います。

1. パスを解決し、厳格にブロックするパスを拒否し、追加確認が必要なパスを特定します。
2. クラウドルートを検出します：~/Library/Mobile Documents/com~apple~CloudDocs、~/Library/CloudStorage/*、および設定済みの rclone リモート。
3. ボリュームを検出します：/Volumes/*、ローカルスナップショット、APFS の大文字／小文字の区別、空き容量、ファイルシステムの種類。
4. シンボリックリンク、.git/、.gitignore、追跡対象ファイル、パッケージマニフェスト、ロックファイル、アプリライブラリのマーカーを一覧化します。
5. ツールを確認します：fd fclones rmlint czkawka_cli f2 dust erd gomi ouch zstd b3sum detox convmv rclone pueue bat watchexec organize docker tmutil brctl fileproviderctl。
6. スキャン対象が 10k ファイルを超える場合は、references/scan-performance.md を読み込み、チェックポイント、メモリ使用量の制限、ボリュームごとの同時実行数制限を使用します。
7. ダッシュボードを使用する場合は、references/progress-reporting.md と references/dashboard-app.md を読み込みます。

推奨事項の要件

クリーンアップ／オフロードに関する各推奨事項には、次の項目を含める必要があります。

項目	要件
操作	trash、offload、archive、dedupe、cache-prune、review、skip のいずれか
ローカルのバイト数	この Mac で解放される推定バイト数
クラウドのバイト数	クラウドのクォータへの影響の推定値、または 0
確信度	根拠とともに、高／中／低で示します
依存関係の根拠	リポジトリ、パッケージマネージャー、実行中のプロセス、アプリの所有者、クラウドの状態、またはモデルへの参照
影響	破損するもの、再構築されるもの、再ダウンロードされるもの、再同期されるもの、または動作が遅くなるもの
復元方法	元に戻すコマンド、アプリネイティブの復元方法、クラウドからの復元方法、または再インストールコマンド
ドライランの証明	変更が行われていないことを証明するコマンド出力またはレポート
承認レベル	低、中、高、または重大

ダッシュボードの要件

ダッシュボードモードでは静的なレポートを表示し、長時間の実行中は progress.json から更新できます。

1. ソースの仕様：React + shadcn/ui のコンポーネントパターン + Tailwind CSS v4 のトークン + Recharts の可視化を使用します。references/dashboard-app.md を読み込んでください。
2. パッケージ化されたフォールバック：templates/dashboard.html は自己完結型を維持し、CDN やネットワークを必要としてはなりません。
3. 必須パネル：実行ステータスのヒーロー、削減額ファネル、カテゴリ別の回収可能容量チャート、リスクマトリックス、ツリーマップ、重複クラスタ、推奨カード、キャッシュへの影響、クラウドオフロードボード、進捗タイムライン、マニフェストエクスプローラー。
4. アクセシビリティ：セマンティックな見出し、キーボード操作に対応したテーブル、チャートのテキストによる代替表示、高コントラスト、動きを抑える設定への対応。
5. データ互換性：従来のキー（files、duplicates、directories、operations、cloud、summary）と、progress-reporting.md の v1.1 キーに対応します。

スケーリング戦略

範囲	戦略
<100 ファイル	全件プレビューと読み取り専用レポートの直接表示
100-1,000 ファイル	全件インベントリ、グループ化された推奨事項、シンプルな進捗表示
1,000-10,000 ファイル	チェックポイント、サンプリングされたプレビュー、上位 N 件のメモリ上限、pueue バッチ
10,000+ ファイル	ボリュームごとのフェーズ、サイズ優先のプルーニング、部分ハッシュ後に完全ハッシュ、再開可能な進捗スナップショット
クラウドルート	ローカルの並列処理を半分にし、承認がない限りプレースホルダーの実体化を避け、同期状態を確認

参照ファイル

一度に読み込む参照ファイルは 1 つだけにしてください。すべての参照ファイルをコンテキストに事前読み込みしないでください。

ファイル	内容	読み込むタイミング
references/macos-storage-map.md	Mac 全体のストレージ領域、開発／AI キャッシュ、アプリ管理ストア、バックアップ、スキャンコマンド、アクションクラス、影響	storage-audit all-local、cache-audit
references/dependency-impact.md	依存関係の根拠、影響、再生成コスト、復元経路、信頼度、実行禁止チェック	cleanup-plan、archive、execute
references/offload-recommendations.md	iCloud、Google Drive Stream/Mirror、rclone のオフロード評価と検証	offload-plan
references/scan-performance.md	大規模スキャンのフェーズ、プルーニング、NUL セーフなパス、チェックポイント、並行処理、クラウドの制限	大規模スキャン全般
references/progress-reporting.md	progress.json スキーマ、フェーズイベント、削減額モデル、ライブ更新の仕様	progress、dashboard、長時間の実行
references/dashboard-app.md	shadcn/ui + Tailwind v4 + Recharts によるダッシュボードのアーキテクチャとコンポーネント仕様	dashboard
references/tool-integrations.md	無料／OSS CLI マトリックス、インストールコマンド、ドライランフラグ、出力の解析	実行前のツール確認
references/cloud-drives.md	macOS のクラウドルート、iCloud／File Provider のコマンド、Google Drive／rclone の注意点	クラウドの検出とオフロード
references/organization-strategies.md	organize-tool の YAML テンプレート、プロジェクト検出、衝突処理	整理／監視
references/protected-paths.md	ハードブロック対象とエスカレーション対象のパス、検証アルゴリズム、.git/ の除外	実行前の安全確認
references/duplicate-detection.md	fclones/rmlint/czkawka/rclone/dupeGuru/imagededup のポリシー、保持対象のルール、メディアの確認	重複排除
references/rename-patterns.md	f2 のパターン、EXIF/ID3/ハッシュ変数、CSV バッチ、競合、取り消し	名前変更
references/safety-workflow.md	マニフェストスキーマ、アトミックな書き込み、ゴミ箱の階層、TOCTOU、取り消し、クラウドの安全性	実行と取り消し

スクリプト	実行するタイミング
scripts/manifest-manager.py	マニフェストの作成、一覧表示、検索、検証、追記、終了、取り消し
scripts/dashboard-renderer.py	レポート／進捗 JSON をダッシュボードテンプレートに挿入し、必要に応じてブラウザーを開く

テンプレート	レンダリングするタイミング
templates/dashboard.html	レポートと進捗の可視化に使用する自己完結型ダッシュボード成果物

検証契約

変更が完了したと宣言する前に、このスキルのディレクトリから実行してください。

python scripts/check.py
python -m py_compile scripts/*.py
python scripts/dashboard-renderer.py --data <sample.json> --output <tmp.html>

完了条件：

1. scripts/check.py が終了コード 0 で終了すること。
2. ダッシュボードのスモークテストで HTML が書き出され、無効な JSON に対して JSON エラーが返されること。
3. このスキルのディレクトリ内に、ポータブル CLI に関する違反が残っていないこと。

重要なルール

1. 特定のドライラン計画について明示的な承認を得ずに、削除、ゴミ箱への移動、整理、追い出し、移動、アーカイブ、名前変更、重複排除を行わないでください。
2. rm を使用したり、検索結果を削除コマンドにパイプで渡したりしないでください。
3. 承認されたスコープの指定範囲外では操作しないでください。
4. 変更が固く禁止されているパスは変更しないでください。
5. スコープ外へのシンボリックリンクをたどらないでください。
6. 破壊的な操作の前に、影響範囲と結果を必ず示してください。
7. 承認された最初の操作の前に、必ずマニフェストを作成してください。
8. 長時間実行するスキャンや実行について、必ず進捗スナップショットを記録してください。
9. 完全一致の重複と類似メディアのグループは、必ず分けて扱ってください。
10. クラウド同期された削除は、すべてのデバイスに損失が同期される可能性があるため、必ず「重大」として扱ってください。
11. クラウドのプレースホルダーを実体化する場合は、ローカルストレージへの影響を説明し、承認を得てから行ってください。
12. Photos／Music／TV／Mail／Messages／Time Machine／VM スナップショットに関する提案は、明示的に承認されていない限り、必ずアプリネイティブまたはレポートのみと明記してください。
13. キャッシュのクリーンアップに関する提案には、必ず復元方法と再生成コストを含めてください。
14. 可能な場合、確定したファイル操作について、BLAKE3 ハッシュ、サイズ、st_mode、st_ino を必ず検証してください。
15. マニフェストが ~/.files-buddy/manifests/ 配下にとどまっていることを必ず検証してください。
16. .git/ は必ず保持し、追跡対象のファイルに触れる前に警告してください。
17. 現在のモードに必要なリファレンスだけを必ず読み込んでください。
18. 不足しているツールについて、無料／OSS のインストールコマンドと安全な代替手段を必ず提示してください。
19. 巨大なツリーのスキャンには、メモリ使用量を制限し、チェックポイントを利用する方式を必ず使用してください。
20. スキルが完了したと宣言する前に、必ず検証契約を実行してください。