feat: Release v0.10 - Modular Architecture & External Config

- Refactor codebase into src/ (preprocessing, translation, assembly) - Add pipeline/ scripts for individual stages - Externalize configuration to config/config.yaml - Fix Cover Image preservation - Update documentation and manuals
2026-01-31 22:49:44 +08:00
parent 9ef82393be
commit 7a93c52b42
306 changed files with 30313 additions and 1071 deletions
@@ -0,0 +1,100 @@
+# ePub Bilingual Translator - Architecture & Data Flow (Revised)
+
+本文档详细描述了程序处理一个 EPUB 文件的完整生命周期。整个流程旨在实现**结构稳定性**（不丢段落）与**内容精细度**（不丢格式）的最佳平衡。
+
+## High Level Data Flow
+
+```mermaid
+graph TD
+    Input[Input EPUB] --> Cleaner[EpubCleaner]
+    Cleaner --> CleanedEPUB[1. Cleaned EPUB Temp]
+    
+    CleanedEPUB --> Profiler[Book Profiler]
+    Profiler -->|Identify| Profile[Book Profile / Style]
+    
+    CleanedEPUB --> Extractor[FineGrainedExtractor]
+    
+    subgraph Extraction
+        Extractor -->|Step 1: P/H Tags| P[Source Paragraph]
+        P -->|Step 2: FormatExtract| PhText[Analyzed Text]
+        PhText -->|Register| Manifest[Manifest DB]
+    end
+    
+    Manifest -->|Batch| LLM[LLM Translation]
+    Profile -->|Prompt Context| LLM
+    
+    LLM -->|Translation| Manifest
+    
+    Manifest --> Restorer[FormatRestorer]
+    Restorer -->|Reconstruct HTML| TargetHtml[Target HTML]
+    
+    CleanedEPUB --> Backfiller[Backfill Engine]
+    TargetHtml --> Backfiller
+    
+    Backfiller -->|Bilingual/Chinese Mode| DOM[Final DOM]
+    DOM --> Builder[BilingualBuilder]
+    Builder --> Output[Output EPUB]
+```
+
+## Detailed Workflow
+
+### 1. Preprocessing (预处理)
+**模块**: `src/epub_cleaner.py`
+*   **Flatten Structure**: 消除嵌套 `div`，统一转为 `<p>`，消除结构性漏译风险。
+*   **Auto-Fix**: 修复 TOC 死链、缺失 UID、由于 `ebooklib` bug 导致的样式丢失。
+*   **Result**: 产生一个标准的临时文件，后续所有操作基于此文件，不再受原始糟糕格式影响。
+
+### 2. Intelligent Extraction (智能提取)
+**模块**: `src/fine_grained_extractor.py` + `src/format_extractor.py`
+
+#### A. 结构层 (Macro)
+使用 `FineGrainedExtractor` 锁定所有正文元素 (`p`, `h1`-`h6`)。
+*   **Filter**: 排除页码、页眉脚。
+*   **Optimization**: 针对目录章节，识别 **罗马数字 (I, II)**、**单独数字 (1, 2)**、**修饰符 (***)**，这些内容**不送翻译**，直接在回填时保留原文，以维持原书排版美感。
+
+#### B. 内容层 (Micro)
+对每个提取的段落调用 `FormatExtractor`：
+*   **Inline Style**: 将 `<b>`, `<i>` 转为配对占位符 `φ1φ...φ/1φ`。
+*   **Formula Protection**: 识别 $E=mc^2$ 等数学公式，保护为不可变占位符。
+*   **Drop Cap Handling**: 
+    - 原始: `<span class="dropcap">T</span>he`
+    - 提取给 LLM: "The" (完整单词，无格式干扰)
+    - 记录: Prefix 包含 Drop Cap 样式。
+
+### 3. Manifest Management (清单管理)
+**模块**: `src/manifest_manager.py`
+Manifest 是系统的**核心状态中心 (Source of Truth)**。
+*   **作用**: 解耦提取和翻译。提取器只管往 Manifest 填数据，翻译器只管从 Manifest 取数据。
+*   **Persistence**: 支持中断续传，翻译进度实时保存。
+
+### 4. Translation with Profiling (翻译)
+**模块**: `src/book_profiler.py` & `src/translator.py`
+*   **Profiling**: 在翻译前，抽取部分文本分析书籍的类型（技术、小说、诗歌）、核心术语和语言风格，生成 `System Prompt`。
+*   **Translation**: 这是纯文本层面的转换，LLM 处理的是带有 `φ` 占位符的文本。
+
+### 5. Robust Restoration (健壮还原)
+**模块**: `src/format_restorer.py`
+负责将 LLM 返回的文本还原为 HTML。
+*   **Drop Cap Logic**: 
+    - **原文回填**: 需要 Prefix `<span class="dropcap">T</span>`。
+    - **译文回填**: **丢弃** Drop Cap Prefix。中文不需要首字母下沉，否则会出现 "T这本书..." 的怪诞结果。
+*   **Error Handling**:
+    - **Missing Placeholders**: 如果 LLM 丢了 `φ1φ`，自动在末尾补全或报错重试。
+    - **Hallucinated Placeholders**: 移除 LLM 臆造的不存在 ID。
+
+### 6. Backfill Strategy (回填策略)
+**模块**: `src/fine_grained_extractor.py` (backfill method)
+支持多种模式，且**严格遵循一对一 (One-to-One) 映射**，绝不依赖顺序，而是依赖元素的内存引用或唯一 ID。
+
+*   **Mode A: Bilingual (双语)**
+    - 保留原文 DOM。
+    - 在原文后 `append` 一个新元素 `<p class="translation">译文</p>`。
+    - 样式继承：译文元素复制原文的 `margin`, `text-align` 等关键样式。
+
+*   **Mode B: Chinese Only (仅中文)**
+    - **Replace**: 直接用译文元素替换原文元素。
+    - **Drop Cap 适配**: 此时译文通常为普通段落，不再保留首字母下沉样式，以符合中文排版习惯。
+
+### 7. Assembly (组装)
+**模块**: `src/bilingual_builder.py`
+将内存中的 DOM 序列化，重新打包资源，生成最终 EPUB。