kordoc 4.1.0 → 4.2.1

package/README.md

@@ -7,11 +7,13 @@
 
 > *대한민국에서 둘째가라면 서러울 문서지옥. 거기서 7년 버틴 공무원이 만들었습니다.*
 
-HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX — 관공서에서 쏟아지는 모든 문서를 파싱하고, 비교하고, 분석하고, 생성합니다.
+HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX, 이미지(PNG/JPG/WebP) — 관공서에서 쏟아지는 모든 문서를 파싱하고, 비교하고, 분석하고, 생성합니다.
 
 [English](./README-EN.md)
 
-![kordoc 데모](./demo.gif)
+[![Kordoc 활용하기 — 영상 보기](./docs/video-demo.jpg)](https://youtu.be/Q13GmgDcIw0)
+
+<sub>▶ 클릭하면 유튜브에서 재생됩니다.</sub>
 
 ---
 
@@ -27,7 +29,7 @@ npx -y kordoc setup
 1. 사용 중인 AI 클라이언트 번호 선택 (Claude Desktop / Cursor / Claude Code / Windsurf / VS Code / Gemini CLI / Zed / Antigravity — 설치된 건 `[감지됨]` 표시)
 2. 설정 파일 자동 패치 → 클라이언트 재시작
 
-Windows 도 자동으로 `cmd /c npx` 래핑. 수동 JSON 편집 불필요. 재시작하면 11개 문서 도구 (`parse_document`, `parse_table`, `fill_form`, `patch_document`, `generate_document` 등) 활성화.
+Windows 도 자동으로 `cmd /c npx` 래핑. 수동 JSON 편집 불필요. 재시작하면 15개 문서 도구 (`parse_document`, `parse_table`, `fill_form`, `patch_document`, `generate_document` 등) 활성화.
 
 > **CLI 로만 쓸 거면** 설치 없이 `npx kordoc <파일>` 바로 사용. 아래 [CLI](#cli) 섹션 참고.
 
@@ -70,7 +72,7 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 
 단순한 텍스트 추출을 넘어, **공문서 처리를 위한 모든 과정**을 자동화합니다.
 
-*   **📄 어떤 문서든 마크다운으로**: `HWP3` (구버전), `HWP`(5.x), `HWPX`, `HWPML`, `PDF`, `XLS`, `XLSX`, `DOCX` 파일을 즉시 `Markdown`으로 변환합니다. AI(LLM)가 문서를 읽고 분석하기 가장 좋은 상태로 만들어줍니다.
+*   **📄 어떤 문서든 마크다운으로**: `HWP3` (구버전), `HWP`(5.x), `HWPX`, `HWPML`, `PDF`, `XLS`, `XLSX`, `DOCX` 파일은 물론 `PNG`/`JPG`/`WebP` 이미지(자동 OCR)까지 즉시 `Markdown`으로 변환합니다. AI(LLM)가 문서를 읽고 분석하기 가장 좋은 상태로 만들어줍니다.
 *   **📊 복잡한 표(Table) 완벽 재현**: 선이 없는 PDF나 복잡하게 병합된 HWP 표도 구조를 분석하여 정확한 마크다운 테이블로 복원합니다. 법령 개정안 PDF의 신구조문대비표도 통째로 살립니다 (v3.16.2).
 *   **🔍 신구대조표 자동 생성**: 두 문서의 차이점을 분석하여 무엇이 바뀌었는지 한눈에 보여줍니다. (HWP와 HWPX 간의 비교도 가능!)
 *   **📝 마크다운을 다시 HWPX로**: AI가 작성한 내용을 다시 보고서 양식(`HWPX`)으로 되돌려줍니다. 이제 복사-붙여넣기 노가다에서 해방되세요.
@@ -84,6 +86,17 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 
 ---
 
+## 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 조판, 검색어 형광펜 지원).
@@ -108,7 +121,7 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 ## v4.0.6 변경사항
 
 - **📊 PDF 무괘선 밴드 표 파편화 수정**: 세출예산 사업명세서류의 요약행 밴드에서 수직선이 끊겨 부서명이 유실되던 것을 4중 가드 수직선 브리지로 복원 (광진구 2026 세출예산 637곳 실측).
-- **📝 HWPX 캡션 안 중첩표 보존 (#46)**: 캡션 속 표 내용이 통째로 사라지던 것(304자 중 297자)을 문서 순서 평탄화로 보존. 제보 [@jumaniac](https://github.com/jumaniac), 조언 [@hiSandog](https://github.com/hiSandog).
+- **📝 HWPX 캡션 안 중첩표 보존 (#46)**: 캡션 속 표 내용이 통째로 사라지던 것(304자 중 297자)을 문서 순서 평탄화로 보존. 제보 [@jumaniac](https://github.com/jumaniac), 조언 @hiSandog.
 
 ## v4.0.5 변경사항
 
@@ -148,7 +161,7 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 
 ## v3.18.0 변경사항
 
-- **🎨 서식 프로필**: 표의 위상뿐 아니라 **테두리·음영·열 실측폭·셀 글꼴까지** 원본 문서 없이 재현합니다. `hwpxToProfile(hwpx)`로 레퍼런스 서식만 JSON으로 추출하고, `markdownToHwpx(md, { profile })`로 다른 문서에 그 서식을 입힙니다 — 원본 유출 없이 기관 서식만 공유·재현(이슈 #41, 스키마 [`docs/format-profile-spec.md`](docs/format-profile-spec.md)). 스키마·예시 기여: [@chiclooc-rgb](https://github.com/chiclooc-rgb) (PR #42).
+- **🎨 서식 프로필**: 표의 위상뿐 아니라 **테두리·음영·열 실측폭·셀 글꼴까지** 원본 문서 없이 재현합니다. `hwpxToProfile(hwpx)`로 레퍼런스 서식만 JSON으로 추출하고, `markdownToHwpx(md, { profile })`로 다른 문서에 그 서식을 입힙니다 — 원본 유출 없이 기관 서식만 공유·재현(이슈 #41, 스키마 [`docs/format-profile-spec.md`](docs/format-profile-spec.md)). 스키마·예시 기여: [@ai-localgov-officer](https://github.com/ai-localgov-officer) (PR #42).
 
 ## v3.17.0 변경사항
 
@@ -491,7 +504,7 @@ MCP 등록 대신 스킬(SKILL.md) 형태로 쓰려면:
 - **구조화 파싱** — `IRBlock[]`과 `DocumentMetadata`에 직접 접근. 마크다운 넘어선 데이터 활용.
 - **페이지 범위** — `parse(buffer, { pages: "1-3" })` — 필요한 페이지만 빠르게.
 - **Markdown → HWPX** — 역변환. AI가 생성한 내용을 바로 공문서로.
-- **OCR 연동** — 이미지 기반 PDF도 텍스트 추출 (Tesseract, Claude Vision 등 프로바이더 직접 제공).
+- **OCR** — 스캔/이미지 PDF 텍스트 추출. 내장 엔진(`ocr: true`, PP-OCRv5 korean) 또는 외부 프로바이더(Tesseract, Claude Vision 등).
 - **Watch 모드** — `kordoc watch ./수신함 -d ./변환결과 --webhook https://...`
 - **MCP 7개 도구** — parse_document, detect_format, parse_metadata, parse_pages, parse_table, compare_documents, parse_form
 - **에러 코드** — `"ENCRYPTED"`, `"ZIP_BOMB"`, `"IMAGE_BASED_PDF"` 등 구조화된 에러 핸들링
@@ -638,12 +651,26 @@ const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
 const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지
 ```
 
-### OCR (이미지 PDF)
+### OCR (스캔/이미지 PDF) — 내장 엔진 (v4.2.0+)
+
+```typescript
+// 내장 OCR (PP-OCRv5 korean, 첫 사용 시 모델 ~18MB 자동 다운로드)
+const result = await parse(buffer, { ocr: true })     // OCR 필요 페이지만 자동 판정
+const result = await parse(buffer, { ocr: "force" })  // 전 페이지 강제 OCR
+```
+
+- **API 키·외부 서비스 불필요** — det(선 검출)+rec(CTC 인식) ONNX 를 로컬 CPU 로 추론합니다
+  (PaddlePaddle 공식 변환본, Apache-2.0 / 한국어 사전 11,945자 — 완성형 한글 11,172자 전량 + 자모·라틴·기호).
+- **페이지 단위 정밀 적용** — 텍스트층이 없는 스캔 페이지, ToUnicode 가 깨진 페이지
+  (`needsOcr` 신호)만 OCR 하고 정상 페이지의 파싱 결과는 그대로 유지합니다.
+- **표 복원** — OCR 라인 좌표를 기존 블록 파이프라인(xy-cut 읽기 순서 + 클러스터 표
+  감지)에 태우므로 스캔본에서도 표 구조가 복원됩니다.
+- 외부 OCR 을 쓰고 싶으면 종전대로 프로바이더 함수를 전달하세요:
 
 ```typescript
 const result = await parse(buffer, {
   ocr: async (pageImage, pageNumber, mimeType) => {
-    return await myOcrService.recognize(pageImage)
+    return await myOcrService.recognize(pageImage) // Claude Vision, Tesseract 등
   }
 })
 ```
@@ -655,8 +682,8 @@ PDF는 텍스트층이 있어도 ToUnicode/CMap이 깨졌거나 NUL 등 제어
 ```typescript
 const r = await parsePdf(buffer)
 if (r.success && r.qualitySummary?.needsOcr) {
-  // OCR 큐로 라우팅 (kordoc은 OCR을 기본 탑재하지 않음)
-  await routeToOcr(buffer, r.qualitySummary.ocrCandidatePages)
+  // 내장 OCR 로 재시도 (v4.2.0+) — 또는 외부 OCR 큐로 라우팅
+  const retried = await parse(buffer, { ocr: true })
 }
 
 // 페이지 단위 신호

package/dist/{-AS4IABL2.js → -BSO3CDQQ.js}

@@ -30,6 +30,7 @@ import {
   parseHwp3,
   parseHwpml,
   parseHwpx,
+  parseImage,
   parsePdf,
   parseXls,
   parseXlsx,
@@ -39,8 +40,9 @@ import {
   renderHtml,
   unknownFontWarnings,
   validateHwpx
-} from "./chunk-L2XQQTOY.js";
-import "./chunk-UOO7LSDG.js";
+} from "./chunk-WWYAYZ5U.js";
+import "./chunk-7FCNOKOR.js";
+import "./chunk-54WVWWT4.js";
 import {
   detectFormat,
   detectOle2Format,
@@ -49,7 +51,7 @@ import {
   isOldHwpFile,
   isPdfFile,
   isZipFile
-} from "./chunk-YOO6ET6M.js";
+} from "./chunk-TCJRGFYY.js";
 import "./chunk-MOL7MDBG.js";
 import {
   applySplices,
@@ -57,7 +59,7 @@ import {
   buildRangeSplices,
   placeSealHwpx,
   scanSectionXml
-} from "./chunk-AX2R5Q2N.js";
+} from "./chunk-WJSGYVFD.js";
 import {
   DEFAULT_REDACT_RULES,
   redactMarkdown,
@@ -65,10 +67,10 @@ import {
 } from "./chunk-DZIXKL7E.js";
 import {
   blocksToChunks
-} from "./chunk-F2ZU3IZG.js";
+} from "./chunk-QOC7S5VE.js";
 import {
   blocksToMarkdown
-} from "./chunk-SSTK6IKK.js";
+} from "./chunk-QSB2RTX5.js";
 import {
   SPACE_EM_FIXED,
   SPACE_EM_FONT,
@@ -78,11 +80,11 @@ import {
   renderHwpxToSvg,
   simulateWrap,
   simulateWrapKeepWord
-} from "./chunk-37HJHCPA.js";
-import "./chunk-GQVSHGG4.js";
+} from "./chunk-PLTG6ZRF.js";
+import "./chunk-BHILWIE6.js";
 import {
   VERSION
-} from "./chunk-O5VS7RIR.js";
+} from "./chunk-Z6LPEWIX.js";
 export {
   DEFAULT_REDACT_RULES,
   HwpxSession,
@@ -133,6 +135,7 @@ export {
   parseHwp3,
   parseHwpml,
   parseHwpx,
+  parseImage,
   parsePdf,
   parseXls,
   parseXlsx,
@@ -150,4 +153,4 @@ export {
   unknownFontWarnings,
   validateHwpx
 };
-//# sourceMappingURL=-AS4IABL2.js.map
+//# sourceMappingURL=-BSO3CDQQ.js.map