docvortex 0.4.2__tar.gz → 0.4.4__tar.gz

{docvortex-0.4.2/src/docvortex.egg-info → docvortex-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.2
+Version: 0.4.4
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -43,6 +43,7 @@ Requires-Dist: opencv-python>=4.11.0.86
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist<4,>=3.8; extra == "test"
 Requires-Dist: markdown; extra == "test"
 Requires-Dist: jsonschema<5,>=4; extra == "test"
 Provides-Extra: dev
@@ -106,6 +107,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.4}/README.md

@@ -53,6 +53,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.4}/docs/USAGE.md

@@ -7,6 +7,20 @@ you need access to intermediate results. All examples use the public Python SDK.
 Install with `pip install docvortex` and replace `report.pdf` with a local text PDF.
 Each example can be run independently in a fresh output directory.
 
+## Global CLI log level
+
+The root-level `--log-level` option controls loguru output for CLI commands.
+It defaults to `info`, supports `trace`, `debug`, `info`, `warning`, `error` and
+`critical`, and must be placed before the subcommand:
+
+```bash
+docvortex --log-level debug convert report.pdf --format markdown --output output/report.md
+```
+
+`DOCVORTEX_LOG_LEVEL` provides the same setting through an environment variable.
+An explicit `--log-level` value takes precedence. SDK imports do not change the
+host application's existing loguru sinks.
+
 ## Stage APIs
 
 The pipeline has three stages:

{docvortex-0.4.2 → docvortex-0.4.4}/docs/sdk-0.4.md

@@ -18,6 +18,12 @@ MinerU 使用 `docvortex>=0.4.0,<0.5.0`。本轮调整 Python 模块边界，保
 
 `docvortex.public_api.PUBLIC_API` 是静态模块及符号清单。新增跨库依赖必须同时更新清单、文档和契约测试；不能通过基础实现、私有模块或动态别名绕过边界。
 
+## 结果包素材导出（0.4.3）
+
+跨库调用方可通过 `docvortex.export.materialize_middle(middle_json, assets=None)` 获取图片外置后的文档副本与 `AssetStore`，再通过 `validate_materialized_assets(document, assets)` 验证所有图片引用。直接图片和视觉 HTML 内嵌图片使用安全相对路径，原始图片字节及布局方向扩展保持不变；代码字面量不作为 HTML 素材处理。
+
+调用方负责将该副本及素材写入自己的结果包，不应先省略图片再从源 PDF 重裁。缺失引用、未物化网络图片或同名素材冲突会显式失败。物化不修改输入对象、不读取源 PDF、不下载网络资源；已有外部素材须通过 `AssetStore` 显式提供。
+
 ## 行为与资源所有权
 
 `prepare_text_evidence` 返回具名的 `PDFTextEvidence`，`apply_text_evidence` 统一完成链接、样式、脚本与 InlineSpan 物化。MinerU 仍决定调用时机、公式排除区域、超大字符页和 OCR 回退。

{docvortex-0.4.2 → docvortex-0.4.4}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-cov", "markdown", "jsonschema>=4,<5"]
+test = ["pytest", "pytest-cov", "pytest-xdist>=3.8,<4", "markdown", "jsonschema>=4,<5"]
 dev = ["ruff==0.14.2", "build", "twine"]
 
 [project.urls]

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/cli.py

@@ -3,16 +3,36 @@
 from __future__ import annotations
 
 from pathlib import Path
+import sys
 
 import click
+from loguru import logger
 
 from .version import __version__
 
 
+_LOG_LEVELS = ("trace", "debug", "info", "warning", "error", "critical")
+
+
+def _configure_log_level(level: str) -> None:
+    """按全局参数重建 loguru 标准错误输出，并过滤低于该等级的日志。"""
+    logger.remove()
+    logger.add(sys.stderr, level=level.upper())
+
+
 @click.group(help="DocVortex: native multi-format document parsing and conversion.")
 @click.version_option(__version__)
-def main() -> None:
-    """提供独立文档引擎的命令行入口。"""
+@click.option(
+    "--log-level",
+    type=click.Choice(_LOG_LEVELS, case_sensitive=False),
+    default="info",
+    show_default=True,
+    envvar="DOCVORTEX_LOG_LEVEL",
+    help="Global loguru log level; place this root option before the command.",
+)
+def main(log_level: str) -> None:
+    """提供独立文档引擎的命令行入口，并应用全局日志等级。"""
+    _configure_log_level(log_level)
 
 
 @main.command("convert")

docvortex-0.4.4/src/docvortex/export/__init__.py

@@ -0,0 +1,5 @@
+"""文档副本与素材字节的公开导出边界。"""
+
+from .files import materialize_middle, validate_materialized_assets
+
+__all__ = ["materialize_middle", "validate_materialized_assets"]

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/export/middle.py

@@ -58,7 +58,11 @@ def _prepare_export_copy(middle_json: MiddleJson) -> tuple[MiddleJson, dict[str,
                 block.image_base64 = None  # type: ignore[attr-defined]
 
             content = getattr(block, "content", None)
-            if not isinstance(content, str) or "data:image/" not in content:
+            if (
+                str(block.type) not in {"table_body", "chart_body", "image_body"}
+                or not isinstance(content, str)
+                or "data:image/" not in content
+            ):
                 continue
             if block.index is None:
                 raise ValueError(f"HTML image carrier requires index: page_idx={page.page_idx}, type={block.type}")

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/public_api.py

@@ -165,6 +165,7 @@ PUBLIC_API: dict[str, tuple[str, ...]] = {
         "attach_visual_block_images",
         "attach_visual_block_images_from_pdf",
     ),
+    "docvortex.export": ("materialize_middle", "validate_materialized_assets"),
     "docvortex.errors": (
         "DocumentError",
         "InvalidRequestError",

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/render/_internal/pdf/diagnostics.py

@@ -12,6 +12,7 @@ from ....result import Diagnostic
 
 
 _diagnostics: ContextVar[list[Diagnostic] | None] = ContextVar("pdf_diagnostics", default=None)
+_DEBUG_DIAGNOSTIC_CODES = frozenset({"pdf_title_layout_expanded", "pdf_layout_scaled"})
 
 
 @contextmanager
@@ -26,8 +27,8 @@ def collect_pdf_diagnostics() -> Iterator[list[Diagnostic]]:
 
 
 def report_pdf_diagnostic(code: str, message: str, page_index: int | None = None) -> None:
-    """将同一条定位信息写入日志与当前高层产物的诊断列表。"""
-    logger.warning("{}: {}", code, message)
+    """PDF 渲染诊断统一使用 DEBUG 日志，结构化诊断保持完整。"""
+    logger.debug("{}: {}", code, message)
     items = _diagnostics.get()
     if items is not None:
         diagnostic = Diagnostic(code, message, page_index)

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/render/_internal/pdf/formula.py

@@ -356,7 +356,7 @@ def _local_name(tag: str) -> str:
 
 
 def _formula_preview(latex: str) -> str:
-    """为告警生成有界 LaTeX 摘要，避免超长公式污染日志。"""
+    """为诊断生成有界 LaTeX 摘要，避免超长公式污染日志。"""
     return latex if len(latex) <= 200 else f"{latex[:197]}..."
 
 

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/render/_internal/pdf/inline.py

@@ -43,7 +43,7 @@ class PdfAnchorRegistry:
         return self._names.get(normalized) if normalized else None
 
     def attach_markup(self, anchor: str | None) -> str:
-        """返回首个目标的 Paragraph anchor 标签，重复目标仅记录告警。"""
+        """返回首个目标的 Paragraph anchor 标签，重复目标仅记录诊断。"""
         normalized = (anchor or "").strip()
         name = self.resolve(normalized)
         if name is None:
@@ -85,7 +85,7 @@ class PdfInlineContext:
     next_formula_id: int = 0
 
     def location(self, page_idx: int, block_index: int | None, block_type: str) -> str:
-        """返回稳定的 page/block 告警定位文本。"""
+        """返回稳定的 page/block 诊断定位文本。"""
         return f"page_idx={page_idx}, block_index={block_index}, block_type={block_type}"
 
     def register_formula(self, image: InlineFormulaImage) -> str:

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/render/_internal/pdf/original.py

@@ -131,17 +131,19 @@ class OriginalPdfRenderer(_PdfRenderer):
             )
             if reasons:
                 plan.exception_count += 1
-                self._warning("pdf_layout_font_exception", f"reason={','.join(reasons)}, {detail}", item.page_idx, item.block)
+                self._diagnostic(
+                    "pdf_layout_font_exception", f"reason={','.join(reasons)}, {detail}", item.page_idx, item.block
+                )
             if item.geometry_conflict:
-                self._warning("pdf_title_geometry_conflict", detail, item.page_idx, item.block)
+                self._diagnostic("pdf_title_geometry_conflict", detail, item.page_idx, item.block)
             elif item.clearance_unavailable:
-                self._warning("pdf_title_clearance_unavailable", detail, item.page_idx, item.block)
+                self._diagnostic("pdf_title_clearance_unavailable", detail, item.page_idx, item.block)
             ox0, oy0, ox1, oy1 = item.original_rect
             dx0, dy0, dx1, dy1 = item.draw_rect
             expanded = dx0 < ox0 - 0.001 or dy0 < oy0 - 0.001 or dx1 > ox1 + 0.001 or dy1 > oy1 + 0.001
             if expanded:
                 plan.expanded_count += 1
-                self._warning("pdf_title_layout_expanded", detail, item.page_idx, item.block)
+                self._diagnostic("pdf_title_layout_expanded", detail, item.page_idx, item.block)
             plan.titles.append(
                 {
                     "page_idx": item.page_idx,
@@ -190,7 +192,9 @@ class OriginalPdfRenderer(_PdfRenderer):
                         )
                     )
                 return prepared
-            self._warning("pdf_layout_approximate", "Missing child bbox; fitting the group inside its parent", page_idx, block)
+            self._diagnostic(
+                "pdf_layout_approximate", "Missing child bbox; fitting the group inside its parent", page_idx, block
+            )
         assert block.bbox is not None
         x0, y0, x1, y1 = block.bbox
         width, height = (x1 - x0) * page_width, (y1 - y0) * page_height
@@ -226,14 +230,14 @@ class OriginalPdfRenderer(_PdfRenderer):
                 if prepared is not None:
                     return [self._prepared_image_flowable(prepared, block)]
             if isinstance(block, (TableBodyBlock, ChartBodyBlock)):
-                self._warning(
+                self._diagnostic(
                     "pdf_layout_visual_fallback", "Region image unavailable; rendering structured content", page_idx, block
                 )
                 if "<table" in block.content.lower():
                     try:
                         return list(self._html_tables(block.content, page_idx=page_idx, block=block))
                     except PdfTableError as exc:
-                        self._warning("pdf_table_fallback", str(exc), page_idx, block)
+                        self._diagnostic("pdf_table_fallback", str(exc), page_idx, block)
                 if block.content.strip():
                     return [self._preformatted(_plain_html_text(block.content), page_idx, block, self.styles.spatial_table)]
             return [self._placeholder("image unavailable", page_idx=page_idx, block=block, width=self.available_width)]
@@ -281,7 +285,7 @@ class OriginalPdfRenderer(_PdfRenderer):
         url: str | None = None,
     ) -> Paragraph:
         """用可测量段落展示缺失内容，避免固定高度的占位表格产生文字外溢。"""
-        self._warning("pdf_content_placeholder", label, page_idx, block)
+        self._diagnostic("pdf_content_placeholder", label, page_idx, block)
         spans = [TextSpan(type="text", content=label[:320] or "content unavailable")]
         if url:
             spans = [HyperlinkSpan(type="hyperlink", url=url, content=spans)]
@@ -322,11 +326,11 @@ class OriginalPdfRenderer(_PdfRenderer):
         """只绘制已经确认的测量结果，正文不重新排版，标题使用独立的安全绘制框。"""
         fit = item.fit
         if fit.small_text:
-            self._warning(
+            self._diagnostic(
                 "pdf_layout_small_text", f"Block fitted below 6 pt (scale={fit.scale:.4f})", item.page_idx, item.block
             )
         if fit.scale < 0.999:
-            self._warning("pdf_layout_scaled", f"Block fitted at scale={fit.scale:.4f}", item.page_idx, item.block)
+            self._diagnostic("pdf_layout_scaled", f"Block fitted at scale={fit.scale:.4f}", item.page_idx, item.block)
         rect = item.draw_rect or item.original_rect
         canvas.saveState()
         try:

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/render/_internal/pdf/renderer.py

@@ -332,7 +332,7 @@ class _PdfRenderer:
                 flowable.spaceAfter = 7
                 return [flowable]
             except PdfFormulaError as exc:
-                self._warning("pdf_formula_fallback", str(exc), page_idx, block)
+                self._diagnostic("pdf_formula_fallback", str(exc), page_idx, block)
         if _has_image_payload(block):
             image = self._try_prepared_block_image(block, page_idx)
             if image is not None:
@@ -433,7 +433,7 @@ class _PdfRenderer:
                         rendered.extend(self._html_tables(content, page_idx=page_idx, block=child))
                         continue
                     except PdfTableError as exc:
-                        self._warning("pdf_table_fallback", str(exc), page_idx, child)
+                        self._diagnostic("pdf_table_fallback", str(exc), page_idx, child)
                     if _has_image_payload(child):
                         image = self._try_prepared_block_image(child, page_idx)
                         if image is not None:
@@ -473,7 +473,7 @@ class _PdfRenderer:
                     try:
                         rendered.extend(self._html_tables(content, page_idx=page_idx, block=child))
                     except PdfTableError as exc:
-                        self._warning("pdf_table_fallback", str(exc), page_idx, child)
+                        self._diagnostic("pdf_table_fallback", str(exc), page_idx, child)
                         if not image_succeeded:
                             rendered.append(self._preformatted(_plain_html_text(content), page_idx, child, self.styles.body))
                 elif content and not image_succeeded:
@@ -573,7 +573,7 @@ class _PdfRenderer:
             try:
                 prepared = prepare_html_image(source, self.asset_resolver)
             except PdfAssetError as exc:
-                self._warning("pdf_image_unavailable", str(exc), page_idx, block)
+                self._diagnostic("pdf_image_unavailable", str(exc), page_idx, block)
                 return self._placeholder(
                     f"image unavailable: {alt_text}",
                     block=block,
@@ -616,11 +616,11 @@ class _PdfRenderer:
         )
 
     def _try_prepared_block_image(self, block: ImagePayloadBlock, page_idx: int) -> PreparedImage | None:
-        """尝试离线准备图片并把所有素材错误降级为 warning。"""
+        """尝试离线准备图片，并把素材错误统一记录为 DEBUG 诊断。"""
         try:
             return prepare_block_image(block, self.asset_resolver)
         except PdfAssetError as exc:
-            self._warning("pdf_image_unavailable", str(exc), page_idx, block)
+            self._diagnostic("pdf_image_unavailable", str(exc), page_idx, block)
             return None
 
     def _prepared_image_flowable(
@@ -659,7 +659,7 @@ class _PdfRenderer:
         url: str | None = None,
     ) -> Table:
         """创建带浅色边框、可选远程链接和定位文本的稳定占位框。"""
-        self._warning("pdf_content_placeholder", label, page_idx, block)
+        self._diagnostic("pdf_content_placeholder", label, page_idx, block)
         normalized = re.sub(r"\s+", " ", label).strip()[:_MAX_PLACEHOLDER_TEXT] or "content unavailable"
         markup = render_plain_text_markup(normalized)
         if url:
@@ -688,11 +688,11 @@ class _PdfRenderer:
 
     @staticmethod
     def _location(page_idx: int, block: BlockBase) -> str:
-        """返回 PDF 告警与占位使用的稳定 page/block 定位。"""
+        """返回 PDF 诊断与占位使用的稳定 page/block 定位。"""
         return f"page_idx={page_idx}, block_index={block.index}, block_type={block.type}"
 
-    def _warning(self, code: str, message: str, page_idx: int, block: BlockBase) -> None:
-        """用统一位置格式同时报告日志与结构化 PDF 诊断。"""
+    def _diagnostic(self, code: str, message: str, page_idx: int, block: BlockBase) -> None:
+        """用统一位置格式同时报告 DEBUG 日志与结构化 PDF 诊断。"""
         report_pdf_diagnostic(code, f"{message} ({self._location(page_idx, block)})", page_idx)
 
 

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.4.2"
+__version__ = "0.4.4"
 
 __all__ = ["__version__"]

{docvortex-0.4.2 → docvortex-0.4.4/src/docvortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.4.2
+Version: 0.4.4
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex
@@ -43,6 +43,7 @@ Requires-Dist: opencv-python>=4.11.0.86
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-xdist<4,>=3.8; extra == "test"
 Requires-Dist: markdown; extra == "test"
 Requires-Dist: jsonschema<5,>=4; extra == "test"
 Provides-Extra: dev
@@ -106,6 +107,8 @@ docvortex convert report.pdf --format markdown --output output/report.md
 
 Replace `report.pdf` with a local file in any supported input format.
 Use `--format` to choose the output; run `docvortex convert --help` for options.
+The root-level `--log-level` option controls loguru output and defaults to `info`.
+It must precede the command; `DOCVORTEX_LOG_LEVEL=warning` can also configure it.
 
 ### Python
 

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex.egg-info/SOURCES.txt

@@ -422,6 +422,7 @@ src/docvortex/resources/html/docvortex.min.css
 tests/test_architecture.py
 tests/test_benchmark_entrypoint.py
 tests/test_brand_protocol.py
+tests/test_cli_logging.py
 tests/test_complete_pipeline.py
 tests/test_converter_lifecycle.py
 tests/test_document_envelope.py
@@ -438,6 +439,7 @@ tests/test_pdf_output_text.py
 tests/test_pdf_render_pool.py
 tests/test_pdf_source_row_merging.py
 tests/test_pdf_symbol_normalization.py
+tests/test_public_export_api.py
 tests/test_public_image_api.py
 tests/test_public_pipeline.py
 tests/test_refactor_raster.py
@@ -557,6 +559,7 @@ tests/unittest/test_office_parser_regressions.py
 tests/unittest/test_pdf_cjk_wrapping.py
 tests/unittest/test_pdf_classify.py
 tests/unittest/test_pdf_demo_links.py
+tests/unittest/test_pdf_diagnostic_levels.py
 tests/unittest/test_pdf_document.py
 tests/unittest/test_pdf_original_layout.py
 tests/unittest/test_pdf_pagination.py

{docvortex-0.4.2 → docvortex-0.4.4}/src/docvortex.egg-info/requires.txt

@@ -33,5 +33,6 @@ twine
 [test]
 pytest
 pytest-cov
+pytest-xdist<4,>=3.8
 markdown
 jsonschema<5,>=4

docvortex-0.4.4/tests/test_cli_logging.py

@@ -0,0 +1,127 @@
+"""验证 CLI 全局 loguru 日志等级参数的解析与过滤行为。"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Iterator
+
+from click.testing import CliRunner
+from loguru import logger
+import pytest
+
+from docvortex import cli
+
+
+@pytest.fixture
+def isolated_logger() -> Iterator[None]:
+    """隔离 loguru 全局 sink，避免 CLI 日志测试影响其他用例。"""
+    logger.remove()
+    yield
+    logger.remove()
+    logger.add(sys.stderr)
+
+
+class _DummyPDFDocument:
+    """替身 PDF 文档，避免日志参数测试依赖真实 PDF 解析。"""
+
+    def __enter__(self) -> "_DummyPDFDocument":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> bool:
+        return False
+
+    def classify(self) -> str:
+        return "txt"
+
+
+def _invoke_classify(runner: CliRunner, source: Path, *arguments: str):
+    """调用 classify 子命令并返回执行结果，供日志参数断言复用。"""
+    return runner.invoke(cli.main, [*arguments, "classify", str(source)])
+
+
+def test_cli_log_level_defaults_to_info(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """未显式配置时，根命令默认传入 info 日志等级。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setattr("docvortex.document.pdf.PDFDocument", lambda _: _DummyPDFDocument())
+
+    result = _invoke_classify(CliRunner(), source)
+
+    assert result.exit_code == 0, result.output
+    assert levels == ["info"]
+
+
+def test_cli_log_level_accepts_root_option_and_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """根命令参数生效，且显式参数优先于环境变量。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setattr("docvortex.document.pdf.PDFDocument", lambda _: _DummyPDFDocument())
+    monkeypatch.setenv("DOCVORTEX_LOG_LEVEL", "warning")
+    runner = CliRunner()
+
+    environment_result = _invoke_classify(runner, source)
+    explicit_result = _invoke_classify(runner, source, "--log-level", "debug")
+
+    assert environment_result.exit_code == 0, environment_result.output
+    assert explicit_result.exit_code == 0, explicit_result.output
+    assert levels == ["warning", "debug"]
+
+
+def test_cli_rejects_invalid_log_level(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """非法日志等级在进入业务命令前被 Click 拒绝。"""
+    source = tmp_path / "source.pdf"
+    source.write_bytes(b"dummy")
+    levels = []
+    monkeypatch.setattr(cli, "_configure_log_level", levels.append)
+    monkeypatch.setenv("DOCVORTEX_LOG_LEVEL", "verbose")
+
+    result = _invoke_classify(CliRunner(), source)
+
+    assert result.exit_code != 0
+    assert "Invalid value" in result.output
+    assert levels == []
+
+
+@pytest.mark.parametrize(
+    ("level", "expected"),
+    [
+        ("info", ("debug hidden", False, "warning shown", True)),
+        ("debug", ("debug shown", True, "warning shown", True)),
+        ("error", ("warning hidden", False, "error shown", True)),
+    ],
+)
+def test_configure_log_level_filters_loguru_output(
+    isolated_logger, capsys: pytest.CaptureFixture[str], level: str, expected: tuple[str, bool, str, bool]
+) -> None:
+    """全局日志等级按 loguru 阈值过滤标准错误输出。"""
+    cli._configure_log_level(level)
+    logger.debug("debug hidden" if level == "info" else "debug shown")
+    logger.warning("warning hidden" if level == "error" else "warning shown")
+    logger.error("error shown")
+
+    stderr = capsys.readouterr().err
+    debug_message, debug_expected, warning_message, warning_expected = expected
+    assert (debug_message in stderr) is debug_expected
+    assert (warning_message in stderr) is warning_expected
+    assert "error shown" in stderr
+
+
+def test_importing_cli_preserves_host_loguru_sink() -> None:
+    """导入 CLI 模块不重建宿主应用已配置的 loguru sink。"""
+    messages: list[str] = []
+    handler_id = logger.add(messages.append, level="DEBUG", format="{message}")
+    try:
+        importlib.reload(cli)
+        logger.debug("host sink remains")
+    finally:
+        logger.remove(handler_id)
+
+    assert "host sink remains\n" in messages

docvortex-0.4.4/tests/test_public_export_api.py

@@ -0,0 +1,71 @@
+"""验证跨库素材导出接口的字节所有权及字面量边界。"""
+
+from __future__ import annotations
+
+import base64
+from typing import get_type_hints
+
+import pytest
+
+from docvortex.assets import AssetStore
+from docvortex.export import materialize_middle, validate_materialized_assets
+from docvortex.public_api import PUBLIC_API
+from docvortex.schema import MiddleJson
+
+
+def test_public_export_preserves_payloads_geometry_and_code() -> None:
+    """直接图与表内图外置后字节不变，代码中的同名字面量不被当作素材。"""
+    image = b"\xff\xd8\xffexample\xff\xd9"
+    uri = "data:image/jpeg;base64," + base64.b64encode(image).decode()
+    markup = f'<img src="{uri}" width="10">'
+    middle = MiddleJson.from_dict(
+        {
+            "schema": "docvortex.middle",
+            "schema_version": "2.0",
+            "is_full_document": False,
+            "metadata": {"file_suffix": "pdf", "producer": {"name": "test", "version": "1"}},
+            "extensions": {
+                "docvortex_layout": {
+                    "version": 1,
+                    "pages": [{"page_idx": 4, "width_pt": 400, "height_pt": 600, "image_rotations": {"2": 270}}],
+                }
+            },
+            "pages": [
+                {
+                    "page_idx": 4,
+                    "blocks": [
+                        {
+                            "type": "table",
+                            "index": 2,
+                            "bbox": [0.1, 0.1, 0.4, 0.5],
+                            "content": [{"type": "table_body", "index": 2, "content": markup, "image_base64": uri}],
+                        },
+                        {
+                            "type": "code",
+                            "sub_type": "code",
+                            "guess_lang": "html",
+                            "index": 3,
+                            "bbox": [0.1, 0.6, 0.9, 0.8],
+                            "content": [{"type": "code_body", "index": 3, "content": markup}],
+                        },
+                    ],
+                }
+            ],
+        }
+    )
+    before = middle.to_json()
+    exported, assets = materialize_middle(middle)
+    validate_materialized_assets(exported, assets)
+    assert set(assets) == {"images/page_4_table_body_2.jpg", "images/page_4_table_body_2_1.jpg"}
+    assert all(payload == image for payload in assets.values())
+    assert exported.extensions == middle.extensions
+    assert exported.pages[0].blocks[1].content[0].content == markup
+    assert middle.to_json() == before
+    repeated, copied_assets = materialize_middle(exported, assets)
+    assert repeated == exported and dict(copied_assets) == dict(assets)
+    assert copied_assets is not assets
+    with pytest.raises(ValueError, match="Missing materialized asset"):
+        validate_materialized_assets(exported, AssetStore())
+    assert set(PUBLIC_API["docvortex.export"]) == {"materialize_middle", "validate_materialized_assets"}
+    assert get_type_hints(materialize_middle)["return"] == tuple[MiddleJson, AssetStore]
+    assert get_type_hints(validate_materialized_assets)["return"] is type(None)