rhwp-exam-ingest

name	rhwp-exam-ingest
description	PDF/이미지/MD/DOCX 형태의 시험문제 자료를 HWPX 시험지 파일로 변환합니다. Claude가 시험지를 직접 읽어(Vision) 문제 구조(지문/선택지/이미지)를 인식하고, 이미지를 정확한 bbox로 잘라 "지문과 선택지 사이" 또는 "지문 아래"에 배치한 HWPX를 생성합니다. 트리거: 사용자가 시험지 파일을 주며 "HWPX로 만들어줘", "한글 시험지로 변환", "exam ingest", "/rhwp-exam-ingest", "시험문제 변환".

rhwp-exam-ingest — 시험지 → HWPX 변환 Skill

목적

사용자가 PDF/이미지/MD/DOCX 형태로 제공하는 시험문제 자료(수능, 모의고사, EBS, 학원 자체 시험지, 자체 출제 자료 등)를 한컴오피스에서 편집 가능한 HWPX 파일로 변환합니다. OCR/Vision/레이아웃 분석은 Claude 본인의 멀티모달 능력으로 직접 수행하며, Anthropic API 별도 호출은 하지 않습니다.

작동 원리

[입력: PDF/PNG/JPG/MD/DOCX]
        │
        ▼ helpers/ 스크립트로 입력 정규화
        │  (PDF→페이지 PNG, DOCX→텍스트+이미지 추출, MD→직접, IMG→그대로)
        │
        ▼ Claude가 Read tool로 페이지 PNG 1장씩 검토
        │  → 시험문제 구조 인식 (자연어 분석):
        │     - 문제 번호 ("1.", "2.", ...)
        │     - 지문 (stem) — 주관식 문장 또는 글
        │     - 선택지 ① ② ③ ④ ⑤
        │     - 이미지/도형/그래프 영역 (bbox 좌표 포함)
        │     - 이미지의 의미적 위치 (지문과 선택지 사이? 지문 아래? 인라인?)
        │
        ▼ Write tool로 ingest.json 작성 (ingest_schema_v1 준수)
        │
        ▼ Bash로 helpers/crop_image.sh 호출
        │  → bbox로 PNG 자르기
        │
        ▼ Bash로 rhwp build-from-ingest 호출
        │  → HWPX 파일 생성
        │
        ▼ [출력: out.hwpx]

중요: Claude(이 모델)가 직접 시험지 이미지를 보고 분석합니다. 외부 OCR 엔진(PaddleOCR, Tesseract 등)을 호출하지 않습니다. 이는 다음 장점을 제공합니다:

• 한국어 시험지 layout을 자연어로 이해 (지문 vs 선택지 의미 분석)
• 이미지의 의미적 배치 위치 결정 (between/above/below/inline)
• 별도 API 키나 네트워크 호출 불필요
• 사용자 환경에 OCR 모델 설치 불필요

사용자 트리거 예시

자연어로 호출:

• "이 시험지 PDF를 HWPX로 변환해줘 — samples/2010-exam_kor.pdf"
• "/rhwp-exam-ingest [-o ]"
• "수능 영어 모의고사 30문제를 한컴 시험지로 만들고 싶어"

입력 형식별 처리

1. PDF 시험지

bash .claude/skills/rhwp-exam-ingest/helpers/pdf_to_pngs.sh <input.pdf> <out_dir>

각 페이지를 PNG로 변환 (300 DPI 기본). out_dir/page_001.png, page_002.png, ...

PDF가 텍스트 layer를 가지면 Vision 분석 보조로 사용 (OCR 부담 감소). pdftotext로 텍스트 추출 후 Claude의 Vision 분석 결과와 교차 검증.

2. 이미지 (PNG/JPG)

직접 Read tool로 시험지 이미지를 보고 분석. 큰 이미지는 사전에 분할이 필요할 수 있으나 보통 한 페이지 분량은 그대로 처리 가능.

3. Markdown (MD)

# MD 파일 직접 읽기 — 텍스트 + 이미지 ref만 있으므로 단순.

![alt](path) 패턴의 이미지를 media 항목에 추가. 텍스트는 # 1., ## 1. 등 마크다운 패턴으로 문제 번호 추론 또는 사용자 입력대로 그룹핑.

4. DOCX

python3 .claude/skills/rhwp-exam-ingest/helpers/extract_docx.py <input.docx> <out_dir>

out_dir/text.txt (본문) + out_dir/img/*.png (임베디드 이미지) 출력.

Claude의 분석 작업 (단계별 instructions)

사용자가 시험지를 제공하면 다음 순서로 작업합니다:

Step 1: 입력 정규화

사용자 입력에 따라 helpers/ 스크립트를 호출하여 페이지 PNG들과 임베디드 텍스트(있으면)를 임시 디렉토리에 생성합니다.

TMP=$(mktemp -d /tmp/rhwp-ingest.XXXXXX)
bash .claude/skills/rhwp-exam-ingest/helpers/pdf_to_pngs.sh user_input.pdf "$TMP"

Step 2: Vision 분석 — 페이지별 시험문제 구조 인식

각 page_NNN.png 를 Read tool로 읽고 다음을 자연어로 분석한 뒤 자료구조에 정리합니다:

• 문제 번호: "1.", "2.", "1)", "①" 등을 stem 시작 마커로 인식.
• 지문(stem): 문제 번호 다음에 오는 본문. 글 한 단락 또는 지시문 + 본문 ("다음 글의 주제로 가장 적절한 것은?" + 글).
• 선택지(choices): ①, ②, ③, ④, ⑤로 시작하는 줄. 보통 5개. label은 그대로 포함.
• 이미지/도형 영역: 시험지 안에 포함된 그래프/일러스트/표/도형. 각 이미지마다 bbox=[x, y, w, h](픽셀 단위) 추정.
• 이미지의 의미적 placement:
  • between: 지문과 선택지 사이 (가장 흔함 — 그래프/그림 보고 답하는 문제)
  • below: 선택지 다음 (드물지만 연관 자료가 뒤에 올 때)
  • above: 지문 앞 (지시문 위에 그림이 먼저 오는 경우)
  • inline: 지문 텍스트 안에 그림이 끼어들 때 (지시문 일부)

Step 3: ingest.json 작성

스키마는 tools/rhwp-ingest/schema/ingest_schema_v1.json 준수. 샘플은 tools/rhwp-ingest/schema/sample_minimal.json.

핵심 구조:

{
  "version": "1",
  "page_size": {"width_mm": 210, "height_mm": 297},
  "default_font": "함초롬바탕",
  "header_text": "국어 영역",
  "footer_text": "1/20",
  "form_label": "홀수형",
  "passages": [
    {
      "id": "p1-3",
      "blocks": [
        {"type": "text", "text": "[1~3] 다음 글을 읽고 물음에 답하시오."},
        {"type": "text", "text": "긴 공유 지문..."}
      ]
    }
  ],
  "questions": [
    {
      "number": 1,
      "passage_ref": "p1-3",
      "stem": "다음 글의 주제로 가장 적절한 것은?",
      "auto_number": true,
      "stem_blocks": [
        {"type": "text", "text": "다음 글의 주제로 가장 적절한 것은?"},
        {
          "type": "boxed",
          "title": "<보기>",
          "blocks": [
            {"type": "text", "text": "보기 본문..."}
          ]
        },
        {"type": "image", "ref": "img/q1_passage.png", "placement": "between"}
      ],
      "choices": [
        {"label": "①", "text": "선택지 1"},
        {"label": "②", "text": "선택지 2"},
        {"label": "③", "text": "선택지 3"},
        {"label": "④", "text": "선택지 4"},
        {"label": "⑤", "text": "선택지 5"}
      ],
      "media": [
        {"id": "img/q1_passage.png", "natural_w": 800, "natural_h": 600,
         "target_w_mm": 80, "placement": "between"}
      ]
    }
  ]
}

media[].id는 --media-dir 기준 상대 경로. Claude가 Step 4에서 자르기 결과 PNG를 그 경로에 저장.

공유 지문과 보기 박스

• 여러 문제가 같은 지문을 공유하면 top-level passages[] 에 지문을 한 번 작성하고, 각 문제에서 passage_ref 로 참조한다.
• builder는 같은 passage_ref 를 처음 만나는 위치에 공유 지문을 한 번만 출력한다.
• <보기>/[보기]처럼 테두리와 배경이 있는 보조 자료는 stem_blocks 안에 {"type":"boxed","title":"<보기>","blocks":[...]} 로 작성한다.
• header_text, footer_text, form_label 은 시험지 반복 머리말/꼬리말 정보를 구조적으로 전달하는 필드다.

auto_number 필드 사용법 (v2 정책 — Task #660 후속)

빌더는 첫 stem 텍스트 앞에 {number}. prefix를 자동으로 붙인다. 다만 사용자가 stem 텍스트 자체에 번호를 명시적으로 작성한 경우에는 auto_number: false를 함께 설정해 빌더의 자동 prefix를 끈다.

상황	auto_number	stem_blocks 첫 텍스트 예시
일반 문제 (default)	true 또는 미지정	"다음 글의 주제는?" → 빌더가 "1. 다음 글의 주제는?" 생성
공유 지문 그룹 지시문	passages[] 사용 권장	passages[].blocks 에 "[1~3] 다음 글을 읽고 물음에 답하시오." 작성
사용자가 명시적으로 prefix 작성	false	"2. ㉠에 해당하는 내용으로 가장 적절한 것은?" → 그대로 출력
<보기> / [보기] 본문	true	"[보기]를 참고하여…" → 빌더가 "12. [보기]를 참고하여…" 생성

권장: 가능하면 auto_number: true(default) + stem 텍스트는 prefix 없이 작성하는 것이 깔끔하다. 공유 지문은 passages[]/passage_ref 로 분리하고, 사용자가 문제 번호까지 명시적으로 작성한 경우에만 false로 끈다.

Step 4: 이미지 자르기

각 media[] 항목에 대해:

bash .claude/skills/rhwp-exam-ingest/helpers/crop_image.sh \
    "$TMP/page_001.png" \
    "<x>" "<y>" "<w>" "<h>" \
    "$MEDIA_DIR/img/q1_passage.png"

bbox 좌표는 Step 2에서 분석한 것을 사용. ImageMagick magick 명령어 기반.

Step 5: HWPX 빌드

rhwp build-from-ingest "$TMP/ingest.json" --media-dir "$MEDIA_DIR" -o "$OUT_HWPX"

성공 시 사용자에게 결과 파일 경로 + 통계(문제 수, 문단 수, 바이트 크기) 보고.

한계 및 주의사항

현재 알려진 한계

• 이미지 직렬화: rhwp의 HWPX writer가 Picture inline 직렬화 분기를 #182에서 추가 중입니다. #182 완료 전에는 이미지가 HWPX에 포함되어도 한컴이 표시 못 할 수 있습니다. 현재는 텍스트 위주 변환이 안전.
• 수식: 복잡 수식(LaTeX 수준)은 이미지로 캡처하여 Picture로 삽입하는 것이 안전합니다. HWP Equation IR 매핑은 후속 마일스톤.
• 표/정밀 박스: 단순 표는 Picture로 캡처. Table/Frame IR 빌드는 후속 작업.

Vision 분석 정확도 향상 팁

• 시험지가 스캔본이라 흐릿하면 사용자에게 더 선명한 원본 또는 PDF 제공을 요청.
• 한 페이지에 30+ 문제가 빽빽하면 페이지를 절반/사분면으로 나누어 분석.
• 문제 번호 매김이 일관되지 않으면 사용자에게 그룹핑 명시 요청.

검증

생성된 HWPX는 다음으로 확인:

rhwp dump <out.hwpx>      # IR 구조 확인
unzip -l <out.hwpx>       # ZIP 구조 확인 (BinData/ 이미지 포함 여부)

한컴오피스 2024 또는 LibreOffice + hwpx 플러그인으로 시각 확인 권장.

의존성

필수

• rhwp 바이너리 빌드됨 (cargo build --release 후 target/release/rhwp 또는 cargo run --bin rhwp 사용)

PDF 입력 시

• pdftoppm (poppler-utils) 또는 magick (ImageMagick)
• 선택: pdftotext (텍스트 layer 추출)

DOCX 입력 시

• python3 + python-docx: pip install python-docx

이미지 자르기

• magick (ImageMagick 7) 또는 convert (ImageMagick 6)

설치 확인 helper:

bash .claude/skills/rhwp-exam-ingest/helpers/check_deps.sh

참조

• 전체 계획서: ~/.claude/plans/pdf-md-docx-optimized-neumann.md
• spike 결과: mydocs/tech/m100_neumann_spike.md
• JSON 스키마: tools/rhwp-ingest/schema/ingest_schema_v1.json
• 샘플 입력: tools/rhwp-ingest/schema/sample_minimal.json
• 확장 샘플 입력: tools/rhwp-ingest/schema/sample_structured.json
• 빌더 본체: src/document_core/builders/exam_paper.rs
• 관련 이슈: #660 (본 작업 1단계 완료), #182 (Picture 직렬화), #654 (사전 검증 spike)