feat(pdf): add mineru-first strategy for MinerU-priority fallback

docs/en/guides/01-configuration.md

@@ -1052,12 +1052,44 @@ PDF parsing configuration. Three strategies are supported: `local` (local pdfplu
 
 | 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_timeout` | float | Request timeout in seconds (default `300.0`) |
-| `mineru_bodys` | dict | MinerU API multipart form fields |
+| `strategy` | str | Parsing strategy: `local` / `mineru` / `mineru_first` / `auto` (default `auto`) |
+| `mineru_endpoint` | str | MinerU API **base URL** (e.g. `http://127.0.0.1:8000`, or `https://mineru.net/api/v4` for the online API) |
+| `mineru_timeout` | float | Request/polling timeout in seconds (default `300.0`) |
+| `mineru_bodys` | dict | MinerU API multipart form fields (passed through) |
+| `mineru_api_mode` | str | Protocol flavor: `auto` (detect from the response, default) / `sync` (legacy inline `/file_parse`) / `async` (task APIs) |
+| `mineru_token` | str | Optional bearer token for the online MinerU API (sent as `Authorization: Bearer ...`) |
 
-**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`.
+**MinerU protocols** — three flavors are supported:
+
+- **Legacy self-hosted (`sync`)**: a single `POST {mineru_endpoint}/file_parse` answering inline with the markdown; form parameters are passed through from `mineru_bodys`.
+- **Current self-hosted (`async`)**: `POST {mineru_endpoint}/tasks` answers `202` with `task_id`/`status_url`/`result_url`; the task is polled until `completed` and the markdown is downloaded from the result zip.
+- **Online batch API (`async`)**: `POST {mineru_endpoint}/extract/task/batch` (Bearer-token auth via `mineru_token`), poll `{mineru_endpoint}/extract-results/batch/{batch_id}` until `state=done`, download `full_zip_url` and unpack.
+
+Under the default `mineru_api_mode=auto` the flavor is detected automatically: the inline endpoint is tried first and a `404` (or a task-shaped response) switches to the task flow, so existing self-hosted v1 deployments keep working without config changes. The startup `/health` preflight only applies to the sync flavor (the online service has no such endpoint).
+
+**Choosing a strategy:**
+
+| `strategy` | MinerU used? | On MinerU failure | `mineru_endpoint` required |
+|---|---|---|---|
+| `local` | no | n/a | no |
+| `mineru` | always | the import fails | yes |
+| `mineru_first` | yes, tried first | falls back to the local parser | yes |
+| `auto` | only if local fails | the import fails | optional |
+
+Use `mineru_first` when remote conversion is worth the extra latency and quality but must never block an import — a missing token, a rate limit, or an outage degrades the document to the local parser instead of failing the whole batch. Unlike `mineru`, `mineru_first` never turns a MinerU problem into a startup problem: the preflight result is advisory and the fallback happens per document. The parser records which path actually ran in the result metadata as `pdf_strategy_effective` (`mineru` or `local`), so you can audit conversion quality after the fact.
+
+**Online example:**
+
+```json
+{
+  "pdf": {
+    "strategy": "mineru",
+    "mineru_endpoint": "https://mineru.net/api/v4",
+    "mineru_api_mode": "auto",
+    "mineru_token": "your-mineru-api-token"
+  }
+}
+```
 
 ### External parser API (`parser_api`) {#parser-api}
 

docs/zh/guides/01-configuration.md

@@ -1047,12 +1047,44 @@ PDF 解析配置。支持三种策略：`local`（本地 pdfplumber）、`mineru
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
-| `strategy` | str | 解析策略：`local` / `mineru` / `auto`（默认 `auto`） |
-| `mineru_endpoint` | str | MinerU API **base URL**（如 `http://127.0.0.1:8000`） |
-| `mineru_timeout` | float | 请求超时秒数（默认 `300.0`） |
-| `mineru_bodys` | dict | MinerU API multipart form 参数 |
+| `strategy` | str | 解析策略：`local` / `mineru` / `mineru_first` / `auto`（默认 `auto`） |
+| `mineru_endpoint` | str | MinerU API **base URL**（如自托管 `http://127.0.0.1:8000`，在线服务 `https://mineru.net/api/v4`） |
+| `mineru_timeout` | float | 请求/轮询超时秒数（默认 `300.0`） |
+| `mineru_bodys` | dict | MinerU API multipart form 参数（透传） |
+| `mineru_api_mode` | str | 协议形态：`auto`（按响应自动识别，默认）/ `sync`（旧版内联 `/file_parse`）/ `async`（任务式 API） |
+| `mineru_token` | str | 在线 MinerU API 的 bearer token（以 `Authorization: Bearer ...` 发送） |
 
-**MinerU 协议**：同步调用 `POST {mineru_endpoint}/file_parse`，multipart 文件字段为 `files`，form 参数由 `mineru_bodys` 透传。
+**MinerU 协议**——支持三种形态：
+
+- **旧版自托管（`sync`）**：单次 `POST {mineru_endpoint}/file_parse` 内联返回 markdown；form 参数由 `mineru_bodys` 透传。
+- **新版自托管（`async`）**：`POST {mineru_endpoint}/tasks` 返回 `202` 与 `task_id`/`status_url`/`result_url`；轮询任务至 `completed` 后从结果 zip 下载 markdown。
+- **在线批量 API（`async`）**：`POST {mineru_endpoint}/extract/task/batch`（通过 `mineru_token` 做 Bearer 认证），轮询 `{mineru_endpoint}/extract-results/batch/{batch_id}` 至 `state=done`，下载 `full_zip_url` 并解包。
+
+默认 `mineru_api_mode=auto` 时自动识别协议形态：先尝试内联端点，返回 `404`（或任务式响应）即切换到任务流，存量自托管 v1 部署无需改配置。启动时的 `/health` 预检仅适用于 sync 形态（在线服务没有该端点）。
+
+**如何选择策略：**
+
+| `strategy` | 是否使用 MinerU | MinerU 失败时 | 是否必填 `mineru_endpoint` |
+|---|---|---|---|
+| `local` | 否 | — | 否 |
+| `mineru` | 始终使用 | 导入失败 | 是 |
+| `mineru_first` | 优先使用 | 回退到本地解析器 | 是 |
+| `auto` | 仅本地失败后使用 | 导入失败 | 否 |
+
+当远程转换值得额外延迟、但**绝不能阻塞导入**时，请使用 `mineru_first`：token 缺失、限流或服务故障都会让该文档降级为本地解析，而不是让整批导入失败。与 `mineru` 不同，`mineru_first` 不会把 MinerU 的问题变成启动问题——预检结果仅作告警，回退按文档逐个发生。解析结果元数据中的 `pdf_strategy_effective`（值为 `mineru` 或 `local`）会记录实际走的路径，便于事后审计转换质量。
+
+**在线服务示例：**
+
+```json
+{
+  "pdf": {
+    "strategy": "mineru",
+    "mineru_endpoint": "https://mineru.net/api/v4",
+    "mineru_api_mode": "auto",
+    "mineru_token": "your-mineru-api-token"
+  }
+}
+```
 
 ### 外部解析 API（`parser_api`） {#parser-api}