crawl-scouter 0.8.1

Pre-scraping diagnostic tool

크롤링 스카우터 진단기

본격 크롤러를 짜기 전에, URL 하나로 그 사이트가 어떻게 수집 가능한지 진단하는 내부 도구. 설계 문서: docs/specs/크롤링_스카우터_진단기_설계_v7_확장.md

설치

pip install -e .
pip install -e ".[dev]"   # 선택: ruff/mypy 검증 시
playwright install chromium
pip install -e ".[llm]"   # 선택: --llm 실제 API 연결 시

실행

scouter --version
scouter https://example.com/
scouter https://example.com/ --json
scouter https://example.com/ --html --out report.html
scouter https://example.com/ --html --out-dir reports
scouter https://example.com/ --llm --html --out report.html
scouter https://example.com/ --agent-prompt --json
scouter https://example.com/ --ua "Mozilla/5.0 ..."

자동 저장 기본 폴더: set SCOUTER_OUTPUT_DIR=D:\reports scouter https://example.com/ --html scouter https://example.com/ --json

저장 우선순위: --out > --out-dir > SCOUTER_OUTPUT_DIR > stdout

소스 체크아웃 상태에서 직접 실행: python scouter.py https://example.com/

구성

• schemas.py : dataclass, enum, 공통 상수
• fetcher.py : HTTP 클라이언트, delay/UA, HTTP probe
• robots.py : robots.txt, sitemap 후보 검증
• detection.py : anti-bot/challenge, Unknown Mitigation, 콘텐츠 프로필
• rendering.py : framework marker, SSR/CSR 판정
• api_candidates.py : API 후보 HEAD 검증
• playwright_phase2.py : Playwright 브라우저 2단계
• llm_layer.py : 선택 LLM 해석 레이어, 입력 위생, mock/API 호출
• protocol_builder.py : 실행 프로토콜 JSON 생성, agent prompt
• report_text.py : 텍스트 리포트
• report_html.py : HTML 리포트, Best Path/Risk 로직
• scouter.py : 오케스트레이션, JSON 직렬화, CLI
• bigarray_v0_2.py : 데이터 배열 선택 점수
• extract_arrays_v0_2.py : HTML/script 배열 후보 추출
• signals_pro.py : 숨은 API·GraphQL·pagination·selector·encoding·official path 신호

문서/산출물

• docs/specs/ : 설계 명세
• docs/memos/ : 메모와 작업 지시
• docs/handover/ : 인계 기록
• QUICKSTART.md : 외부 검수자용 실행 절차
• artifacts/qa/ : QA summary
• artifacts/zips/: 검수 패키지
• reports/ : 최신 실사이트 리포트
• pyproject.toml : editable install + console entry point
• LICENSE : MIT License
• CHANGELOG.md : 릴리즈 변경 이력

테스트

python -m mypy
cd tests
python test_v0_1.py                  # v0.1 단위 (18)
python test_challenge_v0_1.py        # 차단 감지 (9)
python test_bigarray_v0_2.py         # 데이터 배열 점수 (14)
python test_extract_v0_2.py          # HTML 추출 파이프라인 (15)
python test_completeness.py          # 완전성 신호 (7)
python test_csr_detection.py         # CSR 감지 (5)
python test_team_review_v0_2.py      # 팀 리뷰 5개 약점 회귀 (22)
python test_robots_backlog.py        # robots RFC 9309 + redirect (13)
python test_v0_2_integration.py      # v0.2 연결 (9)
python test_merge.py                 # pro signals 머지 (5)
python test_head_verify.py           # §3.5 HEAD 검증 (24)
python test_antibot_v0_3.py          # §3.3 제공자 식별 + Unknown Mitigation (20)
python test_selector_encoding.py     # §3.8 selector + §3.9 인코딩 (13)
python test_official_paths.py        # §3.7 공식 API·한국 라우팅·약관 (14)
python test_playwright_phase2_v0_4.py # v0.4 Playwright 2단계
python test_html_report_v0_5.py      # v0.5 HTML 리포트
python test_challenge_mock_v0_5.py   # v0.5 challenge mock 테스트셋
python test_challenge_phase2_v0_5.py # v0.5 challenge → Phase 2 확장
python test_content_profile.py       # div/span 콘텐츠·JS shell 판정 회귀
python test_modular_imports_v0_5.py  # 모듈 분리 import smoke
python test_sitemap_validation.py    # sitemap HEAD 검증 false positive 회귀
python test_llm_layer_v0_7.py        # v0.7 LLM 해석 레이어
python test_protocol_v0_8.py         # v0.8 실행 프로토콜
python test_review_improvements_v0_8.py # 외부 리뷰 반영 회귀

상태 (2026-06-04 갱신)

완료:

• v0.1 본체 + 차단 게이트 + brotli 수정 (이전 세션)
• v0.2 점수 코어 + HTML 추출 (이전 세션)
• 팀 리뷰 5개 약점 반영 (이번 세션): · 승자 점수 절대 임계값(0.30) + meaningful_keys=0 강등 · VALUABLE/NOISE 키 충돌 해소 (size·color는 NOISE 쪽만 유지) · 한국어 키 보강 (이름/가격/평점 등 22개 추가) · value_diversity 중첩 dict 처리 명시화 + 표본 가중 · JSON-LD 단일 객체 후보 등록
• robots 백로그 처리 (이번 세션): · RFC 9309 4xx → robots 기준 제한 신호 없음 / 5xx → 보수적 차단 · redirect_chain·final_url 정보 보존
• v0.2 모듈을 진단봇 본체에 연결 (이번 세션): 마커 발견 시 SSR_HYDRATED / HYDRATION_NO_ARRAY / HYDRATION_NO_DATA로 분기
• v0.4 Playwright 2단계: · CSR/CSR_SUSPECTED/challenge일 때 브라우저 진단 실행 · 렌더링된 HTML을 1단계 분석에 재투입 · 실제 XHR/fetch 요청과 설정 쿠키를 리포트/JSON에 기록 · Playwright 실패 시 1단계 결과만으로 판단하도록 graceful fallback
• v0.5 HTML 리포트: · Best Path → Estimated Work → Data Map → Blockers & Risks 순서 · confidence/evidence는 접힘 상세로 분리 · robots/challenge/login/PII를 비용·일정 플래그로 표시 · challenge 통과 시 Phase 2 API/DOM 기반 Best Path로 갱신, 미통과 시 manual_review
• v0.5 challenge mock 테스트셋: · 7개 provider + Unknown Mitigation fixture · VERIFICATION_GATE 보류와 HTML 리포트 비용 플래그 회귀
• 2차 품질선: · sitemap 후보 HEAD Content-Type 검증 · robots sitemap이 text/html catch-all이면 Best Path에서 제외 · sitemap 검증 사유를 텍스트/JSON/HTML 리포트에 표시 · div/span 기반 정적 콘텐츠 카운팅 · 큰 JS shell을 body_size만으로 STATIC 처리하지 않도록 보정
• 모듈 분리: · legacy monolith 삭제 · 10개 책임 모듈 + scouter.py CLI로 분리 · import smoke 포함 전체 310 PASS / 0 FAIL
• v0.7 LLM 해석 레이어: · LLM off면 기존 JSON/HTML 경로 유지 · LLM on일 때 구조화 데이터만 위생 처리해 mock/API 호출 · Executive Brief + data/strategy/gate/terms 해석을 HTML/JSON에 표시
• v0.8 실행 프로토콜: · BestPath별 connection_test/collection_plan/storage/verification 생성 · 민감 header 제외, pagination/retry/storage/verification 규칙 포함 · agent_prompt 옵션과 HTML/JSON 프로토콜 섹션 제공
• 외부 리뷰 반영: · VERSION/UA를 0.8 기준으로 정합화 · QUICKSTART.md 추가 · Best Path Trace를 protocol/HTML/JSON에 표시 · 광고/로그/인증 API 후보를 수집용 API에서 강등 · protocol 5a 힌트(sample_record_hint, json_path_hints) 추가 · protocol 5b 힌트(selector_hints, wait_condition) 추가
• 릴리즈 패키징: · pyproject.toml, scouter console entry point, --version · MIT LICENSE, CHANGELOG.md, .gitignore 릴리즈 산출물 정리 · 사용자-facing CLI 에러 메시지 정리

1차 마일스톤:

• 완료. URL 1개로 경량 진단, 필요 시 Playwright 2단계, 텍스트/JSON/HTML 리포트까지 내부 1차 판단 가능.

다음:

• v0.8 QA: 실제 샘플 리포트에서 프로토콜 품질 검수

백로그:

• curl_cffi 차단통과 (소프트콘·philpapers)