zero-agent-core-mineru 0.1.0__tar.gz

zero_agent_core_mineru-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+site/
+*.db
+*.sqlite
+*.sqlite3
+.venv/*

zero_agent_core_mineru-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Agent Core contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

zero_agent_core_mineru-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.5
+Name: zero-agent-core-mineru
+Version: 0.1.0
+Summary: Handwritten Agent Core 的 MinerU 文档解析扩展
+Project-URL: Homepage, https://github.com/qiuzixu/agent-core
+Project-URL: Repository, https://github.com/qiuzixu/agent-core
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.13
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: zero-agent-core<0.3,>=0.2.0
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.18; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
+Requires-Dist: pytest<10,>=9; extra == 'dev'
+Requires-Dist: ruff<1,>=0.14; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Handwritten Agent Core MinerU
+
+`zero-agent-core-mineru` 是 Agent Core 的可选文档解析扩展。它调用已经部署好的 MinerU
+自托管 `/file_parse` HTTP 服务，把 Markdown 或 `content_list` 转换成 Core `Document`。
+
+```bash
+pip install zero-agent-core-mineru
+```
+
+```python
+from agent_core_mineru import MinerUConfig, MinerUDocumentLoader
+
+loader = MinerUDocumentLoader(
+    "./manual.pdf",
+    config=MinerUConfig(endpoint="http://127.0.0.1:8000/file_parse"),
+)
+documents = await loader.load()
+```
+
+本包不安装 MinerU、OCR 模型或 GPU 运行时。MinerU 云端异步批处理 API 使用不同协议，可以实现
+`MinerUTransport` 后注入。

zero_agent_core_mineru-0.1.0/README.md

@@ -0,0 +1,21 @@
+# Handwritten Agent Core MinerU
+
+`zero-agent-core-mineru` 是 Agent Core 的可选文档解析扩展。它调用已经部署好的 MinerU
+自托管 `/file_parse` HTTP 服务，把 Markdown 或 `content_list` 转换成 Core `Document`。
+
+```bash
+pip install zero-agent-core-mineru
+```
+
+```python
+from agent_core_mineru import MinerUConfig, MinerUDocumentLoader
+
+loader = MinerUDocumentLoader(
+    "./manual.pdf",
+    config=MinerUConfig(endpoint="http://127.0.0.1:8000/file_parse"),
+)
+documents = await loader.load()
+```
+
+本包不安装 MinerU、OCR 模型或 GPU 运行时。MinerU 云端异步批处理 API 使用不同协议，可以实现
+`MinerUTransport` 后注入。

zero_agent_core_mineru-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zero-agent-core-mineru"
+version = "0.1.0"
+description = "Handwritten Agent Core 的 MinerU 文档解析扩展"
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+license = "Apache-2.0"
+dependencies = [
+  "zero-agent-core>=0.2.0,<0.3",
+  "httpx>=0.28,<1",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/qiuzixu/agent-core"
+Repository = "https://github.com/qiuzixu/agent-core"
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.18,<2",
+  "pytest>=9,<10",
+  "pytest-asyncio>=1.3,<2",
+  "ruff>=0.14,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_core_mineru"]
+
+[tool.uv.sources]
+zero-agent-core = { path = "../..", editable = true }
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF"]
+ignore = ["RUF001", "RUF002", "RUF003"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+files = ["src"]
+
+[[tool.mypy.overrides]]
+module = ["httpx"]
+ignore_missing_imports = true

zero_agent_core_mineru-0.1.0/src/agent_core_mineru/__init__.py

@@ -0,0 +1,14 @@
+"""Agent Core 的 MinerU 文档解析扩展。"""
+
+from agent_core_mineru.config import MinerUConfig, MinerUOutputMode
+from agent_core_mineru.parser import MinerUBlobParser, MinerUDocumentLoader
+from agent_core_mineru.transport import HttpxMinerUTransport, MinerUTransport
+
+__all__ = [
+    "HttpxMinerUTransport",
+    "MinerUBlobParser",
+    "MinerUConfig",
+    "MinerUDocumentLoader",
+    "MinerUOutputMode",
+    "MinerUTransport",
+]

zero_agent_core_mineru-0.1.0/src/agent_core_mineru/config.py

@@ -0,0 +1,50 @@
+"""MinerU 扩展配置。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Literal
+from urllib.parse import urlparse
+
+MinerUOutputMode = Literal["blocks", "markdown"]
+
+
+@dataclass(frozen=True)
+class MinerUConfig:
+    """MinerU ``/file_parse`` 请求配置。
+
+    扩展包只调用已经部署好的 MinerU HTTP 服务，不负责下载模型或启动 OCR 运行时。
+    ``endpoint`` 应指向 MinerU 自托管服务的 ``/file_parse`` 路由。
+    """
+
+    endpoint: str = "http://127.0.0.1:8000/file_parse"
+    api_key: str | None = None
+    timeout_seconds: float = 300.0
+    backend: str = "pipeline"
+    parse_method: str = "auto"
+    language: str = "ch"
+    formula_enabled: bool = True
+    table_enabled: bool = True
+    start_page_id: int = 0
+    end_page_id: int = 99999
+    output_mode: MinerUOutputMode = "blocks"
+    parser_version: str = "mineru-http-v1"
+    max_file_bytes: int = 100 * 1024 * 1024
+    headers: Mapping[str, str] = field(default_factory=dict)
+    extra_form_fields: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        parsed = urlparse(self.endpoint)
+        if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+            raise ValueError("MinerU endpoint 必须是有效的 http 或 https URL")
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds 必须大于 0")
+        if self.start_page_id < 0:
+            raise ValueError("start_page_id 不能小于 0")
+        if self.end_page_id < self.start_page_id:
+            raise ValueError("end_page_id 不能小于 start_page_id")
+        if self.max_file_bytes <= 0:
+            raise ValueError("max_file_bytes 必须大于 0")
+        if not self.parser_version.strip():
+            raise ValueError("parser_version 不能为空")

zero_agent_core_mineru-0.1.0/src/agent_core_mineru/parser.py

@@ -0,0 +1,262 @@
+"""MinerU 响应到 Agent Core Document 的转换。"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import mimetypes
+import uuid
+from collections.abc import AsyncIterator, Mapping
+from pathlib import Path
+from typing import Any
+
+from agent_core import Blob, Document, DocumentLocator, DocumentParsingError, DocumentServiceError
+
+from agent_core_mineru.config import MinerUConfig
+from agent_core_mineru.transport import HttpxMinerUTransport, MinerUTransport, source_filename
+
+
+class MinerUBlobParser:
+    """把 MinerU Markdown 或 content list 响应转换成 Core Document。"""
+
+    def __init__(
+        self,
+        config: MinerUConfig | None = None,
+        *,
+        transport: MinerUTransport | None = None,
+    ) -> None:
+        self._config = config or MinerUConfig()
+        self._transport = transport or HttpxMinerUTransport()
+
+    async def parse(self, blob: Blob) -> list[Document]:
+        if not blob.data:
+            raise DocumentParsingError("不能解析空文件")
+        if len(blob.data) > self._config.max_file_bytes:
+            raise DocumentParsingError(
+                f"文件大小 {len(blob.data)} 字节超过限制 {self._config.max_file_bytes} 字节"
+            )
+
+        payload = await self._transport.parse(blob, config=self._config)
+        result = _resolve_result(payload, source_filename(blob.source))
+        _raise_for_service_error(payload, result)
+
+        blocks = _read_blocks(result)
+        block_documents = self._build_block_documents(blob, blocks, result)
+        markdown = _read_text(result, ("md_content", "markdown", "content", "text"))
+
+        if self._config.output_mode == "blocks" and block_documents:
+            return block_documents
+        if markdown:
+            return [self._build_markdown_document(blob, markdown, result, len(blocks))]
+        if block_documents:
+            merged = "\n\n".join(document.content for document in block_documents)
+            return [self._build_markdown_document(blob, merged, result, len(blocks))]
+        raise DocumentParsingError("MinerU 响应中没有可用的 Markdown 或文本区块")
+
+    def _build_block_documents(
+        self,
+        blob: Blob,
+        blocks: list[Mapping[str, Any]],
+        result: Mapping[str, Any],
+    ) -> list[Document]:
+        documents: list[Document] = []
+        source_key = blob.source or f"blob:{blob.checksum}"
+        mineru_version = _read_scalar_text(result, ("version", "mineru_version"))
+        for index, block in enumerate(blocks):
+            content = _block_content(block)
+            if not content:
+                continue
+            page = _block_page(block)
+            block_id = _read_scalar_text(block, ("block_id", "id")) or str(index)
+            block_type = _read_scalar_text(block, ("type", "block_type")) or "text"
+            identity = (
+                f"{source_key}:{blob.checksum}:{self._config.parser_version}:"
+                f"{page}:{block_id}:{content}"
+            )
+            metadata: dict[str, Any] = {
+                **blob.metadata,
+                "source_checksum": blob.checksum,
+                "parser": "mineru",
+                "parser_version": self._config.parser_version,
+                "mineru_block_index": index,
+                "mineru_block_type": block_type,
+            }
+            if mineru_version:
+                metadata["mineru_version"] = mineru_version
+            documents.append(
+                Document(
+                    document_id=str(uuid.uuid5(uuid.NAMESPACE_URL, identity)),
+                    content=content,
+                    source=blob.source,
+                    mime_type="text/markdown",
+                    metadata=metadata,
+                    locator=DocumentLocator(uri=blob.source, page=page, block_id=block_id),
+                )
+            )
+        return documents
+
+    def _build_markdown_document(
+        self,
+        blob: Blob,
+        markdown: str,
+        result: Mapping[str, Any],
+        block_count: int,
+    ) -> Document:
+        source_key = blob.source or f"blob:{blob.checksum}"
+        identity = f"{source_key}:{blob.checksum}:{self._config.parser_version}:markdown"
+        metadata: dict[str, Any] = {
+            **blob.metadata,
+            "source_checksum": blob.checksum,
+            "parser": "mineru",
+            "parser_version": self._config.parser_version,
+            "mineru_block_count": block_count,
+        }
+        mineru_version = _read_scalar_text(result, ("version", "mineru_version"))
+        if mineru_version:
+            metadata["mineru_version"] = mineru_version
+        return Document(
+            document_id=str(uuid.uuid5(uuid.NAMESPACE_URL, identity)),
+            content=markdown,
+            source=blob.source,
+            mime_type="text/markdown",
+            metadata=metadata,
+            locator=DocumentLocator(uri=blob.source),
+        )
+
+
+class MinerUDocumentLoader:
+    """读取本地文件并通过 MinerU HTTP 服务解析。"""
+
+    def __init__(
+        self,
+        path: str | Path,
+        *,
+        config: MinerUConfig | None = None,
+        transport: MinerUTransport | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._path = Path(path)
+        self._parser = MinerUBlobParser(config, transport=transport)
+        self._metadata = dict(metadata or {})
+
+    async def load(self) -> list[Document]:
+        try:
+            data = await asyncio.to_thread(self._path.read_bytes)
+        except OSError as exc:
+            raise DocumentParsingError(f"读取文档失败：{self._path}") from exc
+        mime_type, _ = mimetypes.guess_type(self._path.name)
+        blob = Blob(
+            data=data,
+            source=str(self._path.resolve()),
+            mime_type=mime_type or "application/octet-stream",
+            metadata=self._metadata,
+        )
+        return await self._parser.parse(blob)
+
+    async def lazy_load(self) -> AsyncIterator[Document]:
+        for document in await self.load():
+            yield document
+
+
+def _has_output_fields(value: Mapping[str, Any]) -> bool:
+    return any(key in value for key in ("md_content", "markdown", "content_list", "blocks"))
+
+
+def _resolve_result(payload: Mapping[str, Any], filename: str) -> Mapping[str, Any]:
+    current = payload
+    for _ in range(4):
+        if _has_output_fields(current):
+            return current
+        data = current.get("data")
+        if isinstance(data, Mapping):
+            current = data
+            continue
+        results = current.get("results")
+        if isinstance(results, Mapping):
+            current = _select_file_result(results, filename)
+            continue
+        break
+    return current
+
+
+def _select_file_result(results: Mapping[str, Any], filename: str) -> Mapping[str, Any]:
+    if _has_output_fields(results):
+        return results
+    stem = Path(filename).stem
+    for key in (filename, stem):
+        value = results.get(key)
+        if isinstance(value, Mapping):
+            return value
+    mappings = [value for value in results.values() if isinstance(value, Mapping)]
+    if len(mappings) == 1:
+        return mappings[0]
+    raise DocumentParsingError("MinerU 响应包含多个文件，但无法匹配当前文件名")
+
+
+def _raise_for_service_error(
+    payload: Mapping[str, Any],
+    result: Mapping[str, Any],
+) -> None:
+    code = payload.get("code")
+    if isinstance(code, int) and code != 0:
+        message = _read_scalar_text(payload, ("msg", "message", "error")) or str(code)
+        raise DocumentServiceError(f"MinerU 解析失败：{message}")
+    error = _read_scalar_text(result, ("error", "err_msg"))
+    if error:
+        raise DocumentServiceError(f"MinerU 解析失败：{error}")
+
+
+def _read_blocks(result: Mapping[str, Any]) -> list[Mapping[str, Any]]:
+    value = result.get("content_list", result.get("blocks"))
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise DocumentParsingError("MinerU content_list 不是有效 JSON") from exc
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise DocumentParsingError("MinerU content_list 必须是数组")
+    return [item for item in value if isinstance(item, Mapping)]
+
+
+def _block_content(block: Mapping[str, Any]) -> str:
+    direct = _read_text(block, ("text", "content", "md_content", "table_body", "latex"))
+    if direct:
+        return direct
+    for key in ("image_caption", "image_footnote", "table_caption", "table_footnote"):
+        value = block.get(key)
+        if isinstance(value, list):
+            parts = [str(item).strip() for item in value if str(item).strip()]
+            if parts:
+                return "\n".join(parts)
+    return ""
+
+
+def _block_page(block: Mapping[str, Any]) -> int | None:
+    page_index = block.get("page_idx")
+    if isinstance(page_index, int) and page_index >= 0:
+        return page_index + 1
+    for key in ("page_no", "page"):
+        value = block.get(key)
+        if isinstance(value, int) and value >= 0:
+            return value
+    return None
+
+
+def _read_text(value: Mapping[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        item = value.get(key)
+        if isinstance(item, str) and item.strip():
+            return item.strip()
+    return ""
+
+
+def _read_scalar_text(value: Mapping[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        item = value.get(key)
+        if isinstance(item, (str, int, float)) and not isinstance(item, bool):
+            text = str(item).strip()
+            if text:
+                return text
+    return ""

zero_agent_core_mineru-0.1.0/src/agent_core_mineru/py.typed

@@ -0,0 +1 @@
+

zero_agent_core_mineru-0.1.0/src/agent_core_mineru/transport.py

@@ -0,0 +1,123 @@
+"""MinerU HTTP 传输实现。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import unquote, urlparse
+
+from agent_core import Blob, DocumentParsingError, DocumentServiceError
+
+from agent_core_mineru.config import MinerUConfig
+
+
+@runtime_checkable
+class MinerUTransport(Protocol):
+    """MinerU 请求传输端口，便于替换认证、网关或测试实现。"""
+
+    async def parse(self, blob: Blob, *, config: MinerUConfig) -> Mapping[str, Any]: ...
+
+
+class HttpxMinerUTransport:
+    """使用 httpx 调用 MinerU ``/file_parse`` 接口。"""
+
+    def __init__(self, client: Any | None = None) -> None:
+        self._client = client
+
+    async def parse(self, blob: Blob, *, config: MinerUConfig) -> Mapping[str, Any]:
+        filename = source_filename(blob.source)
+        headers = {"Accept": "application/json", **dict(config.headers)}
+        if config.api_key:
+            headers.setdefault("Authorization", f"Bearer {config.api_key}")
+        form = {
+            "backend": config.backend,
+            "parse_method": config.parse_method,
+            "lang_list": config.language,
+            "formula_enable": _form_bool(config.formula_enabled),
+            "table_enable": _form_bool(config.table_enabled),
+            "return_md": "true",
+            "return_content_list": "true",
+            "return_images": "false",
+            "start_page_id": str(config.start_page_id),
+            "end_page_id": str(config.end_page_id),
+            **dict(config.extra_form_fields),
+        }
+        files = {
+            "files": (
+                filename,
+                blob.data,
+                blob.mime_type or "application/octet-stream",
+            )
+        }
+
+        if self._client is not None:
+            return await self._post(
+                self._client,
+                config=config,
+                headers=headers,
+                form=form,
+                files=files,
+            )
+
+        import httpx
+
+        try:
+            async with httpx.AsyncClient() as client:
+                return await self._post(
+                    client,
+                    config=config,
+                    headers=headers,
+                    form=form,
+                    files=files,
+                )
+        except DocumentServiceError:
+            raise
+        except Exception as exc:
+            raise DocumentServiceError(f"MinerU 服务调用失败：{exc}") from exc
+
+    @staticmethod
+    async def _post(
+        client: Any,
+        *,
+        config: MinerUConfig,
+        headers: Mapping[str, str],
+        form: Mapping[str, str],
+        files: Mapping[str, tuple[str, bytes, str]],
+    ) -> Mapping[str, Any]:
+        try:
+            response = await client.post(
+                config.endpoint,
+                headers=dict(headers),
+                data=dict(form),
+                files=dict(files),
+                timeout=config.timeout_seconds,
+            )
+        except Exception as exc:
+            raise DocumentServiceError(f"MinerU 服务调用失败：{exc}") from exc
+
+        status_code = int(getattr(response, "status_code", 0))
+        if status_code < 200 or status_code >= 300:
+            response_text = str(getattr(response, "text", ""))[:500]
+            raise DocumentServiceError(f"MinerU 服务返回 HTTP {status_code}：{response_text}")
+        try:
+            payload = response.json()
+        except Exception as exc:
+            raise DocumentParsingError("MinerU 服务返回了无效 JSON") from exc
+        if not isinstance(payload, Mapping):
+            raise DocumentParsingError("MinerU 响应根节点必须是对象")
+        return payload
+
+
+def source_filename(source: str | None) -> str:
+    """从本地路径或 URL 提取上传文件名。"""
+    if not source:
+        return "document.bin"
+    parsed = urlparse(source)
+    path = unquote(parsed.path) if parsed.scheme else source
+    filename = Path(path).name
+    return filename or "document.bin"
+
+
+def _form_bool(value: bool) -> str:
+    return "true" if value else "false"

zero_agent_core_mineru-0.1.0/tests/test_adapter.py

@@ -0,0 +1,187 @@
+"""MinerU 文档适配器测试。"""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from agent_core import (
+    Blob,
+    DocumentParsingError,
+    DocumentServiceError,
+)
+
+from agent_core_mineru import (
+    HttpxMinerUTransport,
+    MinerUBlobParser,
+    MinerUConfig,
+    MinerUDocumentLoader,
+)
+
+
+class _FakeTransport:
+    def __init__(self, response: Mapping[str, Any]) -> None:
+        self.response = response
+        self.blobs: list[Blob] = []
+        self.configs: list[MinerUConfig] = []
+
+    async def parse(self, blob: Blob, *, config: MinerUConfig) -> Mapping[str, Any]:
+        self.blobs.append(blob)
+        self.configs.append(config)
+        return self.response
+
+
+class _FakeResponse:
+    def __init__(self, payload: object, *, status_code: int = 200, text: str = "") -> None:
+        self._payload = payload
+        self.status_code = status_code
+        self.text = text
+
+    def json(self) -> object:
+        return self._payload
+
+
+class _FakeHttpClient:
+    def __init__(self, response: _FakeResponse) -> None:
+        self.response = response
+        self.requests: list[dict[str, Any]] = []
+
+    async def post(self, url: str, **kwargs: Any) -> _FakeResponse:
+        self.requests.append({"url": url, **kwargs})
+        return self.response
+
+
+class MinerUParserTests(unittest.IsolatedAsyncioTestCase):
+    async def test_blocks_preserve_page_lineage_and_stable_ids(self) -> None:
+        response = {
+            "results": {
+                "manual": {
+                    "version": "2.1.0",
+                    "md_content": "# 飞行手册\n\n起飞前检查。",
+                    "content_list": [
+                        {"type": "title", "text": "飞行手册", "page_idx": 0, "block_id": "b-1"},
+                        {"type": "text", "text": "起飞前检查。", "page_idx": 1},
+                    ],
+                }
+            }
+        }
+        transport = _FakeTransport(response)
+        parser = MinerUBlobParser(transport=transport)
+        blob = Blob(b"pdf", source="C:/docs/manual.pdf", mime_type="application/pdf")
+
+        first = await parser.parse(blob)
+        second = await parser.parse(blob)
+
+        self.assertEqual([document.content for document in first], ["飞行手册", "起飞前检查。"])
+        self.assertEqual(
+            [document.document_id for document in first],
+            [document.document_id for document in second],
+        )
+        assert first[0].locator is not None
+        assert first[1].locator is not None
+        self.assertEqual(first[0].locator.page, 1)
+        self.assertEqual(first[0].locator.block_id, "b-1")
+        self.assertEqual(first[1].locator.page, 2)
+        self.assertEqual(first[1].metadata["parser"], "mineru")
+        self.assertEqual(first[1].metadata["mineru_version"], "2.1.0")
+
+    async def test_markdown_mode_uses_full_markdown(self) -> None:
+        transport = _FakeTransport(
+            {
+                "data": {
+                    "results": {
+                        "document.pdf": {
+                            "md_content": "# 标题\n\n正文",
+                            "content_list": [{"type": "text", "text": "正文", "page_idx": 0}],
+                        }
+                    }
+                }
+            }
+        )
+        parser = MinerUBlobParser(
+            MinerUConfig(output_mode="markdown"),
+            transport=transport,
+        )
+
+        documents = await parser.parse(Blob(b"pdf", source="document.pdf"))
+
+        self.assertEqual(len(documents), 1)
+        self.assertEqual(documents[0].content, "# 标题\n\n正文")
+        self.assertEqual(documents[0].metadata["mineru_block_count"], 1)
+
+    async def test_loader_reads_local_file_and_propagates_metadata(self) -> None:
+        transport = _FakeTransport(
+            {"results": {"manual": {"md_content": "内容", "content_list": []}}}
+        )
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "manual.pdf"
+            path.write_bytes(b"pdf-data")
+            loader = MinerUDocumentLoader(
+                path,
+                transport=transport,
+                metadata={"namespace": "manual"},
+            )
+
+            documents = await loader.load()
+
+        self.assertEqual(transport.blobs[0].data, b"pdf-data")
+        self.assertEqual(transport.blobs[0].mime_type, "application/pdf")
+        self.assertEqual(documents[0].metadata["namespace"], "manual")
+
+    async def test_invalid_content_list_and_service_error_are_explicit(self) -> None:
+        malformed = MinerUBlobParser(
+            transport=_FakeTransport({"results": {"document": {"content_list": "{"}}})
+        )
+        failed = MinerUBlobParser(transport=_FakeTransport({"code": 500, "msg": "模型不可用"}))
+
+        with self.assertRaises(DocumentParsingError):
+            await malformed.parse(Blob(b"pdf", source="document.pdf"))
+        with self.assertRaises(DocumentServiceError):
+            await failed.parse(Blob(b"pdf", source="document.pdf"))
+
+    async def test_file_size_limit_is_checked_before_transport(self) -> None:
+        transport = _FakeTransport({})
+        parser = MinerUBlobParser(MinerUConfig(max_file_bytes=2), transport=transport)
+
+        with self.assertRaises(DocumentParsingError):
+            await parser.parse(Blob(b"pdf"))
+        self.assertEqual(transport.blobs, [])
+
+
+class MinerUTransportTests(unittest.IsolatedAsyncioTestCase):
+    async def test_http_transport_builds_multipart_request(self) -> None:
+        client = _FakeHttpClient(_FakeResponse({"results": {}}))
+        transport = HttpxMinerUTransport(client)
+        config = MinerUConfig(
+            endpoint="http://mineru.local/file_parse",
+            api_key="secret",
+            formula_enabled=False,
+            extra_form_fields={"return_middle_json": "false"},
+        )
+
+        payload = await transport.parse(
+            Blob(b"pdf", source="manual.pdf", mime_type="application/pdf"),
+            config=config,
+        )
+
+        self.assertEqual(payload, {"results": {}})
+        request = client.requests[0]
+        self.assertEqual(request["url"], config.endpoint)
+        self.assertEqual(request["headers"]["Authorization"], "Bearer secret")
+        self.assertEqual(request["data"]["formula_enable"], "false")
+        self.assertEqual(request["data"]["return_content_list"], "true")
+        self.assertEqual(request["files"]["files"][0], "manual.pdf")
+
+    async def test_http_error_is_wrapped(self) -> None:
+        client = _FakeHttpClient(_FakeResponse({}, status_code=503, text="unavailable"))
+        transport = HttpxMinerUTransport(client)
+
+        with self.assertRaises(DocumentServiceError):
+            await transport.parse(Blob(b"pdf"), config=MinerUConfig())
+
+
+if __name__ == "__main__":
+    unittest.main()