借鉴 pdf-inspector 补齐原生 PDF 布局、语义与表格质量

[caichuanwang]

背景

对照 pdf-inspector（Firecrawl 的纯本地 PDF 分类/提取/转 Markdown 库）分析后，OpenDocs 原生 PDF 路径存在四类可落地差距：逐词输出导致段落碎片化与双栏交错、字体元数据采集后丢失导致无法表达标题/列表/代码、页眉页脚与断词原样泄漏、无边框表格与编码质量问题无本地兜底。

改动范围（均在私有 src/opendocs/parsers/pdf/ 内，无公共 API/依赖变更）

模块	内容
extract.py	词级候选 → 行重建 → 双栏/跨栏阅读顺序（有界聚类）；拒绝一维伪表格；文本不同的嵌套表保留；Unicode 非字符/代理项编码质量检测
semantics.py（新增）	文档级正文基准字号 → H1–H3 标题、无序/有序列表、代码块（动态围栏防逃逸）、段落合并与保守断词；重复页眉/页脚/页码过滤
analyze.py	移除不可控的 pdfplumber text/text 回退，改为 ≤500 词的有界本地无边框表格启发式（3 行 × 2 列、数字占比 ≥40%）
merge.py	表格/视觉区域按词中心点所有权（轻微擦边不再误删）；hybrid 视觉元素按所属栏插入，保持列阅读顺序；所有权裁决后再重建行
models.py	NativeTextCandidate 携带 font_size/font_name 并贯通 native worker wire
parser.py	_has_semantic_blocks 识别标题/列表/代码块，避免误报 NoUsableContent

验证

pytest 全量        634 passed, 9 skipped（基线 616，新增 18 个测试）
ruff check .       通过
ruff format --check 通过（112 文件）
ty check src tests 通过
git diff --check   通过

新增测试覆盖：真实合成 PDF 反例（对齐段落不误判表格、无边框数字表格可恢复）、双栏/跨栏/右栏视觉顺序、断词正反例、1–2 页页码过滤、Unicode 各平面边界、完整 PageFacts wire 往返、列表 identity/ordinal、代码围栏与语义-only 文档判定。

残余风险 / 未覆盖

• 原生路由 PDF 的输出从逐词 TextBlock 变为语义块；hybrid/full-vision 页面输出不变
• 跨栏表格与视觉元素插入顺序为新启发式，需私有验收语料进一步校准
• pdf-inspector 的快速预分类层（TextBased/Scanned 路由）与逐页 OCR 回退未引入
• 私有验收语料与真实多页复杂版式未在本次验证（Not-tested）