# Scrapling 심층분석 + 크롤링 스킬 고도화 방안

> task-570.1 산출물 | 분석일: 2026-03-15 | 분석자: 오딘(dev2팀장)

---

## 1. Scrapling 전체 구조 분석

### 1.1 프로젝트 개요
- **버전**: 0.4.2 (Beta)
- **Python**: 3.10+
- **핵심 의존성**: lxml, cssselect, orjson, tld, w3lib
- **선택 의존성**: curl_cffi, playwright, patchright, browserforge, mcp, anyio

### 1.2 아키텍처

```
scrapling/
├── parser.py               # 핵심 파싱 엔진 (Selector, Selectors)
├── __init__.py              # Lazy import 기반 공개 API
├── cli.py                   # Click 기반 CLI (install/shell/mcp/extract)
├── core/
│   ├── custom_types.py      # TextHandler, TextHandlers, AttributesHandler
│   ├── mixins.py            # SelectorsGeneration (CSS/XPath 자동 생성)
│   ├── translator.py        # CSS → XPath 변환 (::text, ::attr 확장)
│   ├── storage.py           # SQLite 기반 Smart Matching 저장소
│   ├── ai.py                # MCP 서버 (FastMCP, 6개 도구)
│   ├── shell.py             # IPython 대화형 셸 + Convertor
│   ├── _types.py            # 타입 정의
│   └── utils/
│       ├── _utils.py        # 로깅, _StorageTools (요소 fingerprinting)
│       └── _shell.py        # CurlParser (DevTools curl 명령어 파서)
├── fetchers/
│   ├── requests.py          # Fetcher/AsyncFetcher (curl_cffi 기반)
│   ├── chrome.py            # DynamicFetcher (Playwright)
│   └── stealth_chrome.py    # StealthyFetcher (Patchright + 안티봇)
├── engines/
│   ├── static.py            # FetcherSession 팩토리 (동기/비동기 겸용)
│   ├── constants.py         # STEALTH_ARGS (38개), HARMFUL_ARGS
│   ├── _browsers/
│   │   ├── _base.py         # SyncSession/AsyncSession 추상 클래스
│   │   ├── _controllers.py  # DynamicSession 구현체
│   │   ├── _stealth.py      # StealthySession + Cloudflare 솔버
│   │   ├── _page.py         # PagePool (탭 풀 관리)
│   │   ├── _validators.py   # msgspec 기반 설정 검증
│   │   └── _config_tools.py # browserforge UA 생성
│   └── toolbelt/
│       ├── custom.py        # Response(Selector 상속), BaseFetcher
│       ├── convertor.py     # ResponseFactory (3종 소스 → Response 통합)
│       ├── fingerprints.py  # browserforge 헤더 생성
│       ├── navigation.py    # 리소스 차단, 프록시 변환
│       └── proxy_rotation.py # ProxyRotator (스레드 안전, 전략 패턴)
└── spiders/
    ├── spider.py            # Spider ABC (크롤링 프레임워크)
    ├── session.py           # SessionManager (다중 세션 관리)
    ├── engine.py            # CrawlerEngine (anyio 기반 병렬 크롤링)
    ├── scheduler.py         # PriorityQueue + SHA-1 중복 필터
    ├── checkpoint.py        # pickle 기반 체크포인트/재시작
    ├── request.py           # Request 타입 (지문, 콜백, 메타데이터)
    └── result.py            # CrawlResult, CrawlStats, ItemList
```

### 1.3 Fetcher 계층 구조

```
BaseFetcher (engines/toolbelt/custom.py)
├── Fetcher          (curl_cffi, HTTP only, 가장 빠름)
├── AsyncFetcher     (curl_cffi, async HTTP)
├── DynamicFetcher   (Playwright, JS 렌더링)
└── StealthyFetcher  (Patchright, 안티봇 우회)

Session 계층 (컨텍스트 매니저):
├── FetcherSession       (동기/비동기 겸용, HTTP)
├── DynamicSession       (Playwright 브라우저)
├── AsyncDynamicSession  (Playwright async)
├── StealthySession      (Patchright 스텔스)
└── AsyncStealthySession (Patchright async)
```

---

## 2. 핵심 기능 심층 분석

### 2.1 Adaptor 시스템: 3단계 Fetcher 차이

| 항목 | Fetcher | DynamicFetcher | StealthyFetcher |
|------|---------|----------------|-----------------|
| 엔진 | curl_cffi | Playwright (Chromium) | Patchright (Chromium 포크) |
| JS 실행 | 불가 | 가능 | 가능 |
| TLS 핑거프린트 위장 | 있음 (impersonate) | 없음 | 없음 |
| 브라우저 핑거프린트 | 없음 | 부분적 (UA만) | 완전 (38개 플래그) |
| Cloudflare 솔버 | 없음 | 없음 | 있음 |
| 속도 | 최고 | 중간 | 최저 |
| 세션 관리 | FetcherSession | DynamicSession | StealthySession |
| Async 지원 | AsyncFetcher | AsyncDynamicSession | AsyncStealthySession |
| 프록시 로테이션 | 있음 | 있음 | 있음 |
| 재시도 | retries=3, delay=1s | 있음 | 있음 |

### 2.2 Smart Matching (자동 매칭) - 핵심 혁신 기능

**목적**: 웹사이트 구조가 변경되어도 이전에 저장한 요소를 자동으로 다시 찾아냄

**플로우**:
```
1단계: 최초 크롤링 (auto_save=True)
  page.css(".price", auto_save=True)
  → XPath 실행 → 요소 발견
  → element_to_dict() → fingerprint 생성 (tag, attributes, text, path, parent, siblings, children)
  → SQLiteStorageSystem.save() → SQLite에 JSON 저장

2단계: 구조 변경 후 재크롤링 (adaptive=True)
  page.css(".price", adaptive=True)
  → XPath 실행 → 실패 (선택자 무효화)
  → SQLiteStorageSystem.retrieve() → 이전 fingerprint 조회
  → relocate() → 전체 DOM 트리 순회
  → __calculate_similarity_score() → 다차원 유사도 계산
  → 최고 점수 요소 반환 (percentage 임계값 적용)
```

**유사도 계산 알고리즘** (difflib.SequenceMatcher 기반):
- 태그명 일치 (0/1점)
- 텍스트 유사도 (0.0~1.0)
- 전체 속성 딕셔너리 유사도 (키 50% + 값 50%)
- 핵심 속성 개별 유사도 (class, id, href, src)
- DOM 경로 유사도 (루트부터의 태그 경로 튜플)
- 부모 요소 유사도 (태그명, 속성, 텍스트)
- 형제 요소 유사도
- → 모든 점수 합산 / 실제 체크 수 = 0~100% 정규화

**find_similar()**: AutoScraper에서 영감. 현재 요소와 같은 깊이/구조의 유사 요소를 페이지 내에서 탐색. 상품 목록에서 하나를 기준으로 나머지를 자동 발견하는 용도.

### 2.3 안티봇 우회 기법

#### (1) TLS 핑거프린트 위장 (Fetcher)
- `curl_cffi`: libcurl 바인딩으로 JA3/JA4 핑거프린트를 Chrome/Firefox/Edge와 동일하게 위장
- `impersonate="chrome"` 파라미터로 브라우저 선택
- 일반 Python requests는 Python TLS 스택을 사용하므로 즉시 탐지됨

#### (2) Patchright 브라우저 (StealthyFetcher)
- Playwright 포크, `navigator.webdriver` 등 수십 개 탐지 포인트 패치
- 코드 한 줄 차이로 playwright↔patchright 교체 가능

#### (3) STEALTH_ARGS (38개 Chrome 플래그)
- `--disable-blink-features=AutomationControlled`: WebDriver 탐지 차단
- `--fingerprinting-canvas-image-data-noise`: Canvas fingerprinting 노이즈 주입
- `--webrtc-ip-handling-policy=disable_non_proxied_udp`: WebRTC IP 누출 차단
- `--blink-settings=primaryHoverType=2,primaryPointerType=4`: 마우스 포인터 타입 위장
- `--enable-features=TrustTokens`: Cloudflare 신뢰 토큰 활성화

#### (4) HARMFUL_ARGS 제거
- Playwright가 기본 추가하는 `--enable-automation` 등을 `ignore_default_args`로 제거

#### (5) browserforge 헤더 생성
- OS별 실제 Chrome 버전 User-Agent 생성
- HTTP 모드: Chrome/Firefox/Edge 랜덤 혼합
- 브라우저 모드: 실행 중인 Chromium과 일치하는 헤더만

#### (6) Cloudflare 자동 솔버
- 4가지 Challenge 타입 탐지: non-interactive, managed, interactive, embedded
- non-interactive: `<title>Just a moment...</title>` polling
- managed/interactive: Turnstile iframe 탐지 + 실제 마우스 클릭 (좌표 랜덤화)
- embedded: Shadow DOM 내부 `#cf_turnstile div` 클릭
- 자동 타임아웃 60초 상향

#### (7) 추가 스텔스 옵션
- `color_scheme: "dark"` + `device_scale_factor: 2` (Retina 위장)
- `screen/viewport: 1920x1080` (데스크탑 표준)
- Google Referer 자동 주입
- WebGL: 기본 활성화 (비활성화하면 오히려 탐지됨)
- ⚠️ **보안 경고**: 이 기법들은 사이트 ToS 위반 가능. 합법적 용도에만 사용

### 2.4 성능 최적화

#### 파싱 성능
- lxml 기반 HTML 파싱 (BeautifulSoup 대비 수배 빠름)
- `__slots__` 사용으로 메모리/속도 최적화
- 지연 초기화: tag/text/attrib는 처음 접근 시에만 계산
- 사전 컴파일된 XPath (`XPath(".//*")` 등)
- `@lru_cache`로 CSS→XPath 변환 결과 캐싱 (256개)
- `orjson`으로 JSON 직렬화 (표준 json 대비 수배 빠름)

#### 네트워크 성능
- 리소스 차단: 이미지/폰트/미디어 등 불필요 리소스 abort
- PagePool: 최대 50개 탭 동시 사용 (비동기)
- download_delay: 도메인별 요청 간격 제어
- CapacityLimiter: 전역/도메인별 이중 동시성 제어

#### 벤치마크 비교 대상 (benchmarks.py)
- Raw lxml, BeautifulSoup4 (lxml/html5lib), PyQuery, Parsel, MechanicalSoup, Selectolax, AutoScraper
- 측정: CPU 시간 기준 (process_time), 5000개 요소 CSS 셀렉트
- Scrapling은 lxml과 거의 동일한 속도 (같은 파서 사용), BS4보다 수배 빠름

### 2.5 Spider 시스템 (자동 크롤링 프레임워크)

- **Spider ABC**: start_urls, parse() 추상메서드, 훅 시스템 (on_start/on_close/on_error)
- **SessionManager**: 다중 세션 등록 (HTTP/브라우저/스텔스 동시 사용), Lazy 초기화
- **Scheduler**: PriorityQueue + SHA-1 중복 필터, dont_filter 옵션
- **CrawlerEngine**: anyio TaskGroup 기반 병렬 크롤링, 전역/도메인별 동시성 제어
- **Checkpoint**: pickle 기반 체크포인트, 5분 주기 자동 저장, Ctrl+C 우아한 정지
- **결과**: CrawlResult(stats, items), JSON/JSONL 내보내기

### 2.6 Storage/캐싱

- SQLite WAL 모드 (동시 읽기/쓰기)
- `@lru_cache(1)`로 싱글턴 패턴
- RLock으로 스레드 안전
- 도메인 단위 저장 (같은 사이트의 다른 페이지에서도 fingerprint 재사용)
- `INSERT OR REPLACE`로 자동 갱신

### 2.7 MCP/AI 통합

- FastMCP 기반 6개 도구: get, bulk_get, fetch, bulk_fetch, stealthy_fetch, bulk_stealthy_fetch
- 콘텐츠 변환: markdown/html/text
- 노이즈 제거: script/style/noscript/svg 태그 자동 제거
- stdio/streamable-http 전송 모드

---

## 3. 우리 시스템 대비 분석

### 3.1 현재 우리 크롤링 도구

**browser.py** (184 lines):
- Playwright CDP 래퍼 CLI
- 기능: navigate, click, type, scroll, screenshot, eval, close
- 세션 관리: PID 파일 기반 단일 Chrome 인스턴스
- 안티봇 우회: 없음
- 재시도: 없음
- 프록시: 없음

**WebFetch** (Claude Code 내장):
- URL → AI 모델로 처리
- HTML → markdown 변환
- 읽기 전용, 상호작용 불가
- 15분 캐시
- 리다이렉트 시 수동 재요청 필요

### 3.2 비교 분석표

| 기능 | browser.py | WebFetch | Scrapling |
|------|-----------|----------|-----------|
| **기본 탐색** | 있음 | 있음 | 있음 |
| **JS 렌더링** | 있음 | 없음 | 있음 (Dynamic/Stealthy) |
| **HTML 파싱** | 없음 | AI 처리 | lxml 기반 고속 파싱 |
| **CSS/XPath 셀렉터** | 없음 | 없음 | 있음 (Scrapy 호환) |
| **안티봇 우회** | 없음 | 없음 | 3단계 (TLS/Browser/Stealth) |
| **TLS 핑거프린트** | Python 기본 | 모름 | curl_cffi (Chrome 위장) |
| **navigator.webdriver** | True (탐지됨) | N/A | Patchright로 제거 |
| **Cloudflare 우회** | 불가 | 불가 | 자동 솔버 |
| **프록시 지원** | 없음 | 없음 | ProxyRotator (전략 패턴) |
| **재시도** | 없음 | 없음 | 자동 (3회, 프록시 교체) |
| **리소스 차단** | 없음 | 없음 | 이미지/폰트/미디어 차단 |
| **병렬 처리** | 단일 탭 | 단일 요청 | PagePool (최대 50탭) |
| **세션 유지** | PID 파일 | 15분 캐시 | 컨텍스트 매니저 |
| **Smart Matching** | 없음 | 없음 | 유사도 기반 요소 재탐색 |
| **Spider 프레임워크** | 없음 | 없음 | 완전한 크롤링 프레임워크 |
| **체크포인트/재시작** | 없음 | 없음 | pickle 기반 자동 저장 |
| **MCP 서버** | 없음 | 없음 | FastMCP 6개 도구 |
| **대화형 셸** | 없음 | 없음 | IPython + curl 파서 |
| **마크다운 변환** | 없음 | 있음 | markdownify 기반 |
| **데이터 추출 API** | eval (JS) | AI 추출 | TextHandler 체이닝 |

### 3.3 Scrapling이 우리보다 뛰어난 점

1. **안티봇 우회**: 3단계 방어(TLS/Browser/Stealth) vs 우리는 0단계
2. **HTML 파싱**: lxml 기반 고속 파서 + CSS/XPath 셀렉터 vs 우리는 파싱 기능 없음
3. **Smart Matching**: 구조 변경에 강인한 요소 탐색 vs 우리는 수동 셀렉터만
4. **프록시/재시도**: 자동 프록시 로테이션 + 재시도 vs 우리는 수동
5. **Spider 프레임워크**: Scrapy급 크롤링 자동화 vs 우리는 수동 스크립트
6. **병렬 처리**: 최대 50탭 동시 + 도메인별 동시성 vs 우리는 단일 탭
7. **MCP 통합**: AI 에이전트가 직접 크롤링 도구 호출 가능

### 3.4 도입하면 안 되는 기능 (리스크)

| 기능 | 리스크 | 판단 |
|------|--------|------|
| Cloudflare 솔버 | 사이트 ToS 위반, 법적 리스크 | ⚠️ 합법적 용도에만 제한적 사용 |
| Canvas/WebRTC 우회 | 과도한 핑거프린트 위장은 감지 시 영구 차단 | ⚠️ 필요 시에만 선택적 활성화 |
| patchright 의존 | Playwright 포크, 업데이트 지연 가능 | ⚠️ 핵심 의존성으로 채택 시 유지보수 부담 |
| curl_cffi | C 라이브러리 의존, 빌드 이슈 가능 | △ 설치 환경 제약 확인 필요 |
| browserforge | 외부 서비스 의존도 확인 필요 | △ 오프라인 사용 가능 여부 확인 |

---

## 4. 전체 도입 가능 목록

### 4.1 파싱/데이터 추출 (Priority: HIGH)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| P-1 | lxml 기반 HTML 파싱 | BS4 대비 3-10x 빠른 파싱 | 중 | 대규모 크롤링 시 필수 | Scrapling 직접 사용 또는 핵심 파서 차용 |
| P-2 | CSS/XPath 셀렉터 | `.css(".price::text")` 방식 데이터 추출 | 중 | 코드 가독성 + 생산성 대폭 향상 | Scrapling 직접 사용 권장 |
| P-3 | TextHandler 체이닝 | `text.clean().re(pattern).json()` | 하 | 데이터 후처리 편의성 | 핵심 기법 차용 가능 |
| P-4 | ::text, ::attr() 의사요소 | Scrapy 호환 CSS 확장 | 하 | 기존 Scrapy 코드 이식 용이 | translator.py 차용 |
| P-5 | 마크다운 변환 | HTML → Markdown (노이즈 태그 제거) | 하 | LLM 입력 최적화 | Convertor 클래스 차용 |
| P-6 | find_similar() | 유사 요소 자동 탐색 (상품 목록 등) | 중 | 반복 구조 데이터 추출 자동화 | Scrapling 직접 사용 |

### 4.2 안티봇/스텔스 (Priority: HIGH)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| A-1 | STEALTH_ARGS 적용 | 38개 Chrome 플래그로 자동화 탐지 차단 | 하 | browser.py 봇 탐지 즉시 개선 | constants.py에서 플래그 목록 차용 |
| A-2 | HARMFUL_ARGS 제거 | Playwright 기본 플래그 중 탐지 유발 플래그 제거 | 하 | A-1과 함께 적용 시 효과 극대화 | ignore_default_args 설정 추가 |
| A-3 | browserforge 헤더 생성 | OS별 실제 Chrome UA + Accept-Language | 하 | User-Agent 탐지 방지 | browserforge 라이브러리 직접 사용 |
| A-4 | Google Referer 자동 주입 | 검색 엔진에서 온 것처럼 위장 | 하 | Referer 기반 차단 우회 | 단순 코드 추가 |
| A-5 | TLS 핑거프린트 위장 (curl_cffi) | JA3/JA4 핑거프린트를 Chrome으로 | 중 | HTTP 전용 크롤링 시 탐지 방지 | curl_cffi 도입 (pip install) |
| A-6 | Canvas fingerprint 노이즈 | 픽셀 데이터에 랜덤 노이즈 주입 | 하 | Canvas 기반 봇 탐지 우회 | Chrome 플래그 추가 |
| A-7 | WebRTC IP 누출 차단 | 프록시 환경 로컬 IP 숨김 | 하 | 프록시 사용 시 필수 | Chrome 플래그 추가 |
| A-8 | init_script 주입 | 페이지 로드 전 JS 실행 (webdriver 속성 숨김 등) | 하 | 탐지 코드보다 먼저 실행 | add_init_script API 활용 |

### 4.3 리소스 최적화 (Priority: MEDIUM)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| R-1 | 리소스 차단 | 이미지/폰트/미디어/CSS 로딩 차단 | 하 | 페이지 로딩 50-80% 단축 | route 인터셉트 핸들러 추가 |
| R-2 | 도메인 차단 | 특정 도메인 요청 차단 (광고/트래커) | 하 | 불필요 네트워크 감소 | R-1과 동일 메커니즘 |
| R-3 | PagePool (탭 풀) | 다중 탭 동시 사용 + 슬롯 관리 | 중 | 병렬 크롤링 속도 향상 | _page.py 설계 차용 |
| R-4 | viewport/screen 최적화 | 1920x1080 + Retina 시뮬레이션 | 하 | 봇 탐지 회피 + 렌더링 정확도 | 설정값 변경만으로 적용 |

### 4.4 네트워크/세션 관리 (Priority: MEDIUM)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| N-1 | 프록시 로테이션 | ProxyRotator + 전략 패턴 | 중 | IP 차단 회피 | proxy_rotation.py 차용 |
| N-2 | 자동 재시도 | 실패 시 프록시 교체 + 재시도 (3회) | 하 | 안정성 향상 | 재시도 루프 구현 |
| N-3 | 프록시 에러 판별 | 프록시 오류 vs 일반 오류 구분 | 하 | 정확한 재시도 판단 | is_proxy_error() 차용 |
| N-4 | Response 이력 추적 | 리다이렉트 체인 전체 보존 | 하 | 디버깅 + 분석 편의 | convertor.py 패턴 차용 |
| N-5 | 세션 팩토리 패턴 | 동기/비동기 겸용 컨텍스트 매니저 | 중 | API 일관성 | FetcherSession 설계 참조 |

### 4.5 Smart Matching (Priority: MEDIUM-HIGH)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| S-1 | 요소 fingerprinting | tag/attributes/path/parent/siblings 저장 | 중 | Smart Matching 기반 | _StorageTools 차용 |
| S-2 | SQLite 저장소 | WAL 모드, RLock, 싱글턴 | 중 | fingerprint 영속 저장 | storage.py 차용 |
| S-3 | 유사도 기반 재탐색 | SequenceMatcher 다차원 비교 | 상 | 구조 변경에 강인한 크롤링 | relocate() 알고리즘 차용 |
| S-4 | auto_save/adaptive 모드 | 저장/검색 자동화 | 중 | 사용자 코드 최소화 | Scrapling 직접 사용 권장 |

### 4.6 Spider/크롤링 자동화 (Priority: MEDIUM)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| SP-1 | Spider ABC | start_urls + parse() 콜백 패턴 | 중 | Scrapy급 크롤링 자동화 | Scrapling 직접 사용 |
| SP-2 | Scheduler (우선순위 큐) | PriorityQueue + SHA-1 중복 필터 | 중 | URL 중복 방지 + 우선순위 제어 | scheduler.py 차용 |
| SP-3 | Checkpoint/재시작 | pickle 기반 자동 저장 + 복원 | 중 | 대규모 크롤링 내결함성 | checkpoint.py 차용 |
| SP-4 | 병렬 크롤링 엔진 | anyio TaskGroup + CapacityLimiter | 상 | 크롤링 속도 대폭 향상 | engine.py 참조 |
| SP-5 | 도메인별 동시성 제어 | per-domain rate limiting | 중 | 예의 바른 크롤링 | CapacityLimiter 차용 |
| SP-6 | 결과 내보내기 | JSON/JSONL 자동 저장 | 하 | 데이터 파이프라인 연동 | ItemList 차용 |

### 4.7 AI/개발자 경험 (Priority: LOW-MEDIUM)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| D-1 | MCP 서버 | Claude 등 AI 에이전트가 크롤링 도구 호출 | 중 | AI 에이전트 크롤링 자동화 | Scrapling MCP 직접 활용 가능 |
| D-2 | curl 파서 | DevTools curl 명령어 → Fetcher 인자 변환 | 하 | 디버깅 시 즉시 재현 가능 | CurlParser 차용 |
| D-3 | IPython 대화형 셸 | 크롤링 실험/디버깅 | 하 | 개발 생산성 | shell.py 참조 |
| D-4 | CLI 도구 | install/extract/mcp 명령어 | 중 | 비개발자도 사용 가능 | cli.py 참조 |
| D-5 | Lazy Import | 필요한 클래스만 지연 로딩 | 하 | 임포트 시간 단축 | __init__.py 패턴 차용 |

### 4.8 Cloudflare/WAF 우회 (Priority: CONDITIONAL)

| # | 기능 | 설명 | 난이도 | 예상 효과 | 구현 방향 |
|---|------|------|--------|-----------|-----------|
| C-1 | Cloudflare 솔버 | 4타입 Challenge 자동 해결 | 상 | CF 보호 사이트 접근 가능 | ⚠️ Scrapling 직접 사용, 합법적 용도만 |
| C-2 | Turnstile 클릭 자동화 | iframe 탐지 + 좌표 랜덤 클릭 | 상 | 인터랙티브 Challenge 해결 | ⚠️ _stealth.py 차용, 법적 검토 필요 |

---

## 5. 스킬 고도화 설계

### 5.1 전략 결정: Scrapling 직접 사용 vs 핵심 기법 차용

| 시나리오 | 추천 전략 | 이유 |
|---------|----------|------|
| 보험 데이터 정기 크롤링 | **Scrapling 직접 사용** | Spider + Smart Matching + 세션 관리 모두 필요 |
| 단일 페이지 데이터 추출 | **핵심 기법 차용** (A-1~A-4 + P-2) | browser.py에 스텔스 플래그만 추가하면 충분 |
| Cloudflare 보호 사이트 | **Scrapling 직접 사용** (StealthyFetcher) | 자체 구현은 유지보수 부담 큼 |
| AI 에이전트 크롤링 | **Scrapling MCP 활용** | 이미 완성된 MCP 서버 존재 |

### 5.2 기존 browser.py 확장 (즉시 적용 가능)

browser.py에 다음을 추가하여 즉시 탐지 회피 개선:

```python
# 1. STEALTH_ARGS 적용
STEALTH_ARGS = [
    "--disable-blink-features=AutomationControlled",
    "--fingerprinting-canvas-image-data-noise",
    "--lang=en-US",
    "--accept-lang=en-US",
    ...  # constants.py에서 38개 가져옴
]

# 2. HARMFUL_ARGS 제거
# Playwright launch 시 ignore_default_args 사용

# 3. 리소스 차단
# page.route("**/*", handler) 추가

# 4. User-Agent 교체
# browserforge로 실제 Chrome UA 생성
```

### 5.3 새 스크립트 필요 여부

| 스크립트 | 필요 여부 | 용도 |
|---------|----------|------|
| browser.py 확장 | 수정 | 스텔스 플래그 + 리소스 차단 추가 |
| 새 크롤링 스킬 SKILL.md | 신규 | Scrapling 기반 크롤링 스킬 정의 |
| scraping_utils.py | 선택 | 프록시 로테이션, fingerprint 유틸리티 |

### 5.4 크롤링 스킬 초안 (SKILL.md)

```yaml
name: advanced-crawling
description: Scrapling 기반 고급 웹 크롤링 스킬
triggers:
  - 웹 크롤링, 스크래핑
  - 안티봇, Cloudflare 우회
  - 데이터 추출, 보험 데이터
  - Smart Matching, 자동 매칭

capabilities:
  - 3단계 Fetcher: HTTP(Fetcher) → 브라우저(Dynamic) → 스텔스(Stealthy)
  - Smart Matching: 구조 변경 시 자동 요소 재탐색
  - 프록시 로테이션 + 자동 재시도
  - 리소스 차단 (이미지/폰트/미디어)
  - CSS/XPath 셀렉터 + TextHandler 체이닝
  - Spider 프레임워크 (자동 크롤링)
  - Checkpoint/재시작 (대규모 크롤링)

usage_guide:
  1. pip install scrapling[all]
  2. scrapling install (Chromium + TLD DB)
  3. 단순 HTTP: Fetcher.get(url)
  4. JS 렌더링: DynamicFetcher.fetch(url)
  5. 안티봇 우회: StealthyFetcher.fetch(url, solve_cloudflare=True)
  6. 자동 크롤링: Spider 상속 + parse() 구현
```

### 5.5 로드맵

| Phase | 내용 | 예상 소요 | 의존성 |
|-------|------|----------|--------|
| Phase 1 | browser.py 스텔스 강화 (A-1~A-4, R-1) | 반나절 | 없음 |
| Phase 2 | Scrapling 설치 + 스킬 SKILL.md 작성 | 반나절 | Phase 1 |
| Phase 3 | Smart Matching 활용 보험 크롤러 프로토타입 | 1일 | Phase 2 |
| Phase 4 | Spider 기반 정기 크롤링 시스템 구축 | 1-2일 | Phase 3 |
| Phase 5 | MCP 서버 통합 (AI 에이전트 크롤링) | 반나절 | Phase 2 |

---

## 부록: 코드 규모 참고

| 모듈 | 주요 파일 | 대략적 라인 수 |
|------|----------|--------------|
| Parser | parser.py | ~1,100 |
| Custom Types | custom_types.py | ~380 |
| Storage | storage.py | ~150 |
| Smart Matching | parser.py (relocate, similarity) | ~200 |
| Fetcher Sessions | static.py | ~770 |
| Browser Base | _base.py | ~535 |
| Browser Controllers | _controllers.py | ~357 |
| Stealth | _stealth.py, constants.py | ~300 |
| Validators | _validators.py | ~230 |
| Spider | spider.py, engine.py | ~600 |
| Scheduler | scheduler.py | ~120 |
| Checkpoint | checkpoint.py | ~100 |
| Toolbelt (전체) | 5개 파일 | ~400 |
| AI/MCP | ai.py | ~200 |
| Shell | shell.py | ~350 |
| CLI | cli.py | ~300 |
| **합계** | | **~6,000+** |