lasta/AI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
939b65f0b79b9e941d50afc048dbc8e065555c55
AI/Playwright_분석_및_기능명세.md
LASTA_DEV01\lasta 9e88f4c7ad ontology
2026-05-13 19:57:34 +09:00

27 KiB
Raw Blame History

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. 통합 설계안

권장 구조:

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

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

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

type EvidencePolicy = {
  keepHtml: boolean;
  keepText: boolean;
  keepScreenshot: boolean;
  keepPdf: boolean;
  keepTrace: boolean;
  keepHar: boolean;
  keepNetworkSummary: boolean;
  hashArtifacts: boolean;
};

9.4 EvidenceBundle

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

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

type OntologyExtractionResult = {
  evidenceBundleId: string;
  entities: ExtractedEntity[];
  relations: ExtractedRelation[];
  attributes: ExtractedAttribute[];
  warnings: string[];
};

9.7 ExtractedEntity

type ExtractedEntity = {
  id: string;
  label: string;
  typeCandidates: string[];
  aliases: string[];
  sourceRefs: SourceRef[];
  confidence: number;
};

9.8 ExtractedRelation

type ExtractedRelation = {
  subjectId: string;
  predicate: string;
  objectIdOrValue: string;
  relationType: 'entity-entity' | 'entity-value';
  sourceRefs: SourceRef[];
  confidence: number;
};

9.9 SourceRef

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

Reference in New Issue View Git Blame Copy Permalink