kordoc

모두 파싱해버리겠다.

대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.

HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX, 이미지(PNG/JPG/WebP) — 관공서 문서를 파싱·비교·생성합니다. English

• 📊 PDF 공개 벤치 1위 — opendataloader-bench 200문서 종합 0.960, 공개 12개 파서(상용 포함)보다 높음 (OCR 끄면 0.937·쪽당 0.04초)
• 🇰🇷 한국 공문서 표 무손실 — 원본 HWPX 를 정답으로 채점해 HWPX 표 13,041개가 칸까지 일치

_{▶ 클릭하면 유튜브에서 재생됩니다.}

목차 — 설치 · 주요 기능 · 성능 · 빠른 시작 · CLI · MCP 서버 · API · 지원 포맷 · 보안 · 최근 변경

---

⚡ 설치

Node.js 20+ 만 있으면 됩니다 (macOS / Linux / Windows).

AI 에이전트 연동 (MCP) — 30초

npx -y kordoc setup

설치된 AI 클라이언트(Claude Desktop · Cursor · Claude Code · Windsurf · VS Code · Gemini CLI · Zed · Antigravity · Codex)를 골라 설정을 자동으로 넣습니다. 재시작하면 17개 문서 도구가 켜집니다.

Claude Code 플러그인

/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

.hwp/.hwpx 파일이나 공문서 작성 요청에 스킬이 자동으로 켜집니다(별도 설치 불필요).

라이브러리 · CLI

npm install kordoc        # CLI 만 쓸 거면 설치 없이 npx kordoc <파일>

PDF·OCR 의존성은 기본으로 설치됩니다(줄이려면 --omit=optional — 대신 PDF·OCR 이 빠짐). PDF 인쇄 렌더(markdownToPdf)만 puppeteer-core 를 따로 설치하세요.

설치 문제 해결

• MODULE_NOT_FOUND / Cannot find module ...\dist\cli.js — 깨진 글로벌 설치가 남은 상태입니다.

  npm uninstall -g kordoc
  npx -y kordoc@latest setup
  

• PowerShell npx.ps1 … PSSecurityException — PowerShell 기본 정책 문제입니다. 명령 프롬프트(cmd)에서 npx -y kordoc setup 을 실행하거나, Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 후 PowerShell 을 다시 여세요.
• 제한 네트워크 linux/x64 에서 PNG 렌더·이미지 OCR 만 MISSING_DEPENDENCY(sharp) (#99) — onnxruntime 의 CUDA 다운로드가 실패하면서 sharp 까지 빠진 경우입니다.

  ONNXRUNTIME_NODE_INSTALL=skip npx -y kordoc@^4 <command> ...
  

• 폐쇄망 — 보안 참고.

---

💡 주요 기능

---

📊 성능

모든 수치는 npm run bench:gate 로 재현되고, 배포 때마다 이 게이트를 통과해야 합니다. 채점 기준·재현 방법·옵션별 수치는 docs/benchmarks.md.

PDF → Markdown (opendataloader-bench 200문서)

논문·보고서·슬라이드·스캔 PDF 200개를 사람이 만든 정답과 비교해 읽기 순서·표 구조·제목 위계를 잽니다(1.0 = 정답).

• 기본값만으로 네 항목 모두 1위 — GPU·클라우드 API·LLM 없이 Node.js 하나로. ocr: false 도 네 항목 모두 1위입니다.
• 기본값은 OCR 모델이 캐시에 있으면 스캔 쪽과 큰 그림 속 글을 자동으로 읽습니다. 그림이 많은 문서가 느려지니 속도가 중요하면 ocr: false.

한국 공문서 — 원본 HWPX 가 정답

HWPX 원본과 그 PDF 가 짝으로 있는 실제 정부 문서(보도자료·결재문서·법령 서식·예산서 등)로 잽니다.

HWP·HWPX → Markdown — HwpForge 비교

같은 코퍼스를 원본 HWPX XML 을 정답으로 같은 채점기에 넣었습니다(1열 표 제외).

표 점수 차이는 대부분 HwpForge 의 파이프 표가 병합 칸을 못 담는 데서 옵니다.

---

🚀 빠른 시작

문서 파싱

import { parse } from "kordoc"
import { readFileSync } from "fs"

const result = await parse(readFileSync("사업계획서.hwpx"))   // 파일 경로 문자열도 받음

if (result.success) {
  result.markdown   // 마크다운
  result.blocks     // IRBlock[] 구조화 데이터
  result.metadata   // { title, author, createdAt, pageMode, ... }
  result.pages      // [{ pageNumber, markdown }] 쪽 단위 본문
}

• pages 는 블록에 쪽 번호가 붙는 포맷(HWP·HWPX·PDF, XLS(X)는 시트 = 한 쪽)에서만 나옵니다. 쪽을 매기지 않는 DOCX 에서는 필드를 생략합니다.
• 쪽 경계 신뢰도는 metadata.pageMode — "layout"(조판 캐시 기반 실제 쪽) / "section"(섹션 근사).

파싱 옵션 (parse(buffer, options) · CLI 플래그)

문서 비교 (신구대조표)

import { compare } from "kordoc"

const diff = await compare(구버전Buffer, 신버전Buffer)   // HWP ↔ HWPX 교차 비교 가능
// diff.stats → { added: 3, removed: 1, modified: 5, unchanged: 42 }
// diff.diffs → BlockDiff[] (표는 셀 단위 diff 포함)

양식 필드 추출 · 채우기

import { parse, extractFormFields, fillForm } from "kordoc"
import { readFileSync, writeFileSync } from "fs"

const r = await parse(buffer)
if (r.success) {
  const form = extractFormFields(r.blocks)
  // form.fields → [{ label: "성명", value: "홍길동", row: 0, col: 0 }, ...], form.confidence → 0.85
}

// HWPX 원본 서식 보존 모드 — 글꼴·크기·정렬 유지
const filled = await fillForm(readFileSync("신청서.hwpx"), {
  성명: "홍길동", 주민등록번호: "900101-1234567", 주소: "서울특별시 광진구 능동로 120",
}, "hwpx-preserve")
writeFileSync("신청서_작성완료.hwpx", Buffer.from(filled.output as ArrayBuffer))
// filled.fill.filled → 채운 필드, filled.fill.unmatched → 매칭 실패한 키

내장 표준 기안문 서식 + 누름틀 채우기

표준 기안문 서식(「행정 효율과 협업 촉진에 관한 규정 시행규칙」 별지)이 패키지에 들어 있어 이름만으로 공문서를 만듭니다. 서식 출처: rhwp (MIT).

npx kordoc fill --list-templates                                # 내장 서식 목록 + 필드
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx
npx kordoc fill templates:간이기안문 -f '제목=…' -o 보고.hwpx     # 위치 인자 표기도 같음

• 누름틀 이름으로 먼저 채우고 남은 키는 라벨로 찾습니다 — 누름틀이 있는 어떤 HWPX 서식에도 동작.
• 여러 줄 값은 문단 안 줄바꿈으로 들어가고, 원본 서식은 그대로입니다.
• API: extractClickHereFields → fillHwpx(buf, 값). MCP fill_form 은 template 파라미터로 같은 서식을 씁니다.

HWPX 생성 (Markdown → HWPX)

import { markdownToHwpx } from "kordoc"

const hwpx = await markdownToHwpx("# 제목\n\n본문\n\n| 이름 | 직급 |\n| --- | --- |\n| 홍길동 | 과장 |")

// display math → HWPX 네이티브 수식(<hp:equation>) — \frac·\sqrt·첨자·Greek·적분/극한·화살표·관계 연산자·matrix 의 LaTeX-like subset
await markdownToHwpx("피타고라스\n\n$$a^2 + b^2 = c^2$$")

// 공문서 모드 — 항목부호 8단계 + 내어쓰기 + 공식 여백/명조 자동
// preset: official | report | plan | notice | minutes | gaejosik | press | ministry(업무보고) | bangchim(서울방침)
await markdownToHwpx("1. 추진배경\n  - 세부 항목\n2. 추진계획", { gongmun: { preset: "보고서" } })

// 정부 표준 개조식 보고서 — 표지·목차(장식 배너)·로마숫자 장헤더·본문 제목박스·쪽번호("- 1 -", 표지·목차 제외)
await markdownToHwpx(md, {
  gongmun: {
    preset: "개조식",
    cover: { org: "기관명", date: "2026. 7. 11." },
    toc: true,                          // h2 목록 → Ⅰ Ⅱ Ⅲ 목차 (개조식 기본 켬)
    approval: ["담당", "팀장", "과장"],   // 결재란 (선택)
    pageNumbers: true,                  // 쪽번호 (개조식·보고서·계획서 기본 켬)
    endMark: false,                     // 본문 끝 "끝." (기안문 기본 켬)
  },
})

• 표는 정부 문서 관행(머리행 음영·이중 하변·내용 비례 열폭)을 자동 적용합니다. 테마·참조 문서 표 서식(hwpxToProfile)도 받습니다.
• CLI: kordoc generate 보고서.md -o 보고서.hwpx --preset 개조식 --org 기관명 --approval 담당,팀장,과장

레이아웃 보존 렌더

한컴이 HWPX 에 저장한 조판 캐시로 원본 모양을 그대로 그립니다(서버에 한컴 불필요). 캐시가 없는 생성본은 내장 reflow 엔진이 조판합니다. 수식 개체는 아직 미지원.

import { renderHwpxToSvg, renderDocument, extractRenderedRegions } from "kordoc"

const r = await renderHwpxToSvg(readFileSync("결재문서.hwpx"), { highlights: ["예산"] })
// r.svg, r.width/r.height (pt), r.pageCount, r.stats { texts, images, tables }, r.warnings
const g = await renderHwpxToSvg(generatedHwpx, { reflow: true })   // 조판 캐시 없는 생성본

// 통합 렌더 — HWPX·HWP(5.x), 페이지별 PNG + 표 영역 crop
const { scene, assets } = await renderDocument("결재문서.hwp", { format: "png", pages: "1-2" })
const crops = await extractRenderedRegions("결재문서.hwp", { types: ["table"] })

CLI: kordoc render 결재문서.hwpx -o 결재문서.svg (--highlight 예산, --no-reflow). 미리보기 앱 연동용 상주 렌더는 kordoc render-worker.

대량 변환 — 상주 파싱 워커

await parse(buffer, { images: false })                   // 이미지 바이트 없이
await parse(buffer, { plain: true, htmlTables: true })   // 글 위주 + 모든 표를 HTML 로

kordoc parse-worker 는 프로세스를 띄워 둔 채 stdin JSON 한 줄마다 한 줄로 답합니다(파일마다 node 를 새로 띄우지 않음).

시작  {"ready":true,"version":"4.16.0","protocol":1}
요청  {"id":1,"file":"문서.hwpx","images":false,"ocr":"off"}
응답  {"id":1,"rss":183500800,"result":{ …--format json 과 같은 결과, 실패도 success:false 로… }}
종료  {"cmd":"quit"}  (또는 stdin 닫기)

요청은 ocr("off"·"auto"·"force")·formulaOcr·password 를 받고, 응답의 rss(메모리)로 워커 교체 시점을 정하면 됩니다.

OCR (스캔·이미지 PDF)

await parse(buffer, { ocr: true })      // OCR 필요 쪽 + 그림 속 글 (PP-OCRv5 korean, 첫 사용 시 모델 ~18MB 다운로드)
await parse(buffer, { ocr: "force" })   // 전 쪽 강제
await parse(buffer, {                   // 외부 OCR (Claude Vision, Tesseract 등)
  ocr: async (pageImage, pageNumber, mimeType) => myOcrService.recognize(pageImage),
})

• API 키 없이 로컬 CPU 로 읽습니다(PP-OCRv5 korean ONNX — 완성형 한글 11,172자 전량).
• 텍스트층이 없거나 깨진 쪽만 OCR 하고, 스캔본의 표 구조도 복원합니다.
• 모델 관리: kordoc models --status (폐쇄망은 --export/--import).

PDF 텍스트 품질 신호

parsePdf 는 쪽별 품질 신호를 줍니다 — 텍스트층이 깨진 쪽을 골라 OCR 로 보낼 수 있습니다.

const r = await parsePdf(buffer)
if (r.success && r.qualitySummary?.needsOcr) await parse(buffer, { ocr: true })   // 또는 외부 OCR 큐로
for (const p of r.pageQuality ?? []) if (p.needsOcr) console.log(`p${p.page} 검토 필요: ${p.ocrReason}`)

신호: textChars·hangulRatio·controlCharRatio·replacementCharRatio·puaRatio, needsOcr, ocrReason(low_text·high_pua·high_control·high_replacement·garbled_hangul·vector_text).

---

💻 CLI

# 변환
npx kordoc 사업계획서.hwpx                           # 터미널 출력
npx kordoc 보고서.hwp -o 보고서.md                   # 파일 저장 (그림은 images/보고서/)
npx kordoc *.pdf -d ./변환결과/                      # 일괄 변환
npx kordoc 검토서.hwpx --format json                # JSON (blocks + pages + metadata)
npx kordoc 검토서.pdf --format chunks               # RAG 구조 청크 JSON (breadcrumb + 표 독립 청크)
npx kordoc 보고서.hwpx --pages 1-3                   # 쪽 범위
npx kordoc 스캔본.pdf --ocr                          # 내장 OCR (--ocr-force 로 전 쪽)
npx kordoc 잠긴문서.hwpx --password '암호'            # 열기 암호 HWPX/HWP3/HWP5
npx kordoc 시험지.pdf --no-tables                    # PDF 표 감지 끄기
npx kordoc 문서.pdf --format json --no-images         # 이미지 없이 (--plain·--html-tables 도 있음)

# 양식 채우기
npx kordoc fill 신청서.hwpx -f '성명=홍길동,주소=서울' -o 결과.hwpx
npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx
npx kordoc fill 신청서.hwpx --dry-run                              # 필드 목록만 (누름틀 포함)
npx kordoc fill 신청서.hwpx -j 값.json --formats '{"날짜":"yy.mm.dd"}' # 필드별 값 서식
npx kordoc fill 신청서.hwpx -j 값.json --require-unique            # 한 키가 2곳 이상 매칭되면 거부
npx kordoc fill 신청서.hwpx -j 값.json --mask                      # stdout 에 채운 값 대신 안내만
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx           # 내장 표준 기안문 (--list-templates)

# 생성 · 편집 · 검증
npx kordoc generate 보고서.md -o 보고서.hwpx --preset 보고서        # Markdown → 공문서 HWPX
npx kordoc patch 원본.hwpx 편집.md -o 반영.hwpx                    # 서식 보존 패치 (.hwp 도 자동)
npx kordoc seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 날인.hwpx
npx kordoc validate 산출물.hwpx                                    # HWPX 구조 검증 (ZIP·필수 파트·XML)
npx kordoc lint 보고서.md                                          # 공문서 표기법 19룰 (md/txt, '-'=stdin, error 면 exit 1)
npx kordoc profile 기관서식.hwpx                                   # 표 서식 프로필 JSON → generate --profile

# 개인정보 마스킹
npx kordoc redact 민원서류.hwpx -o 마스킹.hwpx                      # 서식 보존 마스킹 + 잔존 재검사 (남으면 exit 2)
npx kordoc redact 민원서류.hwpx --mask-char '*' -o 마스킹.hwpx      # 마스크 문자 (기본 ●)
npx kordoc redact 계약서.hwp --rules rrn,phone,crn --json --dry-run # 룰 선택 + 위치별 리포트만 (crn·IP 는 opt-in)
npx kordoc redact 민원서류.hwpx --rules rrn,phone,email,name,address -o 마스킹.hwpx  # 이름·주소까지 (opt-in)
npx kordoc redact 공문.pdf                                         # PDF·DOCX 등은 마스킹된 .redacted.md 만

# 렌더
npx kordoc render 결재문서.hwpx -o 미리보기.svg                     # 레이아웃 보존 SVG (캐시 없으면 reflow)
npx kordoc render 결재문서.hwpx --format png --pages 2-4 -d ./pages # PNG·JPEG·HTML·PDF 도
npx kordoc render 결재문서.hwpx --reflow-mode charAll -o 미리보기.svg # reflow 줄바꿈 keep(어절, 기본)|charAll(글자)

# 모델 · 감시
npx kordoc models --status                          # OCR 모델 상태 (--export/--import 폐쇄망 사이드로드)
npx kordoc check-ocr-models --status-only           # 상태만 JSON (옵션 빼면 없는 모델을 받음)
npx kordoc check-formula-models --status-only       # 수식 OCR 모델(MFD+MFR+tokenizer, ~155MB) 상태만
npx kordoc watch ./수신함 -d ./변환결과              # 폴더 감시 (하위 폴더 구조 유지)
npx kordoc watch ./문서 --webhook https://api/hook  # 웹훅 알림

• watch -d 는 하위 폴더 구조를 그대로 둡니다.
• check-ocr-models·check-formula-models 는 없는 모델을 내려받습니다 — 상태만 보려면 --status-only.
• lint 는 Markdown·텍스트용입니다. HWPX 는 kordoc 문서.hwpx | kordoc lint -.

실패 계약 — 기계 판독 가능한 실패 JSON

변환 실패는 모든 --format 에서 stdout 에 아래 JSON 을 내고 exit 1 로 끝납니다 — code 로 분기하세요.

{ "success": false, "fileType": "hwpx", "file": "보고서.hwpx", "error": "암호화된 문서입니다 …", "code": "ENCRYPTED" }

• 실패는 언제나 success:false 객체라 성공 출력(텍스트·배열)과 겹치지 않습니다. 여러 파일이면 실패마다 한 줄씩 나옵니다.
• 종료 코드와 필드는 유지되고 code 값은 추가만 됩니다. error 문구는 사람용이라 계약이 아닙니다.

이미지 번들 — images/<문서 이름>/manifest.json

-o/-d 로 저장하면 그림은 문서마다 images/<문서 이름>/ 에 manifest.json 과 함께 저장됩니다(같은 폴더로 여러 문서를 변환해도 안 덮어씀). --format json --image-refs 는 바이트 대신 경로만 남깁니다.

[ { "name": "image_001.png", "mimeType": "image/png", "bytes": 68, "source": "BinData/image1.png" } ]

• mimeType 은 파일 머리(매직바이트)로 확인한 값, source 는 원본 컨테이너 안 경로입니다.
• 그림은 원본 그대로 저장합니다(PDF 만 PNG 로 재인코딩). 형식은 확장자보다 mimeType 을 믿으세요.

---

🤖 MCP 서버

자동 설치는 npx -y kordoc setup. 수동 등록:

codex mcp add kordoc -- npx -y kordoc mcp          # Codex

{ "mcpServers": { "kordoc": { "command": "npx", "args": ["-y", "kordoc", "mcp"] } } }

Windows 에서 Claude Desktop 이 .cmd 를 못 찾으면 "command": "cmd", "args": ["/c", "npx", "-y", "kordoc", "mcp"].

17개 도구

---

📚 API

파싱

PPTX 는 감지만 합니다(parse() 는 UNSUPPORTED_FORMAT). ZIP 종류를 가르려면 detectFormat() 이 hwpx 일 때 await detectZipFormat(buffer) 를 쓰세요.

비교 · 양식 · 편집

생성 · 렌더

텍스트 · 변환 도구

타입

import type {
  ParseResult, ParseSuccess, ParseFailure, FileType,
  IRBlock, IRBlockType, IRTable, IRCell, CellContext,
  DocumentMetadata, ParseOptions, ErrorCode, OutlineItem,
  DiffResult, BlockDiff, CellDiff, DiffChangeType,
  FormField, FormResult, FormFieldType, FormFieldSchema, FormSchemaResult,
  FillResult, HwpxFillResult, FillOutputFormat, FillFormOutput,
  ClickHereField, BuiltinTemplate,
  PatchOptions, PatchResult, PatchSkip,
  HwpxTheme, MarkdownToHwpxOptions, PageOptions,
  PrintPreset, PrintOptions, PageMargin,
  RenderSvgOptions, RenderSvgResult,
  SealOp, SealPlacement, PlaceSealResult,
  ValidateResult, ValidateIssue,
  RedactRule, RedactOptions, RedactHit, RedactTextResult,
  DocChunk, ChunkOptions, GongmunLintFinding,
  OcrProvider, WatchOptions,
} from "kordoc"

---

📂 지원 포맷

---

🔒 보안

• ZIP·압축 폭탄, XXE, 경로 순회, SSRF 를 막습니다 — 자세한 내용은 SECURITY.md.
• 폐쇄망: KORDOC_OFFLINE=1 은 모든 외부 통신을 막고, KORDOC_ROOT=<디렉토리> 는 MCP 파일 접근을 그 안으로 제한합니다. 오프라인 설치 번들·모델 옮기기는 docs/offline-deployment.md.

---

📝 최근 변경

v4.16.3

• 보안: MCP 문서 생성이 이미지 폴더 안 심링크로 KORDOC_ROOT 밖 파일을 싣던 것 차단 (#101) · MCP 도 한글 이름 그림 지원

v4.16.2

• 위·아래첨자를 <sup>·<sub> 로 — "10⁴ m²" 가 "104 m2" 로 펴지지 않게 (scriptTags, HWPX·HWP·DOCX 기본 켬, 논문·수식 PDF 는 true)
• PDF 2단 논문 저자 줄의 소속 표시(∗†)가 이름 위로 떨어지던 것 수정

전체 이력은 CHANGELOG.md.

---

만든 사람

대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.

라이선스

MIT. 이 프로젝트는 아래 오픈소스를 포함합니다:

• rhwp (MIT, edwardkim) — HWP5 배포용 복호화·lenient CFB 파싱 알고리즘, templates/ 의 기안문 서식
• claw-hwp (MIT, DoHyun468) — OOXML chartSpace 조립, 도장 부유 배치 메트릭, secure-fill 포맷엔진, validate 검사셋
• OpenDataLoader PDF (Apache 2.0, Hancom Inc.) — PDF 표 감지 알고리즘
• hml-equation-parser (Apache 2.0, Open Bapul) — HML 수식 파싱
• PaddleOCR (Apache 2.0, PaddlePaddle) — 텍스트 OCR 엔진 파생 (PP-OCRv5 korean)
• Pix2Text (MIT, breezedeus) — 수식 OCR(MFD/MFR) 알고리즘 포팅. 모델은 런타임 다운로드이며 재배포하지 않습니다 — MFD 가중치의 기반인 Ultralytics YOLOv8 은 AGPL-3.0 이므로 수식 OCR 에 의존하는 상용·비공개 제품은 해당 조건을 별도 확인하세요
• cfb (Apache 2.0, SheetJS) — HWP5 OLE2 컨테이너 파싱
• pdfjs-dist (Apache 2.0, Mozilla) — PDF 텍스트 추출
• JSZip (MIT, Stuart Knightley 외) — ZIP 기반 포맷 파싱

전체 고지는 NOTICE, 라이선스 전문은 THIRD_PARTY/ — 둘 다 npm 배포 패키지에 포함됩니다.