convert-pdf-to-epub

PDF 转 EPUB 转换器

将 PDF 文档转换为高质量的 EPUB 文件，支持自动检测章节、优化图像和添加脚注超链接。

快速开始

# Run conversion (from skill directory)
python -m scripts.convert input.pdf output.epub

# Validate result
python -m scripts.validate input.pdf output.epub

工作流概览

转换分为 3 个阶段，并可选择第 4 个阶段进行适配：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  1. ANALYZE     │ ──► │  2. CONVERT     │ ──► │  3. VALIDATE    │
│  - PDF structure│     │  - Apply config │     │  - Check quality│
│  - Generate cfg │     │  - Build EPUB   │     │  - Report issues│
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                              ┌─────────────────┐
                                              │  4. ADAPT       │
                                              │  (if needed)    │
                                              │  - Tune config  │
                                              │  - Modify code  │
                                              └─────────────────┘

阶段 1：分析

转换前，先分析 PDF，以确定最佳配置：

# Open PDF and examine structure
import fitz  # pymupdf
doc = fitz.open("input.pdf")

# Check for:
# 1. Number of pages
# 2. Presence of images
# 3. Multi-column layout (compare text block x-coordinates)
# 4. Footnotes/endnotes (numbers in margins or at page bottom)
# 5. Font sizes (for heading detection thresholds)

根据分析生成初始配置：

• 小说：使用默认的 y_sort 阅读顺序
• 学术论文：启用 xy_cut 以处理分栏
• 杂志：启用图像优化，并使用 xy_cut

请用户确认建议的配置后再继续。

阶段 2：转换

使用生成的配置运行转换：

from conversion.converter import Converter
from conversion.models import ConversionConfig

config = ConversionConfig(
    page_ranges=PageRanges(skip=[1, 2], content=(3, -3)),
    exclude_regions=ExcludeRegions(top=0.05, bottom=0.05),
    reading_order_strategy="y_sort",  # or "xy_cut" for columns
    image_optimization=ImageOptimizationConfig(enabled=True),
)

converter = Converter(strategy="simple")
result = converter.convert(pdf_path, epub_path, config)

# Check confidence
if result.reading_order_confidence < 0.7:
    print("Warning: Low confidence in reading order")

阶段 3：验证

始终验证转换结果：

from validation.completeness_checker import CompletenessChecker
from validation.order_checker import OrderChecker

# Check text completeness
completeness = CompletenessChecker().check(pdf_text, epub_text)
print(f"Completeness: {completeness.score:.1%}")  # Should be > 95%

# Check reading order
order = OrderChecker().check(pdf_chunks, epub_chunks)
print(f"Order score: {order.score:.1%}")  # Should be > 80%

质量门槛：

• 完整度 < 95%：文本有丢失
• 顺序评分 < 80%：阅读顺序有误

阶段 4：适配（如果验证失败）

请参阅下文的决策树。

---

决策树：遇到问题时

Validation failed?
│
├─► Text loss > 5%?
│   ├─► Check exclude_regions (headers/footers being cut?)
│   │   → Try: exclude_regions.top: 0.03 (reduce from 0.05)
│   ├─► Check page_ranges (skipping too many pages?)
│   │   → Try: page_ranges.skip: [] (don't skip any)
│   └─► Still failing? → See reference/troubleshooting.md#text-loss
│
├─► Wrong reading order?
│   ├─► PDF has columns?
│   │   → Try: reading_order_strategy: "xy_cut"
│   ├─► Columns detected but wrong?
│   │   → Try: multi_column.threshold: 0.3 (more sensitive)
│   └─► Still failing? → See reference/troubleshooting.md#order
│
├─► Headings not detected?
│   ├─► Headings only slightly larger than body?
│   │   → Try: heading_detection.font_size_threshold: 1.1
│   └─► Custom font patterns?
│   │   → May need to modify structure_classifier.py (ADAPTABLE)
│
├─► Footnotes not linking?
│   ├─► Non-standard format (not [1] or (1))?
│   │   → Add pattern to FootnoteDetector.PATTERNS
│   └─► See reference/troubleshooting.md#footnotes
│
└─► Other issue?
    └─► See reference/troubleshooting.md

---

三层架构

代码库分为三层，每层采用不同的修改策略：

第 1 层：冻结（请勿修改）

这些文件实现固定规范或确定性算法：

文件	原因
core/epub_builder.py	EPUB3 规范是固定的
core/text_segmenter.py	验证依赖于相同的分块方式
validation/*	指标必须可复现

除非存在根本性错误，否则切勿修改这些文件。

第 2 层：可配置（先尝试调整配置）

修改代码前，先尝试调整配置：

ConversionConfig:
├── page_ranges         # Which pages to process
├── exclude_regions     # Margins to ignore (headers/footers)
├── multi_column        # Column detection settings
├── reading_order_strategy  # "y_sort" or "xy_cut"
├── heading_detection   # Font size thresholds
├── footnote_processing # Footnote patterns
├── image_optimization  # Compression settings
└── metadata           # Title, author, language

所有参数请参阅 reference/config-tuning.md。

第 3 层：可适配（配置无法解决时可修改）

这些文件包含启发式规则，可能需要针对特定 PDF 进行调整：

文件	可进行的修改
conversion/strategies/*	创建新的策略子类
detectors/structure_classifier.py	标题检测启发式规则
detectors/reading_order/*	添加自定义排序算法
detectors/footnote_detector.py	添加新的脚注模式

指南请参阅 reference/code-adaptation.md。

---

项目结构

<skill-directory>/
├── SKILL.md                     # This file
├── requirements.txt             # Python dependencies
├── core/                        # FROZEN: Core algorithms
│   ├── epub_builder.py          # EPUB3 file creation
│   ├── pdf_extractor.py         # PDF text/image extraction
│   ├── text_segmenter.py        # Deterministic chunking
│   └── image_optimizer.py       # Image compression
│
├── conversion/                  # Main conversion logic
│   ├── converter.py             # Orchestrator
│   ├── models.py                # Data classes & configs
│   ├── strategies/              # ADAPTABLE: Conversion strategies
│   │   ├── base_strategy.py     # Template method pattern
│   │   └── simple_strategy.py
│   └── detectors/               # ADAPTABLE: Detection heuristics
│       ├── structure_classifier.py
│       ├── reading_order/
│       ├── footnote_detector.py
│       └── endnote_formatter.py
│
├── validation/                  # FROZEN: Quality checking
│   ├── completeness_checker.py
│   └── order_checker.py
│
├── scripts/                     # CLI entry points
│   ├── analyze.py
│   ├── convert.py
│   └── validate.py
│
├── reference/                   # Documentation
│   ├── workflow.md
│   ├── architecture.md
│   ├── troubleshooting.md
│   ├── config-tuning.md
│   └── code-adaptation.md
│
└── examples/                    # Example configurations
    ├── fiction-simple.json
    ├── academic-multicol.json
    └── magazine-images.json

---

配置示例

小说（简单布局）

{
  "page_ranges": {"skip": [1, 2], "content": [3, -3]},
  "exclude_regions": {"top": 0.05, "bottom": 0.05},
  "reading_order_strategy": "y_sort",
  "heading_detection": {"font_size_threshold": 1.2}
}

学术论文（双栏）

{
  "page_ranges": {"skip": [1], "content": [2, -1]},
  "exclude_regions": {"top": 0.08, "bottom": 0.08},
  "reading_order_strategy": "xy_cut",
  "multi_column": {"enabled": true, "threshold": 0.4}
}

杂志（图像与分栏）

{
  "reading_order_strategy": "xy_cut",
  "multi_column": {"enabled": true, "column_count": 2},
  "image_optimization": {
    "enabled": true,
    "max_width": 800,
    "jpeg_quality": 75
  }
}

---

参考文档

详细信息请参阅：

• 工作流详情 - 完整的分阶段指南
• 架构 - 三层系统说明
• 故障排除 - 常见问题及解决方案
• 配置调优 - 所有配置参数
• 代码适配 - 修改代码的时机和方法

---

常用命令

# Full conversion with validation (from skill directory)
python -m scripts.convert input.pdf output.epub && \
python -m scripts.validate input.pdf output.epub

# Analyze PDF structure
python -m scripts.analyze input.pdf

---

质量指标

转换后，请务必检查：

指标	良好	警告	差
文本完整度	> 98%	95-98%	< 95%
阅读顺序	> 90%	80-90%	< 80%
置信度	> 0.8	0.6-0.8	< 0.6

如果任何指标处于“警告”或“差”的范围，请遵循上文的决策树。