# 主要なアップデートとアーキテクチャの軌跡（プロジェクト全史）

このドキュメントは、`uag` プロジェクトの誕生から現在に至るまでに導入された主要なアップデート、アーキテクチャの進化、および新機能についてまとめたものです。

---

## 1. コアアーキテクチャとマルチプロバイダ対応（ローカルAI対応の強化）
本プロジェクトは、クラウドAPIだけでなく、**Ollama** などを介した完全なローカル（オフライン）環境をシームレスにサポートする、堅牢なマルチプロバイダLLMクライアントアーキテクチャを基盤として構築されています。

* **マルチプロバイダ統合とローカルAIの強力なサポート**:
  * **OpenAI, Azure OpenAI, Anthropic Claude, Google Gemini, Google Vertex AI, AWS Bedrock, OpenRouter, Ollama, Grok (xAI), NVIDIA** のネイティブAPIをサポート。
  * 特に **Ollama** を用いたローカルLLM（Llama 3.1など）のサポートを徹底的に強化。ローカル環境特有のパラメータ（`keep_alive`, `num_ctx` によるコンテキストサイズ拡張、`repeat_penalty` など）を環境変数から細かくチューニングできる仕組み（`apply_ollama_extra_body`）を実装し、完全オフライン環境でもクラウド並みに高度なツール実行（Tool-use）や画像解析（Ollama Vision）を可能にしました。
* **LLMとの対話の自動翻訳機能（双方向翻訳）**:
  * ユーザーの入力とLLMの応答を自動翻訳する、ステートレスな翻訳ヘルパー（`translate.py`）を実装。これにより、ユーザーが日本語で入力した内容を自動的に英語に翻訳してLLMに送り、LLMからの英語の応答を再び日本語に翻訳してユーザーに返す、といった「LLMとの対話自体の双方向翻訳」をシームレスに実現しています。OpenAI互換APIのほか、GeminiやClaudeのネイティブAPIによる翻訳にも対応しています。
* **決定論的推論と設定温度（Temperature）の統一**:
  * エージェントループ実行時、すべての主要LLMプロバイダにおいて、デフォルトの `temperature` を **`0.2`** に統一し、ツールの呼び出し、JSONフォーマットの出力、および論理的な思考ステップの安定性を確保。
  * 環境変数（例: `UAGENT_GEMINI_TEMPERATURE`, `UAGENT_CLAUDE_TEMPERATURE`, `UAGENT_OLLAMA_TEMPERATURE`）を介して、プロバイダごとに温度を個別に上書きできる仕組みを導入。

---

## 2. コンテキスト圧縮と履歴の引き継ぎ (`shrink_llm`)
長時間の自律エージェントループにおいて、コンテキスト窓の溢れ（オーバーフロー）を防ぎ、トークン消費量を劇的に削減するため、高度な履歴圧縮メカニズムが実装されています。

* **LLMによる自律的な履歴圧縮 (`compress_history_with_llm`)**:
  * システムプロンプト以外の会話履歴が閾値（`UAGENT_SHRINK_CNT`、デフォルト `100` 件）を超えた際、バックグラウンドで自動的に圧縮処理がトリガーされます。
  * 直近の重要な会話（`UAGENT_SHRINK_KEEP_LAST`、デフォルト `20` 件）はそのまま残して即時的な文脈を維持します。
  * それ以前の古い履歴は、別のLLMコンテキストを立ち上げて段階的に要約・圧縮し、1つの高密度な `system` メッセージに統合します。これにより、トークン制限に達することなく、過去の決定事項、実行結果、エラー情報などの文脈をLLM間で無限に引き継ぐことができます。

---

## 3. 長期記憶（Long-term Memory）と自律プロファイリングシステム
エージェントがユーザーの好み、環境情報、およびセッションをまたいだ文脈を保持できるように、永続的な記憶およびプロファイリングレイヤーが備わっています。

* **個人用長期記憶 (`UAGENT_MEMORY_FILE`)**:
  * エージェントが対話を通じて得た重要な知見やユーザーの指示、環境設定を、ローカルのJSONLファイル（`scheck_memory.jsonl`）に永続化します。
  * これらの記憶は起動時にシステムプロンプトへ自動的に注入され、エージェントがセッションをまたいでユーザーの好みを「覚えている」状態を維持します。
* **自律ユーザープロファイリングとスマートマージ (`UAGENT_ENABLE_PROFILING`)**:
  * ユーザーの明示的な設定なしに、会話ログから「開発環境（OS/シェル/エディタ）」「コーディングの好み」「開発上の制約」をバックグラウンドで自律的に分析・抽出するプロファイリング機能を標準搭載（デフォルトで有効、`UAGENT_ENABLE_PROFILING=0` で無効化可能）。
  * 抽出されたプロファイルは、専用の **`scheck_profile.jsonl`** に保存され、既存のプロファイルと「スマートマージ（環境情報は最新値で上書き、好みや制約は重複排除して追加）」されます。
  * 保存前にAPIキーやパスワードなどの機密情報を自動検知して強制マスクするセキュリティフィルターを内蔵し、プライバシーを完全に保護した状態で起動時にシステムプロンプトへ自動注入されます。
* **Shared Long-term Memory (`UAGENT_SHARED_MEMORY_FILE`)**:
  * 複数のエージェントや異なるセッション間でアクセス可能な共有記憶ファイルをサポートし、協調的なコンテキスト共有を可能にします。
  * 対話型コマンド `:shared-mem-list` や `:shared-mem-del <index>` を介して、CLIから直接共有記憶のエントリを管理できます。

---

## 4. 専門サブエージェント・アーキテクチャ (`run_sub_agent`)
親エージェント（オーケストレーター）の制御下で、特定の専門タスクを安全かつサンドボックス化された環境で実行する「サブエージェント実行フレームワーク」が導入されました。

* **役割ベースのサブエージェント**:
  * `planner` (計画設計): 段階的な実行計画の策定、リスクの特定、制約事項の整理。
  * `reviewer` (コード監査): コード、設計、パッチ案のバグ、セキュリティ脆弱性、無限ループリスクの監査。
  * `summarizer` (文脈圧縮): 長い会話履歴やログを必要不可欠なコンテキストに要約・圧縮。
  * `patch_designer` (パッチ設計): 実際の書き換えを行わずに、安全で具体的なコード置換パッチ（差分）を設計。
  * `error_analyst` (エラー解析): コンパイル、テスト、または実行時エラーを解析し、根本原因（Root Cause）を特定。
* **機能（役割）別の個別上書き (オーバーライド)**:
  * サブエージェントの役割ごとに、LLMプロバイダ、モデル名、APIキーを個別に上書きできる環境変数（例: `UAGENT_SUB_AGENT_SUMMARIZER_PROVIDER=gemini` を指定して、要約タスクのみを高速・安価な Gemini 2.5 Flash に処理させる）をサポート。

---

## 5. 高度なツール群とファイル操作
エージェントがユーザーのマシンと安全かつ効率的に対話できるように、豊富なローカルツール群が開発・洗練されてきました。

* **ファイル検索と操作（ページング機能の統合）**:
  * `search_files` / `file_grep`: ディレクトリ走査やファイル内容のパターン検索において、大量の検索結果を安全かつ効率的にスクロールして確認できる **`page`（ページング）パラメータ** を統合。これにより、LLMがコンテキスト窓を圧迫することなく、巨大なプロジェクトから目的のファイルを段階的に探索できるようになりました。
  * `read_file` / `read_pptx_pdf`: 巨大なテキストファイルや、ページ数の多いPDF/PPTXドキュメントを読み込む際、`page` パラメータを指定して特定の範囲やページのみをピンポイントで読み込めるページング機能をサポート。
  * `replace_in_file`: パフォーマンスの最適化、改行コードに関する診断機能、およびエラーレポート機能を強化。
  * `document_extract`: Word系文書（`.docx`, `.rtf`, `.odt`）から本文テキストと構造を抽出するツールを追加。
* **構造化データの抽出と低レイヤー操作**:
  * `exstruct`: Excel（`.xlsx`）ファイルから、表の構造や図形、ハイパーリンクを検出し、JSONやYAMLとして構造化データを抽出。
  * `binary_edit`: ローカルファイルをバイト単位で直接編集（オフセット書き換え、検索置換、JSONパッチ適用など）できる、開発者向けの強力な低レイヤーツール。
  * `db_query`: ローカルのSQLiteデータベースに対して、安全に読み取り専用（SELECT）クエリを実行し、スキーマやデータを直接確認。
* **バッチ状態管理**:
  * 処理の進捗管理、中断されたタスクの再開、ファイルごとの実行結果の記録を行う堅牢なバッチ状態追跡ツール（`batch_state`）を導入。
* **Playwright Inspector**:
  * ブラウザ操作、ネットワークイベント、コンソールログをキャプチャする Playwright Inspector を統合。

---

## 6. エージェント間連携（A2A）と外部プラットフォーム統合
他のエージェントとの協調や、主要なコミュニケーションプラットフォームとのシームレスな連携が可能です。

* **エージェント間協調プロトコル (A2A)**:
  * 異なるエージェント間でメッセージを送信し、タスクの進捗をポーリングして同期する A2A プロトコル（`a2a_send`, `a2a_poll`, `a2a_servers`）をサポート。
* **外部プラットフォーム連携**:
  * `discord_channel_chat`: ボットトークンを使用して、特定のDiscordチャンネルと直接対話し、メッセージの送受信や履歴の取得を行う機能。
  * `teams_webhook_post`: Microsoft Teams の Incoming Webhook を介して、高度にフォーマットされたカード形式の通知やメッセージを送信する機能。

---

## 7. 多言語対応 (I18N)
プロジェクト全体で、グローバル対応のための包括的な国際化フレームワークを備えています。

* **グローバル展開**:
  * CLI、セットアップウィザード、およびツール仕様を**世界30カ国語**（日本語、英語、アラビア語、ヒンディー語、ポルトガル語、ベンガル語、ペルシャ語、モンゴル語、マラーティー語など）に完全ローカライズ。
  * Windowsコンソールの言語自動検出と、ツール内でのI18Nロジックの統一。
* **ツールカタログ検索**:
  * ツールカタログの多言語トークン化サポートを追加し、ユーザーの意図に基づいた検索ランキングと発見精度を向上。

---

## 8. セキュリティと暗号化 (`uag_envsec`)
APIキーや認証情報などの機密情報を保護するため、堅牢な暗号化レイヤーが統合されました。

* **環境変数の暗号化**:
  * `uag_envsec` を統合し、パスワードベースの暗号化によって `.env` ファイルを `.env.sec` に暗号化。
  * CLI起動時に `.env.sec` を自動的に検出して復号・ロードする仕組みを実装。
  * 変数を安全に追加・更新するための `envsec add` コマンドを追加。

---

## 9. GUI、Web、およびマルチメディアの強化
グラフィカル、Webベース、およびマルチメディア機能により、ユーザー体験が大幅に強化されました。

* **GUIコンソールとログ描画**:
  * ターミナルのカラーログをGUI上で正しく解析・表示するための ANSI HTML 描画ヘルパーを追加。
  * GUIコンソールにおけるログのカラー描画の不具合を修正。
* **Web UI 機能**:
  * ドラッグ＆ドロップによるファイルアップロード機能を追加し、画像添付の描画を改善。
* **マルチメディアツール**:
  * `generate_image` & `img2img`: DALL-E 3、Gemini、Vertex AI (Imagen 3) をサポートし、生成後の自動オープン動作に対応。
  * `audio_speech` & `audio_transcribe`: OpenAI、Azure、Gemini、Vertex AI をサポート（Windowsとの互換性のために Google Cloud TTS REST トランスポートを実装）。
