mineru

MinerU

MinerU 是供 Agent 使用的命令行文档阅读器。它可将本地文档解析为易读内容，让 Agent 按页或按块继续读取，并返回稳定的定位符，以便后续读取和引用。

MinerU 不是 RAG 框架、向量数据库或聊天式文档应用。

此技能主要使用 mineru 命令。

何时使用 MinerU

阅读或解析受支持的 PDF、图像和 Office 文档时，优先使用 MinerU。不要仅仅因为其他解析器或 OCR 库更熟悉，就绕过 MinerU。

在用户要求 Agent 执行以下操作时使用此技能：

• 阅读、检查、总结、引用本地文档，或回答有关本地文档的问题。
• 将文档内容转换为 Markdown 以供分析。
• 对扫描版 PDF 或图像执行 OCR。
• 从 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	.pdf，包括扫描版 PDF 和学术论文
图像	.png、.jpg、.jpeg、.webp、.gif、.bmp、.tiff、.jp2
Word	.doc、.docx
PowerPoint	.ppt、.pptx
Excel	.xls、.xlsx
富文本	.rtf
OpenDocument	.odt、.ods、.odp
EPUB	.epub，按 OPF spine 顺序作为完整文档解析，并保留源文档中的内部链接
OFD	.ofd
HTML	.html、.htm、.shtml
MHTML 网页存档	.mhtml、.mht
CSV / TSV	.csv、.tsv

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

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

不要

• 在使用 mineru 读取文档之前就对其进行总结。
• 在 mineru 可以读取文档时，重新实现 PDF/OCR 提取。

Agent 使用规范

• 使用 mineru 作为命令入口。
• 使用 --json 做出控制流决策。
• 遵循继续读取命令和 next_request。
• 保留定位符，以便引用和后续读取。
• 使用 --remote、更改持久配置、添加监视项、停止或重启服务、使缓存失效，或执行 forget --no-dry-run、cleanup --no-dry-run 等破坏性维护操作前，先征求用户同意。
• 当可恢复的引擎或配置错误需要用户选择质量、隐私、下载或配置选项时，列出适用的 MinerU 恢复路径，并等待用户选择后再使用其他文档解析器。

核心决策树

运行命令前，先使用此决策树：

1. 用户提供了文件路径并需要内容：直接读取纯文本格式；否则运行 mineru parse <file>。
2. 用户提供了 doc:... 定位符：运行 mineru read <locator>。
3. 用户要求从之前的输出继续：严格按照 `` 命令执行。
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 失败，请尝试使用 mineru --version 检查较旧的 CLI。如果检测到的版本不符合此要求，请告知用户检测到的版本，并在升级前征求用户同意。如果用户同意，请使用相同的安装程序和环境进行升级，然后再次检查版本。如果用户拒绝，请停止，不要运行此技能的命令。如果无法确定版本，绝不要假定其兼容。

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 作为后备方案，则使用 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 均不可用，或它们都无法使用满足 >=3.10,<3.15 的 Python 安装，请建议用户先安装 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 有四个等级：

等级	中文名称	质量和速度	适用场景
flash	极速解析	质量最低；速度最快	发现、预览和索引；绝不可作为默认的最终阅读质量
basic	基础解析	基础质量；速度适中	私密的本地阅读或对资源要求较低的本地解析
standard	标准解析	标准的高质量；在合适的硬件上，速度与 basic 相近	常规阅读和复杂文档的默认选择
advanced	高级解析	处理普通文档时为标准质量，处理难读文档时质量更高；速度最慢	难读文档，以及用户接受较长等待时间时对质量要求最高的任务

默认等级行为：

• 用户需要常规阅读质量时，省略 --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

带附加组件的模型引擎

MinerU 使用神经网络模型进行本地 basic、standard 和 advanced 解析。 为更好地支持不同硬件，MinerU 提供了不同的模型引擎，并有两个附加组件：torch 和 full。

附加组件	已安装的模型引擎	安装方式
(base)	ONNX + llama.cpp	已包含在 mineru 基础模块中
torch	ONNX + PyTorch + llama.cpp	使用 mineru[torch] 安装（Apple Silicon 已在基础包中安装此附加组件。）
full	ONNX + PyTorch + llama.cpp + vLLM/lmdeploy/mlx	使用 mineru[full] 安装

模型引擎会影响资源使用量和下载大小：

层级	模型引擎	模型下载量	最低 RAM 要求	加速器
basic	ONNX	~0.8 GB	2GB	无（CPU 可用）
basic	PyTorch	~0.8 GB	8 GB	建议使用 GPU/MPS
standard / advanced	ONNX + llama.cpp	~2 GB	8 GB	CPU 可用，建议使用 Vulkan
standard / advanced	PyTorch + llama.cpp	~2 GB	16 GB	需要 GPU/MPS，显存 8 GB 以上
standard / advanced	PyTorch + vLLM/lmdeploy/mlx	~3 GB	16 GB	需要 GPU/MPS，显存 8 GB 以上

服务规则

大多数 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

Agent 规则：

• 当 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。
• 其他加速器：如果已有可用的厂商工具，请使用它；不要仅为检查硬件而安装软件。

选择额外组件

基础软件包适用于大多数硬件，包括仅使用 CPU 的机器、Apple Silicon，以及低端 iGPU/GPU 机器。

只有在内存充足、配备高性能 NVIDIA GPU、能够接受额外的安装磁盘空间，并且希望获得更高吞吐量时，才安装并使用 full extra。硬件要求：

• 总内存至少 16 GB。
• 配备 Volta 或更新架构的 NVIDIA GPU，且至少有 8 GB 可用 VRAM。
• 会额外占用约 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
配备 Apple Silicon 的 MacOS	standard	PyTorch + llama.cpp	torch（已安装）
配备 Intel CPU 的 MacOS	basic	ONNX	（基础软件包）
配备 NVIDIA GPU 且 VRAM 达到 8GB 或以上的 Linux/Windows	standard	PyTorch + vLLM/lmdeploy	full
配备 NVIDIA GPU 且 VRAM 达到 4GB 或以上的 Linux/Windows	basic	PyTorch	torch
配备其他加速器的 Linux/Windows	（视情况而定）	PyTorch / vLLM	自行安装定制的 torch/vllm
配备新型 iGPU 的 Linux/Windows	standard	ONNX + llama.cpp	（基础软件包）
未配备新型加速器的 Linux/Windows	basic	ONNX	（基础软件包）

推荐并询问

检查硬件后，你已经了解当前机器适用的 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 之间通用。请参阅页码范围语法和历史结果兼容性。新请求使用当前语法；使用 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 的输出可能会包含用于继续阅读的命令：

或者：

除非用户要求使用不同的页面、区块、格式或限制，否则请严格运行建议的命令。

Agent 规则：

• 如果 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 模式。

监视、扫描和本地库维护

使用 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 默认使用 flash。
• Watch 结果不代表最终阅读质量。
• 实际阅读仍应使用 mineru parse 或 mineru read。
• CLI 会通过展开用户主目录、使用绝对路径和规范化分隔符来规范化本地路径参数。
• 对于 watch rescan 和 watch remove，可以使用监视 ID 或监视根路径。
• 除非解析规则明确允许远程解析，否则 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 不会阻止监视路径再次发现该路径。
• 如果目标是监视根路径，请先移除监视。如果目标位于活动监视路径内，请提醒用户后续扫描可能会再次发现它。
• scan 不会创建监视。
• scan 仅刷新文件发现状态；这不代表摄取或解析已完成。
• cleanup deleted-files 和 cleanup orphan-docs 默认采用试运行模式；只有用户希望实际清理时，才添加 --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>"

重要环境变量：

变量	含义
MINERU_HOME	MinerU 主目录，默认值为 ~/.mineru
MINERU_API_KEY	明确允许远程解析时使用的 API 密钥

规则：

• 配置远程 URL/API 密钥本身并不代表授权上传。
• 仍需使用 --remote 或启用远程解析的解析规则。
• 避免输出配置中的机密信息。

远程 API 使用情况

查询已配置的 Remote API 的使用情况和限制：

mineru usage
mineru usage --json

JSON 输出

当 Agent 需要稳定的机器可读字段时，使用 --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
  }
}

Agent 规则：

• 根据 error.code 分支处理，而不要依据 message 中的文字说明。
• 遵循 retryable。
• 使用 user_action 决定下一条命令或面向用户的建议。
• 不要从解析内容中移除定位字段；继续读取和引用都需要这些字段。

错误恢复

普通质量恢复流程

对于正在处理的文档读取请求，如果返回 quality_tier_unavailable 或 no_engine：

1. 运行 mineru server status --json，检查本地可用的质量层级和解析服务状态。
2. 如果没有可用的本地质量层级，请遵循评估本地硬件。不要将未配置或已禁用的本地解析服务视为硬件不受支持的证明。
3. 呈现当前可用的层级。如果已评估硬件，还需呈现检测到的硬件以及每个适用本地层级的硬件状态。然后遵循“质量层级”部分中的层级选择指南。
4. 停止并等待用户选择恢复路径。
5. 仅运行所选路径。如果该路径失败，报告失败情况，并返回此决策流程，提供其余适用选项。

除非用户已请求或授权使用其他方案，否则在此流程结束前不要使用其他文档解析器。MinerU 的可恢复设置错误或层级错误本身并不意味着 MinerU 不可用。

常见错误代码请参考下表：

代码	含义	Agent 操作
server_not_running	MinerU 后台服务不可用	运行 mineru server start，然后重试一次
quality_tier_unavailable	普通读取质量不可用	遵循普通质量恢复流程；不要自动回退
no_engine	请求的层级在本地不可用	遵循普通质量恢复流程；不要自动回退
engine_unavailable	引擎进程不可用	如果可重试则重试；否则检查 mineru server status
parse_server_unavailable	无法连接解析服务	检查 mineru server status；不要切换隐私边界
tier_mismatch	不支持请求的层级	请用户选择受支持的层级
parse_failed	MinerU 无法解析文件	报告失败；仅在隐私规则允许时建议使用其他层级
parse_timeout	解析超时	使用更长的 --wait 重试、检查状态，或在用户接受的情况下使用较低层级
parse_oom	内存或 VRAM 耗尽	建议降低质量、缩小 --pages 范围，或仅在获得许可后使用远程服务
remote_not_allowed	可能需要远程服务，但尚未获准	询问用户是否接受上传；不要自行添加 --remote
invalid_api_key	API 密钥无效	请用户设置有效的密钥
quota_exceeded	远程配额已用尽	建议等待或使用本地服务
rate_limit_exceeded	远程速率限制	适当时稍后重试
file_not_found	路径或文件 ID 缺失	请用户提供正确路径，或运行 mineru find
file_permission_denied	无法读取本地文件	请用户修复权限
file_type_unsupported	不支持该格式	报告不支持的类型
file_encrypted	文件受密码保护	请用户提供未锁定的副本
file_corrupted	无法读取文件	请用户提供有效副本
page_range_invalid	PDF 的 --pages 值无效，或对非 PDF 输入使用了 --pages	修正 PDF 页码范围，或在解析整个文档时省略该参数
parse_not_required	输入是可直接读取的文本文件	直接读取源文件；不要重试 mineru parse
not_cached / cache_miss	请求的缓存内容不存在	运行 mineru parse

重试规则：

• 对临时服务启动错误或明确可重试的错误重试一次。
• 不要无限重试解析失败。
• 不要无故更改层级、页码范围或远程/本地隐私边界。
• 未经用户许可，不要在恢复过程中添加 --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 可用时，不要根据人类撰写的文本进行分支判断。