Wenyi断点续跑完全指南：为什么再运行同一条命令就能接着翻译
【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi
Wenyi（文译）是一个面向长文本的 AI 翻译项目，把整本书放进"全局视野"里翻译。它最大的实用特性之一，就是断点续跑：翻译中断后，你不需要重新来过，再运行同一条命令就能从上次停下的地方继续。这篇指南帮你彻底理解它背后的机制和正确用法。
上图的"运行记录"显示了 3 次独立运行——这正是断点续跑最典型的痕迹：每次中断后重新执行命令，都会追加一条新的运行记录，而不是推倒重来。
为什么长文本翻译特别需要断点续跑？
翻译一本小说通常需要数小时：全书预扫、逐章翻译、润色、审校，每一步都在调用大模型。这么长的时间里，意外几乎不可避免：
- 🌐 网络抖动、API 超时、限流（HTTP 429）
- 💻 电脑休眠、进程被 Ctrl+C 或强制关闭
- 💸 模型额度用尽、余额不足
如果每次都从头翻译，不仅浪费时间，还会白白消耗 Token 费用。Wenyi 的设计目标就是：随时可以中断，随时可以接上。
为什么再运行同一条命令就能接着翻译？
秘密在于三个设计，它们共同构成了"状态即进度"的机制。
1️⃣ 每个完成的批次都立即落盘，状态目录是唯一真相
Wenyi 不会等整本书翻译完才保存。每翻译完一个批次（一批段落），就立刻写入本地状态目录：
state/<书名>/targets/<目标语言>/章节中间结果、术语 SQLite 库、用量和报告都在这里。由于每个批次完成后即刻持久化，即使进程下一秒就被杀掉，已完成的译文也安全保存在磁盘上。相关的持久化逻辑可以在 packages/core/wenyi_core/pipeline/runstore.py 中查看，状态存储统一走 packages/core/wenyi_core/storage/protocol.py 协议。
2️⃣ manifest 用 SHA-256 哈希绑定源文件，确保"接的是同一本书"
状态目录里的manifest.json记录了源文件的 SHA-256 哈希。再次运行时，Wenyi 会先核对文件身份：
- ✅ 同一份源文件 → 校验通过，继续续跑
- ❌ 同名文件但内容变了 →拒绝续跑，要求重建状态
这一步防止了"状态对不上号"的尴尬：比如你换了个修订版的 EPUB，旧译文不能直接套在新内容上。初始化是最后提交 manifest 的，保证写入的原子性。
3️⃣ 已有译文自动跳过，只补齐未完成部分
续跑时，Wenyi 会先分离"已完成"与"待译"批次：已完成的章节和段落直接跳过，不产生任何模型调用和费用；只针对未完成部分继续翻译，并按原文顺序重新确定衔接上下文。
开启润色时更精细：章节 JSON 中每个段落的target_before_polish保留翻译阶段的译文，target保留润色后的最终译文——哪一步做完了，就从哪一步之后接着走。
实战三步：中断后如何续跑？
第 1 步：中断（或发现中断）
无需任何特殊操作。Ctrl+C、断网、关机都可以。中断后已落盘的批次不受影响。
第 2 步：用同一个源文件，再运行同一条命令
uv run wenyi translate book.epub命令完全一样，Wenyi 自动识别到已有状态，跳过已完成部分继续翻译。
第 3 步：用 status 查看进度
wenyi status book.epub可以随时确认章节完成情况和累计时长。timing.json只累计实际执行时间，两次运行之间的停机时间不计入。
💡 小技巧：也可以先用wenyi prepare book.epub只做准备（解析、风格分析、初始术语表），不翻正文；之后再跑translate复用状态继续翻译。
常见疑问 FAQ
Q：中断了 3 次，会重复翻译或重复计费吗？不会。已完成批次命中缓存直接跳过，Token 用量在各次运行间累加到同一份usage.json，不会重复计费。
Q：改了源文件内容还能续吗？不能直接续。manifest 的哈希校验会拒绝并提示重建状态——这是保护你的译文不被套在错的内容上。
Q：审校（Review）也支持续跑吗？支持，但语义不同。审校每次都会全量重审完整译文并创建新的时间戳审校目录；interrupted和failed状态的审校都可续跑，下次review继续同一目录而不是新建。详见 docs/zh/pipeline.md — 断点续跑。
Q：SRT 字幕翻译也能续跑吗？能。字幕走轻量路径，进度落在state/srt/<slug>/targets/<目标语言>/，batches/中已缓存的批次会跳过，实现逻辑在 packages/core/wenyi_core/srt/store.py。
Q：想从头重新翻译怎么办？只有这时才需要清理对应的状态目录或改用新的目标目录。
状态目录里都有什么"断点"？
以 SRT 为例，目录结构一目了然（书籍目录类似，额外含章节 JSON 与术语库）：
state/srt/<slug>/targets/<目标语言>/ manifest.json # 源身份、字幕条数、配置 cues.jsonl # 每行一条字幕的翻译状态 batches/ # 模型原始批次结果，供续跑 usage.json # 跨续跑累计 token timing.json # 累计执行时长与每次运行用时 events.jsonl # 运行事件与 LLM 重试记录书籍状态目录还包含glossary.db（术语 SQLite 库）和reviews/（审校记录）。完整说明见 docs/zh/usage.md — 中断与续跑。
续跑之后：直接导出成品
断点续跑还有一个隐藏福利——assemble可以在不调用任何模型的情况下，把当前已落盘的一致快照重新导出为成品。就算另一个终端还在继续翻译，导出读取的是调用时已落盘的快照，不必等整本书结束。
总结
Wenyi 断点续跑的本质可以概括为一句话：批次级检查点 + 内容哈希校验 + 幂等跳过。
- 每批译文立即落盘 → 中断不丢进度
- manifest 哈希绑定源文件 → 保证续的是同一本书
- 已有译文自动跳过 → 不重复翻译、不重复计费
所以"再运行同一条命令"不是玄学，而是状态目录在默默替你记账。把长篇小说放心地交给 Wenyi，睡一觉起来接着跑就好 😴📚
更多机制细节可参考 docs/zh/pipeline.md 与 docs/zh/architecture.md。
【免费下载链接】wenyi将被语言阻隔的作品，带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
