PDF 页码范围规范

状态: Implemented

CLI 的 --pages、Python/Doclib/API 的 page_range 和 Gradio 转换事件的页码参数使用同一套语法；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 Tasks / `MinerUApiParser`	全部
`mineru-kit parse`	全部
Gradio PDF	默认全部；配置 `--max-pages M` 后选择前 M 页，不足则全部

显式 all 选择全部 PDF 页面；内容读取/导出仍受实际缓存可用性约束。非 PDF 的解析限制不变：不能显式设置页码（包括 all）；Gradio 对非 PDF 自动清空并隐藏此控件。 Gradio 仅对已上传的 PDF 显示选页控件，所有档位（包括 Flash）一致；配置的页数上限也适用于直接调用 Gradio 转换事件，显式超限选区报 page_range_invalid。

输入与输出

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"

from mineru.parser import parse

result = parse("report.pdf", tier="flash", page_range="1,3,r1")

{
  "tier": "flash",
  "files": [{"file_name": "report.pdf", "bytes": 12345, "page_range": "1-3,r1"}],
  "output_formats": ["default"]
}

已求值的 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。

历史结果兼容

旧 Doclib 中使用半角 ~ 的正整数结果范围（例如 1~5,8）可以直接读取，并可与新格式结果共存。内容读取、缓存命中、覆盖统计和 compaction 共用此兼容规则；无需因页码分隔符变化而重建数据库、重新解析或更换数据目录。

读取旧缓存文件时仍使用数据库记录中的原始范围和原文件名，例如 1~5_时间戳.json。对外返回的结果范围、新解析记录及正常 compaction 输出统一使用连字符，例如 1-5,8。读取和结果展示不会原地修改旧记录或重命名旧缓存文件。

兼容仅适用于已求值的历史结果及元数据，不放宽新请求输入，也不扩展旧 parsing rules 或旧待处理任务的执行兼容。新请求仍使用 1-5、r1、all。全角 ～、负号倒数页码 -1 / -5~-1 不受支持；已求值结果中也不能包含未经展开的 rN 或 all。