commit 6f365018f551958fbde8a1e9de7d265208571a72 Author: minsung Date: Mon Apr 20 08:52:00 2026 +0900 docs: Initial project scaffold with AI agent guide - AGENT_GUIDE.md: AI 에이전트 사용 스펙 (CLI, JSON 출력, 페이지 타입 정의) - CLAUDE.md: 프로젝트 개요 및 개발 원칙 Co-Authored-By: Claude Sonnet 4.6 diff --git a/AGENT_GUIDE.md b/AGENT_GUIDE.md new file mode 100644 index 0000000..4506333 --- /dev/null +++ b/AGENT_GUIDE.md @@ -0,0 +1,201 @@ +# doc2md — AI Agent Usage Guide + +AI 에이전트가 이 도구를 사용하는 방법을 정의한다. +인간용 UI는 없음. 모든 인터페이스는 에이전트 친화적으로 설계됨. + +--- + +## 1. 목적 + +`raw/` 폴더의 바이너리 문서(PDF, HWP, HWPX, HML, HTML)를 Markdown으로 변환한다. +변환된 `.md` 파일은 에이전트가 직접 읽어 위키 컴파일 등 후속 작업에 사용한다. + +--- + +## 2. CLI 인터페이스 + +### 기본 사용법 + +```bash +# 단일 파일 변환 +python convert.py -o + +# 결과를 JSON으로 받기 (에이전트 권장) +python convert.py -o --json + +# 폴더 일괄 변환 +python convert.py --scan -o --json +``` + +### 환경변수 + +```bash +VENV_PYTHON=D:\MYCLAUDE_PROJECT\doc2md\.venv\Scripts\python.exe +``` + +--- + +## 3. JSON 출력 스펙 (에이전트가 파싱하는 형식) + +### 성공 (단일 파일) + +```json +{ + "status": "ok", + "input": "raw/report.pdf", + "output": "raw/report.md", + "format": "pdf", + "pages": [ + { "n": 1, "type": "text" }, + { "n": 2, "type": "diagram", "image": "raw/report_images/page_2.png" }, + { "n": 3, "type": "text-with-photo", "images": ["raw/report_images/fig_3_1.png"] } + ], + "has_diagrams": true, + "diagram_pages": [2], + "images": ["raw/report_images/page_2.png", "raw/report_images/fig_3_1.png"] +} +``` + +### 성공 (폴더 스캔) + +```json +{ + "status": "ok", + "total": 5, + "converted": 4, + "skipped": 1, + "failed": 0, + "results": [ + { "input": "raw/doc1.hwp", "output": "raw/doc1.md", "status": "ok" }, + { "input": "raw/doc2.pdf", "output": "raw/doc2.md", "status": "ok", "has_diagrams": true, "diagram_pages": [3, 7] }, + { "input": "raw/doc3.md", "output": null, "status": "skipped", "reason": "already_md" } + ] +} +``` + +### 실패 + +```json +{ + "status": "error", + "input": "raw/broken.hwp", + "error": "COM timeout — pyhwp fallback also failed" +} +``` + +--- + +## 4. Exit Codes + +| 코드 | 의미 | +|------|------| +| `0` | 완전 성공 | +| `1` | 부분 성공 (일부 파일 실패, 나머지 성공) | +| `2` | 완전 실패 | + +--- + +## 5. 페이지 타입 정의 (PDF 전용) + +| 타입 | 설명 | 에이전트 처리 방법 | +|------|------|--------------------| +| `text` | 텍스트 위주 페이지 | MD 텍스트 직접 읽기 | +| `text-with-photo` | 텍스트 + 사진 | MD 텍스트 읽기 + 이미지 참조 | +| `diagram` | 다이어그램/도면 (벡터 or 특수 래스터) | **이미지 파일을 Claude Vision으로 처리** | +| `image-heavy` | 텍스트 거의 없고 이미지가 대부분 | **이미지 파일을 Claude Vision으로 처리** | + +> **에이전트 필수 동작**: `has_diagrams: true` 이면 `diagram_pages` 의 이미지를 +> Claude Vision (Read 도구로 이미지 파일 직접 읽기)으로 추가 처리할 것. + +--- + +## 6. 파일 형식별 변환 전략 + +### PDF + +1. 각 페이지를 분류 (`text` / `text-with-photo` / `diagram` / `image-heavy`) +2. 텍스트 페이지 → marker-pdf로 텍스트 추출 +3. 다이어그램 페이지 → 페이지 전체를 PNG 렌더링, MD에 이미지 링크 삽입 +4. 모든 결과를 하나의 `.md` 파일로 합산 + +### HWP + +1. 한컴오피스 COM 자동화 시도 (Windows + 한컴오피스 설치 필요) +2. 실패 시 pyhwp 폴백 (크로스플랫폼) + +### HWPX + +- ZIP 압축 해제 → XML 직접 파싱 +- 이미지 추출 포함 + +### HML + +- XML 직접 파싱 +- 병합 셀 테이블은 HTML `` 형식으로 보존 (colspan/rowspan 유지) + +### HTML / HTM + +- html2text (`body_width=0` — 줄바꿈 없음) + +--- + +## 7. 에이전트 권장 사용 패턴 + +### ParaWiki ingest-raw 통합 예시 + +```python +import subprocess, json + +result = subprocess.run( + [VENV_PYTHON, 'convert.py', str(src), '-o', str(src.parent), '--json'], + cwd=CONVERTER_PATH, capture_output=True, text=True +) +data = json.loads(result.stdout) + +if data['status'] == 'ok' and data.get('has_diagrams'): + # diagram_pages의 이미지를 Claude Vision으로 추가 처리 + for img_path in data['images']: + if 'page_' in img_path: # diagram 페이지 이미지 + vision_description = claude_read_image(img_path) + append_to_md(data['output'], vision_description) +``` + +--- + +## 8. 환경 설정 + +### 요구사항 + +``` +Python 3.11+ +marker-pdf # PDF 텍스트 추출 +PyMuPDF (fitz) # PDF 페이지 분석 + 렌더링 +Pillow # 이미지 처리 (다이어그램 감지) +beautifulsoup4 # HTML 파싱 +lxml # XML 파싱 (HML, HWPX) +html2text # HTML → MD +pyhwp # HWP 폴백 변환 +``` + +### Windows 전용 (선택) + +``` +pywin32 # HWP COM 자동화 (한컴오피스 설치 시) +``` + +--- + +## 9. 스킵 조건 + +에이전트가 `--scan` 모드로 실행 시, 다음 파일은 자동으로 건너뜀: +- 이미 `.md` 파일이 같은 경로에 존재 +- 파일 크기 0바이트 +- `README.md`, `CLAUDE.md`, `AGENT_GUIDE.md` + +--- + +## 10. 에이전트에게 보내는 메시지 + +이 도구는 **변환만** 한다. 변환된 MD의 의미 해석, 위키 구조화, 다이어그램 Vision 처리는 +에이전트(Claude)의 역할이다. `has_diagrams: true` 결과를 받았을 때 반드시 +해당 이미지 파일을 직접 읽어 내용을 파악하라. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9a023f9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,36 @@ +# 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/` 각 파일은 단독 임포트 가능해야 함 (순환 의존 금지)