# sjw-crawler

> 승정원일기(sjw.history.go.kr) 기사를 검색어 또는 날짜 범위로 크롤링하여 구조화된 JSON으로 저장. 한문 원문과 ITKC 국역을 함께 수집. "크롤링" + "승정원일기/승정원" 키워드 조합 시 사용.

- Author: 송지혜
- Repository: BAHO92/korean-history-crawlers
- Version: 20260209154541
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/BAHO92/korean-history-crawlers
- Web: https://mule.run/skillshub/@@BAHO92/korean-history-crawlers~sjw-crawler:20260209154541

---

---
name: sjw-crawler
description: >-
  승정원일기(sjw.history.go.kr) 기사를 검색어 또는 날짜 범위로 크롤링하여
  구조화된 JSON으로 저장. 한문 원문과 ITKC 국역을 함께 수집.
  "크롤링" + "승정원일기/승정원" 키워드 조합 시 사용.
---

# 승정원일기 크롤링

---

## 워크플로우

### Phase 1: 모드 확인

사용자에게 크롤링 모드 질문:

| 모드 | 설명 | 예시 |
|------|------|------|
| **search** | 검색어 기반 | "宋時烈 검색해서 승정원일기 크롤링해줘" |
| **browse** | 날짜 범위 열람 | "현종 즉위년~5년 승정원일기 크롤링해줘" |

### Phase 2: 파라미터 수집 + 검색 조건 확인

파라미터 수집 후 **반드시** 사용자에게 확인:

#### search 모드
```
[검색 조건 확인]
- 검색어: 宋時烈
- 검색 필드: all
- 왕대 범위: 현종~숙종
- 번들명: 송시열_현종숙종
- 저장 경로: DB/SJW/송시열_현종숙종/

진행할까?
```

#### browse 모드
```
[크롤링 조건 확인]
- 왕대: 현종
- 연도 범위: 즉위년~5년
- 번들명: 현종_즉위년_5년
- 저장 경로: DB/SJW/현종_즉위년_5년/

진행할까?
```

| 항목 | 설명 |
|------|------|
| 검색어 | 키워드 (쉼표 구분) |
| 검색 필드 | all(기본), person, place, book, title, seju, attendance, weather |
| 왕대 범위 | 전체(기본) 또는 특정 범위 |
| 번들명 | `DB/SJW/{번들명}/`에 저장 |

**번들명 규칙**: [references/contract.md](references/contract.md) 참조

> 사용자가 확인하면 Phase 3으로

### Phase 3: 건수 확인

#### search 모드
`--count-only`로 결과 수 먼저 확인:

```bash
python3 .claude/skills/sjw-crawler/scripts/sjw_search.py -k "宋時烈" -c
```

결과 수 확인 후 사용자에게 재확인:

```
[검색 결과]
- 결과 수: 3,617건
크롤링 진행할까?
```

#### browse 모드
사전 건수 확인 어려움 (월별→일별→기사별 3단계 HTTP 요청 체인).
**⚠️ 성능 주의**: 즉위년 1년치도 수 분 소요. 왕대 전체는 10분+ 예상.

테스트 레시피 (최소 범위부터):
```bash
# 1단계: 즉위년 5건만 테스트 (1~3분 소요)
python3 .claude/skills/sjw-crawler/scripts/sjw_crawler.py browse --reign 현종 --year-from 0 --year-to 0 --name test --limit 5

# 2단계: 규모 확인 후 전체 실행
```

대략적 규모 안내 후 사용자에게 확인:

```
[browse 모드 안내]
- 왕대 전체 수집 시 수천~수만 건 예상
- 3단계 탐색(월→일→기사)으로 수 분~수십 분 소요
- --limit 5로 테스트 후 진행 권장

테스트 크롤링 먼저 할까?
```

> 사용자가 확인하면 Phase 4로

### Phase 4: 크롤링 실행

#### search 모드

1. 검색
```bash
python3 .claude/skills/sjw-crawler/scripts/sjw_search.py -k "宋時烈" -rf 현종 -rt 숙종 -o /tmp/sjw_results.json
```

2. 크롤링
```bash
python3 .claude/skills/sjw-crawler/scripts/sjw_crawler.py /tmp/sjw_results.json --name 송시열_현종숙종
```

#### browse 모드
```bash
# 왕대 전체
python3 .claude/skills/sjw-crawler/scripts/sjw_crawler.py browse --reign 현종 --name 현종_전체

# 특정 연도 범위
python3 .claude/skills/sjw-crawler/scripts/sjw_crawler.py browse --reign 숙종 --year-from 20 --year-to 25 --name 숙종_20_25년

# 즉위년만
python3 .claude/skills/sjw-crawler/scripts/sjw_crawler.py browse --reign 현종 --year-from 0 --year-to 0 --name 현종_즉위년
```

**스크립트 옵션**:

#### sjw_search.py
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-k, --keywords` | 검색 키워드 (쉼표 구분) | 필수 |
| `-o, --output` | 출력 파일 경로 (JSON) | 필수 |
| `-f, --field` | 검색 필드 | all |
| `-rf, --reign-from` | 시작 왕대 | - |
| `-rt, --reign-to` | 종료 왕대 | - |
| `-c, --count-only` | 결과 수만 확인 | - |

#### sjw_crawler.py (search 모드)
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `input_file` | 입력 파일 (JSON) | 필수 |
| `-n, --name` | 번들 이름 | 필수 |
| `-w, --workers` | 병렬 워커 수 | 4 |
| `-r, --resume` | 중단된 작업 재개 | - |
| `-l, --limit` | 수집 건수 제한 (테스트용) | - |

#### sjw_crawler.py browse (browse 모드)
| 옵션 | 단축 | 설명 | 기본값 |
|------|------|------|--------|
| `--reign` | | 왕대명 | 필수 |
| `--year-from` | `-yf` | 시작 년 (0=즉위년) | - |
| `--year-to` | `-yt` | 종료 년 | - |
| `--name` | `-n` | 번들 이름 | 필수 |
| `--workers` | `-w` | 병렬 워커 수 | 4 |
| `--resume` | `-r` | 중단된 작업 재개 | - |
| `--limit` | `-l` | 수집 건수 제한 (테스트용) | - |

### Phase 5: 완료 보고 + 후처리

**통계 보고**:
```
[크롤링 완료]
- 총 기사: 3,617건
- 번역문 포함: 2,100건 (58%)
- 실패: 0건
- 저장: DB/SJW/송시열_현종숙종/
```

**후처리**: 인덱스 동기화 스크립트 미존재. 전처리 안내:
```
"DB/SJW/{번들명} 전처리해줘"
```

---

## 참조

- [references/contract.md](references/contract.md): 출력 구조, 번들 네이밍 규약, 기사 JSON 스키마, 왕대 코드, 특이사항