From bceb022d24d33b22a07c3c94c5267cb86a415fc2 Mon Sep 17 00:00:00 2001
From: kernelvale <258480682+kernelvale@users.noreply.github.com>
Date: Sat, 14 Nov 2026 04:20:23 +0800
Subject: [PATCH] feat(render): add continued table merging to structured
content
---
docs/JSON_PROTOCOL.md | 7 ++-
.../_internal/structured_content/renderer.py | 21 ++++++-
src/docvortex/render/api.py | 1 +
src/docvortex/render/contracts.py | 5 +-
src/docvortex/render/structured_content.py | 8 ++-
tests/unittest/test_render_api.py | 21 +++++++
.../test_structured_content_render.py | 60 +++++++++++++++++++
7 files changed, 118 insertions(+), 5 deletions(-)
diff --git a/docs/JSON_PROTOCOL.md b/docs/JSON_PROTOCOL.md
index 3cd43413..0bb76617 100644
--- a/docs/JSON_PROTOCOL.md
+++ b/docs/JSON_PROTOCOL.md
@@ -69,7 +69,12 @@ wrapper JSON need not equal the underlying Middle JSON byte for byte.
DocVortex retains its AssetStore and explicit sidecar export behavior.
Structured Content keeps its own content projection, shares metadata/extensions,
-and carries no Model/Middle schema identity. Content List V1/V2 remain MinerU outputs.
+and carries no Model/Middle schema identity. By default, its per-page blocks retain
+continued-table markers without merging content. Set `merge_continued_tables=True`
+in `StructuredContentRenderOptions`, or pass it to `render_structured_content()`, to
+merge marked table continuations through the shared table renderer. This option does
+not merge continued text or lists, keeps empty source pages, and does not mutate the
+input MiddleJson. Content List V1/V2 remain MinerU outputs.
Bundle manifests now use `docvortex.bundle` version `2.0`, with current document
JSON and the existing asset paths, sizes and hashes. Old bundles are rejected.
diff --git a/src/docvortex/render/_internal/structured_content/renderer.py b/src/docvortex/render/_internal/structured_content/renderer.py
index 0682357e..281ac909 100644
--- a/src/docvortex/render/_internal/structured_content/renderer.py
+++ b/src/docvortex/render/_internal/structured_content/renderer.py
@@ -13,6 +13,7 @@
)
from ..markdown.assets import normalize_image_source, resolve_image_source
from ..markdown.escaping import escape_standalone_marker_rule, escape_text_block_markdown_prefix
+from ..common.planner import PlannedBlock, _merge_continued_table_blocks
from ..markdown.inline import render_inline_content
from ....schema import (
BlockType,
@@ -61,10 +62,13 @@ def render_structured_content(
*,
asset_base_url: str = "",
latex_delimiters: LatexDelimitersConfig | None = None,
+ merge_continued_tables: bool = False,
) -> dict[str, Any]:
"""把严格 MiddleJson 无副作用地渲染为树形 Markdown structured_content。"""
if not isinstance(middle_json, MiddleJson):
raise TypeError("render_structured_content expects a MiddleJson instance")
+ if not isinstance(merge_continued_tables, bool):
+ raise TypeError("merge_continued_tables must be a bool")
delimiters = latex_delimiters or LatexDelimitersConfig()
document_fields = middle_json.model_dump(
@@ -72,19 +76,32 @@ def render_structured_content(
exclude={"pages", "schema_id", "schema_version"},
exclude_defaults=True,
)
+ render_middle = middle_json
+ render_blocks_by_source_id: dict[int, PageBlock] = {}
+ removed_block_ids: set[int] = set()
+ if merge_continued_tables:
+ render_middle = middle_json.model_copy(deep=True)
+ planned_blocks = [
+ PlannedBlock(page_idx=page.page_idx, block=block) for page in render_middle.pages for block in page.blocks
+ ]
+ planned_blocks_by_source_id = {id(planned.block): planned for planned in planned_blocks}
+ _merge_continued_table_blocks(planned_blocks)
+ render_blocks_by_source_id = {source_id: planned.block for source_id, planned in planned_blocks_by_source_id.items()}
+ removed_block_ids = {id(planned.block) for planned in planned_blocks if planned.removed}
pages = [
{
"page_idx": page.page_idx,
"blocks": [
_render_content_block(
- block,
+ render_blocks_by_source_id.get(id(block), block),
delimiters=delimiters,
asset_base_url=asset_base_url,
)
for block in page.blocks
+ if id(block) not in removed_block_ids
],
}
- for page in middle_json.pages
+ for page in render_middle.pages
]
return {"pages": pages, **document_fields}
diff --git a/src/docvortex/render/api.py b/src/docvortex/render/api.py
index 2f5edc3f..767cb9fd 100644
--- a/src/docvortex/render/api.py
+++ b/src/docvortex/render/api.py
@@ -193,6 +193,7 @@ def render(
middle_json,
latex_delimiters=resolved_options.latex_delimiters,
asset_base_url=resolved_options.asset_base_url,
+ merge_continued_tables=resolved_options.merge_continued_tables,
)
raise ValueError(f"Unsupported RenderFormat: {output_format}")
diff --git a/src/docvortex/render/contracts.py b/src/docvortex/render/contracts.py
index aa09ee18..d46c6a56 100644
--- a/src/docvortex/render/contracts.py
+++ b/src/docvortex/render/contracts.py
@@ -184,10 +184,13 @@ class StructuredContentRenderOptions:
latex_delimiters: LatexDelimitersConfig | None = None
asset_base_url: str = ""
+ merge_continued_tables: bool = False
def __post_init__(self) -> None:
- """在构造时校验图片资源根地址。"""
+ """在构造时校验图片资源根地址与续表合并开关。"""
_validate_asset_base_url(self.asset_base_url)
+ if not isinstance(self.merge_continued_tables, bool):
+ raise TypeError("merge_continued_tables must be a bool")
RenderOptions: TypeAlias = (
diff --git a/src/docvortex/render/structured_content.py b/src/docvortex/render/structured_content.py
index 1dd9e71e..8c065265 100644
--- a/src/docvortex/render/structured_content.py
+++ b/src/docvortex/render/structured_content.py
@@ -13,11 +13,17 @@ def render_structured_content(
*,
asset_base_url: str = "",
latex_delimiters: LatexDelimitersConfig | None = None,
+ merge_continued_tables: bool = False,
) -> dict[str, Any]:
"""惰性加载 Structured Content 实现并渲染严格 MiddleJson。"""
from ._internal.structured_content.renderer import render_structured_content as _render_structured_content
- return _render_structured_content(middle_json, asset_base_url=asset_base_url, latex_delimiters=latex_delimiters)
+ return _render_structured_content(
+ middle_json,
+ asset_base_url=asset_base_url,
+ latex_delimiters=latex_delimiters,
+ merge_continued_tables=merge_continued_tables,
+ )
__all__ = ["render_structured_content"]
diff --git a/tests/unittest/test_render_api.py b/tests/unittest/test_render_api.py
index f2f48864..9d1cd4e4 100644
--- a/tests/unittest/test_render_api.py
+++ b/tests/unittest/test_render_api.py
@@ -173,6 +173,25 @@ def test_unified_render_rejects_legacy_format_and_mismatched_options() -> None:
render(middle, RenderFormat.PDF, options=DocxRenderOptions())
+def test_structured_content_options_forward_table_merge(monkeypatch: pytest.MonkeyPatch) -> None:
+ """验证统一入口传递续表合并开关。"""
+ received = {}
+
+ def render_stub(middle_json, **kwargs):
+ received.update(kwargs)
+ return {}
+
+ monkeypatch.setattr("docvortex.render.api.render_structured_content", render_stub)
+ result = render(
+ _middle(_page(0)),
+ RenderFormat.STRUCTURED_CONTENT,
+ options=StructuredContentRenderOptions(merge_continued_tables=True),
+ )
+
+ assert result == {}
+ assert received["merge_continued_tables"] is True
+
+
def test_public_options_validate_fields() -> None:
"""验证 Options 构造期的严格字段类型检查。"""
with pytest.raises(TypeError, match="RenderMode"):
@@ -191,6 +210,8 @@ def test_public_options_validate_fields() -> None:
options_type(mode=RenderMode.DEFAULT)
with pytest.raises(TypeError, match="asset_base_url"):
StructuredContentRenderOptions(asset_base_url=1)
+ with pytest.raises(TypeError, match="merge_continued_tables"):
+ StructuredContentRenderOptions(merge_continued_tables=1)
with pytest.raises(TypeError, match="standalone"):
HtmlRenderOptions(standalone=1)
with pytest.raises(TypeError, match="document_title"):
diff --git a/tests/unittest/test_structured_content_render.py b/tests/unittest/test_structured_content_render.py
index 8592aff7..a38cb2a4 100644
--- a/tests/unittest/test_structured_content_render.py
+++ b/tests/unittest/test_structured_content_render.py
@@ -364,6 +364,66 @@ def test_structured_content_keeps_table_image_source_and_cross_page_metadata() -
assert image_only_output["image_source"] == "images/image-only-table.png"
+def test_structured_content_option_merges_only_continued_tables() -> None:
+ """验证可选续表合并不改变续段行为,也不污染输入文档。"""
+ bbox = [0.1, 0.1, 0.9, 0.9]
+ first = TableBlock.model_validate(
+ {
+ "type": "table",
+ "index": 0,
+ "bbox": bbox,
+ "content": [
+ {"type": "table_caption", "index": 0, "content": _inline("Table 1")},
+ {
+ "type": "table_body",
+ "index": 0,
+ "bbox": bbox,
+ "content": "
",
+ },
+ {"type": "table_footnote", "index": 2, "content": _inline("old note")},
+ ],
+ }
+ )
+ second = TableBlock.model_validate(
+ {
+ "type": "table",
+ "index": 0,
+ "bbox": bbox,
+ "continues_prev": True,
+ "content": [
+ {"type": "table_caption", "index": 0, "content": _inline("Table 1 (continued)")},
+ {
+ "type": "table_body",
+ "index": 0,
+ "bbox": bbox,
+ "content": "",
+ },
+ {"type": "table_footnote", "index": 2, "content": _inline("new note")},
+ ],
+ }
+ )
+ middle = _middle(
+ _page(0, first, TextBlock(type="text", index=3, content=_inline("first-"))),
+ _page(
+ 1,
+ second,
+ TextBlock(type="text", index=3, content=_inline("continued"), continues_prev=True),
+ ),
+ )
+ original = deepcopy(middle)
+
+ result = render_structured_content(middle, merge_continued_tables=True)
+
+ assert [block["type"] for block in result["pages"][0]["blocks"]] == ["table", "text"]
+ assert result["pages"][0]["blocks"][0]["content"] == "| A |\n| --- |\n| 1 |\n| 2 |"
+ assert result["pages"][0]["blocks"][0]["captions"] == [{"content": "Table 1"}]
+ assert result["pages"][0]["blocks"][0]["footnotes"] == [{"content": "new note"}]
+ assert result["pages"][0]["blocks"][1]["content"] == "first-"
+ assert result["pages"][1]["blocks"] == [{"type": "text", "content": "continued", "continues_prev": True}]
+ _assert_output_field_contract(result)
+ assert middle == original
+
+
def test_structured_content_keeps_chart_content_separate_from_base64_source(
monkeypatch: pytest.MonkeyPatch,
) -> None: