MinerU/docs/doclib-middle-json-compat-validation.md

Doclib 历史 Middle JSON 兼容验证

日期：2026-09-07。实现基于本地 48fdd2b66 工作区，仅在 Doclib 持久化读取边界恢复兼容。 使用约定见 Doclib 历史兼容。

实现与边界

• 新增 read_cached_middle_json()，在内存中读取当前格式、3.4.5/旧 1.0 包装及旧 MinerU Schema 2.0。
• 页面适配器与 dc0944984 中的原文件逐字节一致；新构造器及元数据处理放在 Doclib 读取层。
• 旧 Schema 2.0 只调整外层，测试明确禁止调用共享语义后处理或 LLM。
• 历史生产版本缺失时记为 unknown，运行参数不可靠时不补造产品记录。
• 缓存命中、覆盖、默认读取档位、FTS 重建和压缩使用同一读取入口。
• 普通读取不改写历史 JSON 或数据库记录；兼容且元数据一致的批次可在正常压缩时写成新格式。
• 通用 ParseResult 与 DocVortex codec 未增加旧格式读取能力；HTTP/ZIP 已临时兼容 3.x remote server，待其升级到 4.0 后移除。
• 本次没有调整包版本、协议版本、解析算法或兼容有效期，也未新增兼容开关。

验证结果

使用本地 Magic-PDF .venv1：

检查	结果
适配器、Doclib、通用读取、HTTP/ZIP、Gradio 专项	560 passed
MinerU 完整测试	1870 passed、3 skipped、3 个既有失败
本次修改的 Python 文件 Ruff	通过
本次修改的补丁空白检查	通过

专项覆盖原 3.4.5 文字、公式、链接、图表、列表、目录和坐标转换；旧 2.0 页面保持； 版本缺失、元数据冲突、未知扩展保留、输入不变和转换幂等性；以及显式错误 schema 不兜底。 真实 SQLite/FTS5 用例覆盖两种历史协议族的缓存命中、内容读取、范围覆盖、索引重建、 默认档位、混合协议压缩、重复页取新及冲突/失败时保留源数据。

完整测试仍存在三项此前已确认的失败，均不涉及本次兼容代码：

• test_basic_extra_includes_preflight_runtime_dependencies：既有 basic extra 缺失。
• test_standard_is_the_highest_model_runtime_extra：既有 test extra 不含 mineru[standard]。
• test_pp_formulanet_fix_latex_uses_shared_mathring_repair：既有 UniMERNetDecode 缺少 fix_latex。

执行期间工作区还存在另外进行的 PDF 渲染、依赖、版本和测试调整，本次未修改这些文件。 初轮完整测试额外出现 PDF 补图用例失败；后续并行更新后，最终完整测试已不再出现该失败。 以上完整测试数字对应最终运行时的整个共享工作区，不将其他修改计入本次兼容实现。

复跑与证据

python -m pytest -q tests/unittest/test_doclib_middle_json.py tests/unittest/test_doclib_legacy_schema_adapter.py tests/unittest/test_doclib_legacy_page_ranges.py tests/unittest/test_doclib_cache_semantics.py tests/unittest/test_legacy_schema_adapter.py tests/unittest/test_parse_result_contract.py tests/unittest/test_parser_api_contract.py tests/unittest/test_kit_gradio.py
python -m pytest -q

本地日志保存在 /tmp/doclib-middle-compat/verified-focused.log 和 /tmp/doclib-middle-compat/full-final.log。先前 JSON 2.0 直接迁移的验证报告不改写； 此记录描述后续收敛为 Doclib 专属兼容边界的行为。