Search Tools Studio (한국어)

개요

Search Tools Studio는 /dashboard/search-tools를 기본 검색 플레이그라운드에서 웹 검색, 웹 스크래핑, 공급자별 나란히 비교 기능을 통합한 3개 탭의 Studio로 전환합니다.

┌ 검색 도구 ─────────────────────────────────────────────────────────────┐
│ [🔍 검색] [📄 스크랩] [⚖ 비교]                  142ms · $0.001  </>    │
│ ⓘ [모달리티 가이드]                                                    │
├──────────────────────────────────────────┬─────────────────────────────┤
│  {활성 탭 콘텐츠}                        │ ─ 구성                      │
│                                          │ 공급자 [자동 ∨]             │
│                                          │   🟢 Serper  $0.001         │
│                                          │   🟢 Tavily  $0.008         │
│                                          │   🔥 Firecrawl (가져오기)   │
│                                          │ 유형   [웹 | 뉴스]          │
│                                          │ 전체 페이지 [ ] (스크랩)    │
│                                          │ 형식 [md|text|html]         │
│                                          │ 재순위 모델 [∨]             │
└──────────────────────────────────────────┴─────────────────────────────┘

---

탭

검색 탭

기존 SearchForm + ResultsPanel + RerankPanel을 하나의 탭으로 발전시킵니다.

• 쿼리 → 결과(제목, URL, 스니펫, 관련성 점수).
• 구성 창에 공급자 메타데이터(비용, 할당량, 상태) 표시.
• 재순위 섹션: 재순위 모델을 선택하고 결과 순서를 재정렬하며 positionDelta 표시.
• 검색 공급자가 구성되지 않은 경우 CTA가 포함된 빈 상태 표시.
• SearchHistory.tsx를 통한 검색 기록.
• POST /v1/search 호출(기존 엔드포인트, 변경 없음).

스크랩 탭

POST /v1/web/fetch(계획 05에서 생성됨)를 통해 URL에서 콘텐츠를 추출하는 새로운 탭입니다.

• 입력: URL + 전체 페이지 토글 + 형식 선택기(markdown / text / HTML).
• 제출 → 가져오기 → ScrapeResult.tsx 렌더링.
• ScrapeResult는 markdown 미리보기 + 원본 토글을 렌더링.
• 제한: 응답 본문이 256 KB를 초과하면 UI에 (잘림, 원본 보기)를 표시하고 Monaco 모달에서 원본을 엽니다(D21).
• 메타데이터 패널: 공급자(firecrawl/jina-reader/tavily-search/tinyfish/nimble-search/anysearch-search), 지연 시간, 비용, 응답 크기, 링크 수.
• useScrapeFetch.ts 훅 사용.

비교 탭

최대 4개의 공급자에서 동일한 쿼리/URL을 병렬로 실행합니다(D22).

• 공급자별로 나란히 열 표시.
• 지표: 지연 시간, 비용, 결과 수, 응답 크기.
• 검색 시 URL 중복 계산(초기 결과 대비 공유 URL 수).
• 공급자별로 POST /v1/search(검색) 또는 POST /v1/web/fetch(스크랩) 호출.

---

구성 창(공유)

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

필드	참고
공급자	상태 배지가 있는 드롭다운(구성됨 / 누락 / 요청 제한됨)
유형	web 또는 news(검색 전용)
전체 페이지	스크랩용 토글 — 처음 보이는 콘텐츠가 아닌 전체 페이지를 가져옴
형식	markdown, text 또는 html(스크랩 전용)
재순위 모델	검색 후 재순위 지정을 위한 선택적 모델
기록	접을 수 있는 검색 기록 섹션

---

SearchConceptCard

SearchConceptCard.tsx — 항상 표시되는 접을 수 있는 아코디언입니다. 다음 개념을 설명합니다:

개념	한 줄 설명
검색	웹 결과 목록(제목, URL, 스니펫, 관련성 점수)을 가져옵니다
스크레이프	URL의 전체 콘텐츠(markdown, 텍스트 또는 HTML)를 추출합니다
비교	동일한 쿼리를 N개의 프로바이더에서 나란히 실행합니다
재정렬	쿼리 관련성을 개선하기 위해 LLM을 통해 결과 순서를 재정렬합니다
자동(최저 비용)	사용 가능한 가장 저렴한 프로바이더를 자동으로 선택합니다

---

프로바이더 카탈로그

ProviderCatalog.tsx는 GET /api/search/providers에서 전체 프로바이더 목록을 제공합니다 (F4에서 가져오기 프로바이더를 포함하도록 확장됨):

| kind | "search"(20개 프로바이더) 또는 "fetch"(firecrawl, jina-reader, tavily-search, tinyfish, nimble-search, anysearch-search) |

상태는 요청 시점에 자격 증명의 존재 여부와 모든 키가 현재 쿨다운 상태인지 확인하여 동적으로 결정됩니다.

---

코드 내보내기

ExportCodeModal(Playground Studio에서 가져옴)과 codeExport.ts는 /v1/search 및 /v1/web/fetch 호출 모두에 대한 curl / Python / TypeScript 스니펫을 생성합니다. API 키 플레이스홀더는 항상 $OMNIROUTE_API_KEY입니다(D11, Playground Studio와 공유).

---

백엔드 변경 사항

이 기능에 필요한 백엔드 변경 사항은 하나뿐이었습니다:

확장된 GET /api/search/providers

src/app/api/search/providers/route.ts는 다음과 같이 확장되었습니다:

• 6개의 가져오기 프로바이더(firecrawl, jina-reader, tavily-search, tinyfish, nimble-search, anysearch-search)를 모두 배열에 포함합니다.
• 모든 항목에 kind: "search" | "fetch"를 추가합니다.
• 실시간 자격 증명 상태에서 파생된 status: "configured" | "missing" | "rate_limited"를 추가합니다.
• 이전 버전과의 호환성을 유지합니다. 기존 필드(id, name 등)는 변경되지 않습니다.

---

주요 파일

경로	용도
src/app/(dashboard)/dashboard/search-tools/SearchToolsClient.tsx	스튜디오 셸, 탭 오케스트레이터
src/app/(dashboard)/dashboard/search-tools/components/SearchToolsTopBar.tsx	탭 + 메트릭 + 내보내기 버튼
src/app/(dashboard)/dashboard/search-tools/components/SearchToolsConfigPane.tsx	공유 설정 패널
src/app/(dashboard)/dashboard/search-tools/components/SearchConceptCard.tsx	설명 카드(항상 표시)
src/app/(dashboard)/dashboard/search-tools/components/ProviderCatalog.tsx	메타데이터가 포함된 프로바이더 목록
src/app/(dashboard)/dashboard/search-tools/components/ScrapeResult.tsx	Markdown 미리보기 + 원시 데이터 전환
src/app/(dashboard)/dashboard/search-tools/components/tabs/SearchTab.tsx	검색 + 재정렬 탭
src/app/(dashboard)/dashboard/search-tools/components/tabs/ScrapeTab.tsx	스크레이프 탭
src/app/(dashboard)/dashboard/search-tools/components/tabs/CompareTab.tsx	다중 프로바이더 비교 탭
src/app/(dashboard)/dashboard/search-tools/hooks/useScrapeFetch.ts	스크레이프 가져오기 훅
src/app/api/search/providers/route.ts	kind + status + 가져오기 프로바이더를 포함하도록 확장
open-sse/config/searchRegistry.ts	검색 프로바이더 메타데이터의 단일 진실 공급원

---

문제 해결

증상	원인	해결 방법
스크레이프 탭에 “endpoint not available”이 표시됨	/v1/web/fetch가 연결되지 않음	플랜 05가 병합되었는지 확인하고 src/app/api/v1/web/fetch/route.ts가 존재하는지 확인하세요
제공자 카탈로그에 모두 “missing”으로 표시됨	자격 증명이 구성되지 않음	/dashboard/providers에서 자격 증명을 추가하세요
스크레이프 콘텐츠가 잘림	응답이 256 KB 제한을 초과함	예상된 동작입니다(D21). 전체 콘텐츠를 보려면 “view raw” 버튼을 사용하세요
비교 탭에 제공자가 2개만 표시됨	속도 제한이 적용 중임	둘 이상의 제공자가 쿨다운 상태일 수 있습니다. Config 창에서 제공자 상태를 확인하세요
테이블에 “Size”가 원시 키로 표시됨	i18n 키가 누락됨	로케일 파일에 search.size가 있는지 확인하고 i18n을 다시 빌드하세요

---

참고 자료

• 마스터 플랜: _tasks/features-v3.8.6/refactorpages/_orchestration/master-plan-group-C.md
• 기능 플랜: _tasks/features-v3.8.6/refactorpages/18-search-tools-studio-redesign.plan.md
• 검색 제공자 레지스트리: open-sse/config/searchRegistry.ts
• Playground Studio(공유 ExportCodeModal + codeExport.ts): docs/frameworks/PLAYGROUND_STUDIO.md
• 웹 가져오기 백엔드: src/app/api/v1/web/fetch/route.ts

---

OmniRoute 소스 코드 (a58000c7685f)