hwp은(는) 무엇을 하나요?
kordoc을 사용하여 에이전트 네이티브 방식으로 HWP/HWPX 문서를 파싱, JSON 추출, 비교(diff), 양식 필드 추출, 마크다운→HWPX 역변환을 수행합니다(읽기/변환 전용 — 바이너리 편집은 rhwp-edit 사용).
주요 기능
- 문서 파싱 및 JSON 추출 — HWP/HWPX 파일을 읽고 그 내용을 JSON 구조로 변환합니다. 제목, 본문, 표, 목록, 그리기 개체, 필드 코드 등을 계층적으로 추출합니다.
- 문서 비교 (diff) — 두 HWP/HWPX 문서의 구조적 차이를 JSON 형태로 반환합니다. 텍스트 추가/삭제/수정, 표 셀 변경, 개체 이동 등을 추적할 수 있습니다.
- 양식 필드 추출 — HWP 문서 내에 포함된 필드 코드(예:
{필드명})와 해당 값 및 위치 정보를 추출합니다. 서식 문서 양식화 및 자동 채우기에 활용됩니다. - 마크다운→HWPX 역변환 — 마크다운 문서를 읽어 HWPX 형식의 워드프로세서 문서로 변환합니다. 제목(1~5단계), 본문, 굵게/기울임, 코드 블록, 표, 목록, 인용구, 이미지 및 하이퍼링크를 지원합니다.
사용 방법
1. 문서 파싱
# HWP 파일 파싱
kordoc parse sample.hwp
# HWPX 파일 파싱
kordoc parse sample.hwpx
결과는 표준 출력으로 JSON이 출력됩니다.
2. JSON 추출
kordoc extract sample.hwp --format json
3. 문서 비교
kordoc diff file1.hwp file2.hwp
4. 양식 필드 추출
kordoc fields sample.hwp
5. 마크다운 → HWPX 변환
kordoc convert input.md -o output.hwpx
지원 마크다운 요소:
- 제목
#~##### - 본문, 굵게(
**bold**), 기울임(*italic*) - 인라인 코드(
`code`) 및 블록 코드( - 순서 없는 목록(
-), 순서 있는 목록(1.) - 표(표 헤더, 정렬, 셀 병합)
- 인용구(
>) - 이미지 및 하이퍼링크
환경 변수
| 변수명 | 기본값 | 설명 |
|---|---|---|
KORDOC_PATH | kordoc | kordoc 실행 파일 경로 (설치 위치가 PATH에 없을 때 설정) |
HWP_LANG | ko | 출력 언어 (ko, en 등) |
NO_COLOR | (설정되지 않음) | 설정 시 ANSI 색상 출력 비활성화 |
의존성
- kordoc — HWP/HWPX 문서 처리를 위한 CLI 도구 (설치 필수)
- Node.js 18+ 또는 Deno 1.30+ (kordoc 실행 환경)
제한 사항
- 읽기 전용(read/convert only): 생성, 수정, 삭제 등 바이너리 수준의 편집은 지원하지 않습니다. 편집이 필요하면 rhwp-edit를 사용하세요.
- 암호화된 문서는 해독 키가 없는 경우 지원되지 않습니다.
- 이미지 포함된 문서에서 이미지 데이터는 경로/참조로만 추출되며, 메타데이터로 제공됩니다.
예시: AI 에이전트 워크플로
- 사용자가 "이 계약서 HWP 파일을 분석해줘"라고 요청합니다.
- 에이전트가
kordoc parse contract.hwp를 실행하여 JSON 구조를 얻습니다. - 에이전트가 JSON에서 키 필드(당사자, 계약 금액, 조건 등)를 추출합니다.
- 에이전트가
kordoc diff original.hwp reviewed.hwp로 변경 사항을 확인합니다. - 필요 시 에이전트가 마크다운 보고서를 작성하고
kordoc convert report.md -o report.hwpx로 변환합니다.