kordoc

모두 파싱해버리겠다.

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

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

English

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

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

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

npx -y kordoc setup

대화형 마법사가:

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

Windows 도 자동으로 cmd /c npx 래핑. 수동 JSON 편집 불필요. 재시작하면 15개 문서 도구 (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@^4 CLI 호출 — 별도 설치 불필요).

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

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

📄 어떤 문서든 마크다운으로: HWP3 (구버전), HWP(5.x), HWPX, HWPML, PDF, XLS, XLSX, DOCX 파일은 물론 PNG/JPG/WebP 이미지(자동 OCR)까지 즉시 Markdown으로 변환합니다. AI(LLM)가 문서를 읽고 분석하기 가장 좋은 상태로 만들어줍니다.
📊 복잡한 표(Table) 복원 — 숫자로 잠금: 병합·중첩 표를 구조 그대로 살립니다. HWPX 코퍼스 291문서 표 1,673/1,673·셀 27,714/27,714 무손실(독립 추출기 대조 게이트 1.0), 동일문서 hwpx↔pdf 대조(6쌍 69표)는 매칭 98.6%·완전일치 65.2%. 선 없는 PDF 표도 감지해 복원하고, 법령 개정안 PDF의 신구조문대비표도 통째로 살립니다 (v3.16.2).
🔍 신구대조표 자동 생성: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (HWP와 HWPX 간의 비교도 가능!)
📝 마크다운을 다시 HWPX로: AI가 작성한 내용을 다시 보고서 양식(HWPX)으로 되돌려줍니다. 이제 복사-붙여넣기 노가다에서 해방되세요.
🏛️ 정부 표준 공문서 생성 (v4.0): 실제 정부 양식 16종 + 실결재 기안문 60건을 전수 디코드·대조해 만든 공문서 엔진. 개조식 보고서(표지·목차 배너·로마숫자 장헤더·쪽번호·결재란), 기안문(별지 제1호서식 두문·결문, "끝." 자동), 공고문·보도자료 프리셋, 항목부호 8단계(1. 가. 1) 가)…) 자동, 공문서 표기법 검수 13룰(kordoc lint)까지 — 한글 COM 실렌더로 조판까지 실측 검증했습니다.
🔄 서식 보존 무손실 라운드트립 (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 Desktop, Cursor, Codex와 같은 도구에서 직접 kordoc을 호출해 문서를 읽고 코딩할 수 있습니다.

v4.8.0 변경사항

📑 --format json 에 페이지별 마크다운 (#68): JSON 결과에 pages: [{ pageNumber, markdown }] 이 기본으로 들어갑니다. v4.7.3 의 실제 페이지 경계(pageMode: "layout")를 그대로 써서, RAG 인용 각주나 뷰어 페이지 동기화에 쪽 단위 본문을 바로 쓸 수 있습니다. 문서를 다시 파싱하지 않고 이미 만든 블록의 pageNumber 로 가르기 때문에 비용은 파싱 시간의 1% 미만입니다(24쪽 PDF 기준 parse 399ms / pages 2.5ms). --pages 3-5 를 쓰면 pages 에도 3~5쪽만 담기고, 페이지 번호를 매기지 않는 포맷(DOCX 등)에서는 pages 자체가 없습니다. 라이브러리에서는 blocksToPages(blocks) 로도 같은 값을 얻습니다. (@sorbetsharkroundhand 제안)
```
{
  "markdown": "# 전체 문서…",
  "pages": [
    { "pageNumber": 1, "markdown": "# 1페이지…" },
    { "pageNumber": 2, "markdown": "2페이지…" }
  ],
  "blocks": [/* … */],
  "metadata": { "pageCount": 2, "pageMode": "layout" }
}
```
여러 페이지에 걸친 표는 현 IR 구조상 시작 페이지의 한 블록이라, 표가 이어지는 중간 페이지의 markdown 은 빈 문자열입니다(항목 자체는 남깁니다 — 배열 길이 = 쪽수).

v4.7.3 변경사항

📄 HWP/HWPX 실제 페이지 경계 복원 (#66): 한컴 저장본의 조판 캐시(HWPX linesegarray / HWP5 PARA_LINE_SEG)로 실제 페이지를 복원합니다 — pageCount·블록별 pageNumber 가 섹션 근사가 아닌 실제 쪽 번호가 되고, parse(buffer, { pages: "3-5" }) 가 실제 3~5쪽을 반환합니다. 신호 4종(vertpos 역행·명시 쪽나눔·분할 표의 셀 흐름 리셋·분할 직후 이중 카운트 억제)을 결합해 실코퍼스 hwp↔hwpx↔pdf 쌍 대조에서 페이지 수 전수 일치. 조판 캐시가 없는 생성 파일은 종전대로 섹션 근사로 동작하며, 새 메타데이터 pageMode: "layout" | "section" 으로 구분됩니다(근사 상태에서 pages 필터 사용 시 PAGE_BOUNDARY_APPROXIMATE 경고). RAG 페이지 인용·뷰어 동기화용. (@sorbetsharkroundhand 제안)

v4.7.2 변경사항

🔒 폐쇄망(내부망) 배포 대응: KORDOC_OFFLINE=1 로 모든 아웃바운드 통신(OCR 모델 다운로드·watch webhook)을 요청 발신 전에 차단하고, KORDOC_ROOT=<디렉토리> 로 MCP 서버의 파일 읽기·쓰기를 해당 디렉토리 하위로 제한합니다(둘 다 opt-in — 미설정 시 기존 동작 그대로). 인터넷 없는 망에 반입하는 오프라인 설치 번들은 node scripts/pack-offline.mjs [--with-ocr] [--with-models] 로 만들고, OCR 모델은 kordoc models --export/--import 로 SHA-256 검증과 함께 옮깁니다. 절차와 보안성 검토용 근거는 docs/offline-deployment.md 참조.
🧹 의존성 취약점 정리: npm audit --omit=dev 0건 (sharp ^0.35.0, adm-zip ^0.6.0 override, MCP SDK 체인 권고 해소).

v4.7.1 변경사항

✏️ 밑줄 보존 전 포맷 확장: v4.7.0 이 PDF 에서 복원한 밑줄을 HWPX·HWP5 에서도 <u>…</u> 로 방출합니다. 한컴이 밑줄 없는 글자에도 type="NONE" 을 넣는 특성 때문에 존재 여부가 아니라 밑줄 종류로 판별합니다.
🔗 PDF 링크 어노테이션 추출: /Annots 의 Link(/URI)를 텍스트와 상관해 [text](https://github.com/chrisryugj/kordoc/blob/main/url) 로 방출합니다 (스킴 화이트리스트 살균).

v4.7.0 변경사항

✏️ PDF 밑줄 감지: baseline 바로 아래 밀착한 얇은 수평선을 텍스트와 상관해 <u>…</u> 로 보존합니다. PDF 에는 밑줄 폰트 플래그가 없어 종전 파서는 이를 전부 버렸습니다. 표 괘선·배지 오탐 방어 5겹. 코퍼스 48문서 중 32문서에서 강조 밑줄 복원.

v4.6.1 변경사항

📰 2단 지면 읽기 순서 수리 (#64): 시험지·잡지처럼 좌우 2단으로 조판된 PDF에서 좌·우 단이 행 단위로 섞여 나오던 문제. 프로즈 특성(정렬·긴 줄)에 기대지 않는 기하 전용 2단 검출을 신설해, 전폭 요소(머리글·쪽번호)를 경계로 좌단 전체 → 우단 전체 순서로 복원합니다 — 기본 모드·--no-tables·OCR 경로 모두. 2026학년도 수능 문제지 실측: --no-tables 기준 물리학Ⅰ·생활과윤리 20/20 문항 순서 역전 0회(종전 13문항/역전 3회), 국어 44/45 역전 0회. 일반 문서 오발화는 행 구조 가드 3종으로 차단(코퍼스 커버리지 게이트 베이스라인 동등). (@choa712 블록 덤프 제보)

v4.6.0 변경사항

🚫 PDF 표 감지 opt-out (#64): --no-tables(CLI) / tables: false(API·MCP) — 시각적 테두리 박스(2단 시험지의 안내문·보기 상자)가 선 기반 표로 잡혀 주변 본문이 셀로 끌려가고 읽기 순서가 뒤집히던 문서에서, 표 감지를 통째로 끄고 자연 읽기순 텍스트만 뽑습니다. 기본값은 종전 그대로 표 감지 켬. (@choa712 제보)
🖼️ 이미지 다량 문서의 JSON 출력 수리 (#65): 이미지가 수백 장인 HWP는 base64 총량이 문자열 한계를 넘어 --format json이 비-JSON으로 끝나고 실패 계약도 안 나왔습니다. 이제 --image-refs로 이미지 바이트 대신 저장 경로만 남길 수 있고, 한계를 넘으면 자동으로 참조 모드로 강등하며, 출력 단계 예외도 원인 코드(OUTPUT_TOO_LARGE 등)가 담긴 실패 JSON으로 나옵니다. (@choa712 제보)
🔤 중첩 인라인 강조 수리 (#61): **굵게 *기울임* 다시** 같은 중첩 강조가 별 리터럴 노출·굵게 소실·서식 역전으로 깨지던 문제 — LLM이 쓴 마크다운에 흔한 패턴이라 generate_document 경로 노출이 컸습니다. (@LeeYudok 제보 + PR #62)
📄 선두 BOM XML 파트 수리 (#63): 일부 OpenXML 라이터가 [Content_Types].xml·.rels 앞에 붙이는 UTF-8 BOM 때문에 xlsx·docx가 통째로 PARSE_ERROR로 거부되던 문제(엑셀·리브레오피스는 정상 열림). (@soyesenna 제보)

v4.5.0 변경사항

📄 페이지 옵션 신설: 용지 크기(A4·A3·B4·B5·Letter·커스텀 mm)·가로 방향·다단(1~8단)·머리말/꼬리말을 생성 옵션으로 지원합니다 — API page, CLI --paper/--landscape/--columns/--header/--footer, MCP generate_document 동명 파라미터. 머리말/꼬리말은 실물 저장본과 동일한 <hp:header>/<hp:footer> 구조라 한글에서 그대로 조판됩니다.
🔗 하이퍼링크 생성: [text](https://github.com/chrisryugj/kordoc/blob/main/url)이 텍스트로 뭉개지지 않고 실측 6-param HYPERLINK 필드로 방출됩니다 — 한글에서 실제 클릭 가능, 재파싱하면 [text](https://github.com/chrisryugj/kordoc/blob/main/url) 복원(왕복 보존). 표 셀 안 링크 포함.
📎 각주 개체 생성: [^1] 마커 + [^1]: 본문 정의가 진짜 <hp:footNote> 개체로 방출돼 한글이 페이지 하단에 각주를 조판합니다.
🖼️ 이미지 실데이터 임베드: images 옵션(url→바이트)·data: URI·CLI/MCP --image-dir로 PNG/JPEG/GIF/BMP를 BinData에 실제로 넣습니다 — 픽셀 치수 자동 환산(96dpi)·본문폭 초과 시 비례 축소. 바이트가 없으면 종전처럼 참조를 placeholder로 보존합니다.
🔍 OCR 저신뢰 폐기 관측: 내장 OCR이 신뢰도<0.5로 조용히 버리던 라인 수를 OCR_LOW_CONF 경고로 노출합니다.
📏 스캔 표 실측 채점 교정: 표 구조가 아닌 정답(클립아트 장식 그리드·1×1 텍스트박스, 비어있지 않은 셀 <3)을 모수에서 제외하고 제외 수를 투명하게 노출 — 교정 후 스캔 표 매칭 71.4%·cellF1 0.595 (문자 recall·CER은 v4.4.1 실측과 동일).

v4.4.1 변경사항

🖼️ MCP 이미지 입력 수리: parse_document 등 파싱 도구가 PNG/JPG/WebP를 확장자 단계에서 거부하던 것(CLI는 정상, MCP만 차단)을 해제 — 스크린샷·스캔 이미지를 MCP로도 바로 변환합니다.
📏 내장 OCR 정확도 첫 실측 (bench/ocr-accuracy.mjs 신설): 코퍼스 PDF 41문서 82페이지, 클린 텍스트층 대조 — 문자 recall 90.0%(글꼴 미렌더 1건 제외 94.0%)·precision 95.1%, 한글 음절 recall median 99.9%, 0.96s/페이지. 스캔 표 구조는 매칭 63%·cellF1 0.50로 아직 약한 지점입니다. 정답이 클린 렌더라 실스캔 노이즈는 미반영(상한치).

v4.4.0 변경사항

🔑 비밀번호 문서 열기 (#59): 열기 암호가 걸린 HWPX·HWP3·HWP5 문서를 --password(CLI) / password(API·MCP)로 엽니다. 세 포맷의 암호화 방식이 각각 다릅니다 — HWPX는 ODF 표준(AES-256-CBC + PBKDF2), HWP3는 단일 DES-ECB, HWP5는 EncryptVersion 4의 비트 단위 CFB. 틀린 비밀번호는 성공으로 위장하지 않고 ENCRYPTED로 실패합니다. (한컴 DRM 문서보안은 별개라 해당 없음, @jangster77 제보)
🩹 HWP3 본문 대량 유실 수리: 그림 뒤에 오는 캡션 문단 리스트를 읽지 않아 그림 하나당 43바이트씩 스트림이 어긋났고, 어긋난 자리가 "문단 끝" 표식으로 읽히면 경고 없이 나머지를 통째로 버렸습니다. 945KB 문서가 0자로 나오던 수준입니다(rhwp 대조 실측 6종 복구, 최대 100만 자). 표 셀 상한 256도 실존 문서(367셀)를 죽여 잔여 스트림 기준으로 교체했습니다.
🔤 CDATA 텍스트 소실 수리: <hp:t><![CDATA[본문]]></hp:t> 로 저장된 텍스트를 경고 없이 버리던 결함 — 공용 XML 헬퍼에 있어 HWPX·HWPML·DOCX 세 포맷에 걸쳐 있었습니다.
🔣 사라지던 글자 복원: 한컴 검증 PUA 11종(결재란 (인), 편람 글머리표, 사각 안 숫자 ①~⑳ 등)과 HWP3 johab 매핑 2종(표 셀 글머리표 ▸, 머리말 회사명) — 매핑에 없는 코드는 삭제되는 구조라 누락이 곧 글자 증발이었습니다.
ᄒᆞᆫ HWP3 아래아(옛한글) 복원: 완성형에 대응 음절이 없어 통째로 빠지던 아래아 음절('ᄒᆞᆫ글 97' 등)을 한컴 HWP5/HWPX 변환본과 같은 자모열(초성+ᆞ+종성)로 보존합니다.
🐛 그 외: 동명 누름틀이 여러 곳에 있는 서식에서 require_unique가 한 곳도 채우지 않던 것, 수식 토큰이 constructor·toString이면 출력이 오염되던 프로토타입 체인 결함, 빈 셀 채우기가 엔티티( ) 원문을 지우던 것(fail-closed 통일), fill 계열 ZIP 폭탄 가드, CLI --format json의 실패 JSON 출력(원인 코드 포함). npm 배포본에 NOTICE·THIRD_PARTY 라이선스 고지도 포함됩니다.

v4.3.0 변경사항

🏛️ 정부 표준 기안문 서식 내장 + 누름틀 채우기: 별지 제1호(일반기안문, 누름틀 23곳)·제2호(간이기안문, 13곳) 서식을 번들 — kordoc fill --template gian / --list-templates / MCP fill_form의 template 파라미터로 파일 없이 표준 기안문을 채워 만듭니다. 누름틀(CLICK_HERE) 필드 채우기 신설 (서식·안내문 보존, 안내문 충돌 침묵 유실 구조적 차단).
📄 빈 문단 보존 옵션 (#57): --keep-empty-paragraphs — 행 줄맞춤 서식 문서(원규 번호표 등)에서 빈 문단이 사라져 값이 다른 항목에 붙던 문제의 opt-in 해법. 본문은 빈 블록, 표 셀은 빈 줄로 "원문 문단 수 = 줄 수" 대응 유지. (@jumaniac 제보)
🐛 에러 계약·MCP 정합 7건: 암호화 XLS가 성공으로 위장하던 것, HWPX DRM 오분류, HWP3/HWPML/sharp 진단 메시지 소실, MCP parse_pages 배포용 HWP 폴백 불발, .xls를 hwp로 오판, pageCount 미전파 등 — 전면 리뷰에서 발굴·일괄 수리.
📐 TAC 인라인 표 outMargin 정합 (rhwp 포팅): 결재란 등 글자취급 표의 가로 여백이 무시돼 문단이 밀리던 렌더 결함 수리 — 실코퍼스 60건 스윕 검증.
⚡ 성능: HWP 바이너리 패치의 섹터 할당 O(n²) 제거(+4MB 삽입 637배 가속), PDF 괘선 표 감지 버킷화. MCP 핸들러 전면 비동기화로 대용량 문서 I/O 중 서버 멈춤 제거.
🧰 내부 정비: 수식 변환기 hwp5→hwpx 정본 통합(포맷별 LaTeX 갈림 해소), 번호서식·XML 헬퍼 공용화, CI 타입체크 신설, 발행 게이트 복원(--ignore-scripts 관행 제거).

v4.2.6 변경사항

📐 개조식·보고서 본문 왼쪽정렬: 개조식·보고서 공문서의 본문 항목(□/○/-)을 양쪽정렬에서 왼쪽정렬로 바꿨습니다. 어절 유지 + 양쪽정렬이 겹치면 다음 어절이 길어 짧게 끊긴 줄(예: 25자 줄을 34자 폭으로)의 어절 간격이 과하게 벌어져 문단이 깨진 것처럼 보이던 문제입니다. 「행정업무운영편람」 개조식 예시의 왼쪽정렬 관례와도 일치합니다. 기안문(official) 등 서술형 본문의 양쪽정렬은 그대로 유지합니다.

v4.2.3 변경사항

인라인 표·텍스트 순서 보존 (#49·#50): 한 문단이나 한 셀 안에서 글자취급(treatAsChar) 표와 텍스트가 번갈아 놓일 때([날짜] 부터 [날짜] 까지 같은 서식 기간 입력란) 텍스트가 표 앞으로 끌려나오던 순서 역전을 수정했습니다. 최상위 blocks와 IRCell.blocks 모두 원문 배치 순서를 따르고, 생성기도 같은 순서로 방출해 라운드트립이 대칭입니다. float·페이지 앵커 표는 종전대로 텍스트 흐름에 불참합니다. (@jumaniac 제보)

v4.2.2 변경사항

~~취소선~~ 추출 (HWP5·HWPX): 법령 개정문 등의 삭제 표시가 마크다운 ~~취소선~~으로 살아납니다. 판정은 취소선 모양 whitelist — 한컴은 취소선 없는 문자에도 취소선 비트를 기본값으로 저장하므로(원저장소 rhwp 실측) 모양이 실제 선 종류일 때만 인정, 미지 값은 안전하게 무시. HWPX는 부분 취소선까지, HWP5는 문단 단위.
ZIP 해제 한도 100→256MB: 단일 섹션 XML이 75MB에 달하는 대형 실문서(rhwp 1만 건 서베이 실측)가 ZIP bomb으로 오인 거부되던 것을 상향.

v4.2.1 변경사항

🖼️ 이미지(PNG/JPG/WebP) 직접 입력: 스크린샷·스캔 이미지를 PDF 래핑 없이 바로 변환합니다 — kordoc 서식.png / parse(buffer) / MCP parse_document. 텍스트층이 없으므로 내장 OCR 이 자동 적용됩니다 (플래그 불필요, 디코딩은 optional dependency sharp).
📐 스캔본 표 괘선 감지: OCR 경로에 래스터 괘선 감지기 신설 — 페이지 픽셀에서 수평/수직 괘선을 직접 찾아(이진화+런렝스, ML 없음) 선 기반 표 파이프라인에 태웁니다. 세로 병합 라벨 셀 + 다중줄 서술형 서식(정부 제출 서식류)도 rowspan/colspan 이 살아있는 표로 복원됩니다. 종전 클러스터 감지는 괘선이 안 잡히는 무테두리 표의 fallback 으로 유지.

v4.2.0 변경사항

👓 내장 텍스트 OCR (PP-OCRv5 korean): 스캔/이미지 PDF를 API 키 없이 로컬 추론으로 읽습니다 — parse(buffer, { ocr: true }) / CLI --ocr / MCP parse_document의 ocr 옵션. 모델 ~18MB는 첫 사용 시 자동 다운로드+SHA 검증. 품질 신호가 가리키는 페이지(스캔·글꼴 매핑 깨짐)만 정밀 OCR 하고 정상 페이지는 그대로 두며, OCR 라인 좌표를 표 감지 파이프라인에 태워 스캔본에서도 표가 복원됩니다. 한국어 사전 11,945자(완성형 한글 11,172자 전량 + 자모·라틴·기호), 1페이지 ≈1초.
🩹 HWP3 구버전 파서 정합 3종: 탭/필드코드/책갈피의 스트림 소비 결함으로 이후 텍스트가 통째로 오염되던 것과, 로마숫자(Ⅰ~~Ⅹ)·원문자(①~~⑩)·따옴표·글머리가 증발하던 것을 원저장소(rhwp) 후속 패치 반영으로 수리.
🐛 수식 OCR 페이지 off-by-one 수리: --pages 필터가 한 페이지 밀리고 수식이 이전 페이지에 붙던 잠복 결함. XLSX/XLS --keep-empty-cols 배선 누락도 수리.

v4.1.0 변경사항

👁️ render_document MCP 도구 신설: 생성·패치·양식 채움 결과 HWPX를 조판 그대로 PNG 이미지로 응답에 직접 반환 — AI가 자기가 만든 문서를 눈으로 확인하고 다시 고치는 루프가 MCP 안에서 닫힙니다 (한컴 저장본은 조판 캐시, 생성본은 reflow 조판, 검색어 형광펜 지원).
🕶️ kordoc redact + redact_document MCP 신설: 개인정보(주민번호·전화·이메일·카드·계좌, 여권·운전면허 opt-in)를 탐지해 원본 서식 그대로 마스킹(850315-●●●●●●●)한 HWPX/HWP를 출력합니다. 생년월일·Luhn 검증으로 오탐 축소, 리포트에 원본 개인정보 미포함. 자동 검출 보조 도구 — 최종 공개 전 사람 확인 필수.
📦 --format chunks + parse_chunks MCP 신설: RAG용 구조 청크 JSON — 헤딩·개조식 위계(□○- / 1.·가.·1))를 breadcrumb 경로로 보존하고 표는 독립 청크로 분리합니다.
📋 표 오른쪽 끝 빈 열 보존 (#47): 서식 문서의 빈 입력란 열이 파싱에서 통째로 삭제되던 문제 — keepTrailingEmptyCols 파싱 옵션(CLI --keep-empty-cols)으로 보존할 수 있고, 양식 경로(parse_form·fill)는 항상 보존해 fill이 채울 수 있는 필드가 목록에서 빠지지 않습니다. 제보 @jumaniac.
📅 XLSX/XLS 날짜 변환: 날짜 셀이 시리얼 숫자("45306")로 나오던 것을 ISO("2024-01-15")로 변환합니다 (내장·커스텀 numFmt 감지, date1904 반영).
🛡️ 프로덕션 전면 리뷰 ~80건 수정: 악성 파일 대응(수식 정규식 ReDoS·HTML 표 span 폭주·HWP3 압축 폭탄·XLSX 그리드 폭주), 표-전용 PDF의 OCR 오판, HWP5 제어문자(하이픈/고정폭 공백) 매핑, DOCX 변경추적 삽입 유실, 양식 채움 라벨 오탐 4종, HWP5 패치 삭제 텍스트 잔존 제로화, MCP 쓰기 경로 검증, PDF 괘선 표 성능(62,500 교차점 3.1s→0.2s) 등 — 자세한 내역은 CHANGELOG.

v4.0.8 변경사항

🖼️ PDF 이미지 추출 신설: 종전에는 이미지 영역 좌표만 계산하고 바이너리는 전량 유실되던 것을, 이미지 XObject를 디코딩 픽셀로 받아 순수 JS PNG 인코딩으로 추출합니다 (pdfjs 비동기 디코딩 대기 포함 — 코퍼스 52 PDF 중 45파일 731장 실측). 페이지 말미 위치에 ![image](https://raw.githubusercontent.com/chrisryugj/kordoc/main/) 참조, 로고·워터마크 페이지 간 중복 억제, 페이지 경계 표 병합 비간섭.
🖼️ HWPX/HWP5 미참조 BinData 스윕: 꼬리말·머리말 안 그림(보도자료 사진 스트립), 결재문서 셀 배경 이미지(borderFill imgBrush) 등 본문 워크가 닿지 않아 유실되던 이미지를 문서 끝에 보강 추출합니다 — 코퍼스 이미지 복구율 HWPX 686/686·HWP5 92/92 (100%).
🖼️ DOCX w:object 이미지: OLE 개체 미리보기(v:imagedata)가 추출에서 빠지던 것 수정 (mc:Fallback 사본은 종전대로 중복 제외).

v4.0.7 변경사항

🔗 DOCX 하이퍼링크 대량 손실 수정: 한 문단에 링크가 여러 개면 마지막 1개만 남던 구조를 제거하고 문서 순서대로 링크별 인라인 [text](https://github.com/chrisryugj/kordoc/blob/main/url) 생성. 워드·구글독스가 흔히 쓰는 필드코드 HYPERLINK(fldSimple/fldChar)와 내부 anchor 링크도 처리 (실측 176→21 손실이던 문서 전량 복원).
🖼️ DOCX 이미지 본문 링크: 이미지가 파일로는 추출되나 마크다운에 ![image](https://raw.githubusercontent.com/chrisryugj/kordoc/main/) 참조가 안 들어가던 것을 문단 위치 인라인 방출로 수정.
🔍 PDF 오매핑 mojibake 감지: ToUnicode 오매핑으로 정상 한글 영역의 엉뚱한 글자가 무경고 통과하던 것을 종성(받침) 분포 신호로 감지 — garbled_hangul 사유의 페이지별 NEEDS_OCR 경고.

v4.0.6 변경사항

📊 PDF 무괘선 밴드 표 파편화 수정: 세출예산 사업명세서류의 요약행 밴드에서 수직선이 끊겨 부서명이 유실되던 것을 4중 가드 수직선 브리지로 복원 (광진구 2026 세출예산 637곳 실측).
📝 HWPX 캡션 안 중첩표 보존 (#46): 캡션 속 표 내용이 통째로 사라지던 것(304자 중 297자)을 문서 순서 평탄화로 보존. 제보 @jumaniac, 조언 @hiSandog.

v4.0.5 변경사항

🖍️ 인라인 강조 복원 일반화: kordoc이 만들지 않은 일반 한컴 문서도 볼드·이탤릭이 마크다운 **·* 마커로 복원됩니다 (charPr 실속성 기반, 한컴 편집 이력으로 쪼개진 run 자동 병합). 표 헤더행처럼 셀 전체가 볼드인 구조 서식은 마커를 만들지 않습니다.
🏛️ 공문서 모드 인라인 강조 왕복: 공문서 HWPX를 재파싱해도 항목 안 **강조**가 보존됩니다 — 보고서 1단계 □ 전체 굵게 같은 구조 볼드와 자동 구분.
↔️ 리스트 depth 왕복: 공문서 재파싱 산출물의 1)·- 항목이 재생성 시 1단계로 붕괴('1)'→'2.', '-'→□)하던 것을 들여쓰기 역산 선행 공백으로 해소 — 기안문·보고서·개조식 2차 왕복이 동일 결과로 수렴.

v4.0.4 변경사항

🖋️ reflow 개체 흐름 모델: float 표(두문 결재표)는 텍스트를 개체 아래로, 페이지 앵커·글 뒤 개체는 흐름 불참, inline 표는 실효높이+행간 전진 — 실결재 코퍼스 자기일관성 59/59 (100%). 한컴 저장본을 프로그램 편집해 일부 문단만 캐시가 없는 혼합 캐시 문서도 reflow로 정확한 위치에 렌더됩니다.
🎨 서식 프로필 0.3.0: 셀 글꼴 이름 왕복(fontName_hangul — 원본 없이 글꼴 재현), 첫 행 지문 anchor_row(첫 셀이 빈 크로스탭 매칭), 행0 전체 병합 표의 열폭 보존, 손편집 JSON의 괘선 값(type·mm·색상) 사전 검증.
🧰 CLI/MCP 옵션 표면 통일: 공문서 옵션 조립·값 집합을 단일 SSOT로 — 두 인터페이스의 옵션 드리프트 원천 차단(MCP 프리셋 별칭 6종 회복 포함). 리팩터 전후 산출물 바이트 동일 검증.
↔️ 왕복 보강: 표 셀 안 볼드·이탤릭·코드 마커 왕복, 파서 문단 들여쓰기 관찰 슬롯(IRBlock.indent), 원문자 15+/51+ 폴백 파서 정합, 중첩표 높이 정밀화, 결문 구분선 컬럼폭 적응.
게이트: 테스트 1,012 · 실렌더 시각 오라클 14종 해밍0 (default 모드 h1~h4 개요번호 미강제 실렌더 확증 포함).

v4.0.3 변경사항

🛡️ 프로덕션 하드닝: v4 전체 2중 리뷰에서 확정된 결함 수정 — 잘못된 수치 옵션(NaN·비정상 범위)의 명시적 거부, 폰트명 XML 이스케이프, 표지·목차를 전 프리셋으로 확대(보도자료 제외), 표지·목차 사용 시 본문 폰트 지정이 무시되던 결함과 13pt 이하 헤딩 위계 역전, 셀 안 개체 캡션 오귀속·거짓 손실 경고 수정.
📏 기안문 기본 12pt·계획서 □→ㅇ→* 체계: 실결재·실측 계획안 지배값을 기본값으로 (종전 값은 --pt 15·numbering: 'standard'로 복원 가능).

v4.0.2 변경사항

📏 실측 벤치마킹: 서울 정보소통광장 실결재 기안문 60건 + 부처별 양식을 전수 디코드해 생성 결과와의 괴리 17건을 목록화, 9건 반영.
- 조판영역 근본수정: 단 컬럼 정의(colPr) 미방출로 본문이 좌우 10mm씩 좁게 잡히고 표가 우측 여백을 침범하던 결함 해소 — 전 프리셋 실렌더 조판영역 초과 0건.
- 기안문 두문·결문 (--doc-head/--doc-foot, 별지 제1호서식) · 보도자료 프리셋 press (머리박스·담당 표) · 공고문 두문 (--notice-head) · 보고정보 행 (--report-info).
- 표 열폭 배분 재작성(열 하한 = 최장 어절 폭 — 짧은 열이 글자 단위로 세로 쪼개지지 않음), 표 셀 12pt, 기안문 여백 실결재 지배값 20/15/20/15, 2단계 부호 ㅇ/○ 프리셋 분화(--bullet2).
실무자(현직 공무원) 눈 QA 게이트 통과 후 릴리스.

v4.0.1 변경사항

✍️ 실무자 QA 3건 수정: bold 시 폰트가 HY견고딕/Arial Black으로 바뀌던 "정체모를 폰트" 제거, h2 섹션 제목 말머리 --h2-marker(box □ / number / none), 개조식 소분류 부호 ― → 실무 관행 하이픈 -.
📝 공문서 표기법 검수 13룰: 날짜·시간·금액·붙임 표기 등을 검수하는 kordoc lint <file> + 공문서 생성 시 경고 병기.

v4.0.0 변경사항

🏛️ 정부 표준 개조식 보고서 완성: 실제 정부 공문서 16종 전수 디코드·대조 기반 — 표지(gradient 제목박스·장식 바)·목차 배너·로마숫자 장헤더·쪽번호("- 1 -", 표지·목차 제외)·결재란·"끝." 자동·본문 제목박스. 표는 실측 문법(헤더 음영+이중선, 외곽 0.4mm 위계, 내용 비례 열폭, 우측 배치) 자동 적용. --preset 개조식.

v3.18.0 변경사항

🎨 서식 프로필: 표의 위상뿐 아니라 테두리·음영·열 실측폭·셀 글꼴까지 원본 문서 없이 재현합니다. hwpxToProfile(hwpx)로 레퍼런스 서식만 JSON으로 추출하고, markdownToHwpx(md, { profile })로 다른 문서에 그 서식을 입힙니다 — 원본 유출 없이 기관 서식만 공유·재현(이슈 #41, 스키마 docs/format-profile-spec.md). 스키마·예시 기여: @ai-localgov-officer (PR #42).

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(CLI는 기본 켬, --no-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 블록이 한컴 수식 개체(<hp:equation>)로 생성됩니다. \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 표 라운드트립 완성.
🎨 서식 프로필: 표의 위상뿐 아니라 테두리·음영·열 실측폭·셀 글꼴까지 원본 없이 재현합니다. hwpxToProfile(hwpx)로 서식만 JSON으로 추출하고, markdownToHwpx(md, { profile })로 다른 문서에 그 서식을 입힙니다 — 원본 유출 없이 기관 서식만 공유·재현(이슈 #41, 스키마: docs/format-profile-spec.md).
🗂️ 다중값 채우기: 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 <hc:intent>(음수 hanging) + <hc:left>(단계별 누적)로 둘째 줄이 내용 첫 글자에 정렬. (실제 한컴 공문서 paraPr 구조와 동일하게 검증)
- 프리셋별 실측 여백·글자 크기 적용(기안문 본문 12pt, 보고서·계획서 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) +

Kordoc

At a glance

README