파일 검색 워크플로우
작업 실행을 위해 관련 파일을 식별하고 필터링하는 5단계 AI 워크플로우에 대한 포괄적인 기술 가이드입니다.
PlanToCode는 플랜을 세우거나 명령을 실행하기 전에 올바른 파일을 식별합니다. 5단계 워크플로우는 범위를 좁히고 컨텍스트를 밀접하게 유지합니다.
워크플로우 아키텍처
워크플로우는 순차적으로 실행되는 5개의 별개 단계를 가진 오케스트레이션된 백그라운드 작업 시스템으로 작동합니다. 각 단계는 이전 단계의 출력을 기반으로 하여 작업 요구 사항에 따라 파일 선택을 점진적으로 개선합니다.
시스템은 각 단계가 독립적인 백그라운드 작업으로 실행되는 분산 작업 아키텍처를 사용하여 취소, 재시도 논리 및 상세한 진행 상황 추적을 가능하게 합니다. 실시간 이벤트는 실행 전반에 걸쳐 게시되어 사용자 인터페이스에 즉각적인 피드백을 제공합니다.
주요 아키텍처 기능:
- • WebSocket과 같은 업데이트를 통한 이벤트 기반 진행 보고
- • 자동 재시도 메커니즘을 갖춘 포괄적인 오류 처리
- • AI 작업을 위한 비용 추적 및 시간 초과 관리
- • 성능 최적화를 위한 중간 결과 캐싱
- • 디렉터리 탐색으로 폴백하는 Git 통합
5단계 워크플로우 프로세스
1단계: 루트 폴더 선택
프로젝트 루트 디렉터리를 결정하고 git 저장소 상태를 검증합니다. 이 단계는 모든 후속 파일 작업의 기본 디렉터리를 설정하고 제외 패턴을 구성합니다.
2단계: 정규식 파일 필터
작업 설명을 기반으로 지능형 정규식 패턴을 생성하여 초기 파일 필터링을 수행합니다. 이 단계는 git ls-files 출력과 바이너리 파일 감지를 결합하여 예비 파일 목록을 생성합니다.
3단계: AI 파일 관련성 평가
AI 모델을 사용하여 파일 콘텐츠를 분석하고 특정 작업 설명과의 관련성을 평가합니다. 이 단계는 주어진 작업에 가장 유용할 가능성이 높은 파일을 식별하기 위해 심층 콘텐츠 분석을 수행합니다.
4단계: 확장 경로 찾기
관계 분석 및 종속성 추적을 통해 추가 관련 파일을 발견합니다. 이 단계는 초기 패턴과 일치하지 않을 수 있지만 맥락적으로 중요한 파일을 식별합니다.
구성 옵션
워크플로우 구성
시간 초과 관리
무한 중단을 방지하기 위해 전체 워크플로우 또는 개별 단계의 최대 실행 시간을 구성합니다.
timeoutMs: 300000 // 5 minutes default제외 패턴
검색 프로세스에서 제외할 디렉터리 및 파일 패턴을 정의합니다.
excludedPaths: ["node_modules", ".git", "dist", "build"]재시도 구성
지수 백오프를 사용하여 실패한 단계에 대한 최대 재시도 횟수를 설정합니다.
maxRetries: 3 // Per stage retry limitAPI 사용 예제
워크플로우 시작
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 명령 실패 또는 메모리 제약
디버깅 도구
워크플로우는 포괄적인 로깅, 성능 메트릭 내보내기 및 문제 해결을 위한 단계 정보, 재시도 시도 및 중간 데이터를 포함한 상세한 오류 컨텍스트를 제공합니다.
워크플로우 상태 관리
상태 전환
워크플로우는 명확하게 정의된 상태를 거쳐 진행됩니다: 생성됨 → 실행 중 → 일시 중지됨(선택 사항) → 완료됨/실패함/취소됨. 각 상태 전환은 실시간 업데이트를 위해 모니터링할 수 있는 이벤트를 게시합니다.
중간 데이터 저장
각 단계는 디렉터리 트리 콘텐츠, 정규식 패턴, 필터링된 파일 목록 및 경로 수정 결과를 포함하는 구조화된 중간 데이터 형식으로 출력을 저장합니다. 이 데이터는 디버깅을 위해 액세스할 수 있으며 특정 단계에서 워크플로우를 재개하는 데 사용할 수 있습니다.
이벤트 기반 업데이트
시스템은 워크플로우 상태 변경, 단계 완료 및 오류 조건에 대한 실시간 이벤트를 게시합니다. 이러한 이벤트는 반응형 사용자 인터페이스와 외부 모니터링 시스템과의 통합을 가능하게 합니다.
데스크톱 앱이 필요하신가요?
파일 검색 워크플로우는 구현 계획 및 터미널 세션과 함께 데스크톱 클라이언트 내에서 실행됩니다.