kordoc

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 표도 구조를 분석하여 정확한 마크다운 테이블로 복원합니다.
• 🔍 신구대조표 자동 생성: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (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.16.0 변경사항

• 📊 차트 생성: 마크다운 ```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 스킬 자동 활성화.

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 변경사항