6f365018f5
- AGENT_GUIDE.md: AI 에이전트 사용 스펙 (CLI, JSON 출력, 페이지 타입 정의) - CLAUDE.md: 프로젝트 개요 및 개발 원칙 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
37 lines
1.4 KiB
Markdown
37 lines
1.4 KiB
Markdown
# doc2md
|
|
|
|
바이너리 문서(PDF/HWP/HWPX/HML/HTML)를 Markdown으로 변환하는 도구.
|
|
AI 에이전트(Claude Code)가 ParaWiki ingest-raw에서 호출한다.
|
|
|
|
## 필수 읽기
|
|
|
|
**사용법은 [AGENT_GUIDE.md](AGENT_GUIDE.md) 를 먼저 읽어라.**
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
doc2md/
|
|
├── convert.py # 통합 CLI 진입점 (에이전트가 직접 호출)
|
|
├── converters/
|
|
│ ├── pdf.py # PDF → MD (페이지별 분류 + 라우팅)
|
|
│ ├── hwp.py # HWP → MD (COM + pyhwp fallback)
|
|
│ ├── hwpx.py # HWPX → MD (ZIP+XML 파싱)
|
|
│ ├── hml.py # HML → MD (XML 파싱)
|
|
│ └── html.py # HTML → MD (html2text)
|
|
├── AGENT_GUIDE.md # AI 에이전트 사용 가이드 (핵심 문서)
|
|
└── requirements.txt
|
|
```
|
|
|
|
## 핵심 원칙
|
|
|
|
1. **비대화형**: 절대 사용자 입력 대기하지 않음
|
|
2. **JSON 출력**: `--json` 플래그 시 파싱 가능한 JSON만 stdout 출력
|
|
3. **멱등성**: 이미 변환된 파일은 건너뜀 (기본 동작)
|
|
4. **다이어그램 플래그**: PDF에 다이어그램 페이지 존재 시 `has_diagrams: true` 반환
|
|
|
|
## 개발 시 주의사항
|
|
|
|
- `convert.py` CLI 인터페이스는 AGENT_GUIDE.md 스펙과 항상 일치해야 함
|
|
- JSON 출력 구조 변경 시 AGENT_GUIDE.md 동시 업데이트 필수
|
|
- `converters/` 각 파일은 단독 임포트 가능해야 함 (순환 의존 금지)
|