kanlac/read-book

读书：翻译与讨论

两种模式

模式一：双语翻译

将英文 epub 翻译为中英对照版。每段英文下方插入中文翻译，保留原书排版。

核心原则：

• 上下文翻译：每批段落附带前文作为 context，确保译文自然衔接，消除孤立翻译导致的突兀感
• 样式继承：翻译段落使用与原文相同的 HTML 标签和 CSS class（标题译为标题大小，正文译为正文大小），不使用统一的翻译样式类
• 标记区分：所有翻译段落添加 lang="zh" 属性，便于后续过滤
• 去重：只翻译最内层元素——当 <li> 内嵌套 <p> 时，只翻译 <p>，避免重复
• 跳过无需翻译的内容：署名行（"—Eric Raymond"）、纯人名等本身就是英文的短段落不翻译
• 表格特殊处理：<td> 中的翻译用 <br/> + <span lang="zh"> 追加在同一单元格内，不创建兄弟节点（否则会破坏表格结构）
• 翻译模型：默认策略是省算力优先
  • Claude 家族默认走 sonnet（不是 Opus）
  • GPT/CodeX 默认走当前可用的最新 GPT 模型（低算力优先），并使用 low effort
  • 也支持 --translator codex，走 codex exec --skip-git-repo-check --output-last-message；
    也支持 --translator custom --translator-cmd "<cmd>" 自定义翻译命令。
• 中文排版：衬线字体（Noto Serif SC / Source Han Serif / Songti SC），翻译段落与下一段英文之间留出足够间距

使用方法：

# 翻译整本书
python3 ${SKILL_PATH}/scripts/translate_epub.py input.epub -o output.epub

# 使用 Codex 进行翻译（headless）
python3 ${SKILL_PATH}/scripts/translate_epub.py input.epub -o output.epub --translator codex

# 使用自定义命令（接入任意 Headless 翻译器）
python3 ${SKILL_PATH}/scripts/translate_epub.py input.epub -o output.epub --translator custom --translator-cmd "python3 my_translator.py"

# 只翻译前 N 个内容文件（适合先试看效果）
python3 ${SKILL_PATH}/scripts/translate_epub.py input.epub -o output.epub --max-files 5

环境变量：

# 覆盖默认翻译后端（claude / codex / custom）
export READ_BOOK_TRANSLATOR=codex

# custom 后端调用命令（可省略 --translator-cmd）
export READ_BOOK_TRANSLATOR_CMD='python3 my_translator.py'

# 可选：给 codex 的模型参数（留空走默认最新 GPT）
export READ_BOOK_TRANSLATOR_MODEL=latest

# 可选：给 GPT/CodeX 的 effort（默认 low）
export READ_BOOK_TRANSLATOR_EFFORT=low

脚本需要 lxml。首次运行前：

python3 -c "from lxml import etree; print('ok')"
# 如果缺失，在 venv 中安装：uv venv /tmp/book-venv && source /tmp/book-venv/bin/activate && uv pip install lxml

经验沉淀（避免重复问题）

Negative few-shot（禁止行为）

• 遇到以下输出时认为本次翻译失败，必须重跑：
  • 我会先...按这个格式返回...
  • 以下是第X段的翻译：
  • I will translate... / I can't translate image...
  • 任何说明模型流程、输出格式、进度或自我评价的句子
• 只允许输出 "[N] 中文" 行；若有任一行不是译文或不包含中文编号段落，立即判定污染。

自动补齐闭环（目标行为）

• 全量执行默认开启：每个批次先做翻译 → 自动检测缺漏/污染 → 自动补齐（先单段重跑，默认 2 轮）→ 最终写入 EPUB。
• 默认脚本会自动给出 已翻/应翻/未补齐 统计，不需要手工中断和二次分发命令。

验收规则（最小闭环）

• 先跑 --max-files 1~3，只看两个信号：是否出现 lang="zh" 译段，是否有说明性文本夹杂。
• 通过后再继续全量；不通过则回退到更小批次并单段补齐，不直接重放全量。
• 全量后仍有系统说明文本或大规模缺段，改用 --translator custom 并重跑新文件名。

模式二：阅读与讨论

当用户想讨论一本书的内容时：

读双语 epub： 带 lang="zh" 属性的段落是机器翻译，仅供用户阅读参考。Agent 分析和讨论时只读原文段落，忽略 lang="zh" 的翻译段落，以原文为准。

读普通 epub： epub 本质是 zip 包，解压后在 OEBPS/ 目录下找 .xhtml 文件，按 content.opf 中的 <spine> 顺序阅读。

讨论方法：

• 先通读目录（TOC），建立全书结构认知
• 按用户指定的章节或主题深入阅读
• 讨论时引用原文关键段落，给出分析和观点
• 将书中观点与更广泛的知识联系起来，提供跨领域洞察