docvortex 0.2.1__py3-none-any.whl

docvortex/render/_internal/pdf/styles.py

@@ -0,0 +1,206 @@
+"""PDF renderer 的页面几何、字体与打印样式。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import resources
+from threading import RLock
+
+from reportlab.lib import colors
+from reportlab.lib.enums import TA_CENTER, TA_LEFT
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib.units import mm
+from reportlab.pdfbase import cidfonts, pdfmetrics
+from reportlab.pdfbase.ttfonts import TTFont
+
+PAGE_MARGIN = 20 * mm
+BODY_FONT = "Helvetica"
+BODY_BOLD_FONT = "Helvetica-Bold"
+MONO_FONT = "Courier"
+HAN_FONT = "STSong-Light"
+JAPANESE_FONT = "HeiseiMin-W3"
+KOREAN_FONT = "HYSMyeongJo-Medium"
+UNICODE_FALLBACK_FONT = "DocVortex-DejaVuSans"
+
+ACCENT_COLOR = colors.HexColor("#0b6fc2")
+BACKGROUND_COLOR = colors.HexColor("#ffffff")
+BORDER_COLOR = colors.HexColor("#d1d5db")
+MUTED_COLOR = colors.HexColor("#6b7280")
+SURFACE_COLOR = colors.HexColor("#f8fafc")
+TEXT_COLOR = colors.HexColor("#1f2937")
+
+_FONT_LOCK = RLock()
+_HEADING_SIZES = (20.0, 16.0, 14.0, 12.0, 11.0, 10.0)
+
+
+@dataclass(frozen=True, slots=True)
+class PdfStyleSet:
+    """保存 PDF renderer 使用的全部稳定段落样式。"""
+
+    body: ParagraphStyle
+    headings: tuple[ParagraphStyle, ...]
+    caption: ParagraphStyle
+    footnote: ParagraphStyle
+    code: ParagraphStyle
+    spatial_table: ParagraphStyle
+    formula_fallback: ParagraphStyle
+    placeholder: ParagraphStyle
+    table_cell: ParagraphStyle
+    table_header: ParagraphStyle
+
+    def heading(self, level: int) -> ParagraphStyle:
+        """按公开一到六级标题返回对应的 PDF 样式。"""
+        return self.headings[min(max(level, 1), len(self.headings)) - 1]
+
+
+def build_pdf_styles() -> PdfStyleSet:
+    """注册标准 CID 字体并构造无外部字体依赖的打印样式集。"""
+    _register_pdf_fonts()
+    body = ParagraphStyle(
+        "DocVortex PDF Body",
+        fontName=BODY_FONT,
+        fontSize=10.5,
+        leading=16,
+        textColor=TEXT_COLOR,
+        alignment=TA_LEFT,
+        spaceBefore=0,
+        spaceAfter=7,
+        splitLongWords=True,
+        allowWidows=1,
+        allowOrphans=1,
+    )
+    headings = tuple(
+        ParagraphStyle(
+            f"DocVortex PDF Heading {level}",
+            parent=body,
+            fontName=BODY_BOLD_FONT,
+            fontSize=size,
+            leading=size * 1.3,
+            spaceBefore=10 if level <= 3 else 8,
+            spaceAfter=6 if level <= 3 else 4,
+            keepWithNext=True,
+        )
+        for level, size in enumerate(_HEADING_SIZES, start=1)
+    )
+    caption = ParagraphStyle(
+        "DocVortex PDF Caption",
+        parent=body,
+        fontSize=9,
+        leading=12,
+        textColor=MUTED_COLOR,
+        spaceBefore=3,
+        spaceAfter=5,
+    )
+    footnote = ParagraphStyle(
+        "DocVortex PDF Footnote",
+        parent=body,
+        fontSize=8.5,
+        leading=11,
+        textColor=MUTED_COLOR,
+        spaceBefore=2,
+        spaceAfter=4,
+    )
+    code = ParagraphStyle(
+        "DocVortex PDF Code",
+        parent=body,
+        fontName=MONO_FONT,
+        fontSize=8.5,
+        leading=11,
+        backColor=SURFACE_COLOR,
+        borderColor=BORDER_COLOR,
+        borderWidth=0.5,
+        borderPadding=7,
+        borderRadius=3,
+        spaceBefore=5,
+        spaceAfter=7,
+    )
+    spatial_table = ParagraphStyle(
+        "DocVortex PDF Spatial Table",
+        parent=code,
+        backColor=BACKGROUND_COLOR,
+        borderPadding=5,
+    )
+    formula_fallback = ParagraphStyle(
+        "DocVortex PDF Formula Fallback",
+        parent=body,
+        fontName=MONO_FONT,
+        fontSize=9,
+        leading=13,
+        textColor=MUTED_COLOR,
+        alignment=TA_CENTER,
+        spaceBefore=5,
+        spaceAfter=6,
+    )
+    placeholder = ParagraphStyle(
+        "DocVortex PDF Placeholder",
+        parent=body,
+        fontSize=9,
+        leading=12,
+        textColor=MUTED_COLOR,
+        spaceBefore=0,
+        spaceAfter=0,
+    )
+    table_cell = ParagraphStyle(
+        "DocVortex PDF Table Cell",
+        parent=body,
+        fontSize=8.5,
+        leading=11,
+        spaceBefore=0,
+        spaceAfter=0,
+    )
+    table_header = ParagraphStyle(
+        "DocVortex PDF Table Header",
+        parent=table_cell,
+        fontName=BODY_BOLD_FONT,
+    )
+    return PdfStyleSet(
+        body=body,
+        headings=headings,
+        caption=caption,
+        footnote=footnote,
+        code=code,
+        spatial_table=spatial_table,
+        formula_fallback=formula_fallback,
+        placeholder=placeholder,
+        table_cell=table_cell,
+        table_header=table_header,
+    )
+
+
+def _register_pdf_fonts() -> None:
+    """幂等注册中日韩 CID 字体与 ziafont 自带 Unicode 回退字体。"""
+    with _FONT_LOCK:
+        registered = set(pdfmetrics.getRegisteredFontNames())
+        for font_name in (HAN_FONT, JAPANESE_FONT, KOREAN_FONT):
+            if font_name not in registered:
+                pdfmetrics.registerFont(cidfonts.UnicodeCIDFont(font_name))
+        if UNICODE_FALLBACK_FONT not in registered:
+            font_path = resources.files("ziafont").joinpath("fonts", "DejaVuSans.ttf")
+            pdfmetrics.registerFont(TTFont(UNICODE_FALLBACK_FONT, str(font_path)))
+        pdfmetrics.registerFontFamily(
+            UNICODE_FALLBACK_FONT,
+            normal=UNICODE_FALLBACK_FONT,
+            bold=UNICODE_FALLBACK_FONT,
+            italic=UNICODE_FALLBACK_FONT,
+            boldItalic=UNICODE_FALLBACK_FONT,
+        )
+
+
+__all__ = [
+    "ACCENT_COLOR",
+    "BACKGROUND_COLOR",
+    "BODY_BOLD_FONT",
+    "BODY_FONT",
+    "BORDER_COLOR",
+    "HAN_FONT",
+    "JAPANESE_FONT",
+    "KOREAN_FONT",
+    "MONO_FONT",
+    "MUTED_COLOR",
+    "PAGE_MARGIN",
+    "PdfStyleSet",
+    "SURFACE_COLOR",
+    "TEXT_COLOR",
+    "UNICODE_FALLBACK_FONT",
+    "build_pdf_styles",
+]

docvortex/render/_internal/pdf/table.py

@@ -0,0 +1,272 @@
+"""HTML table 到可分页 ReportLab 原生表格的安全物化。"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from bs4 import NavigableString, Tag
+from pydantic import ValidationError
+from reportlab.platypus import Flowable, LongTable, Paragraph, Table, TableStyle
+
+from ....schema import CodeInlineSpan, EquationInlineSpan, HyperlinkSpan, InlineSpan, InlineStyle, TextSpan, parse_inline_spans
+from ....foundation.hyperlink import OFFICE_EXTERNAL_HYPERLINK_SCHEMES, sanitize_hyperlink_target
+from ..common.html_table import (
+    HtmlTableCell,
+    HtmlTableError,
+    HtmlTableGrid,
+    HtmlTableSource,
+    MAX_NESTED_TABLE_DEPTH,
+    parse_html_tables as _parse_common_html_tables,
+)
+from .styles import BORDER_COLOR, SURFACE_COLOR, PdfStyleSet
+
+_BLOCK_TAGS = {"address", "article", "blockquote", "div", "figcaption", "footer", "header", "li", "p", "section"}
+_SKIPPED_TAGS = {"script", "style", "template", "noscript"}
+
+
+class PdfTableError(HtmlTableError):
+    """表示 HTML 表格结构或 PDF 表格几何无法安全物化。"""
+
+
+class ParagraphBuilder(Protocol):
+    """定义表格单元格创建富文本 Paragraph 的回调。"""
+
+    def __call__(self, spans: list[InlineSpan], style: object, max_width: float) -> Paragraph:
+        """把单元格行内 span 构造成指定宽度的 Paragraph。"""
+        ...
+
+
+class HtmlImageBuilder(Protocol):
+    """定义表格单元格创建离线图片或占位 Flowable 的回调。"""
+
+    def __call__(self, source: str, max_width: float, alt_text: str) -> Flowable:
+        """把 HTML img source 转换为图片或宽松占位。"""
+        ...
+
+
+def parse_html_tables(source: HtmlTableSource) -> tuple[HtmlTableGrid, ...]:
+    """复用共用网格解析，并保持 PDF 私有异常类型不变。"""
+    try:
+        return _parse_common_html_tables(source)
+    except HtmlTableError as exc:
+        raise PdfTableError(str(exc)) from exc
+
+
+def build_pdf_tables(
+    source: HtmlTableSource,
+    *,
+    available_width: float,
+    styles: PdfStyleSet,
+    build_paragraph: ParagraphBuilder,
+    build_image: HtmlImageBuilder,
+    depth: int = 1,
+) -> tuple[Table, ...]:
+    """把 HTML 表格递归转换为支持合并单元格与重复表头的 PDF 表格。"""
+    if depth > MAX_NESTED_TABLE_DEPTH:
+        raise PdfTableError(f"Nested table depth exceeds {MAX_NESTED_TABLE_DEPTH}")
+    if available_width <= 0:
+        raise PdfTableError("available_width must be positive")
+    grids = parse_html_tables(source)
+    return tuple(
+        _build_pdf_table(
+            grid,
+            available_width=available_width,
+            styles=styles,
+            build_paragraph=build_paragraph,
+            build_image=build_image,
+            depth=depth,
+        )
+        for grid in grids
+    )
+
+
+def _build_pdf_table(
+    grid: HtmlTableGrid,
+    *,
+    available_width: float,
+    styles: PdfStyleSet,
+    build_paragraph: ParagraphBuilder,
+    build_image: HtmlImageBuilder,
+    depth: int,
+) -> Table:
+    """物化一个网格，写入单元格内容、合并区域与固定打印样式。"""
+    column_widths = _column_widths(available_width, grid.column_count)
+    data: list[list[object]] = [["" for _ in range(grid.column_count)] for _ in range(grid.row_count)]
+    commands: list[tuple[object, ...]] = [
+        ("GRID", (0, 0), (-1, -1), 0.5, BORDER_COLOR),
+        ("VALIGN", (0, 0), (-1, -1), "TOP"),
+        ("LEFTPADDING", (0, 0), (-1, -1), 5),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 5),
+        ("TOPPADDING", (0, 0), (-1, -1), 4),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 4),
+    ]
+    for row_index in grid.header_rows:
+        commands.append(("BACKGROUND", (0, row_index), (-1, row_index), SURFACE_COLOR))
+    for placement in grid.cells:
+        cell_width = sum(column_widths[placement.column : placement.column + placement.colspan]) - 10
+        style = styles.table_header if placement.is_header else styles.table_cell
+        data[placement.row][placement.column] = _cell_flowables(
+            placement.tag,
+            max_width=max(1.0, cell_width),
+            style=style,
+            styles=styles,
+            build_paragraph=build_paragraph,
+            build_image=build_image,
+            depth=depth,
+        )
+        if placement.rowspan > 1 or placement.colspan > 1:
+            commands.append(
+                (
+                    "SPAN",
+                    (placement.column, placement.row),
+                    (placement.end_column, placement.end_row),
+                )
+            )
+    repeat_rows = 0
+    while repeat_rows in grid.header_rows:
+        repeat_rows += 1
+    table_class = LongTable if depth == 1 else Table
+    table = table_class(
+        data,
+        colWidths=column_widths,
+        repeatRows=repeat_rows,
+        splitByRow=1,
+        splitInRow=1,
+        hAlign="LEFT",
+    )
+    table.setStyle(TableStyle(commands))
+    return table
+
+
+def _cell_flowables(
+    cell: Tag,
+    *,
+    max_width: float,
+    style: object,
+    styles: PdfStyleSet,
+    build_paragraph: ParagraphBuilder,
+    build_image: HtmlImageBuilder,
+    depth: int,
+) -> list[Flowable]:
+    """把单元格文本、图片与直接嵌套表按安全顺序转换为 Flowable。"""
+    flowables: list[Flowable] = []
+    spans = _html_cell_spans(cell)
+    if spans:
+        flowables.append(build_paragraph(spans, style, max_width))
+    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)
+        flowables.append(build_image(str(source), max_width, str(alt)))
+    for nested in cell.find_all("table"):
+        if nested.find_parent(("td", "th")) is not cell:
+            continue
+        flowables.extend(
+            build_pdf_tables(
+                nested,
+                available_width=max_width,
+                styles=styles,
+                build_paragraph=build_paragraph,
+                build_image=build_image,
+                depth=depth + 1,
+            )
+        )
+    if not flowables:
+        flowables.append(build_paragraph([TextSpan(type="text", content=" ")], style, max_width))
+    return flowables
+
+
+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 []
+    try:
+        return parse_inline_spans(spans)
+    except (TypeError, ValidationError, ValueError) as exc:
+        raise PdfTableError("HTML table cell inline content is invalid") from exc
+
+
+def _html_node_spans(node: object, *, styles: tuple[InlineStyle, ...], allow_links: bool) -> list[InlineSpan]:
+    """递归解析安全 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"}:
+        return []
+    if name == "br":
+        return [TextSpan(type="text", content="\n", styles=list(styles))]
+    if name == "eq":
+        content = node.get_text()
+        return [EquationInlineSpan(type="equation_inline", content=content)] if content.strip() else []
+    if name == "code":
+        content = node.get_text()
+        return [CodeInlineSpan(type="code_inline", content=content)] if content else []
+    style_name: InlineStyle | None = {
+        "b": "bold",
+        "strong": "bold",
+        "i": "italic",
+        "em": "italic",
+        "u": "underline",
+        "s": "strikethrough",
+        "del": "strikethrough",
+        "sup": "superscript",
+        "sub": "subscript",
+    }.get(name)
+    child_styles = tuple(dict.fromkeys((*styles, style_name))) if style_name is not None else styles
+    if name == "a" and allow_links:
+        children = [
+            span
+            for child in node.children
+            for span in _html_node_spans(child, styles=child_styles, allow_links=False)
+            if not isinstance(span, HyperlinkSpan)
+        ]
+        target = sanitize_hyperlink_target(
+            node.get("href"),
+            allowed_schemes=OFFICE_EXTERNAL_HYPERLINK_SCHEMES,
+            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"))
+
+
+def _column_widths(total_width: float, column_count: int) -> list[float]:
+    """把可用宽度确定性地均分到全部逻辑列。"""
+    if column_count <= 0:
+        raise PdfTableError("Table must contain at least one column")
+    base = total_width / column_count
+    return [base for _ in range(column_count)]
+
+
+__all__ = [
+    "HtmlTableCell",
+    "HtmlTableGrid",
+    "MAX_NESTED_TABLE_DEPTH",
+    "PdfTableError",
+    "build_pdf_tables",
+    "parse_html_tables",
+]

docvortex/render/_internal/structured_content/__init__.py

@@ -0,0 +1,3 @@
+"""Structured Content 私有渲染实现。"""
+
+__all__: list[str] = []

docvortex/render/_internal/structured_content/renderer.py

@@ -0,0 +1,193 @@
+"""严格 MiddleJson 到树形 Markdown structured_content 的公共渲染实现。"""
+
+from __future__ import annotations
+
+from typing import Any, TypeAlias
+
+from ....options import LatexDelimitersConfig
+from ..markdown.blocks import (
+    render_single_block,
+    render_title_inline_content,
+    render_visual_annotation,
+    render_visual_body_content,
+)
+from ..markdown.assets import normalize_image_source, resolve_image_source
+from ..markdown.escaping import escape_standalone_marker_rule, escape_text_block_markdown_prefix
+from ..markdown.inline import render_inline_content
+from ....schema import (
+    BlockType,
+    ChartAnnotationBlock,
+    ChartBlock,
+    ChartBodyBlock,
+    CodeAnnotationBlock,
+    CodeBlock,
+    DocTitleBlock,
+    EquationBlock,
+    ImageAnnotationBlock,
+    ImageBlock,
+    ImageBodyBlock,
+    ImagePayloadBlock,
+    MiddleJson,
+    PageAuxTextBlock,
+    PageFootnoteBlock,
+    PageBlock,
+    ParagraphTitleBlock,
+    TextBlock,
+    TableAnnotationBlock,
+    TableBlock,
+    TableBodyBlock,
+)
+
+VisualBlock: TypeAlias = ImageBlock | TableBlock | ChartBlock | CodeBlock
+VisualAnnotationBlock: TypeAlias = ImageAnnotationBlock | TableAnnotationBlock | ChartAnnotationBlock | CodeAnnotationBlock
+
+_CAPTION_TYPES = {
+    BlockType.IMAGE_CAPTION,
+    BlockType.TABLE_CAPTION,
+    BlockType.CHART_CAPTION,
+    BlockType.CODE_CAPTION,
+}
+_FOOTNOTE_TYPES = {
+    BlockType.IMAGE_FOOTNOTE,
+    BlockType.TABLE_FOOTNOTE,
+    BlockType.CHART_FOOTNOTE,
+    BlockType.CODE_FOOTNOTE,
+}
+_REMOVED_BLOCK_FIELDS = {"content", "index", "guess_lang", "image_path", "image_base64", "image_url"}
+
+
+def render_structured_content(
+    middle_json: MiddleJson,
+    *,
+    asset_base_url: str = "",
+    latex_delimiters: LatexDelimitersConfig | None = None,
+) -> dict[str, Any]:
+    """把严格 MiddleJson 无副作用地渲染为树形 Markdown structured_content。"""
+    if not isinstance(middle_json, MiddleJson):
+        raise TypeError("render_structured_content expects a MiddleJson instance")
+
+    delimiters = latex_delimiters or LatexDelimitersConfig()
+    document_fields = middle_json.model_dump(
+        mode="json",
+        exclude={"pages", "schema_id", "schema_version"},
+        exclude_defaults=True,
+    )
+    pages = [
+        {
+            "page_idx": page.page_idx,
+            "blocks": [
+                _render_content_block(
+                    block,
+                    delimiters=delimiters,
+                    asset_base_url=asset_base_url,
+                )
+                for block in page.blocks
+            ],
+        }
+        for page in middle_json.pages
+    ]
+    return {"pages": pages, **document_fields}
+
+
+def _render_content_block(
+    block: PageBlock,
+    *,
+    delimiters: LatexDelimitersConfig,
+    asset_base_url: str,
+) -> dict[str, Any]:
+    """保留父块元数据，并把 block 内容收敛为 Markdown 字符串。"""
+    payload = block.model_dump(
+        mode="json",
+        exclude=_REMOVED_BLOCK_FIELDS,
+        exclude_defaults=True,
+    )
+    if isinstance(block, (DocTitleBlock, ParagraphTitleBlock)):
+        content = render_title_inline_content(block, delimiters)
+        payload["content"] = escape_standalone_marker_rule(escape_text_block_markdown_prefix(content))
+        return payload
+    if isinstance(block, TextBlock):
+        content = render_inline_content(block.content, delimiters)
+        payload["content"] = escape_standalone_marker_rule(escape_text_block_markdown_prefix(content))
+        return payload
+    if isinstance(block, EquationBlock):
+        payload["content"] = block.content.strip()
+        image_source = _resolve_content_image_source(block, asset_base_url)
+        if image_source is not None:
+            payload["image_source"] = image_source
+        return payload
+    if isinstance(block, (PageAuxTextBlock, PageFootnoteBlock)):
+        content = escape_text_block_markdown_prefix(render_inline_content(block.content, delimiters))
+        payload["content"] = escape_standalone_marker_rule(content)
+        return payload
+    if not isinstance(block, (ImageBlock, TableBlock, ChartBlock, CodeBlock)):
+        payload["content"] = render_single_block(
+            block,
+            delimiters=delimiters,
+            asset_base_url=asset_base_url,
+        )
+        return payload
+
+    payload["content"] = render_visual_body_content(
+        block,
+        delimiters=delimiters,
+        asset_base_url=asset_base_url,
+    )
+    payload["captions"] = _render_annotation_group(block, _CAPTION_TYPES, delimiters)
+    payload["footnotes"] = _render_annotation_group(block, _FOOTNOTE_TYPES, delimiters)
+    image_source = _resolve_visual_image_source(block, asset_base_url)
+    if image_source is not None:
+        payload["image_source"] = image_source
+    return payload
+
+
+def _render_annotation_group(
+    block: VisualBlock,
+    accepted_types: set[str],
+    delimiters: LatexDelimitersConfig,
+) -> list[dict[str, Any]]:
+    """按源 index 稳定排序视觉说明，并保留可用 bbox 与 Markdown 内容。"""
+    annotations: list[tuple[int, VisualAnnotationBlock]] = []
+    for position, child in enumerate(block.content):
+        if (
+            isinstance(
+                child,
+                (ImageAnnotationBlock, TableAnnotationBlock, ChartAnnotationBlock, CodeAnnotationBlock),
+            )
+            and child.type in accepted_types
+        ):
+            annotations.append((position, child))
+    annotations.sort(key=_annotation_sort_key)
+    rendered_annotations: list[dict[str, Any]] = []
+    for _, child in annotations:
+        annotation_payload: dict[str, Any] = {}
+        if child.bbox is not None:
+            annotation_payload["bbox"] = list(child.bbox)
+        annotation_payload["content"] = render_visual_annotation(child, delimiters)
+        rendered_annotations.append(annotation_payload)
+    return rendered_annotations
+
+
+def _annotation_sort_key(
+    item: tuple[int, VisualAnnotationBlock],
+) -> tuple[bool, int, int]:
+    """让有 index 的说明升序优先，缺失 index 的说明稳定排在末尾。"""
+    position, block = item
+    return block.index is None, block.index if block.index is not None else 0, position
+
+
+def _resolve_visual_image_source(block: VisualBlock, asset_base_url: str) -> str | None:
+    """解析视觉 body 实际选择的图片来源，并返回安全的 Markdown 地址。"""
+    for child in block.content:
+        if not isinstance(child, (ImageBodyBlock, TableBodyBlock, ChartBodyBlock)):
+            continue
+        return _resolve_content_image_source(child, asset_base_url)
+    return None
+
+
+def _resolve_content_image_source(block: ImagePayloadBlock, asset_base_url: str) -> str | None:
+    """把图片载荷收敛为 structured_content 中唯一且安全的 image_source。"""
+    source = resolve_image_source(block, asset_base_url)
+    return normalize_image_source(source) if source else None
+
+
+__all__ = ["render_structured_content"]