ADR-0024: 文件类型与 Tier 归一化语义
历史决策记录：保留当时的背景、状态和设计。当前接口与实现归属以 开发入口 和现行规范为准；文中的历史模块路径不保证仍存在。
状态: Accepted，已实现 日期: 2026-07-09 Tasks 语义更新: 2026-10-27 相关文档: ../tiers.md, ../cli/mineru-parse.md, ../cli/mineru-kit-parse.md, ../api/tasks.md, 0022-doclib-file-type-tier-remote-semantics.md, 0028-csv-structured-flash-parsing.md
背景
MinerU doclib 可以接收 PDF、image、Office、text 和 HTML 输入，但这些输入并不具备相同的解析能力。
PDF 和 image 支持质量 tier: flash、basic、standard、advanced。EPUB、Office、HTML 和 CSV 当前只有 flash 语义，没有对应的质量 tier。其它 text 可入库和搜索，但不需要解析。此前不同入口对“非 PDF/image + 质量 tier”的处理不完全一致:
- 有的入口报错。
- 有的入口静默走 Office / HTML / CSV parser，或为其它 text 返回没有对应缓存的合成成功响应。
- parsing-rule 可能创建
tier=standard等 parse row，但实际执行的仍是 Office / flash 语义。
这种不一致会让 parse row、缓存目录、locator 和用户看到的实际解析能力脱节。因此需要定义一套按操作类型区分的归一化规则。
本 ADR 细化并部分修订 ADR-0022。ADR-0022 中 doclib 主动单文件解析的严格错误语义仍保留；本 ADR 补充 batch、parsing-rule、API Server 和 mineru-kit 的例外。ADR-0028 进一步把 CSV 从无需解析 text 移入仅支持 flash tier 的结构化输入组。
决策
1. 文件类型分组
MinerU 在 tier 语义上把输入分为三组:
| 分组 | 文件类型 | Tier 能力 |
|---|---|---|
| 支持多 tier 的输入 | PDF、image | flash、basic、standard、advanced |
| 仅支持 flash tier 的输入 | Office、HTML、CSV | 仅 flash 语义 |
| 无需解析的文本输入 | .txt、.md、.markdown、.rst、.tex |
无 tier；直接读取源文件 |
EPUB、Office、HTML 和 CSV 即使通过高层接口传入了 basic、standard 或 advanced，也不能把结果记录为这些质量 tier，除非未来另有 ADR 明确引入对应能力。text 不创建 parse row 或 Middle JSON，显式 parse 返回 parse_not_required。
2. 单对象主动操作
单对象主动操作包括:
mineru parse <single-file>经 doclib 解析。DoclibClient.ensure_parse(ParseRequest(...))。- 本地 SDK 直接解析单个文件（HTTP
MinerUApiParser遵循下述 Tasks 规则）。 mineru-kit parse展开后只有一个输入文件。
规则:
| 输入类型 | 未指定 tier | 指定 flash |
指定 basic/standard/advanced |
|---|---|---|---|
| PDF / image | 使用该入口默认质量选择策略 | 使用 flash |
使用指定质量 tier |
| Office / HTML / CSV | 归一为 flash |
使用 flash |
报错 |
| text | 不解析；doclib 返回 parse_not_required |
不解析；doclib 返回 parse_not_required |
不解析；doclib 返回 parse_not_required |
因此，单对象主动操作中，用户显式指定质量 tier 表达明确质量预期。对于没有质量 tier 能力的输入，系统不能静默降级。SDK 和 mineru-kit 的解析输入校验直接排除 text；doclib 使用更具体的 parse_not_required 指导用户读取源文件。
3. 批量操作
批量操作包括:
- API Server / Router 的 V1 Tasks，包括单文件请求及 HTTP SDK、file_parse 的提交。
mineru-kit parse展开后包含多个输入文件，或输入目录。- parsing-rule 触发的后台解析。
批量操作的目标是处理一组异构文件。为了避免一个 Office 或 HTML 文件阻断整个批次，仅支持 flash tier 的输入允许静默归一为 flash。text 文件不进入 parse 批次；需要保留内容时直接读取或建立文本索引。
规则:
| 输入类型 | 未指定 tier | 指定 flash |
指定 basic/standard/advanced |
|---|---|---|---|
| PDF / image | 使用该入口默认选择策略 | 使用 flash |
使用指定质量 tier |
| Office / HTML / CSV | 归一为 flash |
使用 flash |
归一为 flash |
| text | 不进入 parse 批次 | 不进入 parse 批次 | 不进入 parse 批次 |
批量操作中，EPUB/Office/HTML/CSV 的实际 parse row、缓存目录、locator 和 metadata 必须记录 flash，不能记录用户传入的质量 tier。其它 text 不得生成这些解析产物。
Tasks 的顶层请求 tier 可选，只对 PDF/image 生效。省略或 JSON null 时，接单服务按 standard -> basic -> flash 选择支持的档位；advanced 必须显式指定，仅有 advanced 时省略 tier 返回 503 quality_tier_unavailable。
显式档位不受支持且批次包含 PDF/image 时，整个创建请求返回 400 invalid_request，不自动升降档。纯原生文档忽略合法的显式 tier，固定使用 flash；非法枚举或空字符串仍报参数错误，原生解析是所有正常可用服务的必备能力，不依赖 /v1/tiers 是否发布 flash。
选档在接单时保存，后续逐文件执行和 Router 转发使用有效档位，不随 worker 默认值变化。成功结果通过 files[].parse.tier 返回真实执行档位，不在顶层回显请求 tier，也不产生伪质量缓存。其它 text 不进入 Tasks 解析。
Tasks 默认选择独立于 Doclib 主动操作的默认质量策略，不改变后者必须显式选择 flash 的规则。
4. Parsing-Rule 语义
parsing-rule 是批量/后台规则，不是用户对单个文件的显式 parse 请求。
规则:
tier和remote参数只适用于 PDF 和 image。- EPUB、Office、HTML 和 CSV 命中 parsing-rule 时，忽略 rule 中的
tier、page_range和remote，按flash整本解析。 - text 命中 parsing-rule 时只完成入库和文本索引，不创建 parse row。
- PDF/image 命中 parsing-rule 且指定 tier 时，使用 rule tier。
- PDF/image 命中 parsing-rule 但未指定 tier 时，按以下顺序选择可用 tier:
standard -> basic -> flash
这与用户主动阅读默认选择不同。parsing-rule 是后台批量策略，可以接受最后降级到 flash，因为 watch 自动发现本身也接受 flash。
5. Remote 语义
remote 的含义取决于入口:
| 入口 | EPUB/Office/HTML/CSV + remote | text + remote |
|---|---|---|
doclib / mineru parse 单文件主动解析 |
报 remote_unsupported_for_file_type |
报 parse_not_required |
| parsing-rule | 忽略 remote，按 flash |
只入库和索引 |
| API Server / Router Tasks | 不适用；HTTP 请求明确发往配置的解析服务 | 不接受 text 作为解析输入 |
mineru-kit parse |
允许，作为低层工具特例 | 不接受 text 作为解析输入 |
doclib 单文件主动解析中，remote=true 表示用户显式要求把该文件交给 remote parse-server。因为 remote parse-server 只支持 PDF/image，该组合必须报错，不能静默改成本地 flash，否则会改变用户显式选择的执行路径和隐私语义。
mineru-kit parse 是低层工具，允许 --remote 处理 EPUB/Office/HTML/CSV；当这些输入不能使用质量 tier 时，按批量归一规则处理。其它 text 不作为解析输入。
替代方案
方案 A: EPUB/Office/HTML/CSV 一律静默忽略 tier
未采用。
原因:
- 单文件主动操作中，用户显式指定质量 tier 通常表示明确质量预期。
- 静默忽略会让脚本和用户误以为质量 tier 已执行。
- doclib 的 parse row、缓存和 locator 应准确表达实际结果能力。
方案 B: EPUB/Office/HTML/CSV 一律遇到质量 tier 报错
未采用。
原因:
- 批量任务经常包含混合文件类型。
- parsing-rule 是后台批量策略，不应因为 EPUB/Office/HTML/CSV 携带无效质量 tier 而阻断整个目录处理。
- API Server V1 Tasks 是多文件接口，也应支持异构输入。
方案 C: 为 API Server 增加 file-level effective tier 字段
原先暂缓的响应设计已由 Tasks 的 files[].parse.tier 实现。该字段来自成功产物的实际元数据，不以请求档位代替；不再使用 job-level tier 表示整批实际执行档位。
影响
对 doclib
- doclib 单文件主动解析保持严格语义: EPUB/Office/HTML/CSV 显式质量 tier 报错；其它 text 返回
parse_not_required。 - EPUB/Office/HTML/CSV 未指定 tier 或指定
flash时，实际记录为flash。 - parsing-rule 触发 EPUB/Office/HTML/CSV 时，实际 parse row 必须为
flash；其它 text 只入库和索引。 - parsing-rule 对 PDF/image 未指定 tier 时，允许
standard -> basic -> flash兜底。
对 SDK 和 mineru-kit
- 本地 SDK 单文件解析按单对象主动操作语义处理，并排除 text 解析输入；HTTP
MinerUApiParser遵循 Tasks 语义。 mineru-kit parse需要根据展开后的输入数量区分单对象和批量。mineru-kit parse --remote对 EPUB/Office/HTML/CSV 是允许的低层工具特例；其它 text 不作为解析输入。
对 API Server
- API Server 和 Router Tasks 按批量操作语义处理，包括单文件提交。
- EPUB/Office/HTML/CSV 即使请求 tier 是质量 tier，执行时也按
flash语义；其它 text 不进入 Tasks 解析。 - 成功文件的实际档位通过
files[].parse.tier返回，默认选档及错误规则见上文。
对缓存和 locator
- 缓存键、parse row、locator 和产物 metadata 必须记录实际 tier。
- EPUB/Office/HTML/CSV 不应产生
basic、standard或advanced缓存；其它 text 不应产生任何解析缓存。
后续动作
- 更新 doclib parsing-rule 入队逻辑，确保 EPUB/Office/HTML/CSV 创建
tier=flash的 parse row，其它 text 不创建 parse row。 - 更新 parsing-rule 的 PDF/image 默认 tier 选择顺序为
standard -> basic -> flash。 - 检查 SDK、mineru-kit 和 API Server，对单对象和批量操作分别应用本 ADR 的归一化规则。
- 同步更新 CLI、SDK 和 API 文档，避免继续表述为“所有入口统一报错”或“所有入口统一静默降级”。
2026-09-24 格式扩展：MHTML/MHT 网页归档沿用 HTML 的 Flash-only tier 归一规则，两个后缀均归一为 mhtml，只支持整本解析。