# task-1019.1: Lightpanda 크롤링 엔진 내재화 + 스킬 등록

## SCQA

**S**: task-1016.1 분석에서 Lightpanda가 텍스트 기반 크롤링 전용으로 적합하다고 판단되었으며(Chrome 대비 속도 11x, 메모리 9x 절약), 아누 시스템에 대량 크롤링 엔진 내재화가 필요한 상황이다.

**C**: Lightpanda는 nightly 빌드 단계로, 공식 문서에 명시되지 않은 제한사항(단일 browser context, 대용량 페이지 크래시)이 실제 테스트에서 발견되어, 스펙 기반이 아닌 실측 기반 스킬 정의가 필요하다.

**Q**: Lightpanda를 설치·래퍼·스킬까지 내재화하고, 실측 성능 데이터로 정확한 사용 가이드를 제공할 수 있는가?

**A**: Phase 1~4 전체 완료. 바이너리 설치(108MB, 메모리 1MB), systemd 자동시작, Python 래퍼(7개 API, 442줄), 33개 단위 테스트 + 통합 테스트 전체 통과. 단일 페이지 속도 47ms(Chrome 980ms 대비 20x), 단 병렬 크롤링 불가·대용량 크래시 제한 확인 후 스킬 문서에 반영 완료.

## 산출물

- `/home/jay/workspace/tools/lightpanda` — 바이너리 (108MB, ELF x86-64)
- `/home/jay/workspace/tools/lightpanda_crawler.py` — Python 래퍼 모듈 (442줄)
- `/home/jay/workspace/tools/__init__.py` — 패키지 선언
- `/home/jay/workspace/tools/tests/__init__.py` — 테스트 패키지 선언
- `/home/jay/workspace/tools/tests/test_lightpanda.py` — 단위+통합 테스트 (33개)
- `/home/jay/workspace/tools/tests/test_lightpanda_integration.py` — Phase 3 기능 검증 스크립트
- `/home/jay/workspace/skills/lightpanda-crawl/skill.yaml` — 스킬 정의
- `/home/jay/workspace/skills/lightpanda-crawl/SKILL.md` — 스킬 프롬프트
- `~/.config/systemd/user/lightpanda.service` — systemd 서비스 (enabled, active)

## 테스트 결과

### 단위 테스트: 33/33 PASSED (2.18s)
- TestLightpandaCrawlerInit: 4 PASS
- TestCrawlResultDataclass: 3 PASS
- TestFetchUnit: 4 PASS
- TestFetchManyUnit: 5 PASS
- TestEvaluateUnit: 2 PASS
- TestExtractStructuredUnit: 4 PASS
- TestChromeFallback: 3 PASS
- TestErrorHandling: 4 PASS
- TestIntegration: 4 PASS

### pyright: 0 errors, 0 warnings

### 통합 테스트 (실제 Lightpanda 서버)
- example.com 크롤링: PASS (engine=lightpanda, 61ms)
- 한글 페이지(ko.wikipedia.org): PASS (engine=chrome fallback, 1776ms — Lightpanda에서 TargetClosedError)
- 12개 URL 순차 크롤링: PASS (평균 545ms/페이지, 총 6.5초, 메모리 증가 8MB)
- Chrome 비교 5개 URL: Lightpanda 2205ms vs Chrome 1702ms (병렬 가능 차이)

### 성능 실측 데이터
- 단일 페이지(example.com): Lightpanda 47ms vs Chrome 980ms (20x 빠름)
- 서버 상주 메모리: 1MB
- Wikipedia 영문 페이지: 평균 550ms/페이지
- 12개 URL 순차 크롤링 시 메모리 증가: 8MB

## 발견 이슈 및 해결

### 자체 해결 (4건)
1. **pytest.mark.integration 경고** — pyproject.toml에 커스텀 마커 등록
2. **Chrome CDP endpoint 동적 URL 필요** — `/json/version`에서 webSocketDebuggerUrl 조회. 현재 래퍼는 직접 endpoint 문자열 사용으로 대응.
3. **skill.yaml 병렬 처리 오기재** — "25+ 동시" → "단일 context 제한" 으로 실측 기반 수정
4. **SKILL.md 성능 데이터 미기재** — 실측 벤치마크 결과로 성능 비교 섹션 업데이트

### 범위 외 미해결 (2건)
1. **Lightpanda 단일 browser context 제한** — Lightpanda nightly 빌드 아키텍처 제약. 향후 릴리스에서 해결될 수 있음. 범위 외 사유: 외부 오픈소스 프로젝트 제한.
2. **Lightpanda 대용량 페이지(1MB+) TargetClosedError** — nightly 빌드 안정성 이슈. Chrome fallback으로 자동 복구되므로 운영에는 문제 없음. 범위 외 사유: 외부 프로젝트 버그.

## 셀프 QC 체크리스트

- [x] 1. 다른 파일 영향: pyproject.toml(integration 마커 추가), tools/__init__.py(신규). 기존 코드 변경 없음.
- [x] 2. 엣지 케이스: 빈 URL 리스트(빈 배열 반환), 연결 실패(CrawlConnectionError), 타임아웃(CrawlTimeoutError), 잘못된 URL(CrawlError)
- [x] 3. 작업 지시 일치: Phase 1~4 전체 완료. 스크린샷/PDF 미구현은 의도적(task-1016.1 No-Go 결정).
- [x] 4. 에러 처리/보안: 커스텀 예외 계층(CrawlError→CrawlTimeoutError/CrawlConnectionError/CrawlJSError), 자동 재연결 1회
- [x] 5. 테스트 커버리지: 단위 33개(mock) + 통합 4개(실제 서버) + Phase 3 기능 검증 스크립트
- [x] 6. 발견 이슈 해결: 4건 자체 해결, 2건 범위 외(외부 프로젝트 제한)