AI/Playwright_분석_및_기능명세.md

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