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(read): limit file output to image reads
myhloli72c322f220a9
diff --git a/docs/next/cli/mineru-read.md b/docs/next/cli/mineru-read.mdindex fb089efb..7677efde 100644--- a/docs/next/cli/mineru-read.md+++ b/docs/next/cli/mineru-read.md@@ -72,7 +72,7 @@ mineru read doc:ab12cd3/tier:flash/page:all| `--limit` | int | `30000` | 文本输出软字符上限 || `--after` | locator | 不传 | 使用返回的内容游标续读;要求 Markdown 文档定位或页选择,且 context=0 || `--context` | int | `0` | 按 locator 周围扩展上下文 |-| `--output`, `-o` | path | 不传 | 将返回内容或 image asset 写入本地路径;image 只支持 `.png`、`.jpg`、`.jpeg`、`.webp` |+| `--output`, `-o` | path | 不传 | 仅将 image asset 写入本地路径;Markdown 仅接受 `-` 表示 stdout;image 只支持 `.png`、`.jpg`、`.jpeg`、`.webp` || `--no-marker` | bool | false | 关闭 continuation marker |语义区分:@@ -103,7 +103,7 @@ Markdown 继续优先输出 table、chart 和 formula 的结构化内容。需![Table block]()```-非空 locator 表示该 block 当前可通过 `mineru read <locator> --format image` 读取;空 locator 表示没有可用图片。`--output` 只写 Markdown 文件,保留这些虚拟引用,不创建 `images/` 目录。+非空 locator 表示该 block 当前可通过 `mineru read <locator> --format image` 读取;空 locator 表示没有可用图片。Markdown 阅读仅返回 stdout/JSON;保存当前片段请使用重定向或 SDK,不支持 `--output PATH`。返回的文本保留这些虚拟引用。### `--context`@@ -153,7 +153,7 @@ image 输出路径必须带上述后缀。无后缀、其它后缀以及 `--outp`--json` 时,CLI 输出 `DocContentResponse`。-同时指定 `--output`(且不为 `-`)时,CLI 仍输出 `DocContentResponse`,但内容写入文件:`content` 字段为 `null`,并额外增加 `output` 字段(`{"status": "written", "path": "..."}`)指向已写入的文件;`--format image` 时写入的是 server 返回的 asset。+仅 `--format image --output PATH --json` 会保存 server 返回的 asset,并返回 `content=null` 和额外的 `output` 字段(`{"status": "written", "path": "..."}`)。Markdown 携带实际输出路径时,在读取服务或创建目录之前返回 `invalid_request`(`param=output`);`--output -` 与省略此参数等价。locator-first 读取时:@@ -205,3 +205,9 @@ locator-first 读取时:2. 需要继续阅读时,切换到 `mineru read <locator>`。`parse` 适合“把文件纳入 MinerU 并读默认内容”。`read` 适合“基于已有定位继续读指定位置或导出 page/block 图像”。++## 10. 阅读与保存++`read` 返回受字符预算约束的阅读片段。保存当前片段可使用 `mineru read <locator> --no-marker > part.md`,或通过 SDK 保存返回文本。这里不会自动续读、追加或拼接。++需要导出已解析的完整指定页范围时使用 `mineru parse <path> --pages <range> -o result.md`;该入口复用缓存并执行完整内容导出,不受阅读字符预算限制。图片读取与图片路径输出继续保留。diff --git a/docs/next/decisions/0014-mineru-read-command.md b/docs/next/decisions/0014-mineru-read-command.mdindex 57c4775c..9caa389d 100644--- a/docs/next/decisions/0014-mineru-read-command.md+++ b/docs/next/decisions/0014-mineru-read-command.md@@ -1,5 +1,7 @@# ADR-0014: MinerU Read Command+> 2026-11-13 更新:Markdown 的 `read --output PATH` 已移除,文本保存由 stdout 重定向或 SDK 完成;`--output -` 和图片输出保留。`parse -o` 继续完整导出指定范围。以下文本落盘描述仅保留为历史决策,现行行为见 [read 规范](../cli/mineru-read.md)。+> 历史决策记录:保留当时的背景、状态和设计。当前接口与实现归属以 [开发入口](../README.md) 和现行规范为准;文中的历史模块路径不保证仍存在。状态: Accepteddiff --git a/docs/next/decisions/0015-cli-output-json-composition.md b/docs/next/decisions/0015-cli-output-json-composition.mdindex fd0a02d0..caab5ae0 100644--- a/docs/next/decisions/0015-cli-output-json-composition.md+++ b/docs/next/decisions/0015-cli-output-json-composition.md@@ -1,5 +1,7 @@# ADR-0015: CLI Output 与 JSON 组合语义+> 2026-11-13 更新:Markdown 的 `read --output PATH` 已移除,文本保存由 stdout 重定向或 SDK 完成;`--output -` 和图片输出保留。`parse -o` 继续完整导出指定范围。以下文本落盘描述仅保留为历史决策,现行行为见 [read 规范](../cli/mineru-read.md)。+> 历史决策记录:保留当时的背景、状态和设计。当前接口与实现归属以 [开发入口](../README.md) 和现行规范为准;文中的历史模块路径不保证仍存在。状态: Accepted,已实现diff --git a/docs/next/decisions/0027-doclib-visual-block-locators.md b/docs/next/decisions/0027-doclib-visual-block-locators.mdindex b7877280..4471312d 100644--- a/docs/next/decisions/0027-doclib-visual-block-locators.md+++ b/docs/next/decisions/0027-doclib-visual-block-locators.md@@ -1,5 +1,7 @@# ADR-0027: Doclib 视觉 Block Locator 图片引用+> 2026-11-13 更新:Markdown 的 `read --output PATH` 已移除,文本保存由 stdout 重定向或 SDK 完成;`--output -` 和图片输出保留。`parse -o` 继续完整导出指定范围。以下文本落盘描述仅保留为历史决策,现行行为见 [read 规范](../cli/mineru-read.md)。+> 历史决策记录:保留当时的背景、状态和设计。当前接口与实现归属以 [开发入口](../README.md) 和现行规范为准;文中的历史模块路径不保证仍存在。状态: Accepted,已实现diff --git a/mineru/cli/commands/read.py b/mineru/cli/commands/read.pyindex a59c2d26..1983fe98 100644--- a/mineru/cli/commands/read.py+++ b/mineru/cli/commands/read.py@@ -32,7 +32,9 @@ def read_cmd(context: int = typer.Option(0, "--context", help=t("Read N pages/blocks before and after the locator")),limit: int = typer.Option(30000, "--limit", help=t("Soft character limit for printed content")),format: Literal["markdown", "image"] = typer.Option("markdown", "-f", "--format", help=t("Output format: markdown, image")),- output: str = typer.Option(None, "-o", "--output", help=t("Output path; creates parent directories")),+ output: str = typer.Option(+ None, "-o", "--output", help=t("Image output path; creates parent directories; Markdown only accepts '-'")+ ),no_marker: bool = typer.Option(False, "--no-marker", help=t("Omit continuation marker from output")),json_mode: bool = typer.Option(False, "--json", help=t("JSON output")),) -> None:@@ -65,6 +67,7 @@ def _read(after: str | None = None,) -> DocContentResponse | dict[str, object] | CliResult[ReadTextOutput] | CliResult[None]:"""调用内容服务;只有显式续读时才传入 after,保持普通调用参数兼容。"""+ _validate_read_output(format, output)image_format = _image_format_for_output(format=format, output=output) if format == "image" else "jpeg"client = DoclibClient(timeout=60)if format == "image":@@ -96,15 +99,14 @@ def _prepare_read_output(output: str | None,no_marker: bool,) -> DocContentResponse | dict[str, object] | CliResult[ReadTextOutput] | CliResult[None]:- output_path = _ensure_output_parent(output)+ """只将图片素材写入路径;文本保持渐进阅读和原有 JSON 响应。"""+ _validate_read_output(content.format, output)+ output_path = _ensure_output_parent(output) if content.format == "image" else Noneif json_mode and output_path and output_path != "-":payload: dict[str, object] = content.model_dump(mode="json")- if content.format == "image":- if content.asset is None:- raise MineruError("asset_not_available", t("No image asset returned."), "format")- shutil.copyfile(content.asset.path, output_path)- else:- Path(output_path).write_text(content.content, encoding="utf-8")+ if content.asset is None:+ raise MineruError("asset_not_available", t("No image asset returned."), "format")+ shutil.copyfile(content.asset.path, output_path)payload["content"] = Nonepayload["output"] = _output_info(output_path)return payload@@ -121,10 +123,6 @@ def _prepare_read_output(return cli_ok(ReadTextOutput(t("Written to {path}", path=output_path)), render=_render_read_text)return cli_ok(ReadTextOutput(asset_path), render=_render_read_text)- if output_path and output_path != "-":- Path(output_path).write_text(content.content, encoding="utf-8")- return cli_ok(ReadTextOutput(t("Written to {path}", path=output_path)), render=_render_read_text)-if not content.content and content.content_ranges:message = t("No renderable content in requested pages.")if content.next_request and not no_marker:@@ -141,6 +139,16 @@ def _prepare_read_output(return cli_ok(ReadTextOutput(content.content), render=_render_read_text)+def _validate_read_output(format: str, output: str | None) -> None:+ """在连接服务或创建目录前拒绝文本落盘,保留 stdout 的显式等价写法。"""+ if format == "markdown" and output not in {None, "-"}:+ raise MineruError(+ "invalid_request",+ t("Markdown read does not write files. Use stdout redirection or the SDK to save text."),+ "output",+ )++def _render_read_text(data: ReadTextOutput) -> str:return data.textdiff --git a/mineru/utils/translations.py b/mineru/utils/translations.pyindex cd3dcd66..de776b87 100644--- a/mineru/utils/translations.py+++ b/mineru/utils/translations.py@@ -80,6 +80,12 @@ ZH_MESSAGES: dict[str, str] = {),"Read N pages/blocks before and after the locator": "在定位符前后各读取 N 页/块","Output format: markdown, image": "输出格式: markdown、image",+ "Image output path; creates parent directories; Markdown only accepts '-'": (+ "图片输出路径;自动创建父目录;Markdown 仅接受 '-'"+ ),+ "Markdown read does not write files. Use stdout redirection or the SDK to save text.": (+ "Markdown 阅读不写入文件。请使用 stdout 重定向或 SDK 保存文本。"+ ),"Omit continuation marker from output": "输出中省略续读标记","No image asset returned.": "未返回图片素材。","Image output requires a file path ending with .png, .jpg, .jpeg, or .webp; stdout is not supported.": (diff --git a/tests/unittest/test_cli_next_command_design.py b/tests/unittest/test_cli_next_command_design.pyindex 294df9af..4ff869ab 100644--- a/tests/unittest/test_cli_next_command_design.py+++ b/tests/unittest/test_cli_next_command_design.py@@ -2553,32 +2553,39 @@ def test_read_text_locator_reports_parse_not_required(monkeypatch: Any, json_modassert "('parse_not_required'" not in result.output-def test_read_json_output_writes_markdown_file_and_returns_output_object(monkeypatch: Any, tmp_path: Path) -> None:[email protected]("json_mode", [False, True])[email protected]("existing", [False, True])+def test_read_rejects_markdown_file_before_client_or_filesystem_changes(+ monkeypatch: Any, tmp_path: Path, json_mode: bool, existing: bool+) -> None:+ """文本落盘请求在构造客户端之前失败,已有文件和不存在的父目录均不受影响。"""output = tmp_path / "nested" / "read.md"+ if existing:+ output.parent.mkdir()+ output.write_text("keep", encoding="utf-8")class _Client:def __init__(self, *, timeout: int) -> None:- assert timeout == 60-- def read_content(self, locator: str, **kwargs: Any) -> DocContentResponse:- return DocContentResponse(- sha256="a" * 64,- short_id="ab12cd3",- tier="basic",- format="markdown",- content="hello",- request_scope=ContentRequestScope(locator=locator, context=0, limit=30000),- )+ """非法文本落盘请求不得连接或启动 Doclib。"""+ pytest.fail("Doclib client must not be constructed")monkeypatch.setattr(read, "DoclibClient", _Client)+ args = ["read", "doc:ab12cd3/tier:basic/page:4", "--output", str(output)]+ if json_mode:+ args.append("--json")+ result = runner.invoke(app, args)- result = runner.invoke(app, ["read", "doc:ab12cd3/tier:basic/page:4", "--output", str(output), "--json"])-- assert result.exit_code == 0- payload = json.loads(result.output)- assert payload["content"] is None- assert payload["output"] == {"status": "written", "path": str(output.resolve())}- assert output.read_text(encoding="utf-8") == "hello"+ assert result.exit_code == 1+ if json_mode:+ payload = json.loads(result.output)+ assert payload["error"]["code"] == "invalid_request"+ assert payload["error"]["param"] == "output"+ else:+ assert "stdout redirection or the SDK" in result.output+ if existing:+ assert output.read_text(encoding="utf-8") == "keep"+ else:+ assert not output.parent.exists()assert "Written to" not in result.outputdiff --git a/tests/unittest/test_cli_read_output_contract.py b/tests/unittest/test_cli_read_output_contract.pynew file mode 100644index 00000000..6dc3a4d7--- /dev/null+++ b/tests/unittest/test_cli_read_output_contract.py@@ -0,0 +1,96 @@+"""阅读只返回片段,完整文本导出与图片保存保持各自的输出契约。"""++from __future__ import annotations++import asyncio+import json+from pathlib import Path+from typing import Any++import pytest+from test_doclib_page_selection import _DOC_REF, _SHA256, _cached_library, _page+from typer.testing import CliRunner++from mineru.cli.commands import parse, read+from mineru.cli.main import app+from mineru.doclib.types import (+ ContentNextRequest,+ ContentRequestScope,+ DocContentExportRequest,+ DocContentExportResponse,+ DocContentResponse,+ ParseResponse,+)++[email protected]("json_mode", [False, True])+def test_read_stdout_alias_preserves_content_and_continuation(+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, json_mode: bool+) -> None:+ """显式 stdout 与省略 output 完全等价,不出现落盘字段或名为减号的文件。"""+ monkeypatch.chdir(tmp_path)++ class Client:+ def __init__(self, *, timeout: int) -> None:+ """模拟仅用于读取的客户端。"""++ def read_content(self, locator: str, **kwargs: Any) -> DocContentResponse:+ """返回带续读位置的文本片段。"""+ return DocContentResponse(+ sha256=_SHA256,+ short_id="aaaaaaa",+ tier="flash",+ content="正文",+ request_scope=ContentRequestScope(locator=locator),+ next_request=ContentNextRequest(locator=f"{_DOC_REF}/page:2"),+ )++ monkeypatch.setattr(read, "DoclibClient", Client)+ args = ["read", _DOC_REF, *(["--json"] if json_mode else [])]+ runner = CliRunner()+ normal = runner.invoke(app, args)+ alias = runner.invoke(app, [*args, "-o", "-"])+ assert normal.exit_code == alias.exit_code == 0+ assert normal.stdout == alias.stdout+ if json_mode:+ payload = json.loads(alias.stdout)+ assert payload["content"] == "正文"+ assert payload["next_request"]["locator"].endswith("page:2")+ assert "output" not in payload+ else:+ assert "<!-- Next: mineru read" in alias.stdout+ assert not (tmp_path / "-").exists()+++def test_parse_output_exports_real_cache_beyond_read_budget(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:+ """真实缓存中的长文本完整导出;CLI 的 limit 不影响指定范围的产物。"""+ cache = tmp_path / "cache"+ cache.mkdir()+ body = "A" * 16000 + "B" * 16000 + "C" * 16000+ db, server = asyncio.run(_cached_library(cache, page_count=1, pages=[_page(0, body)]))+ output = tmp_path / "out" / "complete.md"++ class Client:+ def __init__(self, *, timeout: int) -> None:+ """仅替换传输,导出仍执行真实 Doclib 服务。"""++ def ensure_parse(self, request: Any) -> ParseResponse:+ """复用已经准备好的解析缓存。"""+ return ParseResponse(sha256=_SHA256, tier="flash", page_range="1", status="done", cache_hit=True)++ def export_doc_content(self, doc_ref: str, request: DocContentExportRequest) -> DocContentExportResponse:+ """将 CLI 导出请求转给真实服务。"""+ return asyncio.run(server.export_doc_content(doc_ref, request))++ monkeypatch.setattr(parse, "DoclibClient", Client)+ source = tmp_path / "source.pdf"+ source.write_bytes(b"%PDF-1.7\n")+ try:+ result = CliRunner().invoke(+ app, ["parse", str(source), "--tier", "flash", "--limit", "10", "-o", str(output), "--json"]+ )+ assert result.exit_code == 0, result.output+ assert body in output.read_text(encoding="utf-8")+ assert json.loads(result.stdout)["output"]["status"] == "written"+ finally:+ asyncio.run(db.close())