smart-folder-organizer

スマートフォルダー整理ツール

このスキルでは、データの安全性を確保しながら、整理されていないディレクトリを片付けるための体系的なワークフローを提供します。

基本方針

1. 安全第一：ファイルは絶対に削除しないでください。削除対象のファイルは、to_remove/ 内の専用サブフォルダー（例：to_remove/duplicates/ や to_remove/empty_folders/）に移動します。
2. 厳密な範囲指定：現在のディレクトリとそのサブディレクトリ内でのみ操作してください。親ディレクトリ（..）にあるファイルを移動したり、アクセスしたりしないでください。
3. ファイルの保護：ファイルの分類が曖昧な場合は、誤って推測するのではなく、Needs_Review/ フォルダーに移動してください。
4. 大容量ファイル：20MB を超えるファイルは、メモリの問題を防ぐため、PDF テキストの読み取りなどの詳細な内容分析を行わないでください。分析していない大容量ファイルは、専用の Needs_Review/LargeFiles/ ディレクトリに移動してください。
5. フォルダーの取り扱い：現在のディレクトリとそのサブディレクトリ内のファイルをすべて再帰的に処理してください。ファイルを移動する際は、分類先フォルダーを対象ディレクトリのルートに配置してください（各サブフォルダー内に分類先のフォルダー構造を複製しないでください）。見つかった空のサブディレクトリや、処理後に残った空のサブディレクトリは、すべて to_remove/empty_folders/ に移動してください。

ワークフロー

1. スマートフォルダーの検出

個々のファイルを処理する前に、scripts/detect_smart_folders.py <target_dir> を実行して、すでに適切に整理されているサブディレクトリ（Git リポジトリ、ソフトウェアプロジェクト、macOS アプリバンドルなど）を特定します。

• アクション：検出されたフォルダーは、それぞれ全体を Others/ に移動してください。中に入ったり、内容を再整理したりしないでください。
• 判定方法：このスクリプトは、プロジェクトの目印（.git/、package.json、Cargo.toml、Makefile など）やアプリバンドル（.app）を確認し、理由とともに一致した項目を JSON リストとして返します。
• 除外：以降のすべての手順では、Others/ ディレクトリを対象外にしてください。

2. 重複ファイルの検出

find_duplicates.py スクリプトを実行して、同一のファイルを特定します。

• アクション：特定された重複ファイルを to_remove/duplicates/ に移動してください。
• 判定方法：決定的な結果を得るため、scripts/find_duplicates.py スクリプトを使ってファイルのハッシュ（SHA256）を確認してください。

3. 一般的な分類

拡張子と一般的なパターンに基づいてファイルを整理します。

• 写真：Photos/ に移動します。（スクリーンショットは Photos/Screenshots/ に移動します。）
• 動画：Videos/ に移動します。
• インストーラー：Installers/ に移動します（.dmg、.pkg、.exe、.msi）。
• アーカイブ：Archives/ に移動します（.zip、.rar など）。

4. PDF の詳細分析

PDF ファイルは最初の数ページを読み、文書の種類を判断して、名前変更に必要なメタデータを抽出します。

• 重要：PDF を読み取るための動的な Python スクリプトを生成しないでください。代わりに、このスキルに用意されている scripts/extract_pdf_metadata.py スクリプトを実行し、テキストを抽出して文書を決定的に分析してください。このスクリプトは pypdf を使用し、最初の 3 ページと最終ページをサンプリングすることで、高速かつ効率的に分類します。
• 重要：文書の分類には普遍的な意味理解による推論を使用してください。最新の AI モデルは英語、中国語、スペイン語など、数十の言語を理解できます。特定の英語キーワード（「Invoice」など）よりも、文書の意図（例：「支払いを請求している」）を優先してください。意味に基づく分類のガイドラインについては、references/classification.md を参照してください。
• 多言語での命名：英語以外の文書では、命名に必要な情報（[Vendor] や [Provider] など）を、元の文字体系（例：中国語の文字）のまま抽出してください。標準の日付形式 yyyy-mm-dd は変更しません。
• 請求書：名前を yyyy-mm-dd-[Vendor]-[Inv#-][Amount].pdf に変更し、Documents/Invoices/ に移動します。
• 料金明細：名前を yyyy-mm-dd-[Provider]-[Service]-[Account#].pdf に変更し、Documents/Bills/ に移動します。
• 領収書：名前を yyyy-mm-dd-[Store]-[TotalAmount].pdf に変更し、Documents/Receipts/ に移動します。
• 旅行：名前を yyyy-mm-dd-[Transport/Hotel]-[Confirmation#].pdf に変更し、Documents/Travel/ に移動します。

5. 最終整理

• 文書ファイル（.docx、.doc、.pages、.odt）を Documents/Writing/ にまとめます。
• スプレッドシートファイル（.xlsx、.xls、.numbers、.ods、.csv）を Documents/Spreadsheets/ にまとめます。
• プレゼンテーションファイル（.ppt、.pptx、.key、.odp）を Documents/Presentations/ にまとめます。
• 音声ファイル（.mp3、.wav、.flac、.m4a）を Audio/ にまとめます。
• 残りの文書は、該当する場合はサブタイプごとに Needs_Review/Documents/ にまとめます。
• PDF 文書を分析したもののカテゴリが不明な場合は、Needs_Review/Unknown/ に移動します。
• その他の未処理ファイルは Needs_Review/ に移動します。

リソース

scripts/find_duplicates.py

同一ファイルを決定的に検出する Python スクリプトです。ファイル名やサイズに頼るのではなく、SHA-256 ハッシュを使ってファイルの内容を比較し、重複ファイルの JSON リストを返します。

scripts/extract_pdf_metadata.py

pypdf ライブラリを使用して PDF からテキストを抽出する Python ヘルパースクリプトです。独自のスクリプトを作成する代わりに、こちらを使用してください。サンプリング方式（最初の 3 ページと最後のページ）を使って文書分類に必要なテキストを効率的に抽出し、テキストを JSON ラッパーに格納して返します。

scripts/detect_smart_folders.py

対象フォルダーの直下にあるサブディレクトリをスキャンし、プロジェクトのマーカー（.git/、package.json、Cargo.toml、Makefile など）やアプリバンドル（.app）を検出する Python スクリプトです。分解せずに Others/ へ移動する必要がある「スマート」フォルダーの JSON リストを返します。

references/classification.md

PDF やその他の文書タイプに関する詳細なキーワードリストと命名規則が記載されています。