deepdoc-lib 0.2.2__tar.gz → 0.2.5__tar.gz

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/.env.example

@@ -29,7 +29,7 @@ DEEPDOC_VISION_BASE_URL=
 # openai    - OpenAI GPT-4 Vision
 # qwen      - 阿里云通义千问
 # zhipu     - 智谱AI
-# gemini    - Google Gemini
+# gemini    - Google Gemini (需安装: pip install deepdoc-lib[gemini])
 # ollama    - 本地 Ollama 服务
 # anthropic - Anthropic Claude (需额外配置)
 DEEPDOC_VISION_PROVIDER=qwen

deepdoc_lib-0.2.5/.github/workflows/ci.yml

@@ -0,0 +1,105 @@
+name: Tests
+
+on:
+    push:
+    pull_request:
+    workflow_dispatch:
+
+jobs:
+    pytest:
+        name: Pytest (${{ matrix.python-version }})
+        runs-on: ubuntu-latest
+        strategy:
+            matrix:
+                python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: ${{ matrix.python-version }}
+                  cache: "pip"
+
+            # Install without extras so the suite proves the default install
+            # imports and works without optional SDKs such as google-genai.
+            - name: Install dependencies
+              run: |
+                  python -m pip install --upgrade pip
+                  python -m pip install -e . pytest
+
+            - name: Resolve the built wheel with current PyJWT
+              run: |
+                  python -m pip install build
+                  python -m build --wheel
+                  python -m pip install --dry-run --ignore-installed dist/*.whl 'PyJWT[crypto]>=2.15.1,<3'
+
+            - name: Resolve the built wheel with protobuf 6
+              run: |
+                  wheel=$(ls dist/*.whl)
+                  python -m pip install --dry-run --ignore-installed "$wheel" 'protobuf>=6.31,<7'
+                  python -m pip install --dry-run --ignore-installed "${wheel}[gemini]" 'protobuf>=6.31,<7'
+
+            # Preprovision immutable official data instead of asking the NLTK
+            # downloader to traverse the runner's proxy. Do not disable pathsec.
+            - name: Check out pinned NLTK test resources
+              uses: actions/checkout@v4
+              with:
+                  repository: nltk/nltk_data
+                  ref: 550b6625bcef1f2abff2ff770a5a0d272c9c6b2a
+                  path: .ci-nltk-data
+                  persist-credentials: false
+                  sparse-checkout-cone-mode: false
+                  sparse-checkout: |
+                      packages/tokenizers/punkt.zip
+                      packages/tokenizers/punkt_tab.zip
+                      packages/corpora/wordnet.zip
+                      packages/taggers/averaged_perceptron_tagger.zip
+                      packages/taggers/averaged_perceptron_tagger_eng.zip
+
+            - name: Prepare and validate offline NLTK test resources
+              env:
+                  DEEPDOC_NLTK_DATA_DIR: ${{ runner.temp }}/deepdoc-nltk-data
+                  NLTK_DATA: ${{ runner.temp }}/deepdoc-nltk-data
+              run: |
+                  for package in tokenizers/punkt tokenizers/punkt_tab corpora/wordnet \
+                      taggers/averaged_perceptron_tagger taggers/averaged_perceptron_tagger_eng; do
+                      python -m zipfile -e ".ci-nltk-data/packages/$package.zip" "$NLTK_DATA/$(dirname "$package")"
+                  done
+                  python -c 'from deepdoc.depend.nltk_manager import ensure_nltk_data; ensure_nltk_data(offline=True)'
+
+            - name: Run tests
+              env:
+                  DEEPDOC_NLTK_DATA_DIR: ${{ runner.temp }}/deepdoc-nltk-data
+                  NLTK_DATA: ${{ runner.temp }}/deepdoc-nltk-data
+              run: python -m pytest tests
+
+            - name: Test Gemini with the latest google-genai
+              run: |
+                  python -m pip install -e ".[gemini]"
+                  python -m pytest tests/test_gemini_sdk_compatibility.py
+
+    minimum-sdk:
+        name: Minimum SDK contract (3.10)
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.10"
+                  cache: "pip"
+
+            - name: Build and resolve the wheel with the minimum SDKs and current PyJWT
+              run: |
+                  python -m pip install --upgrade pip build
+                  python -m build --wheel
+                  python -m pip install --dry-run --ignore-installed dist/*.whl 'zai-sdk==0.0.4' 'google-genai==1.0.0' 'PyJWT[crypto]>=2.15.1,<3'
+
+            - name: Install and test the minimum SDK contracts
+              run: |
+                  python -m pip install dist/*.whl 'zai-sdk==0.0.4' 'google-genai==1.0.0' 'PyJWT[crypto]>=2.15.1,<3' pytest
+                  python -m pip check
+                  python -m pytest tests/test_zhipu_sdk_compatibility.py tests/test_gemini_sdk_compatibility.py

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc_lib
-Version: 0.2.2
+Version: 0.2.5
 Summary: [RAGFlow](https://ragflow.io/) is an open-source RAG (Retrieval-Augmented Generation) engine based on deep document understanding. It offers a streamlined RAG workflow for businesses of any scale, combining LLM (Large Language Models) to provide truthful question-answering capabilities, backed by well-founded citations from various complex formatted data.
 Author-email: Zhichang Yu <yuzhichang@gmail.com>
 Requires-Python: <3.14,>=3.10
@@ -42,14 +42,15 @@ Requires-Dist: tencentcloud-sdk-python>=3.0.1215
 Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: xgboost<3.0.0,>=2.1.0
 Requires-Dist: xpinyin>=0.7.6
-Requires-Dist: zhipuai>=2.0.1
-Requires-Dist: google-generativeai<0.9.0,>=0.8.1
+Requires-Dist: zai-sdk>=0.0.4
 Requires-Dist: trio>=0.29.0
 Requires-Dist: setuptools<76.0.0,>=75.2.0
 Requires-Dist: huggingface-hub<1.0.0,>=0.25.0
 Provides-Extra: gpu
 Requires-Dist: onnxruntime-gpu>=1.19.2; (sys_platform != "darwin" and platform_machine == "x86_64") and extra == "gpu"
 Requires-Dist: torch; extra == "gpu"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0.0; extra == "gemini"
 Dynamic: license-file
 
 # Deepdoc
@@ -68,6 +69,12 @@ GPU (Linux x86_64 only):
 pip install deepdoc-lib[gpu]
 ```
 
+Gemini vision provider (optional, installs the `google-genai` SDK):
+
+```bash
+pip install deepdoc-lib[gemini]
+```
+
 Note: `onnxruntime` (CPU) and `onnxruntime-gpu` should not be installed together. If you're switching an existing environment to GPU, uninstall CPU ORT first:
 
 ```bash
@@ -222,6 +229,8 @@ vision_model = create_vision_model("qwen")
 
 Supported providers: ["openai", "qwen", "zhipu", "ollama", "gemini", "anthropic"]
 
+The `gemini` provider needs the `gemini` extra: `pip install deepdoc-lib[gemini]`.
+
 - Use Configuration File
 
 Create `deepdoc_config.yaml`:

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/README.md

@@ -14,6 +14,12 @@ GPU (Linux x86_64 only):
 pip install deepdoc-lib[gpu]
 ```
 
+Gemini vision provider (optional, installs the `google-genai` SDK):
+
+```bash
+pip install deepdoc-lib[gemini]
+```
+
 Note: `onnxruntime` (CPU) and `onnxruntime-gpu` should not be installed together. If you're switching an existing environment to GPU, uninstall CPU ORT first:
 
 ```bash
@@ -168,6 +174,8 @@ vision_model = create_vision_model("qwen")
 
 Supported providers: ["openai", "qwen", "zhipu", "ollama", "gemini", "anthropic"]
 
+The `gemini` provider needs the `gemini` extra: `pip install deepdoc-lib[gemini]`.
+
 - Use Configuration File
 
 Create `deepdoc_config.yaml`:

deepdoc_lib-0.2.5/UPSTREAM_SYNC.md

@@ -0,0 +1,86 @@
+# Upstream Sync Record
+
+This library is a standalone, pip-installable extraction of the `deepdoc/`
+module from [infiniflow/ragflow](https://github.com/infiniflow/ragflow),
+restructured around explicit configuration injection
+(`PdfModelConfig` / `TokenizerConfig`, `DEEPDOC_*` env vars) and
+ModelScope-based model distribution instead of ragflow's global settings and
+HuggingFace runtime downloads.
+
+Upstream changes are **ported by behavior, never by wholesale file copy**,
+so the library's public API (`from deepdoc import PdfParser, ...`) and
+packaging stay stable.
+
+## Sync history
+
+### 2026-07-23 — synced to ragflow `18ea0fb7` (2026-07-22)
+
+Ported fixes (upstream PR references):
+
+| Area | Fix | Upstream |
+|---|---|---|
+| vision/operators | `StandardizeImag` → `StandardizeImage` rename; the dynamic `getattr(operators, "StandardizeImage")` dispatch silently skipped image standardization before | [#16785](https://github.com/infiniflow/ragflow/pull/16785) |
+| mineru/tcadp | zip extraction hardening: reject symlink / encrypted / absolute-path / `..`-traversal / zip-slip entries; streaming download for TCADP results | [#12527](https://github.com/infiniflow/ragflow/pull/12527) |
+| html_parser | parse bodyless HTML fragments (`soup.body or soup`) | [#16423](https://github.com/infiniflow/ragflow/pull/16423) |
+| html_parser | switch `html5lib` → `html.parser` (aligns with upstream #14486-era behavior the later fixes assume) | [#14486](https://github.com/infiniflow/ragflow/pull/14486) |
+| html_parser | h4 heading mapping `#####` → `####` | [#13833](https://github.com/infiniflow/ragflow/pull/13833) |
+| html_parser | oversized-block splitting preserves original text (CJK-aware atom splitting) | [#16052](https://github.com/infiniflow/ragflow/pull/16052) |
+| excel_parser | keep `0` / `False` cells; skip fully-empty rows | [#16287](https://github.com/infiniflow/ragflow/pull/16287) |
+| excel_parser | no spurious header-only chunk when data rows are an exact multiple of `chunk_rows` | [#15490](https://github.com/infiniflow/ragflow/pull/15490) |
+| excel_parser | binary-search actual row count for sheets with abnormal `max_row` | [#13018](https://github.com/infiniflow/ragflow/pull/13018) |
+| markdown_parser | full sync to upstream state: protected ranges (fenced code / MD tables / HTML tables) never split by delimiters; GFM separators with 1+ dashes; lone-header attachment | #10896 #11018 #11520 #13892 #15630 #15632 #16109 #16319 |
+| ppt_parser | cached, None-safe shape sorting (group shapes with `top=None` no longer crash) | [#13054](https://github.com/infiniflow/ragflow/pull/13054) |
+| parser/utils | `get_text`: `if binary:` → `if binary is not None:` | [#13196](https://github.com/infiniflow/ragflow/pull/13196) |
+| table_structure_recognizer | English caption patterns (`Figure N` / `Table N` / `Fig. N`) | [#15481](https://github.com/infiniflow/ragflow/pull/15481) |
+| vision/ocr | env-configurable ONNX thread counts (`OCR_INTRA_OP_NUM_THREADS` / `OCR_INTER_OP_NUM_THREADS`) and opt-in GPU arena shrinkage (`OCR_GPUMEM_ARENA_SHRINKAGE=1`) | [#12777](https://github.com/infiniflow/ragflow/pull/12777) |
+| layout_recognizer | figure/equation placeholder boxes get per-type layoutno namespaces (`figure-N` / `equation-N`), preventing unrelated figure and equation crops from merging on scientific PDFs | [#15873](https://github.com/infiniflow/ragflow/pull/15873) |
+| layout_recognizer | re-enable CID-pattern garbage filter for text boxes | [#13404](https://github.com/infiniflow/ragflow/pull/13404) |
+| pdf_parser | garbled-text detection → OCR fallback (PUA/CID chars, subset-font encoding garbling, OCR-alphabet coverage check) | [#13404](https://github.com/infiniflow/ragflow/pull/13404) |
+| pdf_parser | geometry-based word-space recovery, CJK-aware (`_insert_word_spaces`) | [#16958](https://github.com/infiniflow/ragflow/pull/16958) |
+| pdf_parser | remove 299-page hardcoded limit (`MAXIMUM_PAGE_NUMBER = 100000`) | [#14382](https://github.com/infiniflow/ragflow/pull/14382) |
+| pdf_parser | chunked `parse_into_bboxes` for large PDFs (`PDF_PARSER_PAGE_BATCH_SIZE`, default 50) with window→global box remapping; lazy `img_np` in `__ocr` | [#14385](https://github.com/infiniflow/ragflow/pull/14385) |
+| pdf_parser | out-of-range page-index guards in `cropout` / table-figure insertion | [#12938](https://github.com/infiniflow/ragflow/pull/12938) [#12848](https://github.com/infiniflow/ragflow/pull/12848) |
+| pdf_parser (VisionParser) | `pdf_page_num = from_page + idx` (page numbering was wrong when `from_page > 0`); fixed broken relative import of `llm_adapter` | [#12938](https://github.com/infiniflow/ragflow/pull/12938) + fork-local fix |
+| parser (new) | EPUB parser (spine-order XHTML extraction, delegates to HtmlParser), exported as `deepdoc.EpubParser` | [#13650](https://github.com/infiniflow/ragflow/pull/13650) |
+
+Already present before this sync (no action needed): `ast.literal_eval`
+security fix (#12236), XLS/calamine loading (#10660), chartsheet guards
+(#10819), KMeans multi-column detection (#11415 + #12534 cleanup),
+`is_english` regex fix (#11432), OCR GPU memory limit env (#10407),
+`vision_figure_parser_docx_wrapper` guard (#12104).
+
+**Deliberately NOT ported** (decisions):
+
+- **Go + HTTP microservice pipeline** (#16323, `deepdoc/server/`, `DEEPDOC_URL`
+  DLA client): conflicts with this library's pure-Python, in-process design.
+- **Automatic table orientation detection/rotation** (#12719 feature +
+  #12981 / #17016 follow-ups): feature not in our baseline; runs 4× OCR per
+  table; adopt separately if ever needed.
+- **`rag.utils.lazy_image` memory refactors** (docx/excel lazy image loading,
+  #13329 / #13558): optimization only; deferred until vendoring lazy_image is
+  justified.
+- **3-tuple outlines** (`extract_pdf_outlines` returning
+  `(title, depth, page)`, #10456 TOC feature): our `outlines` stays
+  `(title, depth)` to avoid breaking downstream consumers.
+- **`model_speciess` → `model_species` rename** (#13929): our attribute name
+  is part of the public surface; renaming would break existing callers.
+- **paddleocr / opendataloader / somark parsers**: cloud-API clients, not
+  currently needed; revisit on demand.
+- **MinerU feature evolution** (API-only backends, VLM descriptions, etc.):
+  only the security fix was taken; feature sync deferred until MinerU usage
+  is confirmed.
+- **Pure refactors** (moving functions between ragflow modules, lefthook
+  reformatting): not applicable to our layout.
+
+Regression tests: `tests/test_upstream_sync_regressions.py`.
+
+## How to run the next sync
+
+```bash
+# in a ragflow clone
+git log --reverse --format="%h %ad %s" --date=short 18ea0fb7..origin/main -- deepdoc
+```
+
+Then for each commit: understand the behavior change, find the corresponding
+code in this repo, and re-implement it in this library's style (config
+injection, relative imports, vendored `common/` + `depend/`). Update this file.

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/deepdoc/__init__.py

@@ -27,6 +27,7 @@ __all__ = [
     "PlainParser",
     "DocxParser",
     "DoclingParser",
+    "EpubParser",
     "ExcelParser",
     "PptParser",
     "HtmlParser",

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/deepdoc/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.5'
+__version_tuple__ = version_tuple = (0, 2, 5)
 
-__commit_id__ = commit_id = 'g2c122018a'
+__commit_id__ = commit_id = 'g8ef70a65b'

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/deepdoc/depend/simple_cv_model.py

@@ -11,7 +11,7 @@ import requests
 from openai import OpenAI
 from openai.lib.azure import AzureOpenAI
 from PIL import Image
-from zhipuai import ZhipuAI
+from zai import ZhipuAiClient
 
 # 可选导入 ollama
 try:
@@ -162,7 +162,12 @@ class Zhipu4V(Base):
 
     def __init__(self, key, model_name="glm-4v", lang="Chinese", **kwargs):
         super().__init__(key, model_name, lang)
-        self.client = ZhipuAI(api_key=key)
+        # Preserve the legacy override and China default instead of allowing
+        # the maintained SDK's ZAI_BASE_URL to redirect this provider adapter.
+        self.client = ZhipuAiClient(
+            api_key=key,
+            base_url=kwargs.get("base_url") or os.getenv("ZHIPUAI_BASE_URL") or "https://open.bigmodel.cn/api/paas/v4/",
+        )
 
     def describe_with_prompt(self, image, prompt=None):
         """使用智谱AI视觉模型描述图片"""
@@ -301,9 +306,16 @@ class GeminiCV(Base):
 
     def __init__(self, key, model_name="gemini-pro-vision", lang="Chinese", **kwargs):
         super().__init__(key, model_name, lang)
-        import google.generativeai as genai
-        genai.configure(api_key=key)
-        self.model = genai.GenerativeModel(model_name)
+        # The legacy google-generativeai SDK caps protobuf below 6, so Gemini
+        # uses the maintained google-genai SDK as an optional extra instead.
+        try:
+            from google import genai
+        except ImportError as e:
+            raise ImportError(
+                "Gemini vision requires the google-genai package. "
+                "Install it with: pip install 'deepdoc-lib[gemini]'"
+            ) from e
+        self.client = genai.Client(api_key=key)
 
     def describe_with_prompt(self, image, prompt=None):
         """使用Google Gemini模型描述图片"""
@@ -318,11 +330,19 @@ class GeminiCV(Base):
             
             pil_image = Image.open(BytesIO(img_data))
             
-            response = self.model.generate_content([
-                prompt or self.prompt(image),
-                pil_image
-            ])
+            response = self.client.models.generate_content(
+                model=self.model_name,
+                contents=[prompt or self.prompt(image), pil_image],
+            )
 
+            # google-genai returns None (the legacy SDK raised) when the
+            # response has no text, e.g. a safety block; keep the error path.
+            # A block can be reported on the prompt or on the candidate.
+            if response.text is None:
+                candidates = response.candidates or []
+                finish_reason = candidates[0].finish_reason if candidates else None
+                finish_reason = getattr(finish_reason, "name", finish_reason)
+                raise ValueError(f"Gemini returned no text (finish_reason={finish_reason}, prompt_feedback={response.prompt_feedback})")
             return response.text.strip()
         except Exception as e:
             return "**ERROR**: " + str(e)
@@ -466,4 +486,4 @@ def create_vision_model(config=None):
         return VisionModelFactory.create_model(config)
     
     else:
-        raise ValueError(f"不支持的配置类型: {type(config)}")
+        raise ValueError(f"不支持的配置类型: {type(config)}")

{deepdoc_lib-0.2.2 → deepdoc_lib-0.2.5}/deepdoc/parser/__init__.py

@@ -16,6 +16,7 @@
 
 from .docx_parser import RAGFlowDocxParser as DocxParser
 from .docling_parser import DoclingParser
+from .epub_parser import RAGFlowEpubParser as EpubParser
 from .excel_parser import RAGFlowExcelParser as ExcelParser
 from .html_parser import RAGFlowHtmlParser as HtmlParser
 from .json_parser import RAGFlowJsonParser as JsonParser
@@ -31,6 +32,7 @@ __all__ = [
     "PlainParser",
     "DocxParser",
     "DoclingParser",
+    "EpubParser",
     "ExcelParser",
     "PptParser",
     "HtmlParser",

deepdoc_lib-0.2.5/deepdoc/parser/epub_parser.py

@@ -0,0 +1,139 @@
+#
+#  Copyright 2025 The InfiniFlow Authors. 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.
+#
+
+import logging
+import warnings
+import zipfile
+from io import BytesIO
+from xml.etree import ElementTree
+
+from ..config import TokenizerConfig
+from .html_parser import RAGFlowHtmlParser
+
+# OPF XML namespaces
+_OPF_NS = "http://www.idpf.org/2007/opf"
+_CONTAINER_NS = "urn:oasis:names:tc:opendocument:xmlns:container"
+
+# Media types that contain readable XHTML content
+_XHTML_MEDIA_TYPES = {"application/xhtml+xml", "text/html", "text/xml"}
+
+logger = logging.getLogger(__name__)
+
+
+class RAGFlowEpubParser:
+    """Parse EPUB files by extracting XHTML content in spine (reading) order
+    and delegating to RAGFlowHtmlParser for chunking."""
+
+    def __init__(self, tokenizer_cfg: TokenizerConfig | None = None):
+        self.html_parser = RAGFlowHtmlParser(tokenizer_cfg=tokenizer_cfg)
+
+    def __call__(self, fnm, binary=None, chunk_token_num=512):
+        if binary is not None:
+            if not binary:
+                logger.warning(
+                    "RAGFlowEpubParser received an empty EPUB binary payload for %r",
+                    fnm,
+                )
+                raise ValueError("Empty EPUB binary payload")
+            zf = zipfile.ZipFile(BytesIO(binary))
+        else:
+            zf = zipfile.ZipFile(fnm)
+
+        try:
+            content_items = self._get_spine_items(zf)
+            all_sections = []
+
+            for item_path in content_items:
+                try:
+                    html_bytes = zf.read(item_path)
+                except KeyError:
+                    continue
+                if not html_bytes:
+                    logger.debug("Skipping empty EPUB content item: %s", item_path)
+                    continue
+                with warnings.catch_warnings():
+                    warnings.filterwarnings("ignore", category=UserWarning)
+                    sections = self.html_parser(item_path, binary=html_bytes, chunk_token_num=chunk_token_num)
+                all_sections.extend(sections)
+
+            return all_sections
+        finally:
+            zf.close()
+
+    @staticmethod
+    def _get_spine_items(zf):
+        """Return content file paths in spine (reading) order."""
+        # 1. Find the OPF file path from META-INF/container.xml
+        try:
+            container_xml = zf.read("META-INF/container.xml")
+        except KeyError:
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        try:
+            container_root = ElementTree.fromstring(container_xml)
+        except ElementTree.ParseError:
+            logger.warning("Failed to parse META-INF/container.xml; falling back to XHTML order.")
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        rootfile_el = container_root.find(f".//{{{_CONTAINER_NS}}}rootfile")
+        if rootfile_el is None:
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        opf_path = rootfile_el.get("full-path", "")
+        if not opf_path:
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        # Base directory of the OPF file (content paths are relative to it)
+        opf_dir = opf_path.rsplit("/", 1)[0] + "/" if "/" in opf_path else ""
+
+        # 2. Parse the OPF file
+        try:
+            opf_xml = zf.read(opf_path)
+        except KeyError:
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        try:
+            opf_root = ElementTree.fromstring(opf_xml)
+        except ElementTree.ParseError:
+            logger.warning("Failed to parse OPF file '%s'; falling back to XHTML order.", opf_path)
+            return RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+        # 3. Build id->href+mediatype map from <manifest>
+        manifest = {}
+        for item in opf_root.findall(f".//{{{_OPF_NS}}}item"):
+            item_id = item.get("id", "")
+            href = item.get("href", "")
+            media_type = item.get("media-type", "")
+            if item_id and href:
+                manifest[item_id] = (href, media_type)
+
+        # 4. Walk <spine> to get reading order
+        spine_items = []
+        for itemref in opf_root.findall(f".//{{{_OPF_NS}}}itemref"):
+            idref = itemref.get("idref", "")
+            if idref not in manifest:
+                continue
+            href, media_type = manifest[idref]
+            if media_type not in _XHTML_MEDIA_TYPES:
+                continue
+            spine_items.append(opf_dir + href)
+
+        return spine_items if spine_items else RAGFlowEpubParser._fallback_xhtml_order(zf)
+
+    @staticmethod
+    def _fallback_xhtml_order(zf):
+        """Fallback: return all .xhtml/.html files sorted alphabetically."""
+        return sorted(n for n in zf.namelist() if n.lower().endswith((".xhtml", ".html", ".htm")) and not n.startswith("META-INF/"))