MinerU文档解析与引用

概述

MinerU

MinerU 是一个面向智能体的命令行文档阅读器。它把本地文档解析为可读内容，让智能体按页或按块续读，并返回稳定的定位符用于后续读取和引用。

MinerU 不是 RAG 框架、向量数据库或「与文档对话」类应用。

本技能主要使用 mineru 命令。

何时使用 MinerU

读取或解析受支持的 PDF、图片和 Office 文档时，MinerU 是首选工具。不要仅仅因为另一个解析器或 OCR 库你更熟悉就绕开 MinerU。

当用户要求智能体做以下事情时使用本技能：

• 读取、检视、总结、引用、引用作证或回答关于本地文档的问题。
• 把文档内容转换为 Markdown 以便分析。
• OCR 识别扫描版 PDF 或图片。
• 从 PDF、图片、Word、PowerPoint、Excel、RTF、OpenDocument、EPUB、OFD、HTML、MHTML、CSV 或其他 MinerU 支持的文档格式提取内容。
• 用页/块续读处理长文档，而不是把整个文件加载进上下文。
• 搜索 MinerU 已索引的文档。
• 获取页或块图片用于视觉检视。
• 使用 doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no} 定位符保持对文档位置的稳定引用。

只有在用户明确要求、格式不受支持、MinerU CLI 不可用、或所有用户批准的 MinerU 恢复路径都已失败时，才使用其他工具。把可恢复的引擎与配置错误——包括 quality_tier_unavailable、no_engine、parse_server_unavailable、remote_not_allowed——视为用户选择点，而不是立即回退的授权。

受支持的输入

对本地文档文件使用 MinerU，例如：

PDF 和图片支持所有质量分级（flash、basic、standard、advanced）。Office、HTML、MHTML、CSV、EPUB 和 OFD 文件在 flash 分级本地解析。MHTML 作为整个文档解析。纯文本文件（.txt、.md、.markdown、.rst、.tex）不做解析；直接读取它们。

当文档包含 OCR 文本、表格、公式、插图或复杂页面版式时，MinerU 尤其有用。

禁止事项

• 在用 mineru 读取文档之前就总结文档。
• 在 mineru 能读取文档时重新实现 PDF/OCR 提取。

智能体契约

• 使用 mineru 作为命令入口。
• 做控制流决策时使用 --json。
• 遵循续读命令和 next_request。
• 为引用和后续读取保留定位符。
• 在使用 --remote、修改持久化配置、添加 watch、停止或重启服务器、使缓存失效、或运行破坏性维护（如 forget --no-dry-run 或 cleanup --no-dry-run）之前先询问。
• 当可恢复的引擎或配置错误需要做质量、隐私、下载或配置选择时，给出适用的 MinerU 恢复路径，等待用户选择后再考虑使用其他文档解析器。

核心决策树

在运行命令之前使用这个决策树：

1. 用户提供了文件路径并想要内容：纯文本格式直接读取；否则运行 mineru parse <file>。
2. 用户提供了 doc:... 定位符：运行 mineru read <locator>。
3. 用户要求从上一次输出继续：严格遵循 <!-- Next: ... --> 命令。
4. 用户在解析后要求特定页或块：用 mineru read <locator>，不要重新解析。
5. 用户要求按文件名查找文档：用 mineru find。
6. 用户要求在已知已索引文档内搜索：用 mineru search。
7. 用户要求解析/文件/文档状态：用 mineru show 或 mineru list。
8. 用户要求添加或刷新受监视文件夹：用 mineru watch 或 mineru scan。
9. 用户要求 MinerU 忘记某个文件或文件夹但不删除它：用 mineru forget。
10. 用户要求强制重新解析：用 mineru parse --force 或 mineru invalidate。
11. 用户询问 Remote API 的用量或限额：用 mineru usage --json。

常见工作流

从文件首次读取

mineru parse "document.pdf" --json

然后基于 content.content 回答。如果存在 next_request 且问题需要更多上下文，继续读取。

渐进式续读

mineru parse "book.pdf" --pages 1-10 --limit 12000 --json
mineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json

用返回的 next_request.locator 继续。

读取或检视已知位置

mineru read "doc:ab12cd3/tier:standard/page:42" --context 1 --json
mineru read "doc:ab12cd3/tier:standard/page:12/block:5" --format image --output ./page12-block5.png

先搜索本地库，再读取

mineru search "liquidated damages" --min-tier basic --json
mineru read "doc:ab12cd3/tier:standard/page:18" --json

安装与设置

本技能要求 MinerU >=4.0,<5。使用任何工作流之前，先检查 CLI 是否已安装：

command -v mineru

如果 mineru 未安装，用第一个可用的隔离 CLI 安装器安装。如果已安装，检查版本：

mineru version --json

如果 mineru version --json 失败，对较老的 CLI 尝试 mineru --version。如果检测到的版本不满足要求，告诉用户找到了哪个版本并在升级前先询问。获批后用相同的安装器和环境升级，然后再次检查版本。被拒绝则停止，不要运行本技能的命令。无法确定版本时永远不要假设兼容。

MinerU 要求 Python >=3.10,<3.15。

升级既有安装

升级前，先确定解析出的 mineru 可执行文件属于哪个工具。检查 uv tool list，再查 pipx list --short；否则，识别包含该可执行文件的 Python 环境。不要用无关的 pip，也不要安装第二份副本。

原地升级或重装之前，先停止 MinerU 服务器。在 Windows 上，修改环境前确认状态报告 running=false：

mineru server stop
mineru server status --json

仅在用户批准升级后使用匹配的升级命令：

uv tool upgrade "mineru>=4.0,<5"
pipx upgrade "mineru>=4.0,<5"
"<environment-python>" -m pip install --upgrade "mineru>=4.0,<5"

如果无法确定归属、存在多个安装、或 MinerU 是从源码或可编辑模式安装的，改为询问用户而不是直接升级。升级后，再次检查解析出的可执行文件及其版本。

如果 Windows 上一次失败的重装已经弄坏了 CLI，在任务管理器或 PowerShell 中按 PID 找到并停止残留的 python.exe -m mineru.doclib.app 进程，然后重新运行完整安装命令。该进程运行期间不要删除工具目录。

用 uv 安装（首选）

如果 uv 可用，工具环境可使用任何受支持的 Python 版本。如果没有受支持的解释器可用，保守起见用 uv 安装 Python 3.12 作为兜底：

command -v uv
uv python find 3.12
uv python find 3.13
uv python find 3.14
uv python find 3.11
uv python find 3.10

如果所有 uv python find 都失败，用 uv 下载 Python 3.12：

uv python install 3.12

然后用找到的受支持解释器安装 MinerU，或如果安装了兜底 Python 3.12 就用它：

uv tool install --python 3.12 "mineru>=4.0,<5"

用 pipx 安装

如果 uv 不可用但 pipx 可用，安装前先查看 pipx 的默认 Python：

command -v pipx
pipx environment --value PIPX_DEFAULT_PYTHON
PIPX_DEFAULT_PYTHON="$(pipx environment --value PIPX_DEFAULT_PYTHON)"
"$PIPX_DEFAULT_PYTHON" --version

检查 pipx 报告的 PIPX_DEFAULT_PYTHON 路径。如果该解释器满足 >=3.10,<3.15，用 pipx 安装：

pipx install "mineru>=4.0,<5"

如果 PIPX_DEFAULT_PYTHON 不受支持，但当前系统上找得到受支持的 Python 解释器，显式传入。python3.12 是一个例子；用任何满足 >=3.10,<3.15 的解释器。

command -v python3.12
python3.12 --version
pipx install --python python3.12 "mineru>=4.0,<5"

如果没有受支持的系统解释器，且 pipx 支持 Python 获取，下载独立 Python 前先征求批准：

pipx install --python 3.12 --fetch-python=missing "mineru>=4.0,<5"

用全局 pip 安装

如果 uv 和 pipx 都不可用，但 pip 或 pip3 可用，检查 pip 命令的 Python 版本，并在安装进全局 python 环境前先询问用户：

which -a pip pip3 pip3.10 pip3.11 pip3.12 pip3.13 pip3.14  # find all available pips
pip --version

如果某个 pip 命令报告 Python >=3.10,<3.15，且用户确认，用验证过的那条受支持的 pip 命令安装。必要时把下文的 pip 替换为验证过的 pip 命令：

pip install "mineru>=4.0,<5"

如果没有受支持的安装器

如果 uv、pipx、pip、pip3 全都不可用，或它们都无法在 Python >=3.10,<3.15 下安装，建议用户先安装 uv。

安装之后

验证已安装的 CLI：

mineru --help

隐私规则

MinerU 是隐私优先的。

• 默认情况下，mineru 本地解析文档。只有命令使用 --remote CLI 参数时才会把文档送去远程解析。
• 优先本地解析。如果本地解析未配置或无法满足请求，且文档不涉及私密或敏感内容，先用 --remote 重试前询问用户。
• 即使配置了远程解析，在用户同意之前也不要上传文档。
• 本地失败不能静默回退到远程。
• 远程失败时，如果请求仍可在本地满足，可以回退到本地。

当远程解析可接受时：

mineru parse "document.pdf" --remote

如果请求涉及敏感、机密、法律、医疗、金融、个人或专有内容，保持本地，除非用户明确授予远程许可。

遥测

MinerU 可能收集匿名的、本地聚合的使用与诊断遥测，用于了解命令用法、成功或失败率、分级选择、粗粒度环境类别和性能计时区间。

遥测不收集文档内容、提取的文本或图片、文件名、文件路径、搜索查询、提示词、片段、API 密钥、用户名、主机名、原始堆栈跟踪或精确的硬件标识符。

用户可以查看遥测状态并显式启用或禁用它。要阻止遥测上传，请显式禁用；禁用同时会停止新的聚合并删除未发送的本地遥测数据。如果用户询问遥测，使用：

mineru telemetry status
mineru telemetry enable
mineru telemetry disable
mineru telemetry preview
mineru telemetry flush

质量分级

MinerU 有四个分级：

默认分级行为：

• 用户想要正常阅读质量时省略 --tier。
• 对基于解析服务器的解析，MinerU 先选 standard，再选 basic；advanced 不会被隐式选择，flash 不是默认的最终阅读分级。
• 对 mineru read doc:{short_id}，MinerU 读取最佳缓存结果，而不是开启新解析。
• 如果正常阅读质量不可用，检查 mineru server status --json，然后向用户给出适用选项：
  • 用 --remote 远程解析，这会上传文档，需要明确许可。
  • 如果硬件支持，启动或配置本地解析服务器，这可能需要下载依赖与模型，并修改持久化配置。
  • 明确接受低质量的本地 flash 分级。
  • 明确授权回退到非 MinerU 解析器。
• 停下来等待用户选择。不要只是为了完成任务就不问一声换用非 MinerU 解析器。
• 只在用户明确要求最快/预览/低成本解析或接受更低质量时使用 --tier flash。
• 在当前对话中首次请用户选择解析分级或托管解析服务器分级之前，先介绍分级体系，而不是不加上下文地抛出分级名称。不要假设用户读过本技能、知道 MinerU 有分级、知道有哪些分级或理解它们之间的差异。
  • 对解析分级选择，解释分级控制解析质量、速度和算力需求。简要描述当前情况下可用的分级及其相关取舍。
  • 对托管解析服务器分级选择，解释服务器分级是部署能力等级，而不是单次解析请求选择的分级。简要描述可用的服务器分级、其安装与硬件要求，以及每个服务器分级能启用哪些解析分级。
  • 无论哪种情况，都基于用户的目标和环境推荐一个选项，并说明推荐理由。
  • 用中文交流时，首次提及使用中文名称加标识符，例如 标准解析（standard）。

示例：

mineru parse "paper.pdf"
mineru parse "paper.pdf" --tier basic
mineru parse "paper.pdf" --tier standard
mineru parse "paper.pdf" --tier advanced
mineru parse "paper.pdf" --tier flash

带Extras的模型引擎

MinerU 在本地 basic、standard 和 advanced 解析中使用神经网络模型。为了更好地支持不同硬件，MinerU 提供带两个 extras（torch 和 full）的不同模型引擎。

模型引擎控制资源占用和下载体积：

服务器规则

大多数 mineru 命令使用本地 MinerU 后台服务。如果命令报 server_not_running 失败，启动它：

mineru server start

在 MinerU 无响应、解析卡住或你需要查看可用分级时检查状态：

mineru server status
mineru server status --json

服务器命令：

mineru server start
mineru server stop
mineru server restart
mineru server status

智能体规则：

• 在 mineru 报告服务未运行时启动服务器。
• 无理由不要反复重启服务器。
• 需要机器可读状态时使用 server status --json。
• 如果高质量本地解析不可用，报告错误和建议动作。未经许可不要切到远程。

本地解析服务器

当用户想要 basic、standard 或 advanced 质量而不把文档送去远程解析时，使用本地解析服务器。

检视本地硬件

当没有可用的本地质量分级时，先检视当前机器再给出恢复选项。mineru server status --json 显示当前配置并可用的分级。本地 supported_tiers 列表为空可能只是意味着本地解析服务器被禁用或未配置，所以在判断本地质量分级能否运行之前先检视硬件。

用可用的只读系统命令检视操作系统、架构、总内存、加速器型号和加速器内存。常见选项包括：

• macOS：uname -m、sysctl -n hw.memsize，以及 system_profiler SPHardwareDataType SPDisplaysDataType。
• Linux：uname -m、/proc/meminfo 或 free -b、lscpu，可用时还有 nvidia-smi。
• Windows PowerShell：(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory、Get-CimInstance Win32_Processor，可用时还有 nvidia-smi。
• 其他加速器：如有已安装的厂商工具就用它；不要为了检视硬件而安装软件。

选择 Extra

基础包适合大多数硬件，包括纯 CPU 机器、Apple Silicon 和低端 iGPU/GPU 机器。

只有当你有足够的内存和强劲的 NVIDIA GPU、接受额外安装磁盘空间、并想要更高吞吐时，才安装并使用 full extra。硬件要求：

• 至少 16 GB 总内存。
• 一块 Volta 或更新的 NVIDIA GPU，至少 8 GB 可用显存。
• 多占约 5GB 磁盘空间。

如果你有 npu、gcu、musa、mlu 或 sdaa 加速器，必须自行安装合适的 torch/vllm。否则，默认 mineru 包只使用 CPU。

以下示例展示如何安装 mineru[full] extra。它假设当前安装工具是 uv tool。如果 mineru 是用其他工具或环境安装的，使用该实际工具/环境的等价命令。安装 extra 会替换活跃的 mineru 环境。先停止 MinerU 服务器，确认 running=false，装完依赖后再启动。

mineru server stop
mineru server status --json
uv tool install --force "mineru[full]>=4.0,<5"
mineru server start
mineru server status --json

选择本地分级

托管本地解析有两个启动分级：basic 和 standard。Standard 服务器提供 basic、standard 和 advanced 请求分级。Advanced 使用与 Standard 相同的依赖、模型集和硬件配置；区别仅在于请求选择 --tier advanced 时投入更多推理算力。

请参考以下规则选择合适的 extra 和分级。

推荐并询问

检视完硬件后，你已经知道当前机器合适的 extra 和分级。在请用户选择分级/extra 之前，总结检测到的硬件并指出每个分级的硬件状态。

当机器满足要求时你应当为用户推荐一个分级；否则在隐私规则允许时提供远程 standard，或使用显式的 flash。

只在用户想要最高质量并接受额外耗时的时候提及 advanced。未经批准不要安装依赖、下载模型、修改配置或重启服务。

配置托管解析服务器

首先，为目标启动分级（basic 或 standard）下载模型。把 <tier> 替换为 basic 或 standard。

mineru-kit models download --tier <tier>
mineru-kit models verify --tier <tier>

然后，为启动分级启用托管本地解析服务器。

mineru config set parse_server.local.managed_tier <tier>
mineru config set parse_server.local.mode managed
mineru server status --json

规则：

• 只在用户要求或批准时才修改本地解析服务器配置或重启服务器。
• 在启用托管模式之前，为启动分级（basic 或 standard）下载并验证模型。
• 先设置 parse_server.local.managed_tier，再设置 parse_server.local.mode=managed。
• 轮询 mineru server status --json，只在目标分级健康后才使用托管解析。
• 如果本地高质量解析无法启动，不要自动加 --remote；先询问用户。

从文件首次读取

从本地文件路径首次主动读取时使用 mineru parse。

mineru parse "report.pdf"

默认情况下，可读内容打印到 stdout。只在用户想把结果保存到文件时使用 --output。

需要结构化的状态、分级、内容和续读信息时使用 JSON：

mineru parse "report.pdf" --json

PDF 页选择在 CLI、Doclib、API、Gradio 和 Python 之间通用。参见[页范围语法与历史结果兼容性](docs/next/page-ranges.md)。新请求使用当前语法；使用 ASCII ~ 的已存储正向页范围无需重建 Doclib 缓存即可继续读取。不支持全角 ～ 和负页码写法。

指定页范围（1 起始、含端点；r1 是最后一页，all 选择所有页）：

mineru parse "report.pdf" --pages 1-10
mineru parse "report.pdf" --pages all

限定上下文：

mineru parse "report.pdf" --limit 12000

不同步等待：

mineru parse "report.pdf" --no-wait --json

更长等待：

mineru parse "report.pdf" --wait 180 --json

输出到文件：

mineru parse "report.pdf" --output ./report.md

规则：

• 含空格的路径加引号。
• 对分页文档，默认主动读取范围是第一个页窗口，通常是 1-10；用返回的标记或 next_request 续读，而不是默认读取整个文档。
• 使用默认分级，除非用户有质量/速度/隐私偏好。
• 只在用户要求整个文档或已知文档足够小时用 --pages all。
• 长文档优先用 --limit 和续读。
• 一旦拿到定位符，切换到 mineru read。

续读

MinerU 的输出可能包含继续读取的命令：

<!-- Next: mineru read doc:ab12cd3/tier:standard/page:11 -->

或：

<!-- Next: mineru parse report.pdf --pages 11-20 -->

严格运行建议的命令，除非用户要求不同的页、块、格式或限额。

智能体规则：

• 如果 MinerU 给出了下一条命令，不要自己猜下一页或下一块。
• 续读时不要从第 1 页重新开始解析。
• 对非分页长文档，续读可能使用来自 next_request.after 的 --after 游标；使用那个精确的游标。
• 下一条命令或 JSON 输出给出定位符时优先用 mineru read。
• 用 --limit 把输出控制在会话预算内。
• 为引用和后续读取保留定位符。

按定位符读取

文档已解析过或用户给出定位符时使用 mineru read。

定位符形式：

doc:{short_id}
doc:{short_id}/tier:{tier}
doc:{short_id}/tier:{tier}/page:{page_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}
doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}

示例：

mineru read "doc:ab12cd3/tier:standard/page:4"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7"
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --context 2
mineru read "doc:ab12cd3/tier:standard/page:4" --limit 8000 --json

规则：

• 页号和块号从 1 开始。
• 字符偏移在块文本内从 0 开始。
• --context N 对页定位符指周围页，对块定位符指周围块。
• 如果只提供 doc:{short_id}，MinerU 应选择最高的缓存结果。如果不存在，先解析文档或报告错误。

读取页或块图片

只在用户需要视觉检视、版式证据、裁剪插图、页面截图或块级视觉验证时使用图片输出。

mineru read "doc:ab12cd3/tier:standard/page:4" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image
mineru read "doc:ab12cd3/tier:standard/page:4/block:7" --format image --output ./block-7.png

规则：

• 页定位符支持 PDF 页图片。
• PDF 块图片要求有效且非空的 bbox。
• Office 块图片只对图片块有意义。
• 多页图片导出不是默认阅读工作流。
• 未提供 --output 时，MinerU 打印生成的资源路径。

搜索与查找

文件名和本地路径用 find：

mineru find "annual report"
mineru find "contract" --ext pdf
mineru find "invoice" --json

已解析文档内容用 search：

mineru search "revenue recognition"
mineru search "transformer architecture" --type pdf
mineru search "appendix" --min-tier basic --limit 10 --json

规则：

• find 不搜索文档内容。
• search 只搜索 MinerU 已索引的内容。
• 如果搜索只返回低质量或 flash 片段而用户需要答案，先按默认质量解析或读取目标文档，再依赖其内容。
• 除非回答用户所必需，不要在最终输出中重复敏感的搜索片段。

检视状态

单个资源用 show：

mineru show file "report.pdf"
mineru show file "report.pdf" --json
mineru show parse 123 --json
mineru show doc "<sha256>" --json
mineru show scan 456 --json

集合用 list：

mineru list docs
mineru list files --ext pdf
mineru list parses --status parsing
mineru list scans --status running
mineru list docs --json

规则：

• 解析超时后用 show file 查看进行中的解析和已缓存分级。
• 用 list parses 检查排队、解析中、失败或完成的解析任务。
• 需要结构化输出时用 JSON 模式。

Watch、Scan 与本地库维护

一次性发现或刷新用 scan：

mineru scan "~/Documents/report.pdf"
mineru scan "~/Documents/project"
mineru scan "~/Documents/project" --no-wait --json

持久文件夹用 watch：

mineru watch add "~/Documents"
mineru watch add "/Volumes/Archive" --removable
mineru watch list
mineru watch rescan "~/Documents"
mineru watch remove "~/Documents"

Watch 规则：

• Watch 用于发现和搜索索引。
• Watch 默认 flash。
• Watch 结果不是最终阅读质量。
• 主动阅读仍应使用 mineru parse 或 mineru read。
• CLI 对本地路径参数做标准化处理：用户主目录展开、绝对路径、规范化分隔符。
• watch rescan 和 watch remove 可用 watch id 或 watch 根路径。
• 除非解析规则明确允许远程，watch 不会触发远程解析。

只在用户想要对路径自动应用解析策略时使用解析规则：

mineru config parsing-rules add "*/papers/*" --tier standard --pages all
mineru config parsing-rules add "*/contracts/*" --tier standard --remote
mineru config parsing-rules list
mineru config parsing-rules remove 3

用排除规则阻止发现：

mineru config exclude-rules add "*/node_modules/*"
mineru config exclude-rules list
mineru config exclude-rules remove 5

用 forget 让 MinerU 忘记某个文件或文件夹，但不删除源文件：

mineru forget "~/Documents/old.pdf"
mineru forget "~/Documents/project"
mineru forget "~/Documents/project" --no-dry-run

本地维护用 cleanup：

mineru cleanup deleted-files
mineru cleanup deleted-files --no-dry-run
mineru cleanup orphan-docs
mineru cleanup orphan-docs --no-dry-run
mineru cleanup temp
mineru cleanup temp --older-than 14

规则：

• forget 不删除源文件。
• forget 不能阻止受监视路径被重新发现。
• 如果目标是 watch 根，先移除 watch。如果目标在活跃 watch 之内，提醒稍后的扫描可能重新发现它。
• scan 不创建 watch。
• scan 只刷新文件发现状态；不代表摄入或解析已完成。
• cleanup deleted-files 和 cleanup orphan-docs 默认 dry-run；只在用户想要实际清理时加 --no-dry-run。
• cleanup orphan-docs --no-dry-run 会删除不再与任何已知文件路径关联的文档的缓存解析内容；只用于维护。

重新解析与缓存控制

MinerU 对同一文档和分级缓存解析结果。

为当前请求强制新解析：

mineru parse "report.pdf" --force

使缓存的解析结果失效：

mineru invalidate "report.pdf"
mineru invalidate "report.pdf" --tier standard

规则：

• 正常阅读优先用缓存结果。
• 用户要求重新解析、或已知缓存输出过期或错误时用 --force；它为本请求跳过已完成的缓存，但不会使或删除旧结果失效。
• 用户希望后续解析和读取避开已有完成结果时用 invalidate；失效不会自动开始新解析。
• 不要在缓存控制中删除用户文件。

配置

显示配置：

mineru config show
mineru config show --json

只在用户给出明确配置键时设置或取消设置值：

mineru config get "<key>"
mineru config set "<key>" "<value>"
mineru config unset "<key>"

重要环境变量：

规则：

• 配置远程 URL/API 密钥本身不构成上传授权。
• 仍需要 --remote 或启用远程的解析规则。
• 避免打印配置中的密钥。

Remote API 用量

查询已配置 Remote API 的用量和限额：

mineru usage
mineru usage --json

JSON 输出

智能体需要稳定的机器可读字段时使用 --json。

mineru parse --json 返回：

{
  "parse": { "...": "parse summary" },
  "content": { "...": "readable content and continuation data" }
}

如果解析仍在进行、超时、或使用了 --no-wait，content 可能为 null。

错误格式：

{
  "error": {
    "type": "engine_error",
    "code": "quality_tier_unavailable",
    "message": "...",
    "param": "tier",
    "retryable": false,
    "user_action": "...",
    "docs_url": null
  }
}

智能体规则：

• 基于 error.code 分支，不要基于 message 里的散文。
• 尊重 retryable。
• 用 user_action 决定下一条命令或面向用户的建议。
• 不要从解析内容中剥离定位符字段；续读和引用需要它们。

错误恢复

正常质量恢复闸门

当主动文档读取请求返回 quality_tier_unavailable 或 no_engine 时：

1. 运行 mineru server status --json 检视本地可用分级和解析服务器状态。
2. 如果没有可用的本地质量分级，遵循[检视本地硬件](#检视本地硬件)。不要把未配置或被禁用的本地解析服务器当作硬件不受支持的证据。
3. 给出当前可用的分级。如果已做过硬件评估，同时给出检测到的硬件和每个适用本地分级的硬件状态。然后遵循「质量分级」章节的分级选择指引。
4. 停下来等待用户选择恢复路径。
5. 只运行被选中的路径。如果该路径失败，报告失败并带着剩余适用选项回到这个决策闸门。

除非用户已要求或授权该回退，否则在此闸门之前不要使用其他文档解析器。可恢复的 MinerU 安装或分级错误本身并不意味着 MinerU 不可用。

常见错误码用这个表：

重试规则：

• 对瞬态服务器启动或明确可重试的错误重试一次。
• 不要无限重试解析失败。
• 无理由不要更改分级、页范围或远程/本地隐私边界。
• 恢复过程中未经用户许可不要加 --remote。

用 MinerU 输出回答用户

读完文档回答问题时：

• 使用解析出的内容，而不是对文档的假设。
• 用户需要可追溯性时引用定位符。
• 优先简洁引用和页/块指引，而不是大段复制。
• 如果内容被截断，说明答案基于目前读到的页/块。
• 在做出需要未读章节的断言之前先继续阅读。
• 对表格、公式、插图或版式敏感的问题，读取相关页/块，必要时使用图片输出。

引用样式示例：

The warranty period is 24 months (doc:ab12cd3/tier:standard/page:7/block:3).

The method is described across pages 4-5; I checked doc:ab12cd3/tier:standard/page:4 and doc:ab12cd3/tier:standard/page:5.

运行规则

• 不要把 flash 作为默认的最终阅读质量。
• 有效的定位符和缓存结果足够时不要重新解析。
• 不要忽略续读命令。
• 页/块续读能回答问题时不要加载整个长文档。
• 不要删除源文件。
• 不要暴露密钥、API 密钥或不必要的本地路径。
• JSON error.code 或 next_request 可用时不要基于人类散文分支。