커스텀 지침과 함께

/ocr /path/to/document.pdf "표만 추출해줘" /ocr /path/to/screenshot.png "코드만 추출해줘"

폴더 내 모든 PDF/이미지 (병렬 처리)

/ocr /path/to/folder/


## Core Workflow

### Step 1: 경로 및 파일 타입 확인

```bash
# 파일인지 폴더인지 확인
ls -la <path>

파일 타입 분류:

.pdf → PDF 모드
.png, .jpg, .jpeg, .webp, .gif, .bmp, .tiff → 이미지 모드
폴더 → Batch Mode로 진행

Step 2: 저장 방식 선택 (PDF만 해당)

PDF 파일인 경우에만 사용자에게 저장 방식을 질문:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요?"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 페이지를 개별 마크다운 파일로 저장 (document_p1.md, document_p2.md, ...)"

저장 방식 변수:

unified: 통합 저장 → document.pdf → document.md
per_page: 페이지별 저장 → document.pdf → document_p1.md, document_p2.md, ...

이미지 파일: 저장 방식 질문 없이 바로 image.png → image.md로 변환

Single File Mode - Image

단일 이미지 파일 처리 워크플로우.

IMPORTANT: 단일 파일도 Task 에이전트를 사용하여 메인 컨텍스트를 보호합니다.

Task(subagent_type="general-purpose"):
  프롬프트: |
    이미지 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [이미지 절대경로]
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 이미지 읽기
    2. 이미지 내용을 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

Single File Mode - PDF

단일 PDF 파일 처리 워크플로우.

IMPORTANT: 단일 파일도 Task 에이전트를 사용하여 메인 컨텍스트를 보호합니다.

통합 저장 모드 (unified)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 마크다운으로 변환하고 저장해주세요.

    파일: [PDF 절대경로]
    저장 방식: 통합 (모든 페이지를 하나의 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 모든 페이지를 하나의 마크다운으로 변환
    3. Write 도구로 [파일명].md 파일 저장
    4. 저장 완료 확인

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [출력파일명].md
    또는
    ⚠️ 실패: [파일명] - [사유]

페이지별 저장 모드 (per_page)

Task(subagent_type="general-purpose"):
  프롬프트: |
    PDF 파일을 OCR하여 페이지별로 마크다운 파일을 생성해주세요.

    파일: [PDF 절대경로]
    저장 방식: 페이지별 (각 페이지를 개별 파일로)
    커스텀 지침: [사용자 지침 있으면 포함]

    **수행 작업:**
    1. Read 도구로 PDF 읽기
    2. 각 페이지별로 마크다운 변환
    3. 각 페이지를 개별 파일로 저장:
       - [파일명]_p1.md (1페이지)
       - [파일명]_p2.md (2페이지)
       - ...
    4. 모든 파일 저장 완료 확인

    **출력 파일 명명 규칙:**
    - document.pdf → document_p1.md, document_p2.md, document_p3.md, ...

    **에러 핸들링:**
    - 413 에러: "⚠️ 파일 크기 초과 (413 에러)"
    - 기타 에러: "⚠️ [에러 메시지]"

    **반환 형식 (내용 제외, 상태만):**
    ✅ 성공: [파일명] → [N]개 페이지 파일 생성
       - [파일명]_p1.md
       - [파일명]_p2.md
       - ...
    또는
    ⚠️ 실패: [파일명] - [사유]

Batch Mode (폴더 처리)

폴더 내 여러 PDF/이미지를 병렬로 처리.

1. 파일 목록 수집 및 분류

# 폴더 내 지원 파일 목록
ls <folder_path>/*.{pdf,png,jpg,jpeg,webp,gif,bmp,tiff} 2>/dev/null

파일 분류:

PDF 파일 목록: *.pdf
이미지 파일 목록: *.png, *.jpg, *.jpeg, *.webp, *.gif, *.bmp, *.tiff

2. 저장 방식 선택 (PDF가 있는 경우만)

PDF 파일이 포함된 경우에만 저장 방식 질문:

AskUserQuestion:
  question: "PDF 변환 결과를 어떻게 저장할까요? (이미지는 항상 통합 저장)"
  header: "저장 방식"
  options:
    - label: "통합 저장 (Recommended)"
      description: "각 PDF의 모든 페이지를 하나의 마크다운 파일로 저장"
    - label: "페이지별 저장"
      description: "각 PDF의 페이지를 개별 마크다운 파일로 저장"

3. 배치 분할 (3개 단위)

파일들을 3개씩 그룹으로 나눕니다 (PDF와 이미지 혼합 가능):

그룹 1: file1.pdf, image1.png, file2.pdf
그룹 2: image2.jpg, file3.pdf, image3.webp
...

4. 병렬 에이전트 실행

각 그룹에 대해 Task 도구로 병렬 에이전트 실행:

Task(subagent_type="general-purpose"):
  프롬프트: |
    다음 파일들을 OCR하여 마크다운으로 변환해주세요.

    파일 목록:
    - [file1 절대경로]
    - [file2 절대경로]
    - [file3 절대경로]

    PDF 저장 방식: [unified 또는 per_page]
    커스텀 지침: [사용자 지침 있으면 포함]
    출력 폴더: [원본과 동일 폴더]

    **파일 타입별 처리:**
    - PDF (.pdf): 지정된 저장 방식 적용
    - 이미지 (.png, .jpg 등): 항상 통합 저장 (image.png → image.md)

    **CRITICAL - 각 파일에 대해 에이전트 내에서 완료:**
    1. Read 도구로 파일 읽기
    2. 에러 발생 시 skip하고 다음 파일로 (413 에러 등)
    3. 마크다운으로 변환
    4. **Write 도구로 파일 저장** (반드시 에이전트 내에서!)
    5. 저장 완료 확인

    **IMPORTANT**:
    - 변환된 마크다운 내용을 메인으로 반환하지 마세요
    - 파일 저장까지 에이전트 내에서 완료해야 합니다
    - 메인에는 처리 결과 상태만 반환합니다

    처리 결과를 다음 형식으로만 보고 (내용 제외):
    ✅ 성공: [파일명] → [출력파일명].md
    ⚠️ SKIP: [파일명] - [사유]

IMPORTANT:

모든 그룹의 Task를 동시에 호출하여 병렬 실행
에이전트는 Read + Write 모두 완료 후 상태만 반환
메인 컨텍스트에 파일 내용이 로드되지 않도록 함

5. 결과 집계

모든 에이전트 완료 후 결과 집계:

## 📊 OCR 처리 결과

### ✅ 성공 ([N]개)
**PDF:**
- document1.pdf → document1.md
- document2.pdf → document2_p1.md, document2_p2.md (페이지별)

**이미지:**
- screenshot.png → screenshot.md
- photo.jpg → photo.md

### ⚠️ Skip ([M]개)
- large_file.pdf - 파일 크기 초과 (413 에러)
- corrupted.png - 읽기 실패

### 📁 출력 위치
[folder_path]/

마크다운 변환 가이드라인

파일 내용을 분석하여 다음 형식으로 마크다운 변환:

# 문서 제목

## 섹션 1
본문 내용...

### 표
| 열1 | 열2 |
|-----|-----|
| 값  | 값  |

### 이미지/다이어그램 설명
[이미지 설명: ...]

커스텀 지침 적용

사용자가 추가 지침을 제공한 경우:

"표만 추출" → 표 형식 데이터만 마크다운 테이블로
"요약해줘" → 핵심 내용만 요약
"영어로 번역" → 번역된 결과물
"코드만 추출" → 코드 블록만 추출

Supported Content Types

콘텐츠	변환 방식
일반 텍스트	그대로 마크다운
제목/섹션	# 헤딩으로 구조화
표	마크다운 테이블
목록	- 또는 1. 형식
이미지/다이어그램	[이미지 설명] 형태로 기술
코드	`언어` 코드 블록
수식	LaTeX ($...$) 형식
스크린샷 UI	UI 요소 및 텍스트 추출

Important Rules

Context 보호 (핵심)

ALWAYS Task 에이전트 내에서 Read + Write 모두 완료
ALWAYS 에이전트는 처리 상태만 반환 (변환된 내용 반환 금지)
NEVER 메인 컨텍스트에 파일 내용을 로드하지 않음

처리 방식

ALWAYS Read 도구를 사용하여 파일 읽기 (라이브러리 사용 금지)
ALWAYS 원본 문서의 구조를 최대한 보존
ALWAYS 사용자 커스텀 지침이 있으면 우선 적용
ALWAYS 에러 발생 시 해당 파일 skip하고 나머지 계속 처리
ALWAYS 폴더 처리 시 3개 단위로 병렬 에이전트 실행
NEVER 외부 라이브러리 사용하지 않음 (PyPDF, Pillow 등)
NEVER 읽을 수 없는 부분을 추측으로 채우지 않음 (불명확시 [불명확] 표시)
NEVER 하나의 context에서 모든 파일을 처리하지 않음 (메모리 초과 방지)

타입	확장자
PDF	`.pdf`
이미지	`.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.bmp`, `.tiff`

ocr

OCR (PDF + Image)

Supported Formats

Quick Start