完美排版ocr

Full OCR pipeline for scanned PDFs with layout preservation. Use this skill whenever the user wants to OCR a PDF, convert a scanned document to searchable te...

Security Scan

The skill implements an OCR pipeline that uploads user PDFs to a third-party OCR API and expects an API token, but the skill metadata omits the required credential and does not clearly disclose remote uploads — this mismatch and external data flow are concerning.

Purpose & Capability

The code and SKILL.md implement exactly a remote-OCR pipeline (split → submit → poll → render) which fits the stated purpose. However, the script requires an API token (PADDLEOCR_TOKEN) and uses a remote endpoint (paddleocr.aistudio-app.com) while the skill's declared requirements list no environment variables or credentials. The missing declaration is an incoherence.

Instruction Scope

Runtime instructions tell the agent to pip-install dependencies and run the included pipeline script. The SKILL.md does not tell the user to set the API token, does not warn that full PDF contents will be uploaded to a remote service, and does not surface the exact remote endpoint — the agent will therefore transmit potentially sensitive documents without an explicit consent/notice step.

Install Mechanism

This is an instruction-only skill with an included script; there is no installer that downloads arbitrary code from unknown URLs. Dependencies are installed via pip at runtime per SKILL.md. No high-risk install URLs or archive extraction are present.

Credentials

The Python code reads PADDLEOCR_TOKEN from the environment (and falls back to a placeholder), but the skill metadata declares no required env vars or primary credential. Requesting a single OCR API token would be proportional to the task, but failing to declare it in the registry is a transparency issue and increases risk of accidental data leaks.

Persistence & Privilege

The skill is not always-enabled and does not request special agent privileges. It writes resumable state and intermediate files to a work directory (jobs.json, chunk_* files) which is normal for a pipeline; nothing in the package attempts to alter other skills or agent-wide settings.

What to consider before installing

This skill will upload entire PDF chunks to a third‑party OCR service (paddleocr.aistudio-app.com) and will fetch remote images referenced by OCR results. The code expects an environment variable PADDLEOCR_TOKEN, but the skill metadata does not declare that — you must set it yourself or the script will attempt to use a placeholder token. Before installing or running: (1) Do not process sensitive documents unless you trust the remote service and token; (2) Verify the OCR endpoint and its privacy/security policy; (3) Prefer using a self-hosted/local OCR alternative if you need confidentiality; (4) Run the script in an isolated environment (sandbox or VM) if you must test it; (5) Consider asking the publisher to update the registry metadata to declare PADDLEOCR_TOKEN and to explicitly disclose that PDFs are uploaded externally. If you want, I can point out the exact lines that send files and read the token so you can review them or suggest edits to make the behavior local-only.

PDF OCR with Layout Preservation

Automated pipeline: Split → OCR API → Layout PDF → Merge

Each original page becomes one PDF page, with text placed at exact bounding-box positions and font sizes calibrated to fill the original block dimensions.

Quick Start

python ~/.claude/skills/pdf-ocr-layout/scripts/pipeline.py "/path/to/input.pdf"

Output: input_ocr.pdf in the same directory. Intermediate files in input_ocr_work/.

Full Options

python ~/.claude/skills/pdf-ocr-layout/scripts/pipeline.py \
  "/path/to/input.pdf" \
  --output "/path/to/output.pdf" \
  --work-dir "/path/to/workdir" \
  --chunk-size 90

Steps for Claude

1. Ask for the PDF path if not already provided in the conversation.
2. Check dependencies (install only what's missing):

   pip install pypdf reportlab Pillow requests -q
   

3. Run the pipeline and stream output to the user:

   python ~/.claude/skills/pdf-ocr-layout/scripts/pipeline.py "{input_pdf}"
   

4. Monitor progress — the script prints step-by-step progress including API polling. API jobs typically take 1–5 minutes per 90-page chunk.
5. Report the output path when done.

Resume / Retry

The pipeline saves state to the work directory and is fully resumable:

• jobs.json — API job IDs (prevents re-submitting already-queued chunks)
• chunk_*_results.jsonl — cached OCR results (skip re-downloading)
• chunk_*_ocr.pdf — completed chunk PDFs (skip re-rendering)

If interrupted, simply re-run the same command. It picks up where it left off.

Common Issues

Problem	Fix
ModuleNotFoundError	Run the pip install command above
API 4xx error	Check the PDF isn't password-protected
Job stuck in running	Normal for large chunks; wait up to 10 min
Missing images in output	Images left blank per design (API images are optional)
Font too small/large	The font size auto-calibrates — first page may look different if it's a cover

Output Quality

• Block positions: exact (scaled from 812×1269px OCR space to A4)
• Font sizes: auto-calibrated using fs = min(√(h×w / n×0.65), h×0.72) — verified to recover original ~13–14pt body text
• Page numbers, headers, footers: included (all block types preserved)
• Images: embedded if URL accessible, blank if not
• 1 OCR page = 1 PDF page: always maintained