mineru CLI 端到端测试用例¶
状态: Draft
读者: CLI 测试执行 Agent、QA、核心开发者
范围: 只测试本地安装的 mineru 命令
非目标: 测试 mineru-kit、直接访问数据库、调用内部 Python API、验证具体解析模型质量
1. 执行规则¶
执行 Agent 只允许调用本地安装的 mineru 命令。
严禁调用:
mineru-kitpythonsqlitecurl- 项目内部模块
- 任何直接修改 MinerU 数据库或缓存目录的命令
每条用例必须记录:
- case id
- command
- exit code
- stdout
- stderr
- pass / fail / blocked
- 失败原因
结构化断言规则:
- 带
--json的命令必须使用 JSON parser 校验 stdout,不允许用字符串截取代替解析。 - JSON 错误优先按
error.code判定;error.message仅用于诊断,不作为稳定协议。用例给出明确错误码时必须精确匹配。 - parse JSON 的
parse对象不包含privacy和via;需要验证路由时,从created_parse_ids或reused_parse_ids提取 parse id,再执行mineru show parse <parse_id> --json。 - 除明确允许的 remote 到同 tier local fallback 外,不允许测试执行器自行改变 tier、page range 或 local/remote 边界重试。
2. 前置条件¶
测试环境需提前准备:
- 本地命令
mineru已安装并在PATH中。 - 环境变量
MINERU_E2E_FIXTURE_DIR指向测试数据目录。 - 测试数据目录至少包含:
$MINERU_E2E_FIXTURE_DIR/sample.pdf$MINERU_E2E_FIXTURE_DIR/sample-copy.pdf,内容与sample.pdf相同,路径不同。$MINERU_E2E_FIXTURE_DIR/watch-dir/watch-doc.pdf$MINERU_E2E_FIXTURE_DIR/empty-dir/,空目录。$MINERU_E2E_FIXTURE_DIR/unsupported.bin,不支持的普通二进制或文本文件。$MINERU_E2E_FIXTURE_DIR/sample doc.pdf,文件名包含空格,内容可与sample.pdf相同。$MINERU_E2E_FIXTURE_DIR/中文样例.pdf,文件名包含中文,内容可与sample.pdf相同。$MINERU_E2E_FIXTURE_DIR/corrupted.pdf,损坏 PDF。$MINERU_E2E_FIXTURE_DIR/empty.pdf,空文件或无法解析出页面的 PDF。$MINERU_E2E_FIXTURE_DIR/sample.rtf、sample.doc/sample.docx、sample.ppt/sample.pptx、sample.xls/sample.xlsx,Office/RTF 样例文件;当前全量 E2E 必须覆盖。$MINERU_E2E_FIXTURE_DIR/sample.ofd、sample.epub、sample.html,OFD/EPUB/HTML 样例文件;当前全量 E2E 必须覆盖。$MINERU_E2E_FIXTURE_DIR/sample.odt、sample.ods、sample.odp,OpenDocument 样例文件;当前全量 E2E 必须覆盖。$MINERU_E2E_FIXTURE_DIR/sample.md、sample.txt、sample.csv、sample.tsv,文本类样例文件;当前全量 E2E 必须覆盖。$MINERU_E2E_FIXTURE_DIR/sample.jpeg,图片样例文件;若当前安装不支持图片输入,可按预期失败分支判定。$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf,指向sample.pdf的符号链接;若平台不支持 symlink,可标记相关用例 BLOCKED。$MINERU_E2E_FIXTURE_DIR/no-read.pdf,权限不可读文件;若平台无法稳定制造权限场景,可标记相关用例 BLOCKED。$MINERU_E2E_FIXTURE_DIR/output-dir/,用于输出文件测试的目录。- 测试环境允许启动本地 doclib server。
- 测试环境必须安装
fullextra,并满足 README 中fullstack 的硬件要求,以同时覆盖light和fullmodel stack 下的本地basic、standard、advancedquality parse-server;默认 tier 相关用例应验证本地 quality tier 可用,不再按缺少本地 quality tier 的预期失败分支判定。 - 全量主流程固定使用
lightstack;fullstack 作为硬性 profile,必须额外覆盖本地 PDF Basic、Standard、Advanced。不得使用auto执行这些用例,以免硬件探测导致测试环境不确定。 - MinerU 的公开 tier 只有
flash、basic、standard、advanced;默认 quality tier 选择顺序为standard、basic,advanced只在显式请求时使用;已缓存结果的读取顺序为advanced、standard、basic、flash。 - 非 PDF/图片格式(Office/RTF/ODF/OFD/EPUB/HTML/MHTML/CSV/TSV)固定使用
flashtier,传入其它 tier 返回tier_unsupported_for_file_type;这些格式不接受 page_range,传入 page_range 返回page_range_invalid。 - 显式指定 quality tier 的 remote 请求应按 remote 成功、remote 失败后同 tier local fallback、remote 与 local 均不可用三个分支判定;不得 fallback 到
flash。未指定 tier 时需要先从 remote 能力中按standard、basic选择默认值,无法选择时返回quality_tier_unavailable;仅暴露advanced不构成可用的默认 quality tier。 - PARSE-013A1 是 remote Standard 硬性测试,remote parse-server 不可用或不支持 Standard 均记录为失败。
2.1 测试 HOME 与隔离配置¶
测试 HOME 使用:
进入测试目录后,设置 MINERU_HOME 隔离运行数据,并将全量主流程固定为 light stack:
cd ~/mineru-e2e-test
export MINERU_HOME=`pwd`
export MINERU_MODEL_SMALL_BACKEND=onnx
export MINERU_MODEL_VLM_ENGINE=llama-cpp
MINERU_HOME 使默认配置文件($MINERU_HOME/config.yaml)、DB、日志、endpoint discovery 文件、UDS socket(启用 UDS 时)和数据目录都落在测试目录中。MINERU_MODEL_SMALL_BACKEND=onnx 与 MINERU_MODEL_VLM_ENGINE=llama-cpp 必须由 doclib server 及其 managed parse-server 继承。
2.2 安装方法¶
在测试 HOME 中创建独立虚拟环境并安装当前仓库:
cd ~/mineru-e2e-test
rm -rf .venv
uv venv .venv
source .venv/bin/activate
cd ~/MinerU-Repo
uv pip install ".[full]"
cd ~/mineru-e2e-test
mineru --help
基础安装已包含 light stack 所需的 ONNX 和 llama.cpp runtime;full extra 额外安装 PyTorch、vLLM/lmdeploy/mlx 等完整 runtime。由于本 E2E 将 full profile 作为硬性测试,安装阶段统一使用 .[full]。
安装完成后,mineru 应由 pyproject.toml 的脚本入口直接提供,不需要配置 shell alias。
执行 Agent 只调用 mineru ... 命令,不测试 mineru-kit,也不直接调用 Python 模块、内部 API 或数据库。
2.2.1 本地模型准备¶
本地 managed 只配置 basic 或 standard 启动能力,两者均要求模型文件已下载到 config.model.base_dir。Standard managed server 同时提供 Standard 和 Advanced 请求能力。模型准备属于测试环境 setup,不属于正式 mineru CLI case。
在执行需要本地 quality tier 的 case 前,测试环境应先准备并验证目标模型:
cd ~/mineru-e2e-test
source .venv/bin/activate
mineru-kit models download --tier standard --small-backend onnx --vlm-engine llama-cpp
mineru-kit models verify --tier standard --small-backend onnx --vlm-engine llama-cpp
mineru-kit models download --tier standard --small-backend torch --vlm-engine llama-cpp
mineru-kit models verify --tier standard --small-backend torch --vlm-engine llama-cpp
说明:
- 每个 stack 的 Standard 模型集覆盖该 stack 的 Advanced 请求,并包含 Basic 所需模型。
- 模型下载和验证必须显式传
--small-backend与--vlm-engine;不得依赖自动模式 的硬件探测结果。 - 如果需要验证模型未准备好的 config 拦截分支,应使用新的隔离
MINERU_HOME,或在测试开始前清空该隔离 HOME 下的models/目录。 - 模型未准备分支固定继承
MINERU_MODEL_SMALL_BACKEND=onnx与MINERU_MODEL_VLM_ENGINE=llama-cpp,确保断言针对 light 模型集。 - 正式 case 执行阶段仍只调用
mineru ...命令。
2.2.2 后端测试 profile 切换¶
本文 light/full 仅保留为测试 profile 标签,分别表示 ONNX + llama 与 Torch + llama,不是配置值。 Linux/Windows 的 vLLM/lmdeploy 验收另行显式选择对应引擎并准备原始权重。
全量主流程默认在 light profile 下执行。切换 profile 前必须停止 doclib server,使新的 server 和 managed parse-server 继承目标环境变量。
切换到 full profile:
mineru config set parse_server.local.mode disabled
mineru server stop
export MINERU_MODEL_SMALL_BACKEND=torch
export MINERU_MODEL_VLM_ENGINE=llama-cpp
mineru server start
恢复 light profile:
mineru config set parse_server.local.mode disabled
mineru server stop
export MINERU_MODEL_SMALL_BACKEND=onnx
export MINERU_MODEL_VLM_ENGINE=llama-cpp
mineru server start
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
切换后必须轮询 mineru server status --json,直到 doclib 正常运行且目标 local parse-server healthy,再执行对应 profile 的 parse case。不得在 server 运行期间仅修改环境变量并假定 stack 已切换。
2.3 Fixture 生成方法¶
fixture 准备阶段允许使用 shell 文件操作创建隔离测试数据。mineru 命令限制只适用于正式 case 执行阶段。
PDF 样例使用仓库内覆盖元素更完整的 demo 文件:
图片样例使用仓库内 demo 文件:
推荐生成步骤:
cd ~/mineru-e2e-test
export MINERU_HOME=`pwd`
export MINERU_E2E_FIXTURE_DIR="$MINERU_HOME/fixtures"
rm -rf "$MINERU_E2E_FIXTURE_DIR"
mkdir -p "$MINERU_E2E_FIXTURE_DIR/watch-dir" "$MINERU_E2E_FIXTURE_DIR/empty-dir" "$MINERU_E2E_FIXTURE_DIR/output-dir" "$MINERU_HOME/removable-watch"
# Office 真实样例已归 DocVortex;手工测试前将该仓库克隆到 $HOME/docvortex。
PDF_SOURCE="$HOME/MinerU-Repo/demo/pdfs/demo1.pdf"
cp "$PDF_SOURCE" "$MINERU_E2E_FIXTURE_DIR/sample.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_HOME/sample.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/sample-copy.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/watch-dir/watch-doc.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/sample doc.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/中文样例.pdf"
cp "$HOME/docvortex/demo/office_docs/docx_01.docx" "$MINERU_E2E_FIXTURE_DIR/sample.docx"
cp "$HOME/docvortex/demo/office_docs/pptx_01.pptx" "$MINERU_E2E_FIXTURE_DIR/sample.pptx"
cp "$HOME/docvortex/demo/office_docs/xlsx_01.xlsx" "$MINERU_E2E_FIXTURE_DIR/sample.xlsx"
cp "$HOME/docvortex/demo/office_docs/docx_01.doc" "$MINERU_E2E_FIXTURE_DIR/sample.doc"
cp "$HOME/docvortex/demo/office_docs/pptx_01.ppt" "$MINERU_E2E_FIXTURE_DIR/sample.ppt"
cp "$HOME/docvortex/demo/office_docs/xlsx_01.xls" "$MINERU_E2E_FIXTURE_DIR/sample.xls"
cp "$HOME/docvortex/demo/office_docs/rtf_01.rtf" "$MINERU_E2E_FIXTURE_DIR/sample.rtf"
# OFD/ODT/ODS/ODP 来自 OFDRW(Apache 2.0)与 Apache ODF Toolkit(Apache 2.0)公开测试资源
curl -sL -o "$MINERU_E2E_FIXTURE_DIR/sample.ofd" "https://raw.githubusercontent.com/ofdrw/ofdrw/7459e35082170061efa6b399a6518dbc219f08ac/ofdrw-converter/src/test/resources/helloworld.ofd"
curl -sL -o "$MINERU_E2E_FIXTURE_DIR/sample.odt" "https://raw.githubusercontent.com/apache/odftoolkit/trunk/odfdom/src/main/resources/OdfTextDocument.odt"
curl -sL -o "$MINERU_E2E_FIXTURE_DIR/sample.ods" "https://raw.githubusercontent.com/apache/odftoolkit/trunk/odfdom/src/main/resources/OdfSpreadsheetDocument.ods"
curl -sL -o "$MINERU_E2E_FIXTURE_DIR/sample.odp" "https://raw.githubusercontent.com/apache/odftoolkit/trunk/odfdom/src/main/resources/OdfPresentationDocument.odp"
# EPUB 使用 Project Gutenberg 公版电子书(Alice's Adventures in Wonderland,无版权限制)
curl -sL -o "$MINERU_E2E_FIXTURE_DIR/sample.epub" "https://www.gutenberg.org/ebooks/11.epub.noimages"
# 手写最小 HTML,含图片引用以验证 source_context 资源解析
mkdir -p "$MINERU_E2E_FIXTURE_DIR/html-bundle"
cp "$MINERU_E2E_FIXTURE_DIR/sample.jpeg" "$MINERU_E2E_FIXTURE_DIR/html-bundle/img.jpeg"
cat > "$MINERU_E2E_FIXTURE_DIR/sample.html" <<'HTML'
<!DOCTYPE html>
<html lang="en"><head><meta charset="utf-8"><title>MinerU E2E HTML</title></head>
<body>
<h1>MinerU E2E HTML Fixture</h1>
<p>This file verifies HTML parsing and resource resolution.</p>
<p><img src="html-bundle/img.jpeg" alt="fixture image"></p>
<ul><li>bullet one</li><li>bullet two</li></ul>
</body></html>
HTML
printf '# MinerU E2E Markdown\n\nThis file verifies markdown input.\n' > "$MINERU_E2E_FIXTURE_DIR/sample.md"
printf 'MinerU E2E text fixture\nsecond line\n' > "$MINERU_E2E_FIXTURE_DIR/sample.txt"
printf 'name,value\nalpha,1\nbeta,2\n' > "$MINERU_E2E_FIXTURE_DIR/sample.csv"
printf 'name\tvalue\nalpha\t1\nbeta\t2\n' > "$MINERU_E2E_FIXTURE_DIR/sample.tsv"
printf 'not a supported document' > "$MINERU_E2E_FIXTURE_DIR/unsupported.bin"
printf 'not a real pdf' > "$MINERU_E2E_FIXTURE_DIR/corrupted.pdf"
: > "$MINERU_E2E_FIXTURE_DIR/empty.pdf"
cp "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/no-read.pdf"
chmod 000 "$MINERU_E2E_FIXTURE_DIR/no-read.pdf"
ln -sf "$MINERU_E2E_FIXTURE_DIR/sample.pdf" "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf"
IMAGE_SOURCE="$HOME/MinerU-Repo/demo/images/photo_20250417_111916.jpeg"
cp "$IMAGE_SOURCE" "$MINERU_E2E_FIXTURE_DIR/sample.jpeg"
执行结束后应恢复不可读文件权限,避免清理失败:
3. 顶层命令与帮助¶
CLI-001 顶层 help¶
命令:
预期:
- exit code = 0
- 输出包含
parse、read、scan、watch、search、find、usage、list、show、server、config、invalidate、forget、cleanup - 输出包含
telemetry - 输出不包含
mineru-kit
CLI-002 子命令 help¶
命令:
mineru parse --help
mineru read --help
mineru scan --help
mineru watch --help
mineru search --help
mineru find --help
mineru usage --help
mineru list --help
mineru show --help
mineru telemetry --help
mineru server --help
mineru config --help
mineru invalidate --help
mineru forget --help
mineru cleanup --help
预期:
- 每条 exit code = 0
- 每条输出包含 usage 或 options 类帮助信息
CLI-002A output/help 契约¶
命令:
预期:
- 两条 exit code = 0
--outputhelp 文案说明可写入文件--outputhelp 文案或相邻说明应体现父目录可自动创建--jsonhelp 文案或相邻说明应体现 JSON 输出- parse/read help 不得暗示
--output与--json互斥
CLI-003 不存在旧命令¶
命令:
预期:
- exit code != 0
4. Server 生命周期¶
SERVER-001 查询初始状态¶
命令:
预期:
- exit code = 0
- 输出为 server 运行信息或
Server is not running.
SERVER-001A 查询初始 JSON 状态¶
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- 如果 server 未运行,JSON 为稳定状态结果,至少包含
running: false - server 未运行不应输出 JSON error
- stdout 不包含
Server is not running.人类文本
SERVER-002 启动 server¶
命令:
预期:
- exit code = 0
- 如果已运行,输出包含
already running - 如果未运行,输出包含
started
SERVER-003 查询运行状态¶
命令:
预期:
- exit code = 0
- 输出包含 server 状态信息
- 不提示连接失败
SERVER-004 JSON 状态¶
命令:
预期:
- server 运行时 exit code = 0
- 输出为 JSON 或等价结构化 server 状态
- 至少包含
running、socket_path、tcp、data_dir、队列或文档库统计中的若干字段 tcp字段至少包含enabled、host、port
SERVER-005 重复启动 server¶
前置: SERVER-002 已成功,server 正在运行。
命令:
预期:
- exit code = 0
- 输出包含
already running - 不启动第二个不可控 server 进程
- 后续
mineru server status仍可正常返回
SERVER-006 restart server¶
命令:
预期:
- 两条 exit code = 0
- restart 输出包含 stopped/started、started 或等价生命周期信息
- status 输出为 JSON
- JSON 表示 server 正在运行
socket_path、data_dir、sqlite_path、log_path仍落在测试 HOME 配置下
SERVER-007 stop 后依赖 server 的命令报错可读¶
命令:
预期:
- stop exit code = 0
- list files exit code != 0
- list files 输出包含
Cannot connect、server、Run 'mineru server start' first或等价可操作错误 - list files 不包含 Python traceback
- 最后一条 start exit code = 0,用于恢复后续测试环境
SERVER-009 环境变量路径生效¶
命令:
预期:
- exit code = 0
- 输出为 JSON
data_dir默认位于$MINERU_HOME/doclib;若显式覆盖doclib.data_dir,则返回该覆盖值socket_path字段等价于MINERU_DOCLIB_UDS_PATH,不得为空;即使当前 transport 是 TCP-only,也可以表示配置路径- TCP 相关字段应位于
tcp.enabled、tcp.host、tcp.port - 日志相关字段或启动失败日志路径应落在
MINERU_DOCLIB_LOG_DIR,或显式配置的MINERU_DOCLIB_LOG_APP_PATH
SERVER-013 endpoint discovery 文件写入¶
前置: server 已启动。
命令:
预期:
- endpoint 文件存在,且 stdout 可解析为 JSON
- endpoint JSON 至少包含
version=2、pid、非空server_id、transports - endpoint JSON 的
server_id等于 status JSON 的server_id transports非空,每个 transport 均包含type- 默认 UDS 可用环境下,
transports至少包含{"type": "uds", "path": ...},且 path 位于测试 HOME - 如果当前环境使用 TCP transport,则对应项包含
{"type": "tcp", "base_url": "http://127.0.0.1:<port>"} mineru server status --json能通过 discovery 正常连接 server
SERVER-014 TCP-only fallback¶
前置:
- 使用一个新的独立
MINERU_HOME,避免与主测试 server 冲突。 - 执行前保存主测试 HOME,例如
MAIN_MINERU_HOME="$MINERU_HOME";执行结束后恢复MINERU_HOME="$MAIN_MINERU_HOME"。 - 设置:
MAIN_MINERU_HOME="$MINERU_HOME"
export MINERU_HOME="$HOME/mineru-e2e-test-tcp"
export MINERU_DOCLIB_UDS_ENABLED=false
export MINERU_DOCLIB_TCP_ENABLED=true
export MINERU_DOCLIB_TCP_PORT=0
命令:
mineru server start
mineru server status --json
cat "$MINERU_HOME/doclib.endpoint.json"
mineru server stop
export MINERU_HOME="$MAIN_MINERU_HOME"
unset MINERU_DOCLIB_UDS_ENABLED MINERU_DOCLIB_TCP_ENABLED MINERU_DOCLIB_TCP_PORT
预期:
- start exit code = 0
- status JSON 中
running=true - status JSON 中
tcp.enabled=true - status JSON 中
tcp.host=127.0.0.1 - status JSON 中
tcp.port是大于 0 的实际端口,不应为 0 - endpoint JSON 的
transports只需包含 TCP transport,base_url端口必须等于 status JSON 的tcp.port - stop exit code = 0
- stop 后
$MINERU_HOME/doclib.endpoint.json被清理;不检查doclib.lock文件是否保留 - 后续
mineru server status --json返回running=false
SERVER-015 endpoint stale 清理¶
前置:
- 使用独立
MINERU_HOME。 - 执行前保存主测试 HOME,例如
MAIN_MINERU_HOME="$MINERU_HOME";执行结束后恢复MINERU_HOME="$MAIN_MINERU_HOME"。 - 手工写入一个 stale
$MINERU_HOME/doclib.endpoint.json,内容指向不存在的本地 TCP 端口。
命令:
MAIN_MINERU_HOME="$MINERU_HOME"
export MINERU_HOME="$HOME/mineru-e2e-test-stale-endpoint"
mkdir -p "$MINERU_HOME"
cat > "$MINERU_HOME/doclib.endpoint.json" <<'JSON'
{"version":2,"pid":999999,"server_id":"stale-server","transports":[{"type":"tcp","base_url":"http://127.0.0.1:9"}]}
JSON
mineru server status --json
mineru server stop
export MINERU_HOME="$MAIN_MINERU_HOME"
预期:
- status exit code = 0
- status JSON 返回
running=false,不因 stale endpoint 输出 Python traceback - stop exit code = 0
- stop 输出
Server is not running或等价信息 - stop 后 stale endpoint 文件仍然存在
- 后续 start 创建的 server 在取得
doclib.lock后清理 stale endpoint 和 UDS socket
SERVER-016 endpoint server identity 校验¶
前置:
- 主测试 HOME 的 server 正在运行。
- 使用独立
MINERU_HOME,并将主测试 HOME 的 endpoint 复制到该目录后修改server_id。
预期:
- 默认 client 在发送业务请求前发现
server_id不匹配。 - 不向主测试 HOME 的 server 发送业务请求或 shutdown 请求。
- 没有其他匹配 transport 时返回
server_instance_mismatch,或由server status表示当前 HOME 的 server 未运行。
SERVER-017 version 1 endpoint 升级迁移¶
前置:
- 使用独立
MINERU_HOME启动 server。 - 将 endpoint 改写为 version 1,保留原 PID 和 transports,删除
server_id。
预期:
mineru server status --json通过 endpoint/status PID 对应关系识别旧格式 server。mineru server restart先等待旧实例完全退出,再启动 replacement。- replacement 写入 version 2 endpoint 和新的
server_id。 - version 1 endpoint PID 与 status PID 不同时返回
server_instance_mismatch,且不发送 shutdown。
SERVER-018 doclib home ownership lock¶
前置:
- 使用独立
MINERU_HOME。
步骤:
- 通过
mineru server start启动第一个 doclib。 - 确认
$MINERU_HOME/doclib.lock存在。 - 使用相同环境直接执行第二个
python -m mineru.doclib.app。 - 确认第二个进程立即失败,第一个 server 仍可通过 status 访问。
- 保留 endpoint 中有效的 PID 和
server_id,临时将 transports 改为不可连接的地址,依次执行mineru server status --json、mineru server start和mineru server stop。 - 恢复原 endpoint,确认第一个 server 仍可通过 status 访问。
- 强制终止第一个 server 进程,再次执行
mineru server start。
预期:
- 第二个进程 exit code 非 0,stderr 包含当前 home,但不显示
doclib.lock路径。 - 第二个进程不删除第一个实例的 endpoint 或 UDS socket。
- endpoint 不可连接但 ownership lock 被占用时,
mineru server status --jsonexit code = 0,stdout 为可直接解析的 JSON,status = starting;endpoint 含有效 PID 时同时返回相同的pid,不得报告普通未运行状态。 - 同一状态下,
mineru server start和mineru server stopexit code 非 0,stderr 包含统一的 home ownership 消息; endpoint 含有效 PID 时消息包含reported PID <pid>。错误输出不要求显示内部错误码service_unavailable。 - status/start/stop 的 ownership 诊断不得自动终止第一个 server;恢复原 endpoint 后,第一个 server 仍可访问。
- 第一个进程退出后 OS lock 自动释放;replacement 能取得 ownership、清理 stale discovery 文件并正常启动。
doclib.lock文件是否存在不表示 server 是否正在运行,其保留行为可能因平台而异。
4A. Telemetry 命令¶
TELEMETRY-001 telemetry help¶
命令:
mineru telemetry --help
mineru telemetry status --help
mineru telemetry enable --help
mineru telemetry disable --help
mineru telemetry preview --help
mineru telemetry flush --help
预期:
- 每条 exit code = 0
- 输出包含 usage 或 options 类帮助信息
mineru telemetry --help输出包含status、enable、disable、preview、flush- 不触发 telemetry 首次选择 prompt
- 不包含 Python traceback
TELEMETRY-002 status JSON 结构¶
前置: server 正在运行。
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 包含
state、installation_id、pending_periods、pending_metrics state取值为unset、enabled或disabledinstallation_id为非空字符串pending_periods和pending_metrics为非负整数- telemetry status 命令自身不触发首次选择 prompt
- 不包含 Python traceback
TELEMETRY-003 preview JSON 结构¶
前置: server 正在运行。
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 为下一次外部 telemetry HTTP 请求 body 的预览,不额外包 CLI metadata
- JSON 包含
api_version、schema_version、batch_id、installation_id、period_start、period_end、context、metrics installation_id与 TELEMETRY-002 的installation_id一致metrics为数组;没有待上报数据时允许为空数组- preview 不触发 flush,不要求外网可用
- 不包含 Python traceback
TELEMETRY-004 enable / disable 与 installation_id 稳定性¶
前置: server 正在运行。
命令:
mineru telemetry status --json
mineru telemetry enable --json
mineru telemetry status --json
mineru telemetry disable --json
mineru telemetry status --json
预期:
- 每条 exit code = 0
- 每条 stdout 为可直接解析的 JSON
- enable 返回后,后续 status 的
state为enabled - disable 返回后,后续 status 的
state为disabled - 全流程中
installation_id保持不变 - enable/disable 命令自身不触发首次选择 prompt
- 不包含 Python traceback
TELEMETRY-005 disabled 时不新增聚合¶
前置: server 正在运行。
命令:
mineru telemetry disable --json
mineru search "mineru-e2e-query-that-should-not-exist" --limit 1 --json
mineru telemetry preview
预期:
- 三条 exit code = 0
- search stdout 为可直接解析的 JSON,允许结果为空
- preview stdout 为可直接解析的 JSON
- preview JSON 中
metrics为空数组,或至少不包含本次 search 产生的search.request.count、search.finished.count、search.duration_bucket.count、search.results_bucket.count - 不包含 Python traceback
TELEMETRY-006 unset 或 disabled 时 flush 不外发¶
前置: server 正在运行;如果当前状态不是 disabled,先执行 mineru telemetry disable --json。
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 中
action=flush - JSON 中
executed=false - JSON 中
reason=telemetry_not_enabled - 不要求外网可用
- 不包含 Python traceback
TELEMETRY-007 enabled 时 preview 可观察业务聚合¶
前置: server 正在运行。
命令:
mineru telemetry enable --json
mineru search "mineru-e2e-query-that-should-not-exist" --limit 1 --json
mineru telemetry preview
预期:
- 三条 exit code = 0
- search stdout 为可直接解析的 JSON,允许结果为空
- preview stdout 为可直接解析的 JSON
- preview JSON 中
metrics包含search.request.count - preview JSON 中应包含
search.finished.count和search.duration_bucket.count - 如果 search 正常返回,
search.finished.count的 status 维度为succeeded metrics中不得包含 query 原文mineru-e2e-query-that-should-not-exist- 不包含 Python traceback
TELEMETRY-008 enabled flush 行为¶
前置: 已执行 TELEMETRY-007,且 preview 中有待上报 metrics。
命令:
预期分支:
- 如果外部 telemetry endpoint 可访问且接收成功:
- flush exit code = 0
- flush JSON 中
action=flush - flush JSON 中
flush_result.status为success或partial_success - 后续 preview 中已成功发送 period 的 metrics 被清除或减少
- 如果外部 telemetry endpoint 不可访问、超时或返回 5xx:
- flush exit code = 0
- flush JSON 中
flush_result.status为failed、partial_success或等价重试状态 - 后续 preview 可保留待上报 metrics
- 两个分支都不应输出外部 endpoint response body
- 两个分支都不应包含 Python traceback
TELEMETRY-009 首次交互式 prompt¶
前置:
- 使用全新的
MINERU_HOME,server 已启动,且mineru telemetry status --json返回state=unset。 - 本用例必须在真实交互式终端执行;如果执行 Agent 只能非交互执行命令,可标记 BLOCKED。
命令:
操作与预期:
- 命令进入业务执行前提示是否开启匿名聚合 telemetry
- prompt 文案应说明收集的是匿名、本地聚合的使用与诊断数据
- prompt 文案应说明不会收集文档内容、提取文本/图片、文件名、文件路径、URL、query、prompt、snippet、traceback、exception message、hostname、用户名、账号 ID、API Key 或精确 CPU/GPU 型号
- prompt 文案应说明 Enter /
y/yes表示开启,n/no表示关闭 - prompt 文案应说明后续可通过
mineru telemetry enable/mineru telemetry disable修改,并可通过mineru telemetry preview查看将要上报的 payload - prompt 文案不得包含当前命令的文件路径、query、文档内容或其它业务输入
- 输入 Enter、
y或yes后,命令继续执行,后续mineru telemetry status --json返回state=enabled - 在另一轮全新
MINERU_HOME中输入n或no后,命令继续执行,后续mineru telemetry status --json返回state=disabled mineru telemetry ...、mineru server ...、mineru config ...命令自身不触发 prompt--help、--json、CI、Agent caller、非 TTY、server 不可访问时不触发 prompt- 不包含 Python traceback
TELEMETRY-010 preview 隐私边界¶
前置: server 正在运行,telemetry 已启用。
命令:
mineru telemetry enable --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru search "mineru-e2e-query-that-should-not-exist" --limit 1 --json
mineru telemetry preview
预期:
- 前三条业务命令 exit code = 0;如果 parse 因环境缺少 flash 能力失败,可记录失败分支,但仍继续检查 preview 隐私边界
- preview exit code = 0,stdout 为可直接解析的 JSON
- preview JSON 不包含:
$MINERU_E2E_FIXTURE_DIRsample.pdfmineru-e2e-query-that-should-not-exist- Markdown 正文、snippet、页面文本、traceback
- API key、secret、配置对象原文
- preview JSON 中允许出现 metric name、低基数字段、bucket、status、tier、source、caller、installation_id 和粗粒度环境 context
5. Config 命令¶
CONFIG-001 查看配置¶
命令:
预期:
- exit code = 0
- 输出包含
Config或配置 key
CONFIG-002 JSON 查看配置¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 包含 config 或 sources 信息
CONFIG-003 设置和读取配置¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru config get parse_server.local.managed_tier
预期:
- 两条 exit code = 0
- get 输出包含
parse_server.local.managed_tier - get 输出包含
standard
CONFIG-003A JSON 读取配置¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru config get parse_server.local.managed_tier --json
预期:
- 两条 exit code = 0
- set 使用普通文本输出;本用例不要求
config set支持--json - get stdout 为可直接解析的 JSON
- get JSON 包含
parse_server.local.managed_tier - get JSON 中 value 为
standard,并且 source 应体现 override 或等价覆盖来源
CONFIG-003B managed tier 模型未准备时拒绝配置¶
隔离要求:
- 使用独立
MINERU_HOME执行本 case。 - 该
MINERU_HOME下的models/目录必须为空或不存在。 - 不执行
mineru-kit models download。
错误输出说明:
mineru config set当前使用普通文本输出,不支持--json。parse_server_model_not_ready是服务端/API JSON error 的error.code,不要求出现在本 CLI case 的 stdout 或 stderr 中。
命令:
mineru config set parse_server.local.managed_tier basic
mineru config get parse_server.local.managed_tier --json
预期:
- 第一条命令 exit code = 1
- 第一条命令输出可读错误
- stdout 或 stderr 表明目标 tier 的模型文件未准备完成
- stdout 或 stderr 包含
mineru-kit models download --tier basic - 第二条命令 exit code = 0
- get JSON 中
value仍为默认值standard,或保持该隔离 HOME 中原有值 - 不包含 Python traceback
CONFIG-003C managed mode 模型未准备时拒绝启用¶
隔离要求:
- 使用独立
MINERU_HOME执行本 case。 - 该
MINERU_HOME下的models/目录必须为空或不存在。 - 不执行
mineru-kit models download。
命令:
预期:
- 第一条命令 exit code = 1
- 第一条命令输出可读错误
- stdout 或 stderr 表明当前 managed tier 的模型文件未准备完成
- stdout 或 stderr 包含
mineru-kit models download --tier standard - 第二条命令 exit code = 0
- get JSON 中
value仍为默认值disabled,或保持该隔离 HOME 中原有值 - 不包含 Python traceback
CONFIG-003D 模型准备后允许启用 managed mode¶
前置条件:
- 使用已完成
mineru-kit models download --tier basic --small-backend onnx --vlm-engine llama-cpp和mineru-kit models verify --tier basic --small-backend onnx --vlm-engine llama-cpp的MINERU_HOME。
命令:
mineru config set parse_server.local.managed_tier basic
mineru config set parse_server.local.mode managed
mineru config get parse_server.local.managed_tier --json
mineru config get parse_server.local.mode --json
预期:
- 四条命令均 exit code = 0
managed_tierget JSON 中value = basicmodeget JSON 中value = managed- 不包含 Python traceback
CONFIG-004 unset 配置¶
命令:
mineru config unset parse_server.local.managed_tier
mineru config get parse_server.local.managed_tier
预期:
- 两条 exit code = 0
- unset 输出包含
removed或unchanged - get 仍能返回有效配置值,默认值应为
standard或等价默认 tier
CONFIG-004A unset 后 JSON 读取配置¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru config unset parse_server.local.managed_tier
mineru config get parse_server.local.managed_tier --json
预期:
- 三条 exit code = 0
- unset 使用普通文本输出;本用例不要求
config unset支持--json - get 输出为可直接解析的 JSON
- unset 后 get 仍能返回有效配置值,默认值应为
standard或等价默认 tier
CONFIG-005 exclude-rules¶
命令:
mineru config exclude-rules add "*/tmp-mineru-e2e-ignore/*" --priority 10
mineru config exclude-rules list
预期:
- 两条 exit code = 0
- list 输出包含该 pattern 或规则 id
CONFIG-005A exclude-rules JSON 和 remove¶
命令:
mineru config exclude-rules add "*/tmp-mineru-e2e-remove/*" --priority 11 --json
mineru config exclude-rules list --json
mineru config exclude-rules remove <rule_id>
mineru config exclude-rules list --json
执行说明:
<rule_id>从第一条 add JSON 输出或第二条 list JSON 输出中提取。
预期:
- 四条 exit code = 0
- add/list JSON 均可直接解析
- remove 前 list 中包含 pattern
*/tmp-mineru-e2e-remove/* - remove 输出包含
removed、Exclude rule或等价成功信息 - remove 后 list 中不再包含该 rule id
CONFIG-006 旧 exclude 命令不可用¶
命令:
预期:
- exit code != 0
CONFIG-007 parsing-rules¶
命令:
mineru config parsing-rules add "*/mineru-e2e/*" --tier flash --pages all --name e2e-flash-rule
mineru config parsing-rules list
预期:
- 两条 exit code = 0
- list 输出包含 pattern
- list 输出包含
flash - list 输出包含
all
CONFIG-008 parsing-rules JSON 和 remove¶
命令:
mineru config parsing-rules add "*/mineru-e2e-remove/*" --tier flash --pages 1-1 --name e2e-remove-rule --json
mineru config parsing-rules list --json
mineru config parsing-rules remove <rule_id>
mineru config parsing-rules list --json
执行说明:
<rule_id>从第一条 add JSON 输出或第二条 list JSON 输出中提取。
预期:
- 四条 exit code = 0
- add/list JSON 均可直接解析
- remove 前 list 中包含 pattern、
flash、1-1 - remove 输出包含
removed、Parsing rule或等价成功信息 - remove 后 list 中不再包含该 rule id
CONFIG-009 不存在的配置 key¶
命令:
预期:
- 两条命令应有一致、可解释的行为
- 如果 exit code = 0,输出必须明确表示 key 不存在、值为空或来源为默认缺失
- 如果 exit code != 0,输出必须包含 not found、unknown key、invalid key 或等价错误
--json失败时 stdout 必须为可直接解析的 JSON error,且包含error.code和error.message- 不包含 Python traceback
5A. Remote API Usage¶
USAGE-001 查询 Remote API usage¶
命令:
预期:
- 三条命令均 exit code = 0
- 普通输出标题为
Remote API Usage - 普通输出包含 Remote URL、access level、billing period、current 和 limits
- JSON stdout 可直接解析,顶层包含
remote_url和usage usage.object = usage,且usage内包含access_level、billing_period、current和limits- JSON 数值来自 Remote API,不依赖本用例硬编码固定配额
- 不包含 Local Parse Server usage
USAGE-002 anonymous guidance¶
前置:
- doclib server 进程未设置
MINERU_API_KEY - 当前 Remote URL 为
https://mineru.net/api
命令:
预期:
- exit code = 0
- 顶层包含
usage,且usage.object = usage usage.access_level = anonymous- 顶层包含
guidance guidance.type = configure_official_api_keyguidance.required = falseguidance.url = https://mineru.net/apiManage/tokenguidance.command使用parse_server.remote.api_key,且不包含真实 API Keyerror字段不存在
USAGE-003 invalid API Key guidance¶
命令:
mineru config set parse_server.remote.api_key invalid-e2e-api-key
mineru usage --json
mineru config unset parse_server.remote.api_key
预期:
- set 和 unset 均 exit code = 0,且不回显完整 API Key
- usage exit code != 0
- usage stdout 为可直接解析的 JSON
error.code = invalid_api_keyerror.param = parse_server.remote.api_key- 顶层
guidance.type = configure_official_api_key guidance.required = true- guidance 不修改
error.message或其它 error 字段
USAGE-004 环境变量 fallback¶
前置:
- doclib server 使用有效
MINERU_API_KEY启动 - SQLite 中没有
parse_server.remote.api_keyoverride
命令:
mineru config unset parse_server.remote.api_key
mineru config get parse_server.remote.api_key --json
mineru usage --json
预期:
- 三条命令均 exit code = 0
- config JSON 的 source 为
environment - config JSON 只包含脱敏值,不包含完整环境变量 API Key
- usage 的
access_level = registered - usage JSON 不包含 anonymous API Key guidance
6. Watch 命令¶
WATCH-001 添加 watch¶
命令:
预期:
- exit code = 0
- 输出包含
Watch added或 id
WATCH-001A 重复添加 watch¶
前置: WATCH-001 已成功。
命令:
预期:
- 命令应有明确行为:
- 若允许幂等,exit code = 0,输出包含 existing、already、Watch added 或等价信息
- 若不允许重复,exit code != 0,输出包含 duplicate、already exists 或等价错误
- 不产生不可解释的重复 watch 记录
- 不包含 Python traceback
WATCH-002 列出 watch¶
命令:
预期:
- exit code = 0
- 输出包含
$MINERU_E2E_FIXTURE_DIR/watch-dir或e2e-watch
WATCH-003 JSON 列出 watch¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 包含 watches 数组或 watch 信息
WATCH-004 watch rescan¶
命令:
预期:
- exit code = 0
- 输出包含
Scan - 状态为 done、running 或 pending 均可接受
- 不出现
watch_not_found
WATCH-004A 使用 watch id rescan¶
前置: WATCH-002 或 WATCH-003 可获得 watch id。
命令模板:
预期:
- 两条 exit code = 0
- 第一条输出包含
Scan - 第二条输出为可直接解析的 JSON
- JSON 包含 scan id、status、path 或 watch_id 中的部分字段
WATCH-004B watch 默认使用 local flash¶
前置: WATCH-001 已添加 watch-dir,且 watch-doc.pdf 未命中任何 parsing rule。
命令:
mineru watch rescan "$MINERU_E2E_FIXTURE_DIR/watch-dir" --wait 60 --json
mineru show file "$MINERU_E2E_FIXTURE_DIR/watch-dir/watch-doc.pdf" --json
mineru list parses --tier flash --status done --json
预期:
- 三条命令均 exit code = 0,stdout 均为可直接解析的 JSON
- show file JSON 中
watch-doc.pdf最终存在flashparse/cache - list parses 中与该文件 sha256 匹配的 parse record 为
tier = flash、privacy = local、via = local - 未命中 parsing rule 时不自动创建
basic、standard、advanced或 remote parse record - watch 结果仅用于发现和索引,不视为默认最终阅读质量
- 不包含 Python traceback
WATCH-005 删除 watch¶
命令:
预期:
- exit code = 0
- 输出包含
Watch removed
WATCH-006 删除不存在的 watch¶
命令:
预期:
- exit code != 0
- 输出包含
watch_not_found、not found 或等价错误 - 不包含 Python traceback
WATCH-007 添加不存在目录¶
命令:
预期:
- exit code != 0
- 输出包含 not found、unreachable、invalid path 或等价错误
- 不包含 Python traceback
7. Scan 命令¶
SCAN-001 扫描单文件¶
命令:
预期:
- exit code = 0
- 输出包含
Scan - 输出包含 seen、refreshed、new、changed、deleted 中的统计字段
SCAN-002 扫描目录 no-wait¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 包含 scan id、status、path 或 kind 字段
- kind 应为 manual
SCAN-003 扫描不存在路径¶
命令:
mineru scan "$MINERU_E2E_FIXTURE_DIR/not-exist"
mineru scan "$MINERU_E2E_FIXTURE_DIR/not-exist" --json
预期:
- 两条 exit code != 0
- 输出包含 not found、unreachable、invalid path 或等价错误
- 不包含 Python traceback
- JSON 模式不得输出半截 JSON 混合 traceback
SCAN-004 扫描空目录¶
前置: 测试数据目录预先包含空目录 $MINERU_E2E_FIXTURE_DIR/empty-dir/。
命令:
mineru scan "$MINERU_E2E_FIXTURE_DIR/empty-dir" --wait 30
mineru scan "$MINERU_E2E_FIXTURE_DIR/empty-dir" --wait 30 --json
预期:
- 两条 exit code = 0
- JSON 输出可直接解析
- 统计字段中 seen/new/changed/deleted 等计数为 0 或符合空目录语义
- 不包含 Python traceback
SCAN-005 扫描不支持文件类型¶
前置: 测试数据目录预先包含不支持文件 $MINERU_E2E_FIXTURE_DIR/unsupported.bin。
命令:
mineru scan "$MINERU_E2E_FIXTURE_DIR/unsupported.bin" --wait 30
mineru scan "$MINERU_E2E_FIXTURE_DIR/unsupported.bin" --wait 30 --json
预期:
- 两条 exit code = 0 或返回明确的 unsupported 错误
- 如果 exit code = 0,输出统计中应体现 unsupported 或 excluded 计数
- 如果 exit code != 0,输出包含 unsupported、invalid type 或等价错误
- 不包含 Python traceback
8. Parse 命令¶
PARSE-001 文件不存在¶
命令:
预期:
- exit code != 0
- 输出包含
File not found
PARSE-002 显式 flash parse¶
命令:
预期:
- exit code = 0
- 输出不包含 Python traceback
- 输出为可读 Markdown、文本内容或 parse 状态提示
PARSE-003 flash parse JSON¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 顶层包含
parse与content parse.sha256或等价 doc 标识存在parse.tier = flashparse.status = donecontent不为 nullcontent.request_scope、content.content_ranges或content.next_request中至少一部分字段存在
PARSE-004 cache hit 行为¶
重复执行:
预期:
- exit code = 0
- 不重新失败
- 若 JSON 中包含 cache_hit,应为 true 或体现已复用结果
- tier 仍为 flash
PARSE-005 no-wait 行为¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 顶层包含
parse与content parse.status为pending、parsing或done- 若
parse.status不是done,则content = null - 若命中缓存直接完成,则
content可直接返回 - 不长时间阻塞
PARSE-006 force 行为¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 不删除旧缓存导致后续普通 parse 失败
PARSE-006A force 默认输出不打印过程 status¶
命令:
预期:
- exit code = 0
- 输出为解析内容、Markdown 或最终可读结果
- 默认模式输出不包含
Parse status: - 默认模式输出不包含
Parse queued - 不包含 Python traceback
PARSE-006B verbose 输出允许过程 status¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --verbose
预期:
- exit code = 0
- 输出允许包含
Parse queued - 输出允许包含
Parse status: - 最终仍输出解析内容、Markdown 或最终可读结果
- 不包含 Python traceback
PARSE-007 默认 tier 行为¶
Profile 前置条件: MINERU_MODEL_SMALL_BACKEND=onnx 与 MINERU_MODEL_VLM_ENGINE=llama-cpp,doclib server 及 managed parse-server 均在该环境下启动。PARSE-007、PARSE-007A、PARSE-007B、PARSE-007C 构成 light profile 的本地 PDF tier 覆盖。
命令:
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含standard,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
- 默认实际 tier 为
standard,不为flash - show JSON 中
tier = standard、privacy = local、via = local - 不允许静默返回 flash 内容
- 不包含 Python traceback
PARSE-007A PDF local basic tier(light stack)¶
命令:
mineru config set parse_server.local.managed_tier basic
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含basic,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = basicparse.status = donecontent不为 null- show JSON 中
tier = basic、privacy = local、via = local - 不包含 Python traceback
PARSE-007B PDF local standard tier(light stack)¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含standard,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = standardparse.status = donecontent不为 null- show JSON 中
tier = standard、privacy = local、via = local - 不包含 Python traceback
PARSE-007C PDF local advanced tier(light stack)¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含advanced,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = advancedparse.status = donecontent不为 null- show JSON 中
tier = advanced、privacy = local、via = local - 不包含 Python traceback
PARSE-007A1 PDF local basic tier(full stack)¶
前置条件:
- 已按 2.2.2 停止 server、设置
MINERU_MODEL_SMALL_BACKEND=torch与MINERU_MODEL_VLM_ENGINE=llama-cpp并重新启动 server。 - 已完成
mineru-kit models download --tier standard --small-backend torch --vlm-engine llama-cpp和对应 verify。
命令:
mineru config set parse_server.local.managed_tier basic
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含basic,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = basic、parse.status = done、content不为 null- show JSON 中
tier = basic、privacy = local、via = local - 不包含 Python traceback
PARSE-007B1 PDF local standard tier(full stack)¶
前置条件: PARSE-007A1 已完成,当前 profile 仍为 MINERU_MODEL_SMALL_BACKEND=torch 与 MINERU_MODEL_VLM_ENGINE=llama-cpp。
命令:
mineru config set parse_server.local.managed_tier standard
mineru config set parse_server.local.mode managed
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
- 重复执行
mineru server status --json,直到 local parse-server healthy 且supported_tiers包含standard,再执行 parse。 <created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 五条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = standard、parse.status = done、content不为 null- show JSON 中
tier = standard、privacy = local、via = local - 不包含 Python traceback
PARSE-007C1 PDF local advanced tier(full stack)¶
前置条件: PARSE-007B1 已完成,当前 profile 仍为 MINERU_MODEL_SMALL_BACKEND=torch 与 MINERU_MODEL_VLM_ENGINE=llama-cpp;Standard managed server healthy 且 supported_tiers 包含 advanced。
命令:
mineru server status --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --json
mineru show parse <created_parse_id> --json
执行说明:
<created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。- 本用例完成后必须按 2.2.2 停止 server、恢复
MINERU_MODEL_SMALL_BACKEND=onnx与MINERU_MODEL_VLM_ENGINE=llama-cpp并重新启动 server;等待 light local parse-server healthy 后再继续后续 case。
预期:
- 三条命令均 exit code = 0
- parse JSON 和 show JSON 均可直接解析
parse.tier = advanced、parse.status = done、content不为 null- show JSON 中
tier = advanced、privacy = local、via = local - 不包含 Python traceback
PARSE-007D 旧 tier 名称不可用¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier medium --pages 1-1
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier high --pages 1-1
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier xhigh --pages 1-1
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier pro --pages 1-1
预期:
- 四条命令均 exit code != 0
- 输出明确说明 tier 取值无效,并列出或体现
flash、basic、standard、advanced中的合法值 - 不启动 parse,不生成新的 parse record
- 不包含 Python traceback
PARSE-008 输出到文件¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output.md"
预期:
- exit code = 0
- 输出包含
Written to或等价成功信息 - 不在 stdout 大量打印完整文档内容
- 后续可通过
mineru read或重新mineru parse验证解析缓存仍可用 - 输出文件路径应为命令指定路径
PARSE-009 JSON 与 output 组合¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output-json.md" --json
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 顶层保持
parse --jsonenvelope,包含parse和content - 当文件写出成功时,
content可以为 null - JSON 顶层包含
output output.status=writtenoutput.path为实际写入路径,建议为绝对路径或规范化绝对路径- 输出文件存在,路径为命令指定路径
- stdout 不允许包含
Written to、Rich 表格、Markdown 正文或其它人类提示文本 - 不包含 Python traceback
PARSE-010 limit 截断与 next_request¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --json
预期:
- exit code = 0
- 输出为可直接解析的 JSON
content不为 null- 如果内容超过 limit,
content中应体现 truncated、next_request、cursor、after 或等价续读信息 - 如果内容未超过 limit,
content中应明确表示未截断或没有 next_request - 不包含 JSON 外的 status/info 文本
PARSE-011 after 续读¶
前置: PARSE-010 返回 next_request.after 或等价 cursor。
命令模板:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --after <after_cursor> --limit 30000 --json
预期:
- exit code = 0
- 输出为可直接解析的 JSON
content不为 nullcontent.request_scope、content.content_ranges或等价字段体现 after/cursor 已生效- 不返回与第一页起始完全相同的截断片段,除非服务端明确说明 cursor 已到末尾
PARSE-012 no-marker¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --no-marker
预期:
- exit code = 0
- 输出不包含
<!-- Next: - 输出不包含 Python traceback
PARSE-013 remote 不接受 flash tier¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --remote --wait 20 --json
预期分支:
- exit code != 0
- stdout 为可直接解析的 JSON error
error.code = tier_unsupported_for_remoteerror.param = tier- 不创建 parse record
- 不包含 Python traceback
PARSE-013A remote 默认 tier¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
- parse 成功时,
<created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取,再执行 show。
预期分支:
- 如果 remote parse-server 暴露
standard或basic: - parse 和 show 均 exit code = 0,stdout 均为可直接解析的 JSON
- 默认 tier 按
standard、basic的顺序选择第一个受 remote 支持的 tier - show JSON 中
privacy = remote、via = remote - 如果 remote parse-server 未暴露
standard或basic,包括仅暴露advanced: - exit code != 0
- stdout 为可直接解析的 JSON error
error.code = quality_tier_unavailable- 不允许 fallback 到
flash - 不包含 Python traceback
PARSE-013A1 PDF remote standard tier¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
<created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取。
预期:
- 两条命令均 exit code = 0,stdout 均为可直接解析的 JSON
parse.tier = standard- show JSON 中
tier = standard、privacy = remote、via = remote - remote 不可用、remote 不支持 Standard、或实际
via = local均记录为失败 - 不允许 fallback 到 local standard、其它 tier 或 flash
- 不包含 Python traceback
PARSE-013B remote no-wait¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --no-wait --json
mineru show parse <created_parse_id> --json
执行说明:
<created_parse_id>从第一条 JSON 的parse.created_parse_ids[0]提取。- 第一条必须立即返回;随后可重复执行 show,直到 parse 进入 done 或 failed 终态。
预期分支:
- 第一条 exit code = 0,stdout 为可直接解析的 JSON,不长时间阻塞
parse.tier = standard、parse.created_parse_ids非空,状态为 pending、parsing 或 done- 最终 done 时,show JSON 中
privacy = remote,via为remote或同 tier fallback 的local - 最终 failed 时,show JSON 中
error_code为parse_server_unavailable、engine_unavailable、tier_mismatch或其它结构化执行错误码 - 不允许 fallback 到
flash或其它 tier - 不包含 Python traceback
PARSE-013C remote force¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
mineru show parse <created_parse_id> --json
执行说明:
- parse 成功时,
<created_parse_id>从 parse JSON 的parse.created_parse_ids[0]提取,再执行 show。
预期分支:
- 如果 remote 或同 tier local fallback 可用:
- parse 和 show 均 exit code = 0,stdout 均为可直接解析的 JSON
- 不复用旧的 done batch 作为唯一依据,JSON 中应体现新 parse 或 force 后结果
- show JSON 中
privacy = remote - remote 成功时
via = remote;remote 不可用但 local Standard 可用时允许via = local - 后续普通 remote parse 不因 force 损坏缓存
- 如果 remote 不支持 Standard,或 remote 和 local Standard 均不可用:
- exit code != 0
- stdout 为可直接解析的 JSON error
- 依据
error.code判定,不依赖error.message文案 - 不允许 fallback 到
flash或其它 tier - 不包含 Python traceback
PARSE-013D remote output¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/remote-output.md"
预期分支:
- 如果 remote 或同 tier local fallback 可用:
- exit code = 0
- 输出包含
Written to或等价成功信息 - stdout 不大量打印完整文档内容
- 输出路径为命令指定路径
- 如果 remote 和 local Standard 均不可用:
- exit code != 0
- 不创建空的成功输出文件
- 不允许 fallback 到
flash或其它 tier - 不包含 Python traceback
PARSE-013E remote 与 local cache 隔离¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --wait 180 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
预期:
- 第一条和第三条 local flash 命令 exit code = 0,tier = flash
- 第二条按 PARSE-013C 的 remote/local fallback 分支判定,成功时 tier 必须为 standard
- remote 成功或失败均不得污染 local flash 缓存
- 第三条不应因为第二条 remote 失败而失败
PARSE-013F remote 配置规则¶
命令:
mineru config parsing-rules add "*/sample.pdf" --tier standard --remote --pages 1-1 --name e2e-remote-rule --json
mineru watch add "$MINERU_E2E_FIXTURE_DIR" --label e2e-remote-rule-watch --json
mineru watch rescan "$MINERU_E2E_FIXTURE_DIR" --wait 60 --json
mineru list parses --limit 20 --json
mineru watch remove "$MINERU_E2E_FIXTURE_DIR" --json
mineru config parsing-rules remove <rule_id>
执行说明:
<rule_id>从第一条 add JSON 中提取。- watch id 从
watch addJSON 中提取;如果 watch 已存在,可复用已有 watch 或先 remove 后重建。
预期分支:
- add/watch/rescan/list/remove exit code = 0,JSON 可解析
- parsing-rule 的
remote字段用于规则命中后的自动解析策略,尤其是 watch 自动触发/后台解析;不要求用户主动mineru parse <path>在未传--remote时也按该规则上传远端 - 规则命中的 parse record 应为
tier = standard、privacy = remote - remote 成功时 parse record 的
via = remote - remote 不可用但 local Standard 可用时允许
via = local;remote 和 local Standard 均不可用时 parse record 应为 failed,并记录结构化error_code - 不允许规则任务 fallback 到
flash或其它 tier - remove 后规则不再影响后续 watch 自动解析
PARSE-013G tier 与文件类型约束¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier standard --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier standard --remote --wait 60 --json
预期:
- 两条命令均 exit code != 0,stdout 均为可直接解析的 JSON error
- 第一条
error.code = tier_unsupported_for_file_type,error.param = tier - 第二条
error.code = remote_unsupported_for_file_type,error.param = remote - Office 文件只允许 local
flash,不创建 Standard/remote parse record - 不包含 Python traceback
PARSE-014 非法 format¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --format html
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --format text
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --format json
预期:
- 三条 exit code != 0
- 输出包含 invalid choice、not one of、unsupported format 或等价错误
- 不启动解析任务
- 不包含 Python traceback
PARSE-015 JSON 输出纯净性¶
命令:
预期:
- exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含
Parse status: - stdout 不包含
Parse queued - stdout 不包含
Written to - stderr 不包含非错误噪声
9. Read 命令¶
前置: PARSE-003 或 PARSE-004 至少成功一次,并从输出、show file 或 list docs 获得 doc short id。
如果无法获得 short id,READ 子套件标记为 BLOCKED。
READ-001 读取 page locator¶
命令模板:
预期:
- exit code = 0
- 输出为 Markdown、文本或可读内容
- 不包含 traceback
READ-002 read JSON¶
命令模板:
预期:
- exit code = 0
- 输出为 JSON
- JSON 包含 request_scope
- request_scope.locator 包含输入 locator 或规范化 locator
READ-002A 无 tier locator 读取最高缓存¶
前置: PARSE-007A、PARSE-007B、PARSE-007C 已为同一 sample.pdf 的第 1 页生成 basic、standard、advanced 三种 done 缓存。
命令模板:
预期:
- exit code = 0,stdout 为可直接解析的 JSON
- 返回
tier = advanced request_scope.locator体现输入 locator 或规范化 locator- 命令只读取最高已缓存结果,不创建新的 parse record
- 不包含 Python traceback
READ-003 read context¶
命令模板:
预期:
- exit code = 0
- 不报
context_not_applicable,除非 locator 粒度确实不支持 context
READ-004 invalid locator¶
命令:
预期:
- exit code != 0
- 输出包含 not found、invalid 或 locator 相关错误
- 不包含 traceback
READ-005 输出到文件¶
命令模板:
预期:
- exit code = 0
- 输出包含
Written to或等价成功信息 - 不在 stdout 大量打印完整文档内容
- 输出文件路径应为命令指定路径
- 不包含 traceback
READ-006 JSON 与 output 组合¶
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1" --output "$MINERU_E2E_FIXTURE_DIR/read-output-json.md" --json
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 顶层保持
read --json的 DocContentResponse 风格结构 - JSON 包含 sha256、short_id、tier、format、request_scope 或等价字段
- 当文件写出成功时,
content应为 null - JSON 顶层包含
output output.status=writtenoutput.path为实际写入路径,建议为绝对路径或规范化绝对路径- 输出文件存在,路径为命令指定路径
- stdout 不允许包含
Written to、Rich 表格、Markdown 正文或其它人类提示文本 - 不包含 Python traceback
READ-007 image 格式¶
命令模板:
预期分支:
- 如果该 locator 支持 image 输出:
- exit code = 0
- 输出为可直接解析的 JSON
- JSON 包含 asset、mime_type、path 或等价字段
- 如果该 locator 不支持 image 输出:
- exit code != 0
- 输出包含 unsupported、not available、no image 或等价错误
- 不包含 Python traceback
READ-008 image 输出到文件¶
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/read-page.png"
预期分支:
- 如果该 locator 支持 image 输出:
- exit code = 0
- 输出包含
Written to或等价成功信息 - 输出路径为命令指定路径
- 输出文件后缀只允许
.png、.jpg、.jpeg、.webp - 输出文件真实编码必须与后缀匹配
- 如果该 locator 不支持 image 输出:
- exit code != 0
- 输出包含 unsupported、not available、no image 或等价错误
- 不包含 Python traceback
READ-008A image JSON 与 output 组合¶
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/read-page-json.png" --json
预期分支:
- 如果该 locator 支持 image 输出:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 顶层保持
read --json的 DocContentResponse 风格结构 - JSON 包含
asset或等价图片元数据 content应为 null- JSON 顶层包含
output output.status=writtenoutput.path为命令指定输出路径的实际写入路径- 不应要求调用方依赖服务端临时 asset path
- 如果该 locator 不支持 image 输出:
- exit code != 0
- stdout 必须为可直接解析的 JSON error,且包含
error.code和error.message - 不包含 Python traceback
READ-009 limit 截断与 next_request¶
命令模板:
预期:
- exit code = 0
- 输出为可直接解析的 JSON
- 如果内容超过 limit,JSON 应体现 truncated、next_request、cursor、locator 或等价续读信息
- 如果内容未超过 limit,JSON 应明确表示未截断或没有 next_request
READ-010 使用 next_request 续读¶
前置: READ-009 返回 next_request.locator。
命令模板:
预期:
- exit code = 0
- 输出为可直接解析的 JSON
- request_scope.locator 体现输入 locator 或规范化 locator
- 不返回与上一段完全相同的起始截断片段,除非服务端明确说明 cursor 已到末尾
READ-011 no-marker¶
命令模板:
预期:
- exit code = 0
- 输出不包含
<!-- Next: - 不包含 Python traceback
READ-012 非法 format¶
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1" --format html
mineru read "doc:<short_id>/tier:flash/page:1" --format text
mineru read "doc:<short_id>/tier:flash/page:1" --format json
预期:
- 三条 exit code != 0
- 输出包含 invalid choice、not one of、unsupported format 或等价错误
- 不包含 Python traceback
READ-013 JSON 输出纯净性¶
命令模板:
预期:
- exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含
Written to - stdout 不包含 Rich 表格、status/info 文本或 Markdown 内容前缀
10. Search 与 Find¶
SEARCH-001 find by filename¶
命令:
预期:
- exit code = 0
- 输出包含
sample.pdf或明确No results found - 若前面 scan/parse 成功,优先期望找到
sample.pdf
SEARCH-002 find JSON¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 包含 results、total 或等价字段
SEARCH-003 search 内容¶
命令:
预期:
- exit code = 0
- 输出为搜索结果或
No results found - 不包含 traceback
SEARCH-004 search tier filter¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 若有结果,结果 tier 应为 flash
SEARCH-005 search min-tier¶
命令:
预期:
- exit code = 0
- 输出为 JSON
SEARCH-006 find ext filter¶
命令:
预期:
- 两条 exit code = 0
- 两条输出均为可直接解析的 JSON
- pdf 过滤下如果有结果,结果 ext 应为 pdf
- docx 过滤下如果有结果,结果 ext 应为 docx
- 不包含 Python traceback
SEARCH-007 find limit 边界¶
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- limit 生效,单次返回结果数量不超过 1
find当前只承诺文件名查询、扩展名过滤、limit 和 JSON 输出;offset 契约单独由 SEARCH-013 覆盖
SEARCH-008 search type filter¶
命令:
mineru search "sample" --type pdf --limit 10 --json
mineru search "sample" --type docx --limit 10 --json
预期:
- 两条 exit code = 0
- 两条输出均为可直接解析的 JSON
- 如果有结果,结果文件类型应符合对应 type filter
- 不包含 Python traceback
SEARCH-009 search offset¶
命令:
mineru search "sample" --limit 1 --offset 0 --json
mineru search "sample" --limit 1 --offset 1 --json
预期:
- 两条 exit code = 0
- 两条输出均为可直接解析的 JSON
- limit 生效,单次返回结果数量不超过 1
- offset 不导致崩溃
SEARCH-010 search 无结果¶
命令:
mineru search "mineru-e2e-query-that-should-not-exist" --limit 10
mineru search "mineru-e2e-query-that-should-not-exist" --limit 10 --json
预期:
- 两条 exit code = 0
- 普通输出包含
No results found或等价空结果提示 - JSON 输出可直接解析
- JSON 中 total 为 0 或 results 为空
SEARCH-011 find 无结果¶
命令:
mineru find "mineru-e2e-filename-that-should-not-exist"
mineru find "mineru-e2e-filename-that-should-not-exist" --json
预期:
- 两条 exit code = 0
- 普通输出包含
No results found或等价空结果提示 - JSON 输出可直接解析
- JSON 中 total 为 0 或 results 为空
SEARCH-012 JSON 输出纯净性¶
命令:
预期:
- 两条 exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含 Rich 表格、
No results found文本或非 JSON 前缀
11. List 命令¶
LIST-001 list files¶
命令:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 若前面 scan/parse 成功,应能看到
sample.pdf或相关 file record
LIST-001A list files filters¶
命令:
mineru list files --status active --limit 20 --json
mineru list files --ext pdf --limit 20 --json
mineru list files --limit 1 --offset 1 --json
预期:
- 三条 exit code = 0
- 三条输出均为可直接解析的 JSON
- status filter 下如果有结果,结果 status 应为 active
- ext filter 下如果有结果,结果 ext 应为 pdf
- limit/offset 不导致崩溃,返回数量不超过 limit
LIST-002 list docs¶
命令:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 若前面 parse 成功,应能看到对应 doc
LIST-002A list docs offset¶
命令:
预期:
- 两条 exit code = 0
- 两条输出均为可直接解析的 JSON
- limit 生效,单次返回结果数量不超过 1
- offset 不导致崩溃
LIST-003 list parses¶
命令:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 若前面 parse 成功,应有 flash parse 记录
LIST-003A list parses filters¶
命令:
mineru list parses --status done --limit 20 --json
mineru list parses --tier flash --status done --limit 20 --json
mineru list parses --limit 1 --offset 1 --json
预期:
- 三条 exit code = 0
- 三条输出均为可直接解析的 JSON
- status filter 下如果有结果,结果 status 应为 done
- tier/status 组合 filter 下如果有结果,结果 tier 应为 flash 且 status 为 done
- limit/offset 不导致崩溃,返回数量不超过 limit
LIST-004 list scans¶
命令:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 若前面 scan/watch rescan 成功,应有 scan 记录
LIST-004A list scans filters¶
命令:
mineru list scans --status done --limit 20 --json
mineru list scans --kind manual --limit 20 --json
mineru list scans --limit 1 --offset 1 --json
预期:
- 三条 exit code = 0
- 三条输出均为可直接解析的 JSON
- status filter 下如果有结果,结果 status 应为 done
- kind filter 下如果有结果,结果 kind 应为 manual
- limit/offset 不导致崩溃,返回数量不超过 limit
LIST-005 watch-id filters¶
前置: WATCH-003 可获得 watch id。
命令模板:
mineru list files --watch-id <watch_id> --limit 20 --json
mineru list scans --watch-id <watch_id> --limit 20 --json
预期:
- 两条 exit code = 0
- 两条输出均为可直接解析的 JSON
- 如果有结果,结果应关联该 watch id 或该 watch path
LIST-006 JSON 输出纯净性¶
命令:
mineru list files --limit 1 --json
mineru list docs --limit 1 --json
mineru list parses --limit 1 --json
mineru list scans --limit 1 --json
预期:
- 四条 exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含 Rich 表格、
No ... found文本或非 JSON 前缀
12. Show 命令¶
SHOW-001 show file¶
命令:
mineru show file "$MINERU_E2E_FIXTURE_DIR/sample.pdf"
mineru show file "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --json
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 输出包含 filename、size_bytes、page_count 或 parse tiers 中的部分字段
SHOW-001A show file 不支持 sha256¶
前置: 从 mineru show file "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --json 或 mineru list files --json 中获得 sha256。
命令模板:
预期分支:
- 两条 exit code != 0
show file只支持 file path,不支持 sha256- 普通输出包含 path、not found、invalid 或等价错误
--json输出为可直接解析的 JSON error- 不包含 Python traceback
- 使用 sha256 查询文档应走
mineru show doc <sha256>
SHOW-002 show doc¶
从 mineru list docs --json 中取一个 sha256。
命令模板:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 输出包含 sha256
- show doc 展示关联 files 或 doc metadata
SHOW-003 show parse¶
从 mineru list parses --json 中取一个 parse id。
命令模板:
预期:
- 两条 exit code = 0
- 输出包含 parse status、tier、page_range
SHOW-004 show scan¶
从 mineru list scans --json 中取一个 scan id。
命令模板:
预期:
- 两条 exit code = 0
- 输出包含 scan status 和统计字段
SHOW-005 show 不存在资源¶
命令:
mineru show parse 999999999
mineru show scan 999999999
mineru show doc 0000000000000000000000000000000000000000000000000000000000000000
mineru show file "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf"
预期:
- 四条 exit code != 0
- 输出包含 not found、invalid 或等价错误
- 不包含 Python traceback
SHOW-006 JSON 输出纯净性¶
命令模板:
mineru show file "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --json
mineru show doc <sha256> --json
mineru show parse <parse_id> --json
mineru show scan <scan_id> --json
预期:
- 四条 exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含 Rich 表格或非 JSON 前缀
13. Invalidate¶
INVALIDATE-001 invalidate flash¶
命令:
预期:
- exit code = 0
- 输出包含
Invalidated或No done batches found - 不删除源文件
INVALIDATE-001A invalidate all tiers¶
命令:
预期:
- exit code = 0
- 输出包含
Invalidated、No done batches found或等价结果 - 不删除源文件
- 后续可重新 parse
INVALIDATE-001B invalidate JSON 支持性¶
命令:
预期:
- 命令必须有明确行为:
- 如果支持 JSON,exit code = 0,stdout 为可直接解析的 JSON
- 如果不支持 JSON,exit code != 0,输出包含 no such option、unknown option 或等价错误
- 不包含 Python traceback
INVALIDATE-001C invalidate 不存在文件¶
命令:
预期:
- exit code != 0
- 输出包含 file not found、not found 或等价错误
- 不包含 Python traceback
INVALIDATE-002 invalidate 后重新 parse¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- tier = flash
- 不因 invalidate 后旧状态损坏而失败
14. Forget¶
FORGET-001 默认 dry-run¶
命令:
预期:
- exit code = 0
- 输出包含
Would forget - 不删除源文件
- 后续
mineru show file "$MINERU_E2E_FIXTURE_DIR/sample-copy.pdf"不因 dry-run 改变状态
FORGET-002 实际 forget¶
命令:
预期:
- exit code = 0
- 输出包含
Forgot - 不删除源文件
- 如果后续重新 scan/parse,该路径可被重新发现
FORGET-003 forget JSON¶
命令:
预期:
- exit code = 0
- 输出为 JSON
- 包含 forgotten_files、matched_as、warnings 或等价字段
FORGET-004 forget 目录 dry-run¶
命令:
预期:
- exit code = 0
- 输出包含
Would forget - 不删除源目录或目录内文件
- 后续
mineru watch list或mineru scan不因 dry-run 破坏状态
FORGET-005 forget 目录 execute¶
命令:
预期:
- exit code = 0
- 输出包含
Forgot - 不删除源目录或目录内文件
- 后续重新 scan/watch rescan 可重新发现该目录下文件
FORGET-006 forget 不存在路径¶
命令:
mineru forget "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf"
mineru forget "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf" --json
预期:
- 两条命令必须有明确行为
- 普通命令如果 exit code = 0,输出必须明确 forgotten_files 为 0 或有 warning
- 普通命令如果 exit code != 0,输出必须包含 not found 或等价错误
- JSON 命令如果 exit code = 0,stdout 必须为可直接解析的 JSON,且明确 forgotten_files 为 0 或有 warning
- JSON 命令如果 exit code != 0,stdout 必须为可直接解析的 JSON error,且包含
error.code和error.message - 不包含 Python traceback
FORGET-007 JSON 输出纯净性¶
命令:
预期:
- exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含
Would forget、Forgot或非 JSON 前缀
15. Cleanup¶
CLEANUP-001 cleanup deleted-files dry-run¶
命令:
预期:
- 两条 exit code = 0
- 默认 dry-run
- JSON 输出可解析
CLEANUP-002 cleanup deleted-files execute¶
命令:
预期:
- exit code = 0
- 输出包含
Removed
CLEANUP-003 cleanup orphan-docs dry-run¶
命令:
预期:
- 两条 exit code = 0
- 默认 dry-run
- JSON 输出可解析
CLEANUP-004 cleanup temp¶
命令:
预期:
- 两条 exit code = 0
- JSON 输出可解析
- 输出包含 removed temp file count 或等价字段
CLEANUP-005 cleanup deleted-files execute JSON¶
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- JSON 包含 removed/deleted/dry_run 或等价字段
- 不包含 Python traceback
CLEANUP-006 cleanup orphan-docs execute¶
命令:
预期:
- 普通命令 exit code = 0
- 普通输出包含
Removed - JSON 命令 exit code = 0
- JSON 命令 stdout 为可直接解析的 JSON
- JSON 包含 removed/orphan/dry_run 或等价字段
- 不包含 Python traceback
CLEANUP-007 cleanup temp 边界参数¶
命令:
预期:
--older-than 0 --jsonexit code = 0,输出为可直接解析的 JSON--older-than -1exit code != 0--older-than -1输出包含 invalid、must be non-negative 或等价错误- 不包含 Python traceback
CLEANUP-008 JSON 输出纯净性¶
命令:
mineru cleanup deleted-files --json
mineru cleanup orphan-docs --json
mineru cleanup temp --older-than 7 --json
预期:
- 三条 exit code = 0
- stdout 可被 JSON parser 直接解析
- stdout 第一段非空内容必须是
{或[ - stdout 不包含
Would remove、Removed或非 JSON 前缀
16. 扩展与边界场景¶
本章节补充跨命令契约、路径边界、并发、文件类型和更深层行为验证。除明确说明外,执行 Agent 仍只调用 mineru 命令。
JSONERR-001 read JSON 错误输出纯净性¶
命令:
预期:
- exit code != 0
- stdout 必须为可直接解析的 JSON error
- JSON 包含
error.type、error.code、error.message - stdout 不得混合
Error:、Rich 文本、traceback 或半截 JSON - stderr 不得混入额外的人类解释文本
JSONERR-002 watch JSON 错误输出纯净性¶
命令:
mineru watch add "$MINERU_E2E_FIXTURE_DIR/not-exist-dir" --label e2e-missing-watch --json
mineru watch remove "$MINERU_E2E_FIXTURE_DIR/not-a-watch-dir" --json
mineru watch rescan "$MINERU_E2E_FIXTURE_DIR/not-a-watch-dir" --json
预期:
- 三条 exit code != 0
- 三条 stdout 均必须为可直接解析的 JSON error
- JSON 包含
error.type、error.code、error.message - stdout 不得混合
Error:、Rich 文本、traceback 或半截 JSON - stderr 不得混入额外的人类解释文本
JSONERR-003 show/config/cleanup JSON 错误输出纯净性¶
命令:
mineru show parse 999999999 --json
mineru config get not.a.real.key --json
mineru cleanup temp --older-than -1 --json
预期:
- 三条 exit code != 0
- 三条 stdout 均必须为可直接解析的 JSON error
- JSON 包含
error.type、error.code、error.message - stdout 不得混合
Error:、Rich 文本、traceback 或半截 JSON - stderr 不得混入额外的人类解释文本
说明:
- 本用例只覆盖进入命令实现后的业务错误。
- Typer/Click 参数解析阶段错误不在 JSON 错误统一契约范围内。
JSONERR-004 server 不可连接时 JSON 错误输出纯净性¶
命令:
mineru server stop
mineru scan "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --json
mineru list files --limit 1 --json
mineru search "sample" --limit 1 --json
mineru find "sample" --limit 1 --json
mineru server start
预期:
- stop exit code = 0
- scan/list/search/find 四条命令 exit code != 0
- scan/list/search/find 四条 stdout 均必须为可直接解析的 JSON error
- JSON 包含
error.type、error.code、error.message - stdout 不得混合
Error:、Rich 文本、traceback 或半截 JSON mineru server status --json的未运行状态不适用本错误契约,见 JSONERR-005- start exit code = 0,用于恢复后续测试环境
JSONERR-005 server status JSON 未运行状态¶
命令:
预期:
- stop exit code = 0
- status exit code = 0
- status stdout 为可直接解析的 JSON
- status JSON 至少包含
running: false - status stdout 不包含
Server is not running.或 JSON error - start exit code = 0,用于恢复后续测试环境
WATCH-008 watch add JSON¶
命令:
mineru watch add "$MINERU_E2E_FIXTURE_DIR/watch-dir" --label e2e-watch-json --json
mineru watch list --json
mineru watch remove "$MINERU_E2E_FIXTURE_DIR/watch-dir" --json
预期:
- 三条 exit code = 0
- 三条 stdout 均为可直接解析的 JSON
- add JSON 包含 id、path、label、status 或等价字段
- list JSON 能看到该 watch
- remove JSON 包含 watch_id/removed 或等价字段
WATCH-009 removable watch¶
命令:
mineru watch add "$MINERU_E2E_FIXTURE_DIR/watch-dir" --label e2e-removable --removable --json
mineru watch list --json
mineru watch remove "$MINERU_E2E_FIXTURE_DIR/watch-dir"
预期:
- 三条 exit code = 0
- add/list JSON 可直接解析
- watch 记录中 removable 应为 true
- 普通 list 输出中应能体现 removable 或 JSON 中明确体现 removable
WATCH-010 removable watch unreachable 行为¶
前置: 需要一个可移除或可临时变为不可访问的 watch fixture;如果当前平台无法稳定制造,标记为 BLOCKED。
命令模板:
mineru watch add <removable_watch_path> --removable --json
mineru watch rescan <watch_id> --wait 30 --json
mineru watch list --json
预期:
- 如果路径可访问,rescan exit code = 0,watch status 为 active
- 如果路径变为不可访问,命令应返回明确 unreachable 状态、scan error 或 watch status=unreachable
- 不包含 Python traceback
LIST-007 list docs file-type filter¶
命令:
mineru list docs --file-type pdf --limit 20 --json
mineru list docs --file-type docx --limit 20 --json
预期:
- 两条 exit code = 0
- 两条 stdout 均为可直接解析的 JSON
- 如果有结果,结果 file_type 应符合过滤条件
- 不包含 Python traceback
SEARCH-013 find offset 契约¶
命令:
预期:
- 如果 CLI 设计支持 find offset,exit code = 0,stdout 为可直接解析的 JSON,返回数量不超过 1
- 如果 CLI 设计不支持 find offset,exit code != 0,输出包含 no such option、unknown option 或等价错误
- 不包含 Python traceback
PARSE-016 page range 边界¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages all --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 2-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 999-1000 --wait 60 --json
预期:
--pages allexit code = 0,stdout 为可直接解析的 JSON- 反向 page range exit code != 0 或返回明确 page_range_invalid/error JSON
- 超出页码 exit code != 0 或返回明确 page_range_invalid/not found/empty range 错误
- 不包含 Python traceback
READ-014 locator 粒度边界¶
前置: 从成功 parse/read JSON 中获得 block/char locator 或 next_request locator。
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1/block:1" --json
mineru read "doc:<short_id>/tier:flash/page:1/block:1/char:1" --json
mineru read "doc:<short_id>/tier:flash/page:999" --json
mineru read "doc:<short_id>/tier:flash/page:1/block:999" --json
预期:
- 合法 block/char locator exit code = 0,stdout 为可直接解析的 JSON
- 超出 page/block locator exit code != 0,stdout 必须为可直接解析的 JSON error
- request_scope.locator 体现输入 locator 或规范化 locator
- 不包含 Python traceback
READ-015 跨页 context¶
命令模板:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- request_scope.context = 2 或等价字段体现 context 生效
- 如果文档页数不足,命令应优雅返回可用范围,不报 traceback
FILETYPE-001 可解析的非 PDF/图片格式¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pptx" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.xlsx" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.doc" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ppt" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.xls" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.rtf" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.epub" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odt" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ods" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odp" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.csv" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.tsv" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.md" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.txt" --tier flash --wait 60 --json
预期:
- 前 14 条命令(DOCX/PPTX/XLSX/DOC/PPT/XLS/RTF/OFD/EPUB/HTML/ODT/ODS/ODP/CSV)exit code = 0
- 前 14 条 stdout 均为可直接解析的 JSON,且
parse.status = done、content或 doc metadata 合理存在 - MD、TXT 两条命令 exit code != 0
- MD、TXT 的 stdout 均为可直接解析的 JSON error
- MD、TXT 的
error.type = invalid_request_error、error.code = parse_not_required、error.param = path - 不包含 Python traceback
FILETYPE-001A 图片输入¶
命令:
预期分支:
- 如果当前安装支持该文件类型,exit code = 0,stdout 为可直接解析的 JSON,content 或 doc metadata 合理存在
- 如果当前安装不支持该文件类型,exit code != 0,输出包含 unsupported、file_type_unsupported、no_engine 或等价错误
- 不包含 Python traceback
FILETYPE-002 损坏、空、不可读文件¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/corrupted.pdf" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/empty.pdf" --tier flash --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/no-read.pdf" --tier flash --wait 60 --json
预期:
- 三条 exit code != 0,除非当前实现对空文件有明确可接受语义
- 输出包含 file_corrupted、parse_empty、file_permission_denied、file_not_found、unsupported 或等价错误
- 失败命令带
--json时,stdout 必须为可直接解析的 JSON error - 如果
no-read.pdf权限场景无法稳定制造,可标记该子项 BLOCKED - 不包含 Python traceback
FILETYPE-003 非 PDF 格式不接受 page_range¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.docx" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.epub" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odt" --tier flash --pages 1-1 --wait 60 --json
预期:
- 五条 exit code != 0
- 五条 stdout 均为可直接解析的 JSON error
error.type = invalid_request_error、error.code = page_range_invalid、error.param = page_range- 不启动解析任务,不创建 parse record
- 不包含 Python traceback
FILETYPE-004 非 PDF/图片格式 tier 约束¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier standard --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.epub" --tier standard --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier standard --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.odt" --tier advanced --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.ofd" --tier standard --remote --wait 60 --json
预期:
- 四条 local 命令 exit code != 0
- 四条 local 命令的
error.code = tier_unsupported_for_file_type、error.param = tier - 一条 remote 命令 exit code != 0
- 一条 remote 命令的
error.code = remote_unsupported_for_file_type、error.param = remote - 非 PDF/图片格式只允许 local
flash,不创建 Standard/Advanced/remote parse record - 不包含 Python traceback
FILETYPE-005 HTML source_context 资源解析¶
前置: $MINERU_E2E_FIXTURE_DIR/sample.html 引用 $MINERU_E2E_FIXTURE_DIR/html-bundle/img.jpeg。
命令:
预期:
- exit code = 0,stdout 为可直接解析的 JSON
parse.status = done,content不为 null- 解析结果包含图片引用(markdown 中存在
或等价图片标记) - 不因相对路径资源找不到而失败
- 不包含 Python traceback
PATH-001 路径字符边界¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample doc.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/中文样例.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf" --tier flash --pages 1-1 --wait 60 --json
预期:
- 文件名含空格和中文的两条命令 exit code = 0,stdout 为可直接解析的 JSON
- symlink 命令如果平台支持 symlink,exit code = 0;如果不支持或 fixture 不存在,标记 BLOCKED
- JSON 中 source/path/request_scope 不应乱码
- 不包含 Python traceback
PATH-002 相对路径和 home 路径¶
命令:
mineru parse "sample.pdf" --tier flash --pages 1-1 --wait 60 --json
mineru show file "sample.pdf" --json
mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1-1 --wait 60 --json
预期:
- 在测试 HOME 下执行时,三条 exit code = 0
- stdout 均为可直接解析的 JSON
- show/parse 应解析到同一个实际文件或等价 canonical path
- CLI 必须主动对输入 path 中的
~执行expanduser - 不能把带引号的
"~/mineru-e2e-test/sample.pdf"当作当前目录下的字面量相对路径 - 不包含 Python traceback
OUTPUT-001 output 边界¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output -
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/output-dir/existing.md"
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/not-exist-dir/out.md"
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "~/mineru-e2e-test/output-dir/home-output.md"
预期:
--output -应等价于 stdout 输出,exit code = 0,不创建名为-的文件- 输出到已有文件应有明确覆盖或拒绝策略;若覆盖,exit code = 0 且输出包含
Written to - 输出到不存在父目录应自动创建父目录并成功,exit code = 0
- 不存在父目录下的目标文件必须存在,且不为空
- 输出路径中的
~必须由 CLI 主动expanduser,不能创建字面量~目录 - 不包含 Python traceback
OUTPUT-001A output 与 JSON 边界¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output - --json
mineru read "doc:<short_id>/tier:flash/page:1" --output - --json
预期:
- 两条 exit code = 0
- stdout 均为可直接解析的 JSON
--output - --json等价于不指定--output- JSON 中不新增
output字段 - 不创建名为
-的文件 - stdout 不包含
Written to、Rich 表格、Markdown 正文或其它人类提示文本
补充分支:
预期:
- exit code != 0
- stdout 为 JSON error envelope
error.code=image_output_extension_unsupportederror.param=output- 不创建名为
-的文件
OUTPUT-002 read image output 后缀边界¶
命令模板:
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page.png"
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page.jpg"
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page.jpeg"
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page.webp"
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page"
mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_E2E_FIXTURE_DIR/output-dir/page-as-md.md"
预期:
.png、.jpg、.jpeg、.webp均 exit code = 0- 输出文件真实编码必须分别匹配 PNG、JPEG、JPEG、WebP
- 无后缀和
.md均 exit code != 0 - JSON 模式下错误为 JSON error envelope,
error.code=image_output_extension_unsupported - 不包含 Python traceback
CONCURRENCY-001 并发 parse force¶
执行方式:
- 启动两个独立 shell,同时执行同一条命令。
- 执行 Agent 仍只调用
mineru命令,不直接访问数据库。
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --json
预期:
- 两个进程均不出现 Python traceback
- 至少一个命令成功;另一个可成功、等待已有任务、或返回明确 lock/queue/busy 错误
- 不允许数据库损坏、后续普通 parse 失败或永久 pending
CONCURRENCY-002 并发 scan 同一目录¶
执行方式:
- 启动两个独立 shell,同时执行同一条命令。
命令:
mineru scan "$MINERU_E2E_FIXTURE_DIR" --wait 30 --json
mineru scan "$MINERU_E2E_FIXTURE_DIR" --wait 30 --json
预期:
- 两个进程均不出现 Python traceback
- 两条命令 exit code = 0 或其中一条返回明确 busy/lock/queue 错误
- 后续
mineru list scans --json可正常返回
CONCURRENCY-003 并发 server start¶
执行方式:
- 确保 server 已停止。
- 启动两个独立 shell,同时执行
mineru server start。
命令:
预期:
- 至少一个命令 exit code = 0
- 另一个命令 exit code = 0 且输出 already running,或 exit code != 0 且输出可读的 socket/busy/started by another process 错误
- 最终
mineru server status --json表示只有一个可用 server - 不包含 Python traceback
CONFIG-010 配置持久化¶
命令:
mineru config set parse_server.local.managed_tier standard
mineru server restart
mineru config get parse_server.local.managed_tier --json
mineru config unset parse_server.local.managed_tier
预期:
- 四条 exit code = 0
- restart 后 get JSON 仍体现
standard,并且 source 应体现 override 或等价覆盖来源 - unset 后恢复默认配置来源
- 不包含 Python traceback
CONFIG-011 rule hit_count 与 scan 影响¶
命令:
mineru config exclude-rules add "*/unsupported.bin" --priority 100 --json
mineru scan "$MINERU_E2E_FIXTURE_DIR" --wait 30 --json
mineru config exclude-rules list --json
mineru config exclude-rules remove <rule_id>
预期:
- 四条 exit code = 0
- scan JSON 中 excluded 或 unsupported 计数符合 exclude 语义
- list JSON 中该 rule 的 hit_count 应增加,或当前实现明确不统计 scan hit_count
- remove 后规则不再出现在 list 中
CLEANUP-009 cleanup deleted-files 真实效果¶
前置: 通过 mineru forget "$MINERU_E2E_FIXTURE_DIR/sample-copy.pdf" --no-dry-run 或其它 CLI 操作制造可清理记录。
命令:
预期:
- 两条 exit code = 0
- cleanup JSON 可直接解析
- list files 中不再包含已清理的 deleted 记录,或 cleanup JSON 明确 deleted_files=0
- 不包含 Python traceback
CLEANUP-010 cleanup orphan-docs 真实效果¶
前置: 通过 forget 所有关联文件制造 orphan doc;如果无法只通过 CLI 稳定制造,标记 BLOCKED。
命令:
预期:
- 两条 exit code = 0
- cleanup JSON 可直接解析
- orphan doc 不再出现在 list docs 中,或 cleanup JSON 明确 orphan_docs=0
- parsed 输出目录不应再被 read/parse 错误引用
- 不包含 Python traceback
CLEANUP-011 cleanup temp 新旧文件边界¶
前置: 测试环境预置 doclib temp 目录中的过期文件和未过期文件;如果无法只通过 CLI 稳定制造,标记 BLOCKED。
命令:
预期:
- exit code = 0
- stdout 为可直接解析的 JSON
- 过期 temp 文件被清理
- 未过期 temp 文件不被清理
- 不包含 Python traceback
SERVER-012 error summary 与 recent logs¶
命令:
mineru parse "$MINERU_E2E_FIXTURE_DIR/corrupted.pdf" --tier flash --wait 20 --json
mineru server status --json
预期:
- 第一条按 FILETYPE-002 损坏 PDF 分支判定
- 第二条 exit code = 0,stdout 为可直接解析的 JSON
- status JSON 中
app_logs应来自MINERU_DOCLIB_LOG_APP_PATH,或由MINERU_DOCLIB_LOG_DIR派生的 app log,最多返回最后 25 条 - status JSON 中
access_logs、stderr_logs、stdout_logs应分别来自对应日志文件,最多返回最后 10 条 recent_logs保留为兼容字段,内容应等同于最后 25 条 app log- 如果错误被记录,error_summary 中应出现 parse/file 错误计数
- 如果当前实现不记录该错误,记录为 fail/issue,不作为 BLOCKED
17. 停止 server¶
SERVER-010 停止 server¶
命令:
预期:
- stop exit code = 0
- status exit code = 0
- status 输出
Server is not running或等价信息
SERVER-011 启动失败时保留子进程 stderr¶
执行顺序:
- 本用例必须作为整套 E2E 的最后一个测试执行。
- 本用例会故意制造 server 启动失败,执行后无需恢复测试 server。
执行方式:
- 人工制造一个不会成功建立任何 local transport 的 server 启动环境。可选方式:
- 设置
MINERU_DOCLIB_UDS_ENABLED=false且MINERU_DOCLIB_TCP_ENABLED=false。 - 或显式设置
MINERU_DOCLIB_UDS_ENABLED=true,并把MINERU_DOCLIB_UDS_PATH指向一个父目录不存在且不可创建的位置。 - 只允许通过环境变量制造失败,不直接修改数据库或内部状态。
命令:
预期:
- exit code != 0
- 输出包含
See log:或等价日志路径提示 - 日志路径应为
MINERU_DOCLIB_LOG_APP_PATH/MINERU_DOCLIB_LOG_STDERR_PATH指向的文件,或由测试 HOME 下logs/派生的 mineru log - 日志文件中能看到 server 子进程 stderr 或异常信息
- stdout/stderr 不只给出空泛的启动失败
18. 补充覆盖执行套件¶
本章节用于补足阶段性执行中容易漏跑的场景。执行 Agent 在完成核心 smoke 与新契约回归后,必须按以下批次继续执行,除非对应前置条件无法满足并明确标记 BLOCKED。
COVERAGE-001 help 与入口补充¶
必跑 case:
- CLI-001 顶层 help
- CLI-002 子命令 help
- CLI-003 不存在旧命令
预期:
- 所有 help 类命令输出稳定、可读
- 顶层 help 不出现
mineru-kit - 旧命令入口保持不可用
COVERAGE-002 server 生命周期补充¶
必跑 case:
- SERVER-003 查询运行状态
- SERVER-005 重复启动 server
- SERVER-006 restart server
- SERVER-007 stop 后依赖 server 的命令报错可读
- SERVER-009 环境变量路径生效
- SERVER-013 endpoint discovery 文件写入
- SERVER-014 TCP-only fallback
- SERVER-015 endpoint stale 清理
- SERVER-016 endpoint server identity 校验
- SERVER-017 version 1 endpoint 升级迁移
- SERVER-018 doclib home ownership lock
- SERVER-012 error summary 与 recent logs
- SERVER-010 停止 server
执行要求:
- SERVER-011 必须仍作为整套测试最后一个 case 执行,不放入本批次中间。
- stop/restart 或独立
MINERU_HOMEtransport 测试后必须恢复主测试 server,避免影响后续批次。
COVERAGE-003 config 普通文本与错误分支补充¶
必跑 case:
- CONFIG-001 查看配置
- CONFIG-003 设置和读取配置
- CONFIG-003B managed tier 模型未准备时拒绝配置
- CONFIG-003C managed mode 模型未准备时拒绝启用
- CONFIG-003D 模型准备后允许启用 managed mode
- CONFIG-004 unset 配置
- CONFIG-005 exclude-rules
- CONFIG-006 旧 exclude 命令不可用
- CONFIG-007 parsing-rules
- CONFIG-009 不存在的配置 key
预期:
- 普通文本输出可读且不包含 traceback
- JSON 分支遵守 JSON error 契约
- add/list/remove 后配置状态一致
COVERAGE-004 watch 普通文本、重复与 removable 补充¶
必跑 case:
- WATCH-001 添加 watch
- WATCH-001A 重复添加 watch
- WATCH-002 列出 watch
- WATCH-004 watch rescan
- WATCH-004B watch 默认使用 local flash
- WATCH-006 删除不存在的 watch
- WATCH-007 添加不存在目录
- WATCH-009 removable watch
- WATCH-010 removable watch unreachable 行为
执行要求:
- WATCH-010 如果平台无法稳定制造路径不可访问,可标记 BLOCKED,但必须说明原因。
- watch add/remove 需要保持清理,避免污染后续 list/watch-id 用例。
COVERAGE-005 scan 边界补充¶
必跑 case:
- SCAN-003 扫描不存在路径
- SCAN-004 扫描空目录
- SCAN-005 扫描不支持文件类型
预期:
- 错误分支清晰,不包含 traceback
- JSON 模式下业务错误输出 JSON error
- 空目录和不支持类型的行为符合用例分支说明
COVERAGE-006 parse 边界、续读、cache 与 remote 组合补充¶
必跑 case:
- PARSE-001 文件不存在
- PARSE-002 显式 flash parse
- PARSE-004 cache hit 行为
- PARSE-005 no-wait 行为
- PARSE-006 force 行为
- PARSE-006A force 默认输出不打印过程 status
- PARSE-006B verbose 输出允许过程 status
- PARSE-007 默认 tier 行为
- PARSE-007A PDF local basic tier
- PARSE-007B PDF local standard tier
- PARSE-007C PDF local advanced tier
- PARSE-007A1 PDF local basic tier(full stack)
- PARSE-007B1 PDF local standard tier(full stack)
- PARSE-007C1 PDF local advanced tier(full stack)
- PARSE-007D 旧 tier 名称不可用
- PARSE-008 输出到文件
- PARSE-010 limit 截断与 next_request
- PARSE-011 after 续读
- PARSE-012 no-marker
- PARSE-013 remote 不接受 flash tier
- PARSE-013A remote 默认 tier
- PARSE-013A1 PDF remote standard tier
- PARSE-013B remote no-wait
- PARSE-013C remote force
- PARSE-013D remote output
- PARSE-013E remote 与 local cache 隔离
- PARSE-013F remote 配置规则
- PARSE-013G tier 与文件类型约束
- PARSE-015 JSON 输出纯净性
- PARSE-016 page range 边界
执行要求:
- remote 路由必须通过
show parse --json的privacy、via、tier验证,不能从 parse JSON 中推断。 - 显式 quality tier 的 remote 请求在 remote 不可用时允许同 tier local fallback;未指定 tier 且 remote 无
standard或basic时应返回quality_tier_unavailable,不得隐式选择advanced。 - remote/local fallback 不得改变 tier,也不得降级到
flash。 - PARSE-013A1 是 remote standard 硬性测试;remote 不可用或不支持 standard 均记录为失败,不能静默 fallback 到 local 或其它 tier。
- PARSE-007A1、PARSE-007B1、PARSE-007C1 是
fullstack 硬性测试;任何一项不得因 full runtime、模型或硬件不可用标记为 BLOCKED。 - full profile 完成后必须恢复
MINERU_MODEL_SMALL_BACKEND=onnx与MINERU_MODEL_VLM_ENGINE=llama-cpp并重启 server,避免影响后续 case。 - force/cache/no-wait 用例必须记录 parse id/status 是否符合预期。
COVERAGE-007 read 边界、续读、image 与 context 补充¶
必跑 case:
- READ-001 读取 page locator
- READ-002A 无 tier locator 读取最高缓存
- READ-003 read context
- READ-004 invalid locator
- READ-005 输出到文件
- READ-007 image 格式
- READ-008 image 输出到文件
- READ-009 limit 截断与 next_request
- READ-010 使用 next_request 续读
- READ-011 no-marker
- READ-012 非法 format
- READ-013 JSON 输出纯净性
- READ-014 locator 粒度边界
- READ-015 跨页 context
执行要求:
- 如果无法从解析结果获得 block/char locator,READ-014 中对应子项可标记 BLOCKED,但 page 越界子项仍必须执行。
- image 不支持时必须按 JSON error 或普通可读错误判定,不得 traceback。
COVERAGE-008 search/list/show 过滤、分页与不存在资源补充¶
必跑 case:
- SEARCH-002 find JSON
- SEARCH-004 search tier filter
- SEARCH-005 search min-tier
- SEARCH-006 find ext filter
- SEARCH-007 find limit 和 offset 边界
- SEARCH-008 search type filter
- SEARCH-009 search offset
- SEARCH-010 search 无结果
- SEARCH-011 find 无结果
- SEARCH-012 JSON 输出纯净性
- SEARCH-013 find offset 契约
- LIST-001A list files filters
- LIST-002A list docs offset
- LIST-003A list parses filters
- LIST-004A list scans filters
- LIST-005 watch-id filters
- LIST-006 JSON 输出纯净性
- LIST-007 list docs file-type filter
- SHOW-001A show file 不支持 sha256
- SHOW-005 show 不存在资源
- SHOW-006 JSON 输出纯净性
执行要求:
show doc必须使用完整 sha256,不使用 short_id。show file必须使用 file path;sha256 查询必须使用show doc。- 所有 JSON 输出必须可直接
json.loads。
COVERAGE-009 invalidate 与 forget 补充¶
必跑 case:
- INVALIDATE-001 invalidate flash
- INVALIDATE-001A invalidate all tiers
- INVALIDATE-001B invalidate JSON 支持性
- INVALIDATE-001C invalidate 不存在文件
- INVALIDATE-002 invalidate 后重新 parse
- FORGET-001 默认 dry-run
- FORGET-002 实际 forget
- FORGET-003 forget JSON
- FORGET-004 forget 目录 dry-run
- FORGET-005 forget 目录 execute
- FORGET-006 forget 不存在路径
- FORGET-007 JSON 输出纯净性
执行要求:
- invalidate/forget 不得删除源文件。
- 实际 forget 后必须验证重新 scan/parse 可重新发现。
COVERAGE-010 cleanup 真实副作用与边界补充¶
必跑 case:
- CLEANUP-002 cleanup deleted-files execute
- CLEANUP-005 cleanup deleted-files execute JSON
- CLEANUP-006 cleanup orphan-docs execute
- CLEANUP-007 cleanup temp 边界参数
- CLEANUP-008 JSON 输出纯净性
- CLEANUP-009 cleanup deleted-files 真实效果
- CLEANUP-010 cleanup orphan-docs 真实效果
- CLEANUP-011 cleanup temp 新旧文件边界
执行要求:
--no-dry-run用例执行前必须先制造可清理数据。- 清理后必须通过 list/show/read/parse 复核真实效果。
COVERAGE-011 文件类型、路径与 output 边界补充¶
必跑 case:
- FILETYPE-001 可解析的非 PDF/图片格式
- FILETYPE-001A 图片输入
- FILETYPE-002 损坏、空、不可读文件中尚未执行的 empty/no-read 子项
- FILETYPE-003 非 PDF 格式不接受 page_range
- FILETYPE-004 非 PDF/图片格式 tier 约束
- FILETYPE-005 HTML source_context 资源解析
- PATH-001 路径字符边界
- PATH-002 相对路径和 home 路径中相对路径、show file 同源子项
- OUTPUT-002 read image output 后缀边界
执行要求:
- docx/pptx/xlsx/doc/ppt/xls/rtf/ofd/epub/html/odt/ods/odp/csv/tsv 输入为全量 E2E 必测项,不支持时记录为失败。
- md/txt 输入必须返回
parse_not_required,不视为可解析格式。 - image 输入如果当前安装不支持,按预期失败分支判定。
- symlink 或 no-read 权限场景无法稳定制造时,相关子项可 BLOCKED,但必须说明平台限制。
COVERAGE-012 并发补充¶
必跑 case:
- CONCURRENCY-001 并发 parse force
- CONCURRENCY-002 并发 scan 同一目录
- CONCURRENCY-003 并发 server start
执行要求:
- 并发命令只能调用
mineru,不得直接操作数据库。 - 允许一个命令返回 busy/lock/queue 类明确错误,但不得出现 traceback 或损坏后续 server 状态。
COVERAGE-013 配置持久化与规则影响补充¶
必跑 case:
- CONFIG-010 配置持久化
- CONFIG-011 rule hit_count 与 scan 影响
预期:
- server restart 后配置仍可读取
- rule hit_count 或等价统计在 scan 后体现规则被使用
COVERAGE-014 telemetry 补充¶
必跑 case:
- TELEMETRY-001 telemetry help
- TELEMETRY-002 status JSON 结构
- TELEMETRY-003 preview JSON 结构
- TELEMETRY-004 enable / disable 与 installation_id 稳定性
- TELEMETRY-005 disabled 时不新增聚合
- TELEMETRY-006 unset 或 disabled 时 flush 不外发
- TELEMETRY-007 enabled 时 preview 可观察业务聚合
- TELEMETRY-008 enabled flush 行为
- TELEMETRY-010 preview 隐私边界
条件必跑 case:
- TELEMETRY-009 首次交互式 prompt:仅在执行 Agent 能使用真实交互式终端时必跑;否则标记 BLOCKED,并说明执行环境不支持交互输入。
执行要求:
- telemetry E2E 只能通过
mineru telemetry ...和其它mineru业务命令观察结果,不得直接读取 SQLite 或调用内部 API。 - 外部 telemetry endpoint 不可用时,flush 用例按失败/保留待上报数据分支判定,不应因此整体失败。
- 所有 preview 隐私边界检查必须确认不包含路径、文件名、query、snippet、正文、traceback 或 API key。
19. 最终报告格式¶
执行 Agent 最终必须按以下格式汇总:
Summary:
- total: N
- passed: N
- failed: N
- blocked: N
Failures:
1. [case id] command
expected:
actual exit code:
actual stdout:
actual stderr:
analysis:
Blocked:
1. [case id] reason
Environment:
- mineru version: <如果 help/status 输出能看到则填写,否则 unknown>
- fixture dir: ...
- quality tier available: basic/standard/advanced
- remote Standard available: yes
- pdf fixture source: ...
PDF 页码语法验收¶
以下用例使用已知 10 页的 PDF;完整语义见 PDF 页码范围规范。
| 用例 | 输入 --pages |
预期 |
|---|---|---|
| PAGE-RANGE-001 | 1-3,7,r2-r1 |
实际范围 1-3,7,9-10;原始 page_idx 为 0,1,2,6,8,9 |
| PAGE-RANGE-002 | 3,1-3,2 |
合并为 1-3;不重排、不重复页面 |
| PAGE-RANGE-003 | r1 |
第 10 页 |
| PAGE-RANGE-004 | 8-15 |
取有效交集 8-10 |
| PAGE-RANGE-005 | 20 |
page_range_invalid,不回退到全文 |
| PAGE-RANGE-006 | 5-3、r1-r5、8-r5 |
page_range_invalid |
| PAGE-RANGE-007 | 1~5、-1、-5~-1 |
旧语法统一拒绝 |
| PAGE-RANGE-008 | all |
全部页面;直接 Python/API/Gradio 的留空也选择全部 |
| PAGE-RANGE-009 | 1,,3、5-、r0、1,3 |
page_range_invalid |
对更长文档另行验证:mineru parse 不传页码仍首次处理前 10 页,续读命令使用 11-20。
重复请求应命中新格式缓存;覆盖状态、新缓存文件名、API 页数统计均使用同一实际页面集合。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 mi/MinerU