# 纯中文模式格式丢失问题 - 深度分析

## 🔴 根本原因：Mode 参数未被正确传递

### 问题概述

当前 `translator.py` 的 `translate_epub()` 方法签名只有 3 个参数：
```python
async def translate_epub(self, epub_path: str, test_mode: bool = False, output_dir: str = None) -> str:
```

**缺失 `mode` 参数！** 这意味着：
1. 无论用户指定 `-m chinese` 还是 `-m bilingual`，都走相同的代码路径
2. 永远使用 `BilingualEPUBBuilder`
3. 格式提取功能 (`format_extractor.py`) 从未被调用

---

## 问题链路分析

### main.py 调用
```python
# main.py:55-59
await translator.translate_epub(
    args.epub_path,
    test_mode=args.test,
    output_dir=args.output,
    mode=args.mode  # ❌ 此参数被忽略！因为 translate_epub 不接受 mode
)
```

### translator.py 未处理 mode
```python
# translator.py:39 - 缺少 mode 参数
async def translate_epub(self, epub_path: str, test_mode: bool = False, output_dir: str = None) -> str:

# translator.py:53 - 提取时未传 mode
self.text_processor.extract_to_manifest(item['content'], item['file_name'], manifest)
# 应该是: extract_to_manifest(..., mode=mode)

# translator.py:72 - 分块时未传 mode
chunks = self.text_processor.create_chunks_from_manifest(manifest)
# 应该是: create_chunks_from_manifest(manifest, mode=mode)

# translator.py:84 - 永远使用 BilingualBuilder
builder = BilingualEPUBBuilder(self.parser.book, self.config)
# 应根据 mode 选择 ChineseEPUBBuilder
```

---

## 完整的格式保留流程 (应有逻辑)

```
┌─────────────────────────────────────────────────────────────────┐
│ 1. 提取阶段 (format_extractor.py)                               │
│    Input:  <p>This is <strong>bold</strong> text.</p>           │
│    Output:                                                       │
│      - clean_text: "This is bold text."                         │
│      - text_with_placeholders: "This is φc00001φboldφc00002φ text." │
│      - placeholder_map: {c00001: "<strong>", c00002: "</strong>"} │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. 翻译阶段 (llm_client.py)                                      │
│    Prompt: p_00001 [BODY] This is φc00001φboldφc00002φ text.    │
│    LLM Response: p_00001 这是φc00001φ粗体φc00002φ文本。          │
│    ⚠️ 问题：LLM 可能丢失/错放占位符！                            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. 还原阶段 (format_restorer.py)                                 │
│    Input:  "这是φc00001φ粗体φc00002φ文本。"                      │
│    Output: "这是<strong>粗体</strong>文本。"                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. 构建阶段 (chinese_builder.py)                                 │
│    使用 translation_with_original_html 替换原始内容               │
└─────────────────────────────────────────────────────────────────┘
```

**当前状态**: 步骤 1、3、4 从未执行！

---

## LLM 占位符丢失的常见原因

即使修复了 mode 传递问题，LLM 仍可能丢失占位符：

| 原因 | 示例 | 解决方案 |
|------|------|----------|
| 占位符被"翻译" | φc00001φ → φ中00001φ | 强调 Prompt: "φ...φ 是代码，禁止修改" |
| 占位符位置错误 | 原: Aφc1φB → 译: φc1φAB | 修复 Agent (repair_format) |
| 占位符完全丢失 | 原: φc1φ → 译: (无) | 后处理：从原文恢复 |
| 幻觉占位符 | 原: (无) → 译: φc99φ | 忽略未知 ID |

---

## 修复建议

### 修复 1: translator.py 添加 mode 参数

```python
async def translate_epub(self, epub_path: str, test_mode: bool = False, 
                         output_dir: str = None, mode: str = "bilingual") -> str:
    # ...
    
    # 提取时传递 mode
    self.text_processor.extract_to_manifest(item['content'], item['file_name'], manifest, mode=mode)
    
    # 分块时传递 mode
    chunks = self.text_processor.create_chunks_from_manifest(manifest, mode=mode)
    
    # 翻译时传递 mode
    await self._translate_concurrently(chunks, manifest, profile, mode=mode)
    
    # 构建时选择正确的 Builder
    if mode == "chinese":
        builder = ChineseEPUBBuilder(self.parser.book, self.config)
        result_file = builder.create_chinese_epub_with_mapping(manifest.get_items(), output_path)
    else:
        builder = BilingualEPUBBuilder(self.parser.book, self.config)
        result_file = builder.create_bilingual_epub_with_mapping(...)
```

### 修复 2: llm_client.py 添加占位符指令

```python
if mode == "chinese":
    base_sys_prompt += """

Placeholder Instructions:
1. Text contains φcXXXXXφ placeholders representing HTML formatting.
2. These are CODE tokens - DO NOT translate, modify, or remove them.
3. Keep placeholders in corresponding positions in your translation.
4. Example: "This is φc00001φboldφc00002φ text." → "这是φc00001φ粗体φc00002φ文本。"
"""
```

### 修复 3: 增强 format_restorer.py 容错

```python
def restore(self, text_with_placeholders, placeholder_map):
    # 如果 LLM 完全丢失占位符，尝试智能合并
    if not self.PLACEHOLDER_REGEX.search(text_with_placeholders):
        logger.warning("所有占位符丢失，降级为纯文本")
        return text_with_placeholders, False
    
    # 现有逻辑...
```

---

## 优先级

| 优先级 | 修复项 | 工作量 |
|--------|--------|--------|
| P0 | translator.py 传递 mode 参数 | 小 |
| P0 | translator.py 选择正确 Builder | 小 |
| P1 | llm_client.py 占位符 Prompt | 小 |
| P2 | format_restorer.py 容错增强 | 中 |
| P2 | repair_format 机制完善 | 中 |