TRANSLATE-BOOK —— AGENT SKILL · 中文导读
一整本书,并行翻译
面向 Codex、Claude Code 和 OpenClaw 的 Agent Skill。把 PDF / DOCX / EPUB 拆成 chunk,交给一批批全新上下文的子代理并行翻译,经 manifest 校验后合并成 HTML、DOCX、EPUB、PDF 四种成品。
§ 01一句话理解
ONE CHUNK, ONE FRESH CONTEXT核心做法:每个 chunk 由一个拥有全新上下文窗口的子代理翻译,避开整书单会话的上下文堆积和输出截断;跨 chunk 的一致性不靠记忆,而靠术语表、邻居摘录和可续跑的状态文件。
§ 02六个核心部件
SIX MOVING PARTS · scripts/SKILL.md 负责编排,确定性的事情交给 scripts/ 里的 Python。下面每一张卡都指向 main 分支上的一个脚本。
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 里的步骤号。主代理按这张台账依次推进;每一行下方是这一步实际调用的脚本或产物。
{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,账交给脚本。
{baseDir},子代理说明不绑定某个平台的工具名,frontmatter 每个字段保持单行。
glossary.json 和 run_state.json 只由主代理写;子代理只读共享状态,各写各的 meta 文件,所以不需要加锁。
机械护栏:GitHub Actions 在每次推送 main 和每个 PR 上用 Python 3.12 跑 compileall 和全部单元测试;单元测试只依赖标准库,第三方依赖都做了导入保护。完整链路用 tests/baselines/ 里的书(如 standard-alice)在 tests/.artifacts/ 下跑。以上数字按 main @ 1c531b4(2026-11-21)清点。
§ 05从哪里开始
GETTING STARTED · 5 PHASESebook-convert)、Pandoc 和 Python 3。pypandoc、beautifulsoup4 可选;MinerU / Marker 只在处理公式、表格密集的 PDF 时才需要。
npx skills add deusyu/translate-book -a codex -gCLAUDE CODE
npx skills add deusyu/translate-book -a claude-code -gOPENCLAW
openclaw skills install @deusyu/translate-book也可以把仓库
git clone 到 ~/.agents/skills/(Codex)或 ~/.claude/skills/(Claude Code)下。Codex 里新装的 Skill 没出现时,重启一次。
$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 ChineseSkill 自动走完转换、拆块、并行翻译、校验、合并和多格式输出。运行中断了,重新发起即可从断点续跑。
output_chunkNNNN.md(不要改 output.md),再重跑 merge_and_build.py;--cleanup 会永久删除中间文件,只在整本定稿后用。
python3 -m unittest discover -s tests -p 'test_*.py' -v项目优先接受详细的 GitHub issue(现象、期望、环境、最小复现),而不是直接提 PR;变更需要放在维护者掌握的编排规则、chunk / manifest 契约和发布流程里一起评估。