# CLAUDE.md (中文版)

此文件为 Claude Code (claude.ai/code) 在本代码库中工作时提供指导。

## 项目概述

这是一个EPUB翻译项目，用于将英文书籍转换为中文。系统从EPUB档案中提取HTML文件，使用各种AI翻译API（DeepSeek、SiliconFlow等）处理和翻译内容，并在SQLite数据库中维护翻译进度。

## 架构设计

### 核心组件

- **翻译引擎**: `/code/` 目录中的主要翻译脚本，处理批量翻译并跟踪进度
- **HTML处理**: 用于EPUB结构的HTML内容提取和清理工具
- **配置管理**: 基于YAML的配置系统，用于API密钥、翻译设置和数据库路径
- **进度跟踪**: SQLite数据库系统，跟踪文件和翻译组的进度
- **EPUB结构**: 组织的目录(001/, 003/, 004/)，包含不同EPUB提取物，HTML文件位于`/Ops/`子目录中

### 主要翻译脚本

- `translate_epub_v4(单线程版本)V3.py` - 原始稳定的单线程翻译脚本
- `translate_epub_v4_optimized.py` - **推荐** 优化版本，具有批量数据库操作和翻译缓存
- `translate_epub.py` - 带异步处理的多线程版本
- `main.py` - 简单的API测试脚本

### HTML处理

- 文件按EPUB结构组织：`META-INF/`、`Ops/`(HTML内容)、`images/`
- HTML文件包含带CSS类的结构化内容（主要是段落的`p34`类）
- 处理脚本清理并准备HTML进行翻译，同时保持结构

## 常用命令

### 运行翻译

```bash
# 推荐：带缓存和批量操作的优化版本（智能跳过已翻译文件）
python code/translate_epub_v4_optimized.py

# 强制重新翻译所有文件（覆盖已存在的文件）
python code/translate_epub_v4_optimized.py --force

# 查看所有可用选项
python code/translate_epub_v4_optimized.py --help

# 原始稳定版本
python code/translate_epub_v4(单线程版本)V3.py

# 多线程版本
python code/translate_epub.py

# 性能对比测试
python code/performance_test.py
```

### 进度监控

```bash
# 检查翻译进度
sqlite3 translation_progress.db "SELECT * FROM translation_progress;"

# 详细文件进度
sqlite3 translation_progress.db "SELECT file_path, ROUND(processed_lines * 100.0 / total_lines, 2) as progress_percent, status, last_updated FROM file_progress;"

# 翻译组进度
sqlite3 translation_progress.db "SELECT file_path, group_index, status, updated_at FROM group_progress ORDER BY file_path, group_index;"

# 检查翻译缓存效果（优化版本）
sqlite3 translation_progress.db "SELECT COUNT(*) as cached_translations, AVG(access_count) as avg_reuse FROM translation_cache;"
```

### 依赖安装

```bash
# 安装所需包
pip install -r code/requirements.txt
```

## 配置

### API配置

系统支持在`code/config.yaml`中配置多个AI翻译提供商：
- DeepSeek API（默认：`deepseek-chat`模型）
- SiliconFlow API 
- Zhipu API（GLM模型）

### 翻译设置

- 可配置的批量大小（最小：3行，最大：10行每请求）
- 带重试逻辑和冷却期的错误处理
- 并发请求限制和超时设置
- 翻译缓存以避免重复翻译相同内容

## 数据库架构

- `translation_progress`: 总体进度跟踪
- `file_progress`: 按文件翻译状态
- `group_progress`: 翻译组/批次状态
- `translation_cache`: 缓存的翻译（仅优化版本）
- `line_progress`: 单行翻译跟踪

## 优化特性 (translate_epub_v4_optimized.py)

### 性能增强

- **智能文件跳过**: 自动检测并跳过已翻译的文件，避免重复工作
- **批量数据库操作**: 将多个数据库写入合并为单个事务（数据库操作快20倍）
- **多级翻译缓存**: 
  - 内存缓存（LRU）用于即时访问
  - 持久化数据库缓存用于会话恢复
  - 基于文件的缓存备份
- **智能进度恢复**: 从中断点高效恢复
- **优化的SQLite设置**: WAL模式、增大缓存大小、内存临时存储
- **命令行选项**: 支持强制重新翻译、跳过缓存等高级功能

### 缓存系统优势

- 避免在文件间重复翻译相同内容
- 持久化缓存在脚本重启后保留
- 相似内容的缓存命中率通常为30-60%
- 自动清理旧的未使用条目

### 监控与统计

- 实时性能指标
- 缓存效果报告
- 数据库操作统计
- 翻译速度跟踪

## 文件组织

- 输入HTML文件：位于编号目录(001/, 003/, 004/)的`/Ops/`子目录下
- 翻译输出：通常保存到`*_translated/`目录
- 归档版本：历史翻译脚本版本存储在`/code/归档/`中
- 配置：YAML文件在`/code/`目录中
- 缓存文件：存储在`/cache/`目录中（优化版本）

## 性能优化建议

### 高优先级优化
1. **使用优化版本脚本**: `translate_epub_v4_optimized.py`提供最佳性能
2. **调整批量大小**: 在`config_optimized.yaml`中根据硬件调整`batch_commit_size`
3. **监控缓存效果**: 定期检查缓存命中率，高重复内容项目收益明显

### 配置调优
- `initial_line_count`: 每组处理行数，增大可提速但可能影响质量
- `cache_size`: 内存缓存大小，根据可用内存调整
- `batch_commit_size`: 数据库批量提交大小，较大值提升性能

### 故障排除

```bash
# 检查缓存统计
sqlite3 translation_progress.db "SELECT * FROM translation_cache LIMIT 10;"

# 查看错误日志
tail -f translation.log

# 重置进度（谨慎使用）
sqlite3 translation_progress.db "DELETE FROM file_progress WHERE status != 'completed';"
```

## 开发提示

- 修改翻译提示词请编辑脚本中的`system`消息内容
- 支持多种编码格式的HTML文件（utf-8, gbk, gb2312, latin1）
- 使用流式输出实时显示翻译进度
- 支持键盘中断时的优雅退出和进度保存

## 性能基准

使用优化版本相比原版本的典型改进：
- 数据库操作速度：提升20-50倍
- 整体翻译速度：提升30-70%（取决于内容重复率）
- 内存使用：更高效的缓存策略
- API调用次数：通过缓存显著减少

---

**提示**: 对于新项目，建议直接使用`translate_epub_v4_optimized.py`以获得最佳性能和用户体验。