# Playwright 분석 및 기능명세 작성일: 2026-05-13 분석 대상: `C:\Users\lasta\MyProject\AI\참고\playwright-main` 프로젝트 성격: Microsoft Playwright 원본 모노레포 계열, Apache-2.0 라이선스 ## 1. 요약 Playwright는 Chromium, Firefox, WebKit을 단일 API로 제어하는 브라우저 자동화 프레임워크다. 이 저장소는 단순 웹 크롤러가 아니라 다음 요소를 모두 포함한 대형 플랫폼이다. - 브라우저 실행 및 원격 제어 런타임 - 브라우저 컨텍스트, 페이지, 프레임, 네트워크, 입력, 다운로드, 쿠키, 저장소 API - E2E 테스트 러너와 fixture, worker, reporter, assertion 체계 - 브라우저 세션 추적, 스크린샷, 비디오, HAR, trace viewer - 코드 생성기, recorder, inspector, HTML reporter - MCP/CLI 기반 AI agent용 브라우저 조작 도구 - 브라우저별 패치와 배포 패키지 구성 범용 온톨로지 구축 플랫폼 관점에서 가장 가치 있는 부분은 테스트 러너 자체보다 `playwright-core`의 브라우저 자동화 계층, 네트워크/DOM/접근성 스냅샷 수집 계층, trace/HAR 증거화 계층, MCP/CLI 도구 계층이다. 사이트 탐색, 구조화 정보 추출, 출처 증거 보존, 동적 웹 페이지 처리, 로그인 세션 재사용, 수집 품질 검증에 거의 그대로 사용할 수 있다. ## 2. 저장소 구조 주요 루트 디렉터리: - `packages`: 실제 제품 패키지와 런타임 소스 - `packages/playwright-core`: 브라우저 자동화 핵심 - `packages/playwright`: 테스트 러너, CLI, reporter, worker, fixture - `packages/trace-viewer`: trace zip 시각화 UI - `packages/html-reporter`: 테스트 결과/실행 결과 HTML 리포트 UI - `packages/recorder`: 코드 생성/recording 관련 UI 및 로직 - `packages/dashboard`: Playwright CLI 세션 모니터링 대시보드 - `docs`: 공식 문서 원본 - `tests`: 브라우저, 테스트 러너, MCP, 컴포넌트 테스트 등 검증 코드 - `utils`: 빌드, 타입 생성, 문서 lint, 브라우저 롤링, 패키징 도구 - `browser_patches`: 브라우저별 패치 관리 패키지 목록 중 중요 항목: - `playwright-core`: 브라우저 제어 엔진. 플랫폼에서 직접 재사용할 최우선 후보. - `playwright`: test runner와 reporter. 플랫폼 내부 검증 자동화나 수집 시나리오 검증에 선택적으로 사용. - `playwright-client`: 클라이언트 번들. - `protocol`: client-server channel protocol 정의. - `injected`: 브라우저 페이지 안에 주입되는 selector, locator, utility 스크립트. - `trace`, `trace-viewer`: 실행 증거, DOM snapshot, network, console, screenshot을 재생/분석. - `html-reporter`: 실행 결과 UI. - `recorder`: 사용자 행동을 자동화 코드로 변환. - `playwright-ct-*`: React/Vue 컴포넌트 테스트. 온톨로지 플랫폼에는 직접 우선순위 낮음. - `playwright-browser-*`, `playwright-chromium/firefox/webkit`: 브라우저별 배포 패키지. ## 3. 기술 스택 - 언어: TypeScript, JavaScript - 런타임: Node.js `>=18` - 패키지 구조: npm workspaces - 빌드: 자체 `utils/build/build.js`, esbuild, TypeScript - UI: React 기반 trace viewer, html reporter, dashboard - 통신: WebSocket, pipe transport, CDP, WebDriver BiDi, 자체 channel protocol - schema/agent tool: `zod`, `@modelcontextprotocol/sdk` - 라이선스: Apache-2.0 ## 4. 핵심 아키텍처 Playwright의 핵심 구조는 server/client/protocol로 나뉜다. ### 4.1 Server 계층 위치: `packages/playwright-core/src/server` Server 계층은 실제 브라우저 프로세스를 띄우고, 브라우저별 프로토콜을 다루며, 페이지/프레임/네트워크/입력/저장소 같은 고수준 객체를 제공한다. 핵심 파일: - `playwright.ts`: Chromium, Firefox, WebKit, Electron, Android 객체를 생성하는 루트 객체. - `browserType.ts`: 브라우저 launch/connect/persistent context 진입점. - `browser.ts`: 브라우저 연결과 context 생명주기. - `browserContext.ts`: 독립 세션, 쿠키, 권한, 라우팅, tracing, storage state. - `page.ts`: 페이지 단위 조작과 이벤트. - `frames.ts`: frame navigation, lifecycle, DOM interaction. - `network.ts`: request/response, routing, headers, timing. - `fetch.ts`: API request context. - `selectors.ts`, `frameSelectors.ts`, `dom.ts`: locator/selector 기반 DOM 조작. - `screenshotter.ts`, `videoRecorder.ts`, `trace`: 증거 수집. - `chromium`, `firefox`, `webkit`, `bidi`: 브라우저별 protocol adapter. - `dispatchers`: server 객체를 channel protocol로 노출. 온톨로지 플랫폼 재사용 포인트: - 동적 페이지 렌더링 후 본문/링크/메타데이터 추출 - SPA, 무한 스크롤, 로그인 뒤 페이지 수집 - request/response 기반 원천 URL, MIME, redirect, status 기록 - DOM snapshot, screenshot, video, trace를 출처 증거로 보존 - 브라우저 context 단위 격리로 사이트별 정책/쿠키/세션 분리 ### 4.2 Client 계층 위치: `packages/playwright-core/src/client` Client 계층은 사용자가 보는 API 객체다. `Playwright`, `BrowserType`, `Browser`, `BrowserContext`, `Page`, `Locator`, `Frame`, `Request`, `Response` 등이 channel protocol 위에서 동작한다. 핵심 파일: - `playwright.ts`: client-side 루트 객체와 브라우저 타입 접근. - `browserType.ts`: `launch`, `connect`, `launchPersistentContext`. - `browser.ts`: browser/context 관리. - `browserContext.ts`: 쿠키, route, tracing, storage state. - `page.ts`: navigation, screenshot, PDF, event, locator. - `locator.ts`: 안정적인 DOM 대상 지정. - `network.ts`: request/response 모델. - `tracing.ts`: trace start/stop. - `fetch.ts`: APIRequestContext. 온톨로지 플랫폼에서는 이 client API를 감싸는 `BrowserAcquisitionService` 또는 `WebEvidenceCollector`를 두는 것이 적합하다. 원본 API를 변경하지 않고 domain workflow만 추가하면 유지보수가 쉽다. ### 4.3 Protocol/Dispatcher 계층 위치: - `packages/playwright-core/src/protocol` - `packages/playwright-core/src/server/dispatchers` - `packages/protocol` Server 객체와 client 객체 사이의 메시지 계약이다. 브라우저 객체를 직접 넘기지 않고 channel owner/dispatcher로 추상화한다. 재사용 의미: - 장기적으로 Python/FastAPI 백엔드와 Node Playwright worker를 분리할 때 이 구조를 참고할 수 있다. - 온톨로지 플랫폼의 “수집 작업 서버”도 command/event protocol로 설계하면 browser worker를 독립 프로세스로 운용하기 쉽다. ### 4.4 Injected 계층 위치: `packages/injected` 브라우저 페이지 내부에 주입되어 selector, locator, accessibility 기반 검색, DOM 조작 보조를 수행한다. Playwright의 강점인 auto-wait와 locator 안정성은 이 계층과 server/client 조합에서 나온다. 온톨로지 플랫폼 재사용 포인트: - 단순 CSS selector보다 안정적인 요소 선택 - accessible role/name 기반 탐색 - 클릭/입력 전 요소 actionability 확인 - 의미 있는 DOM 후보 추출의 기반 ### 4.5 Tools/MCP/CLI 계층 위치: `packages/playwright-core/src/tools` AI agent와 CLI가 브라우저를 조작할 수 있게 도구 단위로 기능을 쪼갠 계층이다. 주요 하위 디렉터리: - `backend`: 실제 브라우저 조작 tool 구현 - `mcp`: Model Context Protocol 서버 및 브라우저 모델 - `cli-client`: command-line agent client - `cli-daemon`: browser session daemon - `dashboard`: 실행 중인 browser session 시각화 - `trace`: trace 분석용 CLI `backend/tools.ts`는 다음 도구 묶음을 등록한다. - navigation - screenshot - snapshot - form - keyboard/mouse - network/route - cookies/storage/webstorage - evaluate/runCode - pdf/video/tracing - tabs/dialogs/files/devtools - verify/wait/console 온톨로지 플랫폼에서 매우 중요하다. “LLM이 브라우저를 조작해 정보원을 탐색하고, 구조화 데이터를 추출하고, 증거를 남기는” 기능을 만들 때 이 도구 계층을 거의 그대로 감싸서 사용할 수 있다. ## 5. 주요 기능 분석 ### 5.1 브라우저 자동화 기능: - Chromium, Firefox, WebKit 실행 - headless/headed 모드 - browser context 격리 - persistent context 지원 - proxy, geolocation, timezone, locale, permissions, viewport, user agent 설정 - page/frame navigation - click, fill, type, press, hover, drag 등 입력 자동화 - dialog, download, file chooser 처리 온톨로지 플랫폼 적용: - 동적 문서 페이지 렌더링 - 검색 엔진/사이트 내 검색 자동화 - 페이지 내 탭, 필터, 페이지네이션 탐색 - 로그인 필요 지식베이스 접근 - 사이트별 수집 프로파일 구성 ### 5.2 Locator와 auto-wait 기능: - `getByRole`, `getByText`, `getByLabel`, `getByPlaceholder`, `getByTestId` - CSS/XPath selector - element actionability 자동 대기 - assertion retry - strict locator 정책 적용: - 사이트 UI가 느리게 로딩되어도 수집 안정성 확보 - 관리자 콘솔/문서 포털/검색 UI 자동화 - DOM 변화가 잦은 사이트에서 selector 취약성 감소 ### 5.3 네트워크 관찰 및 제어 기능: - request/response 이벤트 - route interception - HAR recording/replay - header/cookie/postData/status/timing 접근 - APIRequestContext - WebSocket route 일부 지원 적용: - 수집 문서의 원천 URL, redirect chain, status code, content-type 저장 - JSON API가 노출되는 사이트에서 DOM 대신 API 응답 직접 추출 - 크롤링 금지/인증 오류/레이트리밋 감지 - 동일 URL 재수집 시 변경 여부 판단 ### 5.4 스냅샷, 스크린샷, 비디오, trace 기능: - screenshot - video recording - trace start/stop - DOM snapshot - console/network/action timeline 기록 - trace viewer UI 적용: - 온톨로지 엔티티/관계 추출의 근거 보존 - LLM 추출 결과 검수 화면 제공 - “왜 이 관계가 생성되었는가”를 클릭 가능한 증거로 제시 - 수집 실패 재현 및 디버깅 ### 5.5 PDF와 문서화 기능: - Chromium 기반 `page.pdf` - screenshot 기반 시각 증거 적용: - 웹 문서를 PDF evidence artifact로 저장 - 온톨로지 버전별 출처 snapshot 생성 ### 5.6 테스트 러너 위치: `packages/playwright/src` 기능: - test/expect API - fixture - parallel worker - retry, timeout, shard - project matrix - reporter: list, line, dot, json, junit, html, blob, github - webServer plugin - watch/UI mode 온톨로지 플랫폼에서는 제품 테스트뿐 아니라 “수집 recipe 검증”에 사용할 수 있다. 예를 들어 특정 사이트 수집 recipe가 정상적으로 title/body/date/source evidence를 얻는지 Playwright Test로 검증할 수 있다. ### 5.7 Recorder와 codegen 기능: - 브라우저 조작을 코드로 생성 - selector 후보 생성 - 사용자의 실제 클릭/입력을 시나리오로 변환 적용: - 비개발자가 사이트 수집 절차를 녹화해 recipe 초안 생성 - 수집 자동화 script를 빠르게 제작 - 로그인, 검색, 필터, 다운로드 흐름을 저장 ### 5.8 MCP와 AI Agent 브라우저 조작 기능: - MCP server 제공 - 접근성 tree/snapshot 기반 agent interaction - navigation, click, type, screenshot, network, storage 등 tool schema - extension/CDP relay 구조 일부 포함 적용: - LLM 기반 웹 탐색 agent - 온톨로지 후보 개념/관계 발견을 위한 반자동 탐색 - 사람이 지시한 목표를 브라우저 조작 task로 변환 - “페이지에서 제품군/속성/관계 후보를 찾아라” 같은 agent workflow ### 5.9 Reporter와 Viewer 기능: - HTML reporter - trace viewer - timeline, action list, network tab, console tab, snapshot tab - test result drill-down 적용: - 수집 작업 리포트 UI의 기본 소스로 사용 가능 - 추출 품질, 실패 URL, 에러, 네트워크 로그, 스크린샷을 한 화면에서 검토 - provenance/evidence viewer 구현 참고 ## 6. 범용 온톨로지 구축 플랫폼에 필요한 기능명세 아래 명세는 Playwright 원본을 가능한 한 변형 없이 사용하고, 우리 플랫폼 계층에서 orchestration과 domain logic을 얹는 방향이다. ### 6.1 브라우저 수집 엔진 목적: 동적 웹 페이지를 안정적으로 열고, DOM/텍스트/네트워크/시각 증거를 수집한다. 기능 요구사항: - URL 단위 수집 작업 생성 - browser type 선택: chromium 기본, 필요 시 firefox/webkit - headless/headed 선택 - context 설정: viewport, locale, timezone, userAgent, proxy, geolocation, permissions - navigation timeout, action timeout 설정 - 페이지 load strategy 설정: `load`, `domcontentloaded`, `networkidle` - redirect chain 기록 - final URL 기록 - HTTP status, response headers, content-type 기록 - DOM HTML 저장 - innerText/textContent 저장 - screenshot 저장 - 선택적 PDF 저장 - 선택적 trace 저장 - console error/warning 기록 - request failure 기록 - cookie/storage state 저장 및 재사용 권장 원본 사용: - `playwright-core/src/client/page.ts` - `browserContext.ts` - `network.ts` - `tracing.ts` - `screenshotter.ts` - `fetch.ts` 플랫폼 래퍼 예시: - `BrowserAcquisitionService.collect(url, profile)` - `EvidenceBundle` - `BrowserSessionProfile` - `NetworkEvidence` - `DomEvidence` ### 6.2 사이트 탐색 및 링크 발견 목적: 온톨로지 구축에 필요한 문서/목록/상세 페이지 후보를 발견한다. 기능 요구사항: - 시작 URL seed 등록 - 동일 도메인/허용 도메인 링크 추출 - link text, href, role, bounding box, surrounding text 기록 - canonical URL 정규화 - 중복 URL 제거 - robots/policy는 플랫폼 정책 계층에서 처리 - 페이지네이션 버튼 탐색 - 검색어 기반 사이트 내부 검색 수행 - 무한 스크롤 페이지 처리 - sitemap/API endpoint 발견은 별도 모듈과 결합 권장 원본 사용: - locator - frame/page evaluate - network request observation - tools backend `navigate`, `snapshot`, `mouse`, `keyboard`, `wait` ### 6.3 구조화 추출 준비 목적: LLM/규칙 기반 추출기가 쓰기 좋은 입력을 만든다. 기능 요구사항: - 본문 후보 영역 탐지 - 제목, heading hierarchy 추출 - table/list/card 구조 추출 - form/search/filter UI 추출 - image alt/caption/source 추출 - metadata: title, description, og tags, schema.org JSON-LD 추출 - accessibility snapshot 저장 - network JSON 응답 후보 저장 - DOM path와 locator candidate 저장 권장 원본 사용: - injected selector/locator 구조 - page accessibility snapshot 계열 도구 - `snapshot` backend tool - evaluate/runCode tool 주의: - Playwright는 온톨로지 추출기가 아니다. 엔티티/관계/속성 스키마 추출은 플랫폼의 별도 AI extraction layer가 담당해야 한다. - Playwright는 “신뢰도 높은 웹 상태와 증거를 제공하는 하부 엔진”으로 두는 것이 맞다. ### 6.4 Agent 기반 웹 조사 목적: LLM이 브라우저를 조작하며 지식 후보를 찾고 검증하게 한다. 기능 요구사항: - MCP tool 목록을 플랫폼 agent에게 제공 - agent별 browser context 격리 - 세션별 action log 저장 - agent action마다 screenshot/snapshot 선택 저장 - 허용 도메인, 다운로드, 파일 업로드, 외부 이동 제한 - 사람이 중간에 개입 가능한 headed/session dashboard 제공 - agent task 결과를 evidence bundle과 연결 권장 원본 사용: - `packages/playwright-core/src/tools/backend` - `packages/playwright-core/src/tools/mcp` - `packages/playwright-core/src/tools/cli-daemon` - `packages/playwright-core/src/tools/dashboard` 플랫폼 기능명: - `AgentBrowserSession` - `BrowserToolGateway` - `AgentEvidenceRecorder` - `HumanReviewDashboard` ### 6.5 수집 Recipe 녹화 및 재생 목적: 사용자가 사이트별 수집 절차를 만들고 반복 실행한다. 기능 요구사항: - 브라우저 조작 녹화 - 생성된 locator/code 확인 - recipe step 편집 - 변수화: 검색어, 카테고리, 기간, 페이지 수 - replay 실행 - 실패 step에서 screenshot/trace 제공 - recipe version 관리 권장 원본 사용: - `packages/recorder` - `packages/playwright-core/src/server/recorder` - `packages/playwright-core/src/server/codegen` 플랫폼 Recipe 모델: - `open(url)` - `click(locator)` - `fill(locator, value)` - `press(key)` - `waitFor(condition)` - `extract(targetSpec)` - `paginate(strategy)` - `saveEvidence(policy)` ### 6.6 증거/출처 관리 목적: 온톨로지 결과의 출처와 재현성을 보장한다. 기능 요구사항: - 모든 추출 결과는 source URL과 evidence id를 가진다. - evidence bundle에는 HTML, text, screenshot, network summary, trace path를 포함한다. - relationship triple마다 근거 DOM locator 또는 text span을 연결한다. - trace viewer 또는 유사 UI에서 action/network/snapshot을 열람한다. - 재수집 시 이전 evidence와 diff한다. 권장 원본 사용: - tracing - HAR - trace viewer - html reporter UI 구조 - network events 플랫폼 데이터 모델: - `EvidenceBundle(id, url, capturedAt, browserProfile, artifacts)` - `Artifact(type, path, mime, hash)` - `ExtractionClaim(entityId, predicate, object, evidenceRefs, confidence)` - `SourceSpan(evidenceId, selector, textStart, textEnd, quote)` ### 6.7 수집 품질 검증 목적: 수집 및 추출 pipeline의 신뢰성을 자동 검증한다. 기능 요구사항: - URL 접근 성공률 - 본문 길이 최소 기준 - title/heading 존재 여부 - HTTP status allowlist - screenshot blank 여부 - 주요 selector 존재 여부 - JSON-LD/schema.org 존재 여부 - extraction output schema validation - 실패 시 retry, fallback browser, fallback wait strategy 권장 원본 사용: - Playwright Test runner - expect matcher - html reporter - trace on retry 플랫폼 기능명: - `CrawlerRecipeTest` - `EvidenceQualityGate` - `ExtractionRegressionSuite` ## 7. 재사용 우선순위 ### 1순위: 거의 그대로 사용 - npm 패키지 `playwright` 또는 `playwright-core` - browser/page/context/network/locator/tracing API - screenshot/PDF/HAR/trace 기능 - storage state 재사용 - MCP/CLI backend tool 개념 이 영역은 원본 수정 없이 wrapper를 작성하는 방식이 적합하다. ### 2순위: 일부 UI/구조 차용 - trace viewer - html reporter - dashboard - recorder/codegen 이 영역은 UI와 데이터 모델이 Playwright 테스트 중심이라 그대로 붙이기보다 “evidence viewer”, “collection report”, “recipe recorder”로 재명명하고 데이터 adapter를 두는 것이 좋다. ### 3순위: 참고만 권장 - browser patches - component test packages - browser package publishing logic - Playwright 자체 protocol generator/build system 온톨로지 플랫폼에는 과하고 유지보수 비용이 높다. ## 8. 통합 설계안 권장 구조: ```text Ontology Platform API / Job Orchestrator CollectionJob ExtractionJob ValidationJob Browser Automation Layer Playwright wrapper Browser session pool Site profile manager Agent tool gateway Evidence Layer HTML/Text/Screenshot/PDF/Trace/HAR store Evidence metadata DB Hash/version manager Extraction Layer DOM cleaner JSON-LD parser Table/list extractor LLM extractor Ontology mapper Ontology Layer Entity model Relation model Schema/versioning Graph DB adapter Review UI Evidence viewer Trace viewer adapter Extraction diff Human validation workflow ``` Playwright는 `Browser Automation Layer`와 `Evidence Layer`의 핵심 엔진으로 둔다. 온톨로지 의미 추론, 스키마 정렬, 엔티티 병합, 그래프 저장은 별도 계층으로 분리한다. ## 9. 구체 API 명세 초안 ### 9.1 CollectionProfile ```ts type CollectionProfile = { id: string; browser: 'chromium' | 'firefox' | 'webkit'; headless: boolean; viewport?: { width: number; height: number }; locale?: string; timezoneId?: string; userAgent?: string; proxy?: { server: string; username?: string; password?: string; }; permissions?: string[]; storageStatePath?: string; navigationTimeoutMs: number; actionTimeoutMs: number; trace: 'off' | 'on' | 'retain-on-failure'; screenshot: 'off' | 'page' | 'full-page'; pdf: boolean; har: boolean; }; ``` ### 9.2 CollectionJob ```ts type CollectionJob = { id: string; seeds: string[]; profileId: string; allowedDomains: string[]; maxDepth: number; maxPages: number; crawlMode: 'single-page' | 'same-domain' | 'recipe' | 'agent'; recipeId?: string; agentGoal?: string; evidencePolicy: EvidencePolicy; }; ``` ### 9.3 EvidencePolicy ```ts type EvidencePolicy = { keepHtml: boolean; keepText: boolean; keepScreenshot: boolean; keepPdf: boolean; keepTrace: boolean; keepHar: boolean; keepNetworkSummary: boolean; hashArtifacts: boolean; }; ``` ### 9.4 EvidenceBundle ```ts type EvidenceBundle = { id: string; jobId: string; url: string; finalUrl: string; capturedAt: string; status?: number; contentType?: string; title?: string; artifacts: EvidenceArtifact[]; network: NetworkEvidence[]; console: ConsoleEvidence[]; extractionInput: ExtractionInput; }; ``` ### 9.5 ExtractionInput ```ts type ExtractionInput = { title?: string; headings: Array<{ level: number; text: string; selector?: string }>; mainText: string; links: Array<{ text: string; href: string; selector?: string }>; tables: Array<{ selector?: string; rows: string[][] }>; jsonLd: unknown[]; metadata: Record; accessibilitySnapshot?: unknown; }; ``` ### 9.6 OntologyExtractionResult ```ts type OntologyExtractionResult = { evidenceBundleId: string; entities: ExtractedEntity[]; relations: ExtractedRelation[]; attributes: ExtractedAttribute[]; warnings: string[]; }; ``` ### 9.7 ExtractedEntity ```ts type ExtractedEntity = { id: string; label: string; typeCandidates: string[]; aliases: string[]; sourceRefs: SourceRef[]; confidence: number; }; ``` ### 9.8 ExtractedRelation ```ts type ExtractedRelation = { subjectId: string; predicate: string; objectIdOrValue: string; relationType: 'entity-entity' | 'entity-value'; sourceRefs: SourceRef[]; confidence: number; }; ``` ### 9.9 SourceRef ```ts type SourceRef = { evidenceBundleId: string; artifactType: 'html' | 'text' | 'screenshot' | 'pdf' | 'trace' | 'network'; selector?: string; textQuote?: string; startOffset?: number; endOffset?: number; screenshotRegion?: { x: number; y: number; width: number; height: number }; }; ``` ## 10. 주요 워크플로우 명세 ### 10.1 단일 URL 수집 1. CollectionJob 생성 2. CollectionProfile 로드 3. Playwright browser/context/page 생성 4. URL 이동 5. response/status/final URL 기록 6. DOM, text, metadata, link, JSON-LD 추출 7. screenshot/PDF/trace/HAR 저장 8. EvidenceBundle 생성 9. ExtractionInput 생성 10. Ontology extraction queue로 전달 ### 10.2 사이트 탐색 수집 1. seed URL 수집 2. 링크 후보 추출 3. URL canonicalization 및 domain filter 4. 우선순위 큐에 추가 5. maxDepth/maxPages까지 반복 6. 각 페이지 EvidenceBundle 저장 7. 중복 본문/중복 URL 제거 8. extraction batch 생성 ### 10.3 Agent 조사 1. 사용자가 조사 목표 입력 2. AgentBrowserSession 생성 3. MCP/backend tools 제공 4. agent가 navigate/search/click/snapshot 반복 5. 중요 페이지에서 evidence 저장 6. agent가 후보 entity/relation/sourceRefs 제안 7. 사람이 evidence viewer에서 검수 8. 승인된 claim만 ontology graph에 반영 ### 10.4 Recipe 생성 1. 사용자가 headed browser로 사이트 접속 2. recorder가 행동 기록 3. codegen/locator 후보 생성 4. 플랫폼 Recipe DSL로 변환 5. 변수와 반복/페이지네이션 설정 6. 샘플 실행으로 검증 7. recipe version 저장 ## 11. 변경 없이 사용 가능한 코드/개념 - Playwright npm public API - browser context isolation - locator and auto-wait - tracing API - storage state - route/network observation - screenshot/PDF - API request context - HTML reporter/trace viewer의 UI 패턴 - MCP backend tool 분해 방식 ## 12. 수정 또는 Adapter가 필요한 영역 - Playwright test result 중심 데이터 모델을 ontology evidence 중심 모델로 변환 - trace viewer를 EvidenceBundle과 연결하는 adapter - recorder output을 플랫폼 Recipe DSL로 변환 - MCP tool 권한/보안 정책 - 수집 대상 도메인 제한 - 다운로드/파일 시스템 접근 제한 - 대량 크롤링 스케줄링, 큐, retry, backpressure - robots/약관/레이트리밋 정책 ## 13. 위험요소와 주의사항 - Playwright 원본 전체를 fork해서 수정하면 유지보수 비용이 매우 커진다. - 브라우저 바이너리와 patch 관리까지 직접 들고 가는 것은 권장하지 않는다. - 크롤러 규모가 커지면 browser context/page pool 관리가 필요하다. - trace/video/screenshot은 저장소 비용이 크므로 evidence policy가 필요하다. - 로그인 세션 저장은 보안 민감 정보이므로 암호화와 접근 제어가 필요하다. - LLM agent에게 unrestricted browser tool을 주면 외부 이동/다운로드/입력 위험이 있다. - Playwright는 추출 의미론을 보장하지 않는다. 온톨로지 품질은 extraction/validation layer에서 관리해야 한다. ## 14. 구현 로드맵 ### Phase 1. Playwright 수집 래퍼 - `BrowserAcquisitionService` 작성 - 단일 URL HTML/text/screenshot/network summary 수집 - storage state 지원 - EvidenceBundle 저장 ### Phase 2. 구조화 입력 생성 - heading/link/table/jsonLd/metadata 추출 - 본문 후보 추출 - extraction input schema 고정 - 품질 gate 추가 ### Phase 3. Recipe 기반 수집 - Playwright action step DSL 정의 - recorder/codegen 연계 검토 - replay 및 실패 trace 저장 ### Phase 4. Agent 브라우저 - MCP/backend tools adapter - agent session isolation - action log/evidence 자동 연결 - 도메인/권한 policy 적용 ### Phase 5. Evidence Viewer - trace viewer 또는 유사 UI 통합 - screenshot/DOM/text/source span 연결 - relation claim 검수 화면 ## 15. 결론 이 프로젝트는 범용 온톨로지 구축 플랫폼의 “웹 기반 지식 수집 엔진”으로 매우 적합하다. 다만 원본을 플랫폼 내부로 깊게 fork하기보다, Playwright는 가능한 한 공식 API와 tool 계층을 그대로 사용하고, 우리 쪽에서 다음 계층을 추가하는 방식이 좋다. - 수집 orchestration - evidence data model - ontology extraction input normalization - LLM/규칙 기반 entity/relation extraction - graph persistence - human review workflow 즉, Playwright는 “브라우저로 세상을 안정적으로 관찰하고 증거를 남기는 엔진”으로 쓰고, 범용 온톨로지 플랫폼은 그 위에서 “관찰을 지식 그래프로 바꾸는 시스템”으로 설계하는 것이 가장 현실적이다.