feat(pdf): prefer a configured remote parser in auto, add hosted MinerU support

docs/en/about/02-changelog.md

@@ -7,6 +7,33 @@ This changelog is automatically generated from [GitHub Releases](https://github.
 
 ## Unreleased
 
+- **`auto` falls back to local on any remote parser failure**: each configured remote
+  provider is tried in turn and the first success wins; a provider that raises is logged
+  and the next option is tried, so a remote outage degrades that document to local instead
+  of failing the import. The path actually taken is recorded in `pdf_strategy_effective`,
+  and whether any remote parser is configured is now `PDFConfig.remote_enabled`, expressed
+  over the provider list rather than one service.
+- **MinerU hosted API support (`mineru_token`)**: a new `pdf.mineru_token` setting carries
+  the bearer token for the hosted MinerU service and, because that service has no
+  `/file_parse` route, its presence also selects the hosted batch protocol:
+  `POST /file-urls/batch` to reserve an upload URL, `PUT` the PDF there, poll
+  `GET /extract-results/batch/{batch_id}` until it settles, then download `full_zip_url`
+  and take the markdown with its images. Without a token the endpoint keeps using the
+  existing self-hosted `/file_parse` contract, so current deployments are unaffected.
+  If the batch handshake is refused the parser retries once against `/file_parse`, which
+  keeps token-gated self-hosted deployments working.
+- **PDF `auto` strategy prefers the configured remote parser (behavior change)**: `auto` now
+  sends every PDF to the configured remote parser and uses the local parser only as a
+  fallback, where it previously tried local first and only used MinerU when local parsing
+  failed. With `pdf.mineru_endpoint` set, expect changes in latency, quota consumption and
+  rate-limit exposure; under throttling the fallback makes such imports slower, not faster.
+  Set `strategy: local` to keep the previous remote-as-last-resort behaviour, or
+  `strategy: mineru` to require the remote path and fail on its errors. A remote failure
+  degrades a single document instead of failing the batch, and `pdf_strategy_effective`
+  (`mineru` or `local`) records which converter actually ran. Service-specific settings
+  (`mineru_endpoint`, `mineru_token`, `mineru_bodys`) stay where they are, so a future
+  remote parser is added as a provider rather than as another `strategy` value.
+
 - **LangChain import migration (breaking change)**: The server no longer ships
   `openviking.integrations.langchain` or its forwarding modules. Old imports fail
   immediately; there is no deprecation period or compatibility stub. Install

docs/en/guides/01-configuration.md

@@ -1038,7 +1038,7 @@ needs those platform-specific URL semantics. Add other Git hosts to
 
 ### pdf
 
-PDF parsing configuration. Three strategies are supported: `local` (local pdfplumber), `mineru` (remote MinerU API), and `auto` (try local first, fall back to MinerU).
+PDF parsing configuration. Three strategies are supported: `local` (local pdfplumber), `mineru` (remote MinerU API, failures fail the import), and `auto` (use the configured remote parser when there is one, otherwise local).
 
 ```json
 {
@@ -1061,8 +1061,67 @@ PDF parsing configuration. Three strategies are supported: `local` (local pdfplu
 | `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 |
-
-**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_token` | str | Bearer token for the hosted MinerU service. Setting it also selects the hosted batch protocol (see below) |
+
+**MinerU protocols**: which one is used follows from whether `mineru_token` is set.
+
+| Config | Protocol | Flow |
+|---|---|---|
+| no `mineru_token` | self-hosted (v1) | `POST {mineru_endpoint}/file_parse`, markdown returned inline |
+| `mineru_token` set | hosted batch (v4) | `POST /file-urls/batch` to reserve an upload URL, `PUT` the PDF there, poll `GET /extract-results/batch/{batch_id}` until it settles, then download `full_zip_url` and take the markdown plus its images |
+
+The hosted service has no `/file_parse` route at all, so a token is treated as the
+signal for that API rather than as a credential to bolt onto the v1 call. If the batch
+handshake is refused the parser retries once against `/file_parse`, which keeps a
+token-gated self-hosted deployment working.
+
+**Choosing a strategy:**
+
+| `strategy` | Remote parser used? | On remote failure | `mineru_endpoint` required |
+|---|---|---|---|
+| `local` | no | n/a | no |
+| `mineru` | always | the import fails | yes |
+| `auto` | yes, if one is configured | falls back to the local parser | optional |
+
+`auto` (the default) uses whichever remote parser is configured and treats the local
+parser as the last resort. With `mineru_endpoint` set, every PDF is converted remotely;
+if that call fails — missing token, rate limit, outage — that single document falls back
+to local and the import still succeeds. With nothing configured, `auto` uses the local
+parser directly. `mineru` is the strict variant: MinerU is the result, and a failure
+fails the import rather than degrading.
+
+Whether a remote parser is in play is `PDFConfig.remote_enabled`, expressed over the
+provider list rather than any single service, so adding a provider does not mean
+revisiting `auto`, the preflight, or this page. `mineru_enabled` remains the MinerU
+provider's own check.
+
+`auto` tries each configured remote provider in turn and uses the first one that
+succeeds. A provider that raises is logged and the next option is tried, so any
+remote failure -- `404`, `405`, `429`, a timeout, a `5xx` -- degrades that document
+to local rather than failing it. The path actually taken is recorded in
+`pdf_strategy_effective`, so a batch that quietly stopped using the remote parser is
+visible after the fact.
+
+The startup preflight follows the same rule: `mineru` fails fast if the endpoint is not
+ready, `auto` only warns and leaves the retry to the first parse.
+
+:::warning Behavior change
+`auto` previously tried the local parser **first** and only used MinerU when local
+parsing failed. It now prefers the configured remote parser. If you have `mineru_endpoint`
+set, every PDF is sent to that service, so expect a change in latency, quota usage and
+rate-limit exposure. Set `strategy: local` to keep the previous remote-as-last-resort
+behaviour, or `strategy: mineru` if you want the remote path to be mandatory.
+:::
+
+Service-specific settings live in their own fields (`mineru_endpoint`, `mineru_token`,
+`mineru_bodys`), so supporting a new remote parser is a provider change rather than a new
+`strategy` value.
+
+:::tip `auto` degrades on any remote error
+A remote failure of any kind -- `404`, `405`, `429`, a timeout, a 5xx -- falls back to the
+local parser for that document, so the import still succeeds. Set `mineru_token` when
+pointing `mineru_endpoint` at the hosted MinerU service: that both authenticates the call
+and selects the protocol the service actually speaks.
 
 ### External parser API (`parser_api`) {#parser-api}
 

docs/zh/about/02-changelog.md

@@ -7,6 +7,10 @@ OpenViking 的所有重要变更都将记录在此文件中。
 
 ## 未发布
 
+- **`auto` 在任何远程解析失败时降级到本地**：依次尝试每个已配置的远程 provider 并使用第一个成功的；某个 provider 抛出异常时记录日志并尝试下一个，因此远程服务不可用时使该文档降级到本地解析，而不会使导入失败。实际走的路径记录在 `pdf_strategy_effective`；同时，“是否有远程解析服务在场”改用 `PDFConfig.remote_enabled` 判定，它以 provider 列表表达，而不绑定单一服务。
+- **MinerU 托管服务支持（`mineru_token`）**：新增 `pdf.mineru_token` 用于携带托管版 MinerU 服务的 Bearer token；由于该服务没有 `/file_parse` 路由，配置它同时会选中托管批处理协议：`POST /file-urls/batch` 预留上传 URL → `PUT` 上传 PDF → 轮询 `GET /extract-results/batch/{batch_id}` → 下载 `full_zip_url` 并取出 markdown 与其图片。未配置 token 时仍使用原有的自托管 `/file_parse` 协议，现有部署不受影响。若批处理握手被拒，解析器会再尝试一次 `/file_parse`，以保持带 token 的自托管部署仍然可用。
+- **PDF `auto` 策略改为优先使用已配置的远程解析器（行为变更）**：`auto` 现在会将每份 PDF 发往已配置的远程解析服务，本地解析器仅作兜底；而之前是先本地、本地失败才使用 MinerU。若配置了 `pdf.mineru_endpoint`，请预期延迟、额度消耗与限流风险发生变化；在限流情况下，回退机制会让导入变慢而不是变快。若希望保持原有行为请设为 `strategy: local`；若希望远程解析必须成功、失败即失败，请设为 `strategy: mineru`。远程失败会仅降级单份文档而不使整批导入失败，并由 `pdf_strategy_effective`（`mineru` 或 `local`）记录实际使用的转换器。服务类配置（`mineru_endpoint`、`mineru_token`、`mineru_bodys`）保持当前位置，未来接入新的远程解析服务时只需增加 provider，而无需新增 `strategy` 取值。
+
 - **LangChain 导入迁移（不兼容变更）**：服务端不再提供
   `openviking.integrations.langchain` 及其转发模块，旧导入会立即失败，
   不提供弃用过渡期或兼容占位模块。请安装 `langchain-openviking`

docs/zh/guides/01-configuration.md

@@ -1032,7 +1032,7 @@ ollama pull guoxuter/ov_intent_analysis_sft:v7_q8
 
 ### pdf
 
-PDF 解析配置。支持三种策略：`local`（本地 pdfplumber）、`mineru`（远程 MinerU API）、`auto`（先本地、失败回退 MinerU）。
+PDF 解析配置。支持三种策略：`local`（本地 pdfplumber）、`mineru`（远程 MinerU API，失败即导入失败）、`auto`（配置了远程解析服务就优先使用，否则走本地）。
 
 ```json
 {
@@ -1055,8 +1055,44 @@ PDF 解析配置。支持三种策略：`local`（本地 pdfplumber）、`mineru
 | `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 参数 |
+| `mineru_token` | str | 托管 MinerU 服务的 Bearer token。配置它同时会选中托管批处理协议（见下） |
 
-**MinerU 协议**：同步调用 `POST {mineru_endpoint}/file_parse`，multipart 文件字段为 `files`，form 参数由 `mineru_bodys` 透传。
+**MinerU 协议**：使用哪种协议取决于是否配置了 `mineru_token`。
+
+| 配置 | 协议 | 流程 |
+|---|---|---|
+| 未配 `mineru_token` | 自托管 v1 | `POST {mineru_endpoint}/file_parse`，同步返回 markdown |
+| 配置了 `mineru_token` | 托管批处理 v4 | `POST /file-urls/batch` 预留上传 URL → `PUT` 上传 PDF → 轮询 `GET /extract-results/batch/{batch_id}` → 下载 `full_zip_url` 并解包 markdown 与图片 |
+
+托管服务根本没有 `/file_parse` 路由，因此 token 在这里是“选中托管 API”的信号，而不是简单地贴到 v1 请求上。若批处理握手被拒，解析器会再尝试一次 `/file_parse`，以保持带 token 的自托管部署仍然可用。
+
+**如何选择策略：**
+
+| `strategy` | 是否使用远程解析 | 远程失败时 | 是否必填 `mineru_endpoint` |
+|---|---|---|---|
+| `local` | 否 | — | 否 |
+| `mineru` | 始终使用 | 导入失败 | 是 |
+| `auto` | 配置了就使用 | 回退到本地解析器 | 否 |
+
+`auto`（默认）使用已配置的远程解析服务，并把本地解析器作为最后兜底。若配置了 `mineru_endpoint`，每份 PDF 都会走远程转换；若该调用失败（token 缺失、限流、服务不可用），只该份文档会降级为本地解析，导入仍然成功。若什么都没配，`auto` 直接使用本地解析。`mineru` 是严格变体：远程失败就使导入失败，而不降级。
+
+是否有远程解析服务在场，由 `PDFConfig.remote_enabled` 判定，它是从 provider 列表的角度表达的，而不是绑定某一个具体服务；因此新增 provider 时无需重新修改 `auto`、预检或本页。`mineru_enabled` 仍是 MinerU 这个 provider 自身的判定。
+
+为避免一个已降级的批次变得明显更慢，`auto` 不会无目的地重试：
+
+`auto` 依次尝试每个已配置的远程 provider，并使用第一个成功的。某个 provider 抛出异常时只记录日志并尝试下一个，因此任何远程失败（`404`、`405`、`429`、超时、`5xx`）都会使该文档降级为本地解析，而不会使导入失败。实际走的路径记录在
+`pdf_strategy_effective`，因此静默失效的远程解析在之后仍可见。
+
+启动预检遵循同一规则：`mineru` 在端点未就绪时快速失败，`auto` 仅告警，重试留给首次解析。
+
+:::warning 行为变更
+`auto` 之前是**先本地、本地失败才用 MinerU**；现在改为**优先使用已配置的远程服务**。若你配置了 `mineru_endpoint`，每份 PDF 都会发往该服务，延迟、额度消耗与限流风险都会变化。若希望保持原有行为，设为 `strategy: local`；若希望远程解析必须成功，设为 `strategy: mineru`。
+:::
+
+服务类配置各自独立（`mineru_endpoint`、`mineru_token`、`mineru_bodys`），因此接入新的远程解析服务只需增加 provider，而不是新增 `strategy` 取值。
+
+:::tip `auto` 在任意远程错误时都会降级
+任何远程失败——`404`、`405`、`429`、超时、5xx——都会让该份文档降级到本地解析器，导入仍然成功。当 `mineru_endpoint` 指向托管版 MinerU 时请配置 `mineru_token`：它既能完成认证，也会选中该服务实际支持的协议。
 
 ### 外部解析 API（`parser_api`） {#parser-api}