translate-book常见报错完整FAQ12个高频问题快速排查手册【免费下载链接】translate-bookAgent skill for Codex, Claude Code, and OpenClaw that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents.项目地址: https://gitcode.com/gh_mirrors/tran/translate-booktranslate-book是一款面向 Codex、Claude Code 和 OpenClaw 的 AI 并行译书技能把整本 PDF / DOCX / EPUB 交给 8 路并行子代理翻译再经哈希校验合并成完整译本一键输出 HTML、DOCX、EPUB、PDF。整条流水线分四步转换切块 → 并行翻译 → 校验续跑 → 合并成书。任何一步出问题都会抛出报错本文把新手最常踩的12 个 translate-book 常见报错整理成快速排查手册按流水线阶段定位照抄命令即可解决。快速排查思路所有报错都可以先问自己三个问题再对照下面的 12 个 FAQ报错发生在哪一步—— 转换scripts/convert.py、翻译subagent 并行、还是合并构建scripts/merge_and_build.py是不是环境问题—— Calibre 的ebook-convert或 Pandoc 不在 PATH 中temp 目录是不是过期了—— 大多数校验类报错都指向同一根因{书名}_temp/里的缓存与源文件不再一致删掉重跑即可 核心原则translate-book 的校验失败几乎都是保护机制防止把错的书、旧的内容合并进去删掉过时的 temp 目录或最终产物再重跑基本都能解决。一、环境与依赖类报错1.Calibre ebook-convert not found找不到 Calibre报错信息Error: Calibre ebook-convert not found原因convert.py依赖 Calibre 的ebook-convert命令把 PDF/DOCX/EPUB 转成 HTML但系统里没装 Calibre或者ebook-convert不在 PATH 环境变量里。该检查位于 scripts/convert.py#L1116。解决方案安装 Calibre官网免费安装后确认终端能直接执行ebook-convert --helpmacOS 若从 .dmg 安装需把ebook-convert软链到/usr/local/bin否则 Python 脚本找不到它装完重跑一次 skill 即可2. PDF 生成失败Calibre 不支持 PDF 输出现象book.html、book.epub正常唯独book.pdf生成失败。原因PDF 导出由 Calibre 完成封装在 scripts/calibre_html_publish.py 中如果 Calibre 安装不完整或版本过旧PDF 后端会缺失。解决方案确认 Calibre 已完整安装且版本较新能执行ebook-convert输出pdfWindows 用户建议用官方安装包自带 PDF 后端不要用精简版只修 PDF 不需要重译删掉book.pdf后重跑 scripts/merge_and_build.py 即可二、转换与拆分类报错3.was created from different source bytestemp 目录属于另一个源文件报错信息Error: xxx_temp/ was created from different source bytes (Delete xxx_temp/ (or use a fresh --temp-root) and re-run.)原因每个 temp 目录都记录了源文件的 SHA-256 指纹source_fingerprint.json。你替换了源文件比如换了第二版 PDF却复用了旧目录convert.py会直接中止——复用它等于翻译另一本书。见 scripts/convert.py#L253-L260。解决方案删掉{书名}_temp/目录重新转换或用--temp-root换一个父目录让同名叶子目录落在新位置4.Manifest validation failed源 chunk 拆分后被改过现象合并阶段报 manifest 校验失败提示某个 chunk 的哈希对不上。原因manifest.json记录了每个源 chunk 拆分时的 SHA-256校验时若发现chunk*.md的内容变了手动编辑、误存、被别的工具覆写就会拒绝合并。逻辑在 scripts/manifest.py#L110-L120。解决方案重新运行python3 scripts/convert.py 源文件 --olang zh重新拆分然后重跑翻译如果你确实手改过 chunk 内容——这正是报错要拦住的场景改源文件再重新转换才是正确姿势5. 修改标题/模板/封面后输出没更新现象重跑merge_and_build.py后book.html、book.epub等还是旧内容。原因合并脚本会跳过已存在且看起来是最新的产物如 scripts/merge_and_build.py#L316 的Skipping merge - output.md already exists。你改了标题、作者、模板或图片但旧产物还占着位置。解决方案进入{书名}_temp/删掉旧产物output.md、book*.html、book.docx、book.epub、book.pdf再重跑python3 scripts/merge_and_build.py --temp-dir temp_dir --title 《译后书名》更稳妥的做法每次改配置就用新的 temp 目录6. 想去掉 PDF 页码--strip-page-numbers却不生效现象给convert.py加了--strip-page-numbers却报已存在错误页码也还在。原因该标志只对 Calibre 输入生效且检测到已缓存的input.md或chunk*.md时会直接报错退出——标志必须先转换才能生效。解决方案先删掉 temp 目录里的input.md和chunk*.md缓存再加--strip-page-numbers重跑convert.py注意默认行为已能自动删除单调递增的页码序列1, 2, 3...同时保留年份1984、章节号等正文数字多数情况其实不用加这个标志7. PDF 转换后公式、表格错乱现象学术/技术类 PDF 转出来公式碎成片段、表格拍平、多栏文字交错。原因Calibre 靠坐标启发式重排 PDF 文本对普通正文够用但复杂版面会丢结构。这不是报错而是最常见的隐性翻车。解决方案用版面感知解析器先转出 Markdown公式保留为 LaTeX、表格保留为表格pip install -U mineru4.0,5 mineru-kit parse paper.pdf -o paper.md删掉旧的 temp 目录源指纹不同会中止见上文第 3 条对.md运行python3 scripts/convert.py paper.md --olang zh——Markdown 输入完全绕过 Calibre三、翻译阶段报错8.Blank output/Empty output某个 chunk 翻译成空白报错信息ERROR: Blank output output_chunk0042.md (chunk 0042) — whitespace-only content would be silently dropped on merge ERROR: Empty output file: output_chunk0042.md原因某个子代理写出了空文件0 字节或纯空白文件。合并脚本 scripts/manifest.py#L128-L146 会主动拦截这种 chunk——因为空白文件会在合并时被静默丢弃导致译本缺章。解决方案直接重新运行 skill断点续跑机制会跳过已完成的 chunk只重译失败/空白的那个个别 chunk 反复失败时可单独让它重译每个 chunk 默认自动重试一次9. 翻译中断了怎么办翻译不完整现象会话被掐断、API 限流、手动停止翻译只完成一半。原因这不是故障而是常态——skill 天然支持断点续跑。scripts/run_state.py plan temp_dir在每次启动前会规划哪些 chunk 需要翻译、哪些只需记录状态、哪些无需处理。解决方案重新运行 skill 即可已有合法输出且状态有效的 chunk 全部跳过从断点继续接管很旧的 temp 目录、且希望旧输出按当前术语表强制重译时才加--retranslate-untracked见 scripts/run_state.py10.Missing source chunk源 chunk 文件丢了报错信息ERROR: Missing source: chunk0042.md (chunk 0042) — cannot verify output integrity without source chunk原因temp 目录里的chunk*.md被删除或误清理没有源文件就无法校验输出完整性scripts/manifest.py#L102-L108。解决方案重新运行convert.py重新生成 chunks 和 manifest然后重跑翻译如果你只是用了--cleanup它在构建完全成功后才清理中间文件所以出现这个报错说明清理前就出了问题按上条重跑即可四、合并校验与术语表报错11.output.md exists but manifest invalid旧输出过时现象重跑合并时报 manifest 无效但脚本随后继续了。原因output.md是上一轮合并的产物而 manifest 校验未通过源 chunk 变了、或输出缺块。这是过时速判不是数据损坏。解决方案无需手动处理脚本会自动删除过时的output.md并重新合并如果你在源 chunk 被改过的情况下反复看到它回到第 4 条重跑convert.py才是根治办法12.Glossary upgrade rejected: duplicate source术语表升级被拒现象旧版v1glossary.json首次加载自动升级 v2 时中止提示有重复 source。原因v2 术语表禁止同一个表面词source 或 alias同时归属两个术语——例如两个条目都用了Apple苹果公司 vs 水果。自动升级无法替你消歧见 scripts/glossary.py#L334-L344。解决方案手工编辑 temp 目录下的glossary.json把其中一个 source 改成可区分的写法如Apple (Inc.)保存后重新运行即可注意已存在的glossary.json永远不会被覆盖想从零重建就删掉它排查速查表#报错 / 现象一句话解法1Calibre ebook-convert not found安装 Calibre 并保证在 PATH2PDF 生成失败完整安装支持 PDF 的 Calibre删book.pdf重跑合并3created from different source bytes换源文件了——删 temp 目录或用--temp-root4Manifest validation failed源 chunk 被动过——重跑convert.py5改标题/封面后输出没变删旧产物output.md、book.*再重跑合并6--strip-page-numbers报错先删input.md和chunk*.md缓存7公式/表格错乱MinerU/Marker 转 Markdown 后再转换8Blank/Empty output重跑 skill断点续跑只补空白 chunk9翻译不完整重跑 skill 自动续跑10Missing source chunk重跑convert.py重新生成11output.md exists but manifest invalid脚本自动删除重合并无需干预12Glossary upgrade rejected手编glossary.json消歧后重载写在最后 所有产物都在{书名}_temp/下output.md合并译文、book.html带浮动目录网页版、book.docx/book.epub/book.pdf 遇到上表之外的报错参考 README.zh-CN.md 的常见问题章节或在 skill 输出里保留完整日志再排查 想深入理解每一步可读 SKILL.md 的完整工作流定义以及 scripts/ 目录下各脚本的注释按定位阶段 → 判断是环境还是状态 → 删缓存重跑的思路走12 个高频问题基本都能在五分钟内解决。【免费下载链接】translate-bookAgent skill for Codex, Claude Code, and OpenClaw that translates entire books (PDF/DOCX/EPUB) into any language using parallel subagents.项目地址: https://gitcode.com/gh_mirrors/tran/translate-book创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考