sdpy-kit 0.1.0__py3-none-any.whl

kit/mineru_kit.py

@@ -0,0 +1,918 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+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.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-08-19
+"""MinerU 精准解析 API 工具类
+
+封装 MinerU 官方"精准解析 API"（https://mineru.net/apiManage/docs），
+将 PDF、图片、Office 文档、HTML 等解析为 Markdown/JSON 等结构化结果。
+
+覆盖端点：
+- POST /api/v4/extract/task               创建单文件解析任务（URL 方式）
+- GET  /api/v4/extract/task/{task_id}     查询单任务结果
+- POST /api/v4/file-urls/batch            批量申请文件上传链接
+- GET  /api/v4/extract-results/batch/{batch_id}  查询批量任务结果
+
+设计要点：
+- 全部方法无内部可变状态，线程安全（与 DocKit 风格一致）。
+- 不依赖实例属性者用 staticmethod，需要访问类常量者用 classmethod。
+- 低层方法（create_task / get_task_result / create_batch / upload_files /
+  get_batch_results）直接抛异常，便于精确定位。
+- 高层方法（parse_url / parse_files / wait_for_task / wait_for_batch /
+  download_zip）封装"提交 → 轮询 → 完成"完整流程。
+- 可选参数均为 None 时不发送，交由服务端使用默认值。
+- Token 通过 Settings 的 MINERU_API_KEY 注入（.env 配置）。
+"""
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from kit.config.kit_config import get_settings
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+# 官方限制：单文件大小上限 200MB、单次批量申请上传链接上限 50 个
+_MAX_FILE_SIZE_BYTES: int = 200 * 1024 * 1024
+_MAX_BATCH_FILES: int = 50
+
+# 支持的文件扩展名（官方文档：PDF / 图片 / Office / HTML）
+_SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        # PDF
+        ".pdf",
+        # 图片
+        ".png",
+        ".jpg",
+        ".jpeg",
+        # ".jp2",
+        # ".webp",
+        # ".gif",
+        # ".bmp",
+        # Word
+        ".doc",
+        ".docx",
+        # PowerPoint
+        ".ppt",
+        ".pptx",
+        # Excel
+        ".xls",
+        ".xlsx",
+        # HTML
+        ".html",
+    }
+)
+
+# 任务终态
+_STATE_DONE: str = "done"
+_STATE_FAILED: str = "failed"
+
+
+class MinerUError(Exception):
+    """MinerU API 调用异常（配置缺失 / 网络失败 / HTTP 或业务错误码）"""
+
+
+@dataclass(frozen=True, slots=True)
+class TaskResult:
+    """单任务查询结果
+
+    Attributes:
+        task_id: 任务 ID
+        state: 任务状态（done 完成 / pending 排队 / running 解析中 /
+               failed 失败 / converting 格式转换中）
+        full_zip_url: 解析结果压缩包地址，state=done 时有效
+        err_msg: 失败原因，state=failed 时有效
+        data_id: 业务数据 ID（请求时传入才会返回）
+        extracted_pages: 已解析页数，state=running 时有效
+        total_pages: 文档总页数，state=running 时有效
+        start_time: 解析开始时间，state=running 时有效
+    """
+
+    task_id: str
+    state: str
+    full_zip_url: str | None = None
+    err_msg: str | None = None
+    data_id: str | None = None
+    extracted_pages: int | None = None
+    total_pages: int | None = None
+    start_time: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BatchTaskResult(TaskResult):
+    """批量任务结果项，在 TaskResult 基础上附加文件名"""
+
+    file_name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BatchFile:
+    """批量解析请求中的单个文件描述
+
+    Attributes:
+        name: 文件名（强烈建议带正确扩展名，服务端据此识别类型）
+        data_id: 业务数据 ID（可选，用于唯一标识业务数据）
+        is_ocr: 是否启用 OCR（可选，仅 pipeline / vlm 模型有效）
+        page_ranges: 页码范围（可选），如 "2,4-6"、"2--2"
+    """
+
+    name: str
+    data_id: str | None = None
+    is_ocr: bool | None = None
+    page_ranges: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BatchUploadInfo:
+    """批量申请上传链接结果
+
+    Attributes:
+        batch_id: 批次 ID，用于查询批量任务结果
+        file_urls: 预签名上传 URL 列表（有效期 24 小时）
+    """
+
+    batch_id: str
+    file_urls: list[str]
+
+
+class MinerUKit:
+    """MinerU 精准解析 API 工具类
+
+    仅实现官方"精准解析 API"（需 Token），不支持 Agent 轻量解析 API。
+
+    使用前准备：在 `.env` 中配置::
+
+        MINERU_API_KEY=你的token   # 在 MinerU 官网 API 管理页面自建
+
+    使用方式::
+
+        # 1. 解析一个公网 URL（提交 + 轮询一步到位）
+        result = MinerUKit.parse_url(
+            "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
+            model_version="vlm",
+        )
+        if result.state == "done":
+            zip_path = MinerUKit.download_zip(result.full_zip_url, "./output")
+
+        # 2. 解析本地文件（批量上传 + 轮询一步到位）
+        results = MinerUKit.parse_files(["report1.pdf", "report2.docx"])
+
+        # 3. 低层分步调用
+        task_id = MinerUKit.create_task(url, model_version="vlm")
+        result = MinerUKit.wait_for_task(task_id)
+
+    注意：
+    - 单文件 ≤ 200MB；单次批量 ≤ 50 个文件（官方限制，本地强制校验）。
+    - github、aws 等国外 URL 可能因网络限制请求超时（官方说明）。
+    """
+
+    SUPPORTED_EXTENSIONS: frozenset[str] = _SUPPORTED_EXTENSIONS
+    MAX_FILE_SIZE_BYTES: int = _MAX_FILE_SIZE_BYTES
+    MAX_BATCH_FILES: int = _MAX_BATCH_FILES
+
+    # ------------------------------------------------------------------
+    # 内部工具
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _token() -> str:
+        """读取 API Key，未配置时抛出 MinerUError"""
+        token = get_settings().MINERU_API_KEY
+        if not token:
+            raise MinerUError(
+                "未配置 MINERU_API_KEY，请在 .env 中设置"
+                "（在 MinerU 官网 API 管理页面自建）"
+            )
+        return token
+
+    @classmethod
+    def _headers(cls) -> dict[str, str]:
+        """构造带鉴权的请求头"""
+        return {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {cls._token()}",
+        }
+
+    @staticmethod
+    def _base_url() -> str:
+        """读取 API 基础地址（去除尾部斜杠）"""
+        return get_settings().MINERU_BASE_API_URL.rstrip("/")
+
+    @staticmethod
+    def _request(method: str, url: str, **kwargs: Any) -> dict[str, Any]:
+        """发送 HTTP 请求并统一校验响应，成功返回 JSON 字典
+
+        Raises:
+            MinerUError: 网络失败 / HTTP 非 200 / 业务 code 非 0
+        """
+        timeout = get_settings().MINERU_TIMEOUT
+        try:
+            resp = requests.request(method, url, timeout=timeout, **kwargs)
+        except requests.RequestException as e:
+            logger.error(f"MinerU API 请求失败: {method} {url}: {e}")
+            raise MinerUError(f"网络请求失败: {e}") from e
+
+        if resp.status_code != 200:
+            logger.error(
+                f"MinerU API HTTP 错误: {method} {url} -> "
+                f"{resp.status_code}: {resp.text[:200]}"
+            )
+            raise MinerUError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+
+        payload: dict[str, Any] = resp.json()
+        code = payload.get("code")
+        if code != 0:
+            msg = payload.get("msg", "未知错误")
+            trace_id = payload.get("trace_id", "")
+            logger.error(
+                f"MinerU API 业务错误: code={code}, msg={msg}, trace_id={trace_id}"
+            )
+            raise MinerUError(f"API 错误 code={code}: {msg}（trace_id={trace_id}）")
+        return payload
+
+    @staticmethod
+    def _build_payload(params: dict[str, Any]) -> dict[str, Any]:
+        """过滤值为 None 的参数，仅保留显式传入项"""
+        return {k: v for k, v in params.items() if v is not None}
+
+    @classmethod
+    def _check_local_file(cls, file_path: str | Path) -> Path:
+        """校验本地待上传文件（存在 / 扩展名 / 大小），通过返回绝对路径
+
+        Raises:
+            FileNotFoundError: 文件不存在或不是常规文件
+            ValueError: 扩展名不受支持或超过 200MB 大小限制
+        """
+        path = Path(file_path).resolve()
+        if not path.is_file():
+            raise FileNotFoundError(f"文件不存在: {path}")
+        ext = path.suffix.lower()
+        if ext not in cls.SUPPORTED_EXTENSIONS:
+            raise ValueError(
+                f"不支持的文件格式: {ext or '<无扩展名>'}，"
+                f"支持的格式: {', '.join(sorted(cls.SUPPORTED_EXTENSIONS))}"
+            )
+        if path.stat().st_size > cls.MAX_FILE_SIZE_BYTES:
+            size_mb = path.stat().st_size / 1024 / 1024
+            raise ValueError(
+                f"文件大小 {size_mb:.1f}MB 超过官方限制 200MB: {path.name}"
+            )
+        return path
+
+    # ------------------------------------------------------------------
+    # 低层 API（一端点一方法）
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def create_task(
+        cls,
+        url: str,
+        *,
+        model_version: str | None = None,
+        is_ocr: bool | None = None,
+        enable_formula: bool | None = None,
+        enable_table: bool | None = None,
+        language: str | None = None,
+        data_id: str | None = None,
+        callback: str | None = None,
+        seed: str | None = None,
+        extra_formats: list[str] | None = None,
+        page_ranges: str | None = None,
+        no_cache: bool | None = None,
+        cache_tolerance: int | None = None,
+    ) -> str:
+        """创建单文件解析任务（URL 方式）
+
+        对应官方端点 ``POST /api/v4/extract/task``。该接口不支持文件直接上传，
+        仅接收可公网访问的文件 URL（github、aws 等国外 URL 可能超时）。
+
+        Args:
+            url: 文件 URL（支持 pdf/doc/docx/ppt/pptx/xls/xlsx/图片/html）
+            model_version: 模型版本，可选 ``pipeline``（官方默认）/ ``vlm``（推荐）/
+                ``MinerU-HTML``（解析 HTML 文件时必须指定）
+            is_ocr: 是否启用 OCR，默认服务端 false，仅 pipeline / vlm 有效
+            enable_formula: 是否开启公式识别，默认服务端 true，仅 pipeline / vlm 有效
+            enable_table: 是否开启表格识别，默认服务端 true，仅 pipeline / vlm 有效
+            language: 文档语言（默认 ``ch``），仅 pipeline / vlm 有效
+            data_id: 业务数据 ID（字母/数字/下划线/短划线/句号，≤128 字符）
+            callback: 解析结果回调通知 URL（POST/UTF-8/JSON）；为空需轮询结果
+            seed: 回调签名随机字符串（使用 callback 时必须提供，≤64 字符）
+            extra_formats: 附加导出格式，仅支持 ``docx`` / ``html`` / ``latex``
+                中一个或多个（markdown、json 默认导出无须设置）
+            page_ranges: 页码范围，如 ``"2,4-6"``（第2页及第4~6页）、``"2--2"``
+                （第2页至倒数第二页）
+            no_cache: 是否绕过缓存，默认服务端 false
+            cache_tolerance: 缓存容忍时间（秒），默认服务端 900
+
+        Returns:
+            str: 任务 ID（task_id），用于查询任务结果
+
+        Raises:
+            MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
+
+        Example:
+            >>> task_id = MinerUKit.create_task(
+            ...     "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
+            ...     model_version="vlm",
+            ... )
+        """
+        payload = cls._build_payload(
+            {
+                "url": url,
+                "model_version": model_version,
+                "is_ocr": is_ocr,
+                "enable_formula": enable_formula,
+                "enable_table": enable_table,
+                "language": language,
+                "data_id": data_id,
+                "callback": callback,
+                "seed": seed,
+                "extra_formats": extra_formats,
+                "page_ranges": page_ranges,
+                "no_cache": no_cache,
+                "cache_tolerance": cache_tolerance,
+            }
+        )
+        logger.info(f"提交 MinerU 解析任务: {url}")
+        resp = cls._request(
+            "POST",
+            f"{cls._base_url()}/api/v4/extract/task",
+            headers=cls._headers(),
+            json=payload,
+        )
+        task_id: str = resp["data"]["task_id"]
+        logger.info(f"MinerU 任务已创建: task_id={task_id}")
+        return task_id
+
+    @classmethod
+    def get_task_result(cls, task_id: str) -> TaskResult:
+        """查询单任务结果
+
+        对应官方端点 ``GET /api/v4/extract/task/{task_id}``。
+
+        Args:
+            task_id: 任务 ID（由 create_task / create_batch 返回）
+
+        Returns:
+            TaskResult: 任务状态与结果（state=done 时含 full_zip_url）
+
+        Raises:
+            MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
+
+        Example:
+            >>> result = MinerUKit.get_task_result(task_id)
+            >>> result.state
+            'done'
+        """
+        resp = cls._request(
+            "GET",
+            f"{cls._base_url()}/api/v4/extract/task/{task_id}",
+            headers=cls._headers(),
+        )
+        data: dict[str, Any] = resp.get("data", {})
+        progress: dict[str, Any] = data.get("extract_progress") or {}
+        return TaskResult(
+            task_id=data.get("task_id", task_id),
+            state=data.get("state", ""),
+            full_zip_url=data.get("full_zip_url"),
+            err_msg=data.get("err_msg"),
+            data_id=data.get("data_id"),
+            extracted_pages=progress.get("extracted_pages"),
+            total_pages=progress.get("total_pages"),
+            start_time=progress.get("start_time"),
+        )
+
+    @classmethod
+    def create_batch(
+        cls,
+        files: list[BatchFile],
+        *,
+        model_version: str | None = None,
+        enable_formula: bool | None = None,
+        enable_table: bool | None = None,
+        language: str | None = None,
+        callback: str | None = None,
+        seed: str | None = None,
+        extra_formats: list[str] | None = None,
+        no_cache: bool | None = None,
+        cache_tolerance: int | None = None,
+    ) -> BatchUploadInfo:
+        """批量申请文件上传链接（本地文件解析第一步）
+
+        对应官方端点 ``POST /api/v4/file-urls/batch``。申请到的预签名 URL
+        有效期 24 小时；文件上传完成后系统**自动**提交解析任务，无须再调用
+        create_task。
+
+        Args:
+            files: 文件描述列表（≤50 个），每项含文件名与可选参数
+            model_version: 模型版本（同 create_task；HTML 文件须指定 MinerU-HTML）
+            enable_formula: 是否开启公式识别（同 create_task）
+            enable_table: 是否开启表格识别（同 create_task）
+            language: 文档语言（同 create_task）
+            callback: 解析结果回调通知 URL（同 create_task）
+            seed: 回调签名随机字符串（使用 callback 时必须提供）
+            extra_formats: 附加导出格式（同 create_task）
+            no_cache: 是否绕过缓存（同 create_task）
+            cache_tolerance: 缓存容忍时间（秒，同 create_task）
+
+        Returns:
+            BatchUploadInfo: 批次 ID 与预签名上传 URL 列表
+
+        Raises:
+            ValueError: 文件列表为空或超过 50 个，或扩展名不受支持
+            MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
+
+        Example:
+            >>> info = MinerUKit.create_batch(
+            ...     [BatchFile(name="demo.pdf")], model_version="vlm"
+            ... )
+            >>> info.batch_id
+        """
+        if not files:
+            raise ValueError("文件列表不能为空")
+        if len(files) > cls.MAX_BATCH_FILES:
+            raise ValueError(
+                f"单次批量不能超过 {cls.MAX_BATCH_FILES} 个文件，当前: {len(files)}"
+            )
+        for f in files:
+            ext = Path(f.name).suffix.lower()
+            if ext not in cls.SUPPORTED_EXTENSIONS:
+                raise ValueError(
+                    f"不支持的文件格式: {f.name}（扩展名 {ext or '<无扩展名>'}）"
+                )
+
+        file_dicts = [
+            cls._build_payload(
+                {
+                    "name": f.name,
+                    "data_id": f.data_id,
+                    "is_ocr": f.is_ocr,
+                    "page_ranges": f.page_ranges,
+                }
+            )
+            for f in files
+        ]
+        payload = cls._build_payload(
+            {
+                "files": file_dicts,
+                "model_version": model_version,
+                "enable_formula": enable_formula,
+                "enable_table": enable_table,
+                "language": language,
+                "callback": callback,
+                "seed": seed,
+                "extra_formats": extra_formats,
+                "no_cache": no_cache,
+                "cache_tolerance": cache_tolerance,
+            }
+        )
+        logger.info(f"申请 MinerU 批量上传链接: {len(files)} 个文件")
+        resp = cls._request(
+            "POST",
+            f"{cls._base_url()}/api/v4/file-urls/batch",
+            headers=cls._headers(),
+            json=payload,
+        )
+        data: dict[str, Any] = resp["data"]
+        info = BatchUploadInfo(
+            batch_id=data["batch_id"],
+            file_urls=list(data.get("file_urls", [])),
+        )
+        logger.info(
+            f"MinerU 批量上传链接已获取: batch_id={info.batch_id}，"
+            f"{len(info.file_urls)} 个链接"
+        )
+        return info
+
+    @classmethod
+    def upload_files(
+        cls, file_paths: list[str | Path], upload_urls: list[str]
+    ) -> list[bool]:
+        """将本地文件批量上传至预签名 URL（本地文件解析第二步）
+
+        对文件执行 PUT 上传。官方要求：上传时**不设置** Authorization 与
+        Content-Type 请求头，本方法已按此处理。逐个上传，单个失败记录日志
+        并继续，不影响其余文件。
+
+        Args:
+            file_paths: 本地文件路径列表（与 upload_urls 顺序一一对应）
+            upload_urls: create_batch 返回的预签名上传 URL 列表
+
+        Returns:
+            list[bool]: 每个文件的上传结果（True 成功 / False 失败）
+
+        Raises:
+            ValueError: 两个列表长度不一致
+            FileNotFoundError: 文件不存在（单个文件校验失败直接抛出）
+            MinerUError: 网络请求失败
+
+        Example:
+            >>> results = MinerUKit.upload_files(["demo.pdf"], info.file_urls)
+        """
+        if len(file_paths) != len(upload_urls):
+            raise ValueError(
+                f"文件数 ({len(file_paths)}) 与上传链接数 ({len(upload_urls)}) 不一致"
+            )
+        timeout = get_settings().MINERU_TIMEOUT
+        results: list[bool] = []
+        for file_path, upload_url in zip(file_paths, upload_urls):
+            path = cls._check_local_file(file_path)
+            logger.info(f"上传文件到 MinerU: {path.name}（{path.stat().st_size} 字节）")
+            try:
+                resp = requests.put(upload_url, data=path.read_bytes(), timeout=timeout)
+            except requests.RequestException as e:
+                logger.error(f"文件上传失败: {path.name}: {e}")
+                results.append(False)
+                continue
+            if resp.status_code == 200:
+                logger.info(f"✅ 文件上传成功: {path.name}")
+                results.append(True)
+            else:
+                logger.error(
+                    f"文件上传失败: {path.name} -> HTTP {resp.status_code}: "
+                    f"{resp.text[:200]}"
+                )
+                results.append(False)
+        return results
+
+    @classmethod
+    def get_batch_results(cls, batch_id: str) -> list[BatchTaskResult]:
+        """查询批量任务结果
+
+        对应官方端点 ``GET /api/v4/extract-results/batch/{batch_id}``。
+        注意：查询过早时部分任务可能尚未创建（结果列表可能少于上传文件数），
+        等待全部完成请使用 wait_for_batch。
+
+        Args:
+            batch_id: 批次 ID（由 create_batch 返回）
+
+        Returns:
+            list[BatchTaskResult]: 批次内各文件的当前状态
+
+        Raises:
+            MinerUError: 未配置 Token / 网络失败 / HTTP 或业务错误码
+
+        Example:
+            >>> results = MinerUKit.get_batch_results(info.batch_id)
+            >>> [(r.file_name, r.state) for r in results]
+        """
+        resp = cls._request(
+            "GET",
+            f"{cls._base_url()}/api/v4/extract-results/batch/{batch_id}",
+            headers=cls._headers(),
+        )
+        data: dict[str, Any] = resp.get("data", {})
+        raw_list: list[dict[str, Any]] = data.get("extract_result", [])
+        results: list[BatchTaskResult] = []
+        for item in raw_list:
+            progress: dict[str, Any] = item.get("extract_progress") or {}
+            results.append(
+                BatchTaskResult(
+                    task_id=item.get("task_id", ""),
+                    state=item.get("state", ""),
+                    full_zip_url=item.get("full_zip_url"),
+                    err_msg=item.get("err_msg"),
+                    data_id=item.get("data_id"),
+                    extracted_pages=progress.get("extracted_pages"),
+                    total_pages=progress.get("total_pages"),
+                    start_time=progress.get("start_time"),
+                    file_name=item.get("file_name"),
+                )
+            )
+        return results
+
+    # ------------------------------------------------------------------
+    # 高层便利 API（提交 → 轮询 → 完成）
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def wait_for_task(
+        cls,
+        task_id: str,
+        *,
+        poll_interval: float | None = None,
+        timeout: int | None = None,
+    ) -> TaskResult:
+        """轮询等待单任务到达终态（done / failed）
+
+        Args:
+            task_id: 任务 ID
+            poll_interval: 轮询间隔秒数，None 时使用 MINERU_POLL_INTERVAL
+            timeout: 总等待秒数，None 时使用 MINERU_MAX_WAIT
+
+        Returns:
+            TaskResult: 终态结果（state=done 或 failed）
+
+        Raises:
+            MinerUError: 超过总等待时间仍未到达终态
+
+        Example:
+            >>> result = MinerUKit.wait_for_task(task_id, timeout=300)
+        """
+        settings = get_settings()
+        interval = (
+            poll_interval
+            if poll_interval is not None
+            else settings.MINERU_POLL_INTERVAL
+        )
+        max_wait = timeout if timeout is not None else settings.MINERU_MAX_WAIT
+        deadline = time.monotonic() + max_wait
+        while True:
+            result = cls.get_task_result(task_id)
+            if result.state == _STATE_DONE:
+                logger.info(f"✅ MinerU 任务完成: {task_id}")
+                return result
+            if result.state == _STATE_FAILED:
+                logger.error(f"❌ MinerU 任务失败: {task_id}: {result.err_msg}")
+                return result
+            if result.state == "running" and result.total_pages:
+                logger.info(
+                    f"MinerU 解析中: {task_id} "
+                    f"已解析 {result.extracted_pages or 0}/{result.total_pages} 页"
+                )
+            else:
+                logger.debug(f"MinerU 任务状态: {task_id} -> {result.state}")
+            if time.monotonic() >= deadline:
+                raise MinerUError(
+                    f"等待任务 {task_id} 超时（{max_wait} 秒），"
+                    f"最后状态: {result.state}"
+                )
+            time.sleep(interval)
+
+    @classmethod
+    def wait_for_batch(
+        cls,
+        batch_id: str,
+        *,
+        expected_count: int | None = None,
+        poll_interval: float | None = None,
+        timeout: int | None = None,
+    ) -> list[BatchTaskResult]:
+        """轮询等待批量任务全部到达终态
+
+        Args:
+            batch_id: 批次 ID
+            expected_count: 期望的文件数量。官方在文件上传后才会自动创建任务，
+                查询过早时结果列表可能不完整；传入该值可确保全部任务出现且
+                到达终态后才返回（parse_files 会自动传入）
+            poll_interval: 轮询间隔秒数，None 时使用 MINERU_POLL_INTERVAL
+            timeout: 总等待秒数，None 时使用 MINERU_MAX_WAIT
+
+        Returns:
+            list[BatchTaskResult]: 批次内全部文件的终态结果
+
+        Raises:
+            MinerUError: 超过总等待时间仍未全部到达终态
+
+        Example:
+            >>> results = MinerUKit.wait_for_batch(info.batch_id, expected_count=2)
+        """
+        settings = get_settings()
+        interval = (
+            poll_interval
+            if poll_interval is not None
+            else settings.MINERU_POLL_INTERVAL
+        )
+        max_wait = timeout if timeout is not None else settings.MINERU_MAX_WAIT
+        deadline = time.monotonic() + max_wait
+        while True:
+            results = cls.get_batch_results(batch_id)
+            all_terminal = bool(results) and all(
+                r.state in (_STATE_DONE, _STATE_FAILED) for r in results
+            )
+            count_ok = expected_count is None or len(results) >= expected_count
+            if all_terminal and count_ok:
+                done = sum(1 for r in results if r.state == _STATE_DONE)
+                failed = sum(1 for r in results if r.state == _STATE_FAILED)
+                logger.info(
+                    f"✅ MinerU 批量任务完成: batch_id={batch_id}，"
+                    f"成功 {done} 个，失败 {failed} 个"
+                )
+                return results
+            if time.monotonic() >= deadline:
+                raise MinerUError(
+                    f"等待批量任务 {batch_id} 超时（{max_wait} 秒），"
+                    f"当前可见 {len(results)} 个任务"
+                )
+            logger.debug(
+                f"MinerU 批量任务进行中: batch_id={batch_id}，"
+                f"当前可见 {len(results)} 个任务"
+            )
+            time.sleep(interval)
+
+    @classmethod
+    def parse_url(
+        cls,
+        url: str,
+        *,
+        model_version: str | None = None,
+        is_ocr: bool | None = None,
+        enable_formula: bool | None = None,
+        enable_table: bool | None = None,
+        language: str | None = None,
+        data_id: str | None = None,
+        extra_formats: list[str] | None = None,
+        page_ranges: str | None = None,
+        no_cache: bool | None = None,
+        cache_tolerance: int | None = None,
+        poll_interval: float | None = None,
+        timeout: int | None = None,
+    ) -> TaskResult:
+        """解析公网 URL 文件（提交 + 轮询一步到位）
+
+        create_task 与 wait_for_task 的组合封装，参数含义见二者 docstring
+        （callback / seed 回调相关参数不参与本方法，如需回调请使用低层方法）。
+
+        Args:
+            url: 文件 URL
+            model_version: 模型版本（HTML 文件须指定 MinerU-HTML）
+            is_ocr: 是否启用 OCR
+            enable_formula: 是否开启公式识别
+            enable_table: 是否开启表格识别
+            language: 文档语言
+            data_id: 业务数据 ID
+            extra_formats: 附加导出格式（docx/html/latex）
+            page_ranges: 页码范围
+            no_cache: 是否绕过缓存
+            cache_tolerance: 缓存容忍时间（秒）
+            poll_interval: 轮询间隔秒数
+            timeout: 轮询总超时秒数
+
+        Returns:
+            TaskResult: 终态结果（state=done 时含 full_zip_url）
+
+        Raises:
+            MinerUError: 未配置 Token / 网络失败 / 轮询超时
+
+        Example:
+            >>> result = MinerUKit.parse_url(
+            ...     "https://cdn-mineru.openxlab.org.cn/demo/example.pdf",
+            ...     model_version="vlm",
+            ... )
+            >>> print(result.state, result.full_zip_url)
+        """
+        task_id = cls.create_task(
+            url,
+            model_version=model_version,
+            is_ocr=is_ocr,
+            enable_formula=enable_formula,
+            enable_table=enable_table,
+            language=language,
+            data_id=data_id,
+            extra_formats=extra_formats,
+            page_ranges=page_ranges,
+            no_cache=no_cache,
+            cache_tolerance=cache_tolerance,
+        )
+        return cls.wait_for_task(task_id, poll_interval=poll_interval, timeout=timeout)
+
+    @classmethod
+    def parse_files(
+        cls,
+        file_paths: list[str | Path],
+        *,
+        model_version: str | None = None,
+        is_ocr: bool | None = None,
+        enable_formula: bool | None = None,
+        enable_table: bool | None = None,
+        language: str | None = None,
+        page_ranges: str | None = None,
+        extra_formats: list[str] | None = None,
+        poll_interval: float | None = None,
+        timeout: int | None = None,
+    ) -> list[BatchTaskResult]:
+        """解析本地文件（申请链接 + 上传 + 轮询一步到位）
+
+        create_batch + upload_files + wait_for_batch 的组合封装。
+        每个文件共享相同的解析参数（页码范围等）；如需每个文件独立参数，
+        请使用低层方法自行组合。
+
+        Args:
+            file_paths: 本地文件路径列表（1~50 个，每个 ≤200MB）
+            model_version: 模型版本（HTML 文件须指定 MinerU-HTML）
+            is_ocr: 是否启用 OCR（全部文件共享）
+            enable_formula: 是否开启公式识别
+            enable_table: 是否开启表格识别
+            language: 文档语言
+            page_ranges: 页码范围（全部文件共享）
+            extra_formats: 附加导出格式（docx/html/latex）
+            poll_interval: 轮询间隔秒数
+            timeout: 轮询总超时秒数
+
+        Returns:
+            list[BatchTaskResult]: 全部文件的终态结果（按 file_name 关联）
+
+        Raises:
+            ValueError: 文件数量 / 格式 / 大小不符合官方限制
+            FileNotFoundError: 文件不存在
+            MinerUError: 未配置 Token / 网络失败 / 轮询超时
+
+        Example:
+            >>> results = MinerUKit.parse_files(
+            ...     ["a.pdf", "b.docx"], model_version="vlm"
+            ... )
+            >>> for r in results:
+            ...     print(r.file_name, r.state, r.full_zip_url)
+        """
+        files = [
+            BatchFile(name=Path(p).name, is_ocr=is_ocr, page_ranges=page_ranges)
+            for p in file_paths
+        ]
+        info = cls.create_batch(
+            files,
+            model_version=model_version,
+            enable_formula=enable_formula,
+            enable_table=enable_table,
+            language=language,
+            extra_formats=extra_formats,
+        )
+        cls.upload_files(file_paths, info.file_urls)
+        return cls.wait_for_batch(
+            info.batch_id,
+            expected_count=len(files),
+            poll_interval=poll_interval,
+            timeout=timeout,
+        )
+
+    @staticmethod
+    def download_zip(zip_url: str, dest_dir: str | Path) -> str:
+        """下载解析结果压缩包到本地
+
+        结果 zip 内含 Markdown / JSON（可选 docx/html/latex），文件结构说明见
+        https://opendatalab.github.io/MinerU/reference/output_files/
+
+        Args:
+            zip_url: 结果压缩包地址（full_zip_url）
+            dest_dir: 目标目录（不存在时自动创建），文件名为 task_id.zip 或
+                从 URL 推断
+
+        Returns:
+            str: 保存的本地文件绝对路径
+
+        Raises:
+            MinerUError: 网络失败或 HTTP 非 200
+
+        Example:
+            >>> MinerUKit.download_zip(result.full_zip_url, "./output")
+        """
+        dest = Path(dest_dir)
+        dest.mkdir(parents=True, exist_ok=True)
+        filename = zip_url.rstrip("/").split("/")[-1] or "mineru_result.zip"
+        if not filename.endswith(".zip"):
+            filename = f"{filename}.zip"
+        target = (dest / filename).resolve()
+        timeout = get_settings().MINERU_TIMEOUT
+        logger.info(f"下载 MinerU 结果包: {zip_url}")
+        try:
+            resp = requests.get(zip_url, timeout=timeout, stream=True)
+        except requests.RequestException as e:
+            logger.error(f"下载失败: {e}")
+            raise MinerUError(f"结果包下载失败: {e}") from e
+        if resp.status_code != 200:
+            raise MinerUError(f"结果包下载失败: HTTP {resp.status_code}")
+        with open(target, "wb") as f:
+            for chunk in resp.iter_content(chunk_size=1024 * 1024):
+                if chunk:
+                    f.write(chunk)
+        logger.info(f"✅ 结果包已保存: {target}（{target.stat().st_size} 字节）")
+        return str(target)
+
+    # ------------------------------------------------------------------
+    # 校验辅助
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def is_supported(file_path: str | Path) -> bool:
+        """检查文件格式是否受支持（依据扩展名）
+
+        Args:
+            file_path: 文件路径或文件名
+
+        Returns:
+            bool: 扩展名在支持列表中返回 True
+
+        Example:
+            >>> MinerUKit.is_supported("report.pdf")
+            True
+        """
+        return Path(file_path).suffix.lower() in MinerUKit.SUPPORTED_EXTENSIONS