# uagent プロジェクト高速化・最適化計画

本ドキュメントは、`uagent` プロジェクトにおけるパフォーマンス上のボトルネックを特定し、高速化およびリソース消費削減を実現するための具体的な改善策をまとめた計画書です。

---

## 1. 起動速度の向上（Lazy Import の徹底）

### 課題
`uag` コマンドの実行時、プロンプトが表示されるまでに体感できる遅延（初期オーバーヘッド）が存在します。これは、`cli.py` や `core.py` のグローバルスコープで、使用頻度の低い重い外部ライブラリ（`openai`、`google-genai`、`pyside6`、`playwright` など）が即座にインポートされているためです。

### 改善策
- **外部依存ライブラリの遅延ロード（Lazy Import）**:
  - `cli.py` のトップレベルにある `import openai` や `import google` などのインポート処理を、実際にそれらのクライアントが必要になる関数（例: `_make_client` や各ツールの `run_tool` 内部）へ移動します。
  - GUI（`pyside6`）やブラウザ操作（`playwright`）など、特定のコマンドライン引数やツール実行時のみ使用するモジュールは、エントリーポイントでのインポートを徹底的に排除します。

---

## 2. ファイル置換処理（`replace_in_file`）の最適化

### 課題
`replace_in_file` ツールで大規模なファイルを編集、または `replace_all_in_files` で多数のファイルを一括置換する際、診断情報の生成や差分（diff）計算、同期的なファイルI/Oがボトルネックになります。

### 改善策
- **診断情報（`match_hits`）の生成制限**:
  - 一致箇所が大量にある場合、詳細な行・列番号や前後コンテキストの抽出を先頭の $N$ 件（例: 100件）までに制限し、それ以降はカウントのみ行うことで、メモリ消費とJSONシリアライズのコストを削減します。
- **差分（diff）生成の早期打ち切り**:
  - `difflib.unified_diff` は純粋な Python 実装で遅いため、変更前後の合計文字数が一定（例: 1MB）を超える場合は、diff 生成をスキップして `[diff omitted: file too large]` などの簡易メッセージに差し替えます。
- **一括置換の並列化**:
  - `replace_all_in_files` 実行時、`concurrent.futures.ThreadPoolExecutor` を用いて、複数ファイルの読み込み・マッチング判定を並列化します。書き込みは安全のため、競合を防ぎつつ一括処理します。

---

## 3. ベクトルインデックス化（`index_files`）の高速化

### 課題
セマンティック検索用のベクトルDB構築（`index_files`）において、テキストを500文字などのチャンクに分割し、1チャンクごとに Embedding API を同期呼び出ししているため、ネットワーク往復遅延（RTT）が累積して処理が極めて低速になっています。また、チャンクごとの SQLite コミットがディスクI/Oのボトルネックになっています。

### 改善策
- **バッチリクエスト（一括ベクトル化）の導入**:
  - OpenAI や Gemini などの Embedding API は、複数テキストのリストを1回のリクエストで処理するバッチ送信に対応しています。
  - 1回あたり 16〜32 チャンク（または合計 15,000〜20,000 文字程度）をまとめて1つの API リクエストで送信するように `_get_embedding` を拡張し、ネットワーク往復回数を劇的に削減します。
- **SQLite トランザクションの集約**:
  - チャンクごとの `INSERT` および `commit()` を廃止します。
  - ファイル全体の全チャンクのベクトルを取得し終えてから、1つのトランザクション内で `executemany()` を用いて一括保存し、最後に1回だけ `commit()` することで、ディスクI/Oを最小化します。
- **メタデータによるスキップ判定の厳格化**:
  - ファイルの `mtime`（更新日時）や `file_size` に変化がない場合は、ファイルの読み込みやAPI呼び出しを完全にスキップする仕組みを確実に機能させます。

---

## 4. 期待される効果

1. **コマンド起動時間**: 1秒未満（ほぼ瞬時）への短縮。
2. **一括置換処理**: 数十〜数百ファイルに対する処理速度が 2〜5 倍に向上。
3. **インデックス構築**: ネットワーク環境にもよりますが、バッチ化により構築速度が 5〜10 倍以上に向上。
