MinerU/docs/next/middle-json/README.md

Middle JSON 总览

状态: Draft 读者: backend 开发者、输出开发者、SDK 开发者、Agent 能力开发者 范围: Middle JSON 的目标、当前事实和工作分层 来源: 由根目录旧 Middle JSON 底稿迁移整理而来

当前事实

当前 Middle JSON 的事实标准是 mineru/types.py 中的 schema 2.0 typed document model（mineru/parser/base.py 的 MIDDLE_JSON_SCHEMA_VERSION = "2.0"，3.0 从未发布）:

MiddleJson
  -> pages: list[PageInfo]
PageInfo
  -> blocks: list[PageBlock]
InlineContentBlock
  -> content: list[InlineSpan]

这套结构已经被 parser、doclib、render 和 parse-server 共同使用。旧版带 bbox/图片职责的 Line/Span 不会恢复；当前 InlineSpan 只表达行内文字、公式、代码与链接。

为什么还需要整理

当前混乱主要来自四类不一致:

类别	现状
顶层 envelope	当前 ParseResult.to_dict() 只输出 schema_version: "2.0" + MiddleJson 字段，没有顶层 _backend/_meta 临时 metadata；MinerU 3.4.5 pdf_info 与 schema 1.0 pages 包装由 ParseResult.from_dict() 的运行时 legacy 分支单向迁移（见 migration.md）。
backend 细节	Pipeline/VLM/Hybrid/Office/HTML 对 block type、span 粒度与内部后处理流程的处理不同；public schema 中 bbox 统一为 0-1 归一化坐标或 null，PageInfo 无 page_size。
Agent 能力	稳定 page/block locator 与 short_id 已落地（mineru/doclib/locators.py）；citation 输出形态与隐私边界的部分能力仍在收敛。

下一版目标

Middle JSON 下一版要达到以下目标:

1. 统一使用带协议身份和 metadata 的 JSON 2.0；通用接口严格读取，Doclib 历史数据经独立缓存边界转换，见 envelope.md。
2. 明确 PageInfo / Block / InlineSpan 字段契约。
3. 为每个 backend 提供 normalization 任务清单。
4. 定义 Agent 可引用的稳定 locator 规则。
5. 明确 render 层依赖哪些字段，逐步移除对 _backend 的长期依赖。
6. 提供 migration / validation 的验收标准。

工作分层

层	工作内容	产物
Schema	稳定 dataclass 字段和 envelope。	current-medium.md、envelope.md
Normalization	补齐 backend 差异。	backend-gaps.md
Agent-native	引用、locator。	agent-gaps.md
Structured Content	盘点当前 structured_content，作为新 schema 起点。	structured-content-current.md
Structured Content Schema	定义 NEXT 版目标 schema 草案。	structured-content-schema.md
Rendering	统一 Markdown / Content List / Structured Content 消费。	rendering.md
Migration	分阶段落地。	migration.md

P0 判断

下面这些是 P0，因为它们直接阻塞 Agent 场景:

• 稳定 page/block locator。
• 可从 Agent answer 追溯到 page / block / bbox / source hash。
• 可识别的 MinerU 3.4.5 middle json 能迁移，其它旧数据能被标记为 stale 并触发重新解析。
• ParseResult.from_dict() 可以恢复 API / 缓存结果。
• 默认选择 / tier 产生的不同质量结果能被 doclib 正确区分和缓存。

非目标

• 不重新设计 OCR、layout、VLM 模型输出。
• 不把所有 backend 内部临时字段公开为 schema。
• 不在 Middle JSON 层定义 chunking 算法本身；这里只定义可寻址基础。