doc2md/AGENT_GUIDE.md

doc2md — AI Agent Usage Guide

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

---

1. 목적

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

---

2. CLI 인터페이스

기본 사용법

# 단일 파일 변환
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

환경변수

VENV_PYTHON=D:\MYCLAUDE_PROJECT\doc2md\.venv\Scripts\python.exe

---

3. 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"]
}

성공 (폴더 스캔)

{
  "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" }
  ]
}

실패

{
  "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 통합 예시

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 결과를 받았을 때 반드시 해당 이미지 파일을 직접 읽어 내용을 파악하라.