epub-to-txt 技能包

> EPUB / MOBI / PDF -> TXT -> Markdown -> 多语言翻译 全流程，零 token 消耗

包含脚本

完整流水线

EPUB/PDF -> TXT -> 翻译(可选) -> Markdown -> AI润色（最少token）
-> 脚本 -> 脚本 -> 本地模型 -> 零token -> 只做最后精修

为什么这样设计？
- EPUB/PDF -> TXT：用脚本处理，零 token
- 翻译：Argos Translate 本地神经网络模型推理，零 token、完全离线
- TXT -> Markdown：用脚本识别标题/章节/正文，零 token
- AI 润色：只处理"人味"部分，少量 token，节省 90%

多语言翻译（v3 新增）

引擎：
1. Argos Translate（默认）——纯本地开源神经翻译，模型首次自动下载（en->zh 约 200MB），之后完全离线、零 token
2. translate-shell（备选，--engine trans）——需系统已装 trans 命令且联网

特性：
- 保留章节结构（=== 边框、 小节、Markdown # 标题均不破坏，元数据行不翻译）
- 多语言：--from / --to 任意支持的语言对（en/zh/ja/ko/fr/de/es/ru/ar/pt...），无直连模型时自动经英语中转
- 双语对照：--bilingual 原文+译文交错输出
- 断点续传：翻译中断后重跑同一命令，自动从上次进度继续（进度存 .progress.json）

bash

英文书 -> 中文（最常用）

python3 txt-translate.py book.txt # 输出 book.zh.txt
python3 txt-translate.py book.txt 中文版.txt # 指定输出名
python3 txt-translate.py book.md --to zh # Markdown 也支持

其他语言

python3 txt-translate.py book.txt --from en --to ja # 英->日
python3 txt-translate.py book.txt --from ja --to zh # 日->中（经英语中转）

双语对照 / 批量

python3 txt-translate.py book.txt --bilingual
python3 txt-translate-batch.py ~/books_txt/ --from en --to zh

安装（一次性）：
bash
pip install argostranslate

首次翻译时自动下载对应语言模型，之后完全离线

典型场景：英文 EPUB -> 中文 Markdown
bash
python3 epub-to-txt.py english-book.epub /tmp/book.txt # Step 1: EPUB -> TXT
python3 txt-translate.py /tmp/book.txt /tmp/book.zh.txt # Step 2: 本地翻译 -> 中文
python3 txt-to-md.py /tmp/book.zh.txt /tmp/book.zh.md # Step 3: TXT -> Markdown

性能参考：CPU 上约 1~3 段/秒，一本 300 页英文书约 30~60 分钟（后台跑即可，断点续传不怕中断）。
翻译质量说明：Argos 为开源离线模型，质量接近早期谷歌翻译，适合"通读理解"；出版级质量可在译后让 AI 只润色关键章节（少量 token）。

使用方法

1. EPUB -> TXT

bash
python3 epub-to-txt.py input.epub [output.txt]
python3 epub-to-txt.py input.epub # 自动同名输出

3. MOBI -> TXT v3.2新增

bash
pip install mobi # 一次性安装依赖
python3 mobi-to-txt.py input.mobi [output.txt] # 单本
python3 mobi-to-txt-batch.py ~/books/ # 批量

> 原理：MOBI -> kindleunpack 解压（生成内嵌EPUB或Mobi7文件）-> 复用 EPUB 解析逻辑 -> TXT
> 支持 K8 新版（生成EPUB）和 Mobi7 老版（直接生成 book.html），自动识别，零额外配置

4. PDF -> TXT

bash
python3 pdf-to-txt.py input.pdf [output.txt] # 文字型 PDF（含 PyMuPDF 兜底）

4b. 扫描/图片型 PDF -> TXT（本地 OCR）v3.4升级

bash
pip install rapidocr-onnxruntime pymupdf pillow # rapidocr 已内含 numpy/opencv，无需另装
python3 pdf-to-txt-ocr.py input.pdf [output.txt] # 默认 dpi=200，逐页 OCR
python3 pdf-to-txt-ocr.py input.pdf --dpi 300 --from-page 1 --to-page 5 # 高清/分段

v3.4 大部头：页级输出 + 断点续传（572页跑1小时不怕中断）

python3 pdf-to-txt-ocr.py input.pdf --per-page-dir ./ocr_out --resume

v3.4 跳过封面/版权/目录页（纯水印页白跑）

python3 pdf-to-txt-ocr.py input.pdf --per-page-dir ./ocr_out --resume --skip-pages 1-3

v3.4 先预检文字层（拿文字型 PDF 跑会直接中止并提示改用 pdf-to-txt.py）

python3 pdf-to-txt-ocr.py input.pdf --per-page-dir ./ocr_out --resume --preflight

> 引擎 RapidOCR（onnxruntime 推理，自带中文模型），完全离线、零 token。
> 适合出版社扫描书、影印本、无文字层的图片型 PDF。
>
> v3.4 新能力（来自 2026-09-05 税务师教材 572+486 页全本 OCR 实战）：
> - --per-page-dir <dir>：每页一个 page_NNNN.txt + _manifest.json，后续按章节重组可逐页检索，不用 grep 整个大文件；
> - --resume：断点续传，每页独立文件，中断重跑自动跳过已完成页（大部头必加，否则跑 1~2 小时等于赌博）；
> - --skip-pages 1-3,10-14：跳过封面/版权/扉页/目录，省下纯水印页的 OCR 时间；
> - --preflight：跑前先判定文字层，避免拿文字型 PDF 白跑几十分钟；
> - 页级进度日志：每 N 页打印「耗时/速度/剩余时间/已 OCR 字数」。
>
> 实测基准（CPU，150 dpi，中文教材）：3.7~6.5 秒/页；572 页约 35 分钟，486 页约 30 分钟。

用户明确偏好：扫描型 PDF 停下等决策（v1.0.8 新增）

> 用户多次明确要求：PDF 预检判定为「图片型」时，必须停下并告知页数 + 预估 OCR 时间，不得自动跑 OCR。这是工作纪律，不是可选行为。

具体规则：
1. 任何 PDF 预处理时，先用 pdf-ocr-preflight.py 判定文字层；
2. 若判定为「图片型 / 扫描型」：
- 立即停下，打印页数、书签数、DPI、预估 OCR 时间（按 CPU ~4s/页 估算）；
- 不要 自动跑 pdf-to-txt-ocr.py；
- 等待用户下一步指令 后再决定是否 OCR（以及选定向/全本书页）。
3. 若判定为「文字型」：继续走 pdf-to-txt.py 正常转换。

为什么这样设计：用户之前多次踩坑——大型扫描 PDF 白跑了半小时才发现要 OCR，浪费时间和本地算力。这条纪律保护用户不白跑。

4c. 大部头图片型 PDF：定向 OCR 工作流 v3.3新增

> 适用场景：300~500 页的扫描书、影印本、研报 PDF，只需要其中几个章节。
> 实测收益：431 页的《金融机器学习》，只 OCR 了 110 页（25.5%）就拿到了全部目标章节，机器时间从约 45 分钟降到约 12 分钟，且产出文本小、可直接精读。

Step 0 · 先判定有没有文字层（必做，否则白跑）

pdf-to-txt.py 遇到无文字层 PDF 时会静默输出 0 字符，不要被骗过去。直接用预检脚本一步到位（v3.4 新增，判定文字层 + 扫描 DPI + 书签）：

bash
python3 pdf-ocr-preflight.py input.pdf

输出示例：

页数 572 书签 0 抽样 60 页

文字层分布: 碎片文字=60

判定: 【扫描型】

扫描 ~400 DPI，OCR 中文质量可用

· 无书签 -> 需走 4c：OCR 目录页取「章节->书页」映射，再标定 offset

· 大部头（572页，全本约 38 分钟）-> 若只要部分章节，务必走定向 OCR，别全本

判据：文字层占比 < 30% 且图片多 -> 图片型，走 OCR；顺带看「书签」行：有书签就直接用书签页码，跳过 Step 1~2。

Step 1 · 只 OCR 目录，拿"章节 -> 书页"映射

bash
python3 pdf-to-txt-ocr.py input.pdf toc.txt --dpi 200 --from-page 1 --to-page 14

目录通常在 PDF 前 10~20 页。OCR 输出里，章节名与其起始书页会分行显示（如"第3章 / 标签 / 53"），需在文本里配对读取。

Step 2 · 标定偏移量（关键技巧）

PDF 页 ≠ 书页（前面有扉页、版权页、目录等）。用一发短探针标定：

bash

按估算 offset 取一小段（20~40 页），看目标章标题落在哪个 PDF 页

python3 pdf-to-txt-ocr.py input.pdf probe.txt --dpi 200 --from-page 58 --to-page 96
grep -n " 第 .* 页 |第3章" probe.txt # 页标记与章节名的行号对比

对照"第3章标题出现在 PDF 第 67 页"与"目录说第3章=书页53" -> offset = 67 − 53 = 14，即 PDF页 = 书页 + 14。
每本书的 offset 不同，必须各自标定一次，标定完后续所有章节按公式直算，一次命中。

Step 3 · 按公式定向 OCR 目标章

bash

目标：第7章（书页124~134）-> PDF 138~148

python3 pdf-to-txt-ocr.py input.pdf ch07.txt --dpi 200 --from-page 138 --to-page 148

建议每章单独输出一个 txt，便于后续 grep 定位与引用。

4d. 多本协同提取：IMA 向量定位 -> 定向 OCR v3.3新增

> 适用场景：手上有多本书/研报，需要从不同来源凑齐某个主题的全部内容（如"从 6 本材料里凑齐量化模型的实现细节"）。

决策表（先选路，别盲目全书转）

IMA 的能力边界（实测结论，重要）
- search_knowledge 返回的是文档级命中 + 十几个字的高亮片段（例如只给"样本的加权|唯一性加权;序列自举"），不返回段落原文，也不返回页码；
- 要拿原文必须 fetch_media_content 拉整本——几十 MB 的 PDF 全文会把对话上下文直接撑爆，不可行。

所以正确用法是三步：
1. IMA 定位：用中文/英文语义提问，确认"这个概念在哪本书里出现过、关键词是什么"；
2. 本地确认页码：该书若有本地 PDF -> 走 4c 的目录 OCR + offset 标定；若只有 IMA 版 -> 请用户补一份本地文件（z-library 等渠道），或退而求其次按 IMA 返回的关键词做主题级讨论；
3. 定向提取：本地 TXT 用 grep + 按行号读窗口；本地图片型 PDF 用定向 OCR。

> 一句话：IMA 负责"这本书讲过什么"，本地文件负责"原文到底怎么说的"。

避坑清单（OCR 场景通用）
- 公式与代码片段会字符粘连：OCR 常输出 forloc,tl、ptsl[o]、np.nanvar(_retun_down) 这类粘连/错字，代码使用前必须按语义还原，禁止直接复制运行；
- 表格的列间错位：多列表格（如"因子名称/含义/计算公式/方向"）OCR 后常见数值串到相邻单元格，关键公式必须回看原图核对；
- 先小后大：任何新书都先 OCR 10~20 页验证质量与 offset，再决定是否批量；
- dpi 200 足够：中文印刷体 dpi=200 识别质量已可用，dpi=300 时间翻倍，仅在表格密集页局部提高。

5. TXT -> Markdown（新增！）

bash
python3 txt-to-md.py input.txt [output.md]
python3 txt-to-md.py "/path/中国REITs操作手册.txt" # 自动输出同名.md

6. 批量转换

bash
python3 epub-to-txt-batch.py /path/to/books/ # EPUB批量
python3 mobi-to-txt-batch.py /path/to/books/ # MOBI批量
python3 txt-to-md-batch.py /path/to/txts/ # TXT批量

7. Kindle (AZW3/AZW/MOBI/KFX) -> EPUB/PDF（v1.0.7 新增）

> 用途：把 Amazon Kindle 专有格式先转成开放格式（EPUB 最常用，PDF 适合打印），再走本技能的 EPUB/PDF -> TXT 流水线。
> 首选 calibre（ebook-convert 一条命令覆盖 AZW3+AZW+MOBI+KFX），无 calibre 时 MOBI 可用 pip 的 mobi 库兜底。

bash
pip install mobi # 仅 MOBI 兜底需要；calibre 优先
python3 kindle-to-epub.py book.azw3 # -> book.epub（默认同名）
python3 kindle-to-epub.py book.mobi --to pdf # -> book.pdf
python3 kindle-to-epub-batch.py ~/kindle/ --to epub # 批量

格式说明（来自用户提问）：
- AZW3 = Amazon KF8，Kindle 现代格式，本质私有封装；比它更老的 MOBI 反而更容易转。
- 两者都能被 calibre 转；唯一共同硬门槛是 DRM：亚马逊商店购买的加密版 ebook-convert 会直接报错（本工具不处理加密文件，需先本地 DeDRM 解密）。
- z-library 等渠道下载的无 DRM 版本可正常转。

calibre 安装（非管理员也能用）：
bash

方案A（管理员）：标准安装，自动加入 PATH

msiexec /i calibre-64bit-9.14.0.msi /quiet

方案B（标准用户/无提权）：管理解包到用户目录，不写注册表

msiexec /a calibre-64bit-9.14.0.msi TARGETDIR="%USERPROFILE%.workbuddy\tools\calibre" /quiet

然后脚本会自动探测；或显式指定：

set CALIBRE_EBOOK_CONVERT=%USERPROFILE%.workbuddy\tools\calibre\ebook-convert.exe

典型使用场景

场景：MOBI 书籍转 Markdown

bash
pip install mobi # 首次安装
python3 mobi-to-txt.py 巴菲特致股东的信.mobi /tmp/buffett.txt # Step 1: MOBI -> TXT
python3 txt-to-md.py /tmp/buffett.txt /tmp/buffett.md # Step 2: TXT -> Markdown

场景：把一本书转成可编辑的 Markdown

bash

Step 1: EPUB -> TXT

python3 epub-to-txt.py 智能商业.epub /tmp/智能商业.txt

Step 2: TXT -> Markdown（自动识别章节）

python3 txt-to-md.py /tmp/智能商业.txt /tmp/智能商业.md

Step 3: AI 润色（只润色，节省token）

-> 丢给 AI："请润色这段文字，让它更有传播力"

场景：批量处理一文件夹电子书

bash

批量 EPUB -> TXT

python3 epub-to-txt-batch.py ~/books/

批量 TXT -> Markdown

python3 txt-to-md-batch.py ~/books_txt/

验证结果

ls ~/books_txt/*.md | wc -l

TXT -> Markdown 识别规则

已知限制

• 扫描型 PDF：已支持！用 pdf-to-txt-ocr.py（RapidOCR 本地中文 OCR，零 token）
• 纯图片 EPUB：不支持（需先把图片导出再 OCR，可扩展）
• 复杂分栏排版：OCR 按自然阅读顺序输出，多栏可能串行（建议 --dpi 300 提升）
• 非标准章节标题（如 【第一章】）：需要手动调整
• AZW3 / KFX 需要 calibre：纯 pip 方案（mobi 库）只覆盖 MOBI，AZW3/AZW/KFX 必须装 calibre 的 ebook-convert 才能转
• DRM 文件不支持：亚马逊商店购买的加密 AZW3/MOBI 会被 ebook-convert 拒绝；需先用本地已授权的 DeDRM 流程解密，再转。本工具不处理加密文件

测试验证

已成功转换的书籍：
- 国企三资盘活（EPUB，33章，609KB）
- 中国REITs操作手册（EPUB，67章，925KB -> 917KB MD）
- 智能商业、模型思维、水平思考、查理日记 等

文件结构

epub-to-txt/
SKILL.md # 本文件
epub-to-txt.py # EPUB单本转TXT（零依赖）
epub-to-txt-batch.py # EPUB批量转TXT（零依赖）
mobi-to-txt.py # MOBI单本转TXT（需mobi库）v3.2新增
mobi-to-txt-batch.py # MOBI批量转TXT（需mobi库）v3.2新增
kindle-to-epub.py # Kindle(AZW3/AZW/MOBI/KFX)->EPUB/PDF（calibre，v1.0.7新增）
kindle-to-epub-batch.py # Kindle 批量转 EPUB/PDF（v1.0.7新增）
pdf-to-txt.py # PDF单本转TXT
pdf-to-txt-batch.py # PDF批量转TXT
pdf-to-txt-ocr.py # 扫描型PDF转TXT（RapidOCR本地OCR）v3.4升级
pdf-ocr-preflight.py # OCR前预检：文字层/扫描DPI/书签（选路必做）v3.4新增
txt-to-md.py # TXT单本转Markdown
txt-to-md-batch.py # TXT批量转Markdown
txt-translate.py # TXT/MD多语言翻译（单本）v3新增
txt-translate-batch.py # TXT/MD多语言翻译（批量）v3新增
generate-test-epub.py # 生成测试 EPUB
vendor/ # 第三方依赖（pdfminer）

设计理念

> 外部化思维：把每次解决问题的方案写成文件，不是只存在脑子里

脚本 = 经验的固化 = 零 token 消耗的 AI 工作流

版本：v3.5（2026-09-18）修复「NCX 薄壳丢正文」：多卷合集类 EPUB 的 NCX 常只指向卷/册封面薄壳（<30 字），真实正文在 spine 其他文档。新增兜底——若 NCX 抽出正文 < spine 总量 5% 且 spine>50k 字，则改抽 spine 全部文档（按阅读顺序）。实测《百年哈佛经典(50卷)》从 247 B 修复为 44 MB / 4573 章

版本：v3.4（2026-09-05）pdf-to-txt-ocr 升级：页级输出+断点续传+跳过页+预检；新增 pdf-ocr-preflight.py（OCR前预检文字层/DPI/书签）。572+486 页教材全本 OCR 实战验证

版本：v1.0.8（2026-09-18）新增「扫描型 PDF 停下等决策」工作纪律 + 预检脚本 confirm block，支持 AZW3/AZW/MOBI/KFX 经 calibre 转 EPUB/PDF（mobi 库兜底 MOBI，DRM 文件明确报错）；补充 calibre 非管理员安装（msiexec /a 解包）说明

版本：v3.2（2026-07-29）新增 mobi-to-txt / mobi-to-txt-batch，支持 MOBI -> TXT（需 pip install mobi）

版本：v3.1（2026-07-25）新增 pdf-to-txt-ocr 扫描版 PDF 本地中文 OCR（RapidOCR，零 token）