Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

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.py
index 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:
@staticmethod
def _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}", True
return None, False
@classmethod
diff --git a/mineru/render/_internal/latex/table.py b/mineru/render/_internal/latex/table.py
index 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, Tag
from 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 | Tag
class 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_lin
child_styles = tuple(dict.fromkeys((*styles, style_name))) if style_name is not None else styles
if name == "a" and allow_links:
children = [
- span
+ token
for 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_lin
allow_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.py
index 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 0
if __name__ == "__main__":
diff --git a/tests/fixtures/flash_layout_geometry_manifest.json b/tests/fixtures/flash_layout_geometry_manifest.json
index 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.py
index 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_text
from mineru.model.flash import DocxModel
from mineru.model.flash._shared.spans import inline_span_plain_text
from mineru.types import IndexBlock, ParagraphTitleBlock, TextBlock
+from _span_test_utils import inline_urls
def _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 None
assert 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.py
index 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 Any
from mineru.model.flash.pdf.document import PDFDocument
from mineru.model.flash.pdf.pipeline import _analyze_native_document
from 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.py
index 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(