pdf-bookmarkslisted

# /pdf-bookmarks OCR한 책 PDF는 텍스트는 있지만 목차 기반 책갈피가 없다. 이 스킬은 책의 **인쇄된 목차 페이지**를 읽어 PDF outline(책갈피)을 생성한다. 사용자가 목차 따라 하나씩 손으로 책갈피 다는 노가다를 없앤다. 도구: **이 스킬 폴더의 `scripts/pdf_toc.py`** (PyMuPDF 기반). 아래 `$SCRIPT`는 이 SKILL.md와 같은 폴더의 `scripts/pdf_toc.py`를 가리킨다(위치 하드코딩 금지 — 스킬이 어디에 설치돼 있든 상대참조). ### 사전 요구 (먼저 확인) - **필수**: Python 3.9+ 와 `pymupdf`(`pip install pymupdf`). 책갈피 전 기능이 이걸로 동작(전 OS 동일). - **OCR가 필요할 때만**(생스캔): 플랫폼별 백엔드 — `auto`/`force`(tesseract, `ocrmypdf` 설치 시) 전 OS · `vision`(macOS 내장) · `winocr`(Windows 내장, 한국어 OCR 언어팩). 아래 OCR 스위치 참조. - **이미 OCR된 PDF**(Acrobat·ABBYY·PDF Expert 등 무엇으로든)는 OCR 불필요 → `--ocr off`(기본). - 샌드박스/제한 환경(tesseract·Vision·Windows OCR 없음)에서는 `--ocr off`만 쓰고 입출력 경로는 그 환경 규칙을 따른다. ## 핵심 개념 - 목차엔 `제목 …… 인쇄쪽번호`가 있다. 이걸 파싱해 outline으로 쓴다. - **함정: 인쇄 쪽번호 ≠ PDF 물리 페이지** (표지·서문 때문에 상수 오프셋 존재). `--offset auto`가 첫 제목을 본문에서 검색해 오프셋을 1회 산출한다. - 파싱·오프셋의 품질은 **목차 페이지 OCR 품질**이 좌우한다. 점선 리더·쪽번호가 뭉개지면 파싱이 흔들린다. ## 워크플로 (이 순서로 진행) `$SCRIPT` = 이 스킬 폴더의 `scripts/pdf_toc.py` (실제 절대경로로 치환해 실행) 1. **목차 페이지 찾기** — 앞부분 텍스트를 덤프해 "목차/Contents/차례"가 몇 쪽(PDF 물리 페이지)에 있는지 눈으로 확인한다. ``` python3 $SCRIPT extract <파일.pdf> ``` - 텍스트가 거의 안 나오면 **생스캔**(텍스트 레이어 없음)이다 → `--ocr auto` 붙여 다시: `extract <파일.pdf> --ocr auto`. 2. **미리보기(dry-run)** — 찾은 목차 페이지 범위로 파싱 결과를 사용자에게 보여주고 확인받는다. 조용히 적용하지 말 것. ``` python3 $SCRIPT apply <파일.pdf> --toc-pages <범위> --dry-run ``` - 항목이 0개거나 레벨/쪽이 이상하면: 범위를 조정하거나, 오프셋 자동감지 실패 시 `--offset <정수>` 수동 지정. 3. **적용** — 확인되면 dry-run을 빼고