출처
원문 정리: PyTorchKR 소개글
한국에서 LLM·RAG·에이전트를 붙이다 보면, 모델보다 먼저 막히는 곳이 있습니다.
문서가 한글로 안 열립니다. 정확히는, 사람이 한컴으로 열어 복사·붙여넣기 하기 전에는 AI가 읽을 상태가 안 됩니다.
kordoc은 그 병목을 정면으로 찌르는 도구입니다.
HWP/HWPX/PDF/Office/이미지까지 받아 마크다운으로 바꾸고, 다시 HWPX로 되돌리며, Cursor·Claude 같은 클라이언트에 MCP로 꽂아 문서 도구를 직접 호출하게 합니다.
•
프로젝트명: kordoc (chrisryugj)
•
TypeScript / MIT / Node.js 18+
•
핵심: 파싱 → 편집 → 서식 보존 패치 → 공문서 생성 의 왕복
•
CLI 단독 사용 가능, MCP로 AI 에이전트 연동
•
행정 문서를 오래 다룬 개발자가 만들었고, 관공서 문서 수천 건으로 검증했다고 밝힘
이게 왜 필요할까요??
한국 공공·기업 문서는 포맷이 제각각입니다.
아래아한글 = HWP 3.x / 5.x / HWPX / HWPML
배포물 = PDF (표·스캔·무괘선 표 섞임)
첨부 = XLSX / DOCX / 이미지 스캔본
Plain Text
복사
특히 HWP 계열은 구조가 복잡합니다.
OLE2 바이너리, ZIP+XML, 배포용 암호화, 중첩 표, 병합 셀, 결재란, 개조식 항목부호…
“텍스트만 뽑으면 되지”라고 생각하면, 표가 문단으로 찢어지고 신구조문대비표가 붕괴합니다.
그래서 RAG·요약·비교·양식 채우기 파이프라인에 사람이 끼어듭니다.
문서 수신 → 사람이 한컴으로 열기 → 복사/붙여넣기 → LLM
Plain Text
복사
kordoc의 질문은 단순합니다.
문서 = 사람이 열어줘야 하는 블랙박스여서 기존에 문제였다
문서 = AI가 읽고 고치고 다시 낼 수 있는 워크스페이스로 바꾸자 한다.
Plain Text
복사
한 줄로 말하면: 한국 문서를 LLM의 네이티브 입출력으로 만들자.
여기서 우리가 꼭 알아가야할 핵심 개념!!: Round-trip
많은 “HWP 파서”는 한 방향입니다.
HWP → 텍스트/마크다운 (끝)
Plain Text
복사
kordoc이 눈에 띄는 이유는 왕복(round-trip) 을 제품의 중심에 둔 점입니다.
1) parse 문서 → 마크다운 / IR 블록 / RAG 청크
2) edit 사람이든 LLM이든 마크다운을 고친다
3) patch 바뀐 텍스트만 원본에 되꽂는다 (서식 유지)
4) generate 마크다운에서 공문서 HWPX를 새로 만든다
Plain Text
복사
이게 왜 중요할까요.
관공서·기업에서 진짜로 필요한 건 “요약본 마크다운”만이 아닙니다.
원본과 같은 서식의 산출물입니다. 글꼴, 표 테두리, 결재란, 항목부호 체계가 유지되어야 합니다.
저자들은 실측 공문서 코퍼스 324건 자기참조 채점에서
HWPX 텍스트 재현율 99.998%, 표 구조 정확 일치 100%(1,421개 표)를 보고합니다.
숫자 자체보다 더 인상적인 건, 채점기·코퍼스가 bench/에 있어 재현 가능한 주장이라는 점입니다.
한 줄: 파싱은 시작이고, 서식 보존 패치가 제품이다.
kordoc이 실제로 하는 일 다섯 덩어리
소개글·README를 훑으면 기능이 많아 보이지만, 실무 관점에서는 다섯 묶음으로 보는 게 편합니다.
1. 무엇이든 마크다운으로
지원 범위가 넓습니다.
계열 | 포맷 |
한글 | HWP 3.x / 5.x, HWPX, HWPML |
배포 | PDF |
오피스 | XLS, XLSX, DOCX |
이미지 | PNG / JPG / WebP (OCR) |
표 복원이 특히 강조됩니다.
선 없는 PDF 표, 병합된 HWP 표, 법령 개정안의 신구조문대비표처럼 “파서가 자주 죽는” 케이스를 목표로 잡았습니다.
스캔본·이미지처럼 텍스트층이 없으면 내장 OCR이 돕습니다.
한국어 PP-OCRv5 (~18MB)를 첫 사용 시 받아, API 키 없이 로컬 추론합니다.
정상 페이지는 건드리지 않고, 품질 신호가 가리키는 페이지만 OCR하는 식입니다.
2. RAG용 구조 청크
•
-format chunks / MCP parse_chunks는 단순 슬라이싱이 아닙니다.
헤딩·개조식 위계 → breadcrumb 경로로 보존
표 → 독립 청크로 분리
Plain Text
복사
한국 공문서는 “1. / 가. / 1)” 같은 계층이 곧 검색 단위입니다.
청크에 위계를 남기지 않으면, 검색은 되지만 “어디 항목의 표인지”를 잃습니다.
이 옵션은 그 감각이 살아 있습니다.
3. 비교·양식·마스킹
•
compare_documents: HWP
HWPX 크로스 포맷 신구대조
HWPX 크로스 포맷 신구대조•
fill_form: 라벨-값 패턴으로 빈칸 채우기 (원본 서식 유지)
•
redact_document: 주민번호·전화·이메일 등 탐지 후 서식 보존 마스킹
“파서”를 넘어 행정 워크플로 도구로 확장된 영역입니다.
4. 공문서 생성 (generate)
마크다운 → HWPX.
항목부호 8단계 자동화, 둘째 줄 내어쓰기, 기안문·보고서·개조식·공고문·보도자료 프리셋.
근거로 삼은 표준 문법은 저장소 docs/gongmunseo-reference.md에 정리되어 있습니다.
“예쁘게 대충”이 아니라, 행정 문서 관례를 코드로 박아 넣은 생성기에 가깝습니다.
5. 렌더·날인·차트
•
HWPX → PNG/SVG 렌더 (한컴 없이 미리보기)
•
도장/서명 앵커에 이미지 날인
•
마크다운 chart 펜스 → 한컴 네이티브 차트
에이전트 관점에서 중요한 건 render_document입니다.
생성·패치 결과를 AI가 눈으로 확인 → 다시 수정하는 루프를 MCP 안에서 닫을 수 있습니다.
AI 에이전트와의 접점: MCP
kordoc의 타이밍이 좋은 이유 중 하나는 MCP입니다.
파서가 CLI에만 있으면 “사람이 변환한 뒤 AI에게 넘기는” 구조가 남습니다.
MCP로 붙이면 에이전트가 도구를 직접 호출합니다.
가장 쉬운 설치:
npx -y kordoc setup
Bash
복사
Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Gemini CLI, Zed, Codex 등을 감지해 설정을 패치합니다.
수동 등록 예:
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
JSON
복사
대표 도구 (총 15개 수준):
도구 | 하는 일 |
parse_document | 문서 → 마크다운 |
parse_chunks | RAG용 구조 청크 |
compare_documents | 신구대조 |
fill_form | 양식 채우기 |
patch_document | 서식 보존 패치 |
generate_document | 마크다운 → HWPX |
render_document | HWPX 미리보기 |
redact_document | 개인정보 마스킹 |
Claude Code는 플러그인으로도 쓸 수 있습니다.
/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc
Plain Text
복사
.hwp / .hwpx 언급이나 공문서 생성 요청에 스킬이 자동으로 붙는 구조입니다.
제가 보기엔 여기가 핵심입니다.
문서 도구가 에이전트의 “손”이 되면, 프롬프트만으로 공문서를 다루던 시대와 질이 달라집니다.
CLI로만 써도 충분한 이유
AI 연동 없이도 npx 한 줄이면 됩니다.
npx kordoc 사업계획서.hwpx # 터미널 출력
npx kordoc 보고서.hwp -o 보고서.md # 파일 저장
npx kordoc *.pdf -d ./변환결과/ # 일괄 변환
npx kordoc 검토서.hwpx --format json # blocks + metadata
npx kordoc 보고서.hwpx --format chunks # RAG 청크
npx kordoc fill 신청서.hwpx -f '성명=홍길동' -o 결과.hwpx
npx kordoc generate 보고서.md -o 보고서.hwpx --preset 보고서
npx kordoc patch 원본.hwpx 편집.md -o 반영.hwpx
npx kordoc render 결재문서.hwpx -o 미리보기.svg
npx kordoc lint 보고서.hwpx # 공문서 표기법 검수
Bash
복사
라이브러리로도:
import { parse, patchHwpx, markdownToHwpx } from "kordoc"
import { readFileSync, writeFileSync } from "fs"
const buf = readFileSync("사업계획서.hwpx")
const r = await parse(buf)
if (r.success) {
const edited = r.markdown.replace("개최 예정", "개최 완료")
const patched = await patchHwpx(new Uint8Array(buf), edited)
writeFileSync("반영.hwpx", Buffer.from(patched.data))
}
const hwpx = await markdownToHwpx("# 추진계획\n\n1. 배경\n - 세부", {
gongmun: { preset: "보고서" },
})
TypeScript
복사
실무 팁을 제 식으로 정리하면:
일단 CLI로 자기 문서 3~5개만 통과시켜 보라
표·병합·스캔본이 있는 “나쁜 파일”부터 넣어라
성공 메시지보다 산출물을 한컴/미리보기로 열어라
patch가 skip 한 항목은 실패가 아니라 정직한 경계선이다
Plain Text
복사
서식 보존 라운드트립을 조금 더 깊게
patchHwpx / patchHwp의 발상은 단순합니다.
원본 ZIP/바이너리의 대부분은 건드리지 않는다
바뀐 문단·셀 텍스트만 in-place 치환한다
미지원 편집은 원본을 망가뜨리지 않고 skipped[]로 보고한다
Plain Text
복사
이게 “전체 재생성”보다 중요한 이유가 있습니다.
공문서는 텍스트 내용보다 서식 자산이 비쌉니다.
테두리 두께, 음영, 열폭, 결재란 위치, 글꼴 조합… 이걸 매번 다시 맞추면 사람이 다시 손대게 됩니다.
v3 이후로는 표 행 추가/삭제, HWP 빈 셀 채우기까지 범위가 넓어졌고,
v4에서는 정부 표준 개조식·기안문 프리셋이 한층 두꺼워졌습니다.
CHANGELOG를 보면 “벤치 숫자 올리기”와 “실무자 눈 QA”가 번갈아 등장합니다.
이 리듬이 신뢰감을 줍니다.
반대 방향인 generate는 다른 축입니다.
patch = 원본 자산 위에 최소 수술
generate = 마크다운에서 표준 서식의 새 문서 생성
Plain Text
복사
둘을 같은 “변환”으로 묶으면 헷갈립니다.
용도가 다릅니다.
제가 특히 좋게 본 지점 / 경계선
좋게 본 점
1.
문제 정의가 현장형이다
“파싱 정확도”만 자랑하지 않고, 양식 채우기·신구대조·공문서 생성·마스킹까지 이어집니다.
2.
MCP가 1급 시민이다
문서 도구를 에이전트에 붙이는 경로가 짧습니다. setup 마법사도 실무적입니다.
3.
정직한 실패 보고
못 하는 편집을 조용히 깨뜨리지 않고 skipped / warnings로 드러내는 쪽을 택했습니다.
4.
한국 문서 특수성을 코드에 심었다
개조식, 신구조문대비표, 배포용 HWP, 무괘선 PDF 표, 개인정보 마스킹…
일반 “universal document parser”가 자주 놓치는 지점입니다.
5.
라이선스가 명확하다
MIT. 다만 rhwp, OpenDataLoader PDF, cfb, pdfjs-dist 등 구성요소 라이선스는 NOTICE를 같이 볼 것.
경계선으로 남겨둘 점
1.
벤치마크는 자기참조다
324건 코퍼스 수치는 인상적이지만, 자기 코퍼스 자기 채점입니다.
“만능 보증”이 아니라 “이 도메인에서 강하게 최적화됐다”로 읽는 게 맞습니다.
2.
모든 편집이 patch 되는 건 아니다
복잡한 구조 변경·일부 도형·특수 컨트롤은 skip될 수 있습니다.
실패했다고 화내기보다, 그 경계를 워크플로에 반영해야 합니다.
3.
OCR·생성 결과는 검수가 필요하다
스캔본 OCR, 개인정보 마스킹, 도장 위치는 자동이지만 최종 공개 전 사람 확인이 전제입니다.
README도 그 점을 분명히 합니다.
4.
환경 의존이 남는 케이스
일부 DRM/배포용 문서는 Windows+한컴 COM fallback이 필요할 수 있습니다.
“완전 순수 JS로 만능”은 아직 현실의 모든 잠금을 깨지 않습니다.
자주 하는 실수들입니다!
실수 1. “텍스트만 뽑히면 RAG 끝”이라고 생각한다
표 구조·헤딩 위계·개조식 경로가 무너지면 검색 품질이 바로 깨집니다.
가능하면 chunks / blocks를 보고, 표를 독립 단위로 다루세요.
실수 2. patch와 generate를 같은 버튼으로 쓴다
원본 서식을 살려야 하면 patch.
새 공문서를 표준 양식으로 만들면 generate.
용도가 다릅니다.
실수 3. MCP만 붙이고 산출물을 안 본다
에이전트가 “성공”이라고 말해도, render나 한컴으로 열어보세요.
문서 품질은 로그가 아니라 조판으로 판정됩니다.
실수 4. 좋은 PDF만으로 평가한다
kordoc의 존재 이유는 “나쁜 문서”입니다.
스캔, 무괘선 표, 병합 표, 구버전 HWP, 배포용 잠금 — 이런 샘플로 먼저 시험하세요.
실수 5. 마스킹 결과를 자동 공개한다
redact는 보조 도구입니다.
오탐·미탐이 있을 수 있으니, 대외 배포 전에는 사람이 한 번 더 봅니다.
정리해봅시다!
1.
kordoc은 HWP·HWPX·PDF·Office·이미지까지 마크다운으로 읽고, 필요하면 HWPX로 다시 쓰는 한국 문서 도구다.
2.
핵심 가치는 단순 추출이 아니라 서식 보존 라운드트립 + 공문서 생성 + MCP 연동이다.
3.
RAG를 생각한다면 chunks로 헤딩·개조식 위계와 표를 분리해 보는 편이 낫다.
4.
CLI로 바로 쓸 수 있고, npx kordoc setup으로 에이전트에 15개 문서 도구를 붙일 수 있다.
5.
벤치 숫자와 CHANGELOG의 밀도는 신뢰 신호지만, 자기 문서 코퍼스로의 검증은 여전히 필수다.
6.
자동 변환·마스킹·날인 결과는 초안으로 다루고, 대외 산출물은 사람 검수를 남겨라.
한 줄 평:
한국에서 LLM을 붙일 때 가장 먼저 깨지는 층이 “문서”라면, kordoc은 그 층을 인프라로 끌어올리려는 시도입니다.
파서라기보다 문서 워크스페이스를 에이전트에 열어 주는 어댑터에 가깝습니다.