Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
fix: preserve document ordering and review invariants
myhloli3942ce08be23
diff --git a/mineru/model/flash/office/docx/docx_converter.py b/mineru/model/flash/office/docx/docx_converter.pyindex 5d4359cd..0d8da2d6 100644--- a/mineru/model/flash/office/docx/docx_converter.py+++ b/mineru/model/flash/office/docx/docx_converter.py@@ -1695,15 +1695,14 @@ class DocxConverter:@staticmethoddef _complex_field_hyperlink_target(instruction: str) -> tuple[str | None, bool]:"""从复杂字段指令中提取外部 URL 或内部 bookmark fragment。"""- internal_match = re.search(r'\bHYPERLINK\s+\\l\s+"([^"]+)"', instruction, re.IGNORECASE)- if internal_match:- anchor = internal_match.group(1).strip()- return (f"#{anchor}" if anchor else None), True-external_match = re.search(r'\bHYPERLINK\s+"([^"]+)"', instruction, re.IGNORECASE)- if external_match:- target = external_match.group(1).strip()- return (target or None), False+ bookmark_match = re.search(r'\\l\s+"([^"]+)"', instruction, re.IGNORECASE)+ address = external_match.group(1).strip() if external_match else ""+ bookmark = bookmark_match.group(1).strip() if bookmark_match else ""+ if address:+ return (f"{address}#{bookmark}" if bookmark else address), False+ if bookmark:+ return f"#{bookmark}", Truereturn None, False@classmethoddiff --git a/mineru/render/_internal/latex/table.py b/mineru/render/_internal/latex/table.pyindex 4dd0deaf..da5f78a9 100644--- a/mineru/render/_internal/latex/table.py+++ b/mineru/render/_internal/latex/table.py@@ -3,6 +3,8 @@from __future__ import annotations+from typing import TypeAlias+from bs4 import NavigableString, Tagfrom pydantic import ValidationError@@ -21,6 +23,7 @@ from .inline import LatexAnchorRegistry, escape_latex_text, escape_latex_url, re_BLOCK_TAGS = {"address", "article", "blockquote", "div", "figcaption", "footer", "header", "li", "p", "section"}_SKIPPED_TAGS = {"script", "style", "template", "noscript"}+_HtmlCellToken: TypeAlias = InlineSpan | Tagclass LatexTableError(HtmlTableError):@@ -97,24 +100,7 @@ class LatexTableRenderer:depth: int,) -> str:"""渲染一个 origin cell,并组合 rowspan/colspan 声明。"""- parts: list[str] = []- spans = _html_cell_spans(cell)- if spans:- parts.append(render_inline_spans(spans, self.anchors))- for image in cell.find_all("img"):- if image.find_parent("table") is not cell.find_parent("table"):- continue- source = image.get("src", "")- if isinstance(source, list):- source = ""- alt = image.get("alt", "image")- if isinstance(alt, list):- alt = " ".join(str(item) for item in alt)- parts.append(self._render_image(str(source), str(alt)))- for nested in cell.find_all("table"):- if nested.find_parent(("td", "th")) is not cell:- continue- parts.append(self._render_source(nested, depth=depth + 1))+ parts = self._render_cell_parts(cell, depth=depth)content = r"\par ".join(part for part in parts if part) or "~"if is_header:content = rf"\cellcolor{{MinerUTableHeader}}\textbf{{{content}}}"@@ -125,6 +111,46 @@ class LatexTableRenderer:content = rf"\multicolumn{{{colspan}}}{{|p{{{width}}}|}}{{{content}}}"return content+ def _render_cell_parts(self, cell: Tag, *, depth: int) -> list[str]:+ """按 HTML 来源顺序交替渲染行内内容、图片与嵌套表格。"""++ parts: list[str] = []+ inline_buffer: list[InlineSpan] = []++ def flush_inline_buffer() -> None:+ """把当前连续行内 token 校验并渲染为一个 LaTeX 片段。"""++ if not inline_buffer:+ return+ spans = _parse_cell_inline_spans(inline_buffer)+ rendered = render_inline_spans(spans, self.anchors)+ if rendered:+ parts.append(rendered)+ inline_buffer.clear()++ for token in _html_cell_tokens(cell):+ if not isinstance(token, Tag):+ inline_buffer.append(token)+ continue+ flush_inline_buffer()+ if token.name == "img":+ parts.append(self._render_image_tag(token))+ elif token.name == "table":+ parts.append(self._render_source(token, depth=depth + 1))+ flush_inline_buffer()+ return parts++ def _render_image_tag(self, image: Tag) -> str:+ """读取一个单元格图片标签并渲染为 LaTeX 图片或可见回退。"""++ source = image.get("src", "")+ if isinstance(source, list):+ source = ""+ alt = image.get("alt", "image")+ if isinstance(alt, list):+ alt = " ".join(str(item) for item in alt)+ return self._render_image(str(source), str(alt))+def _render_image(self, source: str, alt_text: str) -> str:"""渲染单元格图片;非本地 sidecar 退化为可见链接或占位。"""path = resolve_html_image_path(source, self.asset_base_path)@@ -182,29 +208,47 @@ def _row_rules(return rules-def _html_cell_spans(cell: Tag) -> list[InlineSpan]:- """把单元格中非图片、非嵌套表内容转换为严格 InlineSpan。"""- spans: list[InlineSpan] = []- for child in cell.children:- spans.extend(_html_node_spans(child, styles=(), allow_links=True))- if not spans:- return []+def _parse_cell_inline_spans(spans: list[InlineSpan]) -> list[InlineSpan]:+ """校验一个不跨图片或嵌套表格的连续单元格行内片段。"""+try:return parse_inline_spans(spans)except (TypeError, ValidationError, ValueError) as exc:raise LatexTableError("HTML table cell inline content is invalid") from exc-def _html_node_spans(node: object, *, styles: tuple[InlineStyle, ...], allow_links: bool) -> list[InlineSpan]:- """递归解析表格单元格中的安全富文本标签。"""+def _html_cell_tokens(cell: Tag) -> list[_HtmlCellToken]:+ """按来源顺序返回单元格中的行内、图片与嵌套表格 token。"""++ return [+ token+ for child in cell.children+ for token in _html_node_tokens(+ child,+ styles=(),+ allow_links=True,+ )+ ]+++def _html_node_tokens(+ node: object,+ *,+ styles: tuple[InlineStyle, ...],+ allow_links: bool,+) -> list[_HtmlCellToken]:+ """递归解析 HTML 节点,同时把图片和嵌套表格保留为顺序屏障。"""+if isinstance(node, NavigableString):text = str(node)return [TextSpan(type="text", content=text, styles=list(styles))] if text else []if not isinstance(node, Tag):return []name = (node.name or "").lower()- if name in _SKIPPED_TAGS or name in {"img", "table"}:+ if name in _SKIPPED_TAGS:return []+ if name in {"img", "table"}:+ return [node]if name == "br":return [TextSpan(type="text", content="\n", styles=list(styles))]if name == "eq":@@ -227,10 +271,14 @@ def _html_node_spans(node: object, *, styles: tuple[InlineStyle, ...], allow_linchild_styles = tuple(dict.fromkeys((*styles, style_name))) if style_name is not None else stylesif name == "a" and allow_links:children = [- span+ tokenfor child in node.children- for span in _html_node_spans(child, styles=child_styles, allow_links=False)- if not isinstance(span, HyperlinkSpan)+ for token in _html_node_tokens(+ child,+ styles=child_styles,+ allow_links=False,+ )+ if not isinstance(token, HyperlinkSpan)]target = sanitize_hyperlink_target(node.get("href"),@@ -238,21 +286,63 @@ def _html_node_spans(node: object, *, styles: tuple[InlineStyle, ...], allow_linallow_relative=True,allow_fragment=True,)- if target is not None and children:- try:- return [HyperlinkSpan(type="hyperlink", url=target, content=children)] # type: ignore[arg-type]- except ValidationError:- pass- return children- spans = [span for child in node.children for span in _html_node_spans(child, styles=child_styles, allow_links=allow_links)]- if name in _BLOCK_TAGS and spans and not _spans_end_with_newline(spans):- spans.append(TextSpan(type="text", content="\n"))- return spans---def _spans_end_with_newline(spans: list[InlineSpan]) -> bool:- """判断当前 span 序列是否已经以普通文本换行结束。"""- return bool(spans and isinstance(spans[-1], TextSpan) and spans[-1].content.endswith("\n"))+ return _wrap_hyperlink_tokens(children, target)+ tokens = [+ token+ for child in node.children+ for token in _html_node_tokens(+ child,+ styles=child_styles,+ allow_links=allow_links,+ )+ ]+ if name in _BLOCK_TAGS and tokens and not _tokens_end_with_newline(tokens):+ tokens.append(TextSpan(type="text", content="\n"))+ return tokens+++def _wrap_hyperlink_tokens(+ tokens: list[_HtmlCellToken],+ target: str | None,+) -> list[_HtmlCellToken]:+ """只包装链接内连续的 InlineSpan,让图片和嵌套表格保持原位。"""++ if target is None:+ return tokens+ output: list[_HtmlCellToken] = []+ inline_buffer: list[InlineSpan] = []++ def flush_inline_buffer() -> None:+ """把当前链接行内片段包装成一个 HyperlinkSpan。"""++ if not inline_buffer:+ return+ try:+ output.append(+ HyperlinkSpan(+ type="hyperlink",+ url=target,+ content=list(inline_buffer),+ )+ )+ except ValidationError:+ output.extend(inline_buffer)+ inline_buffer.clear()++ for token in tokens:+ if isinstance(token, Tag):+ flush_inline_buffer()+ output.append(token)+ else:+ inline_buffer.append(token)+ flush_inline_buffer()+ return output+++def _tokens_end_with_newline(tokens: list[_HtmlCellToken]) -> bool:+ """判断当前 token 序列是否已经以普通文本换行结束。"""++ return bool(tokens and isinstance(tokens[-1], TextSpan) and tokens[-1].content.endswith("\n"))__all__ = ["LatexTableError", "LatexTableRenderer"]diff --git a/scripts/review_flash_layout_geometry.py b/scripts/review_flash_layout_geometry.pyindex cef56433..9fa06537 100644--- a/scripts/review_flash_layout_geometry.py+++ b/scripts/review_flash_layout_geometry.py@@ -347,7 +347,6 @@ def _parse_args() -> argparse.Namespace:parser.add_argument("--manifest", type=Path, default=TRACKED_GOLD_MANIFEST)parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)parser.add_argument("--no-render", action="store_true")- parser.add_argument("--skip-performance-gate", action="store_true")parser.add_argument("--include", action="append", default=[], help="仅运行指定 PDF 文件名,可重复传入")parser.add_argument("--role",@@ -360,6 +359,30 @@ def _parse_args() -> argparse.Namespace:return parser.parse_args()+def _geometry_summary_mismatch(+ file_name: str,+ expected_document: dict[str, Any],+ actual_document: dict[str, Any],+) -> dict[str, Any] | None:+ """比较版本化几何摘要,并返回缺失或数值漂移的结构化诊断。"""++ expected_summary = expected_document.get("expected_geometry_summary")+ actual_summary = actual_document.get("geometry_summary")+ if not isinstance(expected_summary, dict):+ return {+ "file": file_name,+ "reason": "geometry_summary_expectation_missing",+ }+ if actual_summary != expected_summary:+ return {+ "file": file_name,+ "reason": "geometry_summary_mismatch",+ "expected": expected_summary,+ "actual": actual_summary,+ }+ return None++def main() -> int:"""执行版本化 Flash 语料并写出几何、金标和视觉审阅产物。"""@@ -392,12 +415,20 @@ def main() -> int:documents.append(document)gold_mismatches: list[dict[str, Any]] = []+ geometry_mismatches: list[dict[str, Any]] = []tracked_by_file = {Path(str(document["path"])).name: document for document in tracked_gold.get("documents", [])}for document in documents:expected = tracked_by_file.get(document["file"])if expected is None or expected.get("sha256") != document["sha256"]:gold_mismatches.append({"file": document["file"], "reason": "source_missing_or_sha_mismatch"})continue+ geometry_mismatch = _geometry_summary_mismatch(+ document["file"],+ expected,+ document,+ )+ if geometry_mismatch is not None:+ geometry_mismatches.append(geometry_mismatch)expected_pages = expected.get("pages", [])if not expected_pages:continue@@ -425,19 +456,12 @@ def main() -> int:if bbox_pages:gold_mismatches.append({"file": document["file"], "reason": "bbox_fingerprint_mismatch", "pages": bbox_pages})- performance_failures = []- if not args.skip_performance_gate:- for document in documents:- expected = tracked_by_file.get(document["file"], {})- max_elapsed = expected.get("max_elapsed_seconds")- if isinstance(max_elapsed, (int, float)) and document["elapsed_seconds"] > float(max_elapsed):- performance_failures.append({"file": document["file"], "metric": "elapsed_seconds"})manifest = {"source_root": str(source_root),"source_count": len(documents),"page_count": sum(document["pages"] for document in documents),"txt_page_count": sum(document["pages"] for document in documents if document["parse_mode"] == "txt"),- "performance_failures": performance_failures,+ "geometry_mismatches": geometry_mismatches,"gold_mismatches": gold_mismatches,"documents": [{key: value for key, value in document.items() if key != "gold_pages"} for document in documents],}@@ -470,7 +494,7 @@ def main() -> int:f"- Documents: {manifest['source_count']}",f"- Pages: {manifest['page_count']}",f"- TXT pages: {manifest['txt_page_count']}",- f"- Performance failures: {len(performance_failures)}",+ f"- Geometry summary mismatches: {len(geometry_mismatches)}",f"- Gold mismatches: {len(gold_mismatches)}",f"- All pages approved: {gold['all_approved']}","",@@ -481,7 +505,7 @@ def main() -> int:f"elapsed={document['elapsed_seconds']:.3f}s")(output_dir / "review.md").write_text("\n".join(review_lines) + "\n", encoding="utf-8")- return 1 if gold_mismatches or performance_failures else 0+ return 1 if geometry_mismatches or gold_mismatches else 0if __name__ == "__main__":diff --git a/tests/fixtures/flash_layout_geometry_manifest.json b/tests/fixtures/flash_layout_geometry_manifest.jsonindex 494f2018..35645aca 100644--- a/tests/fixtures/flash_layout_geometry_manifest.json+++ b/tests/fixtures/flash_layout_geometry_manifest.json@@ -12286,7 +12286,7 @@],"expected_geometry_summary": {"repaired_chars": 27763,- "repaired_lines": 1348,+ "repaired_lines": 1347,"split_y_candidates": 27,"strong_x_runs": 7,"sibling_x_runs": 3@@ -16202,13 +16202,5 @@"sibling_x_runs": 1}}- ],- "performance_validation": {- "baseline_p95_seconds": 2.499708,- "current_p95_seconds": 2.565039,- "p95_change_ratio": 0.0261,- "baseline_total_seconds": 17.466309,- "current_total_seconds": 17.340156,- "total_change_ratio": -0.0072- }+ ]}diff --git a/tests/unittest/test_docx_complex_fields.py b/tests/unittest/test_docx_complex_fields.pyindex 8f788621..ede12ae1 100644--- a/tests/unittest/test_docx_complex_fields.py+++ b/tests/unittest/test_docx_complex_fields.py@@ -13,6 +13,7 @@ from mineru.backend.postprocess.inline import inline_plain_textfrom mineru.model.flash import DocxModelfrom mineru.model.flash._shared.spans import inline_span_plain_textfrom mineru.types import IndexBlock, ParagraphTitleBlock, TextBlock+from _span_test_utils import inline_urlsdef _append_field_char(paragraph: Paragraph, field_type: str) -> None:@@ -128,6 +129,24 @@ def _build_complex_toc_docx() -> bytes:return output.getvalue()+def _build_external_bookmark_field_docx() -> bytes:+ """生成同时包含外部文档地址与 bookmark switch 的复杂字段。"""++ document = Document()+ paragraph = document.add_paragraph()+ _append_field_char(paragraph, "begin")+ _append_instruction(+ paragraph,+ ' HYPERLINK "chapter.docx" \\l "Section1" ',+ )+ _append_field_char(paragraph, "separate")+ _append_result_text(paragraph, "Open section")+ _append_field_char(paragraph, "end")+ output = BytesIO()+ document.save(output)+ return output.getvalue()++def test_nested_complex_toc_fields_preserve_titles_and_strict_index_targets() -> None:"""验证拆分且嵌套的复杂域不会只剩页码,并按真实正文目标收敛目录 anchor。"""file_bytes = _build_complex_toc_docx()@@ -148,3 +167,19 @@ def test_nested_complex_toc_fields_preserve_titles_and_strict_index_targets() ->assert isinstance(typed_index.content[1], TextBlock)assert typed_index.content[1].anchor is Noneassert inline_plain_text(typed_index.content[1].content) == "二、缺失章节\t9"+++def test_external_complex_hyperlink_preserves_bookmark_switch() -> None:+ """验证外部复杂字段把文档地址与 bookmark 合成为同一个链接目标。"""++ file_bytes = _build_external_bookmark_field_docx()+ model_pages = DocxModel().predict(BytesIO(file_bytes))+ raw_text = next(block for page in model_pages for block in page if block["type"] == "text")++ assert inline_span_plain_text(raw_text["content"]) == "Open section"+ assert inline_urls(raw_text["content"]) == ["chapter.docx#Section1"]++ middle_json, _ = doc_analyze(file_bytes, effort="flash", parse_mode="auto", file_suffix="docx")+ typed_text = next(block for page in middle_json.pages for block in page.blocks if isinstance(block, TextBlock))+ assert inline_plain_text(typed_text.content) == "Open section"+ assert inline_urls(typed_text.content) == ["chapter.docx#Section1"]diff --git a/tests/unittest/test_flash_pdf_semantics.py b/tests/unittest/test_flash_pdf_semantics.pyindex e5a7d0b9..c304e92f 100644--- a/tests/unittest/test_flash_pdf_semantics.py+++ b/tests/unittest/test_flash_pdf_semantics.py@@ -12,6 +12,7 @@ from typing import Anyfrom mineru.model.flash.pdf.document import PDFDocumentfrom mineru.model.flash.pdf.pipeline import _analyze_native_documentfrom scripts.review_flash_layout_geometry import (+ _geometry_summary_mismatch,_page_bbox_fingerprint,_page_fingerprint,)@@ -387,3 +388,44 @@ def test_chinese_paper_continuation_caption_precedes_tight_table_body() -> None:assert _normalized_text(caption.get("content")) == "续表"assert "续表" not in str(table.get("content") or "")assert float(caption["bbox"][3]) < float(table["bbox"][1])+++def test_flash_layout_geometry_summary_comparison_is_strict() -> None:+ """验证几何摘要缺失或任一计数漂移都会形成独立门禁失败。"""++ expected = {+ "expected_geometry_summary": {+ "repaired_chars": 10,+ "repaired_lines": 2,+ }+ }+ actual = {+ "geometry_summary": {+ "repaired_chars": 10,+ "repaired_lines": 2,+ }+ }++ assert _geometry_summary_mismatch("sample.pdf", expected, actual) is None+ assert _geometry_summary_mismatch("sample.pdf", {}, actual) == {+ "file": "sample.pdf",+ "reason": "geometry_summary_expectation_missing",+ }+ assert _geometry_summary_mismatch(+ "sample.pdf",+ expected,+ {+ "geometry_summary": {+ "repaired_chars": 10,+ "repaired_lines": 1,+ }+ },+ ) == {+ "file": "sample.pdf",+ "reason": "geometry_summary_mismatch",+ "expected": expected["expected_geometry_summary"],+ "actual": {+ "repaired_chars": 10,+ "repaired_lines": 1,+ },+ }diff --git a/tests/unittest/test_latex_render.py b/tests/unittest/test_latex_render.pyindex f8a6ad75..283dc0e9 100644--- a/tests/unittest/test_latex_render.py+++ b/tests/unittest/test_latex_render.py@@ -268,6 +268,37 @@ def test_latex_renders_visual_blocks_complex_tables_and_code_in_source_order() -assert r"{\small\ttfamily Step \(x^2\)\par}" in rendered+def test_latex_table_cell_preserves_interleaved_text_image_and_nested_table_order() -> None:+ """验证单元格文字、图片与嵌套表格严格保持 HTML 来源顺序。"""++ table = TableBlock(+ type="table",+ index=0,+ content=[+ TableBodyBlock(+ type="table_body",+ index=0,+ content=(+ "<table><tr><td><b>before<img src='images/cell.png' alt='cell'>after</b>"+ "<table><tr><td>nested</td></tr></table>tail</td></tr></table>"+ ),+ )+ ],+ )++ rendered = render_latex(+ _middle(_page(0, table)),+ asset_base_path="assets",+ )++ before_index = rendered.index(r"\textbf{before}")+ image_index = rendered.index(r"\detokenize{assets/images/cell.png}")+ after_index = rendered.index(r"\textbf{after}")+ nested_index = rendered.index("nested")+ tail_index = rendered.index("tail")+ assert before_index < image_index < after_index < nested_index < tail_index++def test_latex_image_and_table_fallbacks_remain_visible_without_io() -> None:"""验证远程、data URI、不支持格式和畸形表格均退化为可见内容。"""remote = ImageBlock(