如何实现可靠的断点续跑Wenyi批级检查点与原子状态写入设计原理【免费下载链接】wenyi将被语言阻隔的作品带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyiWenyi文译是一个面向长篇小说的开源 AI 翻译工具其翻译与审校流程支持批级检查点与原子状态写入任何一章中断后重新运行同一条命令即可从上次进度继续不会重复付费调用模型也不会损坏已保存的译文。本文面向新手讲清这套可靠断点续跑背后的 4 个设计原理。1. 长书翻译为什么会卡死在中间一本几十万字的小说完整跑完翻译 审校往往需要数小时。这期间随时可能发生 网络中断、模型 API 限流进程被杀️ 电脑休眠、终端关闭 人工 CtrlC 取消如果状态保存不当轻则已完成的批次全部重跑白花 token 费用重则留下半截文件导致状态损坏、整本书推倒重来。Wenyi 的官方定位正是把单遍翻译、对中断脆弱升级为批级检查点 章节状态跟踪用同一条命令恢复任何中断的运行见 README.md。2. 原理一原子写入——磁盘上永远不会出现半个文件所有状态manifest、章节、报告、用量都通过同一种方式落盘先写同目录下的.tmp临时文件再用os.replace原子替换正式文件。正式文件 ←── 原子替换 ←── .tmp 临时文件写完才生效为什么这样做就可靠os.replace在同一文件系统内是原子操作读到的要么是完整的旧内容要么是完整的新内容不存在中间态即使进程在写临时文件时崩溃正式文件也毫发无损最多只是丢掉一次未完成的更新临时文件与正式文件同目录避免跨目录 rename 失效的坑。核心实现只有几行位于 runstore.py写入.tmp→json.dump→os.replace(tmp, path)注释原话是 Atomic replacement prevents partial files after interruption。审校模块的 run_store.py 同样遵循_atomic_json约定连审查块缓存、用量账本、结果文件都走这条路。3. 原理二批级检查点——进度以批次为单位增量保存批次翻译的最小保存单位Wenyi 不会一次把整章塞给模型而是按 token 预算把章节切成批次batch串行翻译。每完成一个批次立即做三件事把译文写回章节状态文件又是原子写入并追加batch_translated事件记录术语抽取检查点用批次起点:数量作为检查点键见 runstore.py 的 batch_glossary_key保证术语抽取只执行一次更新滚动上下文让下一批次能看到刚译完的前文。续跑只补缺的那部分中断后重跑时resume_batches会把段落按完成状态重新分组translation_batch.py已译完的批次整批跳过只按原文顺序重建上下文、补译缺失段落绝不动用已有译文。批次进度统计也只把全部段落都有译文的批次计为完成避免重复计数见 translation.py。还有一个巧妙的细节哪些批次的术语已抽取不靠额外状态文件而是从只追加的事件日志events.jsonl里回放恢复completed_batch_glossary_keys。日志只增不改天然适合做完成标记。4. 原理三manifest 最后提交——初始化成功只有一个信号任务初始化时Wenyi 会先写入.initializing.json源文件指纹把派生状态清干净只有分析、术语、章节全部就绪后才最后原子提交manifest.json并删除初始化标记见 runstore.py 的 begin/finish_initialization。这意味着✅ 有 manifest → 初始化完整可以续跑❌ 没 manifest 但有.initializing.json→ 上次初始化半途失败重新初始化时自动清理残留旧数据不会污染新任务 同时用源文件 SHA-256 做身份校验ensure_source_identity换了一本书却想用旧状态目录时会被明确拒绝防止同名目录串书。一句话manifest 最后提交让状态目录永远处于要么全新、要么完整的两种状态之一。5. 原理四审校轮次检查点——连多轮 Agent 审校也能续跑全书审校是最耗时的阶段多轮循环、并发审查块、仲裁、修订任何一轮中断都很心疼。Wenyi 为它做了两层检查点块级缓存chunk cache每个审查块完成后结果立刻原子写入chunks/{块ID}.json。续跑时通过is_chunk_done直接命中缓存跳过已完成的模型调用run_store.py。轮级检查点checkpoint.json每一轮审校结束或扫描完成时保存一份完整会话快照下一轮次、修订补丁、失败记录、清洁连击数等并带phase标记round_done/scan_done。恢复时由 ReviewCheckpoint.restore 解码若停在scan_done本轮扫描结果直接复用不重复调用模型已完成的轮次不重新执行聚合而是用rebuild_snapshots_from_chunks从块缓存重建保证最终报告完整若用户调低了最大轮次等设置检查点会被安全钳制到合法范围而不是产生空循环。配合find_resumable只要result.json状态是running / interrupted / failed且内容摘要、配置、术语指纹都没变就能找到上次那次审校接着跑——失败也允许续跑块缓存继续复用run_store.py。6. 配套细节锁与事件日志命名文件锁区分职责.run.lock长任务、.state.lockmanifest/章节原子持久化的短锁、.events.lock事件追加跨进程也不会写乱runstore.py 锁定义只追加的events.jsonl记录每次动作既是审计轨迹也是术语检查点这类完成标记的数据源。7. 这些原理对你的实际意义场景没有检查点Wenyi 的做法翻译到一半断网整章/整书重跑只补未完成批次已完成批次跳过审校第 2 轮被中断全部审查块重调模型块缓存命中轮次检查点直接续初始化时崩溃状态目录脏数据manifest 未提交自动重新初始化用量记录写到一半丢失费用账目错乱用量先写 pending 日志再发布可幂等恢复recover_usage对新手来说记住三个关键词就够了原子写永不损坏、批级检查点进度不丢、manifest 最后提交状态要么全新要么完整。相关资料状态持久化主实现runstore.py批次规划与续跑切分translation_batch.py审校检查点恢复review_checkpoint.py审校运行存储run_store.py官方架构说明持久化边界docs/architecture.md翻译流程中文文档docs/zh/pipeline.md状态演进与恢复的规划分析docs/zh/project-review/2026-09-05/p01-state-evolution-and-recovery.md【免费下载链接】wenyi将被语言阻隔的作品带到读者的语言中。Bringing literature into your language.项目地址: https://gitcode.com/BigDawnGhost/wenyi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考