Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
fix: update page range syntax from '~' to '-' across documentation and codebase
myhlolidcc69e4e9bc4
diff --git a/README.md b/README.mdindex cb080265..e4a2ef0d 100644--- a/README.md+++ b/README.md@@ -107,7 +107,7 @@ Then answer from `content.content`. If `next_request` exists and the question ne### Continue progressively```bash-mineru parse "book.pdf" --pages 1~10 --limit 12000 --json+mineru parse "book.pdf" --pages 1-10 --limit 12000 --jsonmineru read "doc:ab12cd3/tier:standard/page:11" --limit 12000 --json```@@ -498,10 +498,12 @@ Use JSON when you need structured status, tier, content, and continuation:mineru parse "report.pdf" --json```-For a specific page range:+PDF page selection is shared across CLI, Doclib, API, Gradio and Python. See the [page-range contract and breaking upgrade instructions](docs/next/page-ranges.md). The old `~` and negative page-number syntax is no longer supported.++For a specific page range (1-based, inclusive; `r1` is the last page, `all` selects every page):```bash-mineru parse "report.pdf" --pages 1~10+mineru parse "report.pdf" --pages 1-10mineru parse "report.pdf" --pages all```@@ -532,7 +534,7 @@ mineru parse "report.pdf" --output ./report.mdRules:- Quote paths with spaces.-- For paged documents, the default active read range is the first page window, usually `1~10`; continue with the returned marker or `next_request` instead of reading the whole document by default.+- For paged documents, the default active read range is the first page window, usually `1-10`; continue with the returned marker or `next_request` instead of reading the whole document by default.- Use the default tier unless the user has a quality/speed/privacy preference.- Use `--pages all` only when the user asks for the whole document or the document is known to be small enough.- Prefer `--limit` and continuation for long documents.@@ -549,7 +551,7 @@ MinerU output may include a command to continue reading:or:```text-<!-- Next: mineru parse report.pdf --pages 11~20 -->+<!-- Next: mineru parse report.pdf --pages 11-20 -->```Run the suggested command exactly unless the user asks for a different page, block, format, or limit.diff --git a/docs/en/usage/cli_tools.md b/docs/en/usage/cli_tools.mdindex 39af2a9a..180cf215 100644--- a/docs/en/usage/cli_tools.md+++ b/docs/en/usage/cli_tools.md@@ -73,3 +73,13 @@ mineru-kit vlm-server --engine auto --port 30000- `MINERU_INTRA_OP_NUM_THREADS` / `MINERU_INTER_OP_NUM_THREADS`: ONNX operator thread settings.Prefer each command's `--help` output and [model source documentation](./model_source.md) for current defaults.++## PDF page selection++Use `--pages "1-5,8,r3-r1"`: page numbers start at 1, ranges include both endpoints,+and `r1` means the last page. Use `all` for every page. Results are sorted and deduplicated;+partially out-of-bounds ranges select their valid intersection. Reversed or empty selections+fail with `page_range_invalid`. Without `--pages`, `mineru parse` starts with the first 10 pages;+`mineru-kit parse`, Python and Gradio select all pages. The old `~` and negative-number syntax+is no longer accepted. Upgrade clients and servers together and rebuild old Doclib caches+in a fresh data directory. See the [shared page-range contract](../../next/page-ranges.md).diff --git a/docs/en/usage/quick_usage.md b/docs/en/usage/quick_usage.mdindex c7375be3..997ec2e4 100644--- a/docs/en/usage/quick_usage.md+++ b/docs/en/usage/quick_usage.md@@ -106,3 +106,13 @@ model:```See [Model Source Documentation](./model_source.md) for model download and local-source details.++## PDF page selection++Use `--pages "1-5,8,r3-r1"`: page numbers start at 1, ranges include both endpoints,+and `r1` means the last page. Use `all` for every page. Results are sorted and deduplicated;+partially out-of-bounds ranges select their valid intersection. Reversed or empty selections+fail with `page_range_invalid`. Without `--pages`, `mineru parse` starts with the first 10 pages;+`mineru-kit parse`, Python and Gradio select all pages. The old `~` and negative-number syntax+is no longer accepted. Upgrade clients and servers together and rebuild old Doclib caches+in a fresh data directory. See the [shared page-range contract](../../next/page-ranges.md).diff --git a/docs/next/README.md b/docs/next/README.mdindex 12581360..83dd91b3 100644--- a/docs/next/README.md+++ b/docs/next/README.md@@ -1,5 +1,7 @@# Next MinerU 文档体系+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。+状态: Implemented读者: 项目核心开发者、SDK/API 设计参与者、需要理解下一代能力边界的外部开发者范围: 组织下一阶段 MinerU 的产品方向、系统架构、公开接口和关键内部规范diff --git a/docs/next/api/parse-jobs.md b/docs/next/api/parse-jobs.mdindex 940e27e4..2cc11a01 100644--- a/docs/next/api/parse-jobs.md+++ b/docs/next/api/parse-jobs.md@@ -1,5 +1,7 @@# Parse Jobs+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: API 使用者、服务端开发者、SDK 开发者范围: 解析任务创建、查询和轮询@@ -34,7 +36,7 @@ Job 状态:"type": "file_id","file_id": "file-01HXYZ123ABCDEF"},- "page_range": "1~10"+ "page_range": "1-10"}],"tier": null,@@ -125,7 +127,7 @@ Local Parse Server 的 source 策略由启动参数决定:| 字段 | 类型 | 默认 | 说明 ||------|------|------|------|-| `page_range` | string | `null` | PDF 页码范围。省略或传 `null` 表示解析整个文件;图片及其他非 PDF 输入只允许省略或传 `null`。推荐 `~` 分隔,如 `1~10`、`1,3,5~7`、`-5~-1`。 |+| `page_range` | string | `null` | PDF 页码范围。省略或传 `null` 表示解析整个文件;图片及其他非 PDF 输入只允许省略或传 `null`。使用 `-` 分隔,如 `1-10`、`1,3,5-7`、`r5-r1`。 |OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定,客户端不能通过文件级参数单独关闭或开启。@@ -165,7 +167,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定{"file_id": "file-01HXYZ123ABCDEF","name": "report.pdf",- "page_range": "1~12",+ "page_range": "1-12","status": "queued"}],@@ -213,7 +215,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定{"file_id": "file-01HXYZ123ABCDEF","name": "report.pdf",- "page_range": "1~12",+ "page_range": "1-12","status": "completed","parse": {"model_used": "MinerU2.5-Pro-2605-1.2B",@@ -245,7 +247,7 @@ OCR 策略和图片分析能力由 `tier` 与服务端实际引擎自动决定|------|------|------|| `file_id` | string 或 null | 输入 File ID。`local` source 可以为 `null`。 || `name` | string | 文件显示名。 |-| `page_range` | string | 服务端规范化后的实际解析页码范围。请求未指定时为 `1~{total}`;请求指定时,服务端先按文件总页数展开负数页码,再去重并合并连续页码区间。例如 `1,2,3,-1,-1` 在 10 页文件中规范化为 `1~3,10`。 |+| `page_range` | string | 服务端规范化后的实际解析页码范围。请求未指定时为 `1-{total}`;请求指定时,服务端先按文件总页数展开倒数页码 `rN`,再去重并合并连续页码区间。例如 `1,2,3,r1,r1` 在 10 页文件中规范化为 `1-3,10`。 || `status` | string | 文件级状态。 || `parse.model_used` | string | 实际模型 ID。仅当该文件 `status="completed"` 时出现。 || `parse.duration_ms` | integer | 单文件从开始解析到结束的耗时,不包含排队时间。仅当该文件 `status="completed"` 时出现。 |diff --git a/docs/next/architecture.md b/docs/next/architecture.mdindex 15a02fe0..3c13af0b 100644--- a/docs/next/architecture.md+++ b/docs/next/architecture.md@@ -154,7 +154,7 @@ metadata 更新规则:入库阶段写基础 metadata;解析完成后,只|------|------|| `sha256` | 指向文档内容 || `tier` | 实体 tier:`flash` / `basic` / `standard` / `advanced`;未指定 tier 应在入队前或执行前解析为实体 tier |-| `page_range` | 正值页码范围字符串,如 `1~5,46~50` |+| `page_range` | 正值页码范围字符串,如 `1-5,46-50` || `status` | `pending` / `parsing` / `done` / `failed` / `superseded` || `priority` | Agent 同步请求高于 watch 后台任务 || `privacy` | 用户请求偏好:`local` / `remote` |@@ -314,16 +314,16 @@ ParseWorker 按 `tier`、`privacy` 和 parse-server 健康状态路由:ab/ab3f...7e2d/flash/- 1~5_1710000000000.json- 98~102_1710000123000.json+ 1-5_1710000000000.json+ 98-102_1710000123000.jsonbasic/- 1~10_1710001234000.json- 11~20_1710002234000.json+ 1-10_1710001234000.json+ 11-20_1710002234000.jsonimages/ # 仅在解析结果包含必要 sidecar 时存在standard/- 1~20_1710003234000.json+ 1-20_1710003234000.jsonadvanced/- 1~20_1710004234000.json+ 1-20_1710004234000.json```每个 JSON 文件表示一次解析批次,文件名由页码范围和完成时间组成。每个 tier 独立目录,互不覆盖。remote 解析完成后也写入同一结构,供 CLI、SDK、搜索和缓存统一读取。diff --git a/docs/next/cli/mineru-e2e-test-cases.md b/docs/next/cli/mineru-e2e-test-cases.mdindex b6996879..e3304ec5 100644--- a/docs/next/cli/mineru-e2e-test-cases.md+++ b/docs/next/cli/mineru-e2e-test-cases.md@@ -815,7 +815,7 @@ mineru search "mineru-e2e-query-that-should-not-exist" --limit 1```bashmineru telemetry enable --json-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 flash --pages 1-1 --wait 60 --jsonmineru search "mineru-e2e-query-that-should-not-exist" --limit 1 --jsonmineru telemetry preview```@@ -1072,7 +1072,7 @@ mineru config parsing-rules list命令:```bash-mineru config parsing-rules add "*/mineru-e2e-remove/*" --tier flash --pages 1~1 --name e2e-remove-rule --json+mineru config parsing-rules add "*/mineru-e2e-remove/*" --tier flash --pages 1-1 --name e2e-remove-rule --jsonmineru config parsing-rules list --jsonmineru config parsing-rules remove <rule_id>mineru config parsing-rules list --json@@ -1086,7 +1086,7 @@ mineru config parsing-rules list --json- 四条 exit code = 0- add/list JSON 均可直接解析-- remove 前 list 中包含 pattern、`flash`、`1~1`+- remove 前 list 中包含 pattern、`flash`、`1-1`- remove 输出包含 `removed`、`Parsing rule` 或等价成功信息- remove 后 list 中不再包含该 rule id@@ -1457,7 +1457,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf"命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60```预期:@@ -1471,7 +1471,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-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 flash --pages 1-1 --wait 60 --json```预期:@@ -1490,7 +1490,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai重复执行:```bash-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 flash --pages 1-1 --wait 60 --json```预期:@@ -1505,7 +1505,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --no-wait --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --no-wait --json```预期:@@ -1523,7 +1523,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --no-命令:```bash-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```预期:@@ -1537,7 +1537,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --for命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60```预期:@@ -1553,7 +1553,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --for命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --force --wait 60 --verbose+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --force --wait 60 --verbose```预期:@@ -1574,7 +1574,7 @@ Profile 前置条件: `MINERU_MODEL_STACK=light`,doclib server 及 managed parmineru config set parse_server.local.managed_tier standardmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --pages 1~1 --force --wait 180 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1600,7 +1600,7 @@ mineru show parse <created_parse_id> --jsonmineru config set parse_server.local.managed_tier basicmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1~1 --force --wait 120 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --jsonmineru show parse <created_parse_id> --json```@@ -1627,7 +1627,7 @@ mineru show parse <created_parse_id> --jsonmineru config set parse_server.local.managed_tier standardmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1~1 --force --wait 180 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1654,7 +1654,7 @@ mineru show parse <created_parse_id> --jsonmineru config set parse_server.local.managed_tier standardmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1~1 --force --wait 300 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --jsonmineru show parse <created_parse_id> --json```@@ -1686,7 +1686,7 @@ mineru show parse <created_parse_id> --jsonmineru config set parse_server.local.managed_tier basicmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1~1 --force --wait 120 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier basic --pages 1-1 --force --wait 120 --jsonmineru show parse <created_parse_id> --json```@@ -1713,7 +1713,7 @@ mineru show parse <created_parse_id> --jsonmineru config set parse_server.local.managed_tier standardmineru config set parse_server.local.mode managedmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1~1 --force --wait 180 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1738,7 +1738,7 @@ mineru show parse <created_parse_id> --json```bashmineru server status --json-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1~1 --force --wait 300 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier advanced --pages 1-1 --force --wait 300 --jsonmineru show parse <created_parse_id> --json```@@ -1760,10 +1760,10 @@ mineru show parse <created_parse_id> --json命令:```bash-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+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```预期:@@ -1778,7 +1778,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier pro --pages 1~1命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output.md"+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output "$MINERU_E2E_FIXTURE_DIR/parse-output.md"```预期:@@ -1794,7 +1794,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-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+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```预期:@@ -1815,7 +1815,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --limit 20 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --json```预期:@@ -1834,7 +1834,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令模板:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --after <after_cursor> --limit 30000 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --after <after_cursor> --limit 30000 --json```预期:@@ -1850,7 +1850,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --aft命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --limit 20 --no-marker+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --limit 20 --no-marker```预期:@@ -1864,7 +1864,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --remote --wait 20 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --remote --wait 20 --json```预期分支:@@ -1881,7 +1881,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --rem命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --remote --pages 1~1 --force --wait 180 --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --remote --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1907,7 +1907,7 @@ mineru show parse <created_parse_id> --json命令:```bash-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 standard --remote --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1929,7 +1929,7 @@ mineru show parse <created_parse_id> --json命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1~1 --force --no-wait --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pages 1-1 --force --no-wait --jsonmineru show parse <created_parse_id> --json```@@ -1952,7 +1952,7 @@ mineru show parse <created_parse_id> --json命令:```bash-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 standard --remote --pages 1-1 --force --wait 180 --jsonmineru show parse <created_parse_id> --json```@@ -1980,7 +1980,7 @@ mineru show parse <created_parse_id> --json命令:```bash-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"+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"```预期分支:@@ -2001,9 +2001,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier standard --remote --pag命令:```bash-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+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```预期:@@ -2018,7 +2018,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-mineru config parsing-rules add "*/sample.pdf" --tier standard --remote --pages 1~1 --name e2e-remote-rule --json+mineru config parsing-rules add "*/sample.pdf" --tier standard --remote --pages 1-1 --name e2e-remote-rule --jsonmineru watch add "$MINERU_E2E_FIXTURE_DIR" --label e2e-remote-rule-watch --jsonmineru watch rescan "$MINERU_E2E_FIXTURE_DIR" --wait 60 --jsonmineru list parses --limit 20 --json@@ -2080,7 +2080,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --format json命令:```bash-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```预期:@@ -2891,7 +2891,7 @@ mineru invalidate "$MINERU_E2E_FIXTURE_DIR/not-exist.pdf" --tier flash命令:```bash-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 flash --pages 1-1 --wait 60 --json```预期:@@ -3328,8 +3328,8 @@ mineru find "sample" --limit 1 --offset 1 --json```bashmineru 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+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```预期:@@ -3443,11 +3443,11 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/no-read.pdf" --tier flash --wait 60 --json命令:```bash-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+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```预期:@@ -3502,9 +3502,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.html" --tier flash --wait 60 --json命令:```bash-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+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```预期:@@ -3519,9 +3519,9 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/symlink-sample.pdf" --tier flash --pages 1命令:```bash-mineru parse "sample.pdf" --tier flash --pages 1~1 --wait 60 --json+mineru parse "sample.pdf" --tier flash --pages 1-1 --wait 60 --jsonmineru show file "sample.pdf" --json-mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1~1 --wait 60 --json+mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1-1 --wait 60 --json```预期:@@ -3538,10 +3538,10 @@ mineru parse "~/mineru-e2e-test/sample.pdf" --tier flash --pages 1~1 --wait 60 -命令:```bash-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"+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"```预期:@@ -3558,7 +3558,7 @@ mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wai命令:```bash-mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1~1 --wait 60 --output - --json+mineru parse "$MINERU_E2E_FIXTURE_DIR/sample.pdf" --tier flash --pages 1-1 --wait 60 --output - --jsonmineru read "doc:<short_id>/tier:flash/page:1" --output - --json```@@ -3616,8 +3616,8 @@ mineru read "doc:<short_id>/tier:flash/page:1" --format image --output "$MINERU_命令:```bash-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+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```预期:@@ -4156,3 +4156,22 @@ Environment:- remote Standard available: yes- pdf fixture source: ...```++## PDF 页码语法验收++以下用例使用已知 10 页的 PDF;完整语义见 [PDF 页码范围规范](../page-ranges.md)。++| 用例 | 输入 `--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 页数统计均使用同一实际页面集合。diff --git a/docs/next/cli/mineru-kit-gradio.md b/docs/next/cli/mineru-kit-gradio.mdindex f65b39c6..2777f25c 100644--- a/docs/next/cli/mineru-kit-gradio.md+++ b/docs/next/cli/mineru-kit-gradio.md@@ -1,5 +1,7 @@# mineru-kit gradio+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Implemented`mineru-kit gradio` 提供一个基于 MinerU V1 API 的文档解析界面。它不直接调用旧 `/file_parse` 或 `/tasks` 接口,也不使用 `doclib` 缓存。@@ -51,7 +53,11 @@ mineru-kit gradio \界面一次提交一个文件,支持 `filetypes.PARSEABLE_EXTENSIONS` 中的 PDF、图片、Office/ODF、RTF、HTML、CSV/TSV、EPUB 和 OFD。-页码输入使用 V1 `page_range` 语法,例如 `1~5,8,-1`;留空表示全部页面。只有原始 PDF 支持显式页码范围,其他格式会自动清空并禁用页码控件。+解析 tier 使用原生离散滑块选择,上方即时显示当前档位。滑块按 `flash → basic → standard → advanced` 排列,仅包含服务实际支持的档位。默认优先选择 `standard`,否则选择最高可用档位;仅有一个档位时禁用滑块。上传新文件或清除结果会保留当前选择。++启用 Gradio 事件 API 时,转换事件的 `tier_position` 参数为从 `0` 开始的整数位置,替代原来的 tier 字符串。例如四档齐全时 `3` 对应 `advanced`;仅支持 `basic/standard/advanced` 时 `2` 对应 `advanced`。位置始终按照上述顺序对实际可用档位编号,越界位置会报错。V1 API 的 `tier` 参数仍使用字符串,启动参数不变。++页码输入使用 V1 `page_range` 语法,例如 `1-5,8,r1`;留空表示全部页面。只有原始 PDF 支持显式页码范围,其他格式会自动清空并禁用页码控件。Gradio 首先发现 `/v1/health` 和 `/v1/tiers`,然后通过 `MinerUApiParser` 上传文件、创建 `/v1/parse/jobs`、轮询任务并下载 ZIP 结果。解析结果保存为严格 Middle JSON 2.0。diff --git a/docs/next/cli/mineru-kit-parse.md b/docs/next/cli/mineru-kit-parse.mdindex 5483f720..bf59a78e 100644--- a/docs/next/cli/mineru-kit-parse.md+++ b/docs/next/cli/mineru-kit-parse.md@@ -1,5 +1,7 @@# mineru-kit parse+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: 批处理开发者、解析内核开发者范围: `mineru-kit parse` 的输入、输出、local/remote 规则和命名约定diff --git a/docs/next/cli/mineru-library.md b/docs/next/cli/mineru-library.mdindex 38125888..9fa5b493 100644--- a/docs/next/cli/mineru-library.md+++ b/docs/next/cli/mineru-library.md@@ -125,8 +125,8 @@ JSON 输出为 `FileInfoResponse` 顶层对象,至少包含:```json[- {"tier": "flash", "page_range": "1~20", "status": "done", "done_at": 1730000000},- {"tier": "basic", "page_range": "1~5,18~20", "status": "done", "done_at": 1730000100}+ {"tier": "flash", "page_range": "1-20", "status": "done", "done_at": 1730000000},+ {"tier": "basic", "page_range": "1-5,18-20", "status": "done", "done_at": 1730000100}]```@@ -134,7 +134,7 @@ JSON 输出为 `FileInfoResponse` 顶层对象,至少包含:```json[- {"id": 123, "tier": "standard", "page_range": "6~17", "status": "parsing"}+ {"id": 123, "tier": "standard", "page_range": "6-17", "status": "parsing"}]```diff --git a/docs/next/cli/mineru-parse.md b/docs/next/cli/mineru-parse.mdindex fc5d65f2..3e619f3a 100644--- a/docs/next/cli/mineru-parse.md+++ b/docs/next/cli/mineru-parse.md@@ -1,5 +1,7 @@# mineru parse+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: Agent skill 作者、CLI 使用者、核心开发者范围: `mineru parse` 的默认行为、参数、隐私、tier、输出、等待和缓存@@ -100,7 +102,7 @@ PDF/image 的默认选择策略通过当前目标 parse-server 的能力发现分页文档使用物理页码:```text-<!-- Next: mineru parse report.pdf --pages 11~20 -->+<!-- Next: mineru parse report.pdf --pages 11-20 -->```非分页文档当前也使用 `--after` cursor 继续读取:diff --git a/docs/next/config.md b/docs/next/config.mdindex 29a6a495..7261869b 100644--- a/docs/next/config.md+++ b/docs/next/config.md@@ -1,5 +1,7 @@# 配置体系+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。+状态: Draft读者: 想了解 doclib / mineru 配置的用户、实现配置能力的核心开发者范围: 本地配置、远端配置、解析参数、环境变量和优先级规则diff --git a/docs/next/decisions/0003-parse-request-wait-batches.md b/docs/next/decisions/0003-parse-request-wait-batches.mdindex cbe10d0f..6495de48 100644--- a/docs/next/decisions/0003-parse-request-wait-batches.md+++ b/docs/next/decisions/0003-parse-request-wait-batches.md@@ -27,7 +27,7 @@ parse 请求返回本次请求需要等待的 batch 集合,而不是单个 `pa{"sha256": "...","tier": "basic",- "page_range": "1~10",+ "page_range": "1-10","status": "pending","wait_parse_ids": [12, 13],"created_parse_ids": [13],@@ -69,8 +69,8 @@ GET /parses?ids=12,13```json{"parses": [- {"id": 12, "sha256": "...", "tier": "basic", "page_range": "1~5", "status": "done"},- {"id": 13, "sha256": "...", "tier": "basic", "page_range": "6~10", "status": "parsing"}+ {"id": 12, "sha256": "...", "tier": "basic", "page_range": "1-5", "status": "done"},+ {"id": 13, "sha256": "...", "tier": "basic", "page_range": "6-10", "status": "parsing"}]}```diff --git a/docs/next/decisions/0004-doclib-http-api-resources.md b/docs/next/decisions/0004-doclib-http-api-resources.mdindex 9c99412e..92310dd2 100644--- a/docs/next/decisions/0004-doclib-http-api-resources.md+++ b/docs/next/decisions/0004-doclib-http-api-resources.md@@ -51,7 +51,7 @@ POST /invalidate{"sha256": "...","tier": "basic",- "page_range": "1~10",+ "page_range": "1-10","status": "pending","cache_hit": false,"wait_parse_ids": [12, 13],@@ -66,7 +66,7 @@ POST /invalidateGET /parses?ids=12,13GET /parses?doc_ref=...&tier=basicGET /parses?doc_ref=...&tier=basic&status=pending-GET /parses?doc_ref=...&tier=basic&page_range=1~10+GET /parses?doc_ref=...&tier=basic&page_range=1-10````ids` 查询用于 CLI wait 等精确请求状态判断。`doc_ref + tier + page_range` 查询用于计算页覆盖状态(过滤参数为 `doc_ref`,可接受 sha256 或 path 等文档引用,与 [ADR-0003](0003-parse-request-wait-batches.md) 一致)。@@ -93,7 +93,7 @@ GET /docs/{sha256}`GET /docs/{sha256}/content` 从有效 done parse record 的 Middle JSON 中读取并转换内容:```http-GET /docs/{sha256}/content?tier=basic&page_range=1~10&format=markdown+GET /docs/{sha256}/content?tier=basic&page_range=1-10&format=markdown```读取内容不触发解析。缺页时应返回明确错误或 pending 状态,由调用方再决定是否 `POST /parses`。diff --git a/docs/next/decisions/0013-doc-content-progressive-reading.md b/docs/next/decisions/0013-doc-content-progressive-reading.mdindex a9386741..bd2a3879 100644--- a/docs/next/decisions/0013-doc-content-progressive-reading.md+++ b/docs/next/decisions/0013-doc-content-progressive-reading.md@@ -82,8 +82,8 @@ def get_doc_content(HTTP API 使用 GET query,不使用 request body:```http-GET /api/v1/docs/{sha256}/content?tier=basic&page_range=1~10&limit=30000-GET /api/v1/docs/{sha256}/content?tier=basic&page_range=7~10&after=doc:ab12cd3/tier:basic/page:7/block:4&limit=30000+GET /api/v1/docs/{sha256}/content?tier=basic&page_range=1-10&limit=30000+GET /api/v1/docs/{sha256}/content?tier=basic&page_range=7-10&after=doc:ab12cd3/tier:basic/page:7/block:4&limit=30000GET /api/v1/docs/{sha256}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:1/block:42&limit=30000```@@ -92,8 +92,8 @@ GET /api/v1/docs/{sha256}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:1- content 接口的默认 `limit` 是 `30000`。- CLI、HTTP API、SDK 使用同一个默认 `limit`。- export 接口没有 `limit`,也不设计 `limit` 参数。-- 分页文档默认 `page_range=1~10`。-- 分页文档如果显式传 `page_range=all`,Server 规范化为 `1~{page_count}`。+- 分页文档默认 `page_range=1-10`。+- 分页文档如果显式传 `page_range=all`,Server 规范化为 `1-{page_count}`。- 非分页文档可以不传 `page_range`,也可以只传 `after`。`limit` 是 soft limit,单位是渲染后的字符预算。Server 应尽量在自然边界停止,但协议不承诺精确等于 `limit`。@@ -122,7 +122,7 @@ doc:{short_id}/tier:{tier}/page:{page_no}/block:{block_no}/char:{offset}```json{- "page_range": "1~10",+ "page_range": "1-10","after": null,"limit": 30000}@@ -147,7 +147,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21```json{"request_scope": {- "page_range": "21~30",+ "page_range": "21-30","after": "doc:ab12cd3/tier:basic/page:21","limit": 30000}@@ -165,13 +165,13 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21- 非分页文档常规情况下使用 block 级 cursor。- 只有在单页或单 block 过长时,才细化到 block 或 char。-默认 `page_range=1~10` 且未截断:+默认 `page_range=1-10` 且未截断:```json{"content_ranges": [{- "page_range": "1~10",+ "page_range": "1-10","start": "doc:ab12cd3/tier:basic/page:1","end": "doc:ab12cd3/tier:basic/page:10"}@@ -184,18 +184,18 @@ GET /api/v1/docs/{sha}/content?tier=basic&after=doc:ab12cd3/tier:basic/page:21```json{"request_scope": {- "page_range": "1~5,20~25",+ "page_range": "1-5,20-25","after": null,"limit": 30000},"content_ranges": [{- "page_range": "1~5",+ "page_range": "1-5","start": "doc:ab12cd3/tier:basic/page:1","end": "doc:ab12cd3/tier:basic/page:5"},{- "page_range": "20~25",+ "page_range": "20-25","start": "doc:ab12cd3/tier:basic/page:20","end": "doc:ab12cd3/tier:basic/page:25"}@@ -240,7 +240,7 @@ truncated=false => next_request may be null or non-null请求:```http-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-10&limit=30000```响应:@@ -248,20 +248,20 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000```json{"request_scope": {- "page_range": "1~10",+ "page_range": "1-10","after": null,"limit": 30000},"content_ranges": [{- "page_range": "1~10",+ "page_range": "1-10","start": "doc:ab12cd3/tier:basic/page:1","end": "doc:ab12cd3/tier:basic/page:10"}],"truncated": false,"next_request": {- "page_range": "11~20"+ "page_range": "11-20"}}```@@ -273,7 +273,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000```json{"next_request": {- "page_range": "36~38"+ "page_range": "36-38"}}```@@ -292,7 +292,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000请求:```http-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-10&limit=30000```如果 Server 只输出到第 6 页,并在页边缘停止:@@ -301,14 +301,14 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000{"content_ranges": [{- "page_range": "1~6",+ "page_range": "1-6","start": "doc:ab12cd3/tier:basic/page:1","end": "doc:ab12cd3/tier:basic/page:6"}],"truncated": true,"next_request": {- "page_range": "7~10"+ "page_range": "7-10"}}```@@ -322,7 +322,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~10&limit=30000请求:```http-GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000+GET /api/v1/docs/{sha}/content?tier=basic&page_range=7-10&limit=30000```响应:@@ -338,7 +338,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000],"truncated": true,"next_request": {- "page_range": "7~10",+ "page_range": "7-10","after": "doc:ab12cd3/tier:basic/page:7/block:4"}}@@ -357,7 +357,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000],"truncated": true,"next_request": {- "page_range": "7~10",+ "page_range": "7-10","after": "doc:ab12cd3/tier:basic/page:7/block:4/char:32784"}}@@ -372,7 +372,7 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=7~10&limit=30000示例:```http-GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~5,20~25+GET /api/v1/docs/{sha}/content?tier=basic&page_range=1-5,20-25```若文档还有第 26 页之后的内容:@@ -380,18 +380,18 @@ GET /api/v1/docs/{sha}/content?tier=basic&page_range=1~5,20~25```json{"request_scope": {- "page_range": "1~5,20~25",+ "page_range": "1-5,20-25","after": null,"limit": 30000},"truncated": false,"next_request": {- "page_range": "26~35"+ "page_range": "26-35"}}```-`6~19` 不会被自动补读。用户显式跳过的页段不属于 Server 的下一段建议。+`6-19` 不会被自动补读。用户显式跳过的页段不属于 Server 的下一段建议。## 非分页文档@@ -452,13 +452,13 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL分页文档:```html-<!-- Next: mineru parse report.pdf --pages 11~20 -->+<!-- Next: mineru parse report.pdf --pages 11-20 -->```分页文档页内 continuation:```html-<!-- Next: mineru parse report.pdf --pages 7~10 --after doc:ab12cd3/tier:basic/page:7/block:4 -->+<!-- Next: mineru parse report.pdf --pages 7-10 --after doc:ab12cd3/tier:basic/page:7/block:4 -->```非分页文档:@@ -481,15 +481,15 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL### 方案 C: 用 server-side read session 记录已读页-拒绝。它需要状态存储、过期、清理和并发语义。P0 采用无状态请求。默认页改为线性 `1~10` 后,分页文档可以用简单的下一段 `page_range` 推荐避免尾页重复。+拒绝。它需要状态存储、过期、清理和并发语义。P0 采用无状态请求。默认页改为线性 `1-10` 后,分页文档可以用简单的下一段 `page_range` 推荐避免尾页重复。### 方案 D: 分页文档 continuation 总是用 `after`拒绝。分页文档最自然的继续方式是页码范围。常规页边缘截断应简化为 `next_request.page_range`,只有页内 block/char 截断才需要 `after`。-### 方案 E: 继续使用默认 `1~5,-5~-1`+### 方案 E: 继续使用默认 `1-5,r5-r1`-拒绝。头尾采样会导致无状态渐进阅读时容易重复读取尾页,也让 `next_request` 必须携带额外 read state 才能正确推荐后续页。P0 改为默认 `1~10`,使阅读计划线性、可预测。+拒绝。头尾采样会导致无状态渐进阅读时容易重复读取尾页,也让 `next_request` 必须携带额外 read state 才能正确推荐后续页。P0 改为默认 `1-10`,使阅读计划线性、可预测。## 影响@@ -499,7 +499,7 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL- CLI 应根据 `next_request` 渲染下一条命令提示。- CLI 不应反解析 Markdown marker 来决定下一次请求。- export 接口保持不截断,不增加 `limit`。-- 分页文档默认页码范围使用 `1~10`。+- 分页文档默认页码范围使用 `1-10`。- 分页文档只要 `next_request` 非空,就必须包含 `page_range`。## 后续动作@@ -507,14 +507,14 @@ CLI marker 是展示层,不是协议源头。Server 返回 `next_request`,CL1. 更新 doclib Interface、Client、Server 类型和签名。2. 实现 content cursor parser 和 validator。3. 实现 `request_scope` 规范化:- - 默认 `page_range=1~10`。+ - 默认 `page_range=1-10`。- 分页文档只传 `after` 时推导连续 10 页。- 校验 `after` 属于 `page_range` scope。4. 实现 `content_ranges` 和 `next_request` 计算。5. 为 Markdown render 增加 soft limit。6. 更新 CLI parse 输出 marker,使其从 `next_request` 生成。7. 增加测试:- - 默认 `1~10`。+ - 默认 `1-10`。- 未截断时生成下一段 `page_range`。- 页边缘截断时只返回 `next_request.page_range`。- 页内 block/char 截断时返回 `page_range + after`。diff --git a/docs/next/decisions/0014-mineru-read-command.md b/docs/next/decisions/0014-mineru-read-command.mdindex f7f3b75b..bc987af6 100644--- a/docs/next/decisions/0014-mineru-read-command.md+++ b/docs/next/decisions/0014-mineru-read-command.md@@ -181,7 +181,7 @@ parse read 返回示例:"format": "markdown","content": "...","request_scope": {- "page_range": "1~10",+ "page_range": "1-10","after": null,"limit": 30000,"locator": null,@@ -189,14 +189,14 @@ parse read 返回示例:},"content_ranges": [{- "page_range": "1~10",+ "page_range": "1-10","start": "doc:ab12cd3/tier:basic/page:1","end": "doc:ab12cd3/tier:basic/page:10/block:18"}],"truncated": false,"next_request": {- "page_range": "11~20",+ "page_range": "11-20","after": null,"locator": null},diff --git a/docs/next/decisions/0016-mineru-kit-parse-command.md b/docs/next/decisions/0016-mineru-kit-parse-command.mdindex 80b5edac..d4faeaf0 100644--- a/docs/next/decisions/0016-mineru-kit-parse-command.md+++ b/docs/next/decisions/0016-mineru-kit-parse-command.md@@ -65,7 +65,7 @@ mineru-kit parse <input...> -o <output> [flags]其中:-- `--pages` 支持如 `1~5` 或 `all`+- `--pages` 支持如 `1-5` 或 `all`- `--format` 当前只支持 `markdown`、`middle_json`、`zip`- 默认 `--format` 为 `markdown`diff --git a/docs/next/implementation-plan.md b/docs/next/implementation-plan.mdindex 5c466044..daed56b5 100644--- a/docs/next/implementation-plan.md+++ b/docs/next/implementation-plan.md@@ -641,11 +641,11 @@ M1 和 M2 的部分测试任务可以并行,但 `ParseResult.from_dict()`、JS具体步骤:-1. 准备已有 done batch: `page_range=1~5`。-2. 请求 `page_range=1~10`。-3. 期望只创建 `6~10` 的 pending batch。-4. 准备已有 pending batch: `page_range=6~10`。-5. 再请求 `1~10`,期望不重复创建,而是提升 priority。+1. 准备已有 done batch: `page_range=1-5`。+2. 请求 `page_range=1-10`。+3. 期望只创建 `6-10` 的 pending batch。+4. 准备已有 pending batch: `page_range=6-10`。+5. 再请求 `1-10`,期望不重复创建,而是提升 priority。6. 测试 `force=True` 时跳过 done cache,但复用 active batch。7. 测试 `force=True` 只为 active 未覆盖页创建新 parse。8. 测试返回 `wait_parse_ids`、`created_parse_ids`、`reused_parse_ids`。diff --git a/docs/next/open-questions.md b/docs/next/open-questions.mdindex 8dedb289..9f0da61d 100644--- a/docs/next/open-questions.md+++ b/docs/next/open-questions.md@@ -54,7 +54,7 @@| `mineru-kit parse` local/remote | local 支持 `tier/backend` 并校验兼容,PDF/image 二者都不传时默认 `standard`,OFD/EPUB/Office/HTML/CSV 按 ADR-0024/0028 归一,其它 text 不作为解析输入;remote 支持 `--remote`/`--remote-url`/`--api-key`,允许传 `tier`,禁止传 `backend`。 || parsing-rules 默认 tier | parsing-rules 允许不指定 tier;PDF/image 按 `standard` -> `basic` -> `flash` 选择,OFD/EPUB/Office/HTML/CSV 归一为 `flash`,其它 text 只入库和索引;只记录实际 tier。 || Telemetry P0 | P0 必须实现 doclib server telemetry 状态、聚合、flush 和 CLI 管理入口;纯工具无 telemetry 能力。 |-| `mineru parse` 默认页码范围 | 分页文档默认解析和读取 `1~min(page_count,10)`;该默认由 doclib 读取/解析计划负责,CLI 参数层不硬编码默认 `--pages`。 |+| `mineru parse` 默认页码范围 | 分页文档默认解析和读取 `1-min(page_count,10)`;该默认由 doclib 读取/解析计划负责,CLI 参数层不硬编码默认 `--pages`。 || 渐进式阅读协议 | Server 返回结构化 `next_request`;CLI marker 只由 `next_request` 渲染,不作为协议源头,详见 [ADR-0013](decisions/0013-doc-content-progressive-reading.md)。 || 非分页文档增量读取 | 非分页长文档通过 `after` cursor 继续读取;当前不为 `mineru parse` 暴露单独的 `--offset` 参数。 || Doc short id | `docs.short_id` 按 SHA256 7 位前缀起步、冲突递增长度、写入后保持稳定,详见 [ADR-0011](decisions/0011-doclib-doc-short-id.md)。 |diff --git a/docs/next/page-naming.md b/docs/next/page-naming.mdindex 62ef4b83..907e2f57 100644--- a/docs/next/page-naming.md+++ b/docs/next/page-naming.md@@ -1,5 +1,7 @@# Page Naming Convention+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](page-ranges.md)。+状态: Implemented读者: 核心开发者、编程 Agent、SDK/API/CLI 设计参与者、文档作者范围: MinerU Next 中页码、页码范围、页面数组和页数统计的命名约定@@ -21,7 +23,7 @@| 名称 | 含义 | 类型示例 | 说明 ||------|------|----------|------|-| `page_range` | 页码范围字符串 | `str \| None` | 例如 `"1~10"`、`"1,3,5~7"`、`"all"`。是否已经规范化由所在层契约定义。 |+| `page_range` | 页码范围字符串 | `str \| None` | 例如 `"1-10"`、`"1,3,5-7"`、`"all"`。是否已经规范化由所在层契约定义。 || `pages` | 页面对象列表 | `list[PageInfo]` / `list[dict]` | 只用于真实页面结构,例如 `ParseResult.pages`、Middle JSON 顶层 `{"pages": [...]}`。 || `<state>_pages` | 某状态下的页面对象列表 | `done_pages: list[PageInfo]` | 仅当值仍然是 `PageInfo` / page dict 列表时使用。 || `page_idx` | 0-based 页面索引 | `int` | 第一页为 `0`。对应 `PageInfo.page_idx`。 |@@ -45,7 +47,7 @@| 避免写法 | 推荐写法 ||----------|----------|| `pages: str` | `page_range: str` |-| `result.pages == "1~10"` | `result.page_range == "1~10"` |+| `result.pages == "1-10"` | `result.page_range == "1-10"` || `num_pages` | `page_count` 或 `total_page_count` || `total_pages` | `page_count` 或 `total_page_count` || `done_pages: str` | `done_page_range: str` |@@ -69,9 +71,9 @@示例:```python-ParseRequest(page_range="1~10")-ParseInfo(page_range="1~5")-ContentNextRequest(page_range="11~20")+ParseRequest(page_range="1-10")+ParseInfo(page_range="1-5")+ContentNextRequest(page_range="11-20")```### 4.2 `pages`@@ -157,7 +159,7 @@ page_numbers = sorted(parse_page_range_set(page_range))命名时先问这几个问题:-1. 值是不是 `"1~10"` 这样的范围字符串?+1. 值是不是 `"1-10"` 这样的范围字符串?- 是: 用 `page_range`。2. 值是不是 `PageInfo` 或 page dict 的列表?- 是: 用 `pages` 或 `<state>_pages`。diff --git a/docs/next/page-ranges.md b/docs/next/page-ranges.mdnew file mode 100644index 00000000..907a9fc2--- /dev/null+++ b/docs/next/page-ranges.md@@ -0,0 +1,98 @@+# PDF 页码范围规范++状态: Implemented++CLI 的 `--pages`、Python/Doclib/API 的 `page_range` 和 Gradio 页码输入使用同一套语法。+页码表示 PDF 文件内的页面顺序,从 1 开始,不使用正文印刷页码或 PDF page label。+内部 `page_idx` / `page_indices` 仍从 0 开始,抽页后保留原始页索引。++## 输入语法++| 表达式 | 含义 |+|---|---|+| `5` | 第五页 |+| `1-5` | 第一到第五页,包含两端 |+| `1-3,7,10-12` | 多个区间和单页 |+| `all` | 全部页面 |+| `r1` | 最后一页 |+| `r5-r1` | 最后五页 |+| `3-r1` | 第三页到最后一页 |++端点使用 ASCII 正整数(`[1-9][0-9]*`),或小写 `r` 加该正整数。`all` 只能独立使用。+允许首尾、逗号和连字符两侧空白,例如 ` 1 - 3 , r1 `。不接受前导零、正负号、中文分隔符、+大写 `R` / `ALL`、空选项和缺失端点;`1:5` 不是受支持的切片语法。++先以文档总页数求值 `rN`,再检查区间方向;任何倒序区间均报错。+`5-3`、`r1-r5` 无效;五页文档的 `4-r3` 也无效,不能被其他有效选项掩盖。++有效页面取区间与文档的交集,再去重、升序和合并相邻页:++- 十页文档的 `8-15` 得到 `8-10`。+- 十页文档的 `r20-r8` 得到 `1-3`。+- `3,1-3,2` 得到 `1-3`,不会重排或复制页面。+- 整个表达式选不到页面时,例如十页文档的 `20`,返回 `page_range_invalid`。++## 未指定与全部++空字符串、纯空白和接口允许的 `null` 都表示未指定,默认策略由入口选择:++| 入口 | 未指定 PDF 页码时 |+|---|---|+| `mineru parse` / Doclib 解析 | 首次前 10 页,不足 10 页则全部 |+| Doclib 内容读取 | 首次前 10 页;带续读游标时保留现有窗口策略 |+| Doclib 内容导出 | 导出已有缓存内容 |+| Python `parse` / `parse_async` | 全部 |+| V1 Parse Jobs / `MinerUApiParser` | 全部 |+| `mineru-kit parse` / Gradio | 全部 |++显式 `all` 选择全部 PDF 页面;内容读取/导出仍受实际缓存可用性约束。+非 PDF 的解析限制不变:不能显式设置页码(包括 `all`);Gradio 对非 PDF 自动清空并禁用此控件。++## 输入与输出++```bash+mineru parse report.pdf --pages "1-3,7,r2-r1"+mineru parse report.pdf --pages all+mineru-kit parse report.pdf -o result.md --pages "r5-r1"+```++```python+from mineru.parser import parse++result = parse("report.pdf", tier="flash", page_range="1,3,r1")+```++```json+{+ "tier": "flash",+ "files": [{"source": {"type": "file_id", "file_id": "file-example"}, "page_range": "1-3,r1"}],+ "output_formats": ["middle_json"]+}+```++已求值的 API/Doclib 范围、覆盖状态、续读命令、解析记录及新缓存文件名使用正整数连字符格式。+例如十页文档的 `1-3,r1` 输出为 `1-3,10`,`5-5` 输出为 `5`,空覆盖集合输出空字符串。+parsing rules 和排队中的 V1 请求尚未取得总页数时允许保留 `rN` / `all`;实际解析时再求值。++## 错误与实现边界++统一错误码为 `page_range_invalid`,类型为 `invalid_request_error`。Python 抛出+`InvalidRequestError`;CLI 和 Gradio 保留该错误含义。V1 创建任务的语法错误返回 HTTP 400,+`error.param` 定位到 `files.<index>.page_range`。总页数求值错误通过异步任务的文件级错误返回。++共享实现位于 `mineru/parser/page_range.py`,负责语法、求值、格式化和页数统计。缓存内部的空范围+表示空集合,不表示用户输入的“未指定”。总页数未知的缓存内容导出可使用绝对页码或全部缓存,+不能用已有缓存的最大页码推测 `r1`。++## 不兼容升级++本次不支持旧输入 `1~5`、`-1`、`-5~-1`,也不提供旧页码缓存迁移或旧服务端回退。+更新调用方、SDK、Doclib 和 Parse Server,重新创建使用旧语法的 parsing rules。++已有 Doclib 数据可保留备份。升级后使用新的数据目录重新入库、解析:++1. 停止旧 Doclib 实例,在独立配置文件中把 `doclib.data_dir` 配置为新的空目录。+2. 按[配置说明](config.md)同步配置独立 DB/endpoint 路径,以新配置启动 Doclib;客户端使用同一配置。+3. 重新添加 watch / parsing rules,重新扫描或执行 `mineru parse`,生成新格式记录与缓存。++程序不会在此次升级中自动删除旧数据。不要把旧数据库或旧 parsed 目录复制到新实例继续使用。diff --git a/docs/next/sdk/doclib-client.md b/docs/next/sdk/doclib-client.mdindex 5902211f..1ab00d8b 100644--- a/docs/next/sdk/doclib-client.md+++ b/docs/next/sdk/doclib-client.md@@ -1,5 +1,7 @@# Doclib SDK: `DoclibClient`+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: SDK 开发者、`mineru` CLI 开发者、MCP/桌面端集成方范围: 本地 doclib client 的公开能力、方法和错误模型diff --git a/docs/next/sdk/migration.md b/docs/next/sdk/migration.mdindex b141fe78..e7c8b5f6 100644--- a/docs/next/sdk/migration.md+++ b/docs/next/sdk/migration.md@@ -1,5 +1,7 @@# 迁移路径+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: 核心开发者、SDK 开发者范围: 从当前 SDK 代码走向目标公开契约的步骤diff --git a/docs/next/sdk/parser.md b/docs/next/sdk/parser.mdindex c39e042a..cc927fd6 100644--- a/docs/next/sdk/parser.md+++ b/docs/next/sdk/parser.md@@ -1,5 +1,7 @@# Tool SDK: `mineru.parser`+页码表达式、默认范围及不兼容升级要求统一见 [PDF 页码范围规范](../page-ranges.md)。+状态: Draft读者: SDK 开发者、`mineru-kit` 开发者、核心开发者范围: 无状态解析工具层的公开入口、统一 parser 类和目标契约@@ -148,7 +150,7 @@ class DocumentParser:```pythonfrom mineru.parser import parse-result = parse("report.pdf", tier="basic", page_range="1~5")+result = parse("report.pdf", tier="basic", page_range="1-5")print(result.markdown())```@@ -158,7 +160,7 @@ print(result.markdown())from mineru.parser import MinerUParserwith MinerUParser(tier="basic") as parser:- result = parser.parse("report.pdf", page_range="1~10")+ result = parser.parse("report.pdf", page_range="1-10")images = result.images()```diff --git a/docs/next/workflows.md b/docs/next/workflows.mdindex d1433552..9020f725 100644--- a/docs/next/workflows.md+++ b/docs/next/workflows.md@@ -383,7 +383,7 @@ watch -> flash index -> search result -> Agent chooses document -> mineru parse当输出被截断或只解析部分页时,应输出可机器理解的 marker:```text-<!-- mineru:next page_range=6~10 tier=standard -->+<!-- mineru:next page_range=6-10 tier=standard -->```marker 不应依赖自然语言提示。具体 marker 格式可在 CLI 或 Agent 文档中继续细化。@@ -481,16 +481,16 @@ doclib 解析产物按内容和实际使用的 tier 隔离。`parsed/` 目录下ab/ab3f...7e2d/flash/- 1~5_1710000000000.json- 98~102_1710000123000.json+ 1-5_1710000000000.json+ 98-102_1710000123000.jsonbasic/- 1~10_1710001234000.json- 11~20_1710002234000.json+ 1-10_1710001234000.json+ 11-20_1710002234000.jsonimages/ # 可选,仅保存解析产生的必要 sidecarstandard/- 1~20_1710003234000.json+ 1-20_1710003234000.jsonadvanced/- 1~20_1710004234000.json+ 1-20_1710004234000.json```单个 JSON 文件表示一次解析批次,基本形态:@@ -732,8 +732,8 @@ mineru parse report.pdf --tier flash输入:```bash-mineru parse report.pdf --tier basic --pages 1~5-mineru parse report.pdf --tier basic --pages 6~10+mineru parse report.pdf --tier basic --pages 1-5+mineru parse report.pdf --tier basic --pages 6-10```期望:@@ -741,7 +741,7 @@ mineru parse report.pdf --tier basic --pages 6~101. 两次请求可以生成两个 done parse batch。2. `parsed/<sha-prefix>/<sha>/basic/` 下保存两个 JSON 文件。3. 每个 JSON 文件只包含对应页码范围的 `pages`。-4. 后续请求 `--pages 1~10` 可以由已完成批次覆盖,不需要重新解析。+4. 后续请求 `--pages 1-10` 可以由已完成批次覆盖,不需要重新解析。5. compaction 可以将两个批次合并成更少的 parse row 和 JSON 文件。6. 合并时按 `page_idx` 组织页面;同一页如果被重复解析,较新批次覆盖较旧批次。@@ -750,18 +750,18 @@ mineru parse report.pdf --tier basic --pages 6~10输入:```bash-mineru parse report.pdf --tier basic --pages 1~5-mineru parse report.pdf --tier basic --pages 1~5 --force+mineru parse report.pdf --tier basic --pages 1-5+mineru parse report.pdf --tier basic --pages 1-5 --force```期望:1. 第二次请求调用 `POST /parses`,返回 `wait_parse_ids`。2. 旧 done batch 不被删除,也不被标记失效。-3. 如果已有 active parse 覆盖 `1~5`,第二次请求可以复用该 parse,并把 id 放入 `reused_parse_ids`。+3. 如果已有 active parse 覆盖 `1-5`,第二次请求可以复用该 parse,并把 id 放入 `reused_parse_ids`。4. 如果没有 active parse 覆盖,第二次请求创建新 parse,并把 id 放入 `created_parse_ids`。5. CLI wait 查询 `GET /parses?ids=...`,等待所有 `wait_parse_ids` 完成。-6. 如果第二次解析成功,读取 `1~5` 时使用 `done_at` 更新的有效 batch。+6. 如果第二次解析成功,读取 `1-5` 时使用 `done_at` 更新的有效 batch。7. 如果第二次解析失败,第一次解析结果仍然可读、可搜索,但本次 force 请求显示为失败。### 13.8 Invalidate 缓存diff --git a/docs/zh/usage/cli_tools.md b/docs/zh/usage/cli_tools.mdindex 52d7d11e..0ce6d910 100644--- a/docs/zh/usage/cli_tools.md+++ b/docs/zh/usage/cli_tools.md@@ -73,3 +73,11 @@ mineru-kit vlm-server --engine auto --port 30000- `MINERU_INTRA_OP_NUM_THREADS` / `MINERU_INTER_OP_NUM_THREADS`:ONNX 算子线程配置。当前默认值以各命令的 `--help` 和[模型源说明](./model_source.md)为准。++## PDF 页码选择++使用 `--pages "1-5,8,r3-r1"`:页码从 1 开始,包含区间两端,`r1` 表示最后一页,`all` 表示全部。+结果去重并按原页序排列;部分越界取有效交集,倒序或选不到页面时返回 `page_range_invalid`。+省略页码时 `mineru parse` 默认前 10 页,`mineru-kit parse`、Python 和 Gradio 默认全部。+不再接受 `~` 和负数页码;升级调用方和服务端后,在新 Doclib 数据目录重建解析缓存。+完整说明见 [PDF 页码范围规范](../../next/page-ranges.md)。diff --git a/docs/zh/usage/quick_usage.md b/docs/zh/usage/quick_usage.mdindex e2a22d2c..58def7b0 100644--- a/docs/zh/usage/quick_usage.md+++ b/docs/zh/usage/quick_usage.md@@ -106,3 +106,11 @@ model:```模型下载和本地模型源的详细说明见[模型源说明](./model_source.md)。++## PDF 页码选择++使用 `--pages "1-5,8,r3-r1"`:页码从 1 开始,包含区间两端,`r1` 表示最后一页,`all` 表示全部。+结果去重并按原页序排列;部分越界取有效交集,倒序或选不到页面时返回 `page_range_invalid`。+省略页码时 `mineru parse` 默认前 10 页,`mineru-kit parse`、Python 和 Gradio 默认全部。+不再接受 `~` 和负数页码;升级调用方和服务端后,在新 Doclib 数据目录重建解析缓存。+完整说明见 [PDF 页码范围规范](../../next/page-ranges.md)。diff --git a/mineru/cli/commands/config.py b/mineru/cli/commands/config.pyindex b7cb3bc2..9d6fb411 100644--- a/mineru/cli/commands/config.py+++ b/mineru/cli/commands/config.py@@ -21,6 +21,7 @@ from ...doclib.types import (RemoveExcludeRuleResponse,RemoveParsingRuleResponse,)+from ...parser.page_range import normalize_page_range_inputfrom ...types import Tierfrom ..contracts import CliContextfrom ..runtime import run_cli@@ -101,7 +102,7 @@ def exclude_rules_remove(rule_id: int = typer.Argument(..., help="Rule id to remdef parsing_rules_add(pattern: str = typer.Argument(..., help="Glob pattern to match"),tier: Tier | None = typer.Option(None, "--tier", help="Parse tier: flash, basic, standard, advanced"),- pages: str | None = typer.Option(None, "--pages", help="Page range, e.g. all or 1~10"),+ pages: str | None = typer.Option(None, "--pages", help="PDF pages, e.g. all, 1-10 or r3-r1"),remote: bool = typer.Option(False, "--remote", help="Allow remote parsing"),name: str | None = typer.Option(None, "--name", help="Rule name"),json_mode: bool = typer.Option(False, "--json", help="JSON output"),@@ -110,13 +111,21 @@ def parsing_rules_add(ctx = CliContext(json_mode=json_mode)run_cli(ctx,- lambda: _client().add_parsing_rule(- ParsingRuleRequest(pattern=pattern, tier=tier, page_range=pages, remote=remote, name=name)- ),+ lambda: _add_parsing_rule(pattern, tier=tier, page_range=pages, remote=remote, name=name),render=_render_parsing_rule_added,)+def _add_parsing_rule(+ pattern: str, *, tier: Tier | None, page_range: str | None, remote: bool, name: str | None+) -> ParsingRuleInfo:+ """在访问 Doclib 前校验规则中的页码表达式。"""+ page_range = normalize_page_range_input(page_range) or None+ return _client().add_parsing_rule(+ ParsingRuleRequest(pattern=pattern, tier=tier, page_range=page_range, remote=remote, name=name)+ )++@parsing_rules_app.command("list")def parsing_rules_list(json_mode: bool = typer.Option(False, "--json", help="JSON output")) -> None:"""List parsing rules."""diff --git a/mineru/cli/commands/parse.py b/mineru/cli/commands/parse.pyindex b5613d62..32e33f57 100644--- a/mineru/cli/commands/parse.py+++ b/mineru/cli/commands/parse.py@@ -21,6 +21,7 @@ from ...doclib.types import (TelemetryObservationsRequest,)from ...errors import MineruError, error_response+from ...parser.page_range import normalize_page_range_inputfrom ...types import Tierfrom ..contracts import CliContext, CliResultfrom ..guidance import api_key_guidance_for_error@@ -66,23 +67,11 @@ def _emit_notice(message: str, *, json_mode: bool) -> None:def _validate_page_range_input(page_range: str | None) -> None:- if page_range is None or page_range.strip() == "" or page_range.strip() == "all":- return+ """复用共享语法校验,并把错误参数定位到 CLI 的 pages 选项。"""try:- for raw_part in page_range.split(","):- part = raw_part.strip()- if not part:- raise ValueError- if "~" in part:- raw_start, raw_end = part.split("~", 1)- start = int(raw_start.strip())- end = int(raw_end.strip())- if start > 0 and end > 0 and start > end:- raise ValueError- else:- int(part)- except ValueError:- raise MineruError("page_range_invalid", f"Invalid page range: {page_range}", "pages") from None+ normalize_page_range_input(page_range)+ except MineruError as exc:+ raise MineruError(exc.code, str(exc), "pages") from Nonedef parse_cmd(@@ -92,7 +81,7 @@ def parse_cmd("--tier",help="Parse tier: flash, basic, standard, advanced (default: server decides)",),- pages: str = typer.Option(None, "-p", "--pages", help="Page range, e.g. '1~5' or 'all'"),+ pages: str = typer.Option(None, "-p", "--pages", help="PDF pages: '1-5,8,r3-r1' or 'all'; default: first 10 pages"),after: str = typer.Option(None, "--after", help="Continue reading after a content cursor"),limit: int | None = typer.Option(None, "--limit", help="Soft character limit for STDOUT content"),format: Literal["markdown"] = typer.Option("markdown", "-f", "--format", help="Output format: markdown"),@@ -159,6 +148,7 @@ def _parse(raise MineruError("file_not_found", f"File not found: {file_path}", "path")_validate_page_range_input(pages)+ pages = normalize_page_range_input(pages) or Noneclient = DoclibClient(timeout=wait + 30)diff --git a/mineru/doclib/background/compaction.py b/mineru/doclib/background/compaction.pyindex 3b153b44..13a72ca9 100644--- a/mineru/doclib/background/compaction.py+++ b/mineru/doclib/background/compaction.py@@ -11,6 +11,7 @@ from collections.abc import Sequencefrom typing import Any, castfrom ...parser.base import MIDDLE_JSON_SCHEMA_VERSION+from ...parser.page_range import format_page_rangefrom ...types import Tierfrom ..core.db import DatabaseManagerfrom ..rows import ParseBatchRow, ParseGroupRow, ParseRow@@ -124,19 +125,8 @@ class Compaction:if r["done_at"] and r["done_at"] > max_done_at:max_done_at = r["done_at"]- # merge contiguous ranges- sorted_page_numbers = sorted(all_page_numbers)- merged_ranges: list[str] = []- start = sorted_page_numbers[0]- end = start- for page_no in sorted_page_numbers[1:]:- if page_no == end + 1:- end = page_no- else:- merged_ranges.append(f"{start}~{end}" if start != end else str(start))- start = page_no- end = page_no- merged_ranges.append(f"{start}~{end}" if start != end else str(start))+ # 使用统一格式化逻辑生成每段连续页的缓存范围。+ merged_ranges = format_page_range(all_page_numbers).split(",")# check if merge actually reduced row countif len(merged_ranges) >= len(rows):diff --git a/mineru/doclib/client.py b/mineru/doclib/client.pyindex de73196a..57ace97b 100644--- a/mineru/doclib/client.py+++ b/mineru/doclib/client.py@@ -11,6 +11,7 @@ from pydantic import BaseModelfrom pydantic_core import to_jsonable_pythonfrom ..errors import MineruError, ServerNotRunningError+from ..parser.page_range import normalize_page_range_inputfrom ..types import Tierfrom .base import DoclibInterfacefrom .endpoint import (@@ -128,6 +129,7 @@ class DoclibClient(DoclibInterface):@route("POST", "/parses", tags=("parse",))def ensure_parse(self, request: ParseRequest) -> ParseResponse:+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})return self._request_model(ParseResponse, body=request)@route("GET", "/parses", tags=("parse",))@@ -143,6 +145,7 @@ class DoclibClient(DoclibInterface):limit: int = 50,offset: int = 0,) -> ListParsesResponse:+ page_range = normalize_page_range_input(page_range) or Nonereturn self._request_model(ListParsesResponse,params={@@ -237,6 +240,7 @@ class DoclibClient(DoclibInterface):format: str = "markdown",no_marker: bool = False,) -> DocContentResponse:+ page_range = normalize_page_range_input(page_range) or Nonereturn self._request_model(DocContentResponse,path_params={"doc_ref": doc_ref},@@ -275,6 +279,7 @@ class DoclibClient(DoclibInterface):@route("POST", "/docs/{doc_ref}/exports", tags=("docs",))def export_doc_content(self, doc_ref: str, request: DocContentExportRequest) -> DocContentExportResponse:+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})return self._request_model(DocContentExportResponse, path_params={"doc_ref": doc_ref}, body=request)@route("GET", "/search", tags=("search",))@@ -354,6 +359,7 @@ class DoclibClient(DoclibInterface):@route("POST", "/parsing-rules", tags=("rules",))def add_parsing_rule(self, request: ParsingRuleRequest) -> ParsingRuleInfo:+ request = request.model_copy(update={"page_range": normalize_page_range_input(request.page_range) or None})return self._request_model(ParsingRuleInfo, body=request)@route("GET", "/parsing-rules", tags=("rules",))diff --git a/mineru/doclib/server.py b/mineru/doclib/server.pyindex f60b8c1d..19b2c22f 100644--- a/mineru/doclib/server.py+++ b/mineru/doclib/server.py@@ -24,6 +24,11 @@ from pydantic import ValidationErrorfrom ..config import configfrom ..errors import InvalidRequestError, MineruError, NotFoundError, error_response, http_status_forfrom ..filetypes import IMAGE_EXTENSIONS, TEXT_EXTENSIONS, TEXT_FILE_TYPES+from ..parser.page_range import (+ expand_page_range as _expand_page_range,+ format_page_range as _page_numbers_to_range_str,+ normalize_page_range_input,+)from ..parser.tier import TierDependencyError, ensure_tier_runtime_dependenciesfrom ..render._internal.markdown.assets import build_markdown_imagefrom ..render._internal.markdown.blocks import render_single_block@@ -406,6 +411,12 @@ class DoclibServer(AsyncDoclibInterface):limit=limit,offset=offset,)+ page_range = normalize_page_range_input(page_range)+ if resolved_sha256 and tier and page_range:+ doc = await self.state.db.fetchone("SELECT * FROM docs WHERE sha256=?", (resolved_sha256,))+ if doc is None:+ raise NotFoundError("doc_not_found", f"Document {resolved_sha256} not found.", "doc_ref")+ page_range = _expand_page_range(page_range, doc["page_count"] or 1)coverage = _parse_coverage(page_range, rows) if resolved_sha256 and tier and page_range else Nonereturn ListParsesResponse(parses=[_parse_info(row, coverage=coverage) for row in rows],@@ -1210,13 +1221,17 @@ class DoclibServer(AsyncDoclibInterface):(sha256, tier, PARSE_STATUS_DONE),)loaded_pages = load_pages_from_done_batches(data_dir, sha256, tier, cast(list[ParseBatchRow], rows))- if page_range:- loaded_pages = filter_pages_by_user_range(loaded_pages, page_range)- if not loaded_pages:- raise NotFoundError("not_cached", "Requested parsed content is not cached.", "page_range")doc = cast(DocRow | None, await self.state.db.fetchone("SELECT * FROM docs WHERE sha256=?", (sha256,)))if doc is None:raise NotFoundError("doc_not_found", f"Document {sha256} not found.", "doc_ref")+ page_range = normalize_page_range_input(page_range)+ if page_range and doc["page_count"] is not None:+ loaded_pages = filter_pages_by_user_range(loaded_pages, _expand_page_range(page_range, doc["page_count"]))+ elif page_range and page_range != "all":+ # 总页数未知时只允许绝对页码,不能用已缓存页数推断文档末页。+ loaded_pages = filter_pages_by_user_range(loaded_pages, page_range)+ if not loaded_pages:+ raise NotFoundError("not_cached", "Requested parsed content is not cached.", "page_range")output: list[str] = []page_count = doc["page_count"]for page in loaded_pages:@@ -1695,19 +1710,20 @@ def _is_paginated_doc(doc: DocRow) -> bool:def _normalize_content_page_range(page_range: str | None, after: str | None, doc: DocRow) -> str | None:+ page_range = normalize_page_range_input(page_range)page_count = doc.get("page_count") or 1if _is_paginated_doc(doc):if page_range and page_range.strip() == "all":- return f"1~{page_count}"+ return _expand_page_range("all", page_count)if page_range:return _normalize_page_range(page_range, page_count)if after:cursor = _parse_after_cursor(after)assert cursor is not Noneend = min(page_count, cursor.page_no + 9)- return f"{cursor.page_no}~{end}" if cursor.page_no != end else str(cursor.page_no)+ return _range_str(cursor.page_no, end)end = min(page_count, 10)- return f"1~{end}" if end > 1 else "1"+ return _range_str(1, end)if page_range and page_range.strip() == "all":return Nonereturn _normalize_page_range(page_range, page_count) if page_range else None@@ -1717,55 +1733,6 @@ def _normalize_page_range(page_range: str, page_count: int) -> str:return _expand_page_range(page_range, page_count)-def _expand_page_range(page_range: str, page_count: int) -> str:- available_page_numbers = set(range(1, page_count + 1))- if not page_range or page_range.strip() == "all":- page_numbers = available_page_numbers- else:- page_numbers: set[int] = set()- for part in page_range.split(","):- part = part.strip()- if not part:- continue- if "~" in part:- raw_start, raw_end = part.split("~", 1)- start = int(raw_start.strip())- end = int(raw_end.strip())- if start < 0:- start = page_count + start + 1- if end < 0:- end = page_count + end + 1- if start <= end:- page_numbers.update(range(start, end + 1))- else:- page_no = int(part)- if page_no < 0:- page_no = page_count + page_no + 1- page_numbers.add(page_no)- page_numbers &= available_page_numbers- if not page_numbers:- raise InvalidRequestError("page_range_invalid", f"Page range does not select any pages: {page_range}", "page_range")- return _page_numbers_to_range_str(page_numbers)---def _page_numbers_to_range_str(page_numbers: set[int]) -> str:- if not page_numbers:- return ""- ranges: list[str] = []- ordered = sorted(page_numbers)- start = ordered[0]- end = ordered[0]- for page_no in ordered[1:]:- if page_no == end + 1:- end = page_no- continue- ranges.append(f"{start}~{end}" if start != end else str(start))- start = page_no- end = page_no- ranges.append(f"{start}~{end}" if start != end else str(start))- return ",".join(ranges)--def _select_context_pages(pages: list[PageInfo], target: ContentCursor | None, context: int) -> list[PageInfo]:if target is None or target.page_no is None or context <= 0:return pages@@ -2179,7 +2146,7 @@ def _last_requested_page(page_range: str | None) -> int | None:def _range_str(start: int, end: int) -> str:- return f"{start}~{end}" if start != end else str(start)+ return _page_numbers_to_range_str(range(start, end + 1))def _effective_data_dir(state: Any) -> str:diff --git a/mineru/doclib/services/config_svc.py b/mineru/doclib/services/config_svc.pyindex e6080ffa..3b05eb1a 100644--- a/mineru/doclib/services/config_svc.py+++ b/mineru/doclib/services/config_svc.py@@ -9,6 +9,7 @@ import timefrom typing import castfrom ...errors import InvalidRequestError+from ...parser.page_range import normalize_page_range_inputfrom ...types import Tierfrom ..config_defaults import CONFIG_DEFAULTS, CONFIG_SOURCE_DEFAULT, CONFIG_SOURCE_OVERRIDE, ConfigSourcefrom ..config_schema import validate_config_key, validate_config_value@@ -208,6 +209,7 @@ class ConfigService:(name, pattern, priority, now, now),)if rule_type == RULE_TYPE_PARSING_RULE:+ page_range = normalize_page_range_input(page_range) or Nonereturn await self.db.execute_insert("INSERT INTO parsing_rules (name, pattern, tier, page_range, remote, priority, created_at, updated_at) ""VALUES (?, ?, ?, ?, ?, ?, ?, ?)",diff --git a/mineru/doclib/services/parse_svc.py b/mineru/doclib/services/parse_svc.pyindex b0f59bf1..85e4e80a 100644--- a/mineru/doclib/services/parse_svc.py+++ b/mineru/doclib/services/parse_svc.py@@ -28,6 +28,12 @@ from ...filetypes import ()from ...parser.api_client import _APITransportError, _V1APIErrorfrom ...parser.base import ParseResult+from ...parser.page_range import (+ expand_page_range,+ format_page_range as _page_numbers_to_range_str,+ normalize_page_range_input,+ parse_page_range_set,+)from ...types import QUALITY_TIERS, TIER_ORDER, PageInfo, Tier, select_default_quality_tier, select_parsing_rule_tierfrom ..core.db import DatabaseManagerfrom ..core.file_io import FileStat, MetadataExtractionError, compute_sha256, extract_metadata, get_file_stat@@ -124,21 +130,6 @@ def _raise_refresh_error(refreshed: FileRefreshResult) -> None:# ── range helpers ──────────────────────────────────────────────────-def parse_page_range_set(page_range: str) -> set[int]:- """Parse a page_range string like '1~5,10~15' into 1-based page numbers."""- page_numbers: set[int] = set()- for part in page_range.split(","):- part = part.strip()- if not part:- continue- if "~" in part:- a, b = part.split("~", 1)- page_numbers.update(range(int(a.strip()), int(b.strip()) + 1))- else:- page_numbers.add(int(part))- return page_numbers--def filter_pages_by_user_range(pages: list[PageInfo], page_range: str) -> list[PageInfo]:"""Filter 0-based PageInfo objects by a user-facing 1-based page range."""requested_page_numbers = parse_page_range_set(page_range)@@ -166,64 +157,10 @@ def page_range_uncovered(request_page_range: str, done_batches: list[ParseRow])return needed_page_numbers - covered_page_numbers-def _page_numbers_to_range_str(page_numbers: set[int]) -> str:- """Convert a set of page numbers (1-based) to a compact range string."""- if not page_numbers:- return ""- sorted_page_numbers = sorted(page_numbers)- ranges: list[str] = []- start = sorted_page_numbers[0]- end = start- for page_no in sorted_page_numbers[1:]:- if page_no == end + 1:- end = page_no- else:- ranges.append(f"{start}~{end}" if start != end else str(start))- start = page_no- end = page_no- ranges.append(f"{start}~{end}" if start != end else str(start))- return ",".join(ranges)---def expand_page_range(page_range: str | None, page_count: int) -> str:- """Expand shorthand page_range like 'all' or negative ranges like '-5~-1'- into positive page ranges. Returns '1~{page_count}' for None/empty."""- available_page_numbers = set(range(1, page_count + 1))- if not page_range or page_range.strip() == "all":- page_numbers = available_page_numbers- else:- page_numbers: set[int] = set()- for part in page_range.split(","):- part = part.strip()- if not part:- continue- if "~" in part:- a, b = part.split("~", 1)- a, b = a.strip(), b.strip()- start = int(a)- end = int(b)- # negative index: -5 means page_count-5+1- if start < 0:- start = page_count + start + 1- if end < 0:- end = page_count + end + 1- if start <= end:- page_numbers.update(range(start, end + 1))- else:- page_no = int(part.strip())- if page_no < 0:- page_no = page_count + page_no + 1- page_numbers.add(page_no)- page_numbers &= available_page_numbers- if not page_numbers:- raise InvalidRequestError("page_range_invalid", f"Page range does not select any pages: {page_range}", "page_range")- return _page_numbers_to_range_str(page_numbers)--def default_parse_range(page_count: int | None) -> str:"""Return the default page range for active reading."""if page_count and page_count > 0:- return f"1~{min(page_count, 10)}"+ return expand_page_range("1-10", page_count)return "1"@@ -726,6 +663,7 @@ class ParseService:remote: bool = False,) -> ParseResponse:"""Handle a parse request from CLI. Returns info for status polling."""+ page_range = normalize_page_range_input(page_range) or None# ensure the path is current before trusting files.sha256refreshed = await self.refresh_file(path, ensure_ingested=True, allow_images=True)if refreshed.status == "unsupported":@@ -1383,8 +1321,12 @@ class ParseService:sql += " ORDER BY created_at DESC"rows = cast(list[ParseRow], await self.db.fetchall(sql, tuple(params)))result: dict[str, object] = {"parses": [_parse_record_response(row) for row in rows]}+ page_range = normalize_page_range_input(page_range)if sha256 and tier and page_range:- result["coverage"] = _parse_coverage(page_range, rows)+ doc = await self.db.fetchone("SELECT * FROM docs WHERE sha256=?", (sha256,))+ if doc is None:+ raise InvalidRequestError("doc_not_found", f"Document {sha256} not found.", "doc_ref")+ result["coverage"] = _parse_coverage(expand_page_range(page_range, doc["page_count"] or 1), rows)return resultasync def invalidate(self, sha256: str, tier: Tier | None = None) -> int:diff --git a/mineru/doclib/types.py b/mineru/doclib/types.pyindex ad48932e..f4967a27 100644--- a/mineru/doclib/types.py+++ b/mineru/doclib/types.py@@ -6,6 +6,7 @@ from typing import Any, Literalfrom pydantic import BaseModel, Field+from ..parser.page_range import PAGE_RANGE_DESCRIPTIONfrom ..types import TierParseSubmitStatus = Literal["pending", "done"]@@ -95,7 +96,7 @@ class RemoveParsingRuleResponse(DoclibModel):class ParseRequest(DoclibModel):path: strtier: Tier | None = None- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)force: bool = Falseremote: bool = False@@ -104,7 +105,7 @@ class ParseResponse(DoclibModel):sha256: strshort_id: str | None = Nonetier: Tier- page_range: str+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")status: ParseSubmitStatuscache_hit: bool = Falsewait_parse_ids: list[int] = Field(default_factory=list)@@ -114,9 +115,9 @@ class ParseResponse(DoclibModel):class ParseCoverage(DoclibModel):- done_page_range: str- active_page_range: str- missing_page_range: str+ done_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")+ active_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")+ missing_page_range: str = Field(description="Resolved 1-based page ranges; an empty string denotes no pages.")class ParseInfo(DoclibModel):@@ -124,7 +125,7 @@ class ParseInfo(DoclibModel):sha256: strshort_id: strtier: Tier- page_range: str+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")status: ParseStatuspriority: int = 0privacy: str@@ -276,7 +277,7 @@ class DocContentResponse(DoclibModel):class ContentRequestScope(DoclibModel):- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)after: str | None = Nonelimit: int = 30000locator: str | None = None@@ -285,13 +286,13 @@ class ContentRequestScope(DoclibModel):class ContentRange(DoclibModel):- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)start: strend: strclass ContentNextRequest(DoclibModel):- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)after: str | None = Nonelocator: str | None = None@@ -306,7 +307,7 @@ class ContentAsset(DoclibModel):class DocContentExportRequest(DoclibModel):tier: Tier- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)format: str = "markdown"output: strno_marker: bool = False@@ -368,7 +369,7 @@ class FileInfoResponse(DoclibModel):class TierParseInfo(DoclibModel):tier: Tierstatus: ParseStatus- page_range: str+ page_range: str = Field(description="Resolved 1-based inclusive page ranges, e.g. 1-5,8.")done_at: int | None = None@@ -461,7 +462,7 @@ class ParsingRuleRequest(DoclibModel):pattern: strname: str | None = Nonetier: Tier | None = None- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)remote: bool = Falsepriority: int = 0@@ -482,7 +483,7 @@ class ParsingRuleInfo(DoclibModel):pattern: strname: str | None = Nonetier: Tier | None = None- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION)remote: bool = Falseenabled: bool = Truepriority: int = 0diff --git a/mineru/kit/commands/parse.py b/mineru/kit/commands/parse.pyindex c139949d..34731d7c 100644--- a/mineru/kit/commands/parse.py+++ b/mineru/kit/commands/parse.py@@ -6,11 +6,14 @@ from typing import Literal, castimport typer+from ...errors import MineruErrorfrom ...filetypes import ensure_tier_supported_for_parse_extension, is_flash_only_parse_extensionfrom ...parser import MinerUApiParserfrom ...parser import parse as local_parse-from ...types import Tier+from ...parser.api_client import _V1APIError+from ...parser.page_range import normalize_page_range_inputfrom ...parser.tier import normalize_backend+from ...types import Tierfrom ..common import (build_remote_api_url,effective_local_tier_and_backend,@@ -27,7 +30,7 @@ from ..output import print_info, print_successdef parse_cmd(inputs: list[str] = typer.Argument(..., help="Input files or directories"),output: str = typer.Option(..., "-o", "--output", help="Output path; required"),- pages: str | None = typer.Option(None, "-p", "--pages", help="Page range, e.g. '1~5' or 'all'"),+ pages: str | None = typer.Option(None, "-p", "--pages", help="PDF pages: '1-5,8,r3-r1' or 'all'; default: all pages"),format: str = typer.Option("markdown","-f",@@ -44,6 +47,10 @@ def parse_cmd(disable_image_analysis: bool = typer.Option(False, "--disable-image-analysis", help="Disable image analysis"),) -> None:"""Parse files or directories into markdown, middle JSON, or zip outputs."""+ try:+ pages = normalize_page_range_input(pages)+ except MineruError as exc:+ exit_with_message(exc.code, str(exc), "pages")output_format = cast(Literal["markdown", "middle_json", "zip"], format)parse_tier = cast(Tier | None, tier)parse_ocr_mode = cast(Literal["auto", "txt", "ocr"], ocr_mode)@@ -107,6 +114,8 @@ def parse_cmd(save_parse_result(result, dest, output_format)if verbose:print_info(str(parse_result_payload(path, dest, output_format)))+ except (MineruError, _V1APIError) as exc:+ exit_with_message(exc.code, str(exc), exc.param)except Exception as exc:exit_with_message("parse_failed", f"Failed to parse {path}: {exc}")print_success(f"Parsed {len(paths)} input(s).")diff --git a/mineru/kit/gradio/app.py b/mineru/kit/gradio/app.pyindex 3fa7194d..e9b6ad08 100644--- a/mineru/kit/gradio/app.py+++ b/mineru/kit/gradio/app.py@@ -4,13 +4,17 @@ from __future__ import annotationsimport asyncioimport html+import jsonimport osfrom pathlib import Pathfrom collections.abc import Callablefrom typing import Any, Literalfrom urllib.parse import quote+from ...errors import MineruErrorfrom ...filetypes import IMAGE_EXTENSIONS, OFFICE_EXTENSIONS, PARSEABLE_EXTENSIONS, PDF_EXTENSIONS+from ...parser.page_range import normalize_page_range_input+from ...types import TIERS, Tierfrom ...utils.stdio import configure_standard_streamsfrom .artifacts import RunArtifacts, markdown_for_gradio, persist_parse_result, render_downloadfrom .client import (@@ -131,6 +135,13 @@ def _default_tier(capabilities: V1ServerCapabilities) -> str:return capabilities.tiers[0]+def _tier_for_position(position: int | float, tier_choices: list[Tier]) -> Tier:+ """把离散滑块位置映射为服务支持的 tier,并拒绝越界或非整数位置。"""+ if isinstance(position, bool) or position not in range(len(tier_choices)):+ raise ValueError("Invalid tier slider position")+ return tier_choices[int(position)]++def _status_html(message: str) -> str:"""生成不解释协议细节、只显示当前阶段的安全状态片段。"""raw_message = str(message or _DEFAULT_STATUS)@@ -186,7 +197,7 @@ def _effective_page_range(path_value: str | Path | None, raw_page_range: str | N"""仅为 PDF 保留用户输入的 V1 page_range,其它格式统一返回空字符串。"""if _file_suffix(path_value) not in PDF_EXTENSIONS:return ""- return str(raw_page_range or "").strip()+ return normalize_page_range_input(raw_page_range)def _is_pdf_or_image(path_value: str | Path | None) -> bool:@@ -232,9 +243,9 @@ def build_gradio_app(import gradio as grfrom gradio_pdf import PDF- if not capabilities.tiers:+ tier_choices = [tier for tier in TIERS if tier in capabilities.tiers]+ if not tier_choices:raise ValueError("V1 API server did not advertise any parsing tier")- tier_choices = list(capabilities.tiers)preferred_tier = _default_tier(capabilities)file_types = _supported_file_types()markdown_copy_kwargs = {"buttons": ["copy"]} if _gradio_major_version(gr) >= 6 else {"show_copy_button": True}@@ -253,16 +264,28 @@ def build_gradio_app(type="filepath",elem_classes=["mineru-upload-file"],)- tier = gr.Dropdown(- choices=tier_choices,- value=preferred_tier,- label="解析 tier",- elem_classes=["mineru-tier-select"],- )+ with gr.Group():+ tier_label = gr.Markdown(+ value=f"解析 tier:{preferred_tier}",+ padding=True,+ elem_classes=["mineru-tier-label"],+ )+ tier = gr.Slider(+ minimum=0,+ # 单档位时保留非零跨度,避免原生滑块计算进度时除零。+ maximum=max(1, len(tier_choices) - 1),+ value=tier_choices.index(preferred_tier),+ step=1,+ precision=0,+ interactive=len(tier_choices) > 1,+ label="解析 tier",+ show_label=False,+ elem_classes=["mineru-tier-slider"],+ )page_range = gr.Textbox(value="",label="页码范围",- placeholder="例如 1~5,8,-1;留空表示全部",+ placeholder="例如 1-5,8,r1 或 all;留空表示全部",interactive=False,elem_classes=["mineru-kit-page-range"],)@@ -415,6 +438,18 @@ def build_gradio_app()private_event_kwargs = _private_event_kwargs(gr)+ tier.input(+ fn=None,+ inputs=tier,+ outputs=tier_label,+ js="""(position) => {+ // 在浏览器端即时显示当前档位;实际解析独立读取滑块位置。+ const tiers = %s;+ return ["解析 tier:" + tiers[position]];+ }"""+ % json.dumps(tier_choices),+ **private_event_kwargs,+ )input_file.change(fn=update_file_preview,inputs=input_file,@@ -436,7 +471,7 @@ def build_gradio_app(async def convert_handler(file_path: str | None,- selected_tier: str,+ tier_position: int | float,raw_page_range: str,request: object | None = None,) -> Any:@@ -464,7 +499,16 @@ def build_gradio_app(if suffix not in PARSEABLE_EXTENSIONS:yield (_status_html(f"Failed: unsupported file type '.{suffix}'"), "", "", "", *empty_result[4:])return- page_text = _effective_page_range(source_path, raw_page_range)+ try:+ selected_tier = _tier_for_position(tier_position, tier_choices)+ except ValueError as exc:+ yield (_status_html(f"Failed: {exc}"), "", "", "", *empty_result[4:])+ return+ try:+ page_text = _effective_page_range(source_path, raw_page_range)+ except MineruError as exc:+ yield (_status_html(f"Failed: {exc.code}: {exc}"), "", "", "", *empty_result[4:])+ returnyield (_status_html(STATUS_PREPARING_REQUEST), "", "", "", *empty_result[4:])status_queue: asyncio.Queue[str] = asyncio.Queue()loop = asyncio.get_running_loop()diff --git a/mineru/kit/gradio/artifacts.py b/mineru/kit/gradio/artifacts.pyindex f62552a5..f397935d 100644--- a/mineru/kit/gradio/artifacts.py+++ b/mineru/kit/gradio/artifacts.py@@ -514,8 +514,6 @@ def _prepare_origin_pdf(with PDFDocument(source_bytes) as doc:page_count = doc.page_countpage_indices = parse_page_range(page_range, page_count)- if page_range.strip() and not page_indices:- raise ValueError(f"Page range does not select any pages: {page_range}")if page_indices == list(range(page_count)):output_path.write_bytes(source_bytes)return output_path, page_indicesdiff --git a/mineru/kit/gradio/client.py b/mineru/kit/gradio/client.pyindex bf70924d..49796383 100644--- a/mineru/kit/gradio/client.py+++ b/mineru/kit/gradio/client.py@@ -18,6 +18,7 @@ import httpxfrom ...parser.api_client import MinerUApiParser, should_trust_env_for_urlfrom ...parser.base import ParseResult+from ...parser.page_range import normalize_page_range_inputfrom ...parser.process_control import ManagedProcessControlfrom ...types import SERVER_TIERS, TIERS, ServerTier, Tierfrom ...utils.stdio import utf8_subprocess_env@@ -183,6 +184,7 @@ class V1ArtifactClient:status_callback: Callable[[str], None] | None = None,) -> ParseResult:"""通过 V1 API 解析单个文件,并返回带图片/模型输出的 `ParseResult`。"""+ page_range = normalize_page_range_input(page_range)if not path.is_file():raise FileNotFoundError(path)if tier not in TIERS:diff --git a/mineru/parser/api_client.py b/mineru/parser/api_client.pyindex 7e5fd013..cceef8ae 100644--- a/mineru/parser/api_client.py+++ b/mineru/parser/api_client.py@@ -29,6 +29,7 @@ from ..filetypes import mime_type_for_extensionfrom ..types import PageInfo, Tier, validate_tierfrom ..utils.image_payload import validate_image_sidecar_pathfrom .base import DocumentParser, ParseResult+from .page_range import normalize_page_range_input_POLL_INTERVAL_SECONDS = 1_POLL_MAX_ATTEMPTS = 3600@@ -99,6 +100,7 @@ class MinerUApiParser(DocumentParser):# ── DocumentParser interface ─────────────────────────────────────def parse(self, path: str | Path, *, page_range: str = "") -> ParseResult:+ page_range = normalize_page_range_input(page_range)file_path = Path(path)if not file_path.exists():raise FileNotFoundError(file_path)@@ -108,6 +110,7 @@ class MinerUApiParser(DocumentParser):return self._build_result(job, file_path.name)async def parse_async(self, path: str | Path, *, page_range: str = "") -> ParseResult:+ page_range = normalize_page_range_input(page_range)file_path = Path(path)if not file_path.exists():raise FileNotFoundError(file_path)@@ -160,6 +163,7 @@ class MinerUApiParser(DocumentParser):return sourcedef _build_payload(self, source: dict[str, Any], page_range: str) -> dict[str, Any]:+ page_range = normalize_page_range_input(page_range)file_entry: dict[str, Any] = {"source": source}if page_range:file_entry["page_range"] = page_rangediff --git a/mineru/parser/api_server.py b/mineru/parser/api_server.pyindex 76582ef6..78c5f2b0 100644--- a/mineru/parser/api_server.py+++ b/mineru/parser/api_server.py@@ -56,6 +56,12 @@ from ..utils.stdio import configure_standard_streamsfrom ..version import __version__from . import parse_asyncfrom .base import ParseResult+from .page_range import (+ PAGE_RANGE_DESCRIPTION,+ count_pages_in_range as _count_pages_in_range,+ format_page_range as _compact_page_numbers,+ normalize_page_range_input,+)from .tier import (ParserRuntimeOptions,TierDependencyError,@@ -445,7 +451,7 @@ FileSource = Annotated[class JobFileEntry(BaseModel):model_config = _PYDANTIC_CONFIGsource: FileSource- page_range: str | None = None+ page_range: str | None = Field(default=None, description=PAGE_RANGE_DESCRIPTION, examples=["1-5,8,r3-r1", "all"])class CallbackConfig(BaseModel):@@ -1245,22 +1251,6 @@ def _job_has_any_flash_only_inputs(req: CreateJobRequest, file_store: FileStore)return any(is_flash_only_parse_extension(_source_name(entry.source, file_store)) for entry in req.files)-def _compact_page_numbers(page_numbers: list[int]) -> str:- if not page_numbers:- return ""- ordered = sorted(set(page_numbers))- ranges: list[str] = []- start = prev = ordered[0]- for page in ordered[1:]:- if page == prev + 1:- prev = page- continue- ranges.append(str(start) if start == prev else f"{start}~{prev}")- start = prev = page- ranges.append(str(start) if start == prev else f"{start}~{prev}")- return ",".join(ranges)--def _page_range_from_result_pages(pages: list[PageInfo]) -> str:page_numbers: list[int] = []for i, page in enumerate(pages):@@ -1270,26 +1260,6 @@ def _page_range_from_result_pages(pages: list[PageInfo]) -> str:return _compact_page_numbers(page_numbers)-def _count_pages_in_range(page_range: str) -> int:- total = 0- for part in page_range.split(","):- token = part.strip()- if not token:- continue- if "~" not in token:- total += 1- continue- left, right = token.split("~", 1)- try:- start = int(left)- end = int(right)- except ValueError:- total += 1- continue- total += max(0, end - start + 1)- return total--@dataclass(frozen=True, slots=True)class _ExtractedSource:"""保存 API 输入字节、响应类型及 HTML 来源上下文。"""@@ -1787,6 +1757,13 @@ async def create_job(access_level: AccessLevel = Depends(_resolve_access_level),) -> Response:"""Create a parse job."""+ for index, entry in enumerate(body.files):+ try:+ entry.page_range = normalize_page_range_input(entry.page_range) or None+ except MineruError as exc:+ _raise_api_error(+ 400, error_type=exc.type, code=exc.code, message=str(exc), param=f"files.{index}.page_range"+ )_require_model_preload_ready(request)if body.callback is not None:_raise_api_error(diff --git a/mineru/parser/base.py b/mineru/parser/base.pyindex 019b95f3..7d614782 100644--- a/mineru/parser/base.py+++ b/mineru/parser/base.py@@ -227,7 +227,7 @@ class DocumentParser(ABC):path:Path to the document file.page_range:- PDF-only 1-based page range string (``"1~5,-3~-1"``). Empty means all pages.+ PDF-only 1-based inclusive range (``"1-5,r3-r1"``). ``r1`` is the last page; empty or ``"all"`` means all pages."""async def parse_async(self, path: str | Path, *, page_range: str = "") -> ParseResult:diff --git a/mineru/parser/mineru_parser.py b/mineru/parser/mineru_parser.pyindex 34a733b9..a8dfccbd 100644--- a/mineru/parser/mineru_parser.py+++ b/mineru/parser/mineru_parser.py@@ -129,6 +129,9 @@ class MinerUParser(DocumentParser):) -> _PreparedInput:"""读取路径、检测类型并补齐 HTML 来源或 PDF 页范围状态。"""from .file_type import guess_suffix_by_path+ from .page_range import normalize_page_range_input++ page_range = normalize_page_range_input(page_range)file_name = path.stemfile_bytes = path.read_bytes()@@ -201,16 +204,11 @@ class MinerUParser(DocumentParser):from ..model.flash.pdf.document import PDFDocumentfrom .page_range import parse_page_range- doc = PDFDocument(file_bytes)- page_indices = parse_page_range(page_range, doc.page_count)- if page_range.strip() and not page_indices:- raise InvalidRequestError(- "page_range_invalid",- f"Page range does not select any pages: {page_range}",- "page_range",- )+ with PDFDocument(file_bytes) as doc:+ page_count = doc.page_count+ page_indices = parse_page_range(page_range, page_count)- if page_indices == list(range(doc.page_count)):+ if page_indices == list(range(page_count)):return file_bytes, None, Nonefrom ..model.flash.pdf.pdfium import safe_rewrite_pdf_bytes_with_pdfium_resultdiff --git a/mineru/parser/page_range.py b/mineru/parser/page_range.pyindex a144efe5..113a85de 100644--- a/mineru/parser/page_range.py+++ b/mineru/parser/page_range.py@@ -1,8 +1,23 @@# Copyright (c) Opendatalab. All rights reserved.+"""所有入口共享的页码范围语法、求值和格式化;默认选页策略由调用方决定。"""+from __future__ import annotations+import re+from collections.abc import Iterable+from loguru import logger+from ..errors import InvalidRequestError++PAGE_RANGE_DESCRIPTION = (+ "PDF page selection: 1-based inclusive ranges, e.g. '1-5,8,r3-r1'; "+ "'r1' is the last page and 'all' selects every page. Blank means unspecified. "+ "Selections are sorted and deduplicated; out-of-bounds pages are omitted. "+ "Reversed ranges, '~' and negative page numbers are invalid."+)+_SEGMENT_PATTERN = re.compile(r"(r?[1-9][0-9]*)(?:\s*-\s*(r?[1-9][0-9]*))?")+def get_end_page_id(end_page_id: int | None, pdf_page_num: int) -> int:"""归一化旧 CLI 的 0-based 结束页,越界时钳制到最后一页。"""@@ -13,47 +28,134 @@ def get_end_page_id(end_page_id: int | None, pdf_page_num: int) -> int:return normalized_end_page_id-def parse_page_range(raw: str, page_count: int) -> list[int]:- """Parse a 1-based page-range string into a 0-based flattened list of page indices.-- Format (aligned with Unified API ``page_range``):- ``"1~5"`` → pages 1 through 5- ``"1,3,5~7"`` → pages 1, 3, 5, 6, 7- ``"-5~-1"`` → last 5 pages (page_count=100 → [95, 96, 97, 98, 99])- ``"5"`` → single page 5- ``""`` → all pages-- Separator: ``~`` recommended, ``-`` also accepted.- Negative values are resolved against *page_count* (e.g. ``-1`` = last page).- Returns an empty list when every resolved segment is outside ``[0, page_count)``.- """- if not raw or not raw.strip():- return list(range(page_count))-- result: list[int] = []- for segment in raw.split(","):- segment = segment.strip()- if not segment:- continue- sep = "~" if "~" in segment else "-"- parts = segment.split(sep, 1)-- def _resolve(token: str) -> int:- n = int(token.strip())- return page_count + n + 1 if n < 0 else n-- start_1b = _resolve(parts[0])- end_1b = _resolve(parts[1]) if len(parts) > 1 and parts[1].strip() else start_1b-- start_0b = start_1b - 1 # 1-based → 0-based- end_0b = end_1b - 1-- lo = max(0, min(start_0b, end_0b))- hi = min(page_count - 1, max(start_0b, end_0b))+def _invalid_range(raw: str | None, reason: str) -> InvalidRequestError:+ """统一生成可跨 Python、CLI 和 HTTP 传递的页码错误。"""+ return InvalidRequestError("page_range_invalid", f"Invalid page range {raw!r}: {reason}", "page_range")+++def _parse_endpoint(token: str) -> int:+ """以负整数在内部标记倒数端点,外部输入只接受 rN。"""+ return -int(token[1:]) if token.startswith("r") else int(token)+++def _parse_segments(raw: str | None) -> list[tuple[int, int]] | None:+ """解析完整表达式;None 表示全部,倒数端点留待获得总页数后求值。"""+ value = (raw or "").strip()+ if not value or value == "all":+ return None+ segments: list[tuple[int, int]] = []+ for part in value.split(","):+ match = _SEGMENT_PATTERN.fullmatch(part.strip())+ if match is None:+ raise _invalid_range(raw, "expected a page, an inclusive range, or 'all'")+ try:+ start = _parse_endpoint(match[1])+ end = _parse_endpoint(match[2]) if match[2] else start+ except ValueError as exc:+ raise _invalid_range(raw, "page number is too large") from exc+ if (start > 0) == (end > 0) and start > end:+ raise _invalid_range(raw, "reversed ranges are not supported")+ segments.append((start, end))+ return segments+++def _merge_intervals(intervals: Iterable[tuple[int, int]]) -> list[tuple[int, int]]:+ """合并已求值区间,无需逐页展开即可排序、去重和连接相邻区间。"""+ merged: list[tuple[int, int]] = []+ for start, end in sorted(intervals):+ if merged and start <= merged[-1][1] + 1:+ merged[-1] = (merged[-1][0], max(end, merged[-1][1]))+ else:+ merged.append((start, end))+ return merged+++def _format_endpoint(value: int) -> str:+ """把内部端点转换为正整数或 rN 文本。"""+ return str(value) if value > 0 else f"r{-value}"+++def _format_intervals(intervals: Iterable[tuple[int, int]]) -> str:+ """生成无空白的范围文本,单页只输出一个端点。"""+ return ",".join(+ _format_endpoint(start) if start == end else f"{_format_endpoint(start)}-{_format_endpoint(end)}"+ for start, end in intervals+ )+++def normalize_page_range_input(raw: str | None) -> str:+ """校验未绑定文档的输入,清理空白并保留 all/rN;空值统一为未指定。"""+ segments = _parse_segments(raw)+ if segments is None:+ return "all" if (raw or "").strip() else ""+ if all(start > 0 and end > 0 for start, end in segments):+ segments = _merge_intervals(segments)+ return _format_intervals(segments)+++def _resolved_intervals(raw: str | None, page_count: int) -> list[tuple[int, int]]:+ """按文档总页数求值并裁剪,先验证所有区间再合并有效交集。"""+ segments = _parse_segments(raw)+ if page_count <= 0:+ raise _invalid_range(raw, "document has no available pages")+ if segments is None:+ return [(1, page_count)]+ intervals: list[tuple[int, int]] = []+ for start, end in segments:+ start = start if start > 0 else page_count + start + 1+ end = end if end > 0 else page_count + end + 1+ if start > end:+ raise _invalid_range(raw, "reversed ranges are not supported")+ lo, hi = max(1, start), min(page_count, end)if lo <= hi:- result.extend(range(lo, hi + 1))+ intervals.append((lo, hi))+ if not intervals:+ raise _invalid_range(raw, "selection does not contain any available pages")+ return _merge_intervals(intervals)+++def parse_page_range(raw: str, page_count: int) -> list[int]:+ """把 1-based 表达式转换为去重升序的 0-based 页索引,空值选择全部。"""+ return [page_idx for start, end in _resolved_intervals(raw, page_count) for page_idx in range(start - 1, end)]+++def expand_page_range(raw: str | None, page_count: int) -> str:+ """将含 all/rN 的表达式展开为实际文档的正整数规范范围。"""+ return _format_intervals(_resolved_intervals(raw, page_count))+++def _absolute_intervals(raw: str) -> list[tuple[int, int]]:+ """读取已求值的覆盖范围;空文本表示空集合,禁止未经求值的 all/rN。"""+ if not raw.strip():+ return []+ segments = _parse_segments(raw)+ if segments is None or any(start < 0 or end < 0 for start, end in segments):+ raise _invalid_range(raw, "page count is required to resolve all/rN")+ return _merge_intervals(segments)+++def parse_page_range_set(raw: str) -> set[int]:+ """把已求值的范围转换为 1-based 页码集合,供缓存覆盖与内容过滤使用。"""+ return {page_no for start, end in _absolute_intervals(raw) for page_no in range(start, end + 1)}+++def count_pages_in_range(raw: str) -> int:+ """统计已求值范围的唯一页数,不为统计分配逐页集合。"""+ return sum(end - start + 1 for start, end in _absolute_intervals(raw))+- return sorted(set(result))+def format_page_range(page_numbers: Iterable[int]) -> str:+ """将 1-based 页码集合格式化为去重升序的连续范围;空集合输出空字符串。"""+ return _format_intervals(_merge_intervals((page_no, page_no) for page_no in page_numbers))-__all__ = ["get_end_page_id", "parse_page_range"]+__all__ = [+ "PAGE_RANGE_DESCRIPTION",+ "count_pages_in_range",+ "expand_page_range",+ "format_page_range",+ "get_end_page_id",+ "normalize_page_range_input",+ "parse_page_range",+ "parse_page_range_set",+]diff --git a/mineru/resources/gradio_app.css b/mineru/resources/gradio_app.cssindex 138e91a9..e7a449dc 100644--- a/mineru/resources/gradio_app.css+++ b/mineru/resources/gradio_app.css@@ -46,6 +46,12 @@ body.dark .gradio-container {top: 12px;align-self: flex-start;}+/* 档位名称由上方 Markdown 显示,仅隐藏原生滑块的数字区,不修改轨道和滑块样式。 */+.mineru-tier-slider .head,+.mineru-tier-slider .min_value,+.mineru-tier-slider .max_value {+ display: none;+}.mineru-upload-file label[data-testid="block-label"] {align-items: flex-start !important;line-height: 1.35 !important;diff --git a/tests/unittest/test_cli_next_command_design.py b/tests/unittest/test_cli_next_command_design.pyindex daa5d8bb..a9facdba 100644--- a/tests/unittest/test_cli_next_command_design.py+++ b/tests/unittest/test_cli_next_command_design.py@@ -358,7 +358,7 @@ def test_list_renderers_return_tables(monkeypatch: Any) -> None:sha256="a" * 64,short_id="aaaaaaa",tier="basic",- page_range="1~2",+ page_range="1-2",status="done",privacy="local",created_at=1,@@ -405,7 +405,7 @@ def test_list_renderers_return_tables(monkeypatch: Any) -> None:docs_table = list_resources._render_list_docs(ListDocsResponse(docs=[doc], total=1, limit=50))assert parses_table.title == "Parses (1 total)"- assert ("7", "done", "basic", "1~2", "aaaaaaa") in parses_table.rows+ assert ("7", "done", "basic", "1-2", "aaaaaaa") in parses_table.rowsassert scans_table.title == "Scans (1 total)"assert ("8", "done", "manual", "/tmp/docs", "3", "2", "1") in scans_table.rowsassert files_table.title == "Files (1 total)"@@ -426,7 +426,7 @@ def test_config_and_rule_renderers_return_tables(monkeypatch: Any) -> None:parsing_table = config._render_parsing_rules(ParsingRuleListResponse(rules=[- ParsingRuleInfo(id=4, pattern="*.pdf", tier="basic", page_range="1~2", remote=True, name="pdfs")+ ParsingRuleInfo(id=4, pattern="*.pdf", tier="basic", page_range="1-2", remote=True, name="pdfs")]))@@ -436,7 +436,7 @@ def test_config_and_rule_renderers_return_tables(monkeypatch: Any) -> None:assert exclude_table.title == "Exclude Rules"assert ("3", "*.tmp", "10") in exclude_table.rowsassert parsing_table.title == "Parsing Rules"- assert ("4", "*.pdf", "basic", "1~2", "yes", "pdfs") in parsing_table.rows+ assert ("4", "*.pdf", "basic", "1-2", "yes", "pdfs") in parsing_table.rowsdef test_watch_list_renderer_returns_table(monkeypatch: Any) -> None:@@ -738,7 +738,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_psha256="a" * 64,short_id="aaaaaaa",tier="standard",- page_range="1~10",+ page_range="1-10",status="failed",privacy="remote",created_at=1,@@ -751,7 +751,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_psha256="a" * 64,short_id="aaaaaaa",tier="standard",- page_range="1~10",+ page_range="1-10",status="done",privacy="remote",via="remote",@@ -768,7 +768,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_preturn ParseResponse(sha256="a" * 64,tier="standard",- page_range="1~10",+ page_range="1-10",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -785,7 +785,7 @@ def test_parse_wait_ignores_failed_rows_outside_wait_ids(monkeypatch: Any, tmp_ptier="standard",format="markdown",content="parsed",- request_scope=ContentRequestScope(page_range="1~10", after=None, limit=30000),+ request_scope=ContentRequestScope(page_range="1-10", after=None, limit=30000),)monkeypatch.setattr(parse, "DoclibClient", _Client)@@ -810,7 +810,7 @@ def test_parse_wait_json_maps_invalid_api_key_param(monkeypatch: Any, tmp_path:sha256="a" * 64,short_id="aaaaaaa",tier="standard",- page_range="1~1",+ page_range="1-1",status="failed",privacy="remote",created_at=3,@@ -827,7 +827,7 @@ def test_parse_wait_json_maps_invalid_api_key_param(monkeypatch: Any, tmp_path:return ParseResponse(sha256="a" * 64,tier="standard",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -917,7 +917,7 @@ def test_parse_verbose_json_writes_cache_hit_notice_to_stderr(monkeypatch: Any,assert timeout == 90def ensure_parse(self, request: Any) -> ParseResponse:- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~1", status="done", cache_hit=True)+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-1", status="done", cache_hit=True)def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:return DocContentResponse(@@ -926,7 +926,7 @@ def test_parse_verbose_json_writes_cache_hit_notice_to_stderr(monkeypatch: Any,tier="flash",format="markdown",content="parsed",- request_scope=ContentRequestScope(page_range="1~1", limit=30000),+ request_scope=ContentRequestScope(page_range="1-1", limit=30000),)monkeypatch.setattr(parse, "DoclibClient", _Client)@@ -950,7 +950,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_sha256="a" * 64,short_id="aaaaaaa",tier="flash",- page_range="1~1",+ page_range="1-1",status="done",privacy="local",created_at=3,@@ -966,7 +966,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_return ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -982,7 +982,7 @@ def test_parse_verbose_json_writes_queue_notice_to_stderr(monkeypatch: Any, tmp_tier="flash",format="markdown",content="parsed",- request_scope=ContentRequestScope(page_range="1~1", limit=30000),+ request_scope=ContentRequestScope(page_range="1-1", limit=30000),)monkeypatch.setattr(parse, "DoclibClient", _Client)@@ -1114,20 +1114,20 @@ def test_parse_ingest_error_json_is_machine_readable(monkeypatch: Any, tmp_path:def test_parse_next_marker_quotes_windows_path() -> None:path = r"C:\Users\jinzhenj\Downloads\2606.20787v1.pdf"- marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7~10"))+ marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7-10"))assert marker is not Nonecommand = marker.removeprefix("<!-- Next: ").removesuffix(" -->")- assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7~10"]+ assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7-10"]def test_parse_next_marker_escapes_double_quotes_in_path() -> None:path = r'C:\Users\jinzhenj\Downloads\bad"name.pdf'- marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7~10"))+ marker = parse._parse_next_marker(path, ContentNextRequest(page_range="7-10"))assert marker is not Nonecommand = marker.removeprefix("<!-- Next: ").removesuffix(" -->")- assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7~10"]+ assert shlex.split(command) == ["mineru", "parse", path, "--pages", "7-10"]def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tmp_path: Path) -> None:@@ -1141,7 +1141,7 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tmdef ensure_parse(self, request: Any) -> ParseResponse:assert request.tier == "flash"assert request.remote is True- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~10", status="done", cache_hit=True)+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-10", status="done", cache_hit=True)def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:assert kwargs["limit"] == 30000@@ -1151,8 +1151,8 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tmtier="flash",format="markdown",content="parsed",- request_scope=ContentRequestScope(page_range="1~10", limit=30000),- next_request=ContentNextRequest(page_range="11~20"),+ request_scope=ContentRequestScope(page_range="1-10", limit=30000),+ next_request=ContentNextRequest(page_range="11-20"),)monkeypatch.setattr(parse, "DoclibClient", _Client)@@ -1172,7 +1172,7 @@ def test_parse_next_marker_preserves_explicit_parse_context(monkeypatch: Any, tm"--limit","30000","--pages",- "11~20",+ "11-20",]@@ -1187,7 +1187,7 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_patdef ensure_parse(self, request: Any) -> ParseResponse:assert request.tier is Noneassert request.remote is False- return ParseResponse(sha256="a" * 64, tier="basic", page_range="1~10", status="done", cache_hit=True)+ return ParseResponse(sha256="a" * 64, tier="basic", page_range="1-10", status="done", cache_hit=True)def get_doc_content(self, *args: Any, **kwargs: Any) -> DocContentResponse:assert kwargs["limit"] == 30000@@ -1197,8 +1197,8 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_pattier="basic",format="markdown",content="parsed",- request_scope=ContentRequestScope(page_range="1~10", limit=30000),- next_request=ContentNextRequest(page_range="11~20"),+ request_scope=ContentRequestScope(page_range="1-10", limit=30000),+ next_request=ContentNextRequest(page_range="11-20"),)monkeypatch.setattr(parse, "DoclibClient", _Client)@@ -1208,7 +1208,7 @@ def test_parse_next_marker_omits_default_parse_context(monkeypatch: Any, tmp_patassert result.exit_code == 0marker = result.output.strip().splitlines()[-1]command = marker.removeprefix("<!-- Next: ").removesuffix(" -->")- assert shlex.split(command) == ["mineru", "parse", str(source.resolve()), "--pages", "11~20"]+ assert shlex.split(command) == ["mineru", "parse", str(source.resolve()), "--pages", "11-20"]def test_parse_json_no_wait_wraps_parse_and_null_content(monkeypatch: Any, tmp_path: Path) -> None:@@ -1223,7 +1223,7 @@ def test_parse_json_no_wait_wraps_parse_and_null_content(monkeypatch: Any, tmp_preturn ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1252,7 +1252,7 @@ def test_parse_no_wait_text_prints_parse_id_tracking_hint(monkeypatch: Any, tmp_return ParseResponse(sha256="a" * 64,tier="standard",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[4686],created_parse_ids=[4686],@@ -1282,7 +1282,7 @@ def test_parse_no_wait_text_prints_multiple_parse_id_tracking_hints(monkeypatch:return ParseResponse(sha256="a" * 64,tier="standard",- page_range="1~2",+ page_range="1-2",status="pending",wait_parse_ids=[4686, 4687],created_parse_ids=[4687],@@ -1319,7 +1319,7 @@ def test_parse_expands_user_home_in_input_path(monkeypatch: Any, tmp_path: Path)return ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1386,7 +1386,7 @@ def test_parse_json_output_writes_file_and_returns_output_object(monkeypatch: Anassert timeout == 90def ensure_parse(self, request: Any) -> ParseResponse:- return ParseResponse(sha256="a" * 64, tier="flash", page_range="1~1", status="done", cache_hit=True)+ return ParseResponse(sha256="a" * 64, tier="flash", page_range="1-1", status="done", cache_hit=True)def export_doc_content(self, doc_ref: str, request: Any) -> Any:Path(request.output).write_text("exported", encoding="utf-8")@@ -1414,7 +1414,7 @@ def test_parse_wait_status_line_is_verbose_only(monkeypatch: Any, tmp_path: Pathsha256="a" * 64,short_id="aaaaaaa",tier="flash",- page_range="1~1",+ page_range="1-1",status="done",privacy="local",via="local",@@ -1431,7 +1431,7 @@ def test_parse_wait_status_line_is_verbose_only(monkeypatch: Any, tmp_path: Pathreturn ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1472,7 +1472,7 @@ def test_parse_wait_timeout_json_returns_timeout_error(monkeypatch: Any, tmp_patsha256="a" * 64,short_id="aaaaaaa",tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",privacy="local",via="local",@@ -1488,7 +1488,7 @@ def test_parse_wait_timeout_json_returns_timeout_error(monkeypatch: Any, tmp_patreturn ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1528,7 +1528,7 @@ def test_parse_wait_timeout_text_returns_nonzero_exit(monkeypatch: Any, tmp_pathreturn ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1559,7 +1559,7 @@ def test_parse_wait_timeout_json_uses_latest_parsing_status(monkeypatch: Any, tmsha256="a" * 64,short_id="aaaaaaa",tier="flash",- page_range="1~1",+ page_range="1-1",status="parsing",privacy="local",via="local",@@ -1575,7 +1575,7 @@ def test_parse_wait_timeout_json_uses_latest_parsing_status(monkeypatch: Any, tmreturn ParseResponse(sha256="a" * 64,tier="flash",- page_range="1~1",+ page_range="1-1",status="pending",wait_parse_ids=[3],created_parse_ids=[3],@@ -1709,7 +1709,7 @@ def test_parse_rejects_reverse_page_range_as_json_error(monkeypatch: Any, tmp_pamonkeypatch.setattr(parse, "DoclibClient", _Client)- result = runner.invoke(app, ["parse", str(source), "--tier", "flash", "--pages", "2~1", "--json"])+ result = runner.invoke(app, ["parse", str(source), "--tier", "flash", "--pages", "2-1", "--json"])assert result.exit_code == 1payload = json.loads(result.output)diff --git a/tests/unittest/test_doclib_cache_semantics.py b/tests/unittest/test_doclib_cache_semantics.pyindex b8bae2ec..7cb7675c 100644--- a/tests/unittest/test_doclib_cache_semantics.py+++ b/tests/unittest/test_doclib_cache_semantics.py@@ -319,12 +319,12 @@ def test_load_pages_from_done_batches_keeps_newest_page_idx(tmp_path: Path) -> N"blocks": [{"type": "text", "index": 0, "bbox": [0.0, 0.0, 0.1, 0.1], "content": _inline("newer")}],}- _write_batch(tmp_path, sha256, tier, "1~2", 1000, [older_page, older_duplicate])+ _write_batch(tmp_path, sha256, tier, "1-2", 1000, [older_page, older_duplicate])_write_batch(tmp_path, sha256, tier, "2", 2000, [newer_duplicate])done_rows = [{"page_range": "2", "done_at": 2000},- {"page_range": "1~2", "done_at": 1000},+ {"page_range": "1-2", "done_at": 1000},]pages = load_pages_from_done_batches(str(tmp_path), sha256, tier, done_rows)@@ -1225,24 +1225,24 @@ def test_compaction_uses_configured_data_dir(tmp_path: Path) -> None:older_duplicate = {"page_idx": 1, "content": "old"}newer_duplicate = {"page_idx": 1, "content": "new"}- _write_batch(tmp_path, sha256, tier, "1~2", 1000, [older_page, older_duplicate])+ _write_batch(tmp_path, sha256, tier, "1-2", 1000, [older_page, older_duplicate])_write_batch(tmp_path, sha256, tier, "2", 2000, [newer_duplicate])compaction = Compaction(db=None, interval_sec=600, data_dir=str(tmp_path))done_rows = [{"page_range": "2", "done_at": 2000},- {"page_range": "1~2", "done_at": 1000},+ {"page_range": "1-2", "done_at": 1000},]- asyncio.run(compaction._compact_json(sha256, tier, ["1~2"], done_rows, 2000))+ asyncio.run(compaction._compact_json(sha256, tier, ["1-2"], done_rows, 2000))- compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~2", 2000))+ compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-2", 2000))compacted = json.loads(compacted_path.read_text(encoding="utf-8"))assert compacted["schema_version"] == MIDDLE_JSON_SCHEMA_VERSIONassert compacted["is_full_document"] is Trueassert compacted["pages"] == [older_page, newer_duplicate]- assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1~2_2000.json"]+ assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1-2_2000.json"]def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -> None:@@ -1263,13 +1263,13 @@ def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -await db.execute("INSERT INTO parses (sha256, tier, page_range, status, done_at, created_at, updated_at) ""VALUES (?, ?, ?, ?, ?, ?, ?)",- (sha256, tier, "1~10", "done", done_at, done_at, done_at),+ (sha256, tier, "1-10", "done", done_at, done_at, done_at),)_write_batch(tmp_path,sha256,tier,- "1~10",+ "1-10",done_at,[{"page_idx": page_idx, "blocks": []} for page_idx in range(12)],file_suffix="epub",@@ -1280,13 +1280,13 @@ def test_compaction_repairs_underreported_full_document_ranges(tmp_path: Path) -rows = await db.fetchall("SELECT page_range, done_at FROM parses WHERE sha256=? AND tier=?", (sha256, tier))doc = await db.fetchone("SELECT page_count FROM docs WHERE sha256=?", (sha256,))- compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~12", 2000))+ compacted_path = Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-12", 2000))compacted = json.loads(compacted_path.read_text(encoding="utf-8"))- assert rows == [{"page_range": "1~12", "done_at": 2000}]+ assert rows == [{"page_range": "1-12", "done_at": 2000}]assert doc == {"page_count": 12}assert compacted["is_full_document"] is Trueassert [page["page_idx"] for page in compacted["pages"]] == list(range(12))- assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1~12_2000.json"]+ assert sorted(path.name for path in compacted_path.parent.glob("*.json")) == ["1-12_2000.json"]asyncio.run(_run())@@ -1305,7 +1305,7 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)"VALUES (?, ?, ?, ?, ?, ?, ?)",(sha256, "eeeeeee", 1, "epub", 12, 1, 1),)- for page_range, done_at in (("1~10", 1000), ("11~12", 2000)):+ for page_range, done_at in (("1-10", 1000), ("11-12", 2000)):await db.execute("INSERT INTO parses (sha256, tier, page_range, status, done_at, created_at, updated_at) ""VALUES (?, ?, ?, ?, ?, ?, ?)",@@ -1315,7 +1315,7 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)tmp_path,sha256,tier,- "1~10",+ "1-10",1000,[{"page_idx": page_idx, "blocks": []} for page_idx in range(10)],file_suffix="epub",@@ -1327,8 +1327,8 @@ def test_compaction_keeps_rows_when_any_source_batch_is_missing(tmp_path: Path)"SELECT page_range, done_at FROM parses WHERE sha256=? AND tier=? ORDER BY done_at",(sha256, tier),)- assert rows == [{"page_range": "1~10", "done_at": 1000}, {"page_range": "11~12", "done_at": 2000}]- assert Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1~10", 1000)).is_file()+ assert rows == [{"page_range": "1-10", "done_at": 1000}, {"page_range": "11-12", "done_at": 2000}]+ assert Path(parse_batch_json_path(str(tmp_path), sha256, tier, "1-10", 1000)).is_file()asyncio.run(_run())@@ -1970,7 +1970,7 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:"id": 10,"sha256": sha256,"tier": "standard",- "page_range": "1~5",+ "page_range": "1-5","status": "done","priority": 0,"done_at": 1000,@@ -1980,7 +1980,7 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:"id": 11,"sha256": sha256,"tier": "standard",- "page_range": "6~8",+ "page_range": "6-8","status": "pending","priority": 0,"done_at": None,@@ -2004,18 +2004,18 @@ def test_force_request_reuses_active_and_creates_only_uncovered_parse(tmp_path:)service = ParseService(db=db, fts=_FakeFTS(), config_svc=None, data_dir=str(tmp_path), parse_lock_timeout_sec=1800)- result = asyncio.run(service.request_parse(path, tier="standard", page_range="1~10", force=True))+ result = asyncio.run(service.request_parse(path, tier="standard", page_range="1-10", force=True))assert isinstance(result, ParseResponse)assert result.wait_parse_ids == [11, 12]assert result.reused_parse_ids == [11]assert result.created_parse_ids == [12]- assert result.page_range == "1~10"+ assert result.page_range == "1-10"assert result.short_id == "eeeeeee"assert result.status == "pending"assert result.cache_hit is Falseassert db.updated_priorities == [11]- assert parses[-1]["page_range"] == "1~5,9~10"+ assert parses[-1]["page_range"] == "1-5,9-10"def test_non_pdf_requests_use_one_full_document_batch(@@ -2059,7 +2059,7 @@ def test_non_pdf_requests_use_one_full_document_batch(monkeypatch.setattr(parse_svc_module, "extract_metadata", _metadata)initial = await service.request_parse(str(source))- assert initial.page_range == "1~12"+ assert initial.page_range == "1-12"assert initial.created_parse_ids == []assert len(initial.reused_parse_ids) == 1initial_id = initial.reused_parse_ids[0]@@ -2069,41 +2069,41 @@ def test_non_pdf_requests_use_one_full_document_batch(await db.execute("UPDATE parses SET page_range=?, status=?, done_at=?, updated_at=? WHERE id=?",- ("1~10", "done", 1000, 1000, initial_id),+ ("1-10", "done", 1000, 1000, initial_id),)_write_batch(tmp_path / "data",sha256,"flash",- "1~10",+ "1-10",1000,[{"page_idx": page_idx, "blocks": []} for page_idx in range(12)],file_suffix="epub",)repaired = await service.request_parse(str(source))- assert repaired.page_range == "1~12"+ assert repaired.page_range == "1-12"assert len(repaired.created_parse_ids) == 1repaired_id = repaired.created_parse_ids[0]repaired_row = await db.fetchone("SELECT page_range, status FROM parses WHERE id=?", (repaired_id,))- assert repaired_row == {"page_range": "1~12", "status": "pending"}+ assert repaired_row == {"page_range": "1-12", "status": "pending"}reused = await service.request_parse(str(source), force=True)assert reused.created_parse_ids == []assert reused.reused_parse_ids == [repaired_id]- assert reused.page_range == "1~12"+ assert reused.page_range == "1-12"asyncio.run(_run())def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> None:parses = [- {"id": 1, "sha256": "f" * 64, "tier": "standard", "page_range": "1~5", "status": "done", "done_at": 1000},+ {"id": 1, "sha256": "f" * 64, "tier": "standard", "page_range": "1-5", "status": "done", "done_at": 1000},{"id": 2,"sha256": "f" * 64,"tier": "standard",- "page_range": "6~10",+ "page_range": "6-10","status": "failed","error_code": "parse_failed","error_msg": "boom",@@ -2119,7 +2119,7 @@ def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> Non"id": 2,"sha256": "f" * 64,"tier": "standard",- "page_range": "6~10",+ "page_range": "6-10","status": "failed","done_at": None,"created_at": None,@@ -2130,7 +2130,7 @@ def test_list_parse_records_by_ids_returns_precise_status(tmp_path: Path) -> Non"id": 1,"sha256": "f" * 64,"tier": "standard",- "page_range": "1~5",+ "page_range": "1-5","status": "done","done_at": 1000,"created_at": None,@@ -2149,12 +2149,12 @@ def test_filter_pages_by_user_range_uses_one_based_page_numbers() -> None:def test_expand_page_range_uses_available_subset_and_merges_ranges() -> None:- assert expand_page_range("1~10,3,4~5", 5) == "1~5"+ assert expand_page_range("1-10,3,4-5", 5) == "1-5"def test_expand_page_range_rejects_empty_available_subset() -> None:with pytest.raises(InvalidRequestError) as exc_info:- expand_page_range("6~10", 5)+ expand_page_range("6-10", 5)assert exc_info.value.code == "page_range_invalid"@@ -2173,7 +2173,7 @@ def test_remap_api_result_pages_to_non_contiguous_page_range() -> None:))- _remap_api_result_pages_to_page_range(result, "11,13~14")+ _remap_api_result_pages_to_page_range(result, "11,13-14")assert [page.page_idx for page in result.pages] == [10, 12, 13]@@ -2213,7 +2213,7 @@ def test_remap_api_result_pages_rejects_count_mismatch() -> None:)with pytest.raises(ParseFailure) as exc:- _remap_api_result_pages_to_page_range(result, "11~13")+ _remap_api_result_pages_to_page_range(result, "11-13")assert exc.value.code == "parse_page_remap_failed"@@ -3673,7 +3673,7 @@ def test_read_locator_out_of_range_page_returns_page_range_invalid(tmp_path: Patassert exc_info.value.code == "page_range_invalid"assert exc_info.value.param == "page_range"- assert exc_info.value.message == "Page range does not select any pages: 500"+ assert "500" in exc_info.value.message and "available pages" in exc_info.value.messagefinally:await db.close()@@ -4680,7 +4680,7 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:"id": 1,"sha256": sha256,"tier": "flash",- "page_range": "1~10",+ "page_range": "1-10","status": "parsing","privacy": "local",}@@ -4714,7 +4714,7 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:async def _parse(file_row: dict, tier: Tier, page_range: str) -> ParseResult:"""返回十二页整本 EPUB 结果。"""- assert page_range == "1~10"+ assert page_range == "1-10"return ParseResult(middle_json=MiddleJson(pages=[PageInfo(page_idx=page_idx) for page_idx in range(12)],@@ -4736,11 +4736,11 @@ def test_process_doc_normalizes_full_document_range_from_actual_pages(tmp_path:assert asyncio.run(service.process_doc(task)) is Trueassert parses[0]["status"] == "done"- assert parses[0]["page_range"] == "1~12"+ assert parses[0]["page_range"] == "1-12"assert doc_row["page_count"] == 12- batch_path = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1~12", parses[0]["done_at"]))+ batch_path = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-12", parses[0]["done_at"]))assert batch_path.is_file()- assert not Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1~10", parses[0]["done_at"])).exists()+ assert not Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-10", parses[0]["done_at"])).exists()assert len(json.loads(batch_path.read_text(encoding="utf-8"))["pages"]) == 12diff --git a/tests/unittest/test_doclib_interface_contract.py b/tests/unittest/test_doclib_interface_contract.pyindex b201ac35..d2c0e53e 100644--- a/tests/unittest/test_doclib_interface_contract.py+++ b/tests/unittest/test_doclib_interface_contract.py@@ -363,7 +363,7 @@ def test_cleanup_temp_rejects_negative_older_than(tmp_path) -> None:def test_core_doclib_schemas_are_instantiable() -> None:- parse_request = ParseRequest(path="/tmp/a.pdf", tier=None, page_range="1~5")+ parse_request = ParseRequest(path="/tmp/a.pdf", tier=None, page_range="1-5")forget_request = ForgetPathRequest(path="/tmp/a.pdf")forget_response = ForgetPathResponse(path="/tmp/a.pdf", matched_as="file", forgotten_files=1, dry_run=True)scan_request = ScanRequest(path="/tmp", kind="manual", source="cli")@@ -436,7 +436,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:sha256="abc",short_id="abc",tier="standard",- page_range="1~2",+ page_range="1-2",status="pending",priority=10,privacy="local",@@ -447,7 +447,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:error_code="parse_failed",error_msg="failed",)- tier_info = TierParseInfo(tier="standard", page_range="1~2", status="pending")+ tier_info = TierParseInfo(tier="standard", page_range="1-2", status="pending")info = FileInfoResponse(file=file_info,doc=doc_info,@@ -456,7 +456,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:)watch = WatchInfo(id=1, path="/tmp", recursive=True, status="active", last_scan_at=100, last_scan_files=3)exclude_rule = ExcludeRuleInfo(id=2, pattern="*.tmp", hit_count=4)- parsing_rule = ParsingRuleInfo(id=3, pattern="*.pdf", tier="standard", page_range="1~5", remote=True)+ parsing_rule = ParsingRuleInfo(id=3, pattern="*.pdf", tier="standard", page_range="1-5", remote=True)watches = WatchListResponse(watches=[watch])exclude_rules = ExcludeRuleListResponse(rules=[exclude_rule])parsing_rules = ParsingRuleListResponse(rules=[parsing_rule])@@ -498,7 +498,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:remove_exclude_response = RemoveExcludeRuleResponse(rule_id=2, removed=True)remove_parsing_response = RemoveParsingRuleResponse(rule_id=3, removed=True)exclude_rule_request = ExcludeRuleRequest(pattern="*.tmp")- parsing_rule_request = ParsingRuleRequest(pattern="*.pdf", tier="standard", page_range="1~5")+ parsing_rule_request = ParsingRuleRequest(pattern="*.pdf", tier="standard", page_range="1-5")error_info = ErrorInfo(type="invalid_request_error", code="file_not_found", message="missing", param="path")error_response = ErrorResponse(error=error_info)@@ -555,7 +555,7 @@ def test_core_doclib_schemas_are_instantiable() -> None:def test_parse_request_rejects_auto_tier() -> None:with pytest.raises(ValidationError):- ParseRequest(path="/tmp/a.pdf", tier="auto", page_range="1~5")+ ParseRequest(path="/tmp/a.pdf", tier="auto", page_range="1-5")def test_parse_response_status_is_submit_state_only() -> None:diff --git a/tests/unittest/test_doclib_progressive_reading.py b/tests/unittest/test_doclib_progressive_reading.pyindex 207dafb7..81eef5e5 100644--- a/tests/unittest/test_doclib_progressive_reading.py+++ b/tests/unittest/test_doclib_progressive_reading.py@@ -23,22 +23,22 @@ def _page(page_idx: int, *texts: str) -> PageInfo:def test_paginated_default_content_pages_are_first_ten() -> None:doc = {"page_count": 38}- assert _normalize_content_page_range(None, None, doc) == "1~10"- assert _normalize_content_page_range("all", None, doc) == "1~38"- assert _normalize_content_page_range("1~5,-5~-1", None, doc) == "1~5,34~38"+ assert _normalize_content_page_range(None, None, doc) == "1-10"+ assert _normalize_content_page_range("all", None, doc) == "1-38"+ assert _normalize_content_page_range("1-5,r5-r1", None, doc) == "1-5,34-38"def test_content_page_range_uses_available_subset_and_merges_ranges() -> None:doc = {"page_count": 5}- assert _normalize_content_page_range("1~10,3,4~5", None, doc) == "1~5"+ assert _normalize_content_page_range("1-10,3,4-5", None, doc) == "1-5"def test_content_page_range_rejects_empty_available_subset() -> None:doc = {"page_count": 5}with pytest.raises(InvalidRequestError) as exc_info:- _normalize_content_page_range("6~10", None, doc)+ _normalize_content_page_range("6-10", None, doc)assert exc_info.value.code == "page_range_invalid"@@ -48,16 +48,16 @@ def test_paginated_page_boundary_truncation_suggests_pages_only() -> None:rendered = _render_progressive_markdown(pages, short_id="ab12cd3", tier="standard", after=None, limit=40, add_markers=False)next_request = _next_content_request(rendered=rendered,- request_page_range="1~10",+ request_page_range="1-10",after=None,page_count=38,paginated=True,)assert rendered.truncated is True- assert rendered.content_ranges[0].page_range == "1~5"+ assert rendered.content_ranges[0].page_range == "1-5"assert next_request is not None- assert next_request.page_range == "6~10"+ assert next_request.page_range == "6-10"assert next_request.after is None@@ -66,7 +66,7 @@ def test_paginated_long_single_page_truncation_keeps_pages_with_after() -> None:rendered = _render_progressive_markdown(pages, short_id="ab12cd3", tier="standard", after=None, limit=40, add_markers=False)next_request = _next_content_request(rendered=rendered,- request_page_range="7~10",+ request_page_range="7-10",after=None,page_count=38,paginated=True,@@ -75,7 +75,7 @@ def test_paginated_long_single_page_truncation_keeps_pages_with_after() -> None:assert rendered.truncated is Trueassert rendered.content_ranges[-1].end.startswith("doc:ab12cd3/tier:standard/page:7/block:1/char:")assert next_request is not None- assert next_request.page_range == "7~10"+ assert next_request.page_range == "7-10"assert next_request.after == rendered.content_ranges[-1].end@@ -113,14 +113,14 @@ def test_non_contiguous_pages_suggest_after_last_requested_page() -> None:)next_request = _next_content_request(rendered=rendered,- request_page_range="1~5,20~25",+ request_page_range="1-5,20-25",after=None,page_count=38,paginated=True,)assert next_request is not None- assert next_request.page_range == "26~35"+ assert next_request.page_range == "26-35"def test_truncated_false_can_still_have_next_request() -> None:@@ -134,7 +134,7 @@ def test_truncated_false_can_still_have_next_request() -> None:)next_request = _next_content_request(rendered=rendered,- request_page_range="1~10",+ request_page_range="1-10",after=None,page_count=38,paginated=True,@@ -142,7 +142,7 @@ def test_truncated_false_can_still_have_next_request() -> None:assert rendered.truncated is Falseassert next_request is not None- assert next_request.page_range == "11~20"+ assert next_request.page_range == "11-20"def test_paginated_next_request_is_never_after_only() -> None:@@ -164,14 +164,14 @@ def test_paginated_next_request_is_never_after_only() -> None:"cut_inside_page": True,},)(),- request_page_range="7~10",+ request_page_range="7-10",after=None,page_count=38,paginated=True,)assert next_request is not None- assert next_request.page_range == "7~10"+ assert next_request.page_range == "7-10"assert next_request.after is not Nonediff --git a/tests/unittest/test_doclib_telemetry_core.py b/tests/unittest/test_doclib_telemetry_core.pyindex e4a71a3a..f81b1550 100644--- a/tests/unittest/test_doclib_telemetry_core.py+++ b/tests/unittest/test_doclib_telemetry_core.py@@ -463,7 +463,7 @@ def test_parse_wait_observation_uses_parse_rows_for_tier_and_pages_bucket(tmp_pa)await db.execute("INSERT INTO parses (sha256, tier, page_range, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)",- ("sha", "standard", "1~3", "done", now, now),+ ("sha", "standard", "1-3", "done", now, now),)row = await db.fetchone("SELECT id FROM parses WHERE sha256=?", ("sha",))diff --git a/tests/unittest/test_flash_epub.py b/tests/unittest/test_flash_epub.pyindex a20fba47..5d9cc70b 100644--- a/tests/unittest/test_flash_epub.py+++ b/tests/unittest/test_flash_epub.py@@ -410,11 +410,11 @@ def test_public_parser_rejects_epub_page_range(tmp_path: Path) -> None:source.write_bytes(build_epub_fixture())with pytest.raises(InvalidRequestError, match="only supported for PDF") as exc_info:- parse(source, page_range="2~3")+ parse(source, page_range="2-3")assert exc_info.value.code == "page_range_invalid"with pytest.raises(InvalidRequestError, match="only supported for PDF"):- asyncio.run(parse_async(source, page_range="2~3"))+ asyncio.run(parse_async(source, page_range="2-3"))@pytest.mark.parametrize(@@ -976,7 +976,7 @@ def test_doclib_ingests_epub_as_local_flash_with_spine_page_count(tmp_path: Path)assert response.tier == "flash"assert doc == {"file_type": "epub", "page_count": 3}- assert parses == [{"tier": "flash", "status": "pending", "privacy": "local", "page_range": "1~3"}]+ assert parses == [{"tier": "flash", "status": "pending", "privacy": "local", "page_range": "1-3"}]with pytest.raises(InvalidRequestError) as range_exc:await service.request_parse(str(source), tier="flash", page_range="2")@@ -1005,7 +1005,7 @@ def test_doclib_local_epub_task_clears_persisted_full_page_range(monkeypatch: pyservice._parse_via_local( # type: ignore[arg-type]{"path": "/tmp/book.epub", "ext": "epub"},"flash",- "1~3",+ "1-3",))assert result is expecteddiff --git a/tests/unittest/test_kit_gradio.py b/tests/unittest/test_kit_gradio.pyindex b015cac0..f6711950 100644--- a/tests/unittest/test_kit_gradio.py+++ b/tests/unittest/test_kit_gradio.py@@ -8,6 +8,7 @@ import zipfilefrom pathlib import Pathfrom types import SimpleNamespacefrom typing import Any+from unittest.mock import AsyncMockimport httpximport pytest@@ -398,15 +399,15 @@ def test_v1_client_preserves_v1_error_code(monkeypatch: pytest.MonkeyPatch, tmp_async def parse_async(self, _path: Path, *, page_range: str) -> ParseResult:"""抛出与正式 API client 一致的错误形态。"""error = RuntimeError(f"bad range: {page_range}")- error.code = "invalid_page_range" # type: ignore[attr-defined]+ error.code = "page_range_invalid" # type: ignore[attr-defined]raise errormonkeypatch.setattr(gradio_client, "MinerUApiParser", FailingParser)client = V1ArtifactClient(api_url="http://example.test")client._capabilities = V1ServerCapabilities("http://example.test", ("flash",), ("zip",), ("file_id",))with pytest.raises(V1ArtifactError) as error:- asyncio.run(client.parse_file(source, tier="flash", page_range="bad"))- assert error.value.code == "invalid_page_range"+ asyncio.run(client.parse_file(source, tier="flash", page_range="999"))+ assert error.value.code == "page_range_invalid"def test_v1_client_parse_uses_api_parser_zip_contract(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:@@ -437,12 +438,12 @@ def test_v1_client_parse_uses_api_parser_zip_contract(monkeypatch: pytest.Monkey("file_id",),)statuses: list[str] = []- result = asyncio.run(client.parse_file(source, tier="standard", page_range="1~2", status_callback=statuses.append))+ result = asyncio.run(client.parse_file(source, tier="standard", page_range="1-2", status_callback=statuses.append))assert isinstance(result, ParseResult)assert calls["include_images"] is Trueassert calls["include_model_output"] is Trueassert calls["tier"] == "standard"- assert calls["page_range"] == "1~2"+ assert calls["page_range"] == "1-2"assert statuses[0] == "Preparing request..."assert statuses[-1] == STATUS_DOWNLOADING_RESULT@@ -625,7 +626,7 @@ def test_page_range_image_crops_follow_original_page_indices(tmp_path: Path) ->ParseResult(middle_json=_middle_json(page_indices=(1, 2))),source,output_root=tmp_path / "output",- page_range="2~3",+ page_range="2-3",)images = sorted((artifacts.root / "images").glob("*.jpg"))assert len(images) == 2@@ -644,7 +645,7 @@ def test_persist_page_range_keeps_cropped_origin_page_order(tmp_path: Path) -> NParseResult(middle_json=_middle_json(with_image=False, page_indices=(1, 2))),source,output_root=tmp_path / "output",- page_range="2~3",+ page_range="2-3",)assert artifacts.page_indices == (1, 2)assert artifacts.origin_pdf_path is not None@@ -701,8 +702,8 @@ def test_render_download_rejects_state_outside_allowed_root(tmp_path: Path) -> Ndef test_gradio_file_types_page_range_and_header_follow_new_contract() -> None:"""验证完整扩展名、PDF-only 页码规则和复用后的 Header。"""assert set(gradio_app._supported_file_types()) == {f".{extension}" for extension in PARSEABLE_EXTENSIONS}- assert gradio_app._effective_page_range("report.PDF", " 1~3,-1 ") == "1~3,-1"- assert gradio_app._effective_page_range("report.docx", "1~3") == ""+ assert gradio_app._effective_page_range("report.PDF", " 1-3,r1 ") == "1-3,r1"+ assert gradio_app._effective_page_range("report.docx", "1-3") == ""header = gradio_app._render_header(gradio_major_version=6)assert "mineru-gradio6-header" in headerassert "mineru-header-popover mineru-model-popover" in header@@ -742,8 +743,60 @@ def test_build_gradio_app_exposes_three_tabs_and_download_menu(tmp_path: Path) -assert sum(1 for dependency in app.config["dependencies"] if dependency.get("queue") is True) >= 7-def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_path: Path) -> None:- """验证转换事件透传 PDF page_range,并只在新结果完成后启用下载。"""+ ("tiers", "default_position", "default_tier", "maximum"),+ [+ (("advanced", "flash", "standard", "basic"), 2, "standard", 3),+ (("advanced", "standard", "basic"), 1, "standard", 2),+ (("advanced", "flash"), 1, "advanced", 1),+ (("basic", "flash"), 1, "basic", 1),+ (("flash",), 0, "flash", 1),+ (("advanced",), 0, "advanced", 1),+ ],+)+def test_gradio_tier_slider_uses_available_tiers_and_preserves_selection(+ tmp_path: Path, tiers: tuple[str, ...], default_position: int, default_tier: str, maximum: int+) -> None:+ """验证乱序、缺档及单档位下的原生滑块默认值与文件切换、清除行为。"""+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))+ demo = build_gradio_app(+ V1ArtifactClient(api_url=capabilities.base_url), capabilities, output_root=tmp_path, enable_example=False+ )+ slider = next(block for block in demo.blocks.values() if block.__class__.__name__ == "Slider")+ label = next(block for block in demo.blocks.values() if "mineru-tier-label" in (block.elem_classes or []))+ assert (slider.minimum, slider.maximum, slider.step, slider.precision) == (0, maximum, 1, 0)+ assert slider.value == default_position+ assert slider.interactive is (len(tiers) > 1)+ assert label.value == f"解析 tier:{default_tier}"+ assert not any(block.__class__.__name__ == "Dropdown" for block in demo.blocks.values())+ label_event = next(event for event in demo.config["dependencies"] if event["targets"] == [(slider._id, "input")])+ assert label_event["backend_fn"] is False+ assert label_event["queue"] is False+ assert label_event["outputs"] == [label._id]+ for fn in demo.fns.values():+ if fn.name in {"update_file_preview", "reset_ui"}:+ assert slider not in fn.outputs and label not in fn.outputs+ if fn.name == "convert_handler":+ assert fn.inputs[1] is slider+ assert slider.api_info()["type"] == "integer"+++ ("tiers", "position", "expected_tier"),+ [+ (("advanced", "flash", "standard", "basic"), 0, "flash"),+ (("advanced", "flash", "standard", "basic"), 1, "basic"),+ (("advanced", "flash", "standard", "basic"), 2, "standard"),+ (("advanced", "flash", "standard", "basic"), 3, "advanced"),+ (("advanced", "standard", "basic"), 2, "advanced"),+ (("advanced", "flash"), 1, "advanced"),+ (("flash",), 0, "flash"),+ ],+)+def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(+ tmp_path: Path, tiers: tuple[str, ...], position: int, expected_tier: str+) -> None:+ """验证滑块位置映射与 PDF page_range 透传,并只在新结果完成后启用下载。"""source = tmp_path / "demo.pdf"source.write_bytes(_pdf_bytes())@@ -770,9 +823,9 @@ def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_pasync def collect_updates(handler: Any) -> list[tuple[Any, ...]]:"""收集 Gradio 异步生成器的全部增量输出。"""- return [update async for update in handler(str(source), "flash", " 1 ")]+ return [update async for update in handler(str(source), position, " 1 ")]- capabilities = V1ServerCapabilities("http://127.0.0.1:1", ("flash",), ("zip",), ("file_id",))+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))client = FakeClient()demo = build_gradio_app(client, # type: ignore[arg-type]@@ -783,13 +836,44 @@ def test_gradio_conversion_forwards_page_range_and_enables_fresh_downloads(tmp_pconvert_handler = next(fn.fn for fn in demo.fns.values() if fn.name == "convert_handler")updates = asyncio.run(collect_updates(convert_handler))- assert client.calls == [(source.resolve(), "flash", "1")]+ assert client.calls == [(source.resolve(), expected_tier, "1")]assert len(updates[-1]) == 15assert updates[-1][8] is not Noneassert all(update["interactive"] is True and update["value"] is None for update in updates[-1][-6:])assert all(update["interactive"] is False and update["value"] is None for update in updates[0][-6:])+ ("tiers", "position"),+ [+ (("flash", "basic", "standard", "advanced"), -1),+ (("flash", "basic", "standard", "advanced"), 4),+ (("flash",), 1),+ (("flash", "advanced"), 0.5),+ (("flash", "advanced"), float("nan")),+ (("flash", "advanced"), True),+ ],+)+def test_gradio_conversion_rejects_invalid_tier_position(tmp_path: Path, tiers: tuple[str, ...], position: int | float) -> None:+ """验证非法位置会清除结果且不会向解析服务提交请求,包括单档位的占位上界。"""+ source = tmp_path / "demo.csv"+ source.write_text("name,value\na,1\n", encoding="utf-8")+ client = SimpleNamespace(parse_file=AsyncMock())+ capabilities = V1ServerCapabilities("http://127.0.0.1:1", tiers, ("zip",), ("file_id",))+ demo = build_gradio_app(client, capabilities, output_root=tmp_path, enable_example=False)+ handler = next(fn.fn for fn in demo.fns.values() if fn.name == "convert_handler")++ async def collect_updates() -> list[tuple[Any, ...]]:+ """收集非法滑块位置对应的错误输出。"""+ return [update async for update in handler(str(source), position, "")]++ updates = asyncio.run(collect_updates())+ assert "Failed: Invalid tier slider position" in updates[-1][0]+ assert updates[-1][8] is None+ assert all(item["interactive"] is False and item["value"] is None for item in updates[-1][-6:])+ client.parse_file.assert_not_called()++def test_gradio_conversion_failure_clears_previous_downloads(tmp_path: Path) -> None:"""验证解析失败会清空结果 State 并禁用所有旧下载按钮。"""source = tmp_path / "demo.pdf"@@ -804,7 +888,7 @@ def test_gradio_conversion_failure_clears_previous_downloads(tmp_path: Path) ->async def final_update(handler: Any) -> tuple[Any, ...]:"""返回 Gradio 异步生成器的最后一次更新。"""- updates = [update async for update in handler(str(source), "flash", "")]+ updates = [update async for update in handler(str(source), 0, "")]return updates[-1]capabilities = V1ServerCapabilities("http://127.0.0.1:1", ("flash",), ("zip",), ("file_id",))diff --git a/tests/unittest/test_parser_api_contract.py b/tests/unittest/test_parser_api_contract.pyindex c1c9f3fa..2c8d0227 100644--- a/tests/unittest/test_parser_api_contract.py+++ b/tests/unittest/test_parser_api_contract.py@@ -447,10 +447,10 @@ def test_api_client_builds_file_page_range_without_options(tmp_path: Path) -> Nopdf.write_bytes(b"%PDF-1.7\n")parser = MinerUApiParser(api_url="http://localhost:8000", tier="standard")- payload = parser._build_payload({"type": "local", "path": str(pdf)}, "1,3~5")+ payload = parser._build_payload({"type": "local", "path": str(pdf)}, "1,3-5")assert payload["output_formats"] == ["middle_json"]- assert payload["files"] == [{"source": {"type": "local", "path": str(pdf)}, "page_range": "1,3~5"}]+ assert payload["files"] == [{"source": {"type": "local", "path": str(pdf)}, "page_range": "1,3-5"}]assert "options" not in payload["files"][0]diff --git a/tests/unittest/test_pdf_page_id.py b/tests/unittest/test_pdf_page_id.pyindex 28d0d6c5..28a08417 100644--- a/tests/unittest/test_pdf_page_id.py+++ b/tests/unittest/test_pdf_page_id.py@@ -1,26 +1,367 @@from __future__ import annotations+import asyncio+import io+from pathlib import Path+from types import SimpleNamespace+from unittest.mock import AsyncMock, Mock+import pytest+from fastapi.testclient import TestClient+from pypdf import PdfReader+from reportlab.pdfgen import canvas+from typer.testing import CliRunner++from mineru.cli.commands.parse import _validate_page_range_input+from mineru.cli.main import app as cli_app+from mineru.doclib.server import _normalize_content_page_range+from mineru.doclib.services.config_svc import ConfigService+from mineru.doclib.services.parse_svc import default_parse_range+from mineru.errors import InvalidRequestError, MineruError+from mineru.kit.gradio.app import _effective_page_range+from mineru.kit.gradio.artifacts import persist_parse_result+from mineru.kit.gradio.client import V1ArtifactClient+from mineru.kit.main import app as kit_app+from mineru.parser import MinerUParser, api_server+from mineru.parser.api_client import MinerUApiParser+from mineru.parser.page_range import (+ count_pages_in_range,+ expand_page_range,+ format_page_range,+ normalize_page_range_input,+ parse_page_range,+ parse_page_range_set,+)++VALID_RANGES = [+ ("5", [5], "5"),+ ("1-5", [1, 2, 3, 4, 5], "1-5"),+ ("1-3,7,9-10", [1, 2, 3, 7, 9, 10], "1-3,7,9-10"),+ ("3,1-3,2", [1, 2, 3], "1-3"),+ ("all", list(range(1, 11)), "1-10"),+ ("r1", [10], "10"),+ ("r5-r1", [6, 7, 8, 9, 10], "6-10"),+ ("3-r1", list(range(3, 11)), "3-10"),+ (" 1 - 3 , r2 - r1 ", [1, 2, 3, 9, 10], "1-3,9-10"),+ ("8-15", [8, 9, 10], "8-10"),+ ("r20-r8", [1, 2, 3], "1-3"),+ ("1,50", [1], "1"),+ ("5-5", [5], "5"),+]+INVALID_RANGES = [+ "1~5",+ "-1",+ "-5~-1",+ "0",+ "r0",+ "5-",+ "-5",+ "1,,3",+ ",1",+ "1,",+ "1,3",+ "1:5",+ "5-3",+ "r1-r5",+ "all,1",+ "ALL",+ "R1",+ "r 1",+ "01",+ "+1",+ "1",+ "1--5",+]++[email protected](("raw", "page_numbers", "canonical"), VALID_RANGES)+def test_page_selection_contract_across_entrypoints(raw: str, page_numbers: list[int], canonical: str) -> None:+ """同一矩阵覆盖共享解析、Doclib 内容读取、CLI 校验和 Gradio 输入。"""+ _validate_page_range_input(raw)+ assert parse_page_range(raw, 10) == [page - 1 for page in page_numbers]+ assert expand_page_range(raw, 10) == canonical+ assert _normalize_content_page_range(raw, None, {"page_count": 10}) == canonical+ assert expand_page_range(_effective_page_range("demo.pdf", raw), 10) == canonical+ assert parse_page_range_set(canonical) == set(page_numbers)+ assert count_pages_in_range(canonical) == len(page_numbers)+ assert format_page_range(reversed(page_numbers)) == canonical++[email protected]("raw", INVALID_RANGES)+def test_invalid_and_retired_syntax_is_rejected_everywhere(raw: str) -> None:+ """旧语法与非法端点必须在所有校验入口返回稳定页码错误。"""+ for action in (+ lambda: normalize_page_range_input(raw),+ lambda: parse_page_range(raw, 10),+ lambda: expand_page_range(raw, 10),+ lambda: _normalize_content_page_range(raw, None, {"page_count": 10}),+ lambda: _effective_page_range("demo.pdf", raw),+ lambda: _validate_page_range_input(raw),+ ):+ with pytest.raises(MineruError) as error:+ action()+ assert error.value.code == "page_range_invalid"+ assert error.value.type == "invalid_request_error"++[email protected]("raw", ["20", "11-20", "r20-r11", "r11", "8-r5", "1,8-r5"])+def test_resolution_rejects_empty_selection_or_reversed_relative_range(raw: str) -> None:+ """依赖总页数的错误在求值时发生;混合有效选项不能掩盖倒序。"""+ normalize_page_range_input(raw)+ with pytest.raises(InvalidRequestError) as error:+ parse_page_range(raw, 10)+ assert error.value.code == "page_range_invalid"++[email protected]("raw", [None, "", " \t\n"])+def test_unspecified_range_preserves_entrypoint_default(raw: str | None) -> None:+ """空值统一为未指定,但 Doclib 与直接 Parser 保留各自默认窗口。"""+ assert normalize_page_range_input(raw) == ""+ assert parse_page_range(raw or "", 15) == list(range(15))+ assert _normalize_content_page_range(raw, None, {"page_count": 15}) == "1-10"+ assert default_parse_range(1) == "1"+ assert _normalize_content_page_range("all", None, {"page_count": 15}) == "1-15"+++def test_large_ranges_are_clipped_before_expansion() -> None:+ """验证巨大端点只处理实际存在的页面,并以区间计算规范化与统计。"""+ assert parse_page_range("1-999999999999999999", 3) == [0, 1, 2]+ assert expand_page_range("r999999999999999999-r1", 3) == "1-3"+ assert normalize_page_range_input("2,1-999999999999999999") == "1-999999999999999999"+ assert count_pages_in_range("1-999999999999999999,2") == 999999999999999999+ assert parse_page_range_set("") == set()+ assert format_page_range([]) == ""+ assert count_pages_in_range("") == 0+ for raw in ["all", "r1"]:+ with pytest.raises(InvalidRequestError):+ parse_page_range_set(raw)++[email protected]("raw", ["1~5", "-1", "r1-r5"])+def test_remote_clients_validate_before_network(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, raw: str) -> None:+ """同步、异步 API 与 Gradio 客户端在上传或能力发现前拒绝非法表达式。"""+ source = tmp_path / "input.pdf"+ source.write_bytes(b"%PDF-1.7")+ parser = MinerUApiParser(api_url="http://example.test", tier="flash")+ build_source = Mock(side_effect=AssertionError("must not upload"))+ async_build_source = AsyncMock(side_effect=AssertionError("must not upload"))+ monkeypatch.setattr(parser, "_build_source", build_source)+ monkeypatch.setattr(parser, "_async_build_source", async_build_source)+ with pytest.raises(InvalidRequestError):+ parser.parse(source, page_range=raw)+ with pytest.raises(InvalidRequestError):+ asyncio.run(parser.parse_async(source, page_range=raw))+ client = V1ArtifactClient(api_url="http://example.test")+ discover = AsyncMock(side_effect=AssertionError("must not discover"))+ monkeypatch.setattr(client, "discover", discover)+ with pytest.raises(InvalidRequestError):+ asyncio.run(client.parse_file(source, tier="flash", page_range=raw))+ build_source.assert_not_called()+ async_build_source.assert_not_called()+ discover.assert_not_called()+++def test_api_rejects_bad_ranges_before_creating_jobs(tmp_path: Path) -> None:+ """直接 HTTP 请求校验共享语法,错误定位到批量请求的具体文件。"""+ app = api_server.create_app(upload_dir=str(tmp_path / "api"), tier="flash", allow_local_source=True)+ with TestClient(app) as client:+ for raw in INVALID_RANGES:+ response = client.post(+ "/v1/parse/jobs",+ json={+ "tier": "flash",+ "files": [+ {"source": {"type": "local", "path": "/unused.pdf"}},+ {"source": {"type": "local", "path": "/unused.pdf"}, "page_range": raw},+ ],+ },+ )+ assert response.status_code == 400+ error = response.json()["error"]+ assert error["code"] == "page_range_invalid"+ assert error["param"] == "files.1.page_range"+ schema = client.get("/openapi.json").json()+ assert "r1" in schema["components"]["schemas"]["JobFileEntry"]["properties"]["page_range"]["description"]+++def test_cli_rejects_old_syntax_and_kit_preserves_range_error(tmp_path: Path) -> None:+ """两个 CLI 均在执行解析前拒绝旧表达式,主 CLI 返回机器可读错误码。"""+ source = tmp_path / "input.pdf"+ source.write_bytes(b"%PDF-1.7")+ runner = CliRunner()+ for raw in ["1~5", "-1"]:+ result = runner.invoke(cli_app, ["parse", str(source), "--pages", raw, "--json"])+ assert result.exit_code == 1+ assert '"page_range_invalid"' in result.output+ result = runner.invoke(kit_app, ["parse", str(source), "--pages", raw, "-o", str(tmp_path / "out.md")])+ assert result.exit_code == 1+ assert "Invalid page range" in result.output+++def test_parsing_rules_validate_without_a_document() -> None:+ """规则保存前校验表达式,允许暂存 rN/all 并拒绝旧语法。"""+ database = SimpleNamespace(execute_insert=AsyncMock(return_value=7))+ service = ConfigService(database)+ for raw, expected in [(" r3 - r1 ", "r3-r1"), ("all", "all"), (" ", None), ("3,1-3", "1-3")]:+ asyncio.run(service.add_rule("pdfs", "parsing_rule", "*.pdf", page_range=raw))+ assert database.execute_insert.call_args.args[1][3] == expected+ database.execute_insert.reset_mock()+ with pytest.raises(InvalidRequestError):+ asyncio.run(service.add_rule("pdfs", "parsing_rule", "*.pdf", page_range="1~5"))+ database.execute_insert.assert_not_called()+++def _numbered_pdf(path: Path, page_count: int = 5) -> None:+ """创建每页带不同正文的真实 PDF,供裁剪和原始页号验证。"""+ document = canvas.Canvas(str(path), pagesize=(240, 320))+ for page_no in range(1, page_count + 1):+ document.drawString(30, 250, f"Source page {page_no}")+ document.showPage()+ document.save()+++def test_real_pdf_selection_preserves_original_indices_and_artifact_order(tmp_path: Path) -> None:+ """实测非连续选页与末页组合,同时核对解析页号、原始 PDF 和 layout PDF。"""+ source = tmp_path / "numbered.pdf"+ _numbered_pdf(source)+ parser = MinerUParser(tier="flash")+ result = parser.parse(source, page_range="r1,3,1,3")+ assert [page.page_idx for page in result.pages] == [0, 2, 4]+ assert not result.middle_json.is_full_document+ assert "Source page 3" in result.markdown()+ assert "Source page 2" not in result.markdown()+ artifacts = persist_parse_result(result, source, output_root=tmp_path / "review", page_range="r1,3,1,3")+ assert artifacts.page_indices == (0, 2, 4)+ assert artifacts.origin_pdf_path is not None and artifacts.layout_pdf_path is not None+ reader = PdfReader(str(artifacts.origin_pdf_path))+ assert [page.extract_text().strip() for page in reader.pages] == ["Source page 1", "Source page 3", "Source page 5"]+ assert len(PdfReader(str(artifacts.layout_pdf_path)).pages) == 3+ prepared = parser._prepare_input(source, "r1")+ assert prepared.retained_page_indices == [4]+ assert PdfReader(io.BytesIO(prepared.file_bytes)).pages[0].extract_text().strip() == "Source page 5"+++def test_async_job_resolves_relative_ranges_and_reports_file_errors(tmp_path: Path) -> None:+ """后台任务完成后返回规范实际范围,依赖总页数的错误保留文件级错误码。"""+ source = tmp_path / "numbered.pdf"+ _numbered_pdf(source)+ store = api_server.FileStore(tmp_path / "files")+ request = api_server.CreateJobRequest.model_validate(+ {+ "tier": "flash",+ "output_formats": ["middle_json"],+ "files": [+ {"source": {"type": "local", "path": str(source)}, "page_range": "1,r2-r1"},+ {"source": {"type": "local", "path": str(source)}, "page_range": "20"},+ ],+ }+ )+ record = api_server.JobStore().create(request, store)+ asyncio.run(api_server._run_job(record, request, store, ocr_mode="auto", image_analysis=True, allow_local_source=True))+ assert record.status == "partial"+ assert record.files[0].page_range == "1,4-5"+ assert record.files[0].status == "completed"+ assert record.files[1].error.code == "page_range_invalid"+ assert record.files[1].error.param == "page_range"+-from mineru.parser.page_range import parse_page_range+def test_doclib_client_validates_requests_before_transport(monkeypatch: pytest.MonkeyPatch) -> None:+ """Doclib SDK 的解析、查询、导出和规则请求复用校验且不修改调用方模型。"""+ from mineru.doclib.client import DoclibClient+ from mineru.doclib.types import DocContentExportRequest, ParseRequest, ParsingRuleRequest+ client = DoclibClient(base_url="http://example.test")+ transport = Mock()+ monkeypatch.setattr(client, "_request_model", transport)+ actions = (+ lambda: client.ensure_parse(ParseRequest(path="demo.pdf", page_range="1~5")),+ lambda: client.list_parses(page_range="1~5"),+ lambda: client.get_doc_content("a" * 64, tier="flash", page_range="1~5"),+ lambda: client.export_doc_content(+ "a" * 64, DocContentExportRequest(tier="flash", output="out.md", format="markdown", page_range="1~5")+ ),+ lambda: client.add_parsing_rule(ParsingRuleRequest(pattern="*.pdf", page_range="1~5")),+ )+ for action in actions:+ with pytest.raises(InvalidRequestError):+ action()+ transport.assert_not_called()+ request = ParseRequest(path="demo.pdf", page_range=" 3,1-3 ")+ client.ensure_parse(request)+ assert transport.call_args.kwargs["body"].page_range == "1-3"+ assert request.page_range == " 3,1-3 "+ client.close()-def test_parse_page_range_empty_means_all_pages() -> None:- assert parse_page_range("", 5) == [0, 1, 2, 3, 4]+def test_kit_preserves_remote_page_range_error(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """远端返回的页码错误不能在 mineru-kit 中被泛化为 parse_failed。"""+ from mineru.kit.commands import parse as kit_parse+ from mineru.parser.api_client import _V1APIError[email protected]("raw", ["6", "6~8", "0", "-20~-10"])-def test_parse_page_range_explicit_out_of_range_does_not_fallback_to_all_pages(raw: str) -> None:- assert parse_page_range(raw, 5) == []+ source = tmp_path / "input.pdf"+ source.write_bytes(b"%PDF-1.7")+ parser = SimpleNamespace(parse=Mock(side_effect=_V1APIError("page_range_invalid", "empty selection", "page_range")))+ monkeypatch.setattr(kit_parse, "MinerUApiParser", Mock(return_value=parser))+ fail = Mock(side_effect=RuntimeError("captured error"))+ monkeypatch.setattr(kit_parse, "exit_with_message", fail)+ result = CliRunner().invoke(+ kit_app,+ [+ "parse",+ str(source),+ "--remote-url",+ "http://example.test",+ "--pages",+ "r1",+ "-o",+ str(tmp_path / "out.md"),+ ],+ )+ assert result.exit_code != 0+ assert fail.call_args.args[0] == "page_range_invalid"+ assert fail.call_args.args[2] == "page_range"-def test_parse_page_range_explicit_partial_out_of_range_keeps_valid_intersection() -> None:- assert parse_page_range("3~8", 5) == [2, 3, 4]+def test_doclib_relative_selection_coverage_and_export(tmp_path: Path) -> None:+ """真实 SQLite 缓存的覆盖查询与内容导出必须先按文档总页数求值 rN/all。"""+ import json+ from mineru.doclib.core.db import DatabaseManager+ from mineru.doclib.server import DoclibServer+ from mineru.doclib.services.parse_svc import parse_batch_json_path-def test_parse_page_range_expands_deduplicates_and_sorts_available_pages() -> None:- assert parse_page_range("1~10,3,4~5", 5) == [0, 1, 2, 3, 4]+ source = tmp_path / "numbered.pdf"+ _numbered_pdf(source)+ result = MinerUParser(tier="flash").parse(source, page_range="1-3,r1")+ sha256 = "a" * 64+ cache = Path(parse_batch_json_path(str(tmp_path), sha256, "flash", "1-3,5", 1000))+ cache.parent.mkdir(parents=True)+ cache.write_text(json.dumps(result.to_dict()), encoding="utf-8")+ async def verify() -> None:+ """构造实际元数据与缓存记录,验证公开服务读取结果。"""+ db = DatabaseManager(str(tmp_path / "doclib.db"))+ await db.initialize()+ try:+ await db.execute(+ "INSERT INTO docs (sha256, short_id, size_bytes, file_type, page_count, first_seen_at, updated_at) "+ "VALUES (?, ?, ?, ?, ?, ?, ?)",+ (sha256, "aaaaaaa", source.stat().st_size, "pdf", 5, 1000, 1000),+ )+ await db.execute(+ "INSERT INTO parses (sha256, tier, page_range, status, privacy, done_at, created_at, updated_at) "+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",+ (sha256, "flash", "1-3,5", "done", "local", 1000, 1000, 1000),+ )+ server = DoclibServer(SimpleNamespace(db=db, data_dir=str(tmp_path)))+ listing = await server.list_parses(doc_ref="aaaaaaa", tier="flash", page_range="r3-r1")+ assert listing.coverage.done_page_range == "3,5"+ assert listing.coverage.missing_page_range == "4"+ text = await server._render_doc_content(sha256, tier="flash", page_range="r1", format="markdown", no_marker=True)+ assert "Source page 5" in text and "Source page 3" not in text+ text = await server._render_doc_content(sha256, tier="flash", page_range="all", format="markdown", no_marker=True)+ assert "Source page 1" in text and "Source page 5" in text+ finally:+ await db.close()-def test_parse_page_range_negative_one_is_last_page() -> None:- assert parse_page_range("-2~-1", 5) == [3, 4]+ asyncio.run(verify())