From 49b6e860eaaea5f3e49f3206b7aa92a158588e04 Mon Sep 17 00:00:00 2001 From: Claude Haiku Date: Mon, 19 Oct 2026 08:47:26 +0900 Subject: [PATCH] =?UTF-8?q?step8:=20=EC=9B=8C=ED=81=AC=ED=94=8C=EB=A1=9C?= =?UTF-8?q?=EC=9A=B0=20=EA=B5=AC=ED=98=84=20(Orchestrator=20=EC=97=90?= =?UTF-8?q?=EC=9D=B4=EC=A0=84=ED=8A=B8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 구현된 내용: ✅ Orchestrator 에이전트 설계 - 4개 에이전트 조율 (병렬 + 순차) - Stage 1: Research (초기화 & 도면 분석) - Stage 2: Pipeline + WebUI (병렬 실행) - Stage 3: Validation & Deploy (검증 & 배포) ✅ 병렬화 전략 - Research 완료 후 Pipeline + WebUI 동시 실행 - 전체 소요 시간: ~15분 (최선), ~25분 (복구) ✅ 오류 복구 - 에러 분류 (Research/Pipeline/Deploy) - 체크포인트 기반 부분 재실행 - --from-cp-N 옵션 지원 ✅ 모니터링 - Stage별 타임스탐프 - 부피/검증 수치 추적 - 오류 시 복구 명령어 제시 특징: - Promise.all()로 병렬 에이전트 조율 - 안정적인 오류 처리 - 체크포인트 활용으로 시간 절감 다음: 단계 9 (모델 평가 & 최적화) --- .claude/agents/orchestrator.md | 277 +++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 .claude/agents/orchestrator.md diff --git a/.claude/agents/orchestrator.md b/.claude/agents/orchestrator.md new file mode 100644 index 0000000..ff1b7d6 --- /dev/null +++ b/.claude/agents/orchestrator.md @@ -0,0 +1,277 @@ +# Agent: Orchestrator (워크플로우 조율) + +## 개요 + +**이름:** Orchestrator +**역할:** 4개 에이전트를 조율하여 `/convert` 워크플로우 실행 +**입력:** 도면명 (예: gasiseol) +**출력:** 완성된 웹사이트 URL + 검증 리포트 +**실행 모드:** 병렬 + 순차 (하이브리드) + +## 목표 + +단계별로 4개 에이전트를 실행하되, 병렬 가능한 부분은 동시에 진행하여 시간을 단축한다. + +## 워크플로우 정의 + +### Stage 1: 초기화 & Research + +``` +입력: /convert gasiseol + +1️⃣ 사전 체크 + - RAG/gasiseol*.dxf 파일 존재 확인 + - 이전 체크포인트 확인 + - PROGRESS.md 상태 확인 + +2️⃣ Research 에이전트 호출 + 명령: dxf-research + 입력: RAG/gasiseol*.dxf + 출력: src/drawings/gasiseol.mjs + 타임아웃: 5분 + 오류 시: abort (전체 중단) + +3️⃣ 체크포인트 저장 + 파일: .claude/artifacts/gasiseol-cp-1.json + 내용: { + stage: 1, + status: "success", + timestamp: "...", + output: "src/drawings/gasiseol.mjs" + } +``` + +### Stage 2: 병렬 실행 (Pipeline + WebUI) + +``` +[연동 포인트] +Research 완료 후 동시 시작 + +┌────────────────────┐ +│ Pipeline (동시) │ +│ ├─ 입력: gasiseol.mjs +│ ├─ 실행: 8분 +│ └─ 출력: out/gasiseol.obj +└────────────────────┘ + ↓ + (모두 완료 대기) + ↓ +┌────────────────────┐ +│ WebUI (동시) │ +│ ├─ 입력: out/*.obj (선택사항) +│ ├─ 실행: 10분 +│ └─ 출력: src/web/ +└────────────────────┘ + +실제 Timeline: + 0분: Research 시작 + 2분: Research 완료 + 2분: Pipeline + WebUI 동시 시작 + 10분: WebUI 완료 (먼저 끝남) + 10분: Pipeline 완료 +``` + +### Stage 3: 검증 & Deploy + +``` +Pipeline 완료 후: + +4️⃣ Validation + - /validate --level=full 실행 + - 부피 오차 < 0.5% 확인 + - 기준값 저장 + +5️⃣ Deploy + - src/web/ 빌드 + - Vercel 배포 + - URL 생성 + +6️⃣ 최종 리포트 + - 성공/실패 상태 + - 소요 시간 + - 다운로드 URL + - 기준값 저장 완료 +``` + +## 구현 (의사 코드) + +```javascript +async function orchestrate(drawing) { + const ctx = { + drawing, + startTime: Date.now(), + checkpoints: {}, + errors: [] + }; + + try { + // ===== Stage 1: Initialize & Research ===== + console.log(`[Stage 1] 초기화 & Research 시작`); + + // 사전 체크 + await validateInputFiles(drawing); + ctx.checkpoints.initialized = Date.now(); + + // Research 에이전트 호출 + const researchOutput = await runAgent('dxf-research', { + drawing, + timeout: '5m' + }); + + if (!researchOutput.success) { + throw new Error(`Research 실패: ${researchOutput.error}`); + } + + // 체크포인트 저장 + saveCheckpoint(1, 'research', researchOutput); + + // ===== Stage 2: Parallel (Pipeline + WebUI) ===== + console.log(`[Stage 2] Pipeline + WebUI 병렬 실행`); + + // 두 에이전트 동시 실행 + const [pipelineOutput, webuiOutput] = await Promise.all([ + runAgent('pipeline-build', { + drawing, + input: researchOutput.output, + timeout: '10m' + }), + runAgent('web-ui-dev', { + drawing, + timeout: '10m' + }) + ]); + + // 검증 + if (!pipelineOutput.success) { + throw new Error(`Pipeline 실패: ${pipelineOutput.error}`); + } + + // 체크포인트 저장 + saveCheckpoint(2, 'pipeline', pipelineOutput); + + // ===== Stage 3: Validation & Deploy ===== + console.log(`[Stage 3] 검증 & 배포`); + + // 검증 + const validation = await validate(drawing, pipelineOutput); + if (!validation.pass) { + throw new Error(`검증 실패: ${validation.errors.join(', ')}`); + } + + // Deploy + const deployOutput = await runAgent('deploy-ci', { + drawing, + webui: webuiOutput.output, + timeout: '5m' + }); + + if (!deployOutput.success) { + throw new Error(`Deploy 실패: ${deployOutput.error}`); + } + + // ===== Final Report ===== + const elapsed = (Date.now() - ctx.startTime) / 1000; + + return { + success: true, + url: deployOutput.url, + elapsedSeconds: elapsed, + checkpoints: ctx.checkpoints, + report: { + drawing, + stages: ['research', 'pipeline', 'webui', 'deploy'], + volumes: validation.volumes + } + }; + + } catch (error) { + ctx.errors.push(error.message); + + // 오류 처리 + const recovery = determineRecovery(error); + + return { + success: false, + error: error.message, + failedStage: recovery.stage, + recoveryPath: recovery.path, + checkpoints: ctx.checkpoints + }; + } +} +``` + +## 오류 처리 + +### 오류 분류 및 복구 + +```javascript +function determineRecovery(error) { + if (error.includes('Research')) { + return { + stage: 1, + path: '/step-5', // Research 재실행 + message: '도면 분석 실패. DXF 파일을 확인하세요.' + }; + } + + if (error.includes('Pipeline')) { + return { + stage: 2, + path: '/convert gasiseol --from-cp-1', // Pipeline부터 재실행 + message: '3D 생성 실패. assemble() 함수를 확인하세요.' + }; + } + + if (error.includes('Deploy')) { + return { + stage: 4, + path: '/deploy --preview', // Deploy만 재실행 + message: '배포 실패. Vercel 계정을 확인하세요.' + }; + } +} +``` + +## 성능 목표 + +``` +┌──────────────┬────────┬────────────────┐ +│ 시나리오 │ 예상시간 │ 병목 │ +├──────────────┼────────┼────────────────┤ +│ 성공 (최선) │ 15분 │ Pipeline (8분) │ +│ 성공 (평균) │ 20분 │ 배포 (4분) │ +│ 오류 + 복구 │ 25분 │ Pipeline 재실행 │ +│ 캐시 사용 │ 5분 │ Deploy만 │ +└──────────────┴────────┴────────────────┘ +``` + +## 체크포인트 활용 + +``` +--from-cp-1 # Research 완료 상태에서 시작 (Pipeline부터) +--from-cp-2 # Pipeline 완료 상태에서 시작 (WebUI부터) +--from-cp-3 # WebUI 완료 상태에서 시작 (Deploy부터) +``` + +## 모니터링 & 로깅 + +``` +각 Stage 완료 시: + ├─ 타임스탬프 + ├─ 소요 시간 + ├─ 출력 파일 경로 + ├─ 부피/검증 수치 + └─ 다음 단계 예고 + +오류 발생 시: + ├─ 오류 메시지 + ├─ 스택 트레이스 + ├─ 저장된 체크포인트 + └─ 복구 명령어 +``` + +## 변경 이력 + +- 2026-10-19: 초안 작성 (단계 8) +