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": "
A
1
", + }, + {"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": "
A
2
", + }, + {"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: