文档工程——EPUB 双语注释书制作全流程

把英文金融原著《Too Big to Fail》（229,110 词 / 5MB PDF / 708 页）变成带中文注释的 EPUB 电子书。经历了 OCR、词汇筛选、并发查词、三版阅读器适配的完整链路。配套 skill：pdf-annotated-epub 与 epub-annotation-delivery（document-processing 领域）。

一、项目目标

• 输入：英文金融原著 PDF（可能含扫描页）
• 输出：带初中以上词汇中文注释的 EPUB，点击注释可看
• 约束：适配用户的阅读器（先后踩了番茄小说、Apple Books、微信读书）

二、处理管线

2.1 PDF 提取与 OCR 判定

1
2
3

# 检测扫描版 vs 文本层
pdftotext "$F" /tmp/test.txt && wc -c /tmp/test.txt
for p in 1 100 300 700; do pdftotext -f $p -l $p "$F" - | head -3; done

• 文本层版（每页 >50 字符）：pdftotext -layout 直接提取
• 扫描版（多为空页）：pdftoppm -r 300 -png 渲染 300dpi + tesseract（chi_sim+eng）OCR
• 批量 OCR 脚本：ocr_pdf.py（渲染→OCR→合并页文本）
• 输出：tbtf_full.txt（1.35MB / 229,110 词）

2.2 词汇筛选

目标：找出「初中以上、值得注释」的词汇。

筛选管线：

1. 排除：初中课标词表 + wordfreq 高频词 + 专有名词
2. 变形还原：不规则动词表（was→be, had→have）+ 复数/分词还原
3. 词频统计：7,726 个需要注释的词条（出现次数标注）

污染修复（重要案例）：

• 发现 phone/name/market 等初中基础词被注释（污染正文）
• 根因：wordfreq top3000 含金融术语（investor/mortgage 等），被误判为基础词
• 修复：初中课标表 + wordfreq zipf≥5.2 硬过滤——zipf=5.14 的 rate 保留；phone(5.3)/place(5.7) 滤除；investor(4.0)/mortgage(4.4) 保留
• 金融学术词（loan/risk/financial）回归注释，基础词清零
• 最终：final_vocab_clean.json 8,987 词全释义，残留 0 / XML 0 错

2.3 释义查询（多线程多 API）

• 有道 jsonapi 为主 + 百度 sug 兜底
• 4 线程并发 + 断点续传
• 7,726 词 5 分钟完成（单线程要 3 小时，提速 34 倍）
• 最终 7,430 词条 0 错误

2.4 EPUB 构建

• 51 个 XHTML 文档 + 2 张图 + 48 章
• EPUB3 规范（xmlns:epub + OPF + NCX）
• 三套构建脚本：build_epub.py（弹注）/ build_jump.py（跳转）/ build_inline.py（内联）

三、版本演进（踩坑修复记）

v1：弹注版（EPUB3 popup footnote）

• 19,066 条 <aside epub:type="footnote"> 弹注
• 问题：用户阅读器不支持 EPUB3 弹注 → 打不开

v2：内联注释版

• 7,404 条释义直接写在词后 〔释义〕
• 问题：大量注释影响阅读流畅度 → 用户不满意

v3：跳转版（最终方案）

• 正文单词 = 带底色可点击链接
• 点击跳转章末词汇表，再点返回
• 注释不进正文、不用 epub:type，100% 兼容任何阅读器
• jump 版：28,231 链接

v3.1：弹注修复版

• 用户换用支持 EPUB3 的阅读器后，弹注版 v3（3.2MB / 19,066 aside）
• 已修复：基础词链接污染清零

四、阅读器适配教训

4.1 番茄小说崩溃事件

用户：「又出现崩溃了，我用的是番茄小说」→ 番茄官方对 EPUB 仅「部分支持，建议先转 TXT」。已换阅读器方案。

4.2 弹注不弹事件

用户：「关键是为什么不能弹出注释？？不然大量注释非常影响阅读」→ 阅读器不支持 EPUB3 弹注。popup/jump 双版本交付。

4.3 文件体积答疑

用户疑问：「为什么我原来的 pdf 5M，现在只有 1M 了？」

内容一字不差（229,110 词），差异全是字体和排版元数据。

五、配套 skill

5.1 pdf-annotated-epub

PDF 转文字版 + 初中以上词汇注释 EPUB：

• 双路径：文本层 PDF 直接提取，扫描版 PDF 走 OCR
• 词汇筛选规则（初中课标 + zipf≥5.2 硬过滤）
• 5 个脚本 + ocr_pdf.py + 词表模板

5.2 epub-annotation-delivery

注释 EPUB 交付与阅读器适配：

• 各阅读器（番茄/Apple Books/微信读书）兼容性矩阵
• 三版方案（弹注/内联/跳转）的选择依据
• 交付自检流程：可打开性/体积/哈希

六、关键数据

七、工程经验

1. 先确认阅读器能力再做方案：EPUB3 弹注不是所有阅读器都支持——v1 的坑就是没先确认
2. 双版本交付是保险：popup + jump 各留一份，用户换阅读器不用重做
3. 体积差异要能解释：用户关心文件大小变化，要能从组成上拆解
4. 词表污染要根治：zipf 硬过滤 + 课标表双保险，比「顺手排除」可靠
5. 并发查词收益巨大：34x 提速，5 分钟 vs 3 小时的差距决定项目可行性