# modern-crawler

> 한국근대사료DB(db.history.go.kr/modern)의 근대 사료를 검색어 또는 컬렉션 지정으로 크롤링하여 구조화된 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~modern-crawler:20260209154541

---

---
name: modern-crawler
version: 0.9.0-beta
description: >-
  한국근대사료DB(db.history.go.kr/modern)의 근대 사료를 검색어 또는 컬렉션 지정으로
  크롤링하여 구조화된 JSON으로 저장. 원문과 번역문을 함께 수집.
  "크롤링" + "근대사료/근대/모던" 키워드 조합 시 사용.
status: beta
---

> **⚠️ Beta**: 이 크롤러는 베타 버전입니다. browse 모드의 셀렉터가 사이트 변경에 따라 동작하지 않을 수 있습니다. 문제 발견 시 [GitHub Issues](https://github.com/yourusername/korean-history-crawlers/issues)에 리포트해 주세요.

# 한국근대사료DB 크롤링

대상: https://db.history.go.kr/modern/

---

## 워크플로우

### Phase 1: 모드 확인

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

| 모드 | 설명 | 예시 |
|------|------|------|
| **search** | 검색어 기반 | "동학 검색해서 근대사료 크롤링해줘" |
| **browse** | 특정 DB/볼륨 지정 | "주한일본공사관기록 1권 크롤링해줘" |

### Phase 2: 파라미터 수집

#### search 모드

사용자에게 확인:

```
[검색 조건 확인]
- 검색어: 동학
- 검색 필드: 전체 (all)
- 번들명: 동학_검색결과
- 저장 경로: DB/Modern/동학_검색결과/

진행할까?
```

#### browse 모드

```
[크롤링 조건 확인]
- 대상: 주한일본공사관기록·통감부문서 (jh)
- 범위: 1권 (jh_001)
- 번들명: 주한일본공사관기록_1권
- 저장 경로: DB/Modern/주한일본공사관기록_1권/

진행할까?
```

| 항목 | 설명 |
|------|------|
| 검색어 | 키워드 (쉼표 구분, search 모드) |
| 검색 필드 | all(기본), title, body, creator |
| 대상 DB | itemId (browse 모드) — [전체 목록](references/collections.md) |
| 번들명 | `DB/Modern/{번들명}/`에 저장 — [네이밍 규약](references/contract.md) |

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

### Phase 3: 건수 확인 + DB 선택

#### search 모드

**1단계: DB별 건수 확인**

```bash
python3 .claude/skills/modern-crawler/scripts/modern_search.py -k "동학" --count-only
```

결과를 **번호 매긴 테이블**로 사용자에게 표시 후, 크롤링할 DB 번호 선택:
- 숫자: `1,3` → 개별 DB 선택
- 범위: `28-30` → 연속 DB 선택
- 전체: `all`
- **AskUserQuestion 사용하지 않음** — 텍스트 기반 대화로 처리

**2단계: 선택된 DB별 상세 수집**

```bash
python3 .claude/skills/modern-crawler/scripts/modern_search.py -k "동학" --items jh,prd -o /tmp/modern_search_results.json
```

#### browse 모드

리프 탐색으로 건수 확인:

```bash
python3 .claude/skills/modern-crawler/scripts/modern_crawler.py browse --item jh --level jh_001 --name test --limit 0 2>&1 | head -20
```

> 건수 확인 후 사용자에게 보고

### Phase 4: 최종 확인 (필수)

**모든 경로에서 반드시 최종 확인 단계를 거친다.**

검색어, 대상 DB, 총 예상 건수, 번들명, 저장 경로를 정리하여 사용자에게 최종 확인:
```
[크롤링 최종 확인]
- 대상 DB: jh (662건), prd (2,100건)
- 총 예상: 2,762건
- 번들명: 동학_검색결과
- 저장: DB/Modern/동학_검색결과/

크롤링 시작할까?
```

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

### Phase 5: 크롤링 실행

#### search 모드

```bash
# 검색 결과 수집 (Phase 3에서 이미 완료)
# → /tmp/modern_search_results.json

# 크롤링
python3 .claude/skills/modern-crawler/scripts/modern_crawler.py crawl /tmp/modern_search_results.json --name 동학_검색결과
```

#### browse 모드

```bash
# 컬렉션 전체
python3 .claude/skills/modern-crawler/scripts/modern_crawler.py browse --item jh --name 주한일본공사관기록_전체

# 특정 볼륨
python3 .claude/skills/modern-crawler/scripts/modern_crawler.py browse --item jh --level jh_001 --name 주한일본공사관기록_1권
```

**스크립트 옵션**:

#### modern_search.py
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `-k, --keywords` | 검색 키워드 (쉼표 구분) | 필수 |
| `-o, --output` | 출력 파일 경로 (JSON) | `--count-only` 시 불필요 |
| `-i, --items` | 대상 DB ID (쉼표 구분) | - |
| `-f, --field` | 검색 필드 (all/title/body/creator) | all |
| `--date-from` | 시작 연도 | - |
| `--date-to` | 종료 연도 | - |
| `-c, --count-only` | DB별 건수만 확인 | - |

#### modern_crawler.py browse
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--item` | 컬렉션 ID (예: jh, kd, prd) | 필수 |
| `--level` | 시작 레벨 ID (특정 볼륨) | - |
| `-n, --name` | 번들 이름 | 필수 |
| `-w, --workers` | 병렬 워커 수 | 4 |
| `-r, --resume` | 중단된 작업 재개 | - |
| `-l, --limit` | 수집 건수 제한 | 무제한 |
| `--types` | 수집 유형 (o/r/both) | both |

#### modern_crawler.py crawl
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `input_file` | 입력 파일 (JSON, modern_search.py 출력) | 필수 |
| `-n, --name` | 번들 이름 | 필수 |
| `-w, --workers` | 병렬 워커 수 | 4 |
| `-r, --resume` | 중단된 작업 재개 | - |
| `-l, --limit` | 수집 건수 제한 | 무제한 |
| `--types` | 수집 유형 (o/r/both) | both |

### Phase 6: 완료 보고

**통계 보고**:
```
[크롤링 완료]
- 번들: 동학_검색결과
- 총 기사: 2,762건
- 번역문 포함: 1,800건 (65%)
- 실패: 3건
- 저장: DB/Modern/동학_검색결과/
```

**후처리 안내**:
```
"DB/Modern/{번들명} 전처리해줘"
```

---

## Known Issues

- **browse 모드 일시 비활성화**: db.history.go.kr 사이트 HTML 구조 변경으로 볼륨 목록 수집이 실패합니다 (`div.nd-snb-content` 셀렉터 불일치). **search 모드를 사용하세요.** browse 모드는 사이트 구조 재분석 후 수정 예정.

---

## 참조

- [references/contract.md](references/contract.md): 출력 구조, 번들 네이밍 규약, 특이사항
- [references/collections.md](references/collections.md): 전체 컬렉션 목록 (itemId)