Agent Orchestrator生命周期状态机:如何保守判定Agent死亡,避免误杀活跃会话

原创2026-09-21 10:36:042,162 阅读

Agent Orchestrator生命周期状态机:如何保守判定Agent死亡,避免误杀活跃会话

Agent Orchestrator(项目代号 AO)是一个多编码智能体编排工具:它能从规划到合并(plan to merge)统一调度 Claude Code、Codex 等 27 种编码 Agent 组成的团队,支持桌面、Web、移动端与云端运行。当同时管理几十个 Agent 会话时,最难的问题不是"启动",而是"判死":系统必须知道哪个会话真的挂了,却不能把"暂时卡住"或"正在等你确认"的活跃会话误判为死亡——一旦误杀,用户未提交的工作就会随之丢失。

Agent Orchestrator 首页介绍 Agent 团队编排功能

为什么"误杀活跃会话"代价如此高昂

想象你在 AO 看板里同时跑着 8 个 Agent 会话。某天 tmux 短暂故障,探针全部报错。如果系统把"探测失败"直接当作"进程已死",8 个正在干活的会话会在同一秒内被全部归档——这正是 issue #3475 描述的灾难场景。

AO 的设计哲学是:宁可漏杀一次,不可错杀一次。漏杀只会在下一轮探测(每 5 秒一次)自动纠正;错杀则直接归档用户整块看板。

生命周期状态机:5 个状态与"粘性状态"

每个会话在数据库里只持久化两个事实:activity_state(活动状态)和 is_terminated(终止位)。活动状态共 5 种,定义在 backend/internal/domain/activity.go:

状态 含义 是否"粘性"(sticky)
active Agent 正在执行任务 ❌ 会随时间过期
idle 空闲待命 ❌ 会随时间过期
waiting_input 停在空提示符,等待你的下一条指令 ✅ 永不因时间降级
blocked 停在一个待决策的权限/确认对话框上 ✅ 永不因时间降级
exited 进程已退出 — 终态
active ──┬──> idle ──┐
         ├──> waiting_input ──(粘性,等用户输入)
         ├──> blocked ──(粘性,等用户决策)
         └──> exited (终态,判死后进入)

关键设计:粘性状态不会被时间"淘汰"。一个停在权限对话框上的 Agent,哪怕你 3 小时不看它,它也仍然是 blocked 而不是"失联死亡"。源码注释把 waiting_input 和 blocked 的区别讲得很清楚:前者"可以安全地发消息",后者的对话框上"任何多余按键都可能代替用户做了决定"——自动化发送器绝不能向 blocked 会话注入输入(见 backend/internal/domain/activity.go 的注释)。

死亡判定第一道门:探针结果只有三态,"未知"绝不等于"死"

负责轮询探活的是 reaper(收割器),位于 backend/internal/observe/reaper/reaper.go。它每 5 秒(DefaultTickInterval)对所有未终止会话做一次探针,结果分三种:

  • ProbeAlive — 进程活着
  • ProbeDead — 进程确认死了
  • ProbeFailed — 探测本身出错了(如 tmux 故障、适配器 bug)

这里有一条铁律:探针错误绝不会被折叠成 alive 或 dead。

为什么?如果把"失败"当成 alive,一次短暂的 tmux 故障会掩盖真正死掉的会话;如果把"失败"当成 dead,一个短暂的适配器 bug 就会终止真正活着的会话。所以报告 failed,让上层裁决。

另外,reaper 只负责"上报事实",从不直接写会话行——它把事实交给生命周期管理器(LCM)统一裁决。这种"观测层只报事实、写状态层唯一裁决"的分层,是避免误杀的第一道架构保险。

Agent Orchestrator 编排看板并行管理多个 Agent 会话

死亡判定第二道门:探针 + 近期活动双确认

就算探针报告 ProbeDead,LCM 也不会立刻动手。在 backend/internal/lifecycle/runtime.go 中,"明确死亡"(runtimeClearlyDead)需要同时满足两个条件:

  1. 探针结果为 ProbeDead;
  2. 该会话在观察时刻的 60 秒活动窗口(defaultRecentActivityWindow)内没有近期活动,且状态不是粘性状态。

也就是说:进程句柄没了,但 1 分钟前 Agent 还在疯狂写代码?那说明可能是探针对象(如 tmux 窗口)与真实进程出现了错位,系统选择不写任何状态,等下一个周期再看。粘性状态(waiting_input / blocked)则直接豁免"近期活动"检查——因为它们本来就不产生新活动,却仍然是活的。

防误杀的第三道门:大规模死亡断路器

这是整个设计中最有工程智慧的一环,同样在 backend/internal/observe/reaper/reaper.go:

如果一轮探测发现至少 5 个会话、且超过 50% 被判定为死亡,那就不是 N 个独立的 Agent 退出,而是一次基础设施故障(或适配器 bug)被误读了。

触发断路器后,本轮所有 ProbeDead 结论会被整体降级为 ProbeFailed,整块看板保持不动,等下一轮探测再重新裁决。代码注释里有一句话说得透彻:"28 个互不相关的 Agent 不可能在同一个探测周期内相继退出。"

小看板(少于 5 个会话)不受断路器影响——两个 Agent 同时正常收尾是完全正常的,无需特殊处理。

防误杀的第四道门:世代围栏与两阶段提交

判死之后的终止动作同样谨慎,实现在 backend/internal/lifecycle/manager.go 的 ApplyRuntimeObservation 中:

  • Launch ID 围栏:探针事实携带会话的 RuntimeLaunchID(启动世代号)。如果会话在判死与终止之间被切换了 Agent(agent switch)或被恢复,世代号对不上,终止操作直接放弃——绝不会杀掉"后来者"。
  • 两阶段提交 + 修订号校验:第一次 mutate 只"标记意图终止"并记录当时的 Revision;第二次 mutate 重新读取数据库,确认修订号、Launch ID 都没有变化、且"明确死亡"条件仍成立,才真正写入 is_terminated。中间任何时刻有并发写入,操作自动失效。

类似地,daemon 启动时判断"上一任进程文件是否过期"(backend/internal/daemon/stale.go)也不只看 PID——Windows 会激进复用 PID,仅凭"PID 还活着"就会误判前代进程尚存。AO 改为探测 /healthz 端点并同时匹配服务名与 PID,这才是"真正的前任还在监听"的地面真值。

普通用户如何观察这套状态机

状态机的成果直接体现在 AO 的界面上:每个会话卡片上的状态灯(运行中 / 等待输入 / 已退出)就是 activity_state 的可视化,"等待输入"的会话还会触发桌面通知。你可以在 docs/assets/readme/dashboard.png 对应的看板界面中直接看到每个会话的活动状态:

Agent Orchestrator 管理仪表盘展示 Agent 会话状态

几个实用提示:

  • 看到会话停在 waiting_input:这是 Agent 在等你下指令,直接发消息即可,系统会认为它是安全的可注入目标;
  • 看到 blocked:说明 Agent 卡在权限确认对话框,需要你在界面上完成决策,自动化流程不会替你按键;
  • 会话被标为 exited 且 is_terminated 置位:说明它已经通过了上面全部四道门的保守判定,可以安全地清理工作区(或按 docs/plans/session-lifecycle-persistence.md 描述的保存/恢复机制取回未提交的工作)。

总结:保守判定是编排系统的第一性原理

Agent Orchestrator 的判死策略可以浓缩为四句话:

  1. 观测层只报事实:探针结果三态分明,"未知"永远不等于"死";
  2. 双条件判死:探针确认死亡 + 60 秒内无近期活动(粘性状态豁免);
  3. 断路器兜底:一轮内多数会话"集体死亡"视为基础设施故障,整轮降级为"结论存疑";
  4. 写操作世代围栏:终止动作分两阶段提交,并发变更会让误杀自动失效。

这套机制让 AO 敢把 27 种 harness 的 Agent 团队托付给无人值守的守护进程——因为最坏情况下的行为是"再等 5 秒",而不是"删掉你的工作"。如果你想深入源码,推荐阅读顺序:backend/internal/domain/activity.go(状态模型)→ backend/internal/observe/reaper/reaper.go(观测与断路器)→ backend/internal/lifecycle/manager.go(裁决与提交),以及守护进程层的 backend/internal/daemon/supervisor/supervisor.go 与 backend/internal/sessionguard/(注入前的最后一道实时守卫)。

登录后查看全文
agent-orchestrator