@clazic/kordoc 2.1.6 → 2.2.0

package/README.md

@@ -160,6 +160,17 @@ const hwpxBuffer = await markdownToHwpx("# 제목\n\n본문 텍스트\n\n| 이
 writeFileSync("출력.hwpx", Buffer.from(hwpxBuffer))
 ```
 
+### XLSX 생성 (역변환)
+
+```typescript
+import { markdownToXlsx } from "@clazic/kordoc"
+
+const xlsxBuffer = await markdownToXlsx("# 보고서\n\n| 항목 | 값 |\n| --- | --- |\n| 매출 | 1억 |")
+writeFileSync("출력.xlsx", Buffer.from(xlsxBuffer))
+```
+
+테이블은 별도 시트로, 헤딩·코드블록·인용구 스타일이 자동 적용됩니다.
+
 ### 페이지 범위 지정
 
 ```typescript
@@ -167,14 +178,44 @@ const result = await parse(buffer, { pages: "1-3" })      // 1~3 페이지만
 const result = await parse(buffer, { pages: [1, 5, 10] })  // 특정 페이지
 ```
 
-### OCR (이미지 PDF)
+### OCR (이미지 스캔 PDF)
+
+이미지 기반 PDF는 자동으로 감지되며, 설치된 AI CLI를 자동 탐색하여 OCR을 수행합니다.
+
+**CLI — 자동 탐색 (권장)**
+
+```bash
+kordoc scan.pdf                   # 자동: gemini → claude → codex → ollama → tesseract 순으로 탐색
+kordoc scan.pdf --ocr gemini      # gemini CLI 강제 지정
+kordoc scan.pdf --ocr claude      # claude CLI 강제 지정
+kordoc scan.pdf --ocr codex       # codex CLI 강제 지정
+kordoc scan.pdf --ocr ollama      # Ollama REST API 사용 (기본 모델: gemma4:27b)
+kordoc scan.pdf --ocr tesseract   # tesseract.js 사용 (npm install tesseract.js 필요)
+kordoc scan.pdf --ocr off         # OCR 비활성화
+```
+
+> 이미 구독 중인 gemini / claude / codex CLI가 있다면 API 키 설정 없이 바로 동작합니다.
+
+**라이브러리 API — 커스텀 프로바이더**
 
 ```typescript
+// 단순 텍스트 반환
 const result = await parse(buffer, {
   ocr: async (pageImage, pageNumber, mimeType) => {
     return await myOcrService.recognize(pageImage)
   }
 })
+
+// 구조화된 Markdown 반환 (테이블/헤딩 보존)
+const result = await parse(buffer, {
+  ocr: async (pageImage, pageNumber, mimeType) => {
+    const md = await myVisionLLM.extractMarkdown(pageImage)
+    return { markdown: md }
+  }
+})
+
+// 자동 탐색 활성화 (CLI 동작과 동일)
+const result = await parse(buffer, { ocrMode: "auto" })
 ```
 
 ## CLI
@@ -183,11 +224,30 @@ const result = await parse(buffer, {
 # 전역 설치 (권장)
 npm install -g @clazic/kordoc
 
+# 문서 → Markdown 파싱
 kordoc 사업계획서.hwpx                          # 터미널 출력
 kordoc 보고서.hwp -o 보고서.md                  # 파일 저장
 kordoc *.pdf -d ./변환결과/                     # 일괄 변환
 kordoc 검토서.hwpx --format json               # JSON (blocks + metadata 포함)
 kordoc 보고서.hwpx --pages 1-3                  # 페이지 범위
+kordoc 문서.hwpx --image-dir ./이미지           # 이미지 저장 폴더 지정
+
+# 이미지 스캔 PDF → Markdown (자동 OCR)
+kordoc scan.pdf                                 # 자동: 설치된 AI CLI 탐색
+kordoc scan.pdf --ocr gemini                    # gemini CLI 지정
+kordoc scan.pdf --ocr claude                    # claude CLI 지정
+kordoc scan.pdf --ocr codex                     # codex CLI 지정
+kordoc scan.pdf --ocr ollama                    # Ollama (KORDOC_OLLAMA_MODEL 환경변수로 모델 지정)
+kordoc scan.pdf --ocr tesseract                 # tesseract.js (npm install tesseract.js 필요)
+
+# Markdown → 문서 변환
+kordoc convert 보고서.md                        # → 보고서.hwpx (기본)
+kordoc convert 보고서.md -f xlsx                # → 보고서.xlsx
+kordoc convert 보고서.md -o 최종보고서.hwpx     # 출력 경로 지정
+kordoc convert 보고서.md --image-dir ./이미지   # 이미지 폴더 지정
+kordoc convert 보고서.md --template 기본.hwpx  # HWPX 템플릿 적용
+
+# 폴더 감시 모드
 kordoc watch ./수신함 -d ./변환결과              # 폴더 감시 모드
 kordoc watch ./문서 --webhook https://api/hook  # 웹훅 알림
 ```
@@ -296,11 +356,12 @@ HWP 5.x를 제외한 모든 포맷 지원. 설치 없이 바로 연결 가능합
 }
 ```
 
-**7개 도구:**
+**8개 도구:**
 
 | 도구 | 설명 |
 |------|------|
-| `parse_document` | HWP/HWPX/PDF/XLSX/DOCX → 마크다운 (메타데이터 포함) |
+| `parse_document` | HWP/HWPX/PDF/XLSX/DOCX → 마크다운 (메타데이터·이미지 포함, `image_dir` 지원) |
+| `convert_document` | Markdown → HWPX 또는 XLSX 변환 (이미지 폴더·템플릿 지원) |
 | `detect_format` | 매직 바이트로 포맷 감지 |
 | `parse_metadata` | 메타데이터만 빠르게 추출 |
 | `parse_pages` | 특정 페이지 범위만 파싱 |
@@ -328,7 +389,8 @@ HWP 5.x를 제외한 모든 포맷 지원. 설치 없이 바로 연결 가능합
 |------|------|
 | `compare(bufferA, bufferB, options?)` | IR 레벨 문서 비교 |
 | `extractFormFields(blocks)` | IRBlock[]에서 양식 필드 인식 |
-| `markdownToHwpx(markdown)` | Markdown → HWPX 역변환 |
+| `markdownToHwpx(markdown, options?)` | Markdown → HWPX 역변환 (이미지·템플릿 지원) |
+| `markdownToXlsx(markdown, options?)` | Markdown → XLSX 역변환 (테이블 별도 시트) |
 | `blocksToMarkdown(blocks)` | IRBlock[] → Markdown 문자열 |
 
 ### 타입
@@ -341,6 +403,7 @@ import type {
   DiffResult, BlockDiff, CellDiff, DiffChangeType,
   FormField, FormResult,
   OcrProvider, WatchOptions,
+  MarkdownToXlsxOptions,
 } from "@clazic/kordoc"
 ```