185 lines
6.8 KiB
Markdown
185 lines
6.8 KiB
Markdown
# `worker` ライブラリ
|
||
|
||
`worker`は、LLM（大規模言語モデル）との対話を抽象化し、複数のLLMプロバイダを統一的に扱うための共通ライブラリです。動的ツール登録システム、フックシステム、MCPプロトコル統合を提供します。
|
||
|
||
## アーキテクチャ
|
||
|
||
**Core Crate Pattern**を採用：`worker-types`（基本型）→ `worker-macros`（マクロ）→ `worker`（メインライブラリ）
|
||
|
||
循環依存を解消し、型安全性と保守性を向上させています。
|
||
|
||
## 概要
|
||
|
||
LLMプロバイダ（Gemini, Claude, OpenAI, Ollama, XAI）を統一インターフェースで利用できます。`Worker`構造体が中心となり、プロンプト管理、ツール登録、フックシステム、MCPサーバー統合を提供します。
|
||
|
||
## 主要なコンポーネント
|
||
|
||
### `Worker`
|
||
|
||
LLMとの対話における中心的な構造体です。
|
||
|
||
- **LLMクライアントの保持**: `LlmClient` enumを通じて複数プロバイダの統一インターフェースを提供
|
||
- **プロンプト管理**: `PromptComposer`によるテンプレートベースのプロンプト組み立て
|
||
- **ストリーミング処理**: リアルタイムイベントストリーム（`process_task_stream`）とメッセージ履歴管理（`process_task_with_history`）
|
||
- **動的ツール管理**: 実行時ツール登録・実行、MCPサーバー統合
|
||
- **フックシステム**: メッセージ送信、ツール利用、ターン完了時の拡張ポイント
|
||
- **セッション管理**: メッセージ履歴の保存・復元機能
|
||
|
||
### `Tool` トレイト
|
||
|
||
動的ツール登録の基盤。`worker-types`で定義され、`#[tool]`マクロで自動実装可能です。
|
||
|
||
### `StreamEvent`
|
||
|
||
LLMストリーミング応答のイベント型。テキストチャンク、ツール呼び出し、ツール結果、完了通知、デバッグ情報、フックメッセージをサポートします。
|
||
|
||
### `LlmClient` Enum
|
||
|
||
各LLMプロバイダクライアントの統合enum。`LlmClientTrait`を実装し、統一されたストリーミング対話と接続確認機能を提供します。
|
||
|
||
### フックシステム
|
||
|
||
- `WorkerHook` トレイト: カスタムフック実装の基盤
|
||
- `HookManager`: フック登録・実行管理
|
||
- `HookEvent`: OnMessageSend、PreToolUse、PostToolUse、OnTurnCompleted
|
||
- `HookContext`: フック実行時のコンテキスト情報
|
||
|
||
### その他の主要型
|
||
|
||
- `Message`: LLM対話のメッセージ（role + content + tool_calls）
|
||
- `LlmDebug`: デバッグログ制御と詳細出力
|
||
- `ModelInfo`: モデル情報とサポート機能
|
||
- `SessionData`: セッション永続化データ
|
||
|
||
## 基本的な使用方法
|
||
|
||
```rust
|
||
use worker::{Worker, LlmProvider, types::{Message, Role, StreamEvent}};
|
||
use futures_util::StreamExt;
|
||
|
||
// Worker初期化
|
||
let mut worker = Worker::new(
|
||
LlmProvider::Gemini,
|
||
"gemini-1.5-flash",
|
||
&api_keys,
|
||
None
|
||
)?;
|
||
|
||
// ツール登録（オプション）
|
||
worker.register_tool(Box::new(some_tool))?;
|
||
|
||
// メッセージ送信とストリーム処理（履歴あり）
|
||
let mut stream = worker.process_task_with_history(
|
||
"Hello, how are you?".to_string(),
|
||
None
|
||
).await;
|
||
|
||
while let Some(Ok(event)) = stream.next().await {
|
||
match event {
|
||
StreamEvent::Chunk(text) => print!("{}", text),
|
||
StreamEvent::ToolCall(call) => println!("Tool: {}", call.name),
|
||
StreamEvent::ToolResult { tool_name, result } => {
|
||
println!("Result from {}: {:?}", tool_name, result);
|
||
},
|
||
StreamEvent::Completion(_) => break,
|
||
_ => {}
|
||
}
|
||
}
|
||
```
|
||
|
||
### ツール登録と実行
|
||
|
||
```rust
|
||
// 個別ツール登録
|
||
worker.register_tool(Box::new(ReadFileTool::new()))?;
|
||
|
||
// MCPサーバーからのツール登録
|
||
let mcp_config = McpServerConfig {
|
||
name: "filesystem".to_string(),
|
||
command: "npx".to_string(),
|
||
args: vec!["-y".to_string(), "@modelcontextprotocol/server-filesystem".to_string()],
|
||
env: HashMap::new(),
|
||
};
|
||
worker.register_mcp_tools(mcp_config).await?;
|
||
|
||
// 複数MCPサーバーの並列初期化
|
||
worker.queue_mcp_server(config1);
|
||
worker.queue_mcp_server(config2);
|
||
worker.init_mcp_servers().await?;
|
||
|
||
// ツール実行
|
||
let result = worker.execute_tool("read_file", json!({"path": "./file.txt"})).await?;
|
||
```
|
||
|
||
### フックシステム
|
||
|
||
```rust
|
||
// カスタムフック実装例
|
||
struct MyHook;
|
||
|
||
#[async_trait::async_trait]
|
||
impl WorkerHook for MyHook {
|
||
fn name(&self) -> &str { "my_hook" }
|
||
fn hook_type(&self) -> &str { "OnMessageSend" }
|
||
fn matcher(&self) -> &str { "" }
|
||
|
||
async fn execute(&self, mut context: HookContext) -> (HookContext, HookResult) {
|
||
// メッセージ前処理
|
||
let new_content = format!("[処理済み] {}", context.content);
|
||
context.set_content(new_content);
|
||
(context, HookResult::Continue)
|
||
}
|
||
}
|
||
|
||
// フック登録
|
||
worker.register_hook(Box::new(MyHook));
|
||
```
|
||
|
||
### 主要API
|
||
|
||
- `register_tool()`: ツール登録
|
||
- `register_mcp_tools()`: MCPサーバーからのツール登録
|
||
- `register_hook()`: フック登録
|
||
- `get_tools()`: 登録済みツール一覧
|
||
- `execute_tool()`: ツール実行
|
||
- `process_task_stream()`: LLMストリーミング対話（履歴なし）
|
||
- `process_task_with_history()`: メッセージ履歴付きストリーミング対話
|
||
- `get_session_data()`: セッションデータ取得
|
||
- `load_session()`: セッション復元
|
||
|
||
## 型システム
|
||
|
||
**Core Crate Pattern**により型を分離：
|
||
- `worker-types`: 基本型（Tool, Message, StreamEvent等）
|
||
- `worker`: 実装とエラー型（WorkerError等）
|
||
|
||
後方互換性のため`worker::types::`経由で全型にアクセス可能。
|
||
|
||
## 主要型
|
||
|
||
- `ToolResult<T>`: ツール実行結果
|
||
- `DynamicToolDefinition`: ツール定義情報
|
||
- `WorkerError`: ライブラリ固有エラー型
|
||
|
||
## LLMプロバイダサポート
|
||
|
||
全プロバイダでストリーミング対話、ツール呼び出し、モデル一覧取得、接続確認を完全実装：
|
||
- Gemini (Google)
|
||
- Claude (Anthropic)
|
||
- OpenAI
|
||
- Ollama
|
||
- XAI (Grok)
|
||
|
||
## 主要機能
|
||
|
||
- **Core Crate Pattern**: 循環依存解消による保守性向上
|
||
- **動的ツール登録**: 実行時ツール追加・実行
|
||
- **#[tool]マクロ**: 関数からツール自動生成
|
||
- **フックシステム**: メッセージ送信・ツール利用・ターン完了時の拡張ポイント
|
||
- **ストリーミング対話**: リアルタイムLLM応答とイベント処理
|
||
- **複数プロバイダ**: 統一インターフェースでの5つのLLMプロバイダサポート
|
||
- **MCP統合**: Model Context Protocolサーバーとの動的連携
|
||
- **セッション管理**: メッセージ履歴の永続化・復元
|
||
- **ワークスペース検出**: Git情報を含む作業環境の自動認識
|
||
- **型安全性**: 強い型チェックとエラーハンドリング
|
||
- **並列処理**: MCPサーバーの並列初期化による高速化 |