v0.3.6 完善 PDF 支持和图片资源处理，优化术语抽取上下文开销

新功能

• 新增实验性 PDF 导出，可通过 --format pdf 使用。
• 提供两种 PDF 渲染引擎：
  • WeasyPrint：排版和 CSS 支持更完整。
  • fpdf2：更轻量、跨平台，但只支持基础 HTML/CSS。
• 新增 --pdf-engine weasyprint|fpdf2 选项。
• HTML/XHTML 输入新增对 picture、source、figcaption 和图片资源的处理。
• 支持将本地资源和 Data URI 图片打包到 HTML、EPUB 与 PDF 产物中。
• 新增 .xhtml 输入支持。
• 新增 trans-novel --version 命令。

PDF 导出依赖按需安装：

# 默认引擎
uv sync --extra pdf-output

# 轻量引擎
uv sync --extra pdf-output-lite

图片与 EPUB 修复

• 修复 MinerU 转换后的 PDF 图片在导出 EPUB 时丢失的问题。
• PDF 转换产物现在会从缓存 HTML 所在目录正确解析图片。
• 改进 <picture>、srcset、内嵌图片和图注的保留。
• 仅含图片、没有正文文字的 HTML 章节不再被跳过。
• EPUB 内部书名现在会区分目标语言和单语/双语版本：
  • 原书名-wenyi-zh
  • 原书名-wenyi-zh-bi

术语抽取优化

• 术语抽取提示词只注入在全书中出现至少两次的已有术语，减少长书的 Token 占用。
• 只出现一次的术语仍会正常保存在术语数据库中，不会被删除。
• 全文匹配结果采用惰性缓存，同一次运行不再重复扫描全文。
• 支持合并术语原文与别名的出现次数。
• 为拉丁、希腊和西里尔文字增加单词边界判断，避免俄文等语言中的短术语误命中更长单词。

版本与构建

• 包版本改为从 Git 标签自动生成，不再在多处手工维护版本号。
• 开发版本会显示距最近标签的提交数和提交哈希。
• PyInstaller 构建会保留包版本元数据。
• 发布构建增加 --version 冒烟测试。
• 测试现在会在推送到 main 和 dev 时自动执行。

文档

• 重构中英文 README，补充：
  • 项目定位与核心能力
  • 一键翻译与分步工作流
  • 支持格式
  • Mermaid 翻译流水线图
  • 项目限制与社区入口
• 完善实验性 PDF 输入与导出说明。
• 更新安装、版本查询和可选依赖文档。

注意事项

• PDF 输入和 PDF 输出仍属于实验性功能。
• fpdf2 的 HTML/CSS 支持有限，复杂排版可能与 EPUB 或 WeasyPrint 结果不同。
• fpdf2 需要可用的中文字体；自动查找失败时可设置：

export TRANS_NOVEL_PDF_FONT=/path/to/font.ttf

致谢

感谢 @Jiang1312 对 PDF 输出与 HTML 图片支持的贡献。

感谢 @Misaka0x26FE 对中英文 README 结构与内容的改进。

v0.3.5 提升模型兼容性、最终审校可靠性和长篇小说术语一致性

新增功能

• 原生支持 Google Gemini，使用官方 google-genai SDK。
• 支持 Gemini 思考等级、思考预算、超时控制及思考 Token 统计。
• 新术语在后续章节才被发现时，会回查其首次出现的原文和译文，优先沿用已有译名，减少前后译名冲突。
• 导出 EPUB 的书名元数据自动追加 -wenyi，便于区分原书与译制版本。

稳定性改进

• Reviewer 增加完成回执，验证实际审校段数，避免把截断响应误认为完整结果。
• 使用 json-repair 本地修复模型返回的畸形 JSON，并统一 JSON 容错逻辑。
• 审校输出异常时自动拆分受影响的文本块并重试；单段重试次数可通过 review_output_retries 配置。
• 持续失败的审校会明确标记失败，不再静默遗漏结果。
• status、report、glossary 和 assemble 等本地命令不再强制要求 API Key。

工程维护

• 引入 Ruff 和 pre-commit，统一格式化、导入排序及静态检查。
• GitHub Actions 使用锁定依赖，在 Python 3.10 和 3.12 上运行离线测试。
• 移除未使用的翻译记忆表和术语库辅助代码。
• 收紧异常处理和类型注解，减少静默错误与维护负担。

配置说明

新增可选配置：

pipeline:
  review_output_retries: 2

表示单段审校输出异常时额外重试两次；不填写时使用默认值。

v0.3.4 改善 EPUB 解析与结构回填，并优化错误提示

EPUB 兼容性与结构保留

• 支持将没有子正文块的 <div> 识别为正文，修复部分 EPUB 章节正文为空的问题。
• 优先翻译嵌套结构中的叶子节点，避免回填时破坏 <ul>、<li>、<blockquote> 等结构。
• 目录列表只替换链接文字，保留原有 href 和列表层级。
• 将 <br> 分隔的视觉行解析为独立翻译段，保留原始换行位置，不再转换成不合理的 \n\n。
• 改善双语 EPUB 的行内结构，避免生成嵌套 <p> 等无效 HTML。
• 忽略 Ruby 注音的 <rt> 和备用括号 <rp>，防止注音或空括号进入待翻译正文。
• 继续保留图片、空锚点等内联元素的位置。

CLI 配置检查

• 除纯导出 assemble 外，所有命令都会在运行前检查模型 API Key。
• API Key 缺失时直接显示明确错误，不再等到语言识别或模型调用阶段才以无关错误退出。
• --help、Fake provider、Ollama 和 vLLM 等无需 API Key 的场景不受影响。

碎碎念

现阶段就是扣一些细节上的问题了，虽然改动不大，但却是实实在在地优化着，大家遇到问题可以及时反馈。绝大多数时候只能自己测试优化，有疏忽的地方在所难免，希望大家使用的时候都顺心❤️

v0.3.3 重构章节切分逻辑，增加防呆设计

• 改进 EPUB 章节识别：按顶层目录划分章节，支持单个 XHTML 包含多章及单章跨多个文件。
• 完整翻译并回写 NCX/NAV 目录标题，同时保留章节锚点与内部跳转。
• 优化 EPUB 内联元素回填，保留图片、链接、换行等结构，并减少状态文件中的冗余数据。
• 增加源语言与目标语言相同检查，避免误启动无效翻译。
• 增强对混合目录、异常目录及 .xml 格式 NCX 的兼容性。

v0.3.2 整理 CLI 工作流，让各阶段命令更直观

Wenyi v0.3.2

本次更新主要整理 CLI 工作流，让各阶段命令更直观。

更新内容

• 新增独立 prepare 命令，仅解析、分析风格、生成初始术语表和预扫全书。
• translate 仍是一键完整流程，重复运行即可断点续跑。
• review、qa、report、assemble 改为顶层命令。
• 术语命令统一为：
  • glossary list
  • glossary conflicts
  • glossary resolve
• translate 新增 --review/--no-review 开关。
• 优化命令帮助、参数说明和错误提示。

命令迁移

resume book.epub
# 改为
translate book.epub

translate book.epub --prepare
# 改为
prepare book.epub

tools qa/report/assemble
# 改为
qa/report/assemble

tools glossary book.epub list
# 改为
glossary list book.epub

除 CLI 结构调整外，翻译流程和已有状态数据不受影响。

v0.3.1 进一步拆分翻译流程，并改善审校与导出体验

本次更新进一步拆分翻译流程，并改善审校与导出体验：

• 新增独立的全书审校命令，支持并行审校、断点续跑、强制重审和自动修复。
• 新增 translate --prepare，可只完成解析、风格分析、初始术语表和全书预扫。
• 全书审校改为默认关闭，由用户在翻译完成后按需执行。
• 双语版本新增保留原文样式选项。
• 改善 HTML 输出的编码声明。
• Release 发布后自动构建并上传 Windows、Linux 压缩包及校验文件。

值得注意的是，将review独立出来并默认关闭是为了大家翻译完毕可以手动审校术语库，删去没必要的术语，避免review出来一堆没用的建议。与此同时，完整翻译正文后，review就可以带上完全体的术语库（当然章内匹配到的术语才进入上下文），这样可以优化跨章一致性的扫描。

v0.3.0 — PDF / HTML / Markdown 支持与长篇翻译可靠性升级

Wenyi v0.3.0

本版本进一步扩展了 Wenyi 支持的文档格式，并重点增强长篇翻译中的断点续跑、电子书内容保留、术语一致性和异常恢复能力。

新增格式支持

• 新增 PDF 输入支持（感谢 @Jiang1312）
  • 通过 MinerU 将 PDF 转换为 HTML 后进入翻译流程
  • 超过 200 页的 PDF 会自动拆分处理
  • 转换结果缓存至书籍状态目录，可在续跑时复用
  • 首次使用需要配置 MINERU_API_KEY
• 新增 Markdown 和 HTML 输入支持
• 新增 HTML 和 Markdown 输出格式
• Markdown 标题层级可在解析和输出过程中保留
• CLI 的 --format 现在支持：
  • epub
  • txt
  • html
  • markdown

PDF 支持目前以文本和 HTML 内容转换为主，效果取决于 MinerU 的转换结果。

EPUB 与 FB2 内容保留

• EPUB 现在可以保留段内图片、换行、SVG、MathML、音视频等原子内联元素
• 日文振假名的 <rt> 内容不再被重复送入翻译
• 支持提取表格单元格和定义列表中的文本
• 提升了非规范 EPUB、旧编码 EPUB 的解析容错能力
• FB2 内嵌图片与封面可被识别并重新写入导出的 EPUB
• 改进 FB2 编码声明和命名空间兼容性

译文文本仍会使用干净的文本结构，不强行保留可能因语序变化而错位的强调、链接或 ruby 文本标签。

翻译可靠性提升

• 严格校验模型返回的翻译数组：
  • 必须是数组
  • 数量必须与输入一致
  • 每项必须是非空字符串
• 批量翻译对齐失败后可逐段重试
• 逐段重试仍失败时明确中止当前批次，避免用空字符串污染译文
• 已成功保存的批次不会丢失，可从失败位置继续翻译
• 改进 OpenAI 兼容接口的 JSON 模式提示，适配要求消息中显式包含 json 的服务
• 对模型返回的术语、人物和审校结果增加类型与范围校验

更可靠的断点续跑

• 初始化流程改为原子提交：
  • 文档解析、风格分析和上下文准备全部完成后，才将状态标记为可续跑
  • 初始化中断后重新运行会正确重试
• 已完成和未完成的段落会沿边界重新分批
• 修改批次大小后续跑，也不会覆盖已经完成的译文
• 翻译进度从已有完成数量开始显示
• PDF 转换缓存位于对应书籍的状态目录中，续跑时无需重复转换
• 独立 QA 命令会从 manifest 恢复实际语言，不再把 auto 直接传给模型

并发与状态安全

• 增加书籍级跨进程文件锁，避免同一本书被多个进程同时修改
• manifest、章节状态等关键文件采用原子写入
• 术语库写入增加事务和并发等待处理
• 审校并发、术语抽取和章节状态保存更加稳定

术语与翻译一致性

• 术语匹配增加 Unicode NFKC 标准化和大小写折叠
• 改进全角、半角以及大小写差异下的术语识别
• 加强术语抽取结果清洗，避免异常 JSON 字段破坏术语库
• 更明确地约束敬称、人物称谓和特殊表达的全书一致性

中文标点处理

• 跨段引号状态只在同一原始长段落的续段间传递
• 避免缺失引号污染后续无关段落
• 改进中英文混排和英文所有格处理
• 翻译提示词进一步要求保留原文中的特殊标点、符号及其句内结构

CLI 与配置体验

• 任意 CLI 命令启动时都会检查并生成默认配置文件
• 增加输入路径、章节编号和输出格式校验
• PDF 转换、文档解析等常见错误现在会显示更友好的提示
• 移除未文档化的 custom provider 别名，统一使用 openai-compatible
• 新增完整的英文 README、使用文档、配置文档和贡献指南
• 中文文档统一整理至 docs/zh/

开发与测试

• 新增 pytest 开发依赖组，克隆后可直接运行测试
• 补全主要函数的文档字符串
• 清理旧兼容代码和无效流水线逻辑
• 当前测试结果：
  • 200 passed
  • 11 subtests passed
  • Ruff 检查通过

v0.2.0：多模型支持、双语输出与体验优化

更新日志

本文件记录文译（Wenyi）的重要版本变化。

0.2.0 - 2026-07-14

0.2.0 是一次功能与架构并重的版本更新。该版本扩展了模型提供商支持，完善了
单语和双语书籍输出，提高了长篇翻译的续跑效率，并加入了按书持久化的 Token
用量统计。

主要更新

• 重构 LLM 层，将通用接口、档位解析、JSON 解析和各模型提供商实现拆分维护。
• 新增 OpenAI、OpenRouter、OpenAI 兼容接口、Ollama 和 vLLM 支持，继续支持
  DeepSeek 与离线 Fake provider。
• 支持 DeepSeek、OpenAI 和 OpenRouter 不同的推理参数格式；通用兼容接口可通过
  reasoning_style 和档位 options 适配中转站或私有服务的特殊参数。
• 单语译本默认输出到源文件目录下的 output/；可选生成双语 EPUB，并配置原文
  与译文的排列顺序。
• 可在 EPUB 末尾附加“关于此翻译”说明页，默认开启，可通过
  output.about_page 关闭。
• 每本书在状态目录中增量维护 usage.json，按模型档位和流水线阶段统计输入、
  输出、缓存命中与总 Token；续跑时继续累计。
• 预处理、全书理解和审校阶段提供更细化的进度显示；章末审校支持并行执行。
• 续跑时根据已完成段落恢复全书进度，不再从零显示；已完成批次的术语提取通过
  事件检查点恢复，避免重复调用模型。

输出与排版

• 新增单语、双语输出开关，默认只生成单语译本。
• 双语版支持 target_first 和 source_first 两种排列方式。
• 修复列表和引用块在双语 EPUB 中被拆出原容器的问题。
• EPUB 输入继续保留原有样式、图片、目录、锚点和 XHTML 模板结构。
• 报告文件不再重复保存 Token 用量，usage.json 成为用量统计的唯一数据源。

模型提供商与请求兼容

• DeepSeek provider 内置默认服务地址、API Key 环境变量和三档模型配置。
• provider 专属参数移入档位的 options，避免通用配置模型被单一提供商字段污染。
• thinking: false 会向支持的提供商显式发送关闭推理的参数，避免模型采用服务端
  默认思考模式。
• OpenAI 请求使用 max_completion_tokens，兼容推理模型和新版 SDK。
• JSON mode 请求会明确在提示中包含 json，兼容要求提示词声明 JSON 输出的服务。
• 统一读取 DeepSeek 顶层缓存统计与 OpenAI 风格的
  prompt_tokens_details.cached_tokens。
• 通用 OpenAI 兼容 provider 支持 request_overrides，便于传递中转站或私有模型的
  扩展请求字段。

翻译流水线与续跑

• 预扫逐章梗概和章末审校均支持可配置并发。
• 全书概览、逐章梗概、风格分析等准备阶段使用独立进度显示。
• 修复阶段切换时进度条沿用上一步计数的问题。
• 续跑进度包含已经翻译的段落，并以全书可翻译段落数量作为总数。
• 为批次术语提取增加持久化完成事件；进程中断后可从未完成批次继续。
• 用量数据在每次模型调用后增量持久化，降低异常退出时统计丢失的风险。

文档解析与术语库

• FB2 的 <body><title> 作为独立可见章节保留，不再丢失作者或书名页。
• 支持缺少标准命名空间或使用不同命名空间形式的 FB2 文件。
• 移除未参与实际工作流的术语 confidence 和 locked 字段。
• 打开旧术语数据库时会自动迁移表结构并保留已有术语内容。
• 术语冲突保留当前译法，同时记录候选译法供人工检查。

配置与默认行为

• 默认生成单语版；双语版需要通过配置或命令行显式开启。
• 默认输出目录改为源文件旁的 output/。
• 配置文件、Pydantic 默认值和文档中的流水线开关已统一。
• 项目声明支持 Python 3.10 及以上版本。
• 新增和扩充配置、使用方法、流水线及双语输出文档。

升级注意事项

LLM 档位配置格式

0.1.1 将 provider 专属字段直接放在档位下：

llm:
  tiers:
    strong:
      model: deepseek-v4-pro
      thinking: true
      reasoning_effort: high

0.2.0 将这些字段移入 options：

llm:
  tiers:
    strong:
      model: deepseek-v4-pro
      options:
        thinking: true
        reasoning_effort: high

继续使用旧格式会触发配置校验错误。升级前请参照 config.yaml 或
docs/configuration.md 调整现有配置。

Python 导入路径

LLM provider 已从原来的单文件实现拆分到 trans_novel.llm.providers。命令行用户
不受影响；直接导入旧内部类的第三方代码需要改用新的 provider 模块或
trans_novel.llm.factory.build_client。

状态与统计文件

• 旧章节状态可以继续用于断点续跑。
• 旧术语数据库会自动迁移，仍建议在首次使用 0.2.0 前备份对应书籍的状态目录。
• Token 用量仅以状态目录中的 usage.json 为准，report.json 不再包含重复副本。

验证

• 完整单元测试：150 项通过。
• Ruff 静态检查通过。
• 构建工作流提供 Windows x64 与 Linux x64 单文件可执行程序。

v0.1.1 打包Windows与Linux下可执行文件供大家使用

翻译稳定性

• 加固 LLM JSON 解析：
  • 容忍尾部多余 } 等垃圾字符。
  • 容忍译文中未转义的英文双引号。
  • 修复“未转义引号 + 尾部多余字符”同时出现时丢失外层 JSON 对象的问题。
• 补充对应回归测试，避免模型偶发格式不规范导致整批翻译中断。

质量与成本

• 优化翻译提示词的缓存顺序：
  • 风格指南 → 全书概览 → 本章梗概 → 术语表 → 前文 → 正文
  • 把章内固定的梗概前移，让更长前缀可命中模型缓存。
• 定向重译提示词同步采用相同顺序。
• 移除了术语 Audit：
  • 不再用模型猜测全书译名变体并自动全局替换正文。
  • 保留实时术语入库、冲突记录、人工锁定和一致性报告。
  • 降低误改正文和功能认知误差。

使用体验

• 进度展示优先显示书内真实章节标题，不再只按内部章节序号。
• 缺少 config.yaml 时自动在当前目录创建带注释的默认配置，已有配置绝不覆盖。

v0.1.0 - Initial Release

这是最初版本的发布，项目现状态运行良好，如果感兴趣的朋友可以去z站看最新上传的村上春树《夏帆》的AI译本。