883 lines
27 KiB
Markdown
883 lines
27 KiB
Markdown
|
# 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<string, string>;
|
||
|
|
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는 “브라우저로 세상을 안정적으로 관찰하고 증거를 남기는 엔진”으로 쓰고, 범용 온톨로지 플랫폼은 그 위에서 “관찰을 지식 그래프로 바꾸는 시스템”으로 설계하는 것이 가장 현실적이다.
|