Skip to content

hwp.md

Latest commit

 

History

History
142 lines (104 loc) · 4.86 KB

hwp.md

File metadata and controls

142 lines (104 loc) · 4.86 KB

HWP 문서 처리 가이드

이 기능으로 할 수 있는 일

  • .hwp, .hwpx, .hwpml 문서를 Markdown으로 변환
  • 문서를 JSON으로 구조화해 blocks, metadata까지 AI에 넘기기
  • 폴더 단위 배치 변환
  • watch로 폴더를 감시하며 새 문서를 계속 변환
  • 두 버전 문서 비교
  • HWPX 양식 필드 추출
  • Markdown을 다시 HWPX로 역변환

먼저 필요한 것

  • Node.js 18+
  • CLI를 한 번만 쓸 때: npx --yes --package kordoc --package pdfjs-dist kordoc --help
  • 반복 실행용 전역 설치: npm install -g kordoc pdfjs-dist
  • Node API 예시를 따라갈 로컬 작업 디렉터리: npm init -y && npm install kordoc pdfjs-dist
  • 현재 배포된 kordoc CLI는 시작 시 pdfjs-dist를 바로 불러오므로 PDF를 안 다뤄도 함께 설치해야 한다
  • import { markdownToHwpx } from "kordoc" 같은 ESM 예시는 전역 NODE_PATH가 아니라 로컬 설치 기준으로 실행해야 한다

어떤 경로를 선택하나

이 스킬의 기본 경로는 항상 kordoc 이다.

  • 문서 읽기/변환 → kordoc
  • 구조화 JSON 추출 → kordoc --format json
  • 연속 입력 폴더 처리 → kordoc watch
  • 양식 필드 추출 → parse() + extractFormFields()
  • 역변환 → markdownToHwpx()
  • 문서 비교 → compare()

이 스킬은 단일한 kordoc 경로를 표준 흐름으로 유지한다.

기본 흐름

  1. kordoc이 없으면 설치한다.
  2. .hwp/.hwpx/.hwpml을 Markdown 또는 JSON으로 변환한다.
  3. 표·이미지·메타데이터가 필요하면 JSON의 blocks / metadata를 확인한다.
  4. 반복 입력 폴더는 watch, 양식 문서는 extractFormFields, 편집 roundtrip은 markdownToHwpx 경로로 이어간다.
  5. 결과 파일 생성 여부와 구조를 확인한다.

예시

Markdown 변환

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp -o 보고서.md

JSON 변환

npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json

배치 처리

npx --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과

페이지 범위 지정

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3

디렉터리 감시 변환

npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함

양식 필드 추출

아래 Node API 예시는 package.json이 있는 로컬 작업 디렉터리에서:

npm init -y
npm install kordoc pdfjs-dist

이미 package.json이 있으면 npm install kordoc pdfjs-dist만 추가로 실행하면 된다.

node --input-type=module - <<'EOF'
import { parse, extractFormFields } from "kordoc";

const result = await parse("신청서.hwpx");
if (!result.success) {
  console.error(result.error);
  process.exit(1);
}

console.log(JSON.stringify(extractFormFields(result.blocks), null, 2));
EOF

Markdown → HWPX 역변환

node --input-type=module - <<'EOF'
import { markdownToHwpx } from "kordoc";
import { writeFileSync } from "node:fs";

const hwpx = await markdownToHwpx("# 제목\n\n본문\n\n| 항목 | 값 |\n| --- | --- |\n| 성명 | 홍길동 |");
writeFileSync("출력.hwpx", Buffer.from(hwpx));
EOF

문서 비교

node --input-type=module - <<'EOF'
import { compare } from "kordoc";
import { readFileSync } from "node:fs";

const before = readFileSync("이전버전.hwp");
const after = readFileSync("최신버전.hwpx");
const diff = await compare(before, after);
console.log(diff.stats);
EOF

결과 확인 포인트

  • Markdown 출력: 제목/본문/표가 기대한 순서로 정리됐는지 확인한다.
  • JSON 출력: success, blocks, metadata가 있는지 확인한다.
  • 이미지/표 구조: blocks 안 image, table 타입이 필요한 만큼 잡혔는지 확인한다.
  • 배치 처리: 입력 개수와 출력 개수가 크게 어긋나지 않는지 확인한다.
  • 양식 필드 추출: extractFormFields(result.blocks) 결과가 비어 있지 않은지 확인한다.
  • 역변환: 생성된 .hwpx 가 열리고 기본 서식/테이블이 유지되는지 확인한다.
  • 문서 비교: diff.stats 의 added / removed / modified 값이 입력 변화와 맞는지 확인한다.

주의할 점

  • 손상된 문서나 일부 특수 양식은 경고가 섞일 수 있다.
  • 이미지 기반 PDF는 OCR provider가 없으면 품질이 제한될 수 있다.
  • 양식 필드 추출은 템플릿 라벨 품질에 따라 일부 필드가 인식되지 않을 수 있다.
  • 공문서 자동화 목적이면 Markdown만 보는 것보다 JSON blocks를 같이 확인하는 편이 안전하다.
  • 현재 배포본 기준으로 문서화된 CLI 명령은 기본 변환과 watch 이며, 양식 처리와 비교는 Node API 예시를 기준으로 잡는 편이 안전하다.