feat(pdf): refactor MinerU parsing to the official file_parse API

docs/en/guides/01-configuration.md

@@ -882,6 +882,36 @@ Use `github_domains`, `gitlab_domains`, or `azure_devops_domains` when the host
 needs those platform-specific URL semantics. Add other Git hosts to
 `code_hosting_domains`.
 
+### pdf
+
+PDF parsing configuration. Three strategies are supported: `local` (local pdfplumber), `mineru` (remote MinerU API), and `auto` (try local first, fall back to MinerU).
+
+```json
+{
+  "pdf": {
+    "strategy": "auto",
+    "mineru_endpoint": "http://127.0.0.1:8000",
+    "mineru_api_key": "your-api-key",
+    "mineru_timeout": 300.0,
+    "mineru_bodys": {
+      "backend": "hybrid-auto-engine",
+      "lang_list": ["ch"],
+      "parse_method": "auto"
+    }
+  }
+}
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `strategy` | str | Parsing strategy: `local` / `mineru` / `auto` (default `auto`) |
+| `mineru_endpoint` | str | MinerU API **base URL** (e.g. `http://127.0.0.1:8000`) |
+| `mineru_api_key` | str | MinerU API authentication key (optional) |
+| `mineru_timeout` | float | Request timeout in seconds (default `300.0`) |
+| `mineru_bodys` | dict | MinerU API multipart form fields |
+
+**MinerU protocol**: a synchronous `POST {mineru_endpoint}/file_parse` request with the PDF as the multipart `files` field; form parameters are passed through from `mineru_bodys`.
+
 ### rerank
 
 Reranking model for search result refinement. Supports VikingDB (Volcengine), Cohere, and OpenAI-compatible APIs.

docs/zh/guides/01-configuration.md

@@ -850,6 +850,36 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8
 需要 GitHub、GitLab 或 Azure DevOps 专属 URL 语义时，应配置到对应的平台字段；
 其他 Git 主机统一添加到 `code_hosting_domains`。
 
+### pdf
+
+PDF 解析配置。支持三种策略：`local`（本地 pdfplumber）、`mineru`（远程 MinerU API）、`auto`（先本地、失败回退 MinerU）。
+
+```json
+{
+  "pdf": {
+    "strategy": "auto",
+    "mineru_endpoint": "http://127.0.0.1:8000",
+    "mineru_api_key": "your-api-key",
+    "mineru_timeout": 300.0,
+    "mineru_bodys": {
+      "backend": "hybrid-auto-engine",
+      "lang_list": ["ch"],
+      "parse_method": "auto"
+    }
+  }
+}
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `strategy` | str | 解析策略：`local` / `mineru` / `auto`（默认 `auto`） |
+| `mineru_endpoint` | str | MinerU API **base URL**（如 `http://127.0.0.1:8000`） |
+| `mineru_api_key` | str | MinerU API 认证密钥（可选） |
+| `mineru_timeout` | float | 请求超时秒数（默认 `300.0`） |
+| `mineru_bodys` | dict | MinerU API multipart form 参数 |
+
+**MinerU 协议**：同步调用 `POST {mineru_endpoint}/file_parse`，multipart 文件字段为 `files`，form 参数由 `mineru_bodys` 透传。
+
 ### rerank
 
 用于搜索结果精排的 Rerank 模型。支持 VikingDB (火山引擎)、Cohere 和 OpenAI 兼容接口。

examples/ov.conf.example

@@ -228,9 +228,14 @@
             "max_section_size": 4000,
             "section_size_flexibility": 0.3,
             "max_section_chars": 6000,
-            "mineru_endpoint": "https://mineru.example.com/api/v1",
+            "mineru_endpoint": "http://127.0.0.1:8000",
             "mineru_api_key": "{your-mineru-api-key}",
             "mineru_timeout": 300.0,
+            "mineru_bodys": {
+                "backend": "hybrid-auto-engine",
+                "lang_list": ["ch"],
+                "parse_method": "auto"
+            },
         },
         "code": {
             "github_raw_domain": "raw.githubusercontent.com",

openviking/parse/parsers/pdf.py

@@ -13,6 +13,7 @@
 """
 
 import asyncio
+import base64
 import hashlib
 import io
 import re
@@ -29,6 +30,7 @@
     lazy_import,
 )
 from openviking.parse.parsers.base_parser import BaseParser
+from openviking.utils.time_utils import parse_iso_datetime
 from openviking_cli.utils import get_logger
 from openviking_cli.utils.config.parser_config import PDFConfig
 
@@ -57,7 +59,7 @@ class PDFParser(BaseParser):
         >>> # Remote API parsing
         >>> config = PDFConfig(
         ...     strategy="mineru",
-        ...     mineru_endpoint="https://api.example.com/convert",
+        ...     mineru_endpoint="http://127.0.0.1:8000",
         ...     mineru_api_key="key"
         ... )
         >>> parser = PDFParser(config)
@@ -682,27 +684,38 @@ def _extract_image_from_page(self, page, img_info: dict) -> Optional[bytes]:
     async def _convert_mineru(
         self,
         pdf_path: Path,
+        storage=None,
         resource_name: Optional[str] = None,
     ) -> tuple[str, Dict[str, Any]]:
         """
-        Convert PDF to Markdown using MinerU API.
+        Convert PDF to Markdown using the MinerU /file_parse API.
 
         Args:
             pdf_path: Path to PDF file
-            resource_name: Optional resource name (unused in MinerU conversion)
+            storage: Media storage used to persist extracted images; defaults to
+                the configured storage if None
+            resource_name: Resource name under which extracted images are saved;
+                defaults to the PDF stem
 
         Returns:
-            Tuple of (markdown_content, metadata)
+            Tuple of (markdown_content, metadata) where metadata includes
+            strategy, endpoint, api_version, backend, task_id, processing_time
+            (seconds) and images_saved
 
         Raises:
-            ImportError: If httpx not installed
-            Exception: If API call fails
+            ValueError: If MinerU endpoint is not configured, or the task does
+                not complete
+            Exception: If the API call fails
         """
         httpx = lazy_import("httpx")
 
         if not self.config.mineru_endpoint:
             raise ValueError("MinerU endpoint not configured")
 
+        # mineru_endpoint is a base URL; append /file_parse unless it already ends with it
+        base = self.config.mineru_endpoint.rstrip("/")
+        url = base if base.endswith("/file_parse") else f"{base}/file_parse"
+
         meta = {
             "strategy": "mineru",
             "endpoint": self.config.mineru_endpoint,
@@ -713,44 +726,92 @@ async def _convert_mineru(
             async with httpx.AsyncClient(timeout=self.config.mineru_timeout) as client:
                 # Prepare file upload
                 with open(pdf_path, "rb") as f:
-                    files = {"file": (pdf_path.name, f, "application/pdf")}
+                    files = {"files": (pdf_path.name, f, "application/pdf")}
 
                     # Prepare headers
                     headers = {}
                     if self.config.mineru_api_key:
                         headers["Authorization"] = f"Bearer {self.config.mineru_api_key}"
 
-                    # Prepare request params
-                    params = self.config.mineru_params or {}
+                    # Prepare Form fields
+                    data: Dict[str, Any] = dict(self.config.mineru_bodys or {})
+
+                    # MinerU must return extracted images for the markdown refs.
+                    data["return_images"] = True
 
                     # Make API request
-                    logger.info(f"Calling MinerU API: {self.config.mineru_endpoint}")
+                    logger.info(f"Calling MinerU API: {url}")
                     response = await client.post(
-                        self.config.mineru_endpoint,
+                        url,
                         files=files,
+                        data=data,
                         headers=headers,
-                        params=params,
                     )
                     response.raise_for_status()
 
-                # Parse response
-                result = response.json()
-                markdown_content = result.get("markdown", "")
+            # Parse response
+            result = response.json()
+            if result.get("status") != "completed":
+                raise ValueError(f"MinerU task not completed: {result.get('status')}")
+
+            results = result.get("results") or {}
+            file_result = results.get(pdf_path.name) or next(iter(results.values()), {})
+            markdown_content = file_result.get("md_content") or ""
+
+            # Extract metadata from response
+            meta["api_version"] = result.get("version")
+            meta["backend"] = result.get("backend")
+            meta["task_id"] = result.get("task_id")
+            started_at, completed_at = result.get("started_at"), result.get("completed_at")
+            if started_at and completed_at:
+                meta["processing_time"] = (
+                    parse_iso_datetime(completed_at) - parse_iso_datetime(started_at)
+                ).total_seconds()
+
+            if not markdown_content:
+                logger.warning(f"MinerU returned empty content for {pdf_path}")
+                return markdown_content, meta
 
-                # Extract metadata from response
-                meta["api_version"] = result.get("version")
-                meta["processing_time"] = result.get("processing_time")
-                meta["total_pages"] = result.get("total_pages")
+            if storage is None:
+                from openviking_cli.utils.storage import get_storage
 
-                if not markdown_content:
-                    logger.warning(f"MinerU returned empty content for {pdf_path}")
+                storage = get_storage()
 
-                logger.info(
-                    f"MinerU conversion: {meta.get('total_pages', '?')} pages → "
-                    f"{len(markdown_content)} chars"
+            if resource_name is None:
+                resource_name = pdf_path.stem
+
+            # MinerU embeds images as base64 data-URLs, referenced from markdown
+            # as `images/<filename>`; save them into the media store and rewrite
+            # the references to the stored relative paths.
+            repl: Dict[str, str] = {}
+            media_dir = storage.media_dir
+            for img_name, data_url in (file_result.get("images") or {}).items():
+                try:
+                    # data URL form: "data:image/jpeg;base64,<b64>"
+                    image_bytes = base64.b64decode(data_url.split(",", 1)[-1])
+                    img_path = Path(img_name)
+                    image_path = storage.save_image(
+                        resource_name,
+                        image_bytes,
+                        filename=img_path.stem,
+                        extension=img_path.suffix or ".png",
+                    )
+                    repl[f"images/{img_name}"] = image_path.relative_to(media_dir).as_posix()
+                except Exception as img_err:
+                    logger.warning(f"Failed to save MinerU image {img_name}: {img_err}")
+
+            if repl:
+                # Single pass over the markdown replaces every known reference;
+                # unknown ``images/...`` text is left untouched.
+                ref_pattern = re.compile(
+                    "|".join(re.escape(ref) for ref in sorted(repl, key=len, reverse=True))
                 )
+                markdown_content = ref_pattern.sub(lambda m: repl[m.group(0)], markdown_content)
+                meta["images_saved"] = len(repl)
 
-                return markdown_content, meta
+            logger.info(f"MinerU conversion: {len(markdown_content)} chars")
+
+            return markdown_content, meta
 
         except Exception as e:
             logger.error(f"MinerU API call failed: {e}")

openviking_cli/utils/config/parser_config.py

@@ -150,7 +150,7 @@ class PDFConfig(ParserConfig):
         mineru_endpoint: MinerU API endpoint URL
         mineru_api_key: MinerU API authentication key
         mineru_timeout: MinerU request timeout in seconds
-        mineru_params: Additional MinerU API parameters
+        mineru_bodys: Additional MinerU API multipart form fields
     """
 
     strategy: str = "auto"  # "local" | "mineru" | "auto"
@@ -159,7 +159,7 @@ class PDFConfig(ParserConfig):
     mineru_endpoint: Optional[str] = None  # API endpoint URL
     mineru_api_key: Optional[str] = None  # API authentication key
     mineru_timeout: float = 300.0  # Request timeout in seconds (5 minutes)
-    mineru_params: Optional[dict] = None  # Additional API parameters
+    mineru_bodys: Optional[dict] = None  # Additional API multipart form fields
 
     # Heading detection configuration
     heading_detection: str = "auto"  # "bookmarks" | "font" | "auto" | "none"