连续运行3天不丢字ainovel-cli 多Agent小说生成的 Step 级 Checkpoint 与 Saga 原子提交全解析【免费下载链接】ainovel-cli✨多agent实现全自动AI小说生成项目地址: https://gitcode.com/gh_mirrors/ai/ainovel-cliainovel-cli是一个用多 Agent 协作实现全自动AI 小说生成的开源工具架构师规划、写手产出、编辑审校一条命令可以连续跑数天、产出数百章正文。长时运行最怕的就是跑到一半崩了前面全白写。它的解法只有两句话——Step 级 checkpoint记录每一步落盘事实Saga 原子提交保证章节提交中断后可从断点重放。这篇文章带你彻底看懂这套不丢字机制不需要读一行源码也能收获。上面是它真实的运行界面左侧是运行状态与 token 预算中间是实时事件流每一章都经历 plan → draft → check → commit 的完整链路右侧是因果链回溯。跑 3 天、写 170 多章随时可以中断、重启、续跑。为什么多 Agent 长跑最怕丢字传统脚本挂了重跑一遍就行但 AI 小说生成不一样每一步都烧钱一章正文要调用多次大模型重试成本是真金白银上下文不可再生模型不会记得上一轮写了什么断点信息必须来自磁盘多 Agent 交错执行写手刚提交、架构师还没规划下一章崩溃可能发生在任何缝隙里所以 ainovel-cli 的设计铁律是完成的唯一证据是 checkpoint 写入而不是模型说自己完成了。一、Step 级 Checkpoint只追加的进度账本1. 每个关键步骤都打一个 checkpoint从定义 internal/domain/checkpoint.go 可以看到一条 checkpoint 只记录五个事实字段含义例子Seq全局单调递增序号1024Scope作用域章节/弧/卷/全局chapter:172Step完成了哪一步plan/draft/commitArtifact产物文件chapters/172.mdDigest产物内容指纹用于判重所有 checkpoint 以只追加append-only方式写入meta/checkpoints.jsonl见 internal/store/checkpoints.go。只追加意味着永远不需要修改历史日志坏了也不会互相污染重启时从上往下读一遍就能完整重建进度。每章写作会依次留下多个 stepplan章节计划→draft草稿→commit终稿提交弧末还有review、arc_summary。崩溃恢复时Engine 读到的不是我上次干到哪一步的模糊记忆而是磁盘上的确定事实恢复入口见 internal/host/resume.go。2. 幂等设计重复执行零副作用这是不丢字的第一道防线。每个写类工具执行前都会先查 checkpoint如果当前 scope 最新的Step Digest与本次完全相同直接返回已有产物不再重做。效果是什么网络抖动导致的重试 → 安全崩溃后恢复的重复派发 → 安全同一个 step 被派发三次 → 磁盘上只有一条记录相同ScopeStepDigest视为幂等不产生新行换句话说你可以放心地反复重启进程引擎不会把同一章写两次、不会把大纲推进两次。3. CheckpointDeltaGuard防止 Agent嘴上说完成大模型偶尔会幻觉式收工——活没干完却结束了本轮。为此每个 Worker架构师/写手/编辑都挂了一个事实护栏 internal/agents/guard/subagent_guards.go本轮开始时的 checkpoint 是基线结束前必须看到对应 step 的新 checkpoint否则拒绝收工连续拦 3 次直接升级终止。弱模型死循环到这里也会被兜住——这是它敢让流程无人值守跑 3 天的底气之一。二、Saga 原子提交一章正文的跨文件事务1. 为什么需要 Saga一章提交要同时写多个文件终稿chapters/chXX.md、章节摘要、时间线、伏笔账本、角色关系、进度progress.json……文件系统没有跨文件事务写到一半断电怎么办答案是把这次提交做成一条Saga持久化意图先把完整提交意图 正文快照冻结到meta/pending_commit.json之后每一步都基于这份冻结载荷推进任何时刻崩溃都能精确续上。核心实现就在 internal/tools/commit_chapter.go。2. 四个阶段每走一步都留痕PendingCommit的状态机定义在 internal/domain/commit.go推进顺序是① started 冻结完整载荷 正文快照落盘 ② state_applied 终稿/摘要/时间线/伏笔等状态写入完成 ③ progress_marked 进度标记完成 提交结果固化 ④ signal_saved commit checkpoint 追加完成 最后清除 pending_commit提交闭环两个关键细节值得新手理解正文快照只认第一次。恢复时一律重放首次落盘的冻结载荷禁止采用重启后模型重新生成的参数或已被覆盖的草稿——否则会出现旧状态 新正文的错配这正是丢字的典型来源。checkpoint 必须先于清除意图。只有commitcheckpoint 落盘后才会删除pending_commit.json见 commit_chapter.go 注释。反过来重启后只要还能看到 pending_commit就知道上一轮提交没走完继续按阶段补齐即可。3. 崩溃在任何一个缝隙都只续不重假设崩溃发生在 ② 和 ③ 之间终稿文件已经写了但进度还没标记。重启后引擎读到pending_commit处于state_applied于是跳过已完成的写入直接从更新进度继续。因为每一步都是幂等的写入前查 checkpoint / 查 completed 列表重放不会产生重复章节。这就是标题里3 天不丢字的工程含义不是永不崩溃而是任何崩溃窗口内的每一步都已持久化意图恢复 按断点重放。三、单文件原子写最底层的最后一道保险上面所有落盘都有一个共同前提单个文件要么写成功、要么像没写过。ainovel-cli 用的是经典的temp 文件 fsync rename 原子替换方案设计见 docs/architecture.md内容先写到同目录临时文件fsync强制刷到磁盘rename原子覆盖目标路径操作系统保证 rename 是原子的——断电时你只会看到旧文件完整或新文件完整永远不会有一个写到一半的残文件。四、三层防线总结层级机制防的是什么文件层tmp fsync rename 原子替换写一半断电产生残文件Step 层checkpoints.jsonl 只追加 Digest 幂等重复执行、崩溃后重放提交层PendingCommit Saga 四阶段推进跨文件提交中断后的状态错配再配上 internal/agents/guard/subagent_guards.go 的收工护栏模型说完成了永远要换算成磁盘上有什么。五、延伸阅读想深入这套体系的更多设计决策Engine 循环、Arbiter 裁定、恢复流程推荐按顺序读这几份仓库内文档总体架构与铁律docs/architecture.md章节推进 Gate 与许可对账docs/chapter-advance-gate.md引擎与 Arbiter 协作docs/engine-arbiter.md关键源码checkpoint 存储 internal/store/checkpoints.go、Saga 定义 internal/domain/commit.go、提交工具 internal/tools/commit_chapter.go小结ainovel-cli 的不丢字不靠运气靠的是把完成从模型的话转换成磁盘上的事实——checkpoint 记每一步、Saga 管每一次提交、原子写保每一个文件。理解了这个模式对你自己写任何长时运行的 AI Agent 系统都有直接参考价值。【免费下载链接】ainovel-cli✨多agent实现全自动AI小说生成项目地址: https://gitcode.com/gh_mirrors/ai/ainovel-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
