epub-book-pipeline

EPUB 图书处理流水线

提供 EPUB 专属的机械操作，用于提取、分块、重建和验证 EPUB 文件。它负责 EPUB 的结构处理，让你可以专注于需要应用的内容转换。

流水线概览

origin.epub → [Step 1: Extract] → source.md + toc_original.yaml + terminology_candidates.md
              → [Step 2: Chunk] → chunk-*.md files (for parallel processing)
              → [** your content modifications here **]
              → [Step 3: Rebuild] → modified.epub
              → [Step 4: Validate]

执行规则

直接运行所请求的流水线步骤，不要预先检查依赖项、环境变量或配置。如果存在问题，脚本会报出清晰的错误——届时再检查并修复即可。

要求

pip install ebooklib beautifulsoup4 lxml

脚本位于 {baseDir}/scripts/。

步骤 1：提取 EPUB → 结构化 Markdown

python {baseDir}/scripts/extract_epub.py --epub <input.epub> --output-dir <output_dir>

功能：

• 解析 EPUB 结构（OPF、NCX、CSS、spine）
• 将包含文本的 XHTML 提取到一个合并的 Markdown 文件中
• 添加结构标记：, , ``
• 将 NCX navLabel 条目提取到 toc_original.yaml（用于后续重建目录）
• 扫描片假名序列，并将其写入 terminology_candidates.md（供审核的专有名词候选项）

输出：

文件	描述
source.md	包含所有文本和结构标记的合并 Markdown 文件
toc_original.yaml	NCX/EPUB3 目录条目（play_order、label、src）
terminology_candidates.md	自动检测到的专有名词候选项（片假名序列），供审核

重要： `` 标记将各个章节映射到其原始 XHTML 文件。切勿删除或修改这些标记——重建步骤依赖它们将修改后的内容放回正确的 XHTML 文件中。

步骤 2：拆分 source.md，以便并行处理

EPUB 文件较大时，分块可让你独立处理各个章节（例如，通过并行子 Agent 处理，或一次处理一个章节）：

python {baseDir}/scripts/chunk_source.py \
  --source <output_dir>/source.md \
  --output-dir <output_dir>/chunks/ \
  --max-chars 12000

--max-chars 用于控制每个分块的目标字符数（默认值为 6000）。所有内部阈值（刷新阈值、合并下限、合并上限）都会按比例缩放。

分块规则：

• `` 标记不可拆分——切勿跨分块拆开
• 超长 FILE 章节会在由空行分隔的段落边界处分割（绝不在段落中间分割）
• --- 场景分隔符是独立的段落块
• 如果分块末尾会出现 h1 标题，则将该 h1 移到下一个分块
• 较短的尾部片段（< max_chars/3）会合并回上一个分块
• 很短的 FILE 章节（仅含图片的页面、较短的章节）会累积到相邻分块中，而不是单独生成很小的块

输出： chunk-NN.md 文件，以及将分块编号映射到 `` 范围的 chunk_index.json。

修改分块内容后，按顺序将它们合并回一个 Markdown 文件，以供重建步骤使用：

cat chunks/chunk-*.md > ../modified.md

如果按顺序处理，也可以直接编辑 source.md，完全跳过步骤 2。

步骤 3：重建 EPUB

修改 Markdown 内容后，将其重建为有效的 EPUB：

python {baseDir}/scripts/rebuild_epub.py \
  --epub <origin.epub> \
  --translation <modified.md> \
  --output <final.epub> \
  [--toc <toc_original.yaml>]

参数：

• --epub：原始 EPUB 文件（用作结构模板）
• --translation：包含内容修改的 Markdown 文件
• --output：输出 EPUB 路径
• --toc：用于自定义目录标签的 YAML 文件（若省略，则自动检测 --translation 同目录下的文件）
• --from-lang / --to-lang：源语言/目标语言代码（默认值：ja → zh-CN）；仅当脚本内置的特定语言转换（删除 ruby、书写模式、排版 CSS）适用于你的使用场景时才需要

功能：

• 以原始 EPUB 为基础进行复制，并根据 `` 映射的章节替换文本
• 根据 toc_original.yaml 重建 NCX/EPUB3 目录（如果提供）
• 保留原始文件中的所有非文本资源（图片、字体、样式表）
• 支持 EPUB2 和 EPUB3 格式
• 支持 SVG 包装页面（封面、彩页）——保持原样

目录自定义： 创建一个 YAML 文件（以 toc_original.yaml 为基础），以便在重建时自定义目录标签：

book_title: The Original Title
toc:
  - play_order: 1
    label: "Custom Chapter Title"
    src: "Text/p-006.xhtml#toc-001"

未指定的字段将使用原始 EPUB 中的值。

第 4 步：验证

验证重建后的 EPUB 在结构上是否完整：

python {baseDir}/scripts/validate_epub.py \
  --epub <final.epub> \
  --source-md <output_dir>/source.md \
  --translation-md <output_dir>/modified.md

**检查项：**ZIP 结构、OPF 元数据完整性、所有包含文本的 XHTML 文件是否存在且格式正确、图像完整性、NCX 与 nav.xhtml 中的目录是否一致，以及源内容与修改后内容之间的结构标记是否对齐。

输出格式：

• 逐个扫描每个 XHTML 文件；每个文件的问题都以 [WARN] 报告
• 摘要行：XHTML files checked: N (OK: M, no Chinese: ..., ruby: ..., lang: ...)
• 总体结果：Summary: X/Y checks passed (Z%) — 除非关键结构错误导致无法验证，否则退出代码为 0

可选项：

• --sample：用于内容验证的 XHTML 文件名（默认为 p-007.xhtml）
• --verbose：显示所有检查项，包括通过的检查

完整流水线示例

BASE=book-work

# 1. Extract
python scripts/extract_epub.py --epub book.epub --output-dir $BASE/

# 2. (Optional) Chunk for parallel processing
python scripts/chunk_source.py --source $BASE/source.md --output-dir $BASE/chunks/ --max-chars 12000

# 3. Apply your content modifications to chunk-*.md or source.md
#    (this is where you edit text, replace content, reformat, etc.)

# 4. Rebuild
python scripts/rebuild_epub.py --epub book.epub --translation $BASE/modified.md --output $BASE/final.epub

# 5. Validate
python scripts/validate_epub.py --epub $BASE/final.epub --source-md $BASE/source.md --translation-md $BASE/modified.md

边缘情况

• SVG 封装页面（封面、彩页）：按原样保留
• 章节标题图像（<h1><img>）：保留图像，可通过 markdown 插入额外文本
• 场景分隔符：○/● → markdown 中的 ---，重建时恢复 — --- 的对齐必须与原文一一对应；不匹配会导致后续段落错位
• 空段落（<p><br/>）：在结构上保留
• EPUB2 与 EPUB3：均可处理（NCX 和 nav.xhtml）
• 嵌入字体：自动保留
• 从右到左／竖排书写模式 CSS：重建时移除（由 --from-lang/--to-lang 控制）；如果生成的 CSS 不适用于你的书写方向，则跳过

脚本参考

脚本	用途
extract_epub.py	EPUB → 结构化 markdown（--epub INPUT --output-dir DIR）
chunk_source.py	按 FILE 边界分块（--source SRC --output-dir DIR [--max-chars N]）
rebuild_epub.py	修改后的 markdown → 最终 EPUB（--epub SRC --translation MD --output EPUB [--toc YAML]）
validate_epub.py	结构检查 + 内容对齐（--epub EPUB [--source-md SRC --translation-md TGT]）