# munzip-crawler

> 한국고전종합DB(db.itkc.or.kr) 문집을 검색어 또는 서지ID 기반으로 크롤링하여 구조화된 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~munzip-crawler:20260209154541

---

---
name: munzip-crawler
description: >-
  한국고전종합DB(db.itkc.or.kr) 문집을 검색어 또는 서지ID 기반으로 크롤링하여
  구조화된 JSON으로 저장. 원문과 국역을 함께 수집.
  "크롤링" + "문집/한국문집총간/ITKC" 키워드 조합 시 사용.
---

# 한국고전종합DB 문집 크롤링

---

## 워크플로우

### Phase 1: 모드 확인

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

| 모드 | 설명 | 예시 |
|------|------|------|
| **search** | 검색어 기반 | "正人心으로 송자대전 검색해서 크롤링해줘" |
| **full** | 서명 전체 | "송자대전 전체 크롤링해줘" |

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

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

#### search 모드
```
[검색 조건 확인]
- 검색어: 正人心
- 서지 ID: ITKC_MO_0367A (송자대전)
- 검색 대상: MO_BD (본문)
- 번들명: 正人心_송자대전
- 저장 경로: DB/Munzip/正人心_송자대전/

진행할까?
```

#### full 모드
```
[크롤링 조건 확인]
- 서지 ID: ITKC_MO_0367A (송자대전)
- 예상 기사 수: ~9,434건 (참조표 기준)
- 번들명: 전체_송자대전
- 저장 경로: DB/Munzip/전체_송자대전/

진행할까?
```

| 항목 | 설명 |
|------|------|
| 검색어 | 검색 키워드 (search 모드만) |
| 서지 ID | ITKC 서지 ID (예: ITKC_MO_0367A). 생략 시 전체 검색 |
| 번들명 | `DB/Munzip/{번들명}/`에 저장 |

**서지ID 참조**: [references/collections.md](references/collections.md)

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

### Phase 3: 건수 확인

`--count-only`로 결과 수 먼저 확인:

```bash
# search 모드
python3 .claude/skills/munzip-crawler/scripts/munzip_crawler.py search -q "正人心" -c ITKC_MO_0367A -n test --count-only

# full 모드
python3 .claude/skills/munzip-crawler/scripts/munzip_crawler.py full -c ITKC_MO_0367A -n test --count-only
```

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

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

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

### Phase 4: 크롤링 실행

#### search 모드
```bash
python3 .claude/skills/munzip-crawler/scripts/munzip_crawler.py search -q "正人心" -c ITKC_MO_0367A -n "正人心_송자대전"
```

#### full 모드
```bash
python3 .claude/skills/munzip-crawler/scripts/munzip_crawler.py full -c ITKC_MO_0367A -n "전체_송자대전"
```

**공통 옵션**:
| 옵션 | 단축 | 설명 | 기본값 |
|------|------|------|--------|
| `--collection` | `-c` | 서지 ID | - |
| `--name` | `-n` | 번들 이름 (필수) | - |
| `--query` | `-q` | 검색어 (search만, 필수) | - |
| `--workers` | `-w` | 병렬 워커 수 | 4 |
| `--resume` | `-r` | 중단된 작업 재개 | - |
| `--limit` | `-l` | 수집 건수 제한 (테스트용) | 무제한 |
| `--count-only` | - | 결과 수만 확인 | - |

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

**통계 보고** (크롤러 출력에서 추출):
```
[크롤링 완료]
- 총 기사: 43건
- 번역문 포함: 21건 (49%)
- 실패: 0건
- 저장: DB/Munzip/正人心_송자대전/
```

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

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

---

## 참조

- [references/contract.md](references/contract.md): 출력 구조, 번들 네이밍 규약
- [references/collections.md](references/collections.md): 주요 서지ID 참조표
- [references/itkc_openapi.md](references/itkc_openapi.md): 한국고전종합DB OpenAPI 상세 사용법