MinerU/docs/next/pitfalls.md

开发陷阱清单

状态: Draft 读者: 核心开发、编程 Agent、代码审查者 范围: 4.x 开发中已知的结构性陷阱与兼容面联动要求 来源: MINERU-1 代码结构分析报告（SHANNON，2026-09-01），逐条对照代码复核后固化。行号以 commit 317428b8 为基准。

本清单收录的是"改动前必须知道，否则容易做错"的事项。每条给出代码锚点与正确做法；纯推测、无法操作的观察不收录。

1. 双轨兼容面的联动要求

1.1 backend 不再是入参

历史过渡层 resolve_tier_and_backend(tier, backend) 与 mineru-kit parse --backend 专家参数（含 pipeline/vlm-* 等别名）已移除：backend 只用于推断 tier，推断后即被丢弃，没有独立作用。backend_for_tier 派生链与 ParserRuntimeOptions.backend 内部字段也已删除。

• 新代码只走 tier；basic/standard/advanced 共用同一个 hybrid-engine，仅 effort 不同（effort_for_tier()，parser/tier.py 的 ParserRuntimeOptions(tier, effort)）。
• 不要在任何 CLI / SDK / API 入口重新引入 backend 入参，也不要恢复 backend 派生函数或内部字段。

1.2 共享文档协议与缓存必须同步

改外层结构时同步 DocVortex schema/readers、MinerU ParseResult 和 Doclib 缓存。 当前使用 schema 身份 + 版本 2.0 + metadata，通用接口拒绝旧协议；不能仅按版本号识别。 Doclib 缓存命中、覆盖、默认档位与压缩均使用专属 read_cached_middle_json，兼容转换旧 3.4.5 和 MinerU 2.0；压缩只合并转换后元数据一致的批次。 详见 envelope.md。

2. Alpha 高频迭代，公开 API 未稳定

4.x 处于 Alpha prerelease，迭代节奏约为日均 10 个提交，公开 API 未稳定（变更专门记录在 docs/next/api/changes.md）。

• 外部集成应 pin 具体 commit，不要跟浮动的 next HEAD。
• 内部改动涉及 NEXT v1 API 行为变化时，必须在 docs/next/api/changes.md 追加条目。

3. 错误协议：设计已定、实现缺位的部分

docs/next/errors.md 已设计 user_action / retryable / docs_url 扩展字段，但 mineru/errors.py 的 error_response（errors.py:208）目前只输出 OpenAI 兼容的 {type, code, message, param}，全仓无 Python 实现点。

• 依赖这些扩展字段的调用方代码不要提前编写。
• 补齐该缺口是自然切入点：改 errors.py 的 error_response 与 CLI JSON 输出，并同步 docs/next/errors.md 状态。

4. 仓库约定速查

两条来自 AGENTS.md / CLAUDE.md 的硬约定，最容易在自动生成提交时违反：

• mineru 子模块之间只使用 relative import（from .base import X），不用 import mineru.xxx 绝对导入。
• commit message / PR body 禁用 fixes|closes|resolves #n（会在 merge 后自动关闭 issue），用 Refs #n。