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を抽出し、1つの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のサイズが大きい場合、チャンク分割によってセクションごとに独立して処理できます（たとえば、サブエージェントで並列処理する場合や、セクションを1つずつ処理する場合）。

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。

チャンクの内容を変更したら、再構築ステップに進むために、順番に連結して1つの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）。スクリプトに組み込まれた言語固有の変換（ルビの削除、書字方向、タイポグラフィCSS）が用途に該当する場合にのみ必要です

処理内容：

• 元のEPUBをベースとしてコピーし、`` に対応付けられたセクションのテキストを置き換えます
• toc_original.yaml が指定されている場合、そこからNCX/EPUB3の目次を再構築します
• 元のEPUBに含まれるテキスト以外のアセット（画像、フォント、スタイルシート）をすべて保持します
• EPUB2とEPUB3の両方の形式に対応します
• SVGラッパーページ（表紙、カラープレート）を処理し、そのまま保持します

目次のカスタマイズ： 再構築時に目次ラベルをカスタマイズするには、toc_original.yaml を基に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	ファイル単位のチャンク分割（--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]）