smart-file-organizer

スマートファイル整理ツール

ファイルの実際の内容を読み取って、壊れたファイル名を復元し、一からわかりやすい名前を付け、必要に応じてファイルをカテゴリ別のフォルダーに整理します。安全に元に戻せるよう、ロールバック用のマップも作成します。

対象ディレクトリ内のファイル（すべてのサブディレクトリを含む）の内容を分析して、内容に沿った名前に変更し、必要に応じて論理的なフォルダー構成に整理します。

モード

• rename-only（デフォルト）：内容分析に基づいて、ファイルの名前をその場で変更します。
• full-organize：ファイル名を変更し、カテゴリ別のフォルダー構成に整理します（フォルダーの作成、名前の変更、統合）。
• collect：ディレクトリを横断してファイルをスキャンし、ユーザーが指定した目的に合致するファイルを1つの出力フォルダーにコピーします。元のファイルの名前は変更せず、移動もしません。

手順

ステップ 1：パラメーターの収集

ユーザーに次の情報を確認します。

1. 対象ディレクトリ — スキャン対象の絶対パス（必須）。
2. モード — rename-only、full-organize、collect のいずれか（デフォルト：rename-only）。
   • collect の場合は、収集クエリも確認します — 収集するファイルの種類（例：「履歴書関連ファイル」、「データセットファイル」、「不要ファイル」）。
3. 使用可能な言語 — ファイル名に使用する言語（デフォルト：元の言語に合わせるか、英語）。

   Which languages should be used in file names?
     Allowed: (e.g., Korean, English)
     Others:  auto-translate to an allowed language (e.g., Japanese → English)
   

   • ファイルの内容が使用可能な言語以外で書かれている場合は、生成した名前をユーザーが希望する使用可能な言語に翻訳します。
   • 略語や固有名詞は翻訳対象外です（IITP、YOLOv8 など）。
4. ファイルフィルター — 対象に含める、または除外する特定の拡張子（デフォルト：すべてのファイル）。
5. 最大深度 — サブディレクトリを再帰的にたどる深さ（デフォルト：無制限）。
6. 名前変更の厳格さ — ファイル名をどの程度積極的に変更するか（デフォルト：recovery）。

   How strictly should files be renamed?
     [R] Recovery  — only fix broken/meaningless names, keep already-descriptive names as-is
     [U] Uniform   — rename ALL files to a standardized format based on content
   

   • recovery：現在の名前が内容を妥当に表しているファイルは、命名規則に完全には沿っていなくてもスキップします。
   • uniform：元の名前はすべて信頼できないものとして扱い、一から名前を生成します — 現在の動作です。

ユーザーが他のオプションを指定せずにディレクトリを指定した場合は、デフォルトを使用して処理を進めます。

ステップ 2：スキャンと一覧の作成

1. 対象ディレクトリ内のすべてのファイルを再帰的に一覧表示します。
2. 隠しファイルと隠しディレクトリ（. で始まるもの）と、一般的な除外パターン（node_modules、.git、__pycache__ など）をスキップします。
3. ソースコードファイルはデフォルトでスキップします — 名前を変更すると、インポートパス、include ディレクティブ、ビルドシステムに支障が出るためです。対象外の拡張子：.py、.cpp、.c、.h、.hpp、.js、.ts、.jsx、.tsx、.java、.go、.rs、.rb、.cs、.swift、.kt、.scala、.sh、.bat、.ps1、および CI/CD 設定ファイル（Jenkinsfile*、Makefile、Dockerfile、*.cmake）。ユーザーは明示的な --include-code フラグまたはリクエストによって、この設定を上書きできます。
4. 実行ファイル／インストーラーファイルはスキップします — .exe、.msi、.appimage、.dmg ファイルは元の名前のまま維持します。
5. データセットの可能性があるディレクトリを検出します — 処理を始める前に、大量のデータセットが含まれている可能性のあるディレクトリを特定します。次のいずれかに該当する場合、そのディレクトリはデータセットの可能性があると判断します。
   • 同じ拡張子のファイルが 100個以上含まれている。
   • 連番またはハッシュベースの命名パターンに従っている（例：img_0001.jpg…img_9999.jpg、a3f8c2.png）。
   • 一般的なデータセット名のパターンに一致する（大文字と小文字を区別しない）：train、val、valid、validation、test、dataset、datasets、images、labels、annotations、samples、corpus、raw、processed。
   • 大量のデータとともにアノテーション／マニフェストファイルが含まれている（例：アノテーション用の *.json／*.csv と画像またはテキストファイルが50個以上）。 疑わしいディレクトリごとに、判断する前にユーザーに確認します。

   ⚠ The following directories are suspected to be datasets:
     📁 train/       — 1,523 .jpg files, sequential naming pattern
     📁 annotations/ — 1,523 .json files + manifest.csv
   
   For each directory, choose:
     [S] Skip  — treat as dataset, do not rename
     [I] Include — treat as normal folder, process files
   

   • ユーザーがデータセットディレクトリだと確認したものは完全に除外し、「データセットディレクトリ（ユーザー確認済み）」として記録します。
   • ユーザーがデータセットディレクトリではないと確認したものは、通常の処理に進みます。
6. 次の項目を含むインベントリを作成します：現在のパス、ファイルサイズ、拡張子、最終更新日。
7. ディレクトリ名をスキャンします — 文字化けや意味のない名前（New Folder、Untitled、1、2、3のような数字のみの名前）が付いたディレクトリを特定します。これらもファイルとともに名前変更マップに含めます。ディレクトリ名の変更はすべてのモード（rename-onlyを含む）で行い、パスが無効になるのを防ぐため、すべてのファイル名を変更した後に実行します。
   • ファイル名／ディレクトリ名の文字コードを復元 — 文字化けしたバイト列を含む名前は、生のバイト列に対してEUC-KR、CP949、Shift_JIS、GB2312、Latin-1を順に試してデコードします。読み取り可能な名前を復元できた場合は、それを名前変更の基準として使用します。
8. インベントリの概要をユーザーに報告します。
   • ファイルの合計数
   • 拡張子ごとの内訳
   • 合計サイズ

ファイルが100個を超える場合は、続行する前にユーザーに確認するか、フィルターを使って対象を絞り込むよう提案します。

バッチ処理 — コンテキストのオーバーフローやツール呼び出しの失敗を避けるため：

• バッチの最大サイズ：1バッチあたり50ファイル。
• ファイルの合計数が50を超える場合、インベントリを最大50ファイルのバッチに分割します。
• 各バッチを独立したサブエージェントとして処理します（サブエージェントを利用できない場合は順次バッチ処理を行います）。
  1. 各バッチは専用のファイルリストを受け取り、ステップ3～4を個別に実行します。
  2. すべてのバッチ結果を統合し、ユーザーに提示する前に単一の名前変更マップを作成します。
• サブエージェントのバッチは並列実行できます（同時実行は最大4バッチ）。
• サブエージェントの自動承認 — サブエージェントは、ユーザーの確認を必要とせず、ファイルの読み取りと分析をすべて実行する必要があります。各バッチ内のツール呼び出しを自動で進めるため、サブエージェントを呼び出す際には--auto-approveまたは同等のフラグを渡します。
• 各バッチは、部分的な名前変更マップをJSON形式で返し、統合できるようにします。
• バッチ統合時の重複排除 — すべてのバッチ結果を統合した後、名前の衝突候補をスキャンします。
  1. 提案された名前ごと（大文字小文字を区別しない）に項目をグループ化します。
  2. 衝突ごとに、識別用の属性（日付、親フォルダー名、または連番）を追加して区別します。
  3. 解決した衝突をドライランの出力に記録し、ユーザーが確認できるようにします。
• 完了確認 — すべてのバッチが返された後、インベントリ内のすべてのファイルが、名前変更済み、理由付きでスキップ済み、または_unknown/への移動済みのいずれかとして処理されていることを確認します。バッチ結果に含まれないファイルがあれば、補足バッチに再登録します。最終的な名前変更マップは、インベントリ内のファイルを100％網羅しなければなりません。

ステップ3：ファイルの内容を分析する

動作はステップ1の名前変更の厳格度設定によって異なります。

uniform モードの場合：

⚠ 重要：コード以外のファイルはすべて、実際の内容に基づいた標準形式の名前に変更する必要があります。例外はありません。

• 元のファイル名は信頼できません。ランダムな文字列だとみなしてください。
• まずファイルの内容を読み取って分析し、その後、名前を一から作成する必要があります。
• 一部が説明的でも標準形式ではない名前のファイル（例：073_disaster_safety_XR.hwpx、report_v2_final.docx）も、内容を読んだ後に名前を変更する必要があります。
• 元の名前を維持できるのは、命名規則に完全に一致し、かつ具体的な内容を正確に表している場合のみです。

名前変更の基準（uniform） — 以下のいずれかに該当するファイルは、名前を変更する必要があります。

• 意味のない接頭辞、通し番号、コードが含まれている（073_、IMG_、DSC_、001_、(3)）。
• 名前が曖昧、省略されている、または文書の具体的な主題を表していない。
• references/naming-conventions.md に記載されている [YYMMDD_]<attr1>_<attr2>[_...<attrN>].<ext> 形式に従っていない。
• 使用が許可されていない言語の文字が含まれている（Step 1 の言語設定に準拠）。
• 具体的な文脈がないまま、汎用的な単語（document、file、untitled、report）が含まれている。

recovery モードの場合（デフォルト）：

明らかに壊れている名前、または意味のない名前のファイルのみ名前を変更します。現在の名前からファイルの内容がある程度わかる場合は、そのまま維持してください。命名規則に完全には従っていなくても構いません。

事前フィルター（内容を読む前） — 大量のファイルを不必要に読み取らないよう、まず簡易的な名前の品質判定を行います。

1. ファイル名の拡張子を除いた部分を取り出します。
2. 2 語以上の意味のある単語（コードや数字ではないもの）が含まれており、除外対象のパターンがない場合は、内容の読み取りをスキップし、「維持」とします。
3. 以下のいずれかに該当する場合のみ、内容を読み取ります。
   • ファイル名の拡張子を除いた部分が、すべて非アルファベット文字で構成されている（ハッシュ、UUID、数字の並び）。
   • 自動生成されたパターンに一致する：IMG_\d+、DSC\d+、Screen Shot、document\(\d+\)、Untitled、New File。
   • 数字と句読点を除いた後の、アルファベットで構成される要素が 2 個未満。
   • 使用が許可されていない言語の文字が含まれている（Step 1 に準拠）。

この事前フィルターにより、ほとんどのファイル名がすでに適切な大規模ディレクトリでは、内容を読む量を大幅に減らせます。

名前変更の基準（recovery） — 以下のいずれかに該当する場合のみ、ファイルの名前を変更します。

• 名前がまったく意味をなさない（例：IMG_20240315_142356.jpg、document(3).pdf、a3f8c2.png）。
• 名前の大部分が、説明的な単語を伴わないコード、ハッシュ、連番で構成されている。
• 名前が汎用的な単語 1 語のみである（untitled、file、new、temp）。
• 使用が許可されていない言語の文字が含まれている（Step 1 の言語設定に準拠）。

一部が説明的な名前（例：quarterly_report.pdf、meeting_notes_march.txt）のファイルは、recovery モードではそのまま維持します。

各ファイルの内容を読み取り、説明的な名前を決定します。

テキストベースのファイル

拡張子：.txt、.md、.json、.csv、.html、.xml、.log、.yaml、.yml、.ini、.cfg、.conf、.toml など。

• ファイルの**先頭 10%**を読み取ります（行数またはバイト数に基づく）。最小：5 行。最大：200 行または 4 KB のいずれか早い方。
• 実際のテキスト内容から、主なトピック、目的、または主題を特定します。
• 提案する名前には、ファイル形式ではなく、テキストの内容を反映させる必要があります。

エンコーディングの検出

ファイルの内容が文字化けしている、または読み取れない場合：

1. 一般的なエンコーディングを次の順に試します：utf-8 → cp949（韓国語） → shift_jis（日本語） → gb2312（中国語） → euc-kr → latin-1。
2. 利用できる場合は、file コマンドまたは chardet に類するヒューリスティックを使用してエンコーディングを検出します。
3. 読み取り可能なテキストを取得したら、内容の分析に進みます。
4. どのエンコーディングでも読み取り可能にならない場合は、ファイルに読み取り不可の印を付けます。

ドキュメント

拡張子：.pdf、.docx、.xlsx、.pptx、.hwp、.hwpx

• **ページの最初の10％**からテキストを抽出します（最低：1ページ、抽出テキストの最大サイズ：8 KB）。
• 抽出したテキストを読み、ドキュメントの主題、タイトル、または目的を特定します。
• **.hwpx**ファイルは XML を含む ZIP アーカイブです。解凍して Contents/section*.xml を解析し、本文テキストを抽出します。
• **.hwp**ファイルには、利用可能であれば hwp5txt または pyhwp を使用します。利用できない場合は、韓国語エンコーディングを指定して strings コマンドを試します。
• テキストの抽出に失敗した場合は、メタデータ（タイトル、作成者、主題）を代替手段として使用します。
• 最後の手段として既存の名前を使用し、⚠ content unreadable — name based on metadata/original を付けて、ユーザーによる確認を促します。

画像

拡張子：.jpg、.png、.gif、.webp、.svg、.jfif

• 利用可能であれば、EXIF データまたは埋め込みメタデータを確認します。
• エージェントが画像認識機能を備えている場合は、画像の内容を直接分析し、描写されているものに基づいて名前を付けます。
• それ以外の場合は、次の順序で文脈からの推測を試みます。
  1. 同じディレクトリ内のファイル — 同じディレクトリにある他のファイルを確認し、トピックやプロジェクトの手掛かりを探します。
  2. タイムスタンプ — 近くのファイルと作成日時・変更日時を比較し、時間的なまとまりを見つけます。
  3. ファイル名の断片 — 元の名前から意味のある部分（日付、連番、アプリ名）を抽出します。
  4. 親ディレクトリ名 — フォルダー名をカテゴリのヒントとして使用します。
• 上記のいずれからも確信を持てる名前が得られない場合は、_unknown/ に移動します。

バイナリ／不明なファイル

• ファイルのメタデータと拡張子のみを使用します。
• バイナリの内容を読み取ろうとしないでください。

読み取り不能なファイル

破損、暗号化、未対応形式、またはあらゆるエンコーディングの試行に失敗したなど、分析できないファイル：

• 元のファイル名を保持したまま、<target-dir>/_unknown/ に移動します。
• 失敗の理由（例：「エンコーディングの検出に失敗」「メタデータのないバイナリ」）を記録します。
• ユーザーが判断を変更できるよう、ドライランのプレビューに含めます。

言語の取り扱い

ステップ1で設定した許可言語を適用します。

• ファイルの内容の言語を検出します。
• 内容の言語が許可リストにない場合は、提案する名前をユーザーが希望する許可言語に翻訳します。
• 頭字語と固有名詞は翻訳せずに保持します。

命名規則

詳細なパターンについては、references/naming-conventions.md を参照してください。主なルール：

• 属性間の区切りには _ を、複数語の属性内の区切りには - を使用します。
• 名前は簡潔にします：属性は最大3～6個です。
• 元のファイル拡張子を保持します。
• ファイルに明確な関連日付がある場合は、日付の接頭辞（YYMMDD_）を含めます。
• document、file、untitled などの一般的な名前は避けます。
• 必ず内容の分析に基づいて新しい名前を生成してください。元のファイル名は決してコピーしないでください。元の名前に関連する単語が含まれていても、命名規則に従って一から名前を組み立て直します。

ステップ 4：名前変更マップの生成（ドライラン）

JSON 形式で名前変更マップを作成します。ファイルの合計数が 30 を超える場合は、概要を先に提示してください：

📊 Rename Summary
  Rename:  142 files
  Keep:    358 files (name already descriptive)
  Unknown:   5 files → _unknown/

  By extension: .pdf (42) · .hwpx (31) · .jpg (28) · .docx (22) · .txt (19)

  [Show full list]  [Show by folder]  [Show renames only]

ユーザーが詳細を求めた場合（またはファイルの合計数が 30 以下の場合）は、名前変更マップ全体を表示します：

Current Name                    → Proposed Name
────────────────────────────────────────────────
IMG_20240315_142356.jpg         → 240315_sunset_beach-photo.jpg
document(3).pdf                 → 240901_quarterly_sales-report_Q3.pdf
073_disaster_safety_XR.hwpx     → 250530_IITP_disaster-safety_XR-augmentation_proposal.hwpx
notes.txt                       → meeting-notes_product-roadmap.txt

⚠ Unreadable (→ _unknown/):
corrupted-data.bin              → _unknown/corrupted-data.bin (reason: binary, no metadata)

承認を得るまで繰り返す承認ループ — ユーザーが明示的に承認するまで繰り返します：

1. 名前変更マップ全体を提示します。
2. ユーザーは次の操作を行えます：
   • すべて承認 — ステップ 5 に進みます。
   • 変更を依頼 — 例：「韓国語の名前にする」「名前を短くする」「写真だけ日付の接頭辞を残す」「ファイル X を _unknown に移動しない」。
   • 特定の項目を編集 — 個別に提案された名前を変更します。
   • ファイルを除外 — 特定のファイルをスキップします。
   • キャンセル — 操作を中止します。
3. ユーザーが変更を依頼した場合は、該当する項目を修正し、更新したマップを再度提示します。
4. このループのステップ 1 に戻ります。

ユーザーが明示的に承認するまで、実行に進まないでください。

実行前のロールバックマップ — ユーザーの承認後、ファイル操作を行う前に、予定されているロールバックマップをただちに保存します：

bash <skill-path>/scripts/rename-map.sh save <target-dir>

これにより <target-dir>/.file-organizer-map.json が作成され、実行が途中で中断された場合でも、ユーザーは完了済みの操作をロールバックできます。

ステップ 5：名前変更の実行

ロールバックマップを保存した後：

1. ファイルの名前を 1 つずつ変更します。
2. 進捗報告 — 大規模なバッチ（50 ファイル以上）では、25 ファイルごとに進捗を報告します：

   ✅ 25/142 renamed... (17%)
   ✅ 50/142 renamed... (35%)
   

3. エラー（名前の競合、権限の問題など）があれば報告します。
4. 名前が競合した場合は、数値の接尾辞を追加します：report_Q3_2.pdf。
5. ロールバックマップを整合させる — すべての名前変更が完了したら、実際のファイルシステムの状態とマップを照合し、実行されなかった操作の項目を削除します：

   bash <skill-path>/scripts/rename-map.sh reconcile <target-dir>
   

   これにより、ロールバックマップには実際に行われた操作だけが含まれるようになります。
6. 実行完了チェック — 整合済みのマップとスキップリストを元のインベントリと比較します。名前変更も明示的なスキップもされていないファイルがあれば、エラーとして報告し、再試行します。

ステップ 6：再編成（full-organize モードのみ）

ユーザーが full-organize を選択した場合は、名前変更後に次の操作を行います：

1. 既存のフォルダー構成と、ファイル内容のカテゴリを分析します。

2. 新しいフォルダー構成を提案します。次の操作を含めることができます：

   • まだ存在しないカテゴリの新しいフォルダーの作成。
   • 既存のフォルダーを、より説明的な名前に変更すること（例：misc/ → reports/、New Folder/ → presentations/）。
   • 類似した内容を含むフォルダーの統合。
   • ファイルを移動した後の空のフォルダーの削除。

   提案の例：

   📁 Folder changes:
     [NEW]    documents/reports/
     [NEW]    images/screenshots/
     [RENAME] misc/ → data/csv/
     [RENAME] New Folder/ → presentations/
     [DELETE] old-stuff/ (empty after move)
   
   📁 Proposed structure:
   <target-dir>/
   ├── documents/
   │   ├── reports/
   │   └── notes/
   ├── images/
   │   ├── photos/
   │   └── screenshots/
   ├── data/
   │   ├── csv/
   │   └── json/
   └── other/
   

3. フォルダー名にはファイル名と同じ規則を適用し（references/naming-conventions.md を参照）、内容がわかる名前を使用します。

4. 提案するフォルダーの変更とファイルの移動をユーザーに提示し、承認を求めます。

5. 承認後、まずフォルダー操作（作成／名前変更）を実行し、次にファイルを移動してから、空のディレクトリを削除します。

6. フォルダーの名前変更／移動操作はすべて、元に戻せるようにロールバックマップに記録します。

ステップ 6b：収集（collect モードのみ）

ユーザーが collect を選択した場合は、ステップ 3〜6 をスキップし、代わりに次の手順に従います：

1. ステップ 1 の収集クエリを検索条件として使用します。
2. インベントリ内の各ファイルについて、次の情報に基づいて関連性を判断します：
   • ファイル名とパスに含まれるキーワード。
   • 内容のサンプリング（テキストは先頭 4 KB、ドキュメントは 8 KB）— ステップ 3 と同じ上限です。
   • メタデータ（拡張子、親フォルダー名、日付）。
3. 各ファイルの関連度をスコア化し、信頼度を含む収集リストを作成します：

   📋 Collect: "resume-related files" → _collected/resume_related/
     ✅ High (12 files):
       documents/resume_john-doe.pdf
       career/portfolio_2025.pptx
       ...
     🔶 Medium (5 files):
       misc/cover-letter_draft.docx
       ...
     ❌ Excluded (283 files): not relevant
   

4. 収集リストを提示し、承認するか、しきい値を調整するか、特定のファイルを除外するかをユーザーに尋ねます。
5. 承認後、一致したファイルを <target-dir>/_collected/<query-slug>/ にコピーします（移動はしません）。
6. 元のディレクトリ構造を維持したフラットコピーとして保存します（名前が競合する場合は、親フォルダー名を先頭に付けます）。
7. 収集内容を .file-organizer-changelog.md に記録します。

ステップ 7：サマリーレポート

サマリーを出力します：

• 名前を変更したファイル：件数
• 移動したファイル：件数（full-organize の場合）
• 収集したファイル：件数と移動先（collect の場合）
• スキップしたファイル：件数と理由
• ロールバックコマンド：bash <skill-path>/scripts/rename-map.sh rollback <target-dir>

変更ログを保存する — <target-dir>/.file-organizer-changelog.md に Markdown ファイルを書き込みます。内容は以下のとおりです：

# File Organizer Change Log

- **Date**: YYYY-MM-DD HH:MM
- **Mode**: rename-only | full-organize | collect
- **Target**: <target-dir>

## Changes (N files)

| # | Before | After |
|---|--------|-------|
| 1 | `old-name.pdf` | `new-name.pdf` |
| ... | ... | ... |

## Skipped (M files)

| # | File | Reason |
|---|------|--------|
| 1 | `some-file.py` | Source code (excluded) |
| 2 | `train/` (1523 files) | Dataset directory (user confirmed) |
| ... | ... | ... |

## Moved to _unknown/ (K files)

| # | File | Reason |
|---|------|--------|
| 1 | `hash-image.webp` | Unreadable content |
| ... | ... | ... |

このファイルは実行のたびに上書きされます（以前のログは保持されません）。

ロールバック

ロールバックマップ（.file-organizer-map.json）には、取り消しのために、名前の変更や移動の操作がすべて記録されます。ユーザーは次のコマンドで管理できます：

# Save current rename map (done automatically before execution)
bash <skill-path>/scripts/rename-map.sh save <target-dir>

# Show the current rollback map contents
bash <skill-path>/scripts/rename-map.sh show <target-dir>

# Undo all renames/moves recorded in the map
bash <skill-path>/scripts/rename-map.sh rollback <target-dir>

# Reconcile map after execution (remove entries for operations that didn't happen)
bash <skill-path>/scripts/rename-map.sh reconcile <target-dir>

# Clear the rollback map (after confirming changes are correct)
bash <skill-path>/scripts/rename-map.sh clear <target-dir>

ユーザーはエージェントに「直前のファイル整理をロールバックして」「名前を変更したファイルを見せて」「ロールバック履歴を消去して」と直接依頼することもできます。

安全ルール

• 既存ファイルを上書きすることは絶対に避け、必ず事前に競合を確認してください。
• ユーザーの明示的な承認なしに、rm -rf や再帰的な削除コマンドを実行してはいけません。サブエージェント内でも同様です。空のディレクトリの削除（rmdir）は、ディレクトリが空であることを確認した場合に限り許可されます。
• 変更を加える前に、必ずロールバックマップを保存してください。
• 実行前に、必ずドライランのプレビューを表示し、ユーザーの明示的な承認を得てください。
• 現在開いているファイル、またはロックされているファイルはスキップしてください。
• 名前の変更や移動の際は、ファイルのアクセス権とタイムスタンプを保持してください。