# 轻量 PDF → EPUB 独立模块

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

## 安装和后端

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

```bash
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](https://pypdfium2.readthedocs.io/en/stable/python_api.html)、[Apple Vision](https://developer.apple.com/documentation/vision/recognizing-text-in-images)、[Tesseract TSV](https://tesseract-ocr.github.io/tessdoc/Command-Line-Usage.html)。PDFium 在本模块中串行调用，避免跨线程调用原生库。

## 中文 PDF 直接重排

```bash
.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 → 翻译

```bash
.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 后：

```bash
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` 支持查看原扫描后确认的逐行校正：

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

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


## FireRed OCR 服务与前 50 页对比

`--ocr firered --ocr-url http://HOST:PORT` 使用显式指定的 OpenAI-compatible 服务，默认模型别名为 `firered-ocr`，可用 `--ocr-model` 更换。客户端仅新增标准库 HTTP 调用，复用 Pillow，不下载模型。当前适配器面向无需认证的内网服务。

```bash
.venv/bin/python scripts/pdf_to_epub.py input/chinese.pdf \
  --output output/pdf/firered-sample.epub --work .work/pdf-firered \
  --language zh-CN --title '书名' --author '作者' --pages 1-50 \
  --ocr firered --ocr-url http://192.168.50.100:8001 --cover-page 1
```

输入图片最长边限制为 1600px，请求 temperature=0、max_tokens=1800，适配本次服务 4096-token 上下文。`--ocr-prompt FILE` 可以指定识别提示；实验使用官方 `conv_for_infer.py` 的提示，来源为 [FireRed-OCR 官方仓库](https://github.com/FireRedTeam/FireRed-OCR)。图片有效内容及设置参与缓存指纹，原始 Markdown、响应、用量和耗时写入工作目录。响应必须正常结束；截断结果保留为 rejected 文件并停止，不当作完整页面接受。

FireRed 返回 Markdown，没有可信的字行坐标和逐字置信度。适配器保留段落和简单标题，未知 bbox 为 null，不虚构坐标。可用 `--geometry-work .work/previous-vision` 引用同源、同页 Vision 缓存的几何信息；模块检查源 SHA 并通过文本对齐匹配坐标，记录来源和匹配比例，正文仍全部来自 FireRed。没有几何参考时不保证还原署名等空间对齐。

署名／日期等短窄右侧行保持独立段落和右对齐，日期不再误当页眉页脚删去；这些段落也不会跨页拼接。扫描混合图文仍需显式保留原页，不自动裁图。

`scripts/compare_pdf_ocr.py` 生成逐页原扫描／Vision／FireRed 对照。两引擎文本一致率不等于准确率；可提供人工核对片段测算局部字错率，不能推广为全部页面准确率。首轮结果和方法见 [50 页验收记录](QA_FIRERED_50_2026-10-29.md)。