Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

refactor(read): limit file output to image reads

myhloli72c322f220a9
diff --git a/docs/next/cli/mineru-read.md b/docs/next/cli/mineru-read.md
index 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.md
index 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) 和现行规范为准;文中的历史模块路径不保证仍存在。
状态: Accepted
diff --git a/docs/next/decisions/0015-cli-output-json-composition.md b/docs/next/decisions/0015-cli-output-json-composition.md
index 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.md
index 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.py
index 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 None
if 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"] = None
payload["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.text
diff --git a/mineru/utils/translations.py b/mineru/utils/translations.py
index 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.py
index 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_mod
assert "('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.output
diff --git a/tests/unittest/test_cli_read_output_contract.py b/tests/unittest/test_cli_read_output_contract.py
new file mode 100644
index 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())