Back to Docs
技術ガイド

ファイル検出ワークフロー

タスク実行のための関連ファイルを識別しフィルタリングする5段階AIワークフローの包括的な技術ガイド。

12分 read

PlanToCodeは、プランを立てたりコマンドを実行したりする前に、適切なファイルを識別します。5段階のワークフローは範囲を絞り込み、コンテキストを簡潔に保ちます。

ワークフローアーキテクチャ

ワークフローは、順次実行される5つの異なる段階を持つオーケストレーションされたバックグラウンドジョブシステムとして動作します。各段階は前の段階の出力に基づいて構築され、タスク要件に基づいてファイル選択を徐々に洗練します。

システムは分散ジョブアーキテクチャを使用し、各段階が独立したバックグラウンドジョブとして実行され、キャンセル、再試行ロジック、詳細な進行状況追跡が可能です。実行中にリアルタイムイベントが公開され、ユーザーインターフェースに即座にフィードバックを提供します。

主要なアーキテクチャ機能:

  • WebSocketのような更新によるイベント駆動の進行状況報告
  • 自動再試行メカニズムを備えた包括的なエラーハンドリング
  • AI操作のコスト追跡とタイムアウト管理
  • パフォーマンス最適化のための中間結果のキャッシュ
  • ディレクトリトラバーサルへのフォールバックを伴うGit統合

5段階ワークフロープロセス

段階1:ルートフォルダの選択

プロジェクトのルートディレクトリを決定し、gitリポジトリのステータスを検証します。この段階は、すべての後続のファイル操作のベースディレクトリを確立し、除外パターンを設定します。

技術的詳細:ディレクトリ検証へのフォールバックを備えたgit検出を使用し、ユーザー定義の除外パターンを適用し、ワークフロー全体の作業ディレクトリコンテキストを確立します。

段階2:正規表現ファイルフィルター

タスクの説明に基づいてインテリジェントな正規表現パターンを生成し、初期ファイルフィルタリングを実行します。この段階では、git ls-files出力とバイナリファイル検出を組み合わせて、予備的なファイルリストを作成します。

Git統合:`git ls-files --cached --others --exclude-standard`を実行して、追跡されたファイルと未追跡のファイルの両方を含めながら.gitignoreルールを尊重します。
バイナリ検出:バイナリ拡張子(.jpg、.png、.pdf、.exeなど)を持つファイルをフィルタリングし、ヌルバイトと非印字文字の比率によるコンテンツ分析を使用してバイナリファイルを検出します。

段階3:AIファイル関連性評価

AIモデルを使用してファイルコンテンツを分析し、特定のタスクの説明との関連性を評価します。この段階では、特定のタスクに最も役立つ可能性が高いファイルを識別するために、深いコンテンツ分析を実行します。

AI処理:大規模言語モデルを使用してタスク要件に対してファイルコンテンツを評価し、トークン制限とコスト最適化を管理するためのインテリジェントなバッチ処理を使用します。

段階4:拡張パスファインダー

関係分析と依存関係追跡を通じて、追加の関連ファイルを発見します。この段階では、初期パターンに一致しない可能性があるが、コンテキスト的に重要なファイルを識別します。

関係分析:インポートステートメント、設定ファイル、プロジェクト構造を分析して、特定のタスクのコンテキストを強化する関連ファイルを見つけます。

設定オプション

ワークフロー設定

タイムアウト管理

ワークフロー全体または個別の段階の最大実行時間を設定して、無期限のハングを防ぎます。

timeoutMs: 300000 // 5 minutes default

除外パターン

検出プロセスから除外するディレクトリとファイルパターンを定義します。

excludedPaths: ["node_modules", ".git", "dist", "build"]

再試行設定

失敗した段階の最大再試行回数を指数バックオフで設定します。

maxRetries: 3 // Per stage retry limit

API使用例

ワークフローの開始

const tracker = await WorkflowTracker.startWorkflow(
  sessionId,
  "Add user authentication to the login page",
  "/path/to/project",
  ["node_modules", "dist"],
  { timeoutMs: 300000 }
);

進行状況の監視

tracker.onProgress((state) => {
  console.log(`Stage: ${state.currentStage}`);
  console.log(`Progress: ${state.progressPercentage}%`);
});
tracker.onComplete((results) => {
  console.log(`Selected ${results.selectedFiles.length} files`);
});

結果の取得

const results = await tracker.getResults();
const selectedFiles = results.selectedFiles;
const intermediateData = results.intermediateData;
const totalCost = results.totalActualCost;

パフォーマンスの考慮事項

メモリ管理

ワークフローは、ファイルキャッシュ(30秒TTL)、バッチ処理(バッチあたり100ファイル)、中間データの自動クリーンアップを備えたインテリジェントなメモリ管理を実装して、メモリ枯渇を防ぎます。

コスト最適化

AI段階はAPIレスポンスから実際のコストを追跡し、トークン使用量を最小限に抑えるインテリジェントなバッチ処理を実装し、実行前にコスト見積もりを提供して経費管理を支援します。

パフォーマンス監視

組み込みのパフォーマンストラッキングは、実行時間、メモリ使用量、スループットメトリックを監視し、過去のデータ分析に基づいて最適化のための推奨事項を提供します。

統合パターン

デスクトップアプリケーション

ワークフローはTauriコマンドを通じてデスクトップアプリケーションとシームレスに統合され、ネイティブファイルシステムアクセスとWorkflowTrackerクラスを介したイベント駆動の更新を提供します。

実装プラン統合

選択されたファイルは自動的に実装プランパネルに送られ、検出ワークフローを再実行することなく、プラン生成が同じ最適化されたファイルコンテキストを使用することを保証します。

セッション管理

ワークフローの結果はセッションごとにキャッシュされ、同じセッション内の複数の操作が検出されたファイルコンテキストを再利用できるため、反復的な開発ワークフローのパフォーマンスが大幅に向上します。

エラーハンドリングとトラブルシューティング

一般的な問題

  • Gitリポジトリが見つかりません:標準除外を使用したディレクトリトラバーサルにフォールバック
  • バイナリファイル検出:拡張子ベースとコンテンツベースの両方のバイナリ検出を使用
  • トークン制限超過:インテリジェントなバッチ処理を実装し、明確なエラーメッセージを提供
  • ネットワークタイムアウト:一時的な障害に対する指数バックオフによる自動再試行

エラーカテゴリ

  • 検証エラー:無効なセッションID、タスクの説明の欠落、または無効なプロジェクトディレクトリ
  • ワークフローエラー:詳細なコンテキストと再試行の提案を含む段階固有の失敗
  • 請求エラー:アクション可能なガイダンス付きの不十分なクレジットまたは支払い失敗
  • システムエラー:ファイルシステムアクセス、gitコマンドの失敗、またはメモリ制約

デバッグツール

ワークフローは包括的なロギング、パフォーマンスメトリックのエクスポート、段階情報、再試行回数、トラブルシューティング用の中間データを含む詳細なエラーコンテキストを提供します。

ワークフロー状態管理

状態遷移

ワークフローは明確に定義された状態を経て進行します:作成済み→実行中→一時停止(オプション)→完了/失敗/キャンセル。各状態遷移は、リアルタイム更新のために監視できるイベントを公開します。

中間データストレージ

各段階は、ディレクトリツリーコンテンツ、正規表現パターン、フィルタリングされたファイルリスト、パス修正結果を含む構造化された中間データ形式で出力を保存します。このデータはデバッグのためにアクセス可能であり、特定の段階からワークフローを再開するために使用できます。

イベント駆動の更新

システムは、ワークフローステータスの変更、段階の完了、エラー条件に対してリアルタイムイベントを公開します。これらのイベントにより、応答性の高いユーザーインターフェースと外部監視システムとの統合が可能になります。

デスクトップアプリが必要ですか?

ファイル検出ワークフローは、実装計画とターミナルセッションとともにデスクトップクライアント内で実行されます。

ファイル検出ワークフロー - PlanToCode