MinerU 文档解析器

当 PDF 解析需要更可控的凭证与流程时

从扫描件或图片型 PDF 中提取可用的 Markdown，常见痛点在于：识别结果结构混乱、表格公式丢失，或调用第三方服务时凭证管理失控。MinerU Document Parser 面向这类工程问题，提供两种可落地的解析路径。

• 认证 API 工作流：优先在用户已持有 MinerU API base URL 与 token 的场景下启用。解析前需确认文件 URL 可达，且不将私有材料上传至未授权公网；将 assets/mineru-api.template.json 复制到技能目录外的私有位置，填入服务地址与凭证，再通过预检脚本验证配置与请求，避免误发。
• 本地 CLI 回退：仅在文件存储于本地或用户明确要求时使用。通过 scripts/check_environment.py 进行环境检查，必要时配置原生 MinerU，执行本地解析命令后读取 mineru-skill-manifest.json 指向的 Markdown 产物。

解析能力的边界与注意点

• 凭证边界：assets/ 中的 JSON 均为可公开模板，禁止作为真实配置。优先使用 MINERU_API_TOKEN 与 MINERU_API_BASE_URL 环境变量；默认 Authorization: Bearer ，非 Bearer 服务需按 configuration.md 配置 auth_header 与 auth_scheme。
• 输出校验：下载或生成 Markdown 后，必须验证文件非空，并对照源文件抽查标题层级、阅读顺序、表格、公式与图片引用。轮询超时时保留任务 ID 续跑，避免重复创建任务。
• 能力限制：仅支持 --language、--page-range、--ocr、--no-table、--no-formula 等文档已声明的选项；默认中文、启用表格、关闭 OCR、启用公式。API 报告失败、轮询超时或输出为空时，不得声称识别成功。

适用场景与不适用场景

• 适用：需要将 PDF/图片稳定转换为结构化 Markdown，且对凭证管理有明确工程约束的团队或个人。
• 不适用：希望零配置直接调用、或需要将凭证写入日志、响应、清单或发布包的场景。

本质上，该技能把 MinerU 的解析能力封装为可审计的工作流：在推进解析的同时，把凭证暴露面压到最低。