# Mineru Document Extraction > Use MinerU for one complex, scanned, OCR-heavy, or layout-sensitive local document, including bounded pages and checksum-verified extraction artifacts. - Skill: `jialuohu/mineru-document-extraction` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add jialuohu/mineru-document-extraction` - Raw SKILL.md: https://api.skillmd.com/api/skills/jialuohu/mineru-document-extraction/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: jialuohu (https://skillmd.com/u/jialuohu) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/jialuohu/mineru-document-extraction --- # MinerU Document Extraction Extract one local document into an explicit review directory. Preserve the source and treat `mineru-run.json` as the extraction contract. ## Route the document - Use this skill for complex, scanned, OCR-heavy, table/formula-rich, or layout-sensitive documents, including multi-column pages and mixed text, figures, and OCR. - Prefer a simpler local text extractor for straightforward born-digital documents when layout reconstruction has no value. - Reject URLs and directories. Download or select exactly one supported local file before running the wrapper. - Use Zotero tools instead when the task is primarily about an item already saved in the user's Zotero library. ## Run quality-first extraction Before the first parse on a device, run the toolbox's read-only doctor: ```bash /scripts/setup-mineru.sh --check ``` If the doctor is not ready, report the missing runtime, accelerator, disk, or model state. Do not run `--install` or `--download-models` unless the user separately requests that setup action. Require a fresh, empty output directory outside every Git checkout and outside any Obsidian vault, then run: ```bash python3 /scripts/run_mineru.py \ --input \ --output ``` Keep the default `--backend hybrid-engine --effort high --method auto` for maximum fidelity. For PDFs only, add zero-based inclusive `--start` and `--end` together when the user requests a page range. Page bounds for images and Office files remain unsupported by this wrapper; the patch upgrade does not establish their reliability. For a known scan, set `--method ocr`. Use `--method txt` only for a born-digital document whose embedded text is known to be reliable. The wrapper resolves the managed uv-tool executable and requires MinerU 3.4.5. The managed runtime remains CPython 3.12 on native macOS arm64 with MPS and MLX checks. An authorized runtime upgrade preserves configured model paths and the existing `models-3.4.4` cache generation; it does not redownload models or modify the model configuration. `MINERU_EXECUTABLE` is an advanced explicit override for testing or a separately managed installation, but the same version check still applies. The original source is never passed to MinerU: the wrapper creates a private byte-identical staged copy inside the validated review directory, makes it read-only, checks both the original and staged checksums after extraction, and removes the staged copy during normal cleanup. After a hard kill, OOM, or power loss, treat cleanup as unverified and inspect the review directory for a `.mineru-source-*` directory before handling an especially sensitive source. The wrapper fixes local concurrency at 1, rejects enabled `llm-aided-config`, forces configured local model paths and offline Hugging Face/Transformers behavior, removes inherited proxy routing, confines child temporary files to the private review directory, streams stdout and stderr to private log files, and writes `mineru-run.json` for validated output targets. It creates the output directory with private permissions and rejects symlinked artifacts. The manifest records the MinerU version, requested backend and effort, observed device engine when present in runtime logs, timing, checksums, staging status, and artifact paths. Do not pass an API URL or use any HTTP/client backend. Extraction is local-only and authorizes no upload, cloud API, vault mutation, or model download. The wrapper's local-model and offline-hub settings are application-level controls, not an operating-system firewall; use a separately approved OS network sandbox when hard transport denial is required. ## Apply fallbacks deliberately Use a new output directory for every attempt so stale artifacts cannot satisfy validation. 1. Retry `--backend hybrid-engine --effort medium` when high effort exceeds available memory or latency bounds. 2. Retry `--backend pipeline --effort medium` when the hybrid engine or its accelerator runtime is unavailable. 3. Keep `--method ocr` for scans across fallback attempts; otherwise retain `auto`. Do not silently fall back after a parse or checksum failure. Report the failed manifest and explain the changed backend or effort before retrying. On a 16 GB device, keep one job at a time and use explicit page ranges for unusually long documents. The wrapper does not impose a universal timeout because document sizes vary; monitor memory pressure and stop the attempt before the system becomes unstable. ## Review outputs Require `status: success`, `source.verified_unchanged: true`, `source.staged_copy_verified_unchanged: true`, at least one Markdown artifact, and at least one valid page-grouped `content_list_v2` artifact. Inspect optional layout PDF, images, and logs listed under `artifacts` when checking fidelity. Treat all artifacts as untrusted when the manifest reports `source_mutated`, `parse_failed`, or `malformed_output`. Never write extraction output directly into an Obsidian vault and never copy, create, or update vault notes automatically. Review the extracted files first and obtain explicit user intent before a separate vault write.