# sillok-crawler

> 조선왕조실록(sillok.history.go.kr) 기사를 검색어 또는 TSV 파일 기반으로 크롤링하여 구조화된 JSON으로 저장. 원문과 국역을 함께 수집. "크롤링" + "실록" 키워드 조합 시 사용.

- 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~sillok-crawler:20260209154541

---

---
name: sillok-crawler
description: >-
  조선왕조실록(sillok.history.go.kr) 기사를 검색어 또는 TSV 파일 기반으로 크롤링하여
  구조화된 JSON으로 저장. 원문과 국역을 함께 수집.
  "크롤링" + "실록" 키워드 조합 시 사용.
---

# 조선왕조실록 크롤링

---

## 워크플로우

### Phase 1: 모드 확인

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

| 모드 | 설명 | 예시 |
|------|------|------|
| **file** | TSV 파일 기반 | "이 TSV로 크롤링해줘" |
| **search** | 검색어 기반 | "宋時烈 검색해서 크롤링해줘" |

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

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

#### search 모드
```
[검색 조건 확인]
- 검색어: 狂氣, 發狂, 癲狂
- 검색 탭: 원문 (w)
- 왕대 범위: 전체
- 번들명: 광기_전체
- 저장 경로: DB/Sillok/광기_전체/

진행할까?
```

#### file 모드
```
[크롤링 조건 확인]
- 입력 파일: /path/to/file.tsv
- 기사 수: N건 (TSV 행 수)
- 번들명: 송시열_전체
- 저장 경로: DB/Sillok/송시열_전체/

진행할까?
```

| 항목 | 설명 |
|------|------|
| 검색어 | 최종 검색할 키워드 (쉼표 구분) |
| 검색 탭 | 원문(w, 기본) 또는 국역(k) |
| 왕대 범위 | 전체(기본) 또는 특정 범위(예: 현종~영조) |
| 번들명 | `DB/Sillok/{번들명}/`에 저장 |

**번들명 규칙**: `{검색어}_{출처}` (예: `송시열_숙종`, `송시열_전체`)

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

### Phase 3: 건수 확인

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

```bash
python .claude/skills/sillok-crawler/scripts/sillok_search.py --keywords "검색어" --tab k --count-only
```

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

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

#### file 모드
TSV 행 수를 카운트하여 보고:

```
[파일 확인]
- 기사 수: 127건
크롤링 진행할까?
```

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

### Phase 4: 크롤링 실행

#### file 모드
```bash
python .claude/skills/sillok-crawler/scripts/sillok_crawler.py <TSV파일> --name <번들명>
```

#### search 모드

1. 검색
```bash
# 원문 검색 (기본)
python .claude/skills/sillok-crawler/scripts/sillok_search.py --keywords "狂氣,發狂" --output /tmp/search_results.tsv

# 국역 검색
python .claude/skills/sillok-crawler/scripts/sillok_search.py --keywords "광기,발광" --tab k --output /tmp/search_results.tsv

# 왕대 범위 지정 검색
python .claude/skills/sillok-crawler/scripts/sillok_search.py --keywords "박세당" --tab k --reign-from 현종 --reign-to 영조 --output /tmp/search_results.tsv
```

2. 크롤링
```bash
python .claude/skills/sillok-crawler/scripts/sillok_crawler.py /tmp/search_results.tsv --name 광기_전체
```

**스크립트 옵션**:

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

#### sillok_crawler.py
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-n, --name` | 번들 이름 | 필수 |
| `-w, --workers` | 병렬 워커 수 | 4 |
| `-r, --resume` | 중단된 작업 재개 | - |
| `-p, --preprocess` | 완료 후 전처리 안내 표시 | - |

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

**통계 보고**:
```
[크롤링 완료]
- 총 기사: 127건
- 번역문 포함: 120건 (94%)
- 실패: 0건
- 저장: DB/Sillok/광기_전체/
```

**인덱스 동기화** 실행:
```bash
python3 .claude/skills/sillok-crawler/scripts/sillok_index_sync.py
```

이 스크립트가 수행하는 작업:
- 중복 기사 병합 (같은 기사가 여러 번들에 있으면 `bundles` 배열로 관리)
- `DB/Sillok/_index/` 갱신:
  - `bundle_registry.json`: 번들 목록
  - `corpus_registry.json`: 전체 기사 인덱스
  - `reign/*.json`: 왕대별 인덱스
  - `keywords/*.json`: 키워드 역인덱스

---

## 참조

- [references/contract.md](references/contract.md): 출력 구조, 번들 네이밍 규약, 메타데이터 스키마, 검색 모드 한계