轻量 PDF → EPUB 独立模块

首版只处理横排单栏、普通段落和简单图片。中文 PDF 转为中文重排 EPUB；英文 PDF 转为英文 EPUB，然后由现有翻译程序处理。PDF 模块不导入翻译客户端，不读取 API Key，不发起翻译请求。

安装和后端

只使用 PDF 模块时，可单独建环境，不安装原项目的翻译 API 依赖：

python3 -m venv .work/pdf-env
.work/pdf-env/bin/pip install -r requirements-pdf.txt

当前项目环境也可以直接安装该文件。相对已有项目，新增 PDF 相关依赖仅 pypdfium2、Pillow；独立安装还包含 EPUB 封装／结构审计所需的 EbookLib、lxml、BeautifulSoup、html5lib。没有 Docling、MinerU、Torch 或额外模型权重。

--ocr auto：正常文本 PDF 使用文本层；全页扫描图片重新 OCR，即使已有隐藏 OCR 层也不直接相信旧结果。Mac 默认使用系统 Apple Vision；其他系统使用可选 Tesseract。
--ocr native：只用已有文本层。扫描页会记录警告，不能把已有 OCR 质量视为已验证。
--ocr vision：强制系统 Vision，需要 macOS 和 Apple command line tools 的 swiftc。辅助程序在工作目录编译并复用，本地处理图片。Codex 沙箱内 Vision 如报 nilError，应允许本地 OCR 进程在沙箱外执行；不是 API 认证错误。
--ocr tesseract：强制可选 Tesseract CLI；需自行安装程序以及 eng／chi_sim 语言数据。适配器已实现，本轮机器没有安装 Tesseract，未进行真实 Tesseract 识别验收。

官方依据：PDFium Python API、Apple Vision、Tesseract TSV。PDFium 在本模块中串行调用，避免跨线程调用原生库。

中文 PDF 直接重排

.work/pdf-env/bin/python scripts/pdf_to_epub.py input/chinese.pdf \
  --output output/pdf/chinese.epub --work .work/pdf-chinese \
  --language zh-CN --title '书名' --author '作者' --cover-page 1

中文正文使用两格缩进；保留原语言，不做繁简转换或自由改写。输出 metadata 明确标注“PDF重排初稿”，不误标为 AI 翻译版。

英文 PDF → EPUB → 翻译

.work/pdf-env/bin/python scripts/pdf_to_epub.py input/english.pdf \
  --output output/pdf/english.epub --work .work/pdf-english \
  --language en --title 'Original Title' --author 'Original Author'

# 在已有翻译环境中执行，沿用它的模型、凭据和配置：
.venv/bin/python main.py output/pdf/english.epub --complete-book --bilingual

PDF 转换完成只打印可选的后续翻译命令，不执行。英文原生文本 PDF 已通过真实 PDF 夹具转换，并验证可由现有 EpubCleaner／FineGrainedExtractor 完整提取；没有调用模型翻译此夹具。

小样、图片与恢复

--pages 1-20,30：按1起算、闭区间选页；未覆盖全书时，书名和报告明确标注部分样例。
--cover-page 1：显式指定封面，不默认把所有 PDF 的第一页当封面。
--image-pages 2,13,476：手动保留插图、扉页、原目录或封底整页原貌。少量文字／空白页也会保留为原页图片并列入报告，不声称所有页均已文字重排。
--dpi 180：扫描渲染分辨率，支持96–400。
同一工作目录一次运行一个任务。再次运行相同命令会复用完成的逐页 OCR；源 SHA、引擎、OCR 实现／系统版本、语言或 DPI 变化时不复用不匹配结果。另一份源文件必须使用新目录。

工作目录保留 source.json、pages/ 原始识别／坐标／置信度、renders/ 原页图、book.json 段落与书签结构、report.json。OCR 失败保留已完成页面，禁止把仅完成部分的处理结果写成全书 EPUB。

EPUB 按原书签组织章节和目录层级；没有书签时使用识别出的简单章节标题，或明确的来源页导航。每个原页都有 pdf-page-N 来源锚点；跨页仅合并明显连续的正文，保留原页追踪。页眉删除记录和原 OCR 行仍在中间结果中。

普通文本 PDF 内的独立图片按页面区域渲染嵌入；扫描页中的混合图文首版不做自动精细分割，需要 --image-pages 保留原页。双栏、竖排、公式、复杂表格、脚注双向链接重建不在本轮范围，不作为已实现功能。

QA

可选安装现有 requirements-qa.txt 和 Chromium 后：

PLAYWRIGHT_BROWSERS_PATH="$PWD/.work/playwright" \
.venv/bin/python scripts/pdf_qa.py output/pdf/chinese.epub \
  --work .work/pdf-chinese --pages 1,4,16 --out .work/pdf-chinese/qa

生成原页／EPUB 900px／390px 对照，实际点击生成的 NAV 目录链接，并检查目标及来源锚点。HTML 报告和 JSON 分开保留自动结果与视觉待审状态。结构审计通过不等于 OCR 字词准确；Vision 置信分数不是字错率，也不能据此给全书准确率。

EPUB 在临时文件中构建并通过结构审计后才替换输出。没有依赖 Calibre 或桌面阅读器；Chromium 连续 XHTML 不能代表所有阅读器分页。

可追溯的局部校正

--corrections corrections.json 支持查看原扫描后确认的逐行校正：

{
  "source_sha256": "当前PDF的完整SHA256",
  "edits": [{
    "line_id": "p0101-l0011",
    "expected": "原始OCR整行原文",
    "replacement": "核对原扫描后的整行文字",
    "evidence": "核对依据"
  }]
}

源 SHA、行 ID 或 expected 不匹配就停止；重复条目和空替换也拒绝。原始 pages/*.json 不改写，校正写在派生 book.json 和报告里，可在重建时重复应用。识别内容变化会改变输出版本标识。此功能用于有证据的文字校对，不替代全书审读。

5.8 KiB Raw Blame History Unescape Escape