llm-worker-rs/docs/architecture.md

各クレートの役割

• worker-types: 全ての基本型定義（Tool, Message, StreamEvent, フック関連型等）
• worker-macros: プロシージャルマクロ（#[tool]）による自動実装
• worker: メインライブラリ（Worker, LLMクライアント, プロンプトコンポーザー等）
• tools: 具体的なツール実装（read, write, bash, mcp等）

workerクレートはworker-typesの全型を再エクスポートし、外部からはworker::types::でアクセス可能です。

エラーハンドリング戦略

• worker-types: ToolResult<T> - 汎用的なツールエラー（Result<T, Box<dyn std::error::Error + Send + Sync>>）
• worker: WorkerError - ライブラリ固有エラー（設定、ネットワーク、ツール実行、JSON解析等）

自動的な型変換（From trait実装）により、一貫したエラーハンドリングを実現しています。認証エラーの自動検出機能も含まれています。

マクロ実装

worker-macrosは完全修飾パスで型を参照し、Core Crate Patternに準拠：

// #[tool]マクロが生成するコード例
impl ::worker_types::Tool for ReadFileTool {
    fn name(&self) -> &str { "read_file" }
    fn description(&self) -> &str { "ファイルを読み込みます" }
    fn parameters_schema(&self) -> ::worker_types::serde_json::Value { /* スキーマ */ }
    
    #[::worker_types::async_trait::async_trait]
    async fn execute(&self, args: ::worker_types::serde_json::Value) 
        -> ::worker_types::ToolResult<::worker_types::serde_json::Value> {
        // 元の関数呼び出し
    }
}

利用ガイドライン

• 新しいツール: #[tool]マクロでasync関数を装飾し、worker::types::ToolResultを返り値型に使用
• 新しいLLMプロバイダ: worker/src/llm/にクライアント実装を追加し、LlmClient enumに追加
• 新しいフック: WorkerHook traitを実装し、HookManagerで管理
• 型の変更: worker-typesで基本型を変更し、コンパイルエラーで影響範囲を確認
• MCP統合: mcp_toolモジュールを使用してModel Context Protocolサーバーとの連携を実装

主要な設計パターン

• 委譲パターン: LlmClient enumでの各プロバイダクライアントへの委譲
• ストリーミング: async streamを使用したリアルタイムイベント処理
• プロンプトテンプレート: Handlebarsベースの動的プロンプト生成
• セッション管理: メッセージ履歴の永続化と復元
• 並列処理: MCPサーバーの並列初期化による高速化