refactor: rename llm worker crate to engine

2026-06-25 22:46:26 +09:00
parent 22598710fd
commit 292fc4ea5d
202 changed files with 1129 additions and 1125 deletions
@@ -0,0 +1,73 @@
+# llm-engine アーキテクチャ
+
+## 概要
+
+llm-engineは3層構成でLLMとのインタラクションを管理する。
+
+```
+┌─────────────────────────────────────────┐
+│  Engine (オーケストレーション)            │
+│  ターンループ / フック / ツール実行       │
+│  Type-state: Mutable ↔ CacheLocked      │
+└───────────┬─────────────────────────────┘
+            │
+┌───────────▼─────────────────────────────┐
+│  Timeline (イベント処理)                 │
+│  Handler dispatch / Block collectors     │
+└───────────┬─────────────────────────────┘
+            │
+┌───────────▼─────────────────────────────┐
+│  LLM Client (プロトコル)                 │
+│  Provider (HTTP) / Scheme (変換)         │
+│  Anthropic / OpenAI / Gemini / Ollama    │
+└─────────────────────────────────────────┘
+```
+
+## モジュール構成
+
+| モジュール | 責務 | 要件 |
+|---|---|---|
+| `engine` | ターンループ、フック統合、ツール実行、Pause/Resume | R1, R4 |
+| `state` | Type-state (Mutable/CacheLocked) | R2 |
+| `hook` | Hook trait、10フックポイント | R3, R4 |
+| `tool` / `tool_server` | ツール定義・登録・実行 | R3 |
+| `timeline` | イベントストリーム処理、Handler dispatch | — |
+| `handler` | Handler/Kind trait、ブロック別ハンドラ | — |
+| `callback` | クロージャベースイベント購読（`on_text_block`, `on_usage` 等） | — |
+| `llm_client` | LLMプロバイダへのHTTPリクエスト/ストリーミング | — |
+| `llm_client/scheme` | プロバイダ固有ワイヤーフォーマット変換 | — |
+| `llm_client/providers` | Anthropic, OpenAI, Gemini, Ollama実装 | — |
+
+## データフロー
+
+### リクエスト（送信）
+```
+Engine.history (Vec<Item>)
+  → build_request() → Request { items, tools, config }
+    → Scheme.build_request() → プロバイダ固有JSON
+      → Provider.stream() → HTTP POST
+```
+
+### レスポンス（受信）
+```
+HTTP SSE bytes
+  → Provider → SSE events
+    → Scheme.parse_event() → Event (統一型)
+      → Timeline.dispatch() → Handler.on_event()
+        → TextBlockCollector / ToolCallCollector
+          → Engine: 履歴に追加、ツール実行判定
+```
+
+## 内部型
+
+### Item (会話履歴の単位)
+- `Item::Message` — テキストメッセージ (user/assistant)
+- `Item::ToolCall` — ツール呼び出し
+- `Item::ToolResult` — ツール実行結果
+- `Item::Reasoning` — 思考 (Extended Thinking)
+
+### Event (ストリーミングイベント)
+- Meta: `Ping`, `Usage`, `Status`, `Error`
+- Block: `BlockStart` → `BlockDelta`* → `BlockStop` / `BlockAbort`
+
+単一の `Event` 型が全層で共有される（`llm_client::event` で定義、他層はre-export）。
@@ -0,0 +1,48 @@
+# llm-engine 要件
+
+## 前提
+
+a. userメッセージを追加しなくてもagentの途中ママ投げれば、AIはそれを自身の生成途中と認識して普通に継続する
+b. KVキャッシュは速度・効率の面で有利で、コンテキストの事後改変はキャッシュヒット率を大幅に下げる
+c. ツール・フックの基本的なスキーマ自動化を提供する
+
+## 要件
+
+### R1: Resume/Pause
+
+メッセージの送信と生成のResume、一時停止/再開。
+
+- `Engine::run()` でターンを開始
+- フックから `Pause` を返してターンを一時停止
+- `Engine::resume()` でユーザーメッセージを追加せず継続
+- AIは中断を認識せず、継続として処理する
+
+**実装**: `engine.rs` — `resume()`, `get_pending_tool_calls()`, `EngineResult::Paused`
+
+### R2: 暗黙的KVキャッシュ保証
+
+キャッシュを破壊しうる操作を明示的にブロックせずとも、いつの間にかキャッシュ破壊してた状態にはしたくない。
+
+- Type-stateパターン（`Mutable` / `CacheLocked`）でコンパイル時に保証
+- `Engine::lock()` でCacheLocked状態に遷移
+- CacheLocked状態ではシステムプロンプトや履歴の変更APIが型レベルで利用不可
+- `locked_prefix_len` でプレフィックスの不変性を追跡
+
+**実装**: `state.rs` (sealed trait), `engine.rs` (state-specific impl blocks)
+
+### R3: ツール・フックスキーマ自動化
+
+- `#[tool]` マクロでツール定義を自動生成
+- `#[tool_registry]` マクロでツールサーバーを自動構成
+- `Hook` traitで10種のフックポイント
+
+**実装**: `llm-engine-macros/`, `tool.rs`, `tool_server.rs`, `hook.rs`
+
+### R4: フックは上層の関心事
+
+フックはLLMクライアント層ではなく、Engine（オーケストレーション）層に配置する。
+
+- LLMクライアント (`llm_client/`) はストリーミングとプロトコルのみ
+- Engine層でフック実行、ツール統合、Pause/Resume制御
+
+**実装**: `engine.rs` (hook integration), `hook.rs` (trait definitions)