# crawl-orchestrator

> 크롤러 오케스트레이션. "수집현황", "어떤 DB가 있어", "크로스 검색", "DB 인벤토리" 요청 시 사용.

- 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~crawl-orchestrator:20260209154541

---

---
name: crawl-orchestrator
description: 크롤러 오케스트레이션. "수집현황", "어떤 DB가 있어", "크로스 검색", "DB 인벤토리" 요청 시 사용.
---

# 크롤러 오케스트레이터

DB 크롤러 인벤토리 관리, 수집현황 조회, 크로스 DB 검색을 수행하는 메타 스킬.
개별 크롤링은 각 크롤러 스킬(sillok-crawler, sjw-crawler 등)이 담당.

---

## 워크플로우

### Phase 1: 요청 분류

사용자 요청을 분류:

| 유형 | 예시 | 동작 |
|------|------|------|
| **인벤토리** | "어떤 DB가 있어?", "크롤러 목록" | → inventory 실행 |
| **수집현황** | "수집현황 보여줘", "뭐가 수집됐어?" | → status 실행 |
| **크로스 검색** | "宋時烈이 어떤 DB에 있어?", "크로스 검색" | → search 실행 |
| **특정 DB 크롤링** | "실록 크롤링해줘", "비변사등록 수집해줘" | → 해당 크롤러 스킬 안내 |

### Phase 2: 실행

#### 인벤토리 조회
```bash
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py inventory
```

등록된 모든 크롤러 목록, 대상 DB, 지원 모드 등을 표로 출력.

#### 수집현황 조회
```bash
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py status
```

DB/ 디렉토리를 스캔해서 소스별 번들 수, 총 기사 수, 최종 수집일을 표로 출력.

#### 크로스 DB 검색
```bash
# 기본 검색
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py search "宋時烈"

# 상세 옵션
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py search "宋時烈" --title "제목검색어" --body "본문검색어" --date-from 16000101 --date-to 17001231
```

db.history.go.kr 통합검색 API로 어떤 DB에 몇 건 있는지 테이블로 출력.
**주의**: 실록/승정원일기/ITKC/뉴스라이브러리는 별도 도메인이라 통합검색에 포함되지 않음.

### Phase 3: 라우팅

검색 결과를 보고 사용자에게 크롤링 방법 안내:

| DB | 크롤러 스킬 | 호출 예시 |
|----|------------|----------|
| 조선왕조실록 | sillok-crawler | "실록 크롤링해줘" |
| 승정원일기 | sjw-crawler | "승정원일기 크롤링해줘" |
| 한국고전종합DB | munzip-crawler | "문집 크롤링해줘" |
| 근대사료 | modern-crawler | "근대사료 크롤링해줘" |
| 뉴스 라이브러리 | newslibrary-crawler | "뉴스 크롤링해줘" |
| 비변사등록 등 미구현 DB | 미구현 안내 | "아직 크롤러가 없어. 개발 필요." |

---

## 스크립트 옵션

### inventory.py inventory
인벤토리 출력. 추가 옵션 없음.

### inventory.py status
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--source` | 특정 소스만 (예: sillok) | 전체 |

### inventory.py search
| 인자/옵션 | 설명 | 기본값 |
|----------|------|--------|
| `keyword` (위치인자) | 검색어 | 필수 |
| `--title` | 제목 검색어 | - |
| `--body` | 본문 검색어 | - |
| `--creator` | 저자 검색어 | - |
| `--date-from` | 시작일 (YYYYMMDD) | - |
| `--date-to` | 종료일 (YYYYMMDD) | - |
| `--items` | 특정 DB만 (쉼표 구분) | - |
| `--count-only` | 건수만 출력 (기본 동작) | true |

---

## 레지스트리 파일

`DB/_registry.yaml` — 모든 크롤러 메타정보.
새 크롤러 추가 시 이 파일의 `sources:` 섹션에 등록.

---

## 관리 커맨드

### inventory.py setup
DB 저장 경로를 설정한다. `config.json`을 생성/수정.
```bash
# 대화형 (경로 직접 입력)
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py setup

# 비대화형
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py setup --db-root ~/my-data/DB
```
| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--db-root` | DB 저장 경로 | (대화형 입력) |

설정하지 않으면 프로젝트 루트의 `DB/` 디렉토리를 사용.

### inventory.py update
스킬을 최신 버전으로 업데이트 (git pull).
```bash
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py update
```

### inventory.py check-deps
크롤러 실행에 필요한 패키지 설치 상태를 확인.
```bash
python3 .claude/skills/crawl-orchestrator/scripts/inventory.py check-deps
```
필수: requests, beautifulsoup4, pyyaml
선택: playwright (뉴스라이브러리 인증용)

---

## 설정 파일

- `config.default.json` — 기본 설정 (커밋됨, 수정하지 않음)
- `config.json` — 사용자별 설정 (gitignored, `setup`으로 생성)

`config.json`의 `db_root` 값이 비어있거나 파일이 없으면 기본 경로(프로젝트 루트/DB)를 사용.
모든 크롤러 스크립트가 이 설정을 참조.

---

## 주의사항

- 이 스킬은 **크롤링을 직접 수행하지 않음**. 인벤토리/검색/안내만 담당.
- 실제 크롤링은 반드시 해당 크롤러 스킬을 호출.
- db.history.go.kr 통합검색은 해당 플랫폼 내 DB만 검색. 별도 도메인 DB(실록, 승정원일기, ITKC, 뉴스라이브러리)는 각 스킬의 search 기능 사용.