foxclaw 0.1.0 → 0.1.2

package/python/vendor/hkc/hkc_kde/kde.py

@@ -0,0 +1,298 @@
+"""
+hkc-kde / kde.py
+Knowledge Digest Engine 主引擎。
+
+完整 Pipeline：
+文件 / URL
+  → Stage 1: Loader（解析原始格式）
+  → Stage 2: Chunker（分块）+ Extractor（LLM 提取）
+  → Stage 3: RelationshipDiscovery（关系发现）
+  → Stage 4: Packager（写入 GraphStore，发布事件）
+"""
+# TODO: Replace with proper package install before v1 release
+
+import hashlib
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from hkc_core.graph.base import GraphStore
+from hkc_core.utils.id_gen import IDGenerator
+from hkc_kep.event_bus import EventBus
+
+from .models import ParsedDocument
+from .chunker import Chunker, MAX_CHARS, OVERLAP_CHARS
+
+# 单文档最多处理的 chunk 数(防止误传超大文件导致数小时的 LLM 调用与不可控账单)。
+#
+# 为什么是 800:按实际步长(MAX_CHARS - OVERLAP_CHARS = 1568 字符/段)折算,
+# 800 段约覆盖 125 万字符,足以吞下一本普通电子书/一份长文档;按 batch=4、
+# 并发 8 的实测口径约 1.3 小时、几元成本,属于"能跑完、看得见进度、账单可控"的
+# 折中。而上传上限 20MB(约 700 万字符 ≈ 4400 段 ≈ 7 小时)远超这个量级,
+# 若把上限调到 0(不限制),一次误传就会在后台连续跑大半天并持续产生费用,
+# 中途既看不到头也无法回退,因此默认不给"全量跑完"的权限。
+#
+# 可经环境变量 HKC_MAX_CHUNKS_PER_DOC 覆盖:设 0 或负数 = 不限制(完整摄入整本书)。
+# 真需要整本摄入时再显式放开,并自行承担耗时与费用。
+# 注意:超出上限只处理前 N 段,而整文件内容哈希已入库,同一文件重传会被去重拦截,
+# 想补齐剩余部分必须先把文件拆分成多份再分别上传。
+DEFAULT_MAX_CHUNKS_PER_DOC = 800
+
+
+class DuplicateDocumentError(Exception):
+    """同一内容已摄入（内容 SHA-256 命中），拒绝重复摄入。"""
+    pass
+
+
+def content_hash_of(data: bytes) -> str:
+    """计算内容 SHA-256 指纹，作为文档精确去重身份。"""
+    return hashlib.sha256(data).hexdigest()
+
+
+def _max_chunks_per_doc() -> int:
+    """运行时读取单文档 chunk 上限(可经 HKC_MAX_CHUNKS_PER_DOC 覆盖)。<=0 表示不限制。"""
+    raw = os.environ.get("HKC_MAX_CHUNKS_PER_DOC", "").strip()
+    if not raw:
+        return DEFAULT_MAX_CHUNKS_PER_DOC
+    try:
+        return int(raw)
+    except ValueError:
+        return DEFAULT_MAX_CHUNKS_PER_DOC
+from .extractor import Extractor
+from .packager import KUPackager
+from .loaders.text_loader import MarkdownLoader, TxtLoader
+from .loaders.web_loader import WebLoader
+
+logger = logging.getLogger(__name__)
+
+
+class KnowledgeDigestEngine:
+
+    def __init__(
+        self,
+        graph_store: GraphStore,
+        event_bus:   EventBus,
+        id_gen:      IDGenerator,
+        api_key:     Optional[str] = None,
+        model:       Optional[str] = None,
+        provider:    str           = "anthropic",
+        base_url:    Optional[str] = None,
+    ):
+        self.store     = graph_store
+        self.bus       = event_bus
+        self.id_gen    = id_gen
+        self.chunker   = Chunker()
+        self.extractor = Extractor(api_key=api_key, model=model, provider=provider, base_url=base_url)
+        self.packager  = KUPackager(graph_store, event_bus, id_gen)
+
+    # ── 公开接口 ─────────────────────────────────────────────
+
+    def ingest_file(
+        self,
+        path:         str,
+        source_title: str = "",
+        source_year:  int = 0,
+        domain:       str = "",
+        source:       str = "",
+        collection:   str = "",
+        progress_cb=None,
+    ) -> list:
+        """
+        摄入本地文件。
+        支持：.pdf / .md / .markdown / .txt / .epub / .mobi / .azw3 / .docx / .xlsx
+        返回写入的 KU 列表。
+
+        source: 有意义的来源标识(如原始上传文件名)。留空时回退到文件路径。
+                上传场景下 path 是临时盘路径,必须传 source 覆盖,否则
+                Evidence 的来源会变成临时路径(可追溯链 KU←Evidence 失真)。
+        progress_cb: 可选 (processed,total)->None,逐 chunk 上报抽取进度(异步摄入用)。
+        """
+        path   = Path(path)
+        suffix = path.suffix.lower()
+
+        # 方向一：入口精确哈希查重。同一文件（内容 SHA-256 相同）重复上传直接拒绝，
+        # 不让它流到知识级去重（否则会重复建 Evidence 再靠 KEE 合并，触发大量关系重定向）。
+        content_hash = content_hash_of(path.read_bytes())
+        if self.find_evidence_by_content_hash(content_hash):
+            raise DuplicateDocumentError(
+                f"文件内容已摄入过（指纹 {content_hash[:12]}），请勿重复上传"
+            )
+
+        if suffix == ".pdf":
+            doc = self._load_pdf(str(path))
+        elif suffix in (".md", ".markdown"):
+            doc = MarkdownLoader().load(str(path))
+        elif suffix == ".txt":
+            doc = TxtLoader().load(str(path))
+        elif suffix in (".epub", ".mobi", ".azw3", ".azw"):
+            from .loaders.ebook_loader import EbookLoader
+            doc = EbookLoader().load(str(path))
+        elif suffix == ".docx":
+            from .loaders.office_loader import DocxLoader
+            doc = DocxLoader().load(str(path))
+        elif suffix == ".xlsx":
+            from .loaders.office_loader import XlsxLoader
+            doc = XlsxLoader().load(str(path))
+        else:
+            raise ValueError(
+                f"不支持的文件格式: {suffix}，"
+                "支持: .pdf .md .txt .epub .mobi .azw3 .docx .xlsx")
+
+        if source:
+            doc.source = source   # 用调用方提供的来源标识覆盖临时盘路径
+
+        return self._run_pipeline(
+            doc,
+            source_title = source_title or path.stem,
+            source_year  = source_year,
+            domain       = domain,
+            collection   = collection,
+            content_hash = content_hash,
+            progress_cb  = progress_cb,
+        )
+
+    def ingest_url(
+        self,
+        url:          str,
+        source_title: str = "",
+        source_year:  int = 0,
+        domain:       str = "",
+    ) -> list:
+        """摄入网页 URL。"""
+        doc = WebLoader().load(url)
+        return self._run_pipeline(
+            doc,
+            source_title = source_title or url,
+            source_year  = source_year,
+            domain       = domain,
+        )
+
+    def ingest_text(
+        self,
+        text:         str,
+        source:       str = "inline",
+        source_title: str = "",
+        source_year:  int = 0,
+        domain:       str = "",
+    ) -> list:
+        """
+        直接摄入文本字符串。
+        适用于：已有文本内容、测试、管道传入。
+        """
+        doc = MarkdownLoader().load_string(text, source=source)
+        return self._run_pipeline(
+            doc,
+            source_title = source_title or source,
+            source_year  = source_year,
+            domain       = domain,
+        )
+
+    # ── 内部流程 ─────────────────────────────────────────────
+
+    def _run_pipeline(
+        self,
+        doc:          ParsedDocument,
+        source_title: str,
+        source_year:  int,
+        domain:       str,
+        collection:   str = "",
+        content_hash: str = "",
+        progress_cb=None,
+    ) -> list:
+        logger.info(
+            "KDE pipeline 开始: doc_id=%s title=%s sections=%d",
+            doc.doc_id, doc.title,
+            sum(len(ch.sections) for ch in doc.chapters),
+        )
+
+        # Stage 2a: Chunk
+        chunks = self.chunker.chunk(doc)
+        logger.info("Chunker: %d chunks", len(chunks))
+
+        if not chunks:
+            logger.warning("文档无有效内容: %s", doc.source)
+            return []
+
+        # 保护:超大文档(如整本电子书)会切出成百上千 chunk,每个都调一次 LLM,
+        # 极慢且烧费用。超过上限时截断,只处理前 N 个,并警告。
+        # 上限可经 HKC_MAX_CHUNKS_PER_DOC 覆盖;设 0 = 不限制(完整摄入)。
+        _cap = _max_chunks_per_doc()
+        if _cap > 0 and len(chunks) > _cap:
+            logger.warning(
+                "文档过大:切出 %d 个 chunk,超过单文档上限 %d。仅处理前 %d 个"
+                "(约 %d 字符)。如需完整摄入,请调大 HKC_MAX_CHUNKS_PER_DOC"
+                "(设 0 = 不限制,但耗时与费用会同步放大);"
+                "注意同一文件重传会被内容去重拦截,补齐剩余部分需先拆分文件。",
+                len(chunks), _cap, _cap, _cap * (MAX_CHARS - OVERLAP_CHARS),
+            )
+            chunks = chunks[:_cap]
+
+        # Stage 2b: LLM 提取（有进度回调则带上；无则按旧签名调用,兼容 MockExtractor）
+        if progress_cb is not None:
+            result = self.extractor.extract(chunks, progress_cb=progress_cb)
+        else:
+            result = self.extractor.extract(chunks)
+        logger.info(
+            "Extractor: facts=%d claims=%d entities=%d concepts=%d",
+            len(result.all_facts()), len(result.all_claims()),
+            len(result.all_entities()), len(result.all_concepts()),
+        )
+
+        # 把 domain 注入 Claim（如果 LLM 没有填写 domain）
+        if domain:
+            for item in result.all_claims():
+                if not item.get("domain"):
+                    item["domain"] = domain
+
+        # Stage 3 + 4: 关系发现 + 打包写入
+        new_kus = self.packager.package(
+            result,
+            source_title = source_title,
+            source_year  = source_year,
+            source_id    = doc.source,   # 精确来源标识(如 memory:agent:finance:mem_001)
+            collection   = collection,
+            content_hash = content_hash,
+        )
+
+        logger.info("KDE pipeline 完成: 写入 %d KU", len(new_kus))
+        return new_kus
+
+    def find_evidence_by_content_hash(self, content_hash: str):
+        """按内容 SHA-256 指纹查找已摄入的文件 Evidence。命中返回 KU，否则 None。
+
+        哈希存在 Evidence.extra["content_hash"]。单机少用户（几十本书）场景下
+        全量遍历 Evidence 即可，简单可靠，无需引入额外索引存储。
+        """
+        if not content_hash:
+            return None
+        from hkc_core.models.enums import KUType
+        for ku in self.store.query_by_type(
+            KUType.EVIDENCE, status="active", limit=10_000_000
+        ):
+            if (getattr(ku, "extra", None) or {}).get("content_hash") == content_hash:
+                return ku
+        return None
+
+    def is_duplicate_content(self, data: bytes) -> bool:
+        """供 API 层在提交/创建 job 前提前拦截重复上传（避免起后台任务）。"""
+        return self.find_evidence_by_content_hash(content_hash_of(data)) is not None
+
+    def _load_pdf(self, path: str) -> ParsedDocument:
+        try:
+            from .loaders.pdf_loader import PDFLoader
+            return PDFLoader().load(path)
+        except ImportError:
+            # PyMuPDF 未安装，降级为纯文本提取
+            logger.warning("PyMuPDF 未安装，PDF 降级为文本提取")
+            import subprocess, shlex
+            safe_path = shlex.quote(path)
+            result = subprocess.run(
+                ["python3", "-c",
+                 f"import fitz; d=fitz.open({safe_path}); "
+                 "print(chr(10).join(p.get_text() for p in d))"],
+                capture_output=True, text=True
+            )
+            if result.returncode == 0:
+                return MarkdownLoader().load_string(result.stdout, source=path)
+            raise

package/python/vendor/hkc/hkc_kde/loaders/ebook_loader.py

@@ -0,0 +1,153 @@
+"""
+hkc-kde / loaders / ebook_loader.py
+电子书解析器：支持 .epub / .mobi / .azw3
+
+- epub：标准格式(zip + xhtml),用 ebooklib + BeautifulSoup 提取文本
+- mobi / azw3：Amazon 格式,用 mobi 库解包为 html 后提取
+  (azw3 即 KF8,mobi 库可处理)
+
+所有格式最终转成纯文本,按 ParsedDocument 返回,后续 pipeline 与其它格式一致。
+"""
+from __future__ import annotations
+
+import os
+import uuid
+import logging
+import shutil
+from pathlib import Path
+
+from ..models import ParsedDocument, Chapter, Section
+
+logger = logging.getLogger(__name__)
+
+# 软依赖检测
+try:
+    import ebooklib
+    from ebooklib import epub
+    HAS_EBOOKLIB = True
+except ImportError:
+    HAS_EBOOKLIB = False
+
+try:
+    from bs4 import BeautifulSoup
+    HAS_BS4 = True
+except ImportError:
+    HAS_BS4 = False
+
+try:
+    import mobi
+    HAS_MOBI = True
+except ImportError:
+    HAS_MOBI = False
+
+
+_MIN_SECTION_CHARS = 12   # 太短的片段(导航/版权页碎片)忽略;阈值偏低以兼容中文短段落
+
+
+def _html_to_text(html: str) -> str:
+    """从 HTML 提取纯文本。"""
+    if HAS_BS4:
+        soup = BeautifulSoup(html, "html.parser")
+        # 去掉脚本/样式
+        for tag in soup(["script", "style"]):
+            tag.decompose()
+        return soup.get_text("\n", strip=True)
+    # 没有 bs4 时的兜底:粗暴去标签
+    import re
+    text = re.sub(r"<[^>]+>", " ", html)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+class EbookLoader:
+    """epub / mobi / azw3 加载器。"""
+
+    def load(self, path: str) -> ParsedDocument:
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {path}")
+
+        suffix = path.suffix.lower()
+        if suffix == ".epub":
+            title, blocks = self._load_epub(path)
+        elif suffix in (".mobi", ".azw3", ".azw"):
+            title, blocks = self._load_mobi(path)
+        else:
+            raise ValueError(f"EbookLoader 不支持的格式: {suffix}")
+
+        # blocks: list[str] 纯文本段落 → 组装成单一章节的多个 Section
+        sections = []
+        for i, blk in enumerate(blocks):
+            blk = blk.strip()
+            if len(blk) < _MIN_SECTION_CHARS:
+                continue
+            sections.append(Section(section_id=f"SEC_{i:04d}", content=blk))
+
+        chapter = Chapter(chapter_id="CH_0001", title=title or path.stem)
+        chapter.sections = sections
+
+        return ParsedDocument(
+            doc_id   = f"DOC_{uuid.uuid4().hex[:8].upper()}",
+            title    = title or path.stem,
+            source   = str(path),
+            doc_type = "EBOOK",
+            chapters = [chapter],
+            metadata = {
+                "format":     suffix.lstrip("."),
+                "file_size":  path.stat().st_size,
+                "section_count": len(sections),
+            },
+        )
+
+    def _load_epub(self, path: Path):
+        if not HAS_EBOOKLIB:
+            raise ImportError("解析 epub 需要 ebooklib，请运行: pip install ebooklib beautifulsoup4")
+        book = epub.read_epub(str(path))
+        # 标题
+        title = ""
+        try:
+            md = book.get_metadata("DC", "title")
+            if md:
+                title = md[0][0]
+        except Exception:
+            pass
+        # 按文档顺序提取每个 html 文档的文本
+        blocks = []
+        for item in book.get_items_of_type(ebooklib.ITEM_DOCUMENT):
+            try:
+                html = item.get_content().decode("utf-8", errors="ignore")
+                text = _html_to_text(html)
+                if text:
+                    blocks.append(text)
+            except Exception as e:
+                logger.warning("epub 文档解析失败: %s", e)
+        return title, blocks
+
+    def _load_mobi(self, path: Path):
+        if not HAS_MOBI:
+            raise ImportError("解析 mobi/azw3 需要 mobi 库，请运行: pip install mobi")
+        tmp_dir = None
+        try:
+            # mobi.extract 返回 (tmp_dir, 解包出的主文件路径)
+            tmp_dir, out_path = mobi.extract(str(path))
+            text = ""
+            op = Path(out_path)
+            if op.suffix.lower() in (".html", ".htm", ".xhtml"):
+                html = op.read_text(encoding="utf-8", errors="ignore")
+                text = _html_to_text(html)
+            elif op.suffix.lower() in (".txt", ""):
+                text = op.read_text(encoding="utf-8", errors="ignore")
+            else:
+                # 兜底:扫描解包目录里的 (x)html。
+                # KF8/azw3(MOBI8)会被解包成 epub 结构,正文是 .xhtml(out_path 为 .epub),
+                # 仅扫 *.html 会漏掉全部正文 → 必须同时覆盖 .xhtml/.htm。
+                # 排序保证 part0000/part0001… 的段落顺序稳定。
+                for f in sorted(Path(tmp_dir).rglob("*")):
+                    if f.suffix.lower() in (".html", ".htm", ".xhtml"):
+                        text += _html_to_text(f.read_text(encoding="utf-8", errors="ignore")) + "\n\n"
+            # 按段落切分(双换行)
+            blocks = [b for b in text.split("\n\n")] if "\n\n" in text else [text]
+            title = path.stem
+            return title, blocks
+        finally:
+            if tmp_dir and os.path.isdir(tmp_dir):
+                shutil.rmtree(tmp_dir, ignore_errors=True)

package/python/vendor/hkc/hkc_kde/loaders/office_loader.py

@@ -0,0 +1,194 @@
+"""
+hkc-kde / loaders / office_loader.py
+Office 文档解析器：支持 .docx（Word）/ .xlsx（Excel）。
+
+- docx：python-docx 读取。段落按「标题样式(Heading/Title)」切章节，正文段落归入当前章节，
+  表格逐行转成 "单元格 | 单元格" 文本一并纳入（很多知识就藏在 Word 表格里）。
+- xlsx：openpyxl 只读+data_only 读取（取缓存值而非公式）。每个工作表 → 一个 Chapter，
+  行按批合并成 Section（避免上千行切出上千个碎 Section 拖垮 chunker/LLM）。
+
+所有格式最终转成纯文本，按 ParsedDocument 返回，后续 pipeline 与其它格式一致。
+软依赖：未装 python-docx / openpyxl 时抛清晰的可操作错误（提示装 knowledge-files），
+不静默产出空文档（否则用户以为摄入成功却啥都没进库）。
+"""
+from __future__ import annotations
+
+import uuid
+import logging
+from pathlib import Path
+
+from ..models import ParsedDocument, Chapter, Section
+
+logger = logging.getLogger(__name__)
+
+# 软依赖检测（缺失时在 load 抛可操作错误，而非 import 期崩溃整个 KDE）
+try:
+    import docx as _docx  # python-docx
+    HAS_DOCX = True
+except ImportError:
+    HAS_DOCX = False
+
+try:
+    import openpyxl as _openpyxl
+    HAS_OPENPYXL = True
+except ImportError:
+    HAS_OPENPYXL = False
+
+
+_MIN_SECTION_CHARS = 2          # docx 段落可能很短（标题项/列表项），阈值给低些保内容
+_XLSX_ROWS_PER_SECTION = 20     # 每 20 行合并为一个 Section
+_XLSX_MAX_ROWS_PER_SHEET = 5000 # 单表行上限，超出截断（防超大表切出海量 chunk 烧 LLM）
+_XLSX_MAX_CELL_CHARS = 500      # 单元格文本上限，防个别巨长单元格
+
+
+def _flush_chapter(chapters, title, paras, counter):
+    """把累积段落收敛成一个 Chapter；空则跳过。返回新的 counter。"""
+    secs = [
+        Section(f"SEC_{counter:04d}_{i:04d}", p)
+        for i, p in enumerate(paras)
+        if len(p) >= _MIN_SECTION_CHARS
+    ]
+    if secs:
+        chapters.append(Chapter(
+            chapter_id=f"CH_{counter:04d}",
+            title=title,
+            sections=secs,
+        ))
+        return counter + 1
+    return counter
+
+
+class DocxLoader:
+    """Word .docx → ParsedDocument。按标题样式切章节，含表格文本。"""
+
+    def load(self, path: str) -> ParsedDocument:
+        if not HAS_DOCX:
+            raise RuntimeError(
+                "解析 .docx 需要 python-docx，未安装。请安装可选依赖："
+                "pip install -e \".[knowledge-files]\"  或  pip install python-docx"
+            )
+        path = Path(path)
+        document = _docx.Document(str(path))
+
+        chapters: list[Chapter] = []
+        current_title = ""
+        current_paras: list[str] = []
+        counter = 1
+
+        def _add_para(para):
+            nonlocal current_title, current_paras, counter
+            text = (para.text or "").strip()
+            if not text:
+                return
+            style = (getattr(para.style, "name", "") or "")
+            if style.startswith("Heading") or style == "Title":
+                # 遇到新标题：先收敛上一章，再切换标题
+                counter = _flush_chapter(chapters, current_title, current_paras, counter)
+                current_title = text
+                current_paras = []
+            else:
+                current_paras.append(text)
+
+        def _add_table(table):
+            # 逐行转 "cell | cell | cell"，追加到【当前】章节（表格归它实际出现的那一节）
+            for row in table.rows:
+                cells = [(c.text or "").strip() for c in row.cells]
+                line = " | ".join(c for c in cells if c)
+                if line:
+                    current_paras.append(line)
+
+        # 按文档 body 子元素的真实顺序遍历，使表格归入它出现位置的章节（而非全塞末章，
+        # 否则 Evidence 溯源标题失真）。用 tag 后缀判断以耐 python-docx 版本差异；
+        # 任何异常回退到「先所有段落、再所有表格」的稳妥旧路径。
+        try:
+            from docx.text.paragraph import Paragraph as _Para
+            from docx.table import Table as _Table
+            body = document.element.body
+            for child in body.iterchildren():
+                tag = getattr(child, "tag", "")
+                if tag.endswith("}p"):
+                    _add_para(_Para(child, document))
+                elif tag.endswith("}tbl"):
+                    _add_table(_Table(child, document))
+        except Exception:
+            chapters.clear(); current_title = ""; current_paras = []; counter = 1
+            for para in document.paragraphs:
+                _add_para(para)
+            for table in document.tables:
+                _add_table(table)
+
+        counter = _flush_chapter(chapters, current_title, current_paras, counter)
+
+        if not chapters:
+            # 空文档也返回一个占位章节，让上层 "文档无有效内容" 分支统一处理
+            chapters = [Chapter("CH_0001", "", [])]
+
+        return ParsedDocument(
+            doc_id=f"DOC_{uuid.uuid4().hex[:8].upper()}",
+            title=path.stem,
+            source=str(path),
+            doc_type="DOCX",
+            chapters=chapters,
+        )
+
+
+class XlsxLoader:
+    """Excel .xlsx → ParsedDocument。每工作表一章，行按批合并为 Section。"""
+
+    def load(self, path: str) -> ParsedDocument:
+        if not HAS_OPENPYXL:
+            raise RuntimeError(
+                "解析 .xlsx 需要 openpyxl，未安装。请安装可选依赖："
+                "pip install -e \".[knowledge-files]\"  或  pip install openpyxl"
+            )
+        path = Path(path)
+        # read_only + data_only：大表内存友好，且取缓存值而非公式串。
+        wb = _openpyxl.load_workbook(str(path), read_only=True, data_only=True)
+        chapters: list[Chapter] = []
+        counter = 1
+        try:
+            for ws in wb.worksheets:
+                rows_text: list[str] = []
+                for ri, row in enumerate(ws.iter_rows(values_only=True)):
+                    if ri >= _XLSX_MAX_ROWS_PER_SHEET:
+                        logger.warning(
+                            "工作表 %s 超过 %d 行，已截断", ws.title, _XLSX_MAX_ROWS_PER_SHEET)
+                        break
+                    cells = []
+                    for v in row:
+                        if v is None:
+                            continue
+                        s = str(v).strip()
+                        if s:
+                            cells.append(s[:_XLSX_MAX_CELL_CHARS])
+                    if cells:
+                        rows_text.append(" | ".join(cells))
+
+                if not rows_text:
+                    continue
+
+                # 按批合并成 Section
+                secs = []
+                for bi, start in enumerate(range(0, len(rows_text), _XLSX_ROWS_PER_SECTION)):
+                    batch = rows_text[start:start + _XLSX_ROWS_PER_SECTION]
+                    secs.append(Section(f"SEC_{counter:04d}_{bi:04d}", "\n".join(batch)))
+                chapters.append(Chapter(
+                    chapter_id=f"CH_{counter:04d}",
+                    title=ws.title or f"Sheet{counter}",
+                    sections=secs,
+                ))
+                counter += 1
+        finally:
+            # read_only 模式必须显式关，否则底层 zip 文件句柄泄漏（Windows 上还会锁文件）
+            wb.close()
+
+        if not chapters:
+            chapters = [Chapter("CH_0001", "", [])]
+
+        return ParsedDocument(
+            doc_id=f"DOC_{uuid.uuid4().hex[:8].upper()}",
+            title=path.stem,
+            source=str(path),
+            doc_type="XLSX",
+            chapters=chapters,
+        )