file-network

バラバラなファイルを日付別・種別別・カテゴリ別など複数の視点でエクスプローラーから探せるように整理するCLIツール。

ファイルの実体は1箇所（canonical/）にだけ置き、それ以外の場所にはWindowsショートカット（.lnk）を作成することで、ファイルをコピーせずにネットワーク状のフォルダ構造を再現します。

---

どう変わるか

整理前

inbox/
  invoice_001.pdf
  meeting_notes_20260401.txt
  train_model.py

整理後

organized/
  canonical/                          ← 実体はここだけ
    documents/  invoice_001.pdf
    docs/       meeting_notes_20260401.txt
    code/       train_model.py

  views/
    by_date/
      2026-04/
        invoice_001.pdf.lnk           ┐
        meeting_notes_20260401.txt.lnk ├─ canonical を指すショートカット
        train_model.py.lnk            ┘
    by_category/
      finance/    invoice_001.pdf.lnk
      docs/       meeting_notes_20260401.txt.lnk
      code/       train_model.py.lnk
    by_type/
      pdf/        invoice_001.pdf.lnk
      text/       meeting_notes_20260401.txt.lnk
      python/     train_model.py.lnk

  .file-network/
    log.json                          ← 操作履歴（undo用）

エクスプローラーで views/by_date/ を開けば日付順に、views/by_category/ を開けばカテゴリ順にファイルを参照できます。ショートカットを開くと実体ファイルが開きます。

---

特徴

• ファイルを増やさない — 実体は1つ、参照だけを増やす
• 既存アプリがそのまま使える — エクスプローラーや任意のファイラーで動作
• 分類コストを最小化 — 日付・種別はルールで自動処理、意味的な分類のみLLMが担当
• 中身を読んで分類 — PDF・Word・Excelのテキストを読み取り、ファイル名だけに頼らない
• やり直せる — 整理後に元の状態へ一発で戻せる
• 壊れても直せる — ファイルを手動移動してショートカットが切れた場合も自動修復

---

必要環境

• Python 3.11+
• Windows（.lnkファイル生成のため）
• OpenAI APIキー（カテゴリ・プロジェクト分類を使う場合）

---

インストール

git clone https://github.com/noguchi513/file-network.git
cd file-network
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
# .env に OPENAI_API_KEY を記入

---

使い方

ファイルを整理する

python main.py SOURCE_DIR OUTPUT_DIR [options]

オプション	説明
--dry-run	ファイルを動かさず、どう整理されるか確認だけする
--mock	APIキーなしで動作確認する（分類は固定のサンプル値）
--config PATH	ビュー定義YAMLのパス（省略時はデフォルト設定）

# まず --dry-run で確認
python main.py ./inbox ./organized --dry-run

# 問題なければ実行
python main.py ./inbox ./organized

# APIキーなしで試す
python main.py ./inbox ./organized --mock

整理前の状態に戻す

python main.py undo [OUTPUT_DIR] [--dry-run]

直前の整理で動かしたファイルを元の場所に戻し、作成したショートカットをすべて削除します。OUTPUT_DIR は省略可能（前回値を自動使用）。

ショートカットのリンク切れを直す

python main.py heal [OUTPUT_DIR]        # 壊れているものを確認するだけ
python main.py heal [OUTPUT_DIR] --fix  # 自動で修復も行う

views/ 内のショートカットを全件チェックし、指す先のファイルが存在しないものを一覧表示します。--fix を付けると、canonical/ の中から同名ファイルを探してリンクを張り直します。

---

ビュー定義のカスタマイズ

views.yaml で使うビューの種類と役割を定義します。required: true のビューは必ず生成されます。

view_types:
  by_date:
    description: "日付別（ファイル名から自動抽出）"
    required: true
  by_category:
    description: "業務カテゴリ別（LLMが判断）"
    required: true
  by_type:
    description: "ファイル種別（拡張子ベース）"
    required: true
  by_project:
    description: "プロジェクト別（省略可）"
    required: false

by_type と by_date は拡張子・ファイル名のルールで処理されます。それ以外はLLMが内容を読んで分類します。

---

リポジトリ構成

file-network/
  main.py                 ← CLIエントリポイント
  views.yaml              ← ビュー定義（カスタマイズ用）
  requirements.txt
  .env.example

  file_network/
    models.py             ← データモデル（Pydantic）
    scanner.py            ← ファイルスキャン・中身の読み取り
    rules.py              ← by_type / by_date のルールベース処理
    llm.py                ← LLM呼び出し（OpenAI）・モック
    graph.py              ← 整理ワークフロー（LangGraph）
    shortcuts.py          ← .lnkファイル生成（pywin32）
    config.py             ← views.yaml 読み込み
    operations_log.py     ← 操作ログ・undo・状態保存
    healer.py             ← ショートカット破損検出・修復

---

内部ワークフロー

intent  → ファイル群の用途・戦略を推定
plan    → ルール(by_type/by_date) + LLM(意味的ビュー) でプラン生成
validate→ パス安全性チェック
execute → ファイル移動 + .lnk生成 + 操作ログ保存
evaluate→ 計画品質をLLMが評価（必要なら再プラン）

---

ライセンス

MIT License — see LICENSE