1仕組みと動作原理
エントリルーティング機構：ユーザーの兆候に基づき最も狭いパスを選択。名前付きの疑わしいソース（Apple Content Caching、Docker、Chromiumのコード署名クローン、特定のキャッシュディレクトリ）はまず専用のリファレンス文書を参照し、原因が真に不明な場合のみ汎用スキャンを実施します。
daymade-macos/macos-cleaner/SKILL.md
Choose the narrowest path that can answer the request
「全盤スキャンより名前付きの疑わしいソースを優先」により、冒頭からhome全体に対してduを実行することを防止。ユーザーが指定したスコープ除外項目は、あらゆる汎用スキャンの提案に優先します。
安全機構のコアは「観察と変更の分離 ＋ 精密な承認ゲート」による4相ステートマシン：Observe（読み取り専用）→ Plan（確認ゲートで一時停止）→ Execute（承認されたスコープのみ）→ Verify（独立した再読み込み）。第2相と第3相を単一のメッセージに統合することは禁止されています。
daymade-macos/macos-cleaner/SKILL.md
Do not compress phases 2 and 3 into one message. A plan printed beside a cleanup command is not a confirmation gate.
明示的に番号付けされた10条の「Safety and authorization contract」（観察と変更の分離、正確な対象の確認、計画の先行、明示的承認の要求、精密に制御されたコマンド、pruneの禁止、広範なrmの禁止、価値ある状態の保護、実行は認可に追従、fail-fast）。
読み取り専用診断は独自開発のPythonスクリプト群（analyze_caches、analyze_dev_env、find_app_remnants、analyze_large_files、analyze_code_sign_clones）によって実行され、厳格な物理割り当て計算規範に従います。duはパス記帳であり物理的な解放ではありません（APFSクローンはエクステントを共有）。
daymade-macos/macos-cleaner/SKILL.md
shared extents can be attributed to every path, so actual release remains unknown until deletion and `df` readback
レポートにはnominal（パス記帳）とphysicalの両列を併記。停止条件は「精密なアクションが存在し、物理的解放が立証可能」な候補のみを対象とし、論理サイズ、Trashへの移動、未検証の削減見込み量はカウントしません。
2系統の削除パス：Finder Trashを優先（osascriptによる削除は復元可能だが、物理容量はゴミ箱を空にして初めて解放）。レガシーなsafe_delete.pyは拒否リストと対話的確認を備えた完全削除ヘルパーですが、ドキュメント上で明縮格付けされています（Trash非経由、全ユーザーデータルートの未検査、開かれているファイルの未検知）。
daymade-macos/macos-cleaner/scripts/safe_delete.py
HIGH_RISK_PATHS = frozenset( _canonical_path(path) for path in [ '/System', '/Library/Apple', '/usr', '/bin', '/sbin', '/etc', '/private/var/db', '~/.ssh', '~/.aws', '~/.gnupg', '~/Library/Keychains', ] )
拒否リストはシステムディレクトリおよび認証情報ディレクトリをカバー。confirm_deleteはdocuments/desktop/credentialsなどの危険なパターンに対して追加警告を発行。一括モードは'all'をサポート（個別の危険警告をスキップ。SKILLドキュメント上は精密な承認後のみ使用可能とし、ユーザー文書への適用は禁止）。
Docker/OrbStackの規律：オブジェクト単位の分析（各イメージ/コンテナ/ボリュームの列挙、参照関係やライブラリ種別の確認、スパースファイルの実際の割り当て）、データベースボリューム名（mysql/postgres/redis/mongo/mariadb）は内容検査を実施して初めて削除提案が可能。**prune系コマンドは絶対に使用禁止**。
daymade-macos/macos-cleaner/SKILL.md
**Never use Docker prune-family commands.** This includes image, container, volume, system, builder, and buildx prune.
docker_analysis.mdの検査には一時コンテナdocker run --rm --pull=never --network=none --read-only --cap-drop=ALL（ネットワークなし、読み取り専用、権限全剥奪）を使用。danglingはデータが無価値であることを意味せず、build cacheは測定のみで削除は行いません（Dockerにはカテゴリ単位のprune制御しかないため）。
事後検証の規律：前後のdf読み取り値から実際の回収量を算出（削除ツールの自己申告は不採用）、クリーンアップ対象サブシステムの再検査、重要な共存サービスに対するPID/ヘルスプローブの再解決、APFSの記帳遅延やバックフィルの可能性がある場合は制限付きの間隔で観察。終了コードが判明しただけの段階で「fixed」と報告することは禁止。
daymade-macos/macos-cleaner/SKILL.md
Never report “fixed” when only the command exit code is known. A successful cleanup requires both the intended state and the protected invariants.
任意のcleanup_report.pyは~/.macos-cleanerにbefore/afterのスナップショットを書き出して比較を補助しますが、ドキュメントではdfの直接読み出しこそが真実の情報源（source of truth）であると規定されており、ローカルターゲットでのみ実行されます。
2コア機能
01ディスク圧迫の根本原因診断（アイデンティティ/ベースライン/サブシステムの状態 ＋ df -k/-h の計算と表示の分離）
02Apple Content Caching / AssetCacheManagerUtil の専門診断および制御されたクリーンアップ（references/apple_content_caching.md 全文を先行参照）
03Chromium コード署名クローンの名目/物理分離分析（analyze_code_sign_clones.py による読み取り専用インベントリ、非上書きマニフェストの任意出力）
04開発環境/キャッシュ/大容量ファイル/アプリ残存ファイルの読み取り専用スキャン（caches/dev_env/large_files/app_remnants の4スクリプト）
05正確な対象確認 ＋ 影響・復旧・サービス影響・事後条件を網羅したクリーンアップ計画表の提示
06Finder Trash優先削除 ＋ 明示的承認に基づくレガシーで保護された完全削除
07前後スナップショットレポート作成（cleanup_report.py --snapshot before/after --compare）
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | df / du / lsof / pgrep / launchctl / ps（系统状态与分配测量） |
| cli | uv（运行 bundled python 脚本） |
| cli | osascript（Finder Trash 删除） |
| cli | docker（可选：per-object 分析 + 受权后的临时只读检查容器） |
| cli | mo / Mole（可选第三方全盘扫描器 github.com/tw93/Mole，需用户批准其固定宽扫描根） |
| cli | sudo AssetCacheManagerUtil / AssetCache（受权后的服务控制） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: scripts/analyze_caches.py / analyze_dev_env.py / find_app_remnants.py / ana
- scripts/ 或 SKILL.md: 外部言語パッケージ依存の動的インストールの宣言
- 本地工作目录: ファイルの読み書きおよび成果物の出力: ~/.macos-cleaner/{before,after}.json（cleanup_report.py スナップショット）
監査ノート： ローカル完結型クリーンアップスキル：外部ネットワーク通信を行わず、認証情報の読み取りも行いません（~/.sshやKeychains等は明示的に保護）。黄色判定の理由は、承認後に実際の破壊的アクションを実行する設計であるためです——完全削除ヘルパー（safe_delete.py の拒否リスト＋対話確認）、Finder Trash、Dockerオブジェクトの削除、sudo AssetCacheManagerUtil によるサービス制御、ならびに任意の全盤読み取り専用スキャン（Moleによるhome/システムライブラリ/apps/volumesのスキャン）やDockerボリューム内容の検査が含まれます。破壊的動作は「10条の認可契約 ＋ 4相ゲート ＋ 正確な対象確認 ＋ 事後のdf/サービス検証」によって強固に制約され、デフォルトは読み取り専用ですが、データ損失のリスクが構造上存在するため「注意して使用」の黄色判定となります（認証情報取得や外部送信はないため橙色には至りません）。
5二重目の独立検証
- [ok] safe_delete.py denylist 与删除逻辑 — HIGH_RISK_PATHS 含 /System、/usr、/bin、/etc、~/.ssh、~/.aws、~/.gnupg、~/Library/Keychains 等；delete_path 对 is_high_risk_path 直接拒绝；文件 unlink/目录 shutil.rmtree。
- [ok] 『观察/变更分离 + 确认门禁』在源码与文档双重存在 — SKILL.md 10 条 contract + 四相状态机 + 'Do not compress phases 2 and 3 into one message'；safe_delete 每次删除前交互 input('[y/N]')。
- [ok] nominal vs physical 纪律有代码/文档支撑 — SKILL.md 明示 du 路径记账 vs df 物理读回；cleanup_report 只做 df 快照不做释放断言；safe_delete 输出 'Measured size removed' 并提示 'Physical release: verify with before/after df -k'。
- [ok] Docker prune 禁令与 per-object 纪律 — SKILL.md 六行明文禁 prune 家族；docker_analysis.md 给 --pull=never --network=none --read-only --cap-drop=ALL 的只读检查容器配方。
- [ok] 无网络/无凭证（安全结论基础） — 全目录扫描零网络调用代码、零凭证读取；Mole/AssetCacheManagerUtil 等外部工具仅在有授权与安装前提下由宿主调用。
- [ok] batch 'all' 可跳过逐项危险模式警告的注意点 — safe_delete.py batch_confirm 支持输入 'all' 直接返回全部 items（不做 danger_patterns 逐项检查，仅 denylist 兜底）——已在 risks 注明；SKILL.md 也限定该助手仅用于精确批准的非用户数据目标。
- [ok] 元数据（commit/license/stars） — 本地 HEAD == pin d5c4678cb5d4fd6acc9c922690df035dbd33d247；GitHub API：MIT、stars 1385（2026-09-09 实采）、pushed_at 2026-09-09T12:33:29Z。
6結論
最適な用途： macOSのディスク警告、「コンテンツキャッシュにさらに空き容量が必要です」の通知、大容量キャッシュの蓄積に対する実際のクリーンアップに適しています。特に「読み取り専用診断 → 計画承認 → 実行 → 事後検証」のフローを受け入れ、正確な確認指示を出せるユーザーに最適です。リモートMacの慎重な運用保守や、Docker/Chromium/開発キャッシュの専門的クリーンアップにも確立された手順を提供します。
不向きな用途： WindowsやLinuxには不向き。「ワンクリックで静かに自動クリーンアップ」を求めるユーザーには不向き（監査範囲の定まらない自動削除を明文で拒否しているため）。ディスク容量回収の目的がなく、単にアプリの挙動を調整したいだけのユースケースには不向き。広範な読み取り/変更権限を付与したくないユーザーや、具体的な空き容量目標を提示できないユーザーには不向きです。
Install Agent-Ready
① Verified Mirror 2026-09-09
Option A · Direct DownloadDownload macos-cleaner.tar.gz
sha256:
Option B · Copy Guide for Agent2e94bb1d20bbcc55…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.