paper-downloader

논문 PDF 다운로드 스킬 (paper-downloader)

0. 핵심 원칙 (반드시 준수)

금지

• 비공식·비합법 PDF mirror 사용 금지: 저작권·기관 라이선스 위반
• 공유 폴더 다운로드 금지: 개인 연구용으로만
• 출판사 anti-bot 우회 금지: 캡챠 자동 풀이, IP rotation, headers 위조 금지
• rate limit 위반 금지: polite pool 사용, email 헤더 포함

허용

• Unpaywall API: OA 버전 자동 탐색
• 기관 프록시: 기관 라이선스 범위 내
• CrossRef: DOI → metadata·landing URL 조회
• 사용자 supervised: 자동화 실패 시 수동 안내

1. 이 스킬이 하는 일

paper-screening 출력의 selected[*].doi를 받아:

1. Unpaywall API로 OA URL 우선 시도
2. 실패 시 기관 프록시 + DOI resolver
3. 두 경로 모두 실패 시 manual_required로 표시
4. 다운로드 성공 시 PDF 검증·SHA256·라이선스 정보 기록

2. 입출력 계약

입력 (필수 필드)

• screened_path: paper-screening의 screened.json 경로
• pipeline_run_id
• config.output_dir, config.pdf_subdir
• config.user_email (Unpaywall polite pool 필수)
• config.use_institutional_proxy (bool)
• config.max_per_run, config.rate_limit_qps, config.skip_if_exists

출력 (필수 산출물)

• downloads.json: schema_version, stage=S4, policy, summary, items[*]
  • items[*]: wos_uid, doi, status, method, pdf_path, pdf_sha256, size_bytes, downloaded_at, source.{found,pdf_url,license,version,host_type}
• manual_guide.md: 수동 다운로드 필요 항목 안내
• failed.json: 다운로드 실패 항목

status enum

• ok | manual_required | skipped_existing | failed

method enum

• unpaywall | institutional_proxy | manual

3. 다운로드 검증 (PDF 무결성)

• 파일 존재 + 최소 크기(min_size_kb=30) 검사
• magic bytes %PDF 확인 (HTML 위장 차단)
• SHA256 해시 기록
• 검증 실패 시 파일 삭제 후 manual_required로 표시

4. OA 우선순위 (Unpaywall)

1. host_type=publisher + version=publishedVersion → 최선
2. host_type=repository + publishedVersion → 차선
3. acceptedVersion → 가능
4. submittedVersion (preprint) → 인용 시 주의

5. 의존성

pip install requests pypdf playwright
playwright install chromium

6. 주의사항

• Unpaywall rate limit: polite pool 100,000 req/day, email 헤더 필수
• PDF 검증 실패: HTML 받음 → manual_required, 너무 작음 → 폐기
• 라이선스: cc-by 또는 publisher host_type → 안전, submittedVersion → 인용 주의
• 중복 처리: skip_if_exists=true 기본
• 개인정보: email은 매니페스트에만, 로그는 마스킹

7. 다음 단계 연계

• 입력: paper-screening의 screened.json
• 출력: paper-quality-reviewer가 status=ok PDF만 QA
• vault 통합: 사용자 검토 후 수동

8. 상세 예시·코드

본 섹션의 입력 예시·전략별 코드(Unpaywall, 기관 프록시, 수동 안내)·메인 워크플로우· 출력 예시(downloads.json, manual_guide.md, 파일 구조)는 docs/appendix/paper-downloader-strategies.md 참조.