ホーム / 全スキル / ワークフロー＆基本ツール / storage-analyzer
English (EN)简体中文 (ZH)日本語 (JA)
ワークフロー＆基本ツール · KKKKhazix/khazix-skills

storage-analyzer

macOS / Windows 読み取り専用ストレージ分析アシスタント（OS自動判別）。ディスク全体の占有状況をスキャンして容量を圧迫している要因を特定し、各項目を「🟢 自動削除可 / 🟡 要手動判断 / 🔴 慎重に対処」の3段階に分類して実行可能な対処手順を提示します。デザイン性に優れ、折りたたみ表示やコマンドのワンクリックコピーが可能なインタラクティブHTMLレポートを生成し、ローカルサーバーを起動してWebページ上からワンクリックで削除（ゴミ箱へ移動／完全削除）することも可能です。スキャン処理は完全に読み取り専用です。ユーザーが「ストレージ分析」「ディスク容量不足」「Cドライブ/HDDがいっぱい」「空き容量がない」「容量を空けたい」「ディスクのクリーンアップ」「容量を食っているもの」「何が容量を圧迫しているか」「ストレージを見てほしい」「PCのストレージ/空き容量を確認」「メモリ不足/足りない」（日本語や中国語の口語では「メモリ」がストレージ容量を指す場合があります）「storage analysis」「disk cleanup」「キャッシュ削除」「ディスククリーンアップ」と言った場合、またはPCの空き容量不足を訴えたり、容量を消費している原因やクリーンアップの提案を求めたりする場面で必ず使用してください。注意：ユーザーが明示的に実行メモリ／RAM（例：「どのプロセスがメモリを消費しているか」「メモリ使用率が高い」「アクティビティモニタを見たい」）を指している場合は、ストレージではなくRAMの問題であるため本スキルの対象外です。

L4 高権限 · 段階的認可と監査V1 コミット固定コマンド実行ネットワーク通信ファイル書き込みDual-pass Audit
Author KKKKhazixGitHub KKKKhazix/khazix-skills ↗Stars 20687License MIT（仓库根 LICENSE，Copyright (c) 2026 数字生命卡兹克）Commit 48e8ba527f
管理レベルは Skill の能力と推奨統制措置を示すものであり、品質や安全性の認証、利用可否の判定ではありません。使用の可否はユーザーおよび管理者が決定します。Agent 環境によって制約が異なるため、自動保護を仮定しないでください。第三者製 Skill の著作権は原著作者に帰属し、利用リスクは利用者が負います。

1仕組みと動作原理

4段階パイプライン：読み取り専用スキャン → agentによるトリアージ分析 → インタラクティブHTMLレポート生成 → 対話内での結論先行サマリー提示。スキャンとレポート生成は分離されており、中間生成物は単一のJSON形式です。

storage-analyzer/SKILL.md
对 macOS 做一次只读存储分析，产出交互式 HTML 报告。流程：扫描 → 分析分级 → 生成网页 → 打开。

スキャナーは完全読み取り専用：df/du/diskutil/stat/ls および os.scandir のみを使用し、ディスクへの書き込みは一切行いません。スクリプトのdocstringとSKILL.mdの鉄則の双方で明記されています。

storage-analyzer/scripts/scan.py
STRICTLY READ-ONLY: only sizes/lists/reads metadata. Never creates, moves, or deletes anything.
SKILL.mdの鉄則にも「スキャン、統計、ディレクトリ一覧取得、メタデータ読み取り（df、du、diskutil、stat、ls）のみ実行可能。rm、mv、rmdir、ゴミ箱を空にする、パーミッション変更など、いかなる書き込み操作も厳禁」と明記されています。

スキャナーはOS（sys.platform）を自動判別し、2通りの対象ディレクトリを処理します。macOSでは home/library/caches/containers/app_support/applications/downloads/dev_caches をスキャンし du でサイズを算出、Windowsでは user_profile/appdata/temp/downloads/program_files をスキャンし os.scandir を使用します。

storage-analyzer/SKILL.md
- **macOS**：扫 home、library、caches、containers、group_containers、app_support、applications、downloads、dev_caches，用 `du` 算大小。 - **Windows**：扫 user_profile、appdata_local、appdata_roaming、temp、downloads、program_files(_x86)、dev_caches，用 `os.scandir` 算大小；`system.disks` 含所有盘符。

トリアージは全棚卸しではなく「クリーンアップ意思決定リスト」です。「削除・対処すべきか」の判断が必要な項目のみを3色シグナルに分類し、通常使用中のアプリケーションやシステムファイルは青色の「システムおよびその他」に分類します。

storage-analyzer/SKILL.md
**三级分类 = 清理决策清单，不是全盘点。** 只把"存在'要不要动它'这个决策"的项放进三灯；日常在用的正常应用、操作系统本身、海量零碎小文件没有清理决策，不进三灯，它们落在磁盘条的蓝色"系统及其他"里。判定标准：

ワンクリック削除はローカルサーバーを利用：server.py が 127.0.0.1 のランダムポートで起動し、セッションごとのランダムトークンを発行。POST /action のリクエスト時のみ実行されます。静的モード（build_report.py）では削除ボタンは明示的に非表示となります。

storage-analyzer/scripts/server.py
- Bound to 127.0.0.1 only; every POST requires the session token; Host header
SKILL.mdにも「ユーザーが共有や保存用の読み取り専用ファイルのみを明示的に求めた場合にのみ静的モードを使用する（`file://` 経由で開いたページはファイルシステムにアクセスできないため、削除ボタンはありません）」と補足されています。

安全モデルは厳格度順の3重ホワイトリスト：rm は緑シグナルの trash_paths のみ、trash は緑および黄シグナルの trash_paths を許可、open はさらに黄シグナルの path と赤シグナルの app_paths を許可。すべて realpath 検証を受け、$HOME 配下であることが必須です。

storage-analyzer/SKILL.md
**安全模型——三套白名单，权限从严到宽**：`rm` 只允许绿灯 `trash_paths`；`trash` 允许绿灯+橙灯 `trash_paths`（橙灯永远不能 rm）；`open`（在文件管理器打开，非破坏性）允许上述全部 + 橙灯真实 `path`。所有请求 realpath 校验 + 必须在 $HOME 内 + token + Host 校验，每次点击浏览器先 confirm。

削除は直接の rm ではなくシステム標準のゴミ箱APIを使用：macOS では osascript 経由で Finder に delete させ（失敗時は ~/.Trash への移動にフォールバック）、Windows では SHFileOperationW + FOF_ALLOWUNDO を使用します。

storage-analyzer/scripts/server.py
script = 'tell application "Finder" to delete (POSIX file %s as alias)' % json.dumps(path)
server.py 内の _trash_windows は ctypes を介して shell32.SHFileOperationW を呼び出し FOF_ALLOWUNDO を付与します。hard_delete（shutil.rmtree/os.remove）はホワイトリスト内のパスにのみ適用されます。

黄シグナルはゴミ箱への移動（可逆）のみ許可し、赤シグナルは削除ボタンを一切置かず「ファイルマネージャーで開く」のみを提供します。これは「判断は必要だが手動削除は推奨されない」項目に対する明確な階層付けです。

storage-analyzer/SKILL.md
橙灯只准移废纸篓、可逆，绝不给"直接删除"）。App 托管又无安全子路径的（Chrome/微信）只给打开按钮、不给 trash_paths。按钮下方会自动写明注意事项（打开只查看不删、移废纸篓可逆需清空才释放等）；如果某项在文件管理器里是 App 内部格式、不方便手动挑选，给它一个 `open_note` 字段做客观说明（会显示在注意事项里）。**口吻要中性、像产品说明**：直接描述"这里是什么结构、为什么不好手动删、想精细操作该去哪"，不要写成"我发现/提醒注意/看着像没视频"这种暴露开发者踩坑视角的话。 - 🔴 **谨慎清理（有决策但不建议手删）**：你可能想动、但建议别手删的具体项——重复安装的应用、想卸载的大应用、运行中应用的核心数据等。给"为什么不建议手删" + `indirect_release` 写**具体卸载步骤**（自带卸载器 / 启动台长按 / 右键移废纸篓 / AppCleaner 清残留 / App Store 可重装等，要可照做不是空话）。应用项给 `app_paths`（真实 `.app` 绝对路径数组）→ 网页出现「在文件管理器打开（去卸载）」按钮，定位到 App 让用户自己正规卸载。**红灯不给删除/卸载按钮**
赤シグナルの項目には indirect_release（具体的なアンインストール手順）と app_paths の提示を義務付け、ユーザー自身がFinder/エクスプローラー上で正規のアンインストールを行えるようにします。

レポートは固定された読書導線を持つインタラクティブHTMLです：ディスク概要（プログレスバー）→ Top 5 → 実行推奨事項 → 3色の折りたたみカード（ワンクリックコマンドコピー付き）→ 長期最適化提案、すなわち「現状 → 診断 → 処方 → 操作 → 予防」の流れで構成されます。

storage-analyzer/SKILL.md
报告阅读流（固定顺序）：磁盘总览卡片（容量 + 进度条 + 三色容量 pills + 系统信息，纯数据）→ 占用排行 Top5 → 执行建议 → 🟢🟡🔴 三级可折叠卡片（命令一键复制）→ 长期优化建议。

Windowsサポートは実機未検証であることを誠実に明記し、初回実行時のパス確認、scandirによるサイズ集計、ゴミ箱削除の確認を求めています。複数ドライブレターの走査には対応済みです。

storage-analyzer/SKILL.md
- **Windows**：代码已写（`scan.py` 的 `scan_windows`、`server.py` 的 `_trash_windows` 走 `SHFileOperationW`），但**未在真实 Windows 上实测**。

サードパーティ製依存関係ゼロ：スクリプトはPython 3標準ライブラリのみを使用し、macOS標準の python3/du/diskutil/osascript を活用するため、導入後すぐに動作します。

storage-analyzer/SKILL.md
- 全部脚本是 **Python 3 标准库**，零第三方依赖（不用 pip install）。

2コア機能

01macOS/Windows ディスク全体の読み取り専用スキャン（グループ別ディレクトリサイズ、容量消費Top項目、全ドライブレター/マウントポイント）
023色シグナルによるクリーンアップ意思決定（🟢 自動削除可 / 🟡 要手動判断 / 🔴 慎重に対処）と具体的な対処手順の提示
03「謎の大容量ディレクトリ」の特定：UUID名のContainerや隠しディレクトリを具体的なアプリや内容まで追跡
04インタラクティブHTMLレポート（折りたたみカード、コマンドのワンクリックコピー、分割プログレスバー、ステータスバッジ）
05ローカルWeb画面からの選択式クリーンアップ：ブラウザ上でのワンクリックゴミ箱移動（可逆）または直接削除（🟢 項目）
06静的読み取り専用レポートのエクスポート（共有・アーカイブ用、削除機能なし）
07長期的な最適化アドバイスの提供（brew cleanup、DerivedData、可視化ツール、外部ストレージ退避、OSストレージ最適化）
08トラブルシューティング案内：Web上に削除ボタンが表示されない＝静的レポートモード、または緑シグナル項目の trash_paths 指定漏れ

4推奨統制措置と判定根拠

安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
  • scripts/: ローカルスクリプト・コマンドの実行: scripts/scan.py（読み取り専用スキャン。subprocessで du/df/diskutil 等のシステムコマンドを呼び出し、書き込みは一切行わない）
  • 网络端点: 外部ネットワークアクセスの宣言: ローカルループバックのみ: http://127.0.0.1:<ランダムポート>/ でレポートページ配信および POST /action を受付（Hostヘッダーは 127.0.0.1/localhost に限定）
  • 本地工作目录: ファイル入出力と成果物出力: /tmp/storage_scan.json（スキャン結果）、ユーザー指定の analysis JSON（agentが出力）、レポートHTML（静的モード時に書き出し）
監査ノート： 判定対象：本スキルディレクトリ（SKILL.md + scripts×3 + assets/report_template.html + references×2、すべてPython 3標準ライブラリ、外部依存ゼロ）。すべての動作がローカル内で完結：読み取り専用スキャン → agentによるトリアージ → レポート生成 → 任意起動の127.0.0.1サーバーによる選択的クリーンアップ。外部ネットワーク通信なし、認証情報読み取りなし、サードパーティ製パッケージなしのため、Blue判定となります（Greenではない理由：独自スクリプトを同梱し、ディスク書き込みを行い、ユーザーの操作に応じて実際のファイル削除を実行するため）。安全境界は極めて明確に定義されています：rm は緑シグナルの trash_paths のみ、trash は緑＋黄シグナルを許可、open は赤シグナルの app_paths も含め許可。すべて realpath 検証を実施し、$HOME 配下を必須とし、セッショントークン、Hostヘッダー検証、ブラウザでの2重確認を経て実行され、赤シグナル項目には一切削除ボタンが提供されません。注意点：完全削除は不可逆である点、ホワイトリストの安全性はagentのトリアージ精度に依存する点、レポートサーバー起動中はトークンで保護されたローカル削除エンドポイントが一時的に開放される点（Ctrl+C で即座に終了可能）。

5二重目の独立検証

  • [ok] 扫描器确实只读 — scan.py 只用 os.scandir/os.listdir/du/df/diskutil 等读取与统计；无 open(...,"w")、无 shutil.rmtree/os.remove、无 mkdir；docstring 明写 STRICTLY READ-ONLY。
  • [ok] 服务侧白名单构造与文档一致 — load() 中：green.trash_paths → rm/trash/open 三集合；yellow.trash_paths 只进 trash+open；yellow.path（存在时）只进 open；red.app_paths（存在时）只进 open——与 SKILL.md「三套白名单，权限从严到宽」逐条对应。
  • [ok] 删除请求的多重校验 — do_POST 依次校验：Host ∈ {127.0.0.1, localhost}、token 相等、mode ∈ {rm,trash,open}、每个 path realpath 后必须在对应白名单、且必须在 HOME 或 /Applications 之下（删除类白名单不含 /Applications）。
  • [ok] 回收站删除的实现 — macOS: osascript `tell application "Finder" to delete (POSIX file ...)`，失败回退 shutil.move 到 ~/.Trash；Windows: ctypes 调 SHFileOperationW，fFlags 含 FOF_ALLOWUNDO（进回收站）。
  • [ok] 无公网请求 — 全目录 URL 扫描仅命中 http://127.0.0.1:%d/（服务自述地址）；无 CDN、无遥测、无第三方 API。
  • [ok] 无凭证读取 — API_KEY/token/secret 扫描：唯一 token 变量是 secrets.token_urlsafe(24) 生成的会话 token，非用户凭证；无 env 读取、无 keychain、无配置文件读取。
  • [ok] 静态报告确实没有删除能力 — build_report.py 把 __DELETE_CONFIG__ 替换为 "null"；模板里的 fetch(DELETE.endpoint, ...) 只有在服务模式下注入 token/endpoint 才可用（SKILL.md 的排障段落也这么说）。
  • [ok] 零第三方依赖 — 三个脚本 import 仅 json/os/secrets/shutil/subprocess/sys/time/webbrowser/http.server/re/ctypes；无 requirements/pip 指令。

6結論

  • 「読み取り専用スキャン＋明示的なクリック削除」により破壊的な判断をユーザーの手に委ね、リスクに応じて削除操作を3段階（直接rm / ゴミ箱移動のみ / フォルダを開くのみ）に厳格に分類。
  • 堅牢なローカルサーバーセキュリティ：127.0.0.1バインド、ランダムポート、セッショントークン、Hostヘッダー検証、realpath解決、$HOMEガードレールにより、DNSリバインディングやパストラバーサルを防止。
  • 標準ライブラリのみで構成された依存関係ゼロの実装（Mac/Windows双方対応）、完成度の高いレポートUI（分割ディスクバー、折りたたみカード、コマンドコピー）。
  • 全棚卸しではなく「意思決定リスト」としてトリアージするため、無意味な項目が画面を埋め尽くすことがない。
  • 「手動削除非推奨」の項目に対し、単に「削除不可」と告げるだけでなく、安全にアンインストールするための正規手順と app_paths を提供。
  • Windows環境が実機未検証であることを明記し、初回検証チェックリストを提供している誠実な設計。
    • 最適な用途： macOS（および自己検証可能なWindows）ユーザーがマシン全体のストレージ総点検を行うのに最適です。容量を食っている要因の特定、再生成可能なキャッシュと個人データの選別、クリックで削除可能なインタラクティブレポートの取得が可能です。また、「ディスク分析＋段階的対処」の基準をチームやカスタマーサポートの対応マニュアルとして定着させる用途にも適しています（分類基準やトーン設定をそのまま再利用可能）。
    不向きな用途： RAM/メモリ使用率のトラブルシューティングには不向きです（説明文で明確に対象外と定義、アクティビティモニタの管轄）；無人環境での完全自動クリーンアップには不向きです（設計上、ユーザーの選択と確認が必要）；不可逆な削除を一切許容できない環境には不向きです（静的レポートのみを利用するか、ゴミ箱移動に限定する場合を除く）；Windowsの本番環境では事前にテスト機で検証することを推奨します。
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload storage-analyzer.tar.gz
    sha256: b8b3f5bde010e27b…
    Option B · Copy Guide for Agent
    install.json
    Agent はこの JSON ガイドから自動的にダウンロードして検証します。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 48e8ba527f.