Playground Studio

개요

Playground Studio는 /dashboard/playground를 단순한 Monaco 기반 편집기에서 모든 기능을 갖춘 테스트 워크스페이스로 전환합니다. 기존 page.tsx를 네 개의 탭과 공유 구성 창을 렌더링하는 PlaygroundStudio 셸로 대체합니다.

┌ Playground ──────────────────────────────────────────────────────────┐
│ [💬 채팅] [⚖ 비교] [{} API] [🔧 빌드]        142↑ 38↓ · $0.002 </>│
├──────────────────────────────────────────┬───────────────────────────┤
│  {활성 탭 콘텐츠}                        │ ─ 구성                    │
│                                          │ 엔드포인트 [chat ∨]       │
│                                          │ 모델       [gpt-5.4 ∨]    │
│                                          │ 시스템     [텍스트 영역]  │
│                                          │ 온도       ▕▕▔▔ 0.7       │
│                                          │ 프리셋 [▾ 불러오기][저장] │
│                                          │ [✨ 프롬프트 개선]         │
└──────────────────────────────────────────┴───────────────────────────┘

탭

채팅 탭

ChatPlayground.tsx를 멀티턴 스트리밍 워크벤치로 발전시킵니다.

MarkdownMessage.tsx를 통한 완전한 마크다운 렌더링(코드 블록, 표, 목록, 링크).
공유 구성 창에서 시스템 프롬프트를 가져옵니다.
메시지별 토큰/비용(프롬프트 + 완성 토큰).
마지막 응답 다시 생성.
SSE 스트리밍을 사용하여 POST /v1/chat/completions로 전송합니다.

비교 탭

프록시의 핵심 차별점: 하나의 프롬프트를 최대 4개 모델에서 병렬로 실행합니다.

최대 4개의 열에서 각각 /v1/chat/completions의 응답을 독립적으로 스트리밍합니다.
열을 추가하는 + 모델 추가 버튼(Cmd+K 단축키).
모두 실행 ▶은 Promise.all과 열별 AbortController를 통해 모든 스트림을 동시에 시작합니다.
전역 모두 취소는 진행 중인 모든 스트림을 중단합니다.
열별 ProviderMetrics는 TTFT, TPS, 토큰 및 예상 비용을 실시간으로 표시합니다.
메트릭에는 “클라이언트 측 추정치”(D12)라는 레이블이 지정되며, 첫 번째 SSE 청크부터 측정됩니다.

API 탭

고급 사용자를 위해 기존 Monaco 편집기의 기능을 100% 유지합니다(D14).

10개 엔드포인트: 채팅 완성, 완성, 임베딩, 이미지, 오디오, 음성, 전사, 조정, 재순위 지정, 검색.
멀티모달 파일 업로드.
실시간 출력을 지원하는 SSE 스트리밍.
ApiTab.tsx로 래핑됩니다(지연 로드, ssr: false).

빌드 탭

도구/함수 호출 및 구조화된 출력 UI:

ToolsBuilder.tsx — 도구별 JSON 스키마 편집기를 사용하여 tools[]를 추가/편집/제거합니다. ToolDefinitionSchema(Zod)를 통해 매개변수를 검증합니다.
StructuredOutputEditor.tsx — JSON 모드 및 JSON 스키마 편집기를 전환합니다. StructuredOutputSchema(Zod)를 통해 응답이 스키마를 준수하는지 검증합니다.
tools[] 및/또는 response_format과 함께 요청을 /v1/chat/completions로 전송합니다.

구성 창(공유)

StudioConfigPane.tsx — 항상 표시되며 접을 수 있습니다.

필드	컴포넌트	참고
엔드포인트	`<select>`	`PlaygroundEndpoint`와 일치하는 10개 옵션
모델	`<input>`	자유 텍스트(예: `openai/gpt-4o`)
시스템 프롬프트	`<textarea>`	모든 탭에 전달됨
매개변수	`ParamSliders`	temperature, max_tokens, top_p, presence/frequency penalty, seed, stop
프리셋	`PresetPicker`	이름이 지정된 구성 스냅샷 불러오기/저장하기(DB에 영구 저장)
프롬프트 개선	`ImprovePromptButton`	할당량 경고 모달을 열고 `/api/playground/improve-prompt` 호출

상태는 PlaygroundStudio.tsx로 끌어올려져 모든 탭에 전달됩니다. 탭을 전환해도 구성 상태가 유지됩니다.

상단 바

StudioTopBar.tsx:

탭 전환기(role=“tablist”).
TokenCostCounter — 실시간 토큰(↑/↓) 및 예상 비용 표시.
코드 내보내기 버튼(</>) — ExportCodeModal을 엽니다.

코드 내보내기 모달

ExportCodeModal.tsx는 codeExport.ts를 사용하여 현재 PlaygroundState에서 curl / Python / TypeScript 스니펫을 생성합니다. API 키 자리표시자는 항상 $OMNIROUTE_API_KEY입니다(D11).

프롬프트 개선기

ImprovePromptButton.tsx → useImprovePrompt.ts → POST /api/playground/improve-prompt:

모달에서 “할당량을 소모합니다”라고 경고합니다.
확인하면 { system, prompt, model, tone }을 라우트로 전송합니다.
라우트는 내부적으로 promptImprover.META_SYSTEM_PROMPT와 함께 /v1/chat/completions를 호출합니다.
{ improvedSystem?, improvedPrompt?, tokensIn, tokensOut }을 반환합니다.
UI는 구성 창의 시스템 프롬프트와 채팅 탭의 사용자 프롬프트를 패치합니다.

프리셋

PresetPicker.tsx → usePresets.ts → /api/playground/presets/*:

playground_presets SQLite 테이블에 저장됩니다(마이그레이션 084_playground_presets.sql).
각 프리셋은 name, endpoint, model, system, params_json, created_at을 저장합니다.
CRUD: GET 목록 조회, POST 생성, GET /:id, PUT /:id, DELETE /:id.

스트림 메트릭

useStreamMetrics.ts + streamMetrics.ts(순수 함수):

start() — 요청 시작 시간을 기록합니다.
onFirstChunk() — TTFT를 기록합니다.
onChunk(n) — 완료 토큰 수를 누적합니다.
finish(usage?) — 최종 메트릭인 ttftMs, totalMs, tps, tokensIn, tokensOut, costUsd를 계산합니다.
가격 정보는 src/lib/playground/types.ts의 정적 테이블에서 가져옵니다(“estimated”로 표시 — D13).

백엔드 라우트

메서드	경로	핸들러
`POST`	`/api/playground/improve-prompt`	`ImprovePromptRequestSchema`으로 Zod 검증 후 메타 프롬프트와 함께 `/v1/chat/completions` 호출
`GET`	`/api/playground/presets`	`{ presets: PlaygroundPresetListItem[] }` 반환
`POST`	`/api/playground/presets`	프리셋 생성, `PlaygroundPresetCreateSchema` 검증
`GET`	`/api/playground/presets/:id`	프리셋 하나 또는 404 반환
`PUT`	`/api/playground/presets/:id`	부분 업데이트
`DELETE`	`/api/playground/presets/:id`	204

인증: 선택 사항(REQUIRE_API_KEY). 오류는 buildErrorBody()를 통해 처리합니다(엄격 규칙 #12).

주요 파일

경로	용도
`src/app/(dashboard)/dashboard/playground/PlaygroundStudio.tsx`	셸 컴포넌트, 탭 오케스트레이터
`src/app/(dashboard)/dashboard/playground/components/StudioTopBar.tsx`	탭 + 카운터 + 내보내기 버튼
`src/app/(dashboard)/dashboard/playground/components/StudioConfigPane.tsx`	공통 설정 패널
`src/app/(dashboard)/dashboard/playground/components/tabs/ChatTab.tsx`	채팅 워크벤치
`src/app/(dashboard)/dashboard/playground/components/tabs/CompareTab.tsx`	다중 모델 비교
`src/app/(dashboard)/dashboard/playground/components/tabs/ApiTab.tsx`	Monaco 편집기(유지)
`src/app/(dashboard)/dashboard/playground/components/tabs/BuildTab.tsx`	도구 + 구조화된 출력
`src/app/(dashboard)/dashboard/playground/components/ExportCodeModal.tsx`	코드 내보내기 모달
`src/app/(dashboard)/dashboard/playground/components/CompareColumn.tsx`	개별 비교 열
`src/app/(dashboard)/dashboard/playground/components/ProviderMetrics.tsx`	TTFT/TPS 표시
`src/app/(dashboard)/dashboard/playground/hooks/useStreamMetrics.ts`	클라이언트 측 메트릭 훅
`src/app/(dashboard)/dashboard/playground/hooks/usePresets.ts`	프리셋 CRUD 훅
`src/app/(dashboard)/dashboard/playground/hooks/useImprovePrompt.ts`	프롬프트 개선 훅
`src/lib/playground/codeExport.ts`	curl/Python/TS 생성기(Search Tools와 공유)
`src/lib/playground/promptImprover.ts`	메타 프롬프트 빌더
`src/lib/playground/streamMetrics.ts`	순수 메트릭 계산
`src/lib/db/playgroundPresets.ts`	DB 모듈(CRUD)
`src/app/api/playground/improve-prompt/route.ts`	프롬프트 개선 REST 라우트
`src/app/api/playground/presets/route.ts`	프리셋 목록 조회 + 생성
`src/app/api/playground/presets/[id]/route.ts`	프리셋 조회/업데이트/삭제
`src/lib/db/migrations/084_playground_presets.sql`	DB 마이그레이션

문제 해결

증상	원인	해결 방법
API 탭에서 Monaco 편집기가 렌더링되지 않음	SSR에서 Monaco를 로드함	`ApiTab`이 `dynamic(..., { ssr: false })`를 사용하는지 확인
비교 스트림이 순차적으로 실행됨	잘못된 `Promise.all` 사용	모든 스트림 시작 작업을 하나의 `Promise.all` 호출에서 디스패치해야 함
메트릭에 `null` TTFT가 표시됨	첫 번째 청크 핸들러가 연결되지 않음	SSE 리더 루프에서 `useStreamMetrics.onFirstChunk()`가 호출되는지 확인
프리셋이 유지되지 않음	DB 마이그레이션이 실행되지 않음	`npm run db:migrate`를 실행하거나 서버를 재시작(시작 시 마이그레이션이 자동 실행됨)
프롬프트 개선 시 502가 반환됨	Config에서 모델이 설정되지 않음	개선하기 전에 사용자가 Config 창에 모델 이름을 입력해야 함
내보낸 코드에 `MISSING_API_KEY`가 표시됨	자리표시자가 삽입되지 않음	`codeExport.ts`는 항상 `API_KEY_PLACEHOLDER = "$OMNIROUTE_API_KEY"`를 사용

참고 자료

마스터 계획: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md
기능 계획: _tasks/features-v3.8.6/refactorpages/17-playground-studio-redesign.plan.md
코드 내보내기: src/lib/playground/codeExport.ts
프롬프트 개선기: src/lib/playground/promptImprover.ts
Search Tools Studio: docs/frameworks/SEARCH_TOOLS_STUDIO.md

undefined (a58000c7685f)