kordoc

모두 파싱해버리겠다.

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

HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX — 관공서에서 쏟아지는 모든 문서를 파싱하고, 비교하고, 분석하고, 생성합니다.

English

---

⚡ 30초 설치 (AI 에이전트 연동)

macOS / Linux / Windows 공용. Node.js 18+ 만 있으면 됩니다.

npx -y kordoc setup

대화형 마법사가:

1. 사용 중인 AI 클라이언트 번호 선택 (Claude Desktop / Cursor / Claude Code / Windsurf / VS Code / Gemini CLI / Zed / Antigravity — 설치된 건 [감지됨] 표시)
2. 설정 파일 자동 패치 → 클라이언트 재시작

Windows 도 자동으로 cmd /c npx 래핑. 수동 JSON 편집 불필요. 재시작하면 10개 문서 도구 (parse_document, parse_table, fill_form, patch_document, generate_document 등) 활성화.

CLI 로만 쓸 거면 설치 없이 npx kordoc 바로 사용. 아래 CLI 섹션 참고.

MODULE_NOT_FOUND / Cannot find module ...\dist\cli.js 가 뜨면: 과거에 깨진 글로벌 설치가 남아있는 상태입니다. 아래로 해결:

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

Windows PowerShell 에서 npx.ps1 파일을 로드할 수 없습니다 · PSSecurityException 이 뜨면: PowerShell 기본 보안 정책이 서명 없는 .ps1 을 차단하는 표준 동작입니다 (kordoc 무관). 아래 중 하나 쓰시면 됩니다.

방법 1 — 명령 프롬프트(cmd) 창에서 실행 (가장 안전) 윈도우 키 → cmd 검색 → Enter → 검은 창에서 그대로:

npx -y kordoc setup

방법 2 — PowerShell 실행 정책 한 번만 완화 관리자 권한 PowerShell:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

이후 PowerShell 재시작 → npx -y kordoc setup 그대로 됨.

Claude Code 플러그인으로 설치

MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:

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

.hwp/.hwpx 언급이나 공문서 생성·서식 채우기 요청 시 kordoc 스킬이 자동 활성화됩니다 (내부에서 npx -y kordoc@^3 CLI 호출 — 별도 설치 불필요).

---

💡 kordoc으로 무엇을 할 수 있나요?

단순한 텍스트 추출을 넘어, 공문서 처리를 위한 모든 과정을 자동화합니다.

• 📄 어떤 문서든 마크다운으로: HWP3 (구버전), HWP(5.x), HWPX, HWPML, PDF, XLS, XLSX, DOCX 파일을 즉시 Markdown으로 변환합니다. AI(LLM)가 문서를 읽고 분석하기 가장 좋은 상태로 만들어줍니다.
• 📊 복잡한 표(Table) 완벽 재현: 선이 없는 PDF나 복잡하게 병합된 HWP 표도 구조를 분석하여 정확한 마크다운 테이블로 복원합니다. 법령 개정안 PDF의 신구조문대비표도 통째로 살립니다 (v3.16.2).
• 🔍 신구대조표 자동 생성: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (HWP와 HWPX 간의 비교도 가능!)
• 📝 마크다운을 다시 HWPX로: AI가 작성한 내용을 다시 보고서 양식(HWPX)으로 되돌려줍니다. 이제 복사-붙여넣기 노가다에서 해방되세요.
• 🔄 서식 보존 무손실 라운드트립 (v3.0): 변환된 마크다운을 편집해서 patchHwpx(HWPX) / patchHwp(HWP 5.x 바이너리)에 넘기면, 원본 서식을 1바이트도 건드리지 않고 바뀐 문단/표 셀의 텍스트만 원본 안에서 교체합니다. v3.7부터는 표에 행을 추가/삭제하는 편집도 원본 서식을 승계하며 반영되고, v3.8부터는 HWP 5.x의 빈 셀에 값 넣기도 지원합니다.
• 🖼️ 레이아웃 보존 렌더 (v3.10~3.15): 한컴이 저장한 조판 캐시 좌표로 원본 레이아웃을 SVG로 재현하고, 캐시가 없는 파일(AI가 만든 HWPX·편집본)은 순수 TS reflow 엔진이 직접 조판합니다. 다페이지·표·그리기 도형·검색어 형광펜까지. 서버에 한컴 없이 HWPX 미리보기를 만들 수 있습니다.
• 📊 차트 생성 (v3.16): 마크다운의 ```chart 펜스(type/cat/계열 라인)가 한컴 네이티브 차트(OOXML chartSpace)로 생성됩니다 — 막대·선·원·도넛·영역·분산·방사형 등 20종, 계열/조각 색 지정 가능.
• 🔴 도장/서명 자동 날인 (v3.16): “(인)”·“서명 또는 인” 같은 앵커 문구를 찾아 도장 PNG를 글 앞 부유로 배치합니다. 표/페이지를 키우지 않아 날인 후 서식이 밀리지 않습니다 (kordoc seal).
• ✏️ 양식 자동 채우기: 공문서 양식 템플릿(신청서, 보고서)에 값을 넣으면 자동으로 빈칸을 채웁니다. 원본 서식(글꼴, 크기, 정렬)을 100% 보존합니다.
• 🤖 AI 에이전트 연동 (MCP): Claude, Cursor와 같은 도구에서 직접 kordoc을 호출해 문서를 읽고 코딩할 수 있습니다.

---

v3.17.0 변경사항

• 🖼️ 레이아웃 렌더 충실도: 글꼴이 문서 지정대로 나오는 per-run 폰트(고딕 제목이 바탕체로 나오던 것 해소), 표지+본문 다구역 문서 전체 렌더, 가로(landscape) 문서 프레임 회전(우측 잘림 해소), 연속 표 문단의 페이지 포개짐 분리.
• ✍️ 결재란 겹침 해소 (reflow): 조판 캐시 없는 문서에서 결재란 라벨표·스탬프표가 같은 자리에 포개 찍히던 것을 한컴과 동일하게 나란히 배치. 중첩표 셀 높이 과소측정도 함께 수정.

v3.16 변경사항

• 📊 차트 생성: 마크다운 ```chart 펜스(type/cat/계열 라인)가 한컴 네이티브 차트(OOXML chartSpace)로 생성됩니다 — 막대·선·원·도넛·영역·분산·방사형 등 20종, 계열/조각 색 지정, 잘못된 펜스는 코드블록 폴백.
• 🔴 도장/서명 자동 날인: kordoc seal — “(인)”·“서명 또는 인” 앵커를 찾아 도장 PNG를 글 앞 부유로 배치. 표/페이지를 키우지 않아 날인 후 서식이 밀리지 않습니다 (MCP place_seal 포함). 중첩표·글상자·탭/줄바꿈 문단은 위치가 근사이며 결과 warnings 로 고지됩니다 — 한컴에서 확인 후 --dx/--dy(dx_mm/dy_mm)로 미세조정하세요.
• 🔌 Claude Code 플러그인: /plugin marketplace add chrisryugj/kordoc → .hwp/.hwpx/공문서 요청에 kordoc 스킬 자동 활성화.
• 🩹 3.16.1 패치: 통합 검증 리뷰 결함 55건 일괄 수정 — 도장 배치(rowspan·colspan·중첩표 원점), 차트 값 파서(천단위 콤마·CRLF 마크다운), 양식 채우기 가드(require_unique), CLI fill -o 출력 등 “성공 메시지 뒤에 조용히 틀린 산출물” 계열 소탕.
• 🩹 3.16.2 패치: 신구조문대비표의 `` 표기를 텍스트 상자로 오인해 표 전체를 문단으로 해체하던 PDF 파서 결함 수정 — 30p 개정안 대비표가 통째 1표로 복원.

v3.15.0 변경사항

• 🖋️ reflow 렌더 (캐시 없는 파일도 조판): markdownToHwpx 산출물·AI 생성본·편집본처럼 조판 캐시(linesegarray)가 없어 렌더가 거부되던 HWPX를 renderHwpxToSvg(buf, { reflow: true }) / kordoc render --reflow로 순수 TS 조판합니다. 검증된 줄나눔 엔진(실측 98% 일치) + 실측 세로 모델로 lineseg를 합성해 기존 렌더 파이프(정렬·표·이미지·형광펜·다페이지)를 재사용합니다. 단문단·표 셀·표 밀어내기·자동 페이지 분할. 한컴 저장본은 캐시 재생 그대로(무회귀).
• 🔺 그리기 도형 렌더: 사각형·타원·선·다각형·호를 SVG로 그립니다(선 색·굵기·점선, 채움, 크기 스케일). 조직도·화살표 등 “원본과 다르게 보이던” 큰 원인을 해결했습니다.
• 🚀 persistent 렌더 워커: kordoc render-worker가 프로세스를 유지하며 연속 렌더 요청(stdin NDJSON)을 처리해 node 콜드스타트를 없앱니다(미리보기 앱 연동용).

v3.14.0 변경사항

• 📄 렌더 다페이지 지원: kordoc render가 전 페이지를 세로 스택 SVG로 그립니다(페이지별 흰 배경·경계선·클립, data-page 속성, RenderSvgResult.pageCount). 기존엔 전 페이지가 첫 장 한 장에 겹쳐 그려졌습니다.
• 🖍️ 렌더 검색어 형광펜: --highlight / RenderSvgOptions.highlights — 텍스트를 매치 경계로 분할해 매치 세그먼트에만 배경을 깝니다(대소문자 무시, textLength 동일 계산으로 정렬 오차 없음).
• 📐 줄 경계 정합: lineseg textpos를 HWP5 문자 스트림 슬롯(컨트롤 8·문자형 컨트롤 1·서로게이트 2슬롯) 기준으로 재구성해, 컨트롤·탭이 섞인 문단에서 첫 줄에 글자가 몰리고 다음 줄이 비던 어긋남을 해결했습니다(데모 1,132개 멀티라인 문단 검증).
• 🖼️ 이미지 크롭 오판 수정: imgClip을 imgDim(내용 상자) 기준으로 해석 — 삽입 후 리사이즈된 이미지(로고 대부분)가 좌상단 코너로 잘못 잘려 깨지던 문제를 해결했습니다(데모 pic 267개 검증).

v3.13.0 변경사항

• 📄 프로즈 박스 감지: 상단 라벨탭(제목 칩)이 박스 테두리에 걸쳐 만든 가짜 열 위로 본문이 전폭으로 흐르는 표(검정고시 응시자격 박스 등)를 감지해, 셀 경계에서 조각나던 본문을 자연 읽기 순서의 문단으로 복원합니다. 기하(전폭 행 지배)와 텍스트(긴 프로즈 셀)의 교집합에서만 발동해 정규 표는 건드리지 않습니다.
• 📝 HML 표 캡션 보존: 표에 딸린 도형 캡션(※ …참조 등)이 hwpml 파싱에서 통째로 소실되던 문제를 수정했습니다. 캡션을 표 앞/뒤 문단으로 보존합니다.

---

v3.12.0 변경사항

• 🏷️ 라벨 헤더 표 강등 면제: 첫 행이 라벨(채용분야|담당업무|우대조건, 성명|응시분야|비고)인 표가 본문 셀의 ○/ㅇ 항목부호나 빈 기입란 때문에 텍스트 박스로 오인돼 문단으로 강등되던 문제를 수정했습니다. 예산표·업무분장표·양식 표가 표로 살아납니다.
• 🔗 개방 변 합성 체인 뷰: 중간 괘선을 셀 경계마다 쪼개 그은 표(문의처 연락처 표 등)도 세그먼트를 논리적으로 이어 좌우 개방 변을 닫습니다. 물리 선은 건드리지 않아 기존 표의 셀 배치에 부작용이 없습니다.
• 📊 PDF 표 구조 벤치: 표 매칭 90.3→98.6%, 완전 일치 58.3→65.2%, cellF1 0.652→0.724. 채점기에 잡매칭 차단(bag 교집합 0)·세밀 분할 프로즈 박스 구제(접두 유사도 폴백)를 더하고, 흐름띠·빈 스캐폴딩 표는 모수에서 제외했습니다.

v3.11.0 변경사항

• 📐 PDF 개방형 표 복원: 한국 행정문서에 흔한 좌/우 바깥 테두리 생략 표(수평 괘선만 전폭, 수직선은 내부 구분선만)에서 가장자리 열이 통째로 사라지던 것을 가상 테두리 합성으로 복원합니다. 채용공고류에서 6열 표가 4열로 찢기고 남은 열·본문이 13x2 유령 표로 흡수되던 병리가 완치됐습니다.
• 🎨 글상자 음영의 괘선 오염 차단: 한컴 PDF가 제목 글상자의 그라디언트 배경을 촘촘한 수평선 수십 개로 내보내, 선 병합 단계에서 실제 상하 테두리까지 삼키던 것을 음영 스택 필터로 걸러냅니다.
• 📊 PDF 표 구조 벤치: hwpx↔pdf 쌍 GT 대조에서 표 매칭 84.7→90.3%, 완전 일치 54.2→58.3%, cellF1 0.632→0.652.

v3.10.0 변경사항

• 🖼️ 레이아웃 보존 렌더: kordoc render 문서.hwpx -o 문서.svg / renderHwpxToSvg(buffer) — 한컴이 저장한 조판 캐시(줄 좌표·셀 그리드·개체 앵커)를 SVG 절대배치로 그려 원본 레이아웃을 재현합니다. run별 글자 크기/굵기/색/장평/자간, 문단 정렬, 셀 배경·테두리, 병합 셀, 인라인 개체, 이미지 크롭까지. 한컴 저장본 전용(1페이지).
• 🔧 uint32 음수 좌표: vertOffset="4294967103"(= −193) 같은 uint32 저장 음수를 올바르게 해석합니다.
• 🔧 셀 내부 COLUMN 기준계: 셀 안 개체의 horzRelTo="COLUMN"을 셀 영역 기준으로 해석합니다 (사진이 페이지 왼쪽으로 튀던 문제).

v3.9.0 변경사항

• 🧮 Markdown 수식 → HWPX native 수식 생성: $$ \frac{a}{b} $$ 같은 display math 블록이 한컴 수식 개체(``)로 생성됩니다. \frac·\sqrt·첨자·그리스 문자·적분/극한·행렬(matrix/pmatrix/bmatrix)·\left( 구분자·\text 리터럴 지원. 생성한 수식은 kordoc으로 다시 파싱해도 같은 LaTeX로 돌아옵니다 (#38, @leehuiso 기여).
• 🛡️ 수식 입력 가드: 닫히지 않은 $$가 문서 전체를 삼키던 문제(일반 문단 폴백), 중괄호 폭탄 크래시(깊이/길이 상한), 닫는 $$ 뒤 텍스트 소실을 수정했습니다.
• 📋 공문 모드 번호 연속: 항목 사이에 수식이 끼어도 항목 번호가 이어집니다 (표와 동일).
• ⚖️ 법령 문서 왕복 무결성 게이트: 조문 번호 뒤 분리·문장 중간 끊김이 없음을 실측(민원처리법 전문 228문단)하고 벤치 게이트로 고정했습니다.

v3.8.4 변경사항

• 📑 DOCX 병합표·텍스트박스 복구: 병합표에서 셀이 통째로 빠지던 버그(세로 병합 미동작 포함)와 텍스트박스 내용 전체 유실을 수정 — 신고서류·KS표준안류 회수율 0.67/0.92 → 1.0/0.998.
• 🔒 개인정보 마스킹 별표 보호: ******·홍** 같은 마스킹 별표가 마크다운 수평선/볼드로 오독되던 것을 이스케이프로 보존합니다 (별표 각주 * 단, …의 리스트 오인도 해소).
• 🔁 md→HWPX 왕복 충실도 0.947→0.9996: 재변환한 HWPX를 다시 파싱해도 헤딩 레벨·리스트 번호(2. 3. 4. 시작 보존)·마스킹 문자가 그대로 살아납니다. 생성 문서는 한컴 "문서 찾아가기"에 개요 구조로 표시됩니다.
• #️⃣ 개요 번호 발명 수정: 번호 서식을 비운 개요 문단(한컴 “번호 없음”)에 파서가 “1.” 접두를 만들어 붙이던 버그 수정.

v3.8.3 변경사항

• 📰 2단 조판 문서(속기록류) 읽기 복원: 2단 본문이 2열 표로 흡수돼 좌우 단의 문장이 뒤섞이던 버그 수정 — 단을 분리해 올바른 순서로 읽습니다.
• 🛡️ 손상 PDF 처리 시간 폭주 가드: 좌표가 오염된 비정상 PDF에서 파싱이 144초까지 걸리던 것을 2초대로 차단합니다 (정상 문서 출력 무변화).
• 📗 한셀(HCell)로 저장한 XLSX 복구: "시트가 없습니다"로 실패하던 한셀 저장 파일이 정상 파싱됩니다.
• 📋 HML 문서의 표 소실 수정: 문단에 앵커된 표가 통째로 빠지고 중첩표 내용이 사라지던 버그 수정 — 표 텍스트 회수율 0.23 → 0.99.

v3.8.2 변경사항

• 📐 변환(축소/플립) 깔린 PDF의 괘선 표 복구: 성과계획서류처럼 콘텐츠에 변환 행렬이 깔린 문서에서 표 감지가 통째로 실패하던 버그 수정 — 2줄 머리글 셀도 rowspan 병합으로 정상 복원됩니다.
• 📄 스캔 PDF의 임베디드 텍스트층 복구: CID 폰트 텍스트가 조용히 소실되던 문제 수정 — "스캔본"으로 보이던 의사록에서 전문 텍스트를 추출합니다 (일부 문서는 pdftotext보다 잘 읽습니다).

v3.8.1 변경사항

• 🔄 PDF 회전 텍스트 복구: 90°로 눕힌 사이드탭 목차·세로 표(계속비 총괄표 등)가 숨김 텍스트로 오인돼 통째로 빠지던 버그 수정 — 이제 보이는 회전 텍스트도 추출됩니다. (숨김텍스트 prompt-injection 방어는 그대로)
• 🧱 내부 구조 정리: PDF 선 감지(1,247줄)·HWPX 파서(1,619줄) 대형 파일을 목적별 15개 모듈로 분리 — 공개 API·출력 100% 동일 (실파일 87건 해시 검증).

v3.8.0 변경사항

• ✏️ HWP 5.x 빈 셀 채우기 (patchHwp): 원본에서 비어 있던 표 셀에 마크다운 편집으로 값을 넣으면 이제 HWP 바이너리에도 삽입됩니다. 한컴이 빈 문단을 저장하는 방식(텍스트 레코드 생략형 포함)을 실파일 실측으로 지원. (실파일 12건 무손상 검증)
• 🏛️ 공문 항목 사이 표: "1. 항목 → 근거 표 → 2. 항목"처럼 리스트 사이에 표가 끼어도 항목 번호가 이어집니다 (공문서 모드).
• 🚀 이미지 대량 참조 메모리 폭발 해소: 같은 이미지를 수천 개 도형이 참조하는 문서(HWP·HWPX)에서 참조마다 데이터를 복사하다 피크 17GB로 죽던 것을 445MB·0.2초 완주로 수정.
• 📢 DOCX 관측성: 이미지/스타일/번호/각주/메타 파싱 실패를 조용히 넘기지 않고 warnings로 보고합니다.

v3.7.0 변경사항

• 📋 표 행 추가/삭제 (patchHwpx): 마크다운에서 표에 행을 새로 넣거나 지워도 이제 원본에 반영됩니다. 새 행은 인접 행의 서식(테두리·글꼴·높이)을 그대로 복제해 셀 텍스트만 바꿔 넣고, rowCnt·셀 좌표·표 높이까지 함께 갱신합니다. 세로 병합을 가로지르거나 행에 이미지/중첩표가 있는 등 위험한 경우엔 문서를 건드리지 않고 사유와 함께 skip합니다. (실제 결재문서 45건 검증 — 손상 0)
• ✏️ 양식 채우기 정확도: 라벨 칸이 병합(colspan)된 서식에서 값이 소리 없이 사라지던 버그 수정, 표 안의 표(중첩표) 속 라벨도 채웁니다. fillFormFields(IR)와 fillHwpx(원본 보존) 두 경로가 같은 결과를 내도록 정합.
• 🔎 라벨 인식 확장: “연번1”·"제1항목"처럼 숫자가 낀 라벨, “제1소위원회위원장” 같은 9자 이상 라벨, “Name”·“Date of Birth” 같은 콜론 없는 영문 라벨을 인식합니다. “6개월”·“1억원”·“해당없음” 같은 값을 라벨로 오인하지 않는 거름망 포함.
• 📢 정직한 부분 적용 보고: PatchSkip.partial 신설 — “적용은 됐지만 원형 그대로는 아님”(셀 내 줄 병합·빈 문단 잔존 등)을 구분해 보고합니다.

v3.6.0 변경사항

• 📐 실측 텍스트 메트릭 엔진: 함초롬바탕 정품 TTF에서 글자 폭을 전수 추출해 한글 프로그램 없이 줄폭·줄바꿈을 계산합니다. 실제 결재문서의 조판 결과와 대조해 줄바꿈점 98% 일치 검증.
• 🪗 자동 장평(autoFit): 한두 글자가 다음 줄로 넘어가는(orphan) 문단만 골라 장평을 95→90%로 줄여 한 줄에 담습니다. 공문서 작성 관행 그대로.
• 📊 HTML 표 생성: 병합(colspan/rowspan)·중첩 표가 든 마크다운도 markdownToHwpx로 구조 그대로 HWPX 표가 됩니다 — parse↔generate 표 라운드트립 완성.
• 🗂️ 다중값 채우기: fillForm 값에 배열(string[])을 주면 같은 라벨의 등장 순서대로 하나씩 소진 — 반복 양식·명부형 표(헤더+여러 행) 채우기.
• 🛡️ 무결성 픽스: 채우기/패치 후 한컴이 “문서가 변조되었습니다” 경고를 띄우던 문제(줄 레이아웃 캐시 잔존), 생성 표 테두리가 보이지 않던 문제(borderFill id 규약) 수정.

v3.5.0 변경사항

• 📊 문장을 표로 — 인플레이스 변환 (patchHwpx): 기존 한글파일(HWPX) 안의 문단을 마크다운 표(| … |)로 편집해 patch에 넘기면, 원본 서식을 그대로 둔 채 그 문장만 표로 바꿔줍니다. 셀 테두리는 자동 생성, 나머지 문단·표·서식은 1바이트도 건드리지 않고 무손실 검증을 통과합니다. CLI kordoc patch·MCP patch_document가 자동 지원. (HWP 5.x 바이너리는 미지원 — generate로 새 문서 생성 권장)
• 🆕 MCP generate_document 도구: AI 에이전트가 마크다운(표 포함)을 바로 HWPX로 생성. parse_document로 읽은 내용을 표로 재구성해 다시 한글파일로 출력하는 워크플로가 완성됩니다. 공문서 프리셋(보고서·기안문…)·글꼴·글자크기 옵션 지원.
• 🐛 공문서 한글 프리셋 크래시 수정: markdownToHwpx(md, { gongmun: { preset: "보고서" } })처럼 라이브러리/MCP에서 한글 프리셋명을 직접 넘기면 터지던 버그 수정(normalizeGongmunPreset). CLI는 영향 없었음.

v3.2.0 변경사항

• 🏛️ 공문서 모드 markdownToHwpx(md, { gongmun }) — 마크다운을 한국 행정 공문서 표준 서식의 HWPX로 렌더링. 행정안전부 「행정업무운영편람」·시행규칙 근거.

  • 항목부호 8단계 자동화 — 중첩 리스트 깊이 → 1. 가. 1) 가) (1) (가) ① ㉮ (마크다운 마커 종류 무시, 깊이로 강제). 가나다 소진 시 단모음 연속(거·너·더), 상위 항목 진행 시 하위 카운터 리셋, 단일 형제 부호 생략.
  • 둘째 줄 내어쓰기 정렬 — OWPML (음수 hanging) + (단계별 누적)로 둘째 줄이 내용 첫 글자에 정렬. (실제 한컴 공문서 paraPr 구조와 동일하게 검증)
  • 공식 여백 위20/아래10/좌20/우20mm·머리말꼬리말0, 본문 15pt 명조(함초롬바탕) 기본 + 맑은 고딕 옵션.
  • 문서종류 프리셋 official(기안문)·report(보고서, □○-ㆍ 불릿)·plan·notice·minutes.

  import { markdownToHwpx } from "kordoc"
  
  const md = "1. 첫째 항목\n  - 둘째 항목\n    - 셋째 항목"
  const hwpx = await markdownToHwpx(md, { gongmun: { preset: "보고서" } })
  // → 1. / 가. / 1) 항목부호 + 내어쓰기 + 공식 여백 자동 적용
  

  CLI: kordoc generate doc.md -o out.hwpx --preset 보고서 (별칭 gen, --font/--pt/--line-spacing/--plain). 표준 레퍼런스: docs/gongmunseo-reference.md, 작성 스킬: .claude/skills/gongmunseo/.

v3.1.0 변경사항

• 🖊️ 에디터 통합 API HwpxSession — 블록 클릭-편집형 에디터를 위한 증분 패치 세션. openHwpxDocument(bytes)로 열고, session.patchBlocks(edits)로 블록 인덱스 기반 직접 편집 (문단 텍스트 / 표 셀). n회 연속 증분 패치 ≡ 일괄 patchHwpx 바이트 동일 동등성을 CI 게이트로 보장합니다.

  import { openHwpxDocument } from "kordoc"
  
  const session = await openHwpxDocument(new Uint8Array(buf))
  session.capability(3)            // "text" | "cell-text" | "locked" — 편집 전 잠금 판정
  const res = await session.patchBlocks([
    { blockIndex: 3, newText: "개최 완료" },
    { blockIndex: 5, cells: [{ row: 1, col: 2, text: "홍길동" }] },
  ])
  // session.bytes — 서식 그대로, 텍스트만 바뀐 HWPX (증분 누적)
  

• 📋 양식 필드 스키마 extractFormSchema(blocks) — 양식 인식에 타입 추론을 더해 폼 UI 자동 생성 지원. 필드 타입 7종(text/date/phone/email/amount/checkbox/idnum) + required(필수 표시 감지) + empty(채움 대상 판정).

• fillHwpx splice 전환 — 수정 범위 외 섹션 XML을 원본 바이트 그대로 보존하도록 전면 재작성 (동작·결과는 v3.0과 패리티).

• CJS 빌드 수정 — require("kordoc") 시 import.meta SyntaxError 나던 버그 수정.

v3.0.1 변경사항

• 🔄 HWP 5.x 바이너리 서식 보존 패치 — patchHwp(원본HWP, 편집된마크다운) 신규 API. HWPX 패치(patchHwpx)의 HWP 5.x(OLE2 바이너리) 대응으로, 변경된 문단/표 셀의 PARA_TEXT만 레코드 안에서 치환합니다 (PARA_HEADER 글자수·CHAR_SHAPE·LINE_SEG 연쇄 갱신).
  • 섹터 레벨 컨테이너 수술: CFB 전체 재조립 없이 대상 스트림의 섹터/FAT 체인/디렉토리 엔트리만 갱신 — 수정 외 영역은 원본과 바이트 동일 (실측: 133섹터 중 5섹터만 변경)
  • 안전 게이트: 레코드 재직렬화 바이트 동일성 검증, 순수 텍스트 문단만 수정, 암호화/배포용/DRM 거부, 미지원 편집은 skipped[]로 graceful skip
  • CLI kordoc patch가 .hwp/.hwpx를 매직바이트로 자동 분기
• CI: Node 18 ESM __dirname 미정의로 테스트 매트릭스가 실패하던 문제 수정

v3.0.0 변경사항

• 🔄 서식 보존 무손실 라운드트립 — patchHwpx(원본HWPX, 편집된마크다운) 신규 API. 변경된 문단/셀의 텍스트만 원본 XML 안에서 in-place 치환하고 나머지 ZIP 엔트리는 바이트 그대로 보존. 미지원 편집(블록 추가/삭제, 표 구조 변경)은 원본을 건드리지 않고 skipped[]로 정직하게 보고하며, 패치 후 자동 재파싱 검증 리포트(verification)를 제공합니다.

  import { parse, patchHwpx } from "kordoc"
  
  const r = await parse(buf)                       // HWPX → 마크다운
  const edited = r.markdown.replace("개최 예정", "개최 완료") // LLM이 편집했다고 가정
  const res = await patchHwpx(new Uint8Array(buf), edited)
  // res.data — 서식 그대로, 텍스트만 바뀐 HWPX 바이트
  // res.applied / res.skipped / res.verification — 적용·미지원·검증 리포트
  

• 🎯 “99.9% 정확도” 파서 대도약 — 실측 공문서 코퍼스 324건(정부 보도자료 + 서울시 결재문서 + 2014~2016 옛 문서) 자기참조 채점 기준:

  지표	v2.9.1	v3.0.0
  HWPX 텍스트 재현율	99.699%	99.998%
  HWPX 표 구조 정확일치	99.875%	100% (1,421표 · 중첩표 343 포함)
  PDF coverage	97.013%	99.16%
  HWP5↔HWPX 쌍 유사도	—	99.94%

  중첩표 구조 보존(IRCell.blocks), 한컴 PUA 매핑, HWP5 이미지 추출(0→90건), 자동번호 카운터, 머리말/각주 정밀 처리 등. 채점기·코퍼스 수집기·게이트는 bench/에 포함 — node bench/score.mjs로 재현 가능.

v2.9.0 변경사항

• 📊 PDF 텍스트 품질 신호 + OCR 필요 판정 — PDF는 텍스트층이 있어도 ToUnicode/CMap 이 깨져 한글이 깨진 글리프로 떨어지거나 NUL 등 제어문자가 섞이는 경우가 많습니다. parsePdf 결과에 페이지별 품질 신호(pageQuality)와 문서 요약(qualitySummary)을 추가 — needsOcr/ocrReason 으로 OCR 큐 자동 라우팅이 가능. kordoc 은 OCR 을 기본 탑재하지 않고 신호만 노출합니다. 전국 지자체 주요업무계획 PDF 190건(45,399쪽) 대량 처리 중 도출. (아래 PDF 텍스트 품질 신호 참고)

v2.8.0 변경사항

• 🎨 markdownToHwpx 테마 옵션 (#31) — 헤딩/본문/인용/표 헤더 셀의 텍스트 색상과 표 헤더 굵기를 옵션으로 지정 가능. 새 export 타입 HwpxTheme, MarkdownToHwpxOptions. 옵션 미지정 시 기존과 동일하게 검정으로 출력(baseline 백워드 호환).

---

설치

npm install kordoc

# PDF 파싱이 필요하면 (선택)
npm install pdfjs-dist

빠른 시작

문서 파싱

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

const buffer = readFileSync("사업계획서.hwpx")
const result = await parse(buffer.buffer)

if (result.success) {
  console.log(result.markdown)       // 마크다운 텍스트
  console.log(result.blocks)         // IRBlock[] 구조화 데이터
  console.log(result.metadata)       // { title, author, createdAt, ... }
}

문서 비교 (신구대조표)

import { compare } from "kordoc"

const diff = await compare(구버전Buffer, 신버전Buffer)
// diff.stats → { added: 3, removed: 1, modified: 5, unchanged: 42 }
// diff.diffs → BlockDiff[] (테이블은 셀 단위 diff 포함)

HWP vs HWPX 크로스 포맷 비교도 가능합니다.

양식 필드 추출

import { parse, extractFormFields } from "kordoc"

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

양식 자동 채우기

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

const template = readFileSync("신청서.hwpx")

// HWPX 원본 서식 보존 모드 — 글꼴, 크기, 정렬 100% 유지
const result = await fillForm(template.buffer, {
  성명: "홍길동",
  주민등록번호: "900101-1234567",
  주소: "서울특별시 광진구 능동로 120",
}, { format: "hwpx-preserve" })

writeFileSync("신청서_작성완료.hwpx", Buffer.from(result.buffer!))
// result.filled → [{ label: "성명", value: "홍길동" }, ...]
// result.unmatched → 매칭 실패한 키 목록

HWPX 생성 (역변환)

import { markdownToHwpx } from "kordoc"

const hwpxBuffer = await markdownToHwpx("# 제목\n\n본문 텍스트\n\n| 이름 | 직급 |\n| --- | --- |\n| 홍길동 | 과장 |")
writeFileSync("출력.hwpx", Buffer.from(hwpxBuffer))

// display math block은 HWPX native 수식()으로 생성됩니다.
// 초기 지원 범위는 \frac, \sqrt, 첨자/위첨자, Greek, 적분/극한,
// 화살표, 관계 연산자, matrix 계열의 제한된 LaTeX-like subset입니다.
const withEquation = await markdownToHwpx("피타고라스\n\n$$a^2 + b^2 = c^2$$")

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

CLI로도: kordoc generate 보고서.md -o 보고서.hwpx --preset 보고서

레이아웃 보존 렌더 (HWPX → SVG)

한컴이 HWPX에 저장하는 조판 캐시(줄 좌표·셀 그리드·개체 앵커)를 그대로 SVG 절대배치로 그립니다. 조판 엔진 없이 빠르고, 서버에 한컴 설치 없이 원본 모양 미리보기를 만들 수 있습니다. 다페이지 세로 스택·검색어 형광펜·그리기 도형 지원(v3.14~15). 조판 캐시가 없는 파일(markdownToHwpx 산출물·AI 생성본·편집본)은 reflow: true를 주면 순수 TS reflow 엔진이 직접 조판합니다(v3.15). 수식 개체는 미지원.

import { renderHwpxToSvg } from "kordoc"

const r = await renderHwpxToSvg(readFileSync("결재문서.hwpx"), { highlights: ["예산"] })
writeFileSync("결재문서.svg", r.svg)
// r.width/r.height (pt), r.pageCount, r.stats { texts, images, tables }, r.warnings

const g = await renderHwpxToSvg(generatedHwpx, { reflow: true }) // 조판 캐시 없는 생성본

CLI로도: kordoc render 결재문서.hwpx -o 결재문서.svg (--reflow·--highlight 예산,집행), 연속 렌더는 kordoc render-worker(stdin NDJSON, 미리보기 앱 연동용)

페이지 범위 지정

const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지

OCR (이미지 PDF)

const result = await parse(buffer, {
  ocr: async (pageImage, pageNumber, mimeType) => {
    return await myOcrService.recognize(pageImage)
  }
})

PDF 텍스트 품질 신호 (v2.9.0+)

PDF는 텍스트층이 있어도 ToUnicode/CMap이 깨졌거나 NUL 등 제어문자가 섞이는 경우가 많다. parsePdf 결과는 페이지별 품질 신호를 함께 반환한다.

const r = await parsePdf(buffer)
if (r.success && r.qualitySummary?.needsOcr) {
  // OCR 큐로 라우팅 (kordoc은 OCR을 기본 탑재하지 않음)
  await routeToOcr(buffer, r.qualitySummary.ocrCandidatePages)
}

// 페이지 단위 신호
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).

CLI

npx kordoc 사업계획서.hwpx                          # 터미널 출력
npx kordoc 보고서.hwp -o 보고서.md                  # 파일 저장
npx kordoc *.pdf -d ./변환결과/                     # 일괄 변환
npx kordoc 검토서.hwpx --format json               # JSON (blocks + metadata 포함)
npx kordoc 보고서.hwpx --pages 1-3                  # 페이지 범위
npx kordoc fill 신청서.hwpx -f '성명=홍길동,주소=서울' -o 결과.hwpx  # 양식 채우기
npx kordoc fill 신청서.hwpx -j values.json -o 결과.hwpx             # JSON 파일로 채우기
npx kordoc fill 신청서.hwpx --dry-run                               # 필드 목록만 확인
npx kordoc generate 보고서.md -o 보고서.hwpx --preset 보고서         # 마크다운 → 공문서 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 render 결재문서.hwpx -o 미리보기.svg      # 레이아웃 보존 SVG 렌더 (--reflow 지원)
npx kordoc watch ./수신함 -d ./변환결과              # 폴더 감시 모드
npx kordoc watch ./문서 --webhook https://api/hook  # 웹훅 알림

MCP 서버 (Claude / Cursor / Windsurf)

자동 설치 (추천):

npx -y kordoc setup

대화형으로 AI 클라이언트를 감지해 설정 파일을 자동 패치. Windows 에서 cmd /c npx 래핑도 자동. 상세는 위 30초 설치 섹션.

수동 등록 (macOS / Linux):

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

수동 등록 (Windows — Claude Desktop 이 .cmd 를 못 찾을 때):

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

11개 도구:

API

핵심 함수

고급 함수

타입

import type {
  ParseResult, ParseSuccess, ParseFailure, FileType,
  IRBlock, IRBlockType, IRTable, IRCell, CellContext,
  DocumentMetadata, ParseOptions, ErrorCode, OutlineItem,
  DiffResult, BlockDiff, CellDiff, DiffChangeType,
  FormField, FormResult, FillResult, HwpxFillResult, FillOutputFormat, FillFormOutput,
  PatchOptions, PatchResult, PatchSkip,
  HwpxTheme, MarkdownToHwpxOptions,
  PrintPreset, PrintOptions, PageMargin,
  RenderSvgOptions, RenderSvgResult,
  OcrProvider, WatchOptions,
} from "kordoc"

지원 포맷

보안

프로덕션급 보안 강화: ZIP bomb 방지, XXE/Billion Laughs 방지, 압축 폭탄 방지, 경로 순회 차단, MCP 에러 정제, 파일 크기 제한(500MB). 자세한 내용은 SECURITY.md 참조.

만든 사람

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

라이선스

MIT

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

• rhwp (MIT, edwardkim) — HWP5 배포용 복호화 및 lenient CFB 파싱 알고리즘
• OpenDataLoader PDF (Apache 2.0, Hancom Inc.) — PDF 테이블 감지 알고리즘
• cfb (Apache 2.0, SheetJS) — HWP5 OLE2 컨테이너 파싱
• pdfjs-dist (Apache 2.0, Mozilla) — PDF 텍스트 추출
• JSZip (MIT, Stuart Knightley 외) — ZIP 기반 포맷 파싱

자세한 내용은 NOTICE 파일을 참조하세요.