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
Refactor image handling and enhance naming conventions for generated assets
myhloli61215f8c469d
diff --git a/docs/next/cli/mineru-kit-gradio.md b/docs/next/cli/mineru-kit-gradio.mdindex 4f3d28bb..3de8f4dd 100644--- a/docs/next/cli/mineru-kit-gradio.md+++ b/docs/next/cli/mineru-kit-gradio.md@@ -100,6 +100,8 @@ Gradio 首先发现 `/v1/health` 和 `/v1/tiers`,然后通过 `MinerUApiParser下载图标位于右侧结果栏的标签行最右端,鼠标悬停或键盘聚焦即可展开菜单。菜单包含 Markdown、JSON、HTML、DOCX、LaTeX、EPUB 和 PDF。下载文件由 Gradio 从本次保存的结果按需生成,不新增 API job 输出格式。Markdown 和 JSON 分别下载独立 ZIP,根目录放置同名 `.md` 或 `.json`,图片放在 `images/`,正文及 JSON 图片字段使用相对路径。JSON 内容使用 Structured Content,不包含 Middle JSON。LaTeX 下载包包含 `.tex` 与 `images/`,可交给 XeLaTeX 使用;Gradio 不自动执行 TeX 编译。预览和下载的单个 HTML 均使用当前 Gradio 服务的图片 HTTP 链接,不嵌入 base64;链接可用性取决于当前服务和任务文件。+图片名称使用原始零基页索引和所属父块的 `type/index`,例如 `images/page_1_image_3.jpg` 表示原第 2 页、索引为 3 的图片块。整表截图使用 `page_1_table_3.jpg`,表内图片按出现顺序使用 `page_1_table_image_3_1.png`、`page_1_table_image_3_2.png`。裁页不会重新编号,下载打包保持相同图片名称;代码和算法不生成截图。历史任务不迁移,重新转换后使用该命名。+每次选择格式后,按钮会显示“准备中”,文件就绪后自动开始下载,无需再次点击。再次下载时,HTML 根据当前访问地址重新生成,其他格式复用已有文件;生成失败时显示错误并允许重试。清除、更换文件或重新解析会使旧下载请求失效。每次解析的文件保存在独立的 `output-dir/gradio/<run-id>/` 目录,包含源文件、Middle JSON、基础文本产物以及可选的 `origin.pdf`、`layout.pdf` 和图片资源。路径只向 Gradio 暴露在配置的 output root 内。diff --git a/mineru/kit/gradio/artifacts.py b/mineru/kit/gradio/artifacts.pyindex aed8c5d8..19785a73 100644--- a/mineru/kit/gradio/artifacts.py+++ b/mineru/kit/gradio/artifacts.py@@ -2,7 +2,6 @@from __future__ import annotations-import hashlibimport htmlimport jsonimport re@@ -33,7 +32,20 @@ from ...render import (StructuredContentRenderOptions,render,)-from ...types import BlockBase, ImagePayloadBlock, MiddleJson+from ...types import (+ AlgorithmBodyBlock,+ BlockBase,+ ChartBlock,+ ChartBodyBlock,+ CodeBlock,+ CodeBodyBlock,+ ImageBlock,+ ImageBodyBlock,+ ImagePayloadBlock,+ MiddleJson,+ TableBlock,+ TableBodyBlock,+)from docvortex.foundation.image_payload import parse_image_data_uri_strictfrom docvortex.foundation.image_payload import validate_image_sidecar_path@@ -153,29 +165,27 @@ class _ImageContext:source_page_by_middle_page: dict[int, int]output_dir: Pathasset_root: Path- image_paths: dict[tuple[int, str, int | None, tuple[float, ...]], str] = field(default_factory=dict)+ crop_cache: dict[tuple[int, tuple[float, ...]], bytes] = field(default_factory=dict)- def crop_for_block(self, block: BlockBase, *, middle_page_idx: int) -> tuple[str, bytes] | None:- """按严格 block bbox 从源 PDF 裁剪图片并写入任务目录。"""+ def crop_for_block(self, block: BlockBase, *, middle_page_idx: int) -> bytes | None:+ """按 bbox 读取裁后 PDF 页面,仅缓存图片字节,不写出临时图片文件。"""if self.source_pdf is None or block.bbox is None:return Nonesource_page_idx = self.source_page_by_middle_page.get(middle_page_idx, middle_page_idx)if source_page_idx < 0 or source_page_idx >= self.source_pdf.page_count:return Nonebbox = tuple(float(item) for item in block.bbox)- key = (source_page_idx, str(block.type), block.index, bbox)- existing = self.image_paths.get(key)+ key = (middle_page_idx, bbox)+ existing = self.crop_cache.get(key)if existing is not None:- path = self.output_dir / existing- return existing, path.read_bytes() if path.is_file() else b""+ return existingtry:data = self.source_pdf.crop_image(block.bbox, source_page_idx)except Exception as exc:logger.warning("Failed to crop Gradio PDF image page={} bbox={}: {}", source_page_idx, bbox, exc)return None- relative = _write_materialized_asset(self.output_dir, data, "jpg")- self.image_paths[key] = relative- return relative, data+ self.crop_cache[key] = data+ return datadef create_run_artifacts(source_path: Path, output_root: Path) -> RunArtifacts:@@ -368,82 +378,62 @@ def render_download(result = ParseResult.from_json(artifacts.middle_json_path.read_text(encoding="utf-8"))middle_json = result.middle_json- image_context = _build_image_context(middle_json, None, artifacts.root)- try:- if download_format == "docx":- target = artifacts.downloads_dir / f"{artifacts.stem}.docx"- _ensure_path_inside(artifacts.root, target)- docx_middle = _materialize_middle_json(middle_json, image_context)- value = cast(- bytes,- render(- docx_middle,- RenderFormat.DOCX,- options=DocxRenderOptions(asset_resolver=_asset_resolver(artifacts.root)),- ),- )- target.write_bytes(value)- elif download_format == "epub":- target = artifacts.downloads_dir / f"{artifacts.stem}.epub"- _ensure_path_inside(artifacts.root, target)- epub_middle = _materialize_middle_json(middle_json, image_context)- value = cast(- bytes,- render(- epub_middle,- RenderFormat.EPUB,- options=EpubRenderOptions(title=artifacts.stem, asset_resolver=_asset_resolver(artifacts.root)),- ),- )- target.write_bytes(value)- elif download_format == "pdf":- target = artifacts.downloads_dir / f"{artifacts.stem}_rendered.pdf"- _ensure_path_inside(artifacts.root, target)- pdf_middle = _materialize_middle_json(middle_json, image_context)- value = cast(- bytes,- render(- pdf_middle,- RenderFormat.PDF,- options=PdfRenderOptions(- document_title=artifacts.stem,- asset_resolver=_asset_resolver(artifacts.root),- ),- ),- )- target.write_bytes(value)- else:- target = artifacts.downloads_dir / f"{artifacts.stem}_latex.zip"- latex_root = artifacts.downloads_dir / "latex"- _ensure_path_inside(artifacts.root, target)- _ensure_path_inside(artifacts.root, latex_root)- latex_root.mkdir(parents=True, exist_ok=True)- latex_context = _build_image_context(+ if download_format == "docx":+ target = artifacts.downloads_dir / f"{artifacts.stem}.docx"+ _ensure_path_inside(artifacts.root, target)+ value = cast(+ bytes,+ render(middle_json,- None,- latex_root,- asset_root=artifacts.root,- )- try:- latex_middle = _materialize_middle_json(middle_json, latex_context)- latex_text = cast(- str,- render(- latex_middle,- RenderFormat.LATEX,- options=LatexRenderOptions(document_title=artifacts.stem),- ),- )- tex_path = latex_root / f"{artifacts.stem}.tex"- tex_path.write_text(latex_text, encoding="utf-8")- _zip_directory(latex_root, target)- finally:- _close_image_context(latex_context)+ RenderFormat.DOCX,+ options=DocxRenderOptions(asset_resolver=_asset_resolver(artifacts.root)),+ ),+ )+ target.write_bytes(value)+ elif download_format == "epub":+ target = artifacts.downloads_dir / f"{artifacts.stem}.epub"_ensure_path_inside(artifacts.root, target)- artifacts.generated_downloads[download_format] = target- return str(target)- finally:- _close_image_context(image_context)+ value = cast(+ bytes,+ render(+ middle_json,+ RenderFormat.EPUB,+ options=EpubRenderOptions(title=artifacts.stem, asset_resolver=_asset_resolver(artifacts.root)),+ ),+ )+ target.write_bytes(value)+ elif download_format == "pdf":+ target = artifacts.downloads_dir / f"{artifacts.stem}_rendered.pdf"+ _ensure_path_inside(artifacts.root, target)+ value = cast(+ bytes,+ render(+ middle_json,+ RenderFormat.PDF,+ options=PdfRenderOptions(+ document_title=artifacts.stem,+ asset_resolver=_asset_resolver(artifacts.root),+ ),+ ),+ )+ target.write_bytes(value)+ else:+ target = artifacts.downloads_dir / f"{artifacts.stem}_latex.zip"+ latex_root = artifacts.downloads_dir / "latex"+ _ensure_path_inside(artifacts.root, target)+ _ensure_path_inside(artifacts.root, latex_root)+ latex_root.mkdir(parents=True, exist_ok=True)+ _copy_materialized_images(artifacts.root, latex_root)+ latex_text = cast(+ str,+ render(middle_json, RenderFormat.LATEX, options=LatexRenderOptions(document_title=artifacts.stem)),+ )+ tex_path = latex_root / f"{artifacts.stem}.tex"+ tex_path.write_text(latex_text, encoding="utf-8")+ _zip_directory(latex_root, target)+ _ensure_path_inside(artifacts.root, target)+ artifacts.generated_downloads[download_format] = target+ return str(target)def _prepare_origin_pdf(@@ -535,7 +525,7 @@ def _materialize_middle_json(middle_json: MiddleJson, context: _ImageContext) ->"""复制 Middle JSON,并为 PDF bbox 或 inline image 准备目标 renderer 所需的图片载荷。"""copied = middle_json.model_copy(deep=True)for page in copied.pages:- page.blocks = [_materialize_block(block, context, middle_page_idx=page.page_idx) for block in page.blocks]+ page.blocks = [_materialize_block(block, context, middle_page_idx=page.page_idx, owner=block) for block in page.blocks]return copied@@ -544,8 +534,13 @@ def _materialize_block(context: _ImageContext,*,middle_page_idx: int,+ owner: BlockBase,) -> BlockBase:- """递归复制 block 树,并统一处理图片 data URI、sidecar 和 PDF bbox。"""+ """沿语义树传递所属视觉父块,仅为图片载荷和富 HTML 正文物化素材。"""+ if isinstance(block, (CodeBlock, CodeBodyBlock, AlgorithmBodyBlock)):+ return block+ if isinstance(block, (ImageBlock, TableBlock, ChartBlock)):+ owner = blockupdates: dict[str, Any] = {}if isinstance(block, ImagePayloadBlock):data: bytes | None = None@@ -563,43 +558,81 @@ def _materialize_block(data = candidate.read_bytes()extension = candidate.suffix.lstrip(".") or extensionelif block.bbox is not None:- cropped = context.crop_for_block(block, middle_page_idx=middle_page_idx)- if cropped is not None:- relative, data = cropped- extension = Path(relative).suffix.lstrip(".") or extension+ data = context.crop_for_block(block, middle_page_idx=middle_page_idx)if data:- updates["image_path"] = _write_materialized_asset(context.output_dir, data, extension)+ updates["image_path"] = _write_materialized_asset(+ context.output_dir,+ data,+ extension,+ page_idx=middle_page_idx,+ owner=owner,+ )updates["image_base64"] = Noneupdates["image_url"] = Nonecontent = getattr(block, "content", None)if isinstance(content, list):- updates["content"] = [_materialize_block(child, context, middle_page_idx=middle_page_idx) for child in content]- elif isinstance(content, str) and "<img" in content.lower():- updates["content"] = _materialize_markup_images(content, context)+ updates["content"] = [+ _materialize_block(child, context, middle_page_idx=middle_page_idx, owner=owner)+ if isinstance(child, BlockBase)+ else child+ for child in content+ ]+ elif isinstance(block, (ImageBodyBlock, TableBodyBlock, ChartBodyBlock)) and "<img" in content.lower():+ updates["content"] = _materialize_markup_images(content, context, page_idx=middle_page_idx, owner=owner)return block.model_copy(update=updates, deep=True) if updates else block-def _write_materialized_asset(output_dir: Path, data: bytes, extension: str) -> str:- """按图片内容生成稳定文件名,避免无 index 的嵌套图片互相覆盖。"""+def _write_materialized_asset(+ output_dir: Path,+ data: bytes,+ extension: str,+ *,+ page_idx: int,+ owner: BlockBase,+ ordinal: int | None = None,+) -> str:+ """使用原始页索引和所属块命名,表内多图区分序号,冲突文件禁止覆盖。"""safe_extension = extension.lower().lstrip(".") or "jpg"if f".{safe_extension}" not in _IMAGE_SUFFIXES:raise ValueError(f"Unsupported image extension: {extension}")- relative = f"images/{hashlib.sha256(data).hexdigest()}.{safe_extension}"- target = output_dir / relative- _ensure_path_inside(output_dir, target)- target.parent.mkdir(parents=True, exist_ok=True)- if not target.exists():- target.write_bytes(data)- return relative---def _materialize_markup_images(content: str, context: _ImageContext) -> str:- """将内嵌 HTML 的 data URI 和已有相对图片统一复制到目标 images 目录。"""+ if owner.index is None:+ raise ValueError("Image owner must have a block index")+ kind = str(owner.type)+ if ordinal is not None and kind != "image":+ kind += "_image"+ suffix = f"_{ordinal}" if ordinal is not None else ""+ stem = f"page_{page_idx}_{kind}_{owner.index}{suffix}"+ # 冲突后缀独立于表内图片序号,避免占用另一张内嵌图片的正式名称。+ for attempt in range(10000):+ duplicate = f"_duplicate_{attempt}" if attempt else ""+ relative = validate_image_sidecar_path(f"images/{stem}{duplicate}.{safe_extension}")+ target = output_dir / relative+ _ensure_path_inside(output_dir, target)+ target.parent.mkdir(parents=True, exist_ok=True)+ if not target.exists():+ target.write_bytes(data)+ return relative+ if target.is_file() and target.read_bytes() == data:+ return relative+ raise ValueError("Too many conflicting image assets")+++def _materialize_markup_images(+ content: str,+ context: _ImageContext,+ *,+ page_idx: int,+ owner: BlockBase,+) -> str:+ """按富 HTML 中的出现顺序,为所属视觉块的内嵌图片分配语义名称。"""+ ordinal = 0def replace(match: re.Match[str]) -> str:"""解析一个 img 的图片载荷并保留原有 HTML 属性及引号。"""+ nonlocal ordinal+ ordinal += 1source = html.unescape(match.group("src")).strip()if source.startswith("data:"):data, extension = parse_image_data_uri_strict(source)@@ -611,12 +644,34 @@ def _materialize_markup_images(content: str, context: _ImageContext) -> str:_ensure_path_inside(context.asset_root, candidate)data = candidate.read_bytes()extension = candidate.suffix.lstrip(".")- relative = _write_materialized_asset(context.output_dir, data, extension)+ relative = _write_materialized_asset(+ context.output_dir,+ data,+ extension,+ page_idx=page_idx,+ owner=owner,+ ordinal=ordinal,+ )return f"{match.group('prefix')}{match.group('quote')}{relative}{match.group('quote')}"return _HTML_IMAGE_RE.sub(replace, content)+def _copy_materialized_images(asset_root: Path, output_dir: Path) -> None:+ """把已有素材按原始相对路径复制到下载包,不重新物化或改变图片名称。"""+ images = asset_root / "images"+ _ensure_path_inside(asset_root, images)+ for source in sorted(images.rglob("*")):+ _ensure_path_inside(images, source)+ if source.is_symlink():+ raise ValueError(f"Image assets must not contain symlinks: {source}")+ if source.is_file():+ target = output_dir / source.relative_to(asset_root)+ _ensure_path_inside(output_dir, target)+ target.parent.mkdir(parents=True, exist_ok=True)+ shutil.copyfile(source, target)++def _asset_resolver(root: Path) -> Callable[[str], bytes]:"""创建只允许读取当前任务目录内安全相对路径的 renderer asset resolver。"""resolved_root = root.resolve()diff --git a/tests/unittest/test_kit_gradio_html.py b/tests/unittest/test_kit_gradio_html.pyindex 63489c4d..58ab65ec 100644--- a/tests/unittest/test_kit_gradio_html.py+++ b/tests/unittest/test_kit_gradio_html.py@@ -70,7 +70,7 @@ def test_materialized_html_and_independent_archives(tmp_path: Path, image_sourceoriginal = middle.model_dump_json()artifacts = persist_parse_result(ParseResult(middle_json=middle), source, output_root=tmp_path / "输出 空格", page_range="")assert middle.model_dump_json() == original- assert len(list((artifacts.root / "images").iterdir())) == 2+ assert {path.name for path in (artifacts.root / "images").iterdir()} == {"page_0_image_1.png", "page_0_table_image_2_1.png"}assert "base64," not in artifacts.middle_json_path.read_text()# 后续导出只能读取物化素材,不再需要源文件或源目录中的图片。source.unlink()@@ -102,8 +102,9 @@ def test_materialized_html_and_independent_archives(tmp_path: Path, image_sourcedocument = archive.read(f"{artifacts.stem}.{extension}").decode()assert "base64," not in document and "gradio_api/file=" not in documentassert all(name.startswith("images/") or name == f"{artifacts.stem}.{extension}" for name in names)- references = set(re.findall(r"images/[a-f0-9]+\.png", document))- assert references and references.issubset(names)+ references = set(re.findall(r"images/page_\d+_[a-z_]+_\d+(?:_\d+)?\.png", document))+ assert references == {"images/page_0_image_1.png", "images/page_0_table_image_2_1.png"}+ assert references.issubset(names)assert {archive.read(name) for name in references} == {red, blue}if format_name == "json":structured = json.loads(document)diff --git a/tests/unittest/test_kit_gradio_image_names.py b/tests/unittest/test_kit_gradio_image_names.pynew file mode 100644index 00000000..5b60615f--- /dev/null+++ b/tests/unittest/test_kit_gradio_image_names.py@@ -0,0 +1,213 @@+"""原始页索引、所属父块和表内图片序号的语义命名回归。"""++from __future__ import annotations++import base64+import json+import zipfile+from pathlib import Path++import pytest+from bs4 import BeautifulSoup+from PIL import Image, ImageStat++from mineru.kit.gradio.artifacts import (+ _build_image_context,+ _close_image_context,+ _materialize_middle_json,+ _write_materialized_asset,+ persist_parse_result,+ render_download,+)+from mineru.parser.base import ParseResult+from mineru.types import (+ AlgorithmBodyBlock,+ BlockType,+ ChartBlock,+ ChartBodyBlock,+ CodeBlock,+ CodeBodyBlock,+ EquationBlock,+ TableBlock,+ TableBodyBlock,+ TextSpan,+)+from test_kit_gradio import _colored_pdf_bytes, _middle_json+from test_kit_gradio_html import _image_bytes+++def _image_uri(color: str) -> str:+ """生成有效 PNG data URI,供不同语义位置的命名测试复用。"""+ return "data:image/png;base64," + base64.b64encode(_image_bytes(color)).decode()++[email protected]("page_indices,page_range", [((1, 2), "2-3"), ((1, 3), "2,4")])+def test_crops_use_original_pages_and_parent_type(tmp_path: Path, page_indices: tuple[int, ...], page_range: str) -> None:+ """两页使用相同块索引时,裁后页号不得覆盖原始页号对应的图片。"""+ source = tmp_path / "colors.pdf"+ source.write_bytes(_colored_pdf_bytes([(1, 0, 0), (0, 1, 0), (0, 0, 1), (0, 0, 1)]))+ middle = _middle_json(page_indices=page_indices)+ for page in middle.pages:+ text, image = page.blocks+ body = image.content[0].model_copy(update={"index": 1})+ page.blocks = [text.model_copy(update={"index": 0}), image.model_copy(update={"index": 1, "content": [body]})]+ original = middle.model_dump_json()+ artifacts = persist_parse_result(+ ParseResult(middle_json=middle), source, output_root=tmp_path / "output", page_range=page_range+ )+ assert middle.model_dump_json() == original+ saved = ParseResult.from_json(artifacts.middle_json_path.read_text())+ expected = {f"page_{page_idx}_image_1.jpg" for page_idx in page_indices}+ assert {path.name for path in (artifacts.root / "images").iterdir()} == expected+ for page, channel in zip(saved.pages, (1, 2)):+ image_path = page.blocks[1].content[0].image_path+ assert image_path == f"images/page_{page.page_idx}_image_1.jpg"+ with Image.open(artifacts.root / image_path) as image:+ mean = ImageStat.Stat(image.convert("RGB")).mean+ assert mean[channel] > 240 and sum(value for index, value in enumerate(mean) if index != channel) < 20++ # 单独读取裁图缓存也不应产生任何临时图片文件。+ crop_root = tmp_path / "crop-only"+ context = _build_image_context(saved.middle_json, artifacts.origin_pdf_path, crop_root, page_indices=page_indices)+ try:+ block = saved.pages[0].blocks[1].content[0]+ first = context.crop_for_block(block, middle_page_idx=page_indices[0])+ assert first and context.crop_for_block(block, middle_page_idx=page_indices[0]) is first+ assert not crop_root.exists()+ finally:+ _close_image_context(context)+++def test_parent_names_table_images_and_repeated_materialization(tmp_path: Path) -> None:+ """截图按父块命名,表内多图按位置编号,相同图片内容不合并不同语义名称。"""+ source = tmp_path / "sample.docx"+ source.write_bytes(b"source")+ middle = _middle_json(file_suffix="docx")+ middle.pages[0].blocks[1].content[0].image_base64 = _image_uri("red")+ middle.pages[0].blocks[1].content[0].content = f'<img src="{_image_uri("blue")}">'+ middle.pages[0].blocks.extend(+ [+ TableBlock(+ type=BlockType.TABLE,+ index=2,+ content=[+ TableBodyBlock(+ type=BlockType.TABLE_BODY,+ index=2,+ image_base64=_image_uri("red"),+ content=(+ f'<table><tr><td><img src="{_image_uri("blue")}"></td>'+ f'<td><img src="{_image_uri("blue")}"></td></tr></table>'+ ),+ ),+ ],+ ),+ ChartBlock(+ type=BlockType.CHART,+ index=3,+ content=[+ ChartBodyBlock(type=BlockType.CHART_BODY, index=3, image_base64=_image_uri("red"), content=""),+ ],+ ),+ EquationBlock(type=BlockType.EQUATION, index=4, image_base64=_image_uri("red"), content="x^2"),+ ]+ )+ artifacts = persist_parse_result(ParseResult(middle_json=middle), source, output_root=tmp_path / "output", page_range="")+ expected = {+ "page_0_image_1.png",+ "page_0_image_1_1.png",+ "page_0_table_2.png",+ "page_0_table_image_2_1.png",+ "page_0_table_image_2_2.png",+ "page_0_chart_3.png",+ "page_0_equation_4.png",+ }+ before = {path.name: path.read_bytes() for path in (artifacts.root / "images").iterdir()}+ assert set(before) == expected+ saved = ParseResult.from_json(artifacts.middle_json_path.read_text())+ assert saved.pages[0].blocks[2].content[0].image_path == "images/page_0_table_2.png"+ table = BeautifulSoup(saved.pages[0].blocks[2].content[0].content, "html.parser")+ assert [image["src"] for image in table.find_all("img")] == [+ "images/page_0_table_image_2_1.png",+ "images/page_0_table_image_2_2.png",+ ]+ assert before["page_0_image_1.png"] == before["page_0_table_2.png"]+ context = _build_image_context(saved.middle_json, None, artifacts.root)+ repeated = _materialize_middle_json(saved.middle_json, context)+ assert repeated == saved.middle_json+ assert {path.name: path.read_bytes() for path in (artifacts.root / "images").iterdir()} == before+ for format_name in ("markdown", "json", "latex"):+ with zipfile.ZipFile(render_download(artifacts.as_state(), format_name)) as archive:+ images = {Path(name).name: archive.read(name) for name in archive.namelist() if name.startswith("images/")}+ assert images == before+ structured = json.loads(artifacts.structured_content_path.read_text())+ assert structured["pages"][0]["blocks"][2]["image_source"] == "images/page_0_table_2.png"+++def test_identical_images_on_different_pages_keep_their_names(tmp_path: Path) -> None:+ """像素相同的跨页图片仍使用各自的原始页索引,保留定位意义。"""+ middle = _middle_json(file_suffix="docx", page_indices=(2, 5))+ for page in middle.pages:+ page.blocks[1].content[0].image_base64 = _image_uri("red")+ context = _build_image_context(middle, None, tmp_path)+ result = _materialize_middle_json(middle, context)+ assert [page.blocks[1].content[0].image_path for page in result.pages] == [+ "images/page_2_image_21.png",+ "images/page_5_image_51.png",+ ]+ assert len(list((tmp_path / "images").iterdir())) == 2+++def test_conflicting_contents_never_overwrite_or_take_inline_ordinals(tmp_path: Path) -> None:+ """同名不同内容分配独立冲突后缀,并避免占用正文内嵌图片的正式序号。"""+ owner = _middle_json(file_suffix="docx").pages[0].blocks[1]+ first = _write_materialized_asset(tmp_path, _image_bytes("red"), "png", page_idx=1, owner=owner)+ second = _write_materialized_asset(tmp_path, _image_bytes("blue"), "png", page_idx=1, owner=owner)+ assert first == "images/page_1_image_1.png"+ assert second == "images/page_1_image_1_duplicate_1.png"+ assert _write_materialized_asset(tmp_path, _image_bytes("blue"), "png", page_idx=1, owner=owner) == second+ inline = _write_materialized_asset(tmp_path, _image_bytes("blue"), "png", page_idx=1, owner=owner, ordinal=1)+ assert inline == "images/page_1_image_1_1.png"+ assert (tmp_path / first).read_bytes() == _image_bytes("red")+ assert len(list((tmp_path / "images").iterdir())) == 3+++def test_code_and_algorithm_img_literals_are_not_materialized(tmp_path: Path) -> None:+ """代码与算法的 img 字面量不得读取资源、改变正文或生成截图。"""+ source = tmp_path / "code.docx"+ source.write_bytes(b"source")+ middle = _middle_json(with_image=False, file_suffix="docx")+ literal = '<img src="missing.png">'+ middle.pages[0].blocks.extend(+ [+ CodeBlock(+ type=BlockType.CODE,+ index=1,+ sub_type="code",+ guess_lang="html",+ content=[+ CodeBodyBlock(type=BlockType.CODE_BODY, index=1, bbox=(0, 0, 1, 1), content=literal),+ ],+ ),+ CodeBlock(+ type=BlockType.CODE,+ index=2,+ sub_type="algorithm",+ content=[+ AlgorithmBodyBlock(+ type=BlockType.ALGORITHM_BODY,+ index=2,+ bbox=(0, 0, 1, 1),+ content=[TextSpan(type="text", content=literal)],+ ),+ ],+ ),+ ]+ )+ original = middle.model_dump_json()+ artifacts = persist_parse_result(ParseResult(middle_json=middle), source, output_root=tmp_path / "output", page_range="")+ saved = ParseResult.from_json(artifacts.middle_json_path.read_text())+ assert saved.middle_json == middle and middle.model_dump_json() == original+ assert not (artifacts.root / "images").exists()+ assert saved.pages[0].blocks[1].content[0].content == literal+ assert saved.pages[0].blocks[2].content[0].content[0].content == literal