fractal崩溃后的完整恢复:崩溃自动修复、孤儿节点对账与暂停恢复终极指南

原创2026-10-26 22:03:291,813 阅读

fractal崩溃后的完整恢复:崩溃自动修复、孤儿节点对账与暂停恢复终极指南

fractal 是一款面向分层 AI Agent 循环的管理工具,它让多个 agent 节点各自在独立的 git worktree 中迭代工作,并以本地 SQLite 数据库记录全部运行状态。当机器重启、tmux 会话被杀或误删了 worktree 时,fractal 的崩溃恢复机制能让整棵节点树自动回到可用状态——本文带你完整掌握崩溃自动修复、孤儿节点对账与暂停恢复三大核心能力。

一、先搞懂状态:fractal 如何记录每个节点的生死

fractal 中每个节点(node)的状态由一个词表示,存储在节点的 .status 文件里,同时镜像到中央数据库的 nodes 注册表中。完整状态集包括:idle、active、paused、completed、stopped、exited、killed、failed、retired。

理解恢复机制前,记住两个关键分类:

  • 未结算状态(active、paused、idle):占用树的容量配额,随时可能"复活";
  • 已结算状态(completed、stopped、exited、killed):运行已结束,可通过 start --continue 重新武装。

状态与数据库行(runs、iterations、steps、events)之间的一致性,正是崩溃恢复要保障的核心。状态机的完整规则见 wiki/features/lifecycle/status_machine.md,官方文档的状态表在 docs/guide/lifecycle.rst。

打开 fractal open 即可进入 TUI 仪表盘,实时查看整棵节点树的运行状态、花费与事件日志:

fractal 崩溃恢复与暂停恢复的 TUI 节点树监控仪表盘

二、崩溃自动修复:节点卡在 active 怎么办

🔥 这是最典型的崩溃场景:节点的循环进程意外死亡——无论是被 tmux kill-session 直接杀掉、宿主机器崩溃,还是进程被 OOM 终结——数据库里的 .status 文件仍然写着 active,但 tmux 会话已经不存在了。

如果放任不管,所有要求"拒绝 active 节点"的操作(merge、delete、retire 等)都会永久卡死在这个幽灵状态上。

自动修复原理:用"证据"而非"猜测"

fractal 的修复逻辑(Node._reconcile_status,见 fractal/core/node.py)基于一条铁律:每个节点同一时刻只允许一个循环(由 start.sh 强制保证)。因此,"会话被证实不存在"就等于"循环确实已死":

  1. 探测 tmux 会话——必须得到确定性答案才会动手;
  2. 状态戳改为诚实的 exited;
  3. 同时关闭该次运行仍开着的 runs/iters/steps 数据库行,避免 DB 与状态文件互相矛盾;
  4. 顺带回收循环记录的残留进程组(无头 agent 会继续悄悄烧钱),并修复 config 与注册表之间的配额漂移。

修复何时触发?答案是:什么都不用做

对账(reconcile)是自动执行的,时机包括:

  • 任何信号动词(finish、stop、pause 等)执行前;
  • merge、delete、retire、start --continue 执行前;
  • 甚至只是读取时——fractal node status 和 fractal node list 都会把"已被证实死亡"的 active 行修复并持久化,而不是原样回显。

端到端测试 tests/test_cli/test_reconcile_cli.py 验证了这一点:一个循环死亡、状态卡在 active 的节点,执行 node retire 时会先被自动对账为 exited,然后正常退休——全程无需手改状态文件。

两个刻意的边界(安全设计)

  • paused 节点绝不会被修复。 暂停的节点本来就没有会话——这是它的正常"停车"状态,不是崩溃。即使在另一台主机上挂载了文件系统,它也不会被误伤;
  • tmux 探测无结果时不修复。 修复只依赖"确凿证据",绝不依赖"无知"。在没有 tmux 可见性的 cron/CI 环境里,盲目修复可能杀掉健康循环的进程组——所以探测失败时宁可不动。

三、孤儿节点对账:worktree 被误删后的审计留痕

另一种常见"数据不一致":你用普通 git 命令(而不是 fractal node delete)手动删除了某个节点的 worktree。此时数据库里的注册行还在,但磁盘上已经没有对应的 worktree 了——这就是孤儿节点(orphan)。

fractal node list 会在 detail 列把这类行标记为 orphaned,仅作展示。而审计工具是:

fractal node reconcile [node]

它会扫描注册表中每个已登记的后代,对工作树缺失的节点各记录一条 orphan 事件(已记录过的分支自动跳过),输出形如 Recorded orphaned node main.c1. 的确认。实现见 fractal/core/node.py 与 CLI 入口 fractal/cli/cmd/node.py。

⚠️ 注意:对账只留痕,不清理——注册行被保留,因为历史数据(runs、events、messages)是有价值的。真正移除孤儿的路径是:

fractal node delete <branch> --force

它会注销孤儿注册、修剪 git 分支与缓存条目,若子树中仍有活着的 worktree 则拒绝执行。三档拆除(delete / reset / destroy)的完整守卫规则见 wiki/user_flow/teardown.md。

四、暂停与恢复:原地冻结,原样解冻

fractal 提供两套"中断-重入"机制,语义完全不同,选错会损失状态:

机制 语义 保留什么 适用场景
pause / resume 原地冻结并解冻同一次运行 预算、迭代计数、被打断的步骤、agent 会话 重启机器、临时离开、冻结开销
stop / start --continue 干净结束并新开一次运行 仅 worktree 中的已提交成果 方向要变、预算要重新武装

暂停为什么"零丢失"

fractal node pause 的信号先于 agent 中止落地,循环因此把被打断的步骤重新归类为 paused 而非 failed,然后整个进程退出、tmux 会话消失——没有任何提交。此时脏 worktree 本身就是冻结在半途迭代上的状态,resume 会从这些字节继续。设计动机详解见 wiki/design/durability.md。

暂停期间节点仍保持"存在":占用它的生成槽位、阻塞祖先的 finish 排空;唯一合法动词是 resume、kill 和 chat(你甚至可以向冻结的节点提问)。

恢复时发生什么

fractal node resume 以叶优先顺序重启子树(保证子节点先于父节点的排空检查读回 active),每个循环接管(adopt)自己未关闭的运行行:同样的预算、同样的迭代编号、被打断的步骤重新进入。

一个容易被忽略的细节:运行与迭代的超时是墙钟时间,fractal 会把每段暂停时长从截止时间中扣回——一个暂停一整夜的节点醒来时不会发现自己已经超时了。

全树急停:fractal pause 与 fractal resume

在根节点上执行的 fractal pause 是整棵树的刹车:

$ fractal pause --reason "reboot host"
$ fractal resume

它会先给根节点上闩(在中央数据库旁写一个 .paused 标记文件),再扇出暂停所有活跃节点。这意味着即使有生成或启动操作与扇出扫描竞速,也会在闩锁前被拒绝。恢复时先解除闩锁(新工作立即合法化),再叶优先重启所有停泊的循环。这是应对机器关机、大型树暂停、即时冻结开销的标准工具。

命令契约细节见 wiki/features/lifecycle/commands.md,两条路径的选择指南在 wiki/user_flow/continue_resume.md。

五、实战恢复清单:出事后按顺序检查

📋 遇到异常时,按这个顺序排查:

  1. fractal node list --live — 重新校验现实:崩溃的 active 节点会被自动重标为 exited,worktree 消失的节点被剔除,一眼看到全局;
  2. 发现卡在 active 的节点 — 什么都不用做,任何后续动词或读取都会自动触发崩溃对账;
  3. 发现 orphaned 标记 — 运行 fractal node reconcile 留痕审计,确认后 delete <branch> --force 注销;
  4. 需要跨重启保留现场 — 养成关机前 fractal pause --reason "..." 的习惯,开机后 fractal resume 精确回到冻结点;
  5. 运行已结束但想续跑 — fractal node start --continue <node>(若上次是预算耗尽结束,必须显式传 --max-cost 重新授权花费);
  6. 想确认一切正常 — fractal open 打开 TUI,核对节点树状态、花费与事件日志。

总结

fractal 的恢复体系建立在一条简洁的原则上:状态必须诚实,且可以被证明。

  • 崩溃自动修复只依赖"会话被证实消失"这一硬证据,且自动发生在下一次读取或动词执行时——你永远不会需要手改状态文件;
  • 孤儿节点对账为带外清理留下完整的 orphan 事件审计链,历史数据永不因清理而丢失;
  • 暂停/恢复把"停机"变成一种持久化状态:进程可以完全消失,重启主机、迁移文件系统都不影响 resume 精确接管。

掌握这三层机制,你的 agent 树就能在任何意外后快速、无损地回到正轨。

登录后查看全文
fractal