Disk Cleaner Skill - すべてのエージェント向け完全機能ガイド

🚨 重要: 絵文字使用ポリシー

スクリプト出力用（クロスプラットフォーム対応）

• スクリプト出力では絵文字を使用しないこと - すべてのスクリプトはASCII安全文字を使用
• スクリプトでは以下を使用: [OK]、[X]、[!]、[*]、[i]、[DIR]、[FILE]、[PKG]、[x]
• Windows GBKおよび他の非UTF-8コンソールでの互換性を確保
• スクリプト出力を修正して絵文字を追加しないこと - クロスプラットフォーム互換性が崩れます

エージェント対人間コミュニケーション用（推奨）

• ユーザーに結果を報告する際は絵文字を使用すること - 出力がより読みやすくなります
• ユーザーへの最終レポートでは以下の絵文字を使用してください:
  • ✅（成功）- 完了した操作、成功したスキャン
  • ❌（エラー）- 失敗した操作、致命的エラー
  • ⚠️（警告）- 警告、注意が必要な問題
  • 🔍（スキャン）- 検索/スキャン操作
  • 📊（統計）- 分析結果、統計
  • 📁（ディレクトリ）- ディレクトリ関連情報
  • 📦（パッケージ）- パッケージ/モジュール情報
  • 🎉（成功）- 完了成功のお祝いメッセージ
  • 🚨（緊急）- 重大な警告
  • 💡（ヒント）- 提案、推奨事項
  • 📋（リスト）- チェックリスト、要約
  • 🔧（ツール）- ツール、ユーティリティ
  • 🌐（グローバル）- クロスプラットフォーム、汎用機能
  • 🛡️（安全）- セキュリティ関連情報
  • ⚡（パフォーマンス）- パフォーマンス改善
  • 📝（ドキュメント）- ドキュメント
  • 🎓（学習）- 教育コンテンツ
  • 📞（サポート）- ヘルプ、サポート情報
  • 📈（成長）- 改善、獲得
  • 🎯（ターゲット）- 目標、目的
  • 🚀（起動）- クイックスタート、高速操作
  • 🛠️（ツール）- ツール関連機能

例:

スクリプト出力(ASCII):    [OK] スキャン完了: 30秒で50,000ファイル
ユーザーへのレポート:     ✅ スキャン完了! 30秒で50,000ファイルを検出

---

📦 完全機能リスト（最初に読んでください！）

🚨 重大事項: プログレッシブスキャン（大型ディスク必須）

• ✅ クイックサンプルモード: 1秒でディスク容量とスキャン時間を推定
• ✅ プログレッシブスキャンモード: 大型ディスク向けに30秒で部分的結果を取得
• ✅ スマート時間制限: ユーザーが数時間待つのを防止
• ✅ リアルタイムフィードバック: 2秒ごとに進捗更新
• ✅ 割り込み可能: Ctrl+Cで部分的結果を取得

🔧 インテリジェントブートストラップ（自動検出・インポート）

• ✅ 自動位置検出: 20以上の一般的なスキルパッケージの場所を検索
• ✅ 環境変数サポート: DISK_CLEANER_SKILL_PATH上書き
• ✅ 自動モジュールインポート: diskclearerモジュールを自動インポート
• ✅ フォールバック機構: 一部の機能が利用できない場合でも動作
• ✅ クロスプラットフォームPython検出: 'python'と'python3'の両方を試行

🌐 汎用互換性

• ✅ すべてのAI IDE: Cursor、Windsurf、Continue、Aider、Claude Code等
• ✅ すべてのプラットフォーム: Windows、macOS、Linux（Windows GBKコンソール含む）
• ✅ すべてのインストールレベル: グローバル、プロジェクト、ユーザーレベル
• ✅ 設定不要: すぐに使用可能
• ✅ クロスプラットフォーム対応エンコーディング: すべてのスクリプトはASCII安全出力を使用（v2.0以降）

🛡️ 安全性と信頼性

• ✅ 診断ツール: check_skill.py - すべての機能を検証
• ✅ 安全なエンコーディング: すべてのスクリプトはASCII文字を使用（出力に絵文字なし）
• ✅ 安全なデフォルト設定: クリーニングは--dry-run、スキャンはスマート制限
• ✅ 保護されたパス: システムディレクトリと実行ファイルを削除しない
• ✅ エラーハンドリング: エラー時のグレースフルデグラデーション
• ✅ GBK/UTF-8互換: Windows GBK、UTF-8およびすべての他のエンコーディングに対応

⚡ パフォーマンス最適化（すべて含まれます）

• ✅ QuickProfiler: スキャン特性を推定するための高速サンプリング
• ✅ ConcurrentScanner: 3～5倍の高速化のためのマルチスレッドI/O
• ✅ os.scandir()最適化: Path.globより3～5倍高速
• ✅ IncrementalCache: より高速な再スキャンのためのキャッシュ結果
• ✅ メモリ監視: 利用可能メモリに基づいて自動適応
• ✅ 早期停止: 設定可能なファイル/時間制限
• ✅ キャッシュ検出強化: 26以上のキャッシュパス（従来は8） - 225%改善

🆕 v2.2以降の新機能

• ✅ 重複ファイル検出: 適応的戦略を用いた重複ファイルの検出と削除
• ✅ 成長トレンド分析: ディスク使用量の時系列追跡、ディスク満杯予測
• ✅ インタラクティブウィザード: 安全確認付きのステップバイステップガイド付きクリーンアップ
• ✅ ファイル整理: インテリジェントなファイルアーカイブと整理（4つの戦略）
• ✅ スキャン制限強化: 500KファイルまでOK（従来は50K）、120秒タイムアウト（従来は30秒）
• ✅ ディープスキャンモード: --deep-scanで無制限スキャン
• ✅ Windowsディレクトリサポート: --include-windowsでシステムディレクトリスキャン

📊 利用可能スクリプト（13以上）

中核分析:

1. analyze_disk.py - スマートサンプリング付きディスク分析（v2.2強化）
2. analyze_progressive.py - 大型ディスク向けプログレッシブスキャン
3. find_duplicates.py - 重複ファイル検出（新機能 v2.2）
4. analyze_growth.py - 成長トレンド分析（新機能 v2.2）

クリーニングと整理: 5. clean_disk.py - 安全なジャンクファイルクリーニング（キャッシュ検出強化） 6. interactive_wizard.py - インタラクティブガイド付きクリーンアップ（新機能 v2.2） 7. organize_files.py - ファイルアーカイブと整理（新機能 v2.2）

監視と診断: 8. monitor_disk.py - ディスク使用量監視 9. check_skill.py - 診断ツール

開発者ツール: 10. skill_bootstrap.py - インテリジェントブートストラップモジュール 11. package_skill.py - パッケージ作成ツール 12. scheduler.py - 自動スケジューリング

🚀 マルチエージェント高速化（パフォーマンス向上のため重大）

🎯 重大インサイト: 並行処理のためにサブエージェントを使用

これはディスク・クリーナーをAIエージェントで使用する際の最も強力な機能の1つです！

複数エージェントを使用する理由

シングルスレッドスキャン:

エージェント スキャン → [Dir1] → [Dir2] → [Dir3] → ... (順次実行、遅い)

マルチエージェント並行スキャン:

メインエージェント
  ├─ サブエージェント-1 スキャン → [Dir1, Dir2, Dir3]（並行）
  ├─ サブエージェント-2 スキャン → [Dir4, Dir5, Dir6]（並行）
  └─ サブエージェント-3 スキャン → [Dir7, Dir8, Dir9]（並行）
結果: 3～10倍高速化! ⚡

マルチエージェントモード使用時期

✅ 以下の場合は常に使用:

• 複数のトップレベルディレクトリをスキャン（例: C:\、D:\、E:\）
• 複数ユーザープロファイルのクリーニング
• 大規模ファイルセット処理（>100Kファイル）
• 時間がクリティカルな操作

❌ 以下の場合は使用しない:

• 単一の小さいディレクトリ（<10Kファイル）
• クイック分析（<30秒）
• シンプルなクリーンアップタスク

マルチエージェントスキャンの実装方法

オプション1: エージェントツール使用（Claude Code推奨）

# サブエージェントを生成するエージェントコード
from anthropic import Anthropic

def parallel_scan_directories(directories_list):
    """
    複数ディレクトリを並行スキャンするためにサブエージェント使用
    """
    # ディレクトリをサブエージェント間で分割（3～5個が最適）
    chunks = split_list(directories_list, n_chunks=3)
    
    # サブエージェントを並行起動
    agents = []
    for i, chunk in enumerate(chunks):
        agent = Anthropic().agent.create(
            name=f"scanner-{i}",
            instructions=f"""
            スキャン対象ディレクトリ: {chunk}
            disk-cleanerを使用: --file-limit 50000 --time-limit 60
            JSON形式で結果を返す
            """,
            model="claude-sonnet-4-20250514"  # 高速モデル
        )
        agents.append(agent)
    
    # すべてのエージェントを待機して結果を集約
    results = [agent.wait() for agent in agents]
    return merge_results(results)

オプション2: 並行サブプロセス（プラットフォーム独立）

import subprocess
from concurrent.futures import ThreadPoolExecutor, as_completed

def parallel_scan_subprocess(directories_list):
    """
    並行サブプロセスコールを使用した複数ディレクトリスキャン
    サブプロセスをサポートするすべてのAI IDEで動作
    """
    def scan_directory(directory):
        """単一ディレクトリをスキャン"""
        cmd = [
            'python',
            'skills/disk-cleaner/scripts/analyze_disk.py',
            '--path', str(directory),
            '--file-limit', '50000',
            '--json'
        ]
        result = subprocess.run(cmd, capture_output=True, text=True)
        return json.loads(result.stdout)
    
    # 3～5個の並行ワーカーを使用
    with ThreadPoolExecutor(max_workers=4) as executor:
        futures = {
            executor.submit(scan_directory, d): d
            for d in directories_list
        }
        
        results = {}
        for future in as_completed(futures):
            directory = futures[future]
            try:
                results[directory] = future.result()
            except Exception as e:
                results[directory] = {"error": str(e)}
    
    return results

# 使用: C:\、D:\、E:\を並行スキャン
directories = ['C:\\', 'D:\\', 'E:\\']
results = parallel_scan_subprocess(directories)

オプション3: マルチプラットフォーム対応エージェントチーム（高度）

エージェント対応システム用（Claude Code、エージェント対応Cursor）:

# 作業の一部を処理する複数サブエージェントチームを作成
def create_agent_team_scan(top_level_paths):
    """
    作業の一部を処理するサブエージェントチームを作成
    """
    team_config = {
        "name": "disk-cleaner-team",
        "members": [
            {
                "name": "scanner-1",
                "task": f"{top_level_paths[0]}をプログレッシブモードでスキャン",
                "tool_use": "subprocess"
            },
            {
                "name": "scanner-2",
                "task": f"{top_level_paths[1]}をプログレッシブモードでスキャン",
                "tool_use": "subprocess"
            },
            {
                "name": "scanner-3",
                "task": f"{top_level_paths[2]}をプログレッシブモードでスキャン",
                "tool_use": "subprocess"
            }
        ],
        "coordination": "parallel",  # すべて同時実行
        "aggregation": "merge_results"  # 最後に結果を結合
    }
    
    return launch_agent_team(team_config)

パフォーマンス比較

シナリオ	単一エージェント	3個サブエージェント	高速化率
3ディスク(各1TB)	~15分	~5分	3倍
10ユーザープロファイル	~20分	~4分	5倍
1Mファイル	~30分	~6分	5倍
キャッシュクリーンアップ(26カ所)	~8分	~2分	4倍

推奨エージェント数

• 小さいジョブ (<50Kファイル): 1個エージェント（オーバーヘッドに値しない）
• 中規模ジョブ (50K～500Kファイル): 2～3個エージェント
• 大規模ジョブ (500K～2Mファイル): 3～5個エージェント
• 巨大ジョブ (>2Mファイル): 5～8個エージェント

最適バランス: 3～4個エージェント（速度とオーバーヘッドの最適なバランス）

ベストプラクティス

1. 論理的に作業を分割: ディスク別、ユーザープロファイル別、ディレクトリタイプ別
2. 一貫したパラメータを使用: すべてのエージェントが同じスキャン制限を使用
3. 結果をキャリフルに結合: 重複排除、ソート、フォーマット
4. 障害を優雅に処理: あるエージェントが失敗しても他を継続
5. 進捗を監視: どのエージェントが完了したか追跡

⚠️ 重大: すべてのAI IDEがサブエージェントに対応しているわけではありません。利用不可の場合は並行サブプロセスにフォールバックしてください。

📚 ドキュメント（必須ファイルのみ）

• SKILL.md - この完全ガイド（最初に読んでください）
• README.md - プロジェクト概要とクイックスタート
• README_zh.md - 中国語ドキュメント
• CHANGELOG.md - バージョン履歴と変更点
• AGENT_QUICK_REF.txt - エージェント向け1ページ参照
• INSTALL.md - 詳細なインストールガイド
• NO_PYTHON_GUIDE.md - Pythonなしユーザー向けのヘルプ
• references/temp_locations.md - プラットフォーム固有のキャッシュ位置

---

🎯 エージェント用チェックリスト（従わなければならない）

ディスク分析リクエスト時:

[ ] ステップ1: Pythonの利用可能性をチェック
[ ] ステップ2: スキルパッケージを検出（20以上の場所を自動検出）
[ ] ステップ3: 診断実行: python scripts/check_skill.py
[ ] ステップ4: クイックサンプル実行: --sample（必須 - これを最初に実行）
[ ] ステップ5: 推定に基づいてスキャンモードを選択
[ ] ステップ6: ユーザーに予想時間を通知
[ ] ステップ7: 適切な制限でスキャン実行
[ ] ステップ8: 結果表示と次のステップを提供

クリーニングリクエスト時:

[ ] ステップ1～3: 上記と同じ
[ ] ステップ4: 常に最初に--dry-runを使用（必須）
[ ] ステップ5: プレビュー結果を表示
[ ] ステップ6: --force前にユーザー確認を取得
[ ] ステップ7: 確認されたら実際のクリーニングを実行

---

⚡ プログレッシブスキャン（大型ディスク向けクリティカル）

🚨 重大情報（最初に読んでください）

汎用互換性

• ✅ すべてのAI IDEで動作: Cursor、Windsurf、Continue、Aider、Claude Code等
• ✅ プラットフォーム独立: Windows、macOS、Linux
• ✅ インストール方法に依存しない: グローバル、プロジェクト、ユーザーレベルのどこでも動作
• ✅ 自己完結型: 外部依存なし、Python 3.7以上のみ

唯一の要件

import subprocess
result = subprocess.run(['python', '--version'], capture_output=True, text=True)
# これが成功すれば、このスキルを使用できます

---

⚡ プログレッシブスキャン（大型ディスク向けクリティカル）

🚨 エージェントは大型ディスク(>100GB)で使用する必要があります

問題: 大型ディスク(500GB以上)での完全ディスクスキャンには数時間かかります。ユーザーは忍耐を失います。

解決策: プログレッシブスキャンを使用 - 数時間ではなく数秒で結果を取得！

📋 3つのスキャンモード

モード1: クイックサンプル（⚡ 最速 - 1秒）

使用時期: ディレクトリサイズとスキャン時間を即座に推定

python scripts/analyze_disk.py --sample
# または
python scripts/analyze_progressive.py --sample

出力:

{
  "sample_file_count": 7591,
  "sample_size_gb": 17.62,
  "files_per_second": 7501.0,
  "estimated_time_seconds": 2.0
}

エージェント判定ロジック:

# 未知のディスクサイズについては常にクイックサンプルを実行
result = subprocess.run(
    ['python', 'scripts/analyze_disk.py', '--sample', '--json'],
    capture_output=True,
    text=True,
    timeout=10,
    cwd=skill_path
)

import json
sample = json.loads(result.stdout)
estimated_time = sample.get('estimated_time_seconds', 0)

# 推定に基づいて次のアクションを選択
if estimated_time < 30:
    mode = 'full'  # 完全スキャンで良い
elif estimated_time < 120:
    mode = 'time_limited'  # 時間制限を使用
else:
    mode = 'progressive'  # プログレッシブモードを使用する必要があります

モード2: プログレッシブスキャン（🎯 大型ディスク向け推奨）

使用時期: 大型ディスクの場合30秒で部分的結果を取得

python scripts/analyze_progressive.py --max-seconds 30

機能:

• ✅ 2秒ごとにリアルタイム進捗更新
• ✅ 発見時に部分的結果を表示
• ✅ Ctrl+Cで割り込み可能で結果を保持
• ✅ スマートファイルカウント制限（デフォルト50,000）

エージェント使用:

def analyze_large_disk_safely(path, max_seconds=30):
    """大型ディスクを時間制限で安全に分析"""
    result = subprocess.run(
        ['python', 'scripts/analyze_progressive.py',
         '--max-seconds', str(max_seconds),
         '--path', str(path)],
        capture_output=True,
        text=True,
        timeout=max_seconds + 10,
        cwd=skill_path
    )
    return result.stdout

モード3: 制限付きスキャン（📊 高速結果）

使用時期: ファイル/時間制限で素早く結果を取得

# ファイル数で制限（高速）
python scripts/analyze_disk.py --file-limit 10000

# 時間で制限（安全）
python scripts/analyze_disk.py --time-limit 30

# 両方の制限（非常に高速）
python scripts/analyze_disk.py --file-limit 10000 --time-limit 30

🎯 エージェント判定ツリー（クリティカル - これに従ってください）

ユーザーリクエスト: "ディスクを分析"
    ↓
┌─────────────────────────────────────────┐
│ ステップ1: クイックサンプル（必須）       │
│ python scripts/analyze_disk.py --sample │
└─────────────────────────────────────────┘
    ↓
    サンプルからestimated_timeを取得
    ↓
    ├─ estimated_time < 30秒
    │   ↓
    │   ✅ 完全スキャンを使用
    │   python scripts/analyze_disk.py
    │
    ├─ estimated_time 30～120秒
    │   ↓
    │   ⚠️ 時間制限を使用
    │   python scripts/analyze_disk.py --time-limit 60
    │   ユーザーに通知: "これには約X分かかります"
    │
    └─ estimated_time > 120秒
        ↓
        🚨 プログレッシブモードを使用する必要があります
        python scripts/analyze_progressive.py --max-seconds 30
        ユーザーに通知: "大型ディスク検出 - プログレッシブスキャン使用(30秒)"

📝 必須レスポンステンプレート

クイックサンプルが< 30秒を示す場合

✅ ディスク分析は約2秒かかります
完全スキャンを開始...

クイックサンプルが30～120秒を示す場合

⚠️ ディスク分析は約3分かかります
より高速な結果のため時間制限スキャンを使用...

クイックサンプルが> 120秒を示す場合

🚨 大型ディスク検出! 完全スキャンには約5分かかります
30秒でプログレッシブスキャンモードを使用して迅速に結果を取得...
(部分的結果をすぐに得られます - 後でいつでも完全スキャンできます)

💡 コピー・ペースト用コード（これを使用してください）

import subprocess
import json
from pathlib import Path

def smart_disk_analysis(disk_path, python_cmd='python'):
    """
    スマートディスク分析 - 自動的に最良の方法を選択

    すべてのエージェント向けの推奨方法
    """
    # スキルパッケージを検出
    skill_path = find_skill_package()  # 独自の検出関数を使用
    if not skill_path:
        return False, "スキルパッケージが見つかりません"

    # ステップ1: クイックサンプル(必須 - これを最初に実行!)
    print("🔍 ディスクをクイックサンプル...")
    sample_result = subprocess.run(
        [python_cmd, 'scripts/analyze_disk.py', '--sample',
         '--path', str(disk_path), '--json'],
        capture_output=True,
        text=True,
        timeout=10,
        cwd=str(skill_path)
    )

    if sample_result.returncode != 0:
        return False, "サンプル失敗"

    try:
        sample = json.loads(sample_result.stdout)
        estimated_time = sample.get('estimated_time_seconds', 0)
    except:
        estimated_time = 0

    print(f"   推定スキャン時間: {estimated_time:.0f}秒")

    # ステップ2: 推定に基づいてスキャン方法を選択
    if estimated_time < 30:
        # 小型ディスク - 完全スキャン
        print("✅ 完全スキャンを使用(小型ディスク)")
        result = subprocess.run(
            [python_cmd, 'scripts/analyze_disk.py',
             '--path', str(disk_path)],
            capture_output=True,
            text=True,
            timeout=60,
            cwd=str(skill_path)
        )

    elif estimated_time < 120:
        # 中型ディスク - 時間制限
        minutes = estimated_time / 60
        print(f"⚠️  時間制限スキャンを使用(~{minutes:.1f}分)")
        result = subprocess.run(
            [python_cmd, 'scripts/analyze_disk.py',
             '--path', str(disk_path),
             '--time-limit', '60'],  # 最大1分
            capture_output=True,
            text=True,
            timeout=70,
            cwd=str(skill_path)
        )

    else:
        # 大型ディスク - プログレッシブモード(必須)
        print(f"🚨 大型ディスク検出! プログレッシブスキャンを使用(30秒)")
        result = subprocess.run(
            [python_cmd, 'scripts/analyze_progressive.py',
             '--path', str(disk_path),
             '--max-seconds', '30',
             '--json'],
            capture_output=True,
            text=True,
            timeout=40,
            cwd=str(skill_path)
        )

    if result.returncode != 0:
        return False, result.stderr

    print(result.stdout)
    return True, result.stdout

# 使用法 - この関数を呼び出すだけ:
success, output = smart_disk_analysis("C:\\")
success, output = smart_disk_analysis("/home/user")
success, output = smart_disk_analysis("D:\\Projects")

⚠️ よくある間違いを避ける

❌ しないこと: 常にディスクサイズをチェックせずに完全スキャンを実行 ✅ すること: 常に最初に--sampleを実行して推定

❌ しないこと: ユーザーを大型ディスクスキャンで数時間待たせる ✅ すること: 大型ディスク用に--max-seconds 30を使用

❌ しないこと: サンプルからの推定時間を無視 ✅ すること: 推定を使用して適切なスキャンモードを選択

❌ しないこと: 制限なしで1TBディスク上でanalyze_disk.pyを実行 ✅ すること: analyze_progressive.pyを--max-secondsで使用

📊 コマンド参照カード

状況	コマンド	時間	結果
サイズ不明	--sample	1秒	推定+推奨
< 30秒	analyze_disk.py	<30秒	完全結果
30～120秒	--time-limit 60	60秒	ほとんどの結果
> 120秒	analyze_progressive.py --max-seconds 30	30秒	部分的結果
非常に大型ディスク	analyze_progressive.py --max-seconds 60	60秒	より多くの結果

🔍 プログレッシブスキャンの仕組み

1. クイックサンプル(1秒)

   • 1秒で可能な限り多くのファイルをスキャン
   • スキャンレート(ファイル/秒)を計算
   • 総スキャン時間を推定
   • 即座にフィードバック

2. プログレッシブスキャン(N秒)

   • N秒間連続スキャン
   • 2秒ごとに進捗を表示
   • 進捗に応じて結果を収集
   • 時間/ファイル制限に達したら戻る
   • ユーザーは割り込み可能、部分的結果を保持

3. スマート停止

   • 時間/ファイル制限に達したら自動停止
   • 割り込み処理のグレースフル処理
   • 部分的結果は依然として有用

🎯 エージェント向けベストプラクティス

1. 常に --sampleを実行
2. 常に モード選択前にestimated_timeをチェック
3. 常に ユーザーに予想スキャン時間を通知
4. 常に 大型ディスク用プログレッシブモードを使用(>2分)
5. 決して ユーザーをフィードバックなしで2分以上待たせない

---

---

🎯 汎用エージェントワークフロー

このワークフローはどのプラットフォーム、どのAI IDE、どの場所でも機能します。

ステップ1: Pythonを検証

import subprocess
import sys

def verify_python():
    """Pythonの確認 - プラットフォーム非依存"""
    try:
        # 'python'を最初に試行（Windows、一部Unix）
        result = subprocess.run(
            ['python', '--version'],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode == 0:
            return True, result.stderr.strip() or result.stdout.strip()
    except FileNotFoundError:
        pass

    try:
        # 'python3'を試行（macOS、Linux）
        result = subprocess.run(
            ['python3', '--version'],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode == 0:
            return True, result.stderr.strip() or result.stdout.strip()
    except FileNotFoundError:
        pass

    return False, "Pythonが見つかりません"

# 実行
python_available, version_info = verify_python()
if not python_available:
    print("❌ Python 3.7以上が必要ですが見つかりません")
    print("ダウンロード: https://www.python.org/downloads/")
    print("参照: NO_PYTHON_GUIDE.md プラットフォーム固有の指示について")
    sys.exit(1)

print(f"✅ Pythonが利用可能: {version_info}")

ステップ2: スキルパッケージを特定

from pathlib import Path
import os

def find_skill_package():
    """
    disk-cleanerスキルパッケージを検出 - 場所に依存しない

    優先順に検索:
    1. 現在の作業ディレクトリ
    2. プロジェクトレベル: ./skills/、./.skills/、./agent-skills/
    3. ユーザーレベル: ~/.skills/、~/.agent-skills/、~/skill-packages/
    4. 一般的なAI IDE場所
    5. 親ディレクトリ
    """

    # python コマンドを取得（pythonまたはpython3）
    python_cmd = 'python' if os.name == 'nt' else 'python3'

    # 検索場所 - プラットフォーム＆IDE非依存
    search_locations = []

    # 1. 現在のディレクトリ
    cwd = Path.cwd()
    search_locations.extend([
        cwd / 'disk-cleaner',
        cwd / 'skills' / 'disk-cleaner',
        cwd / '.skills' / 'disk-cleaner',
        cwd / 'agent-skills' / 'disk-cleaner',
        cwd / '.agent-skills' / 'disk-cleaner',
    ])

    # 2. 親ディレクトリ（プロジェクトルート）
    for parent in [cwd, *cwd.parents]:
        search_locations.extend([
            parent / 'skills' / 'disk-cleaner',
            parent / '.skills' / 'disk-cleaner',
            parent / 'agent-skills' / 'disk-cleaner',
        ])
        # 検索深度を制限
        if len(parent.parts) <= 3:
            break

    # 3. ユーザーホームディレクトリ
    home = Path.home()
    search_locations.extend([
        home / 'skills' / 'disk-cleaner',
        home / '.skills' / 'disk-cleaner',
        home / 'agent-skills' / 'disk-cleaner',
        home / '.agent-skills' / 'disk-cleaner',
        home / 'skill-packages' / 'disk-cleaner',
    ])

    # 4. プラットフォーム固有のユーザーディレクトリ
    if os.name == 'nt':  # Windows
        appdata = os.environ.get('APPDATA', '')
        if appdata:
            search_locations.append(Path(appdata) / 'skills' / 'disk-cleaner')
        localappdata = os.environ.get('LOCALAPPDATA', '')
        if localappdata:
            search_locations.append(Path(localappdata) / 'skills' / 'disk-cleaner')
    else:  # Unix系（macOS、Linux）
        search_locations.extend([
            home / '.local' / 'share' / 'skills' / 'disk-cleaner',
            home / '.config' / 'skills' / 'disk-cleaner',
            Path('/usr/local/share/skills/disk-cleaner'),
        ])

    # 5. AI IDE固有ディレクトリ（IDE非依存）
    # 注: これらは例です - 実際の場所はIDE毎に異なります
    ide_specific = [
        # Cursor
        home / '.cursor' / 'skills' / 'disk-cleaner',
        home / '.cursor' / 'user' / 'skills' / 'disk-cleaner',
        # Windsurf
        home / '.windsurf' / 'skills' / 'disk-cleaner',
        # Continue
        home / '.continue' / 'skills' / 'disk-cleaner',
        # 汎用
        home / '.ai-ide' / 'skills' / 'disk-cleaner',
    ]
    search_locations.extend(ide_specific)

    # 6. sys.pathエントリ（Pythonモジュールスタイル）
    for path_entry in sys.path:
        if path_entry and path_entry not in ['', '.']:
            test_path = Path(path_entry) / 'disk-cleaner'
            search_locations.append(test_path)

    # 重複排除と存在しないものを削除
    search_locations = list(set(search_locations))

    # 有効なスキルパッケージを検索
    for location in search_locations:
        if not location:
            continue
        try:
            # キー指標ファイルをチェック
            if (location / 'scripts' / 'analyze_disk.py').exists():
                return location, f"検出: {location}"
            if (location / 'SKILL.md').exists():
                return location, f"検出: {location}"
        except PermissionError:
            continue
        except Exception:
            continue

    # 見つからない - ヘルプメッセージを提供
    print("❌ スキルパッケージが見つかりません")
    print("\n検索場所:")
    for loc in search_locations[:10]:  # 最初の10個を表示
        print(f"  - {loc}")
    print("\n解決策:")
    print("1. 上記のいずれかの場所にスキルパッケージを抽出")
    print("2. または環境変数を設定: DISK_CLEANER_SKILL_PATH")
    print("3. または関数呼び出し時に明示的なパスを指定")
    return None, "見つかりません"

# 実行
skill_path, message = find_skill_package()
if not skill_path:
    print(message)
    sys.exit(1)

print(f"✅ {message}")

ステップ3: スキルパッケージを検証

def verify_skill_package(skill_path, python_cmd='python'):
    """スキルパッケージ整合性を検証 - 場所に依存しない"""
    check_script = skill_path / 'scripts' / 'check_skill.py'

    if not check_script.exists():
        print(f"❌ チェックスクリプトが見つかりません: {check_script}")
        return False

    try:
        result = subprocess.run(
            [python_cmd, str(check_script)],
            capture_output=True,
            text=True,
            timeout=30,
            cwd=str(skill_path)
        )

        # 検証出力を表示
        if result.stdout:
            print(result.stdout)

        if result.returncode == 0:
            print("✅ スキルパッケージの検証に成功")
            return True
        else:
            print("❌ スキルパッケージの検証に失敗")
            if result.stderr:
                print(result.stderr)
            return False

    except subprocess.TimeoutExpired:
        print("❌ 検証がタイムアウト")
        return False
    except Exception as e:
        print(f"❌ 検証エラー: {e}")
        return False

# pythonコマンドを決定
python_cmd = 'python' if os.name == 'nt' else 'python3'

# 実行
if not verify_skill_package(skill_path, python_cmd):
    sys.exit(1)

ステップ4: 操作を実行

def execute_operation(skill_path, operation, python_cmd='python', **kwargs):
    """
    disk cleaner操作を実行 - プラットフォーム＆IDE非依存

    引数:
        skill_path: スキルパッケージへのパス
        operation: 'analyze'、'clean'、'monitor'
        python_cmd: 'python'または'python3'
        **kwargs: 操作固有の引数
    """

    operation_map = {
        'analyze': 'analyze_disk.py',
        'clean': 'clean_disk.py',
        'monitor': 'monitor_disk.py',
    }

    if operation not in operation_map:
        print(f"❌ 不明な操作: {operation}")
        print(f"有効な操作: {list(operation_map.keys())}")
        return False, None

    script = skill_path / 'scripts' / operation_map[operation]
    cmd = [python_cmd, str(script)]

    # 操作固有の引数を追加
    if operation == 'analyze':
        if kwargs.get('path'):
            cmd.extend(['--path', str(kwargs['path'])])
        if kwargs.get('top'):
            cmd.extend(['--top', str(kwargs['top'])])
        if kwargs.get('json'):
            cmd.append('--json')

    elif operation == 'clean':
        # 安全性のためdry-runを常に使用
        if not kwargs.get('force'):
            cmd.append('--dry-run')
        else:
            cmd.append('--force')

        if kwargs.get('temp'):
            cmd.append('--temp')
        if kwargs.get('cache'):
            cmd.append('--cache')
        if kwargs.get('logs'):
            cmd.append('--logs')

    elif operation == 'monitor':
        if kwargs.get('watch'):
            cmd.append('--watch')
        if kwargs.get('json'):
            cmd.append('--json')

    try:
        print(f"🔧 実行: {' '.join(cmd)}")

        result = subprocess.run(
            cmd,
            capture_output=True,
            text=True,
            timeout=kwargs.get('timeout', 300),
            cwd=str(skill_path)
        )

        # 出力を表示
        if result.stdout:
            print(result.stdout)

        if result.returncode != 0:
            if result.stderr:
                print(f"❌ エラー: {result.stderr}")
            return False, None

        return True, result.stdout

    except subprocess.TimeoutExpired:
        print("⚠️ 操作がタイムアウト")
        return False, None
    except Exception as e:
        print(f"❌ 実行エラー: {e}")
        return False, None

# 実行
success, output = execute_operation(
    skill_path,
    operation='analyze',
    python_cmd=python_cmd,
    path='C:\\Users' if os.name == 'nt' else '/home',
    json=True
)

if success:
    print("✅ 操作が正常に完了")

---

📋 クイック参照（すべてのIDE向け）

⚠️ クリティカル: 大型ディスク用プログレッシブスキャンを使用!

ディスク分析の前に:

1. --sampleを実行して推定スキャン時間を取得

2. 2分の推定でプログレッシブモードを使用

3. フィードバックなしでユーザーを2分以上待たせない

クイック参照:

# ステップ1: 常にこれを最初に実行（1秒）
python scripts/analyze_disk.py --sample

# ステップ2: 推定に基づいて選択
# < 30秒: python scripts/analyze_disk.py
# 30～120秒: python scripts/analyze_disk.py --time-limit 60
# > 120秒: python scripts/analyze_progressive.py --max-seconds 30

ユーザーインテント → 操作マッピング

ユーザーが言う	操作	コマンドテンプレート
"ディスク分析"	analyze	python scripts/analyze_disk.py
"ディスク容量をチェック"	analyze	python scripts/analyze_disk.py --top 50
"クイックスキャン"	analyze	python scripts/analyze_disk.py --sample
"大型ディスク分析"	analyze	python scripts/analyze_progressive.py --max-seconds 30
"テンポラリファイルをクリーン"	clean	python scripts/clean_disk.py --temp --dry-run
"クリーンアップをプレビュー"	clean	python scripts/clean_disk.py --dry-run
"ディスクを監視"	monitor	python scripts/monitor_disk.py
"ディスク使用量"	monitor	python scripts/monitor_disk.py --json

プログレッシブスキャン（大型ディスク向け）

問題: 完全ディスクスキャンは大型ディスク(1TB以上)で数時間かかります

解決策: 時間/ファイル制限を使用したプログレッシブスキャン

# クイックサンプル(1秒) - 即座に推定を取得
subprocess.run(['python', 'scripts/analyze_disk.py', '--sample'])

# プログレッシブスキャン(30秒) - すぐに部分的結果を取得
subprocess.run(['python', 'scripts/analyze_progressive.py',
                 '--max-seconds', '30'])

# ファイル数制限(高速)
subprocess.run(['python', 'scripts/analyze_disk.py',
                 '--file-limit', '10000'])

# 時間制限で完全スキャン
subprocess.run(['python', 'scripts/analyze_disk.py',
                 '--time-limit', '120'])

大型ディスク用推奨ワークフロー:

1. 最初に--sampleを実行して推定を取得(1秒)
2. 推定が長すぎる場合、--max-secondsまたは--file-limitを使用
3. またはリアルタイムフィードバック用にanalyze_progressive.pyを使用

クロスプラットフォームPythonコマンド

プラットフォーム	Pythonコマンド	チェックコマンド
Windows	python	python --version
macOS	python3	python3 --version
Linux	python3	python3 --version

汎用コマンドテンプレート

# すべてのプラットフォームで動作
import os
import subprocess

python_cmd = 'python' if os.name == 'nt' else 'python3'
result = subprocess.run([python_cmd, '--version'], capture_output=True, text=True)

---

🌐 マルチIDE互換性

このスキルパッケージは以下をサポートするすべてのAI IDEで動作:

対応するAI IDE

• ✅ Cursor - プロジェクトまたはユーザーレベルスキルとして動作
• ✅ Windsurf - どの場所でも動作
• ✅ Continue - グローバルまたはプロジェクトスキルとして動作
• ✅ Aider - エージェントツールとして動作
• ✅ Claude Code - スキルとして動作
• ✅ その他のAI IDE - サブプロセス経由で動作

IDE毎のインストール方法

プロジェクトレベルのインストール

your-project/
├── skills/
│   └── disk-cleaner/    ← ここに抽出
├── src/
└── README.md

ユーザーレベルのインストール

~/.skills/disk-cleaner/      ← Unix系
~/agent-skills/disk-cleaner/ ← 別パターン
C:\Users\You\skills\disk-cleaner\ ← Windows

グローバルインストール

/usr/local/share/skills/disk-cleaner/  ← Linux(システム全体)
C:\ProgramData\skills\disk-cleaner\   ← Windows(システム全体)

---

🔧 IDE固有の注釈

Cursor

# Cursorは自動的に次の場所でスキルを検索:
# - .cursor/skills/
# - project/skills/
# - ~/.skills/

# 特別な設定は不要

Windsurf

# Windsurfは以下の場所でスキルに対応:
# - .windsurf/skills/
# - project/skills/

# スキルはサブプロセス経由で動作、特別なセットアップなし

Continue

# Continue設定(必要な場合):
# {
#   "skills": ["./skills/disk-cleaner"]
# }
# しかし、ほとんどの場合は自動検出が機能

Aider

# サブプロセス経由のツールとして使用:
# !python skills/disk-cleaner/scripts/analyze_disk.py

汎用/その他IDE

# スキルはインテリジェント自動検出を含む
# 抽出して使用 - 設定不要

---

🎯 完全コピー・ペースト用テンプレート

"""
汎用Disk Cleanerスキル使用
すべてのAI IDE、すべてのプラットフォーム、どの場所でも動作
"""

import subprocess
import sys
import os
from pathlib import Path


def use_disk_cleaner(operation='analyze', **kwargs):
    """
    disk cleanerスキルを使用 - 汎用関数

    以下で動作:
    - すべてのプラットフォーム(Windows、macOS、Linux)
    - すべてのAI IDE(Cursor、Windsurf、Continue等)
    - すべてのインストールレベル(グローバル、プロジェクト、ユーザー)

    引数:
        operation: 'analyze'、'clean'、'monitor'
        **kwargs: 操作固有の引数

    戻り値:
        (success: bool, output: str)
    """

    # 1. pythonコマンドを決定
    python_cmd = 'python' if os.name == 'nt' else 'python3'

    # 2. Pythonを検証
    try:
        result = subprocess.run(
            [python_cmd, '--version'],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode != 0:
            print("❌ Pythonが見つかりません")
            return False, "Python 3.7以上が必要"
    except Exception as e:
        print(f"❌ Pythonチェック失敗: {e}")
        return False, str(e)

    # 3. スキルパッケージを検出（インテリジェント検索）
    def find_skill():
        search_paths = [
            # 現在のディレクトリ
            Path.cwd() / 'disk-cleaner',
            Path.cwd() / 'skills' / 'disk-cleaner',
            Path.cwd() / '.skills' / 'disk-cleaner',
            # プロジェクトルート
            *[(p / 'skills' / 'disk-cleaner') for p in [Path.cwd(), *Path.cwd().parents][:3]],
            # ユーザーホーム
            Path.home() / 'skills' / 'disk-cleaner',
            Path.home() / '.skills' / 'disk-cleaner',
        ]

        for path in search_paths:
            if (path / 'scripts' / 'analyze_disk.py').exists():
                return path
        return None

    skill_path = find_skill()
    if not skill_path:
        print("❌ スキルパッケージが見つかりません")
        print("抽出先: skills/disk-cleaner/ または ~/.skills/disk-cleaner/")
        return False, "スキルパッケージが見つかりません"

    # 4. 操作を実行
    scripts = {
        'analyze': 'analyze_disk.py',
        'clean': 'clean_disk.py',
        'monitor': 'monitor_disk.py',
    }

    if operation not in scripts:
        return False, f"不明な操作: {operation}"

    script = skill_path / 'scripts' / scripts[operation]
    cmd = [python_cmd, str(script)]

    # 引数を追加
    if operation == 'analyze':
        if kwargs.get('path'):
            cmd.extend(['--path', str(kwargs['path'])])
    elif operation == 'clean':
        cmd.append('--dry-run')  # 常に安全
    elif operation == 'monitor':
        if kwargs.get('json'):
            cmd.append('--json')

    # 実行
    try:
        result = subprocess.run(
            cmd,