TRANSLATE-BOOK —— AGENT SKILL · 中文导读

一整本书,并行翻译

面向 Codex、Claude Code 和 OpenClaw 的 Agent Skill。把 PDF / DOCX / EPUB 拆成 chunk,交给一批批全新上下文的子代理并行翻译,经 manifest 校验后合并成 HTML、DOCX、EPUB、PDF 四种成品。

原书 PDF · DOCX · EPUB · Markdown 拆块 + manifest 8 路子代理 / 批 校验 · 合并 译本 HTML · DOCX · EPUB · PDF

§ 01一句话理解

ONE CHUNK, ONE FRESH CONTEXT
单会话翻译 整本书进一个会话→ 上下文堆积→ 输出截断
TRANSLATE-BOOK 拆成 ~6000 字符的 chunk→ 1 chunk = 1 子代理→ manifest 校验后合并

核心做法:每个 chunk 由一个拥有全新上下文窗口的子代理翻译,避开整书单会话的上下文堆积和输出截断;跨 chunk 的一致性不靠记忆,而靠术语表、邻居摘录和可续跑的状态文件。

§ 02六个核心部件

SIX MOVING PARTS · scripts/

SKILL.md 负责编排,确定性的事情交给 scripts/ 里的 Python。下面每一张卡都指向 main 分支上的一个脚本。

01CONVERT & SPLIT 转换与拆块 Calibre 把原书转成 HTMLZ,再转 Markdown 并拆成 chunk0001.md…;脚注转成全书连续编号的 Pandoc 脚注。Markdown 输入(MinerU / Marker 的输出)直接跳过 Calibre,公式块不会被拆开。 scripts/convert.py→ 02SHA-256 MANIFEST 清单与校验 记录每个源 chunk 的 SHA-256;合并前核对源与输出 1:1 对应、源未在拆分后改动、输出非空非纯空白、脚注标记一个不少。source_fingerprint.json 防止换了源文件却复用旧 chunk。 scripts/manifest.py→ 03TERM CONSISTENCY 术语表 抽样 5 个 chunk 建 glossary.json(v2 schema,含别名、性别、置信度),统计全书词频;每个 chunk 翻译前注入一张「原文 | 别名 | 译文」三列表,作为硬性约束。 scripts/glossary.py→ 04NEIGHBOR CONTEXT 邻居上下文 给每个子代理附上前一个 chunk 末尾、后一个 chunk 开头各约 300 字的只读摘录,只用来判断代词、性别和实体,不翻译、不抄进输出。不新增状态文件。 scripts/chunk_context.py→ 05FEEDBACK MERGE 观察回流 子代理在译文之外写一份 output_chunkNNNN.meta.json(schema 在 meta.py):新实体、别名猜测、属性、冲突。每批结束后 merge_meta.py 把它们保守地合进术语表,需要判断的交给主代理。 scripts/meta.py · merge_meta.py→ 06SELECTIVE RE-TRANSLATE 精确重译 run_state.json 按 chunk 记下用过的术语表版本、实体与各类 hash。术语表或源文改了,plan 只挑出真正受影响的 chunk 重译;中断后重跑会跳过仍然有效的输出。 scripts/run_state.py→

另外还有:merge_and_build.py(合并 chunk → Pandoc HTML → Calibre 出 DOCX / EPUB / PDF)、calibre_html_publish.py(Calibre 转换封装)、两份 HTML 模板,以及 figure_text.py(把图片里的文字转写成 sidecar 再注入 chunk,让它走同一条翻译流程;脚本已在 main,SKILL.md 目前还没有把它编排进流程)。

§ 03流水线总目

SKILL.md · WORKFLOW STEPS

左边的编号就是 SKILL.md 里的步骤号。主代理按这张台账依次推进;每一行下方是这一步实际调用的脚本或产物。

1 收集参数输入文件(必填)、目标语言(默认 zh)、每批并发数(默认 8),以及可选的 temp 目录、EPUB 封面、导出文件名和自定义指令。file_path · target_lang · concurrency PARAMS 2 转换为 Markdown chunk生成 {book}_temp/:chunk、manifest、源文件指纹和 config.txt。公式表格密集的 PDF 建议先用 MinerU / Marker 转 Markdown。convert.py → chunk*.md · manifest.json · source_fingerprint.json CONVERT 3.5 建术语表在步骤 3 找齐源 chunk 之后,抽样提取专有名词与领域术语并统计词频。已存在的 glossary.json 不会被覆盖,手工修改得以保留。glossary.py count-frequencies GLOSSARY 3.7 规划要翻译哪些 chunk把 chunk 分成「需要翻译」「只需补记录」「无需处理」三类,前者就是这次的工作队列。run_state.py plan PLAN 4 并行子代理翻译每批最多 8 个子代理,各自读一个 chunk、拿到专属术语表和邻居摘录,写出译文和 meta 文件。以文件落地为准判断一批完成,再发下一批。output_chunkNNNN.md · output_chunkNNNN.meta.json TRANSLATE 4.5 每批之后合并观察先 record 本批输出,再把子代理的观察合进术语表:无冲突的自动应用,别名与冲突由主代理裁决。run_state.py record · merge_meta.py prepare-merge / apply-merge MERGE META 5 校验完整性并重试缺失的 chunk 最多重试一次;检查全书标题层级(它决定电子书目录)和原版遗留的前后附文,输出 meta 与 run_state 快照。merge_and_build.py --headings · merge_meta.py status · run_state.py status VERIFY 6 翻译书名从 config.txt 读原书名;有正式译名就用正式译名,不加书名号。config.txt · original_title TITLE 7 合并与构建校验通过后合并为 output.md,Pandoc 生成带目录的 HTML,Calibre 生成 DOCX、EPUB、PDF。中间文件默认保留。merge_and_build.py --title … --export-name … BUILD 8–9 汇报与局部修订汇报产物与失败项;之后发现个别译文有问题,改对应的 output_chunkNNNN.md 或删掉重译,再重跑构建,不必整本重来。run_state.py plan / record · merge_and_build.py FIX

§ 04作为 agent harness

SKILL.md ORCHESTRATES, SCRIPTS KEEP THE BOOKS

编排写进 Markdown,账交给脚本。

PLATFORM-NEUTRAL ORCHESTRATION 一份 SKILL.md,三个宿主 同一份编排在 Codex、Claude Code、OpenClaw 上运行:脚本路径一律用 {baseDir},子代理说明不绑定某个平台的工具名,frontmatter 每个字段保持单行。
SINGLE WRITER 共享状态只有一个写者 glossary.json 和 run_state.json 只由主代理写;子代理只读共享状态,各写各的 meta 文件,所以不需要加锁。
SCRIPTS BOOKKEEP · LLM MERGES 脚本记账,LLM 做语义判断 状态、schema 校验、去重、hash、IO 是确定性的 Python;命名、性别归属、别名判定和冲突裁决交给模型。合并保守:新实体要有证据,冲突不静默覆盖。
551SKILL.md 行数
10scripts/ 下的 Python 脚本
10单元测试文件
333测试用例(def test_)
3纳入仓库的 baseline 书

机械护栏:GitHub Actions 在每次推送 main 和每个 PR 上用 Python 3.12 跑 compileall 和全部单元测试;单元测试只依赖标准库,第三方依赖都做了导入保护。完整链路用 tests/baselines/ 里的书(如 standard-alice)在 tests/.artifacts/ 下跑。以上数字按 main @ 1c531b4(2026-11-21)清点。

§ 05从哪里开始

GETTING STARTED · 5 PHASES
1 PHASE 1 · 前置要求 准备运行环境 一个能运行 Skill 的 Agent 宿主(Codex、Claude Code 或 OpenClaw),加上 Calibre(ebook-convert)、Pandoc 和 Python 3。pypandoc、beautifulsoup4 可选;MinerU / Marker 只在处理公式、表格密集的 PDF 时才需要。
2 PHASE 2 · 安装 SKILL 装进你的 Agent CODEX
npx skills add deusyu/translate-book -a codex -g
CLAUDE CODE
npx skills add deusyu/translate-book -a claude-code -g
OPENCLAW
openclaw skills install @deusyu/translate-book
也可以把仓库 git clone 到 ~/.agents/skills/(Codex)或 ~/.claude/skills/(Claude Code)下。Codex 里新装的 Skill 没出现时,重启一次。
3 PHASE 3 · 一句话发起 翻译一本书 CODEX
$translate-book Translate /path/to/book.pdf into Chinese.
CLAUDE CODE
/translate-book translate /path/to/book.pdf to Japanese
或直接说
translate /path/to/book.pdf to Chinese
Skill 自动走完转换、拆块、并行翻译、校验、合并和多格式输出。运行中断了,重新发起即可从断点续跑。
4 PHASE 4 · {book_name}_temp/ 取走成品,按需修订 output.mdbook.htmlbook.docxbook.epubbook.pdf 网页版带浮动目录。要改个别译文,改对应的 output_chunkNNNN.md(不要改 output.md),再重跑 merge_and_build.py;--cleanup 会永久删除中间文件,只在整本定稿后用。
5 PHASE 5 · 测试与反馈 跑测试、提 issue 单元测试
python3 -m unittest discover -s tests -p 'test_*.py' -v
项目优先接受详细的 GitHub issue(现象、期望、环境、最小复现),而不是直接提 PR;变更需要放在维护者掌握的编排规则、chunk / manifest 契约和发布流程里一起评估。