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

## 목표
Lightpanda 헤드리스 브라우저를 아누 시스템에 내재화한다.
대량 크롤링 전용 엔진으로 설치·래퍼 모듈·스킬 정의까지 완료한다.
(어떤 에이전트/팀이 담당할지 매칭은 보류 — 스킬만 정의)

## 배경
- task-1016.1 분석 결과: 스크린샷 No-Go, **텍스트 기반 크롤링 전용 Go**
- Chrome 대비 속도 11배, 메모리 9배 절약
- Playwright CDP 호환 (connect_over_cdp)
- 향후 인슈로 기능에 대량 크롤링 필요 예정

## 작업 범위

### Phase 1: 설치 및 기동

1. **바이너리 설치**
   ```bash
   curl -L -o /home/jay/workspace/tools/lightpanda \
     https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux
   chmod a+x /home/jay/workspace/tools/lightpanda
   ```

2. **systemd user service 등록** (자동 시작)
   ```ini
   # ~/.config/systemd/user/lightpanda.service
   [Unit]
   Description=Lightpanda CDP Server

   [Service]
   ExecStart=/home/jay/workspace/tools/lightpanda serve --host 127.0.0.1 --port 9333
   Restart=on-failure
   Environment=LIGHTPANDA_DISABLE_TELEMETRY=true

   [Install]
   WantedBy=default.target
   ```
   - 포트 9333 사용 (기존 Chrome 원격 디버깅 9222와 충돌 방지)

3. **기동 확인**
   ```bash
   curl -s http://127.0.0.1:9333/json/version
   ```

### Phase 2: Python 래퍼 모듈

`/home/jay/workspace/tools/lightpanda_crawler.py` 작성:

```python
"""Lightpanda 크롤링 래퍼 — 텍스트 기반 대량 크롤링 전용

사용법:
    from tools.lightpanda_crawler import LightpandaCrawler

    async with LightpandaCrawler() as crawler:
        result = await crawler.fetch("https://example.com")
        # result.title, result.text, result.html, result.links

        results = await crawler.fetch_many(urls, concurrency=25)
"""
```

핵심 기능:
1. **`fetch(url)`** — 단일 페이지 크롤링 (title, text, html, links, meta 반환)
2. **`fetch_many(urls, concurrency=25)`** — 대량 병렬 크롤링
3. **`evaluate(url, js_code)`** — JS 실행 후 결과 반환
4. **`extract_structured(url, selectors: dict)`** — CSS 셀렉터 기반 구조화 추출
5. **CDP 연결 관리** — connect_over_cdp, 자동 재연결
6. **Chrome fallback** — Lightpanda 연결 실패 시 Chrome headless로 자동 전환
7. **에러 핸들링** — 타임아웃, 연결 끊김, JS 에러 등

주의:
- **screenshot(), pdf() 메서드 없음** — 의도적 미구현 (Lightpanda 미지원이므로)
- docstring에 "스크린샷이 필요하면 Playwright+Chrome 사용" 명시

### Phase 3: 기능 검증 테스트

1. **기본 테스트** — example.com 크롤링, 한글 페이지 크롤링
2. **네이버 호환성** — 네이버 검색결과 텍스트 추출 (evaluate로 DOM 파싱)
3. **대량 테스트** — 50+ URL 병렬 크롤링, 메모리/속도 측정
4. **Chrome 비교** — 동일 작업을 Chrome headless로 실행, 성능 비교 리포트

### Phase 4: 스킬 정의 및 등록

`/home/jay/workspace/skills/lightpanda-crawl/` 디렉토리 생성:

```yaml
# skill.yaml
name: lightpanda-crawl
description: |
  Lightpanda 기반 초고속 대량 크롤링.
  Chrome 대비 11배 빠르고 9배 메모리 절약.
  텍스트/DOM 기반 크롤링 전용 (스크린샷 불가).
triggers:
  - 대량 크롤링
  - 웹 크롤링
  - 텍스트 추출
  - DOM 파싱
  - 병렬 크롤링
capabilities:
  - 단일/대량 페이지 크롤링
  - JS 실행 후 데이터 추출
  - CSS 셀렉터 기반 구조화 추출
  - 병렬 처리 (25+ 동시)
limitations:
  - 스크린샷 불가 (렌더링 엔진 없음)
  - PDF 생성 불가
  - 뷰포트/UA 커스텀 불가
  - Cloudflare Turnstile 차단됨
  - 복잡 SPA 부분적 미지원
agent: TBD  # 담당 에이전트 매칭 보류
```

스킬 프롬프트 파일도 작성:
```markdown
# lightpanda-crawl.md
대량 크롤링 시 사용하는 스킬.
래퍼 모듈: /home/jay/workspace/tools/lightpanda_crawler.py
CDP 엔드포인트: ws://127.0.0.1:9333
사용 예시, 주의사항, Chrome fallback 설명 포함.
```

## 산출물
- `/home/jay/workspace/tools/lightpanda` — 바이너리
- `/home/jay/workspace/tools/lightpanda_crawler.py` — Python 래퍼
- `/home/jay/workspace/tools/tests/test_lightpanda.py` — 테스트
- `/home/jay/workspace/skills/lightpanda-crawl/` — 스킬 정의
- `~/.config/systemd/user/lightpanda.service` — systemd 서비스
- `memory/reports/task-1019.1.md` — 설치·테스트 결과 보고서

## 주의사항
- 포트 9333 사용 (9222 충돌 방지)
- AGPL-3.0 라이선스 — 내부 사용 OK, SaaS 제공 시 소스 공개 의무
- **에이전트 담당 매칭은 보류** — 스킬 정의만 해두고 agent 필드는 TBD
- 텔레메트리 비활성화 (`LIGHTPANDA_DISABLE_TELEMETRY=true`)

## 한정승인 범위
- Phase 1~4 전체 팀장 자율 진행