kordoc: 대한민국 공문서 처리를 위한 고성능 문서 파싱 및 자동화 라이브러리

kordoc은 대한민국 공무원이 현장에서 7년간의 경험을 바탕으로 개발한, 다양한 문서 포맷(HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX)을 파싱, 분석, 비교 및 생성하는 AI 에이전트 연동용 오픈소스 도구입니다.

1. 핵심 methodology 및 기술적 상세

kordoc은 단순 텍스트 추출을 넘어, 원본 문서의 서식과 구조를 완벽하게 보존하는 '서식 보존 무손실 라운드트립(Lossless Round-trip)' 워크플로를 지향합니다.

• HWPX 및 HWP 5.x 서식 보존 패치: patchHwpx와 patchHwp API를 통해, 수정된 마크다운 내용을 원본 문서의 XML 구조나 OLE2 바이너리 스트림에 직접 반영합니다.
  • patchHwp의 경우, CFB(Compound File Binary) 전체를 재조립하지 않고 대상 섹터 및 FAT(File Allocation Table) 체인만을 갱신하여 1바이트의 오차도 없이 원본 서식을 유지합니다.
  • 증분 패치(Incremental Patching): HwpxSession을 통해 블록 인덱스 기반으로 텍스트나 표 셀을 직접 편집하며, session.patchBlocks()를 통해 수정 범위 외의 XML은 원본 바이트를 그대로 보존합니다.
• 고정밀 파싱 알고리즘:
  • 표 구조 분석: 선이 없는 PDF나 복잡하게 병합된 HWP 표를 분석하여 마크다운 테이블로 복원하며, colSpan/rowSpan 기반의 그리드 계산 버그를 해결하여 99.9% 이상의 정확도를 확보했습니다.
  • PDF 품질 분석: parsePdf 결과에 pageQuality 신호를 포함시켜 needsOcr 여부를 판별합니다. 텍스트 레이어의 깨짐 현상(CMap 손상, 제어 문자 혼입 등)을 controlCharRatio나 replacementCharRatio와 같은 지표로 측정합니다.
• 구조화된 데이터 활용: IRBlock이라는 내부 표현 계층을 사용하여 문서 내 요소를 heading, paragraph, table, list, image, separator의 6가지 타입으로 분류하고 bbox(Bounding Box) 정보를 포함합니다.

2. 주요 기능 및 파이프라인

• 문서 비교(Diffing): compare() 함수를 통해 신구대조표를 자동 생성하며, HWP와 HWPX 등 상이한 포맷 간의 크로스 비교도 지원합니다.
• 양식 자동화(Form Filling): 템플릿 문서 내의 레이블-값 셀 패턴을 인식하고 fillForm을 통해 원본 서식(글꼴, 크기, 정렬 등)을 유지하며 값을 채워 넣습니다.
• OCR 및 에러 핸들링: OCR을 직접 탑재하지 않는 대신, 적절한 OCR 프로바이더와 연동할 수 있는 인터페이스를 제공합니다. 또한, 보안 강화를 위해 ZIP bomb 방지, XXE(XML External Entity) 공격 방지, SSRF(Server-Side Request Forgery) 차단 등 프로덕션급 보안 로직을 적용했습니다.
• AI 에이전트 연동(MCP): Claude Desktop, Cursor, Windsurf 등 주요 AI 에이전트와 연동되는 MCP(Model Context Protocol) 서버를 제공하여, 에이전트가 직접 parse_document, compare_documents, fill_form 등 8개 도구를 호출할 수 있도록 설계되었습니다.

3. 기술적 사양 요약

• 성능 지표: 실측 공문서 324건 기준 HWPX 텍스트 재현율 99.998%, 표 구조 정확일치 100% 달성.
• 호환성: Node.js 18+ 기반, macOS / Linux / Windows 공용.
• 라이선스: MIT 라이선스 기반 (rhwp, pdfjs-dist, cfb, JSZip 등의 오픈소스 모듈 활용).

kordoc은 공문서 처리의 복잡한 반복 작업을 자동화하고, AI가 생성한 결과물을 공문서 양식으로 완벽하게 되돌리는 데 최적화된 고도화된 도구입니다.