# doc2md — AI Agent Usage Guide

AI 에이전트가 이 도구를 사용하는 방법을 정의한다.
인간용 UI는 없음. 모든 인터페이스는 에이전트 친화적으로 설계됨.

---

## 1. 목적

`raw/` 폴더의 바이너리 문서(PDF, HWP, HWPX, HML, HTML)를 Markdown으로 변환한다.
변환된 `.md` 파일은 에이전트가 직접 읽어 위키 컴파일 등 후속 작업에 사용한다.

---

## 2. CLI 인터페이스

### 기본 사용법

```bash
# 단일 파일 변환
python convert.py <input_file> -o <output_dir>

# 결과를 JSON으로 받기 (에이전트 권장)
python convert.py <input_file> -o <output_dir> --json

# 폴더 일괄 변환
python convert.py --scan <input_dir> -o <output_dir> --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 `<table>` 형식으로 보존 (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` 결과를 받았을 때 반드시
해당 이미지 파일을 직접 읽어 내용을 파악하라.