# 이미지·PDF·한글·워드·엑셀 읽기

OSCODE는 로컬 Tesseract OCR과 Poppler로 텍스트를 추출합니다. OCR 자체에는 모델 키가 필요하지 않습니다. `/ocr`는 로컬 결과만 표시합니다. `@파일`로 질문하거나 모델이 `read_document`를 호출하면 추출된 텍스트가 선택한 모델에 전달됩니다.

설치:

- macOS: `brew install tesseract tesseract-lang poppler`
- Ubuntu: `sudo apt install tesseract-ocr tesseract-ocr-kor poppler-utils`
- Windows: Tesseract(한국어 `kor` 데이터 포함)와 Poppler를 설치하고 실행 파일 폴더를 PATH에 추가합니다.

사용 예:

```text
/ocr screenshots/login.png
/ocr "docs/요구 사항.pdf"
/ocr {"path":"docs/spec.pdf","start":4,"pages":2,"language":"kor+eng"}
@docs/spec.pdf 요구사항을 정리해줘
@"screenshots/login screen.png" 오류 문구를 설명해줘
/context add docs/spec.pdf
```

지원: PNG, JPEG, WEBP, BMP, TIFF, PDF, HWP v5, HWPX, DOCX, XLSX. TXT·Markdown·소스 코드는 기존 텍스트 파일 첨부를 사용합니다. 구형 DOC/XLS는 DOCX/XLSX로 저장하세요. PPTX는 PDF로 변환해 첨부하세요. 텍스트와 이미지가 한 페이지에 섞인 PDF는 텍스트 레이어만 읽습니다. 이미지 내부 추가 글자, 표 구조, 시각적 디자인 해석은 보장하지 않습니다.

PDF는 기본 첫 3페이지, 호출당 최대 5페이지입니다. 페이지마다 텍스트 레이어가 비어 있으면 OCR로 전환합니다. 기본 OCR 언어는 `kor+eng`이며 설치되지 않은 언어는 안내 오류를 표시합니다. 영어만 설치된 환경은 `/ocr {"path":"image.png","language":"eng"}`로 사용할 수 있습니다.

프로젝트 내부 파일만 허용하며 파일당 최대 20 MiB입니다. 실행당 30초, 추출 프로세스 출력 128 KB 제한을 적용합니다. PDF 변환 이미지는 긴 변을 2400픽셀로 제한합니다. 임시 파일은 완료·실패·취소 시 제거합니다. 동일 콘텐츠·페이지 범위·언어의 결과는 메모리에 최대 8개 캐시하며 파일 변경 시 재추출합니다. 영구 OCR 캐시는 만들지 않습니다.

`@파일` 첨부는 파일당 2,000자로 제한하고 기존 요청 토큰 예산 검사를 적용합니다. 모델의 `read_document` 결과는 기존 도구 출력 한도로 제한됩니다. 추출 결과는 신뢰할 수 없는 문서 데이터로 표시하며, 문서 안의 지시는 사용자 명령으로 취급하지 않습니다. OCR에는 오인식이 있으므로 중요한 값은 원본과 대조하세요.

구현 참고: [Tesseract CLI](https://tesseract-ocr.github.io/tessdoc/Command-Line-Usage.html), [Poppler](https://poppler.freedesktop.org/).


## HWP / HWPX (0.18.0)

```text
/ocr docs/요구사항.hwp
/ocr "docs/검사 결과.hwpx"
@docs/요구사항.hwp 요구사항을 정리해줘
/context add docs/요구사항.hwpx
```

HWP v5는 별도 로컬 변환기 `hwp5txt`를 사용합니다. `pipx install pyhwp --pip-args="--pre"` 후 `pipx inject pyhwp lxml six`로 설치하고 hwp5txt를 PATH에 추가하세요. HWPX는 PATH의 `python3`와 표준 라이브러리만 사용합니다. 변환기를 npm에 포함하거나 자동 설치하지 않습니다. pyhwp는 별도 AGPL-3.0 프로젝트입니다.

두 형식은 OCR이 아니라 **본문 텍스트 추출**입니다. 페이지를 렌더링하지 않으므로 `start`와 `pages` 옵션은 오류로 안내합니다. 전체 본문을 추출한 뒤 최대 12,000자로 잘라 표시하며 이후 첨부·도구별 한도도 적용됩니다. 한글 문서의 표 셀 텍스트는 읽을 수 있지만 행·열 구조, 그림 속 글자, 수식·도형·머리말 등의 완전한 재현은 지원하지 않습니다. 스캔 이미지는 PDF로 변환해 기존 OCR을 사용하세요.

암호·배포용·구형 HWP·손상 파일은 변환기에 따라 실패할 수 있습니다. 실패나 빈 추출을 성공으로 표시하지 않고 HWPX/PDF 변환을 안내합니다. HWPX는 UTF-8 XML, 최대 100개 본문 구역·본문 XML 합계 8 MiB를 지원합니다. ZIP을 디스크에 풀지 않으며 암호화 ZIP·중복 항목·DTD/외부 엔티티를 거부합니다.

[한컴 HWPX 구조](https://tech.hancom.com/hwpxformat/), [pyhwp 텍스트 변환기](https://pyhwp.readthedocs.io/en/latest/converters.html)를 참고했습니다. 0.18.0에 포함된 기능입니다.


## 워드 / 엑셀 (0.18.0)

```text
/ocr docs/요구사항.docx
/ocr data/검사결과.xlsx
@docs/요구사항.docx 구현할 기능을 정리해줘
@data/검사결과.xlsx 수율 값을 설명해줘
```

Python 3(`python3`)만 필요하며 Word·Excel 설치 없이 로컬 ZIP/XML에서 추출합니다. `/ocr` 조회는 모델 호출이 없고, 질문에 첨부하면 추출 내용이 연결된 모델에 전달됩니다.

- DOCX: 본문 문단과 표 셀 텍스트를 읽습니다. 삭제된 변경 추적 텍스트는 제외합니다. 표의 원래 배치·병합, 머리말·꼬리말·각주·이미지 OCR·스타일 재현은 지원하지 않습니다.
- XLSX: 통합 문서 순서대로 시트명·표시 상태·셀 주소·값을 출력합니다. 숨김 시트도 포함하며 상태를 표시합니다. 공유 문자열과 셀 내부 문자열을 처리합니다.
- 수식은 실행·재계산하지 않습니다. 저장된 결과는 오래된 값일 수 있으며 `cached, not recalculated`로 표시합니다. 저장 결과가 없으면 `missing cached value`와 null을 표시합니다. 날짜·통화·백분율 서식은 적용하지 않아 원시 숫자가 표시될 수 있습니다. 차트·피벗·매크로는 실행하지 않습니다.
- XLSX 최대 20개 시트·5,000개 셀, 읽는 XML 합계 8 MiB, 추출 출력 128 KB입니다. 한도 초과는 실패로 안내합니다. 문서 리더가 표시하는 본문은 최대 12,000자이며 잘림을 표시합니다. 첨부에는 기존 더 작은 토큰 한도가 추가 적용됩니다.
- 페이지 선택(start/pages)은 지원하지 않습니다. 암호화·손상 파일, DTD·엔티티 XML, 외부 시트 연결은 거부합니다. 링크를 따라 네트워크 요청을 보내지 않습니다.

[Microsoft Word 문서 구조](https://learn.microsoft.com/en-us/office/open-xml/word/how-to-open-and-add-text-to-a-word-processing-document), [Excel 셀 구조](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.cell)를 참고했습니다.