独自パイプラインの構築
ファイル検出と計画生成ワークフローを設計するための概念ガイド。
このガイドはPlanToCodeの主要なアーキテクチャパターンを概念的なブループリントに凝縮しています。類似システムを構築したい場合でも、特定の設計決定がなぜ行われたかを理解したい場合でも、このドキュメントは再利用または適応できる基本パターンをカバーしています。
パイプラインアーキテクチャマップ
タスク入力から計画出力までの複数ステージパイプラインの概要。
主要なアーキテクチャパターン
ジョブキューパターン
すべてのLLMバックエンド操作はステータス追跡、キャンセルサポート、リトライロジックを持つバックグラウンドジョブとして実行されます。ジョブはSQLiteに永続化されるため、アプリ再起動後も状態が保持されます。
Benefits
- UIの応答性をLLMレイテンシから分離
- ストリーミング中のキャンセルを可能に
- Provides job history of all operations
- 指数バックオフでのリトライをサポート
Pitfalls to Avoid
- ジョブステータス管理が複雑さを追加
- 再起動時の古いジョブの慎重な処理が必要
- 大きなレスポンスでストリーム蓄積がメモリを消費する可能性
ワークフローオーケストレーターパターン
複数ステージワークフローはオーケストレーターによって調整され、ステージを順次スケジュールし、中間データをステージ間で渡し、任意のステージでの失敗を処理します。
Components
- 定義ローダーがワークフローJSON仕様を読み込み
- ステージスケジューラーがステージを順番にディスパッチ
- ペイロードビルダーが前の出力から入力を構築
- イベントエミッターがUI更新用の進捗を発行
リポジトリパターン
すべての永続化はSQLite操作を抽象化する型付きリポジトリを通じて行われます。これによりクリーンなAPI、テスト可能性、データベースアクセスの集中化が提供されます。
Benefits
- 型付きアクセスがSQLインジェクションを防止
- リポジトリをテスト用にモック可能
- 集中化されたクエリ最適化
- 一貫したエラー処理
Pipeline Steps
1. タスクモデルを定義
システムでタスクを構成するものを定義することから始めます。PlanToCodeはタスク説明、ファイル選択、モデル設定を持つセッションを使用します。
履歴追跡用のバージョニング付きで専用テーブルにタスクメタデータを保存します。
2. ジョブキューを構築
ジョブをストレージに永続化し、ステータスイベントを発行し、キャンセルをサポートするジョブキューを作成します。ジョブはプロンプト、レスポンス、トークン、コストを追跡する必要があります。
並列LLMリクエストを制御するためにセマフォベースの同時実行制限を使用します。
3. プロセッサを実装
各ジョブタイプにはプロンプトを構築し、LLMを呼び出し、レスポンスをパースするプロセッサが必要です。長い出力にはストリーミングを使用します。
プロセッサはステートレスで、ジョブパラメータを通じてすべてのコンテキストを受け取る必要があります。
4. ワークフローオーケストレーターを作成
複数ステージワークフロー用に、ステージをスケジュールし、中間データを管理し、失敗を処理するオーケストレーターを構築します。
コード変更なしで簡単に修正できるよう、ワークフロー定義をJSONとして保存します。
5. ルーティングレイヤーを追加
ペイロードを正規化し、APIキーを管理し、使用量を追跡するサーバープロキシを通じてLLMリクエストをルーティングします。
プロバイダー認証情報はサーバーに保持し、デスクトップクライアントには埋め込まないでください。
アーキテクチャ決定
ローカルデータベースとサーバーサイドストレージのどちらを使用すべきか？
ジョブ状態とアーティファクトにはローカルSQLiteを使用。これによりオフライン操作と高速クエリが可能に。課金とクロスデバイス状態のみサーバーに同期。
ストリーミングか非ストリーミングレスポンスか？
計画生成と段階的に表示される出力にはストリーミングを使用。テキスト改善のような短い変換には非ストリーミングを使用。
LLMプロバイダー障害をどのように処理するか？
指数バックオフで自動リトライを実装。レジリエンスのためにOpenRouterのようなフォールバックプロバイダーを検討。
ファイルコンテンツはどこでロードすべきか？
プロンプト構築直前にプロセッサでファイルコンテンツをロード。これにより新鮮なコンテンツが確保され、ジョブレコードに大きなブロブを保存することを回避。
カスタマイズするものと再利用するもの
Customize
- 特定のユースケース用のプロンプトテンプレート
- プロジェクトタイプ用のファイル検出パターン
- 出力フォーマット（XML、JSON、Markdown）
- タスクタイプごとのモデル選択
Reuse
- ステータス追跡付きのジョブキューアーキテクチャ
- ワークフローオーケストレーターパターン
- 永続化用のリポジトリパターン
- ストリーミングレスポンス処理
- プロバイダールーティングと正規化
避けるべき一般的な落とし穴
クライアントにAPIキーを埋め込む
認証情報を安全に管理するサーバープロキシを通じてすべてのLLMリクエストをルーティング。
ジョブ状態を永続化しない
Store every job with full prompt and response for review and recovery.
LLMコールでUIをブロック
レスポンシブなインターフェースのためにイベント駆動UI更新付きのバックグラウンドジョブを使用。
トークン制限を無視
送信前にトークンを見積もり、コンテキストウィンドウ内に収まるよう大きな入力をチャンク化。
キャンセルサポートなし
ストリーミングチャンク間でキャンセルフラグをチェックしサーバーに伝播。
永続化するアーティファクト
- Full prompt sent to the LLM (for debugging and review)
- ストリーミング蓄積を含む完全なレスポンス
- プロバイダーレスポンスからのトークン数
- モデル価格に基づいて計算されたコスト
- バージョニング用のシステムプロンプトテンプレート識別子
- 複数ステージフロー用のワークフロー中間データ
実装メモ
- 同時読み書きアクセス用にWALモードでSQLiteを使用
- 実行中のジョブを失敗としてマークするグレースフルシャットダウンを実装
- ジョブ処理前に外部依存関係のヘルスチェックを追加
- デバッグ用に完全なコンテキスト付きですべてのLLMエラーをログ記録
- 冗長な読み取りを避けるため短いTTLでファイルコンテンツキャッシングを検討