Doc Reader

---
name: doc-reader
description: |
  HWP·HWPX·HWPML·PDF·XLSX·DOCX 등 문서의 내용을 읽고 표·메타데이터·양식 필드를 확인할 때 사용합니다.
  연결된 kordoc MCP의 실제 도구로 형식을 감지하고 결과와 경고를 원본에 대조합니다.
  요청 예: "이 HWP 파일 읽어줘", "PDF 표 추출해줘", "두 문서 비교해줘", "양식 필드 확인해줘".
version: "1.1.1"
---

# 문서 읽기 (doc-reader)

## 범위

이 플러그인의 `kordoc` MCP를 우선 사용한다. 이 저장소의 `.mcp.json`에 서버가 등록돼 있지만, 현재 호스트에서 도구가 실제로 연결됐는지 확인한다. [kordoc 원저작자 README](https://github.com/chrisryugj/kordoc/blob/main/README-EN.md)는 지원 형식과 도구를 설명한다. 도구 수나 기능은 배포 버전에 따라 달라지므로 이 문서의 목록을 런타임 검증으로 대신하지 않는다.

## 절차

1. 사용자가 제공한 파일의 경로·접근 권한과 읽기 목적을 확인한다. 원본을 수정하지 않는다.
2. 확장자가 의심스럽거나 입력 형식이 불명확하면 `detect_format`으로 확인한다.
3. 목적에 따라 현재 노출된 도구를 선택한다.

| 목적 | kordoc 도구 |
|---|---|
| 전체 내용 | `parse_document` |
| 메타데이터 | `parse_metadata` |
| 일부 페이지·표 | `parse_pages`·`parse_table` |
| 문서 간 차이 | `compare_documents` |
| 양식 필드 | `parse_form` |
| 기존 양식 채우기 | `fill_form` |
| 기존 HWPX/HWP 수정 | `patch_document` |
| 새 HWPX 생성 | `generate_document` → `moai-officer:doc-hwp` 절차 |
| 문서 미리보기 | `render_document` |

4. 파싱된 텍스트·표와 원본의 주요 부분을 대조한다. 병합 셀, 그림 속 글자, 스캔 페이지, 각주, 숨김 텍스트는 빠질 수 있으므로 결과의 `warnings`를 읽고 사용자에게 알린다.
5. 양식 채우기나 문서 수정은 쓰기 작업이다. 대상 필드·출력 경로를 확인하고 원본을 보존한다. 출력 파일을 다시 읽고 변경된 값·변경되지 않아야 할 서식을 대조한다.

## OCR·보호 문서

이미지·스캔 문서는 도구가 OCR 옵션을 제공하는지 확인하고, 문자 인식 결과를 원본 화면과 대조한다. 모델 다운로드나 네트워크 접근이 필요할 수 있다. 암호·DRM 보호 문서는 권한 있는 파일과 실제 지원 기능만 처리한다. 잠금을 우회할 수 있다고 보장하지 않는다. 오류가 나오면 오류 코드와 처리하지 못한 범위를 보고한다.

## 결과 보고

- 감지한 형식, 읽은 페이지 또는 범위, 추출한 주요 내용과 표를 명시한다.
- 원본에서 확인하지 못한 내용은 추정하지 않는다. `warnings`와 누락 가능성을 함께 전달한다.
- 수치나 법적 문구를 인용할 때는 원본 위치를 표시하고, 파싱만으로 진위나 효력을 판정하지 않는다.
- 비교 결과는 추가·삭제·수정의 근거를 원본 두 파일에 대조한다.
- 렌더링이나 대상 앱에서의 열림을 실행하지 못했다면 `미실행`으로 보고한다.

## 도구를 사용할 수 없을 때

현재 호스트의 문서 읽기 기능이 해당 형식을 실제로 지원하는지 확인한다. 다른 형식으로 변환해야 한다면 원본 보존과 변환 손실을 먼저 확인한다. 사용자의 컴퓨터에 Node.js·패키지 설치를 필수 절차로 요구하지 않는다. 처리 경로가 없으면 읽은 척하지 않는다.

## 관련 스킬

- `moai-officer:doc-hwp`: 새 HWPX 생성과 검수
- `moai-officer:doc-docx`: 새 DOCX 작성
- `moai-officer:doc-pdf`: PDF 출력
- `moai-officer:doc-xlsx`: XLSX 작성