技能介绍

问题：缺失导航结构的电子书

很多从 Word、InDesign 或 LaTeX 导出的 PDF 并未内嵌 outline，部分自制 EPUB 也缺少 NCX 或 EPUB3 Nav。结果就是阅读器左侧目录栏为空，读者只能通过滑动翻页。纯文本 TXT 书籍则完全没有结构信息，在电子阅读器上无法实现章节跳转。手动为几百页的书本添加书签不仅耗时，且极易出错。

工作原理：分格式的结构化提取

该技能针对不同文件的底层结构采用了差异化的提取策略：

文本型 PDF：依赖 PyMuPDF，提取每行文本的字号、加粗状态和坐标。以全文档最高频字号为正文基准，通过 --ratio 阈值判定标题候选，并按字号聚类（相邻差 ≤ 1.0pt）归纳层级，最多支持 4 层，最终写回 doc.set_toc()。
扫描版 PDF：调用 Tesseract OCR 进行文本识别。为了防止目录页或页眉干扰，算法采用严格向后单调搜索。若书籍自带印刷目录（含书页号），则优先使用 TOC-offset 模式，通过书页号加上固定偏移直接换算 PDF 物理页，稳定性远超逐章 OCR 反查。
EPUB 与 TXT：EPUB 按 spine 顺序扫描 h1-h4 标签重建导航；TXT 则通过正则匹配中英文章节模式（如 第X章、Chapter、1.1），按章切分为 XHTML 并生成带 TOC 的 EPUB。

适用边界与注意事项

处理过程始终在副本上进行，原文件不会被修改，默认输出文件带有 .bookmarked 后缀。对于文本型 PDF，若自动检测层级混乱，可通过调整 --ratio 参数来修正判定阈值。需要注意的是，PDF 书签定位基于文档实际页序而非页标签；跨行标题可能被拆成多条，长篇书籍建议先使用 --preview 参数预览目录树，确认无误后再通过 --yes 写入。对于无清晰章节结构的扫描件，需手动提供 --chapters 章节表以确保准确性。