整本书翻译技能
用并行子代理把整本 PDF/DOCX/EPUB 书籍翻译成任意语言，含术语一致性校验与多格式输出。
SKILL.md 仅读写用户指定的工作目录，参数缺失时会询问用户，来源指纹与 manifest 校验防止静默复用过期数据，--cleanup 默认仅在成功后清理中间产物且可省略，未发现网络外传或越权行为；扣分点：allowed-tools 含 Bash/Agent 较宽泛，删除临时目录、覆盖导出文件等外部效应缺少显式用户确认。
文档对失败模式（空白 chunk、manifest 校验失败、指纹不匹配、Calibre 缺失降级）描述详尽，测试覆盖 convert/chunk_context/calibre 包装等脚本，CI 运行单测；扣分点：核心编排路径（subagent 翻译、meta 合并、run_state 规划）无测试且脚本源码未在本次审阅中提供，静态无法确认可运行性，按上限 10 封顶。
目标场景（整书翻译为 zh/en/ja 等）、输入输出格式、非适用边界（EPUB 封面提取不做了）、触发描述均清晰，中文文档齐全，依赖本地 Calibre/Pandoc 与 LLM 运行时，不依赖不可达的海外在线服务；扣分点：语义触发条件主要靠描述匹配，缺乏对超大文件、扫描版 PDF 等边界声明。
分层文档完善（SKILL.md/README 双语/AGENTS.md/CLAUDE.md），MIT 许可、git tag 版本锚点、明确维护者流程与已知问题（Calibre 7.6 EPUB bug）；扣分点：无独立 CHANGELOG 文件，发布流程依赖 .claude/commands/release.md（未在证据中），贡献流程对 PR 不友好可能影响可持续维护。
声称的整书并行翻译、多格式输出、术语一致性对手动翻译有明确边际价值，工作流设计自洽；扣分点：无任何已提交的代表性真实译本输出证据，翻译质量（Phase 4 未完成、整书自然度校验是未来工作）作者自己承认未验证，静态审阅不能确认产出直接可用。
存在 CI 工作流运行 unittest，提交的测试覆盖页码清理、源指纹、邻居上下文等关键子路径，issue/PR 引用可追溯；扣分点：测试为 mock 驱动的单元测试，编排主路径与端到端质量无独立可复现证据，静态审阅未执行。
- 静态审阅未执行任何代码：编排主路径（subagent 翻译、meta 合并、run_state 规划）无测试覆盖，首次运行建议先用小文件验证。
- allowed-tools 包含 Bash 与 Agent，权限较宽；--cleanup 会删除中间文件，如需保留请显式省略该参数。
- Ubuntu 系统 Calibre 7.6.0 存在 EPUB 生成 bug（作者已披露），EPUB 输出可能失败；修改标题/模板后需手动删除旧产物再重跑。
- 翻译质量依赖上游 LLM 能力，整书术语自然度作者自认尚未验证，重要书籍需人工审校。
- 运行需本地安装 Calibre、Pandoc 及 Python 依赖，环境缺失时部分格式会静默降级，请在报告中留意格式生成失败提示。
这个 Skill 能做什么，适合哪些场景？
translate-book 是一个面向 Codex、Claude Code 和 OpenClaw 的代理技能，能把整本 PDF、DOCX 或 EPUB 书籍翻译成目标语言（默认中文，也支持英、日、韩、法、德、西等）。它先用 Calibre 把原书转成 Markdown 并切块，然后每块交由一个拥有独立上下文的子代理并行翻译，通过术语表、邻居上下文与逐块元数据保证全书人名、代词和术语不漂移。最后经完整性校验（SHA-256 manifest）合并，用 Pandoc 和 Calibre 生成 HTML、DOCX、EPUB、PDF。项目采用 MIT 协议，明确声明是从 wizlijun/claude_translater 得到启发的独立重写项目，而非分叉。
技能读取输入文件后执行一条多步流水线：1) scripts/convert.py 调用 Calibre（ebook-convert 经 HTMLZ）把 PDF/DOCX/EPUB 转成 Markdown，切成约 6000 字符的 chunk0001.md 等，写 manifest.（逐块 SHA-256）与 source_fingerprint.；2) 从首、尾、中采样块提取专有名词，生成可手改的 glossary.（v2，含别名、性别、置信度），glossary.py 统计词频并按块输出术语表；3) run_state.py 规划选择性重译，跳过已有效且术语未变的块；4) 每批默认 8 个子代理并行翻译，各块附注入术语表与相邻块各约 300 字符的只读摘录，并产出 output_chunkNNNN.meta. 供 merge_meta.py 在批次边界以保守规则合并回术语表；5) 校验 1:1 输出、哈希一致、无空白块后，merge_and_build.py 合并成 output.md，经 Pandoc 生成带浮动目录的 HTML，再由 Calibre 生成 DOCX、EPUB、PDF，支持 --cover、--export-name 等选项。
- 个人译者或独立出版者手里有一本英文 EPUB，想低成本产出一本可读的中文版并直接得到 EPUB/DOCX 交付物
- 技术书读者拿到只发布了原语言的 PDF，想整本译成母语后再细读
- 翻译团队需要先把一本书粗翻一遍，再人工润色——术语表可手改并只重译受影响的块
- 长期连载式翻译项目需要可断点续跑：中断后重跑只补缺失块，源文件被替换会因指纹不匹配而中止而非悄悄复用旧块
- 内容本地化工作者需要保持 100+ 块书里人名、地名、术语译法一致，避免逐会话翻译造成的漂移
这个 Skill 有哪些优点和局限？
- 每块独立子代理（默认 8 并发），避免整本会话式翻译常见的上下文堆积与输出截断
- 术语一致性工程完整：采样建表、词频统计、逐块注入硬约束、子代理元数据回灌、手改后仅重译受影响块
- 可断点续跑且带完整性保障：manifest SHA-256 校验、源指纹、空白/缺失块自动重试一次
- 一次流水线产出 Markdown/HTML/DOCX/EPUB/PDF，附明确的环境前置与故障排查表
- 设计原则清晰：脚本只做簿记，LLM 只做语义合并，共享状态单一写入者
- 依赖较重：需要本机安装 Calibre、Pandoc、Python 3 及 pypandoc，缺任一格式转换即失败
- 子代理并行翻译意味着可观的 token/API 成本，百块级书籍费用不小（源材料未给出用量估算）
- EPUB 封面仅支持显式 --cover 传入，从 EPUB 自动抽取封面明确不在范围内
- 并行翻译的质量仅经仓库内基线样书（如 standard-alice.epub）验证，未提供真实长书的有机质量评测；Phase 4 引导预热仍停留在实验设想
- 贡献流程反常规：维护者要求先开 issue 而非 PR，PR 可能被关闭
- 相邻上下文与术语机制减轻但不消除跨块代词/性别的翻译错误，README 中 roadmap 明确承认全本质量校验仍是未来工作
如何安装这个 Skill？
前置条件：安装并配置好 Codex、Claude Code 或 OpenClaw；安装 Calibre（PATH 中有 ebook-convert）、Pandoc、Python 3，并 pip install pypandoc（可选 beautifulsoup4 以获得更好的目录）。安装方式任选：Codex：npx skills add deusyu/translate-book -a codex -g，或 git clone https://github.com/deusyu/translate-book.git ~/.agents/skills/translate-book；Claude Code：npx skills add deusyu/translate-book -a claude-code -g，或 clone 到 ~/.claude/skills/translate-book；OpenClaw：openclaw skills install @deusyu/translate-book。若装完技能未出现，重启 Codex。
如何使用这个 Skill？
Claude Code / OpenClaw 中直接对代理说：translate /path/to/book.pdf to Chinese，或用斜杠命令 /translate-book translate /path/to/book.pdf to Japanese。Codex 中输入 $translate-book Translate /path/to/book.pdf into Chinese.（Codex 也会在请求匹配技能描述时自动选用）。可选参数在对话中说明即可：目标语言（默认 zh）、并发数（默认 8）、--temp-root 对应的临时目录位置、EPUB 封面图路径、导出别名文件名、以及自定义翻译要求。产物位于 {书名}_temp/ 下：output.md、book.html（浮动目录）、book.docx、book.epub、book.pdf。
这个 Skill 与同类方案有什么区别？
README 明确提到灵感来源 wizlijun/claude_translater：原项目以 shell 脚本为入口、协调 Claude CLI 分步翻译；本项目将其重构为代理技能，用子代理并行翻译，并加入 manifest 校验、可续跑与多格式输出统一流水线，作者强调结构与实现差异显著，属独立项目而非分叉。