mineru-document-extractor

name	mineru-document-extractor
description	当需要解析 PDF 或文档图片并转换为 Markdown 时使用。此技能基于 MinerU 提取文档中的结构化内容，支持扫描件 OCR，并可按需导出为 Markdown、HTML、LaTeX 或 DOCX。适用于 PDF 转 Markdown、提取 PDF 正文、识别扫描版 PDF、提取表格或公式、批量解析文档等任务。

MinerU 渠道选择型文档解析

执行顺序

1. 先检查 mineru-open-api 是否存在
2. 若不存在，执行官方安装命令
3. 安装后执行 mineru-open-api version
4. 使用get_secret tool 读取MINERU_TOKEN, 若读取不到则自动检测 MINERU_TOKEN 环境变量或 ~/.mineru/config.yaml：
   • 若已配置 Token → 默认使用 extract（完整模式）
   • 若未配置 → 用 ask_user 询问用户选择免费或 Token 模式
5. 统一输出到 <workspace>/mineru_skill/<name>_<hash>/

安装与校验

如果命令不存在，先安装 CLI，然后再继续解析。

Linux / macOS：

curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh

Windows（PowerShell）：

irm https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 | iex

Verify installation

mineru-open-api version

渠道选择

使用本 skill 时，先自动检测是否已配置 API Token，再决定渠道：

自动检测逻辑

按以下顺序检查 Token 是否存在：

1. 使用get_secret tool 读取 MINERU_TOKEN
2. 环境变量 MINERU_TOKEN
3. 配置文件 ~/.mineru/config.yaml

检测命令：

# 检查环境变量
echo "${MINERU_TOKEN:-}"

# 检查配置文件（如环境变量为空）
cat ~/.mineru/config.yaml 2>/dev/null | grep -q 'token' && echo "configured" || echo "not_configured"

检测结果处理

• 如果检测到 Token 已配置：默认使用 extract（Token/API 完整模式），无需询问用户。直接告知用户正在使用 Token 模式。
• 如果未检测到 Token：调用 ask_user 询问用户：

未检测到 MinerU API Token，你想走哪种渠道？

1. 官方免费快速模式：无需 token，但有 10MB / 20 页限制，且不含表格识别
2. Token/API 完整模式：需要先创建 token（https://mineru.net/apiManage/token），支持更大文件、表格/公式识别和多格式导出

	flash-extract	extract
Token required	No	Yes (mineru-open-api auth)
Speed	Fast	Normal
Table recognition	No	Yes
Formula recognition	No	Yes
OCR	Yes	Yes
Output formats	Markdown only	md, html, latex, docx, json
Batch mode	No	Yes
Model selection	pipeline	Yes (vlm, pipeline, MinerU-HTML)
File size limit	10 MB	Much higher
Page limit	20 pages	Much higher
Rate limit	Per-IP per-minute cap	Based on API plan
Best for	Quick start, small/simple docs	Large docs, tables, production

flash-extract limits

Limit	Value
File size	Max 10 MB
Page count	Max 20 pages
Supported types	PDF, Images (png/jpg/jpeg/jp2/webp/gif/bmp), Docx, PPTx
IP rate limit	Per-minute request caps (HTTP 429 when exceeded)

When any limit is exceeded, the agent should suggest switching to extract with a token (create at https://mineru.net/apiManage/token), which has significantly higher limits.

当未检测到 Token 时，不要替用户默认选择，必须询问用户。

Core workflow

1. auto_detect_or_ask: 先检测环境变量 MINERU_TOKEN 或 ~/.mineru/config.yaml 是否已配置 Token。若已配置则默认使用 extract；若未配置则 ask_user 选择免费或 Token 模式。
2. Start fast (no token): mineru-open-api flash-extract <file> for quick Markdown conversion
3. Need more? Create token at https://mineru.net/apiManage/token, run mineru-open-api auth, then use mineru-open-api extract for tables, formulas, OCR, multi-format, and batch
4. Check results: output goes to stdout (default) or -o directory

Authentication

Only required for extract . Not needed for flash-extract.

Configure your API token (create one at https://mineru.net/apiManage/token):

mineru-open-api auth                    # Interactive token setup
export MINERU_TOKEN="your-token"  # Or set via environment variable

Token resolution order: --token flag > MINERU_TOKEN env > ~/.mineru/config.yaml.

Supported input formats

Format	flash-extract	extract
PDF (.pdf)	Yes	Yes
Images (.png, .jpg, .jpeg, .jp2, .webp, .gif, .bmp)	Yes	Yes
Word (.docx)	Yes	Yes
Word (.doc)	No	Yes
PowerPoint (.pptx)	Yes	Yes
PowerPoint (.ppt)	No	Yes
HTML (.html)	No	Yes
URLs (remote files)	Yes	Yes

The crawl command accepts any HTTP/HTTPS URL and extracts web page content.

Commands

flash-extract — Quick extraction (no token needed)

Fast, token-free document extraction. Outputs Markdown only. No table recognition. Limited to 10 MB / 20 pages per file, with IP-based rate limiting.

mineru-open-api flash-extract report.pdf                     # Markdown to stdout
mineru-open-api flash-extract report.pdf -o ./out/           # Save to file
mineru-open-api flash-extract https://example.com/doc.pdf    # URL mode
mineru-open-api flash-extract report.pdf --language en       # Specify language
mineru-open-api flash-extract report.pdf --pages 1-10        # Page range

flash-extract flags

Flag	Short	Default	Description
--output	-o	(stdout)	Output path (file or directory)
--language		ch	Document language
--pages		(all)	Page range, e.g. 1-10
--timeout		900	Timeout in seconds

extract — Full extraction (token required)

Convert PDFs, images, and other documents to Markdown or other formats. Supports table/formula recognition, OCR, multiple output formats, and batch mode.

mineru-open-api extract report.pdf                         # Markdown to stdout
mineru-open-api extract report.pdf -f html                 # HTML to stdout
mineru-open-api extract report.pdf -o ./out/               # Save to directory
mineru-open-api extract report.pdf -o ./out/ -f md,docx    # Multiple formats
mineru-open-api extract *.pdf -o ./results/                # Batch extract
mineru-open-api extract --list files.txt -o ./results/     # Batch from file list
mineru-open-api extract https://example.com/doc.pdf        # Extract from URL
cat doc.pdf | mineru-open-api extract --stdin -o ./out/    # From stdin

extract flags

Flag	Short	Default	Description
--output	-o	(stdout)	Output path (file or directory)
--format	-f	md	Output formats: md, json, html, latex, docx (comma-separated)
--model		(auto)	Model: vlm, pipeline, html (see below)
--ocr		false	Enable OCR for scanned documents
--formula		true	Enable/disable formula recognition
--table		true	Enable/disable table recognition
--language		ch	Document language
--pages		(all)	Page range, e.g. 1-10,15
--timeout		900/1800	Timeout in seconds (single/batch)
--list			Read input list from file (one path per line)

| --concurrency | | 0 | Batch concurrency (0 = server default) |

Model comparison: vlm vs pipeline

	vlm	pipeline
Parsing accuracy	Higher — better at complex layouts, mixed content	Standard
Hallucination risk	May produce hallucinated text in rare cases	No hallucination — biggest advantage
Best for	Academic papers, complex tables, intricate layouts	General documents where fidelity matters most

When the user values accuracy and the document has complex formatting, suggest --model vlm. When the user prioritizes reliability and no-hallucination guarantee, suggest --model pipeline (or omit --model to use auto).

auth — Authentication management

mineru-open-api auth              # Interactive token setup
mineru-open-api auth --verify     # Verify current token is valid
mineru-open-api auth --show       # Show current token source and masked value

Supported --language values

The --language flag accepts the following values (default: ch). Used by both flash-extract and extract. Values are organized by script/language family — each value covers all languages listed in its group.

Standalone language packs

For specific languages or CJK combinations.

Value	Included languages	说明
ch	Chinese, English, Chinese Traditional	中英文（默认值）
ch_server	Chinese, English, Chinese Traditional, Japanese	繁体、手写体
en	English	纯英文
japan	Chinese, English, Chinese Traditional, Japanese	日文为主
korean	Korean, English	韩文
chinese_cht	Chinese, English, Chinese Traditional, Japanese	繁体中文为主
ta	Tamil, English	泰米尔文
te	Telugu, English	泰卢固文
ka	Kannada	卡纳达文
el	Greek, English	希腊文
th	Thai, English	泰文

Language family packs

One value covers many languages sharing the same script system.

Value	Script/Family	Included languages
latin	Latin script (拉丁语系)	French, German, Afrikaans, Italian, Spanish, Bosnian, Portuguese, Czech, Welsh, Danish, Estonian, Irish, Croatian, Uzbek, Hungarian, Serbian (Latin), Indonesian, Occitan, Icelandic, Lithuanian, Maori, Malay, Dutch, Norwegian, Polish, Slovak, Slovenian, Albanian, Swedish, Swahili, Tagalog, Turkish, Latin, Azerbaijani, Kurdish, Latvian, Maltese, Pali, Romanian, Vietnamese, Finnish, Basque, Galician, Luxembourgish, Romansh, Catalan, Quechua
arabic	Arabic script (阿拉伯语系)	Arabic, Persian, Uyghur, Urdu, Pashto, Kurdish, Sindhi, Balochi, English
cyrillic	Cyrillic script (西里尔语系)	Russian, Belarusian, Ukrainian, Serbian (Cyrillic), Bulgarian, Mongolian, Abkhazian, Adyghe, Kabardian, Avar, Dargin, Ingush, Chechen, Lak, Lezgin, Tabasaran, Kazakh, Kyrgyz, Tajik, Macedonian, Tatar, Chuvash, Bashkir, Malian, Moldovan, Udmurt, Komi, Ossetian, Buryat, Kalmyk, Tuvan, Sakha, Karakalpak, English
east_slavic	East Slavic (东斯拉夫语系)	Russian, Belarusian, Ukrainian, English
devanagari	Devanagari script (天城文语系)	Hindi, Marathi, Nepali, Bihari, Maithili, Angika, Bhojpuri, Magahi, Santali, Newari, Konkani, Sanskrit, Haryanvi, English

Output behavior

• No -o flag: result goes to stdout; status/progress messages go to stderr
• With -o flag: result saved to file/directory; progress messages on stderr
• Batch mode (extract/crawl only): requires -o to specify output directory
• Binary formats (docx, extract only): cannot output to stdout, must use -o
• Markdown output includes extracted images saved alongside the .md file

General rules

When using this skill on behalf of the user:

• Quote file paths that contain spaces or special characters with double quotes in commands. Example: mineru-open-api extract "report 01.pdf", NOT mineru-open-api extract report 01.pdf.
• Don't run commands blindly on errors — if the user asks "提取失败了怎么办", explain the exit code and troubleshooting steps instead of re-running the command.
• Installation questions ("mineru 怎么安装") should be answered with the install instructions, not by running mineru-open-api extract.
• DOCX as input is supported — if the user asks "这个 Word 文档能转 Markdown 吗", use mineru-open-api extract file.docx or mineru-open-api flash-extract file.docx. Note: .doc format is only supported by extract, not flash-extract.
• Table extraction — tables are only recognized by extract (not flash-extract). If the user mentions tables, use extract.
• For stdout mode (no -o), only one text format can be output at a time. If the user wants multiple formats, suggest adding -o.
• When the user does NOT specify an output path (-o), the agent MUST generate a default output directory to prevent file overwrites. Use:

~/<workspace>/mineru_paerser/<name>_<hash>/

Naming rules:

• <name>: derived from the source, then sanitized for safe directory names.
  • For URLs: last path segment (e.g. https://arxiv.org/pdf/2509.22186 → 2509.22186)
  • For local files: filename without extension (e.g. report.pdf → report)
  • Sanitization: replace spaces and shell-unsafe characters (space, (, ), [, ], &, ', ", !, #, $, `) with _. Collapse consecutive _ into one. Keep alphanumeric, -, _, ., and CJK characters.
• <hash>: first 6 characters of the MD5 hash of the full original source path or URL (before sanitization). This ensures:
  • Different URLs with similar basenames get unique directories
  • Re-running the same source reuses the same directory (idempotent) How the agent should generate the hash:

echo -n "https://arxiv.org/pdf/2509.22186" | md5sum | cut -c1-6

Or on macOS:

echo -n "https://arxiv.org/pdf/2509.22186" | md5 | cut -c1-6

flash-extract limit handling

When flash-extract fails due to file limits or rate limiting, the agent MUST provide a clear explanation and suggest extract as the upgrade path:

Rate limited (HTTP 429):

flash-extract 请求频率超出限制（每 IP 有每分钟/每小时的请求上限）。你可以：

1. 稍等几分钟后重试
2. 前往 https://mineru.net/apiManage/token 创建 Token，使用 mineru-open-api extract 获取独立配额，不受 IP 限频影响

Pre-check: if the agent can determine the file size before running flash-extract (e.g. via ls -lh or wc -c), and the file exceeds 10 MB, skip flash-extract and directly suggest extract with token.

Post-extraction friendly hints

After flash-extract completes successfully, the agent MUST append a brief hint:

Tip: flash-extract 为快速免登录模式（限 10MB/20页，不含表格识别）。如需解析更大文件、表格/公式识别或多格式导出，请前往 https://mineru.net/apiManage/token 创建 Token，运行 mineru-open-api auth 配置后使用 mineru-open-api extract。

Keep the hint to ONE short sentence. Do NOT repeat the hint if the user has already seen it in this session.

When the user specifies -o: use the user's path as-is, do NOT override with the default directory.

Exit codes

Code	Meaning	Recovery
0	Success	—
1	General API or unknown error	Check network connectivity; retry; use --verbose for details
2	Invalid parameters / usage error	Check command syntax and flag values

| 4 | File too large or page limit exceeded | For flash-extract: file must be under 10 MB / 20 pages; switch to extract with token for higher limits. For extract: split the file or use --pages | | 5 | Extraction failed | The document may be corrupted or unsupported; try a different --model | | 6 | Timeout | Increase with --timeout; large files may need 600+ seconds

Troubleshooting

• "no API token found" (on extract/crawl): Run mineru-open-api auth or set MINERU_TOKEN env variable. Or use flash-extract which needs no token.
• Timeout on large files: Increase with --timeout 1600 (seconds)
• Batch fails partially: Check stderr for per-file status; succeeded files are still saved
• Binary format to stdout: Use -o flag; docx cannot stream to stdout
• Private deployment: Use --base-url https://your-server.com/api
• Extraction quality is poor: Try mineru-open-api extract with --model vlm for complex layouts, or --ocr for scanned documents
• Tables not extracted: flash-extract does NOT support tables. Use mineru-open-api extract with a token.
• HTTP 429 on flash-extract: IP rate limit hit. Wait a few minutes or switch to mineru-open-api extract with token.

Notes

• extract requires a token but provides full-featured extraction
• All status/progress messages go to stderr; only document content goes to stdout
• Batch mode automatically polls the API with exponential backoff
• Token is stored in ~/.mineru/config.yaml after mineru-open-api auth