Agent Orchestrator生命周期状态机:如何保守判定Agent死亡,避免误杀活跃会话
Agent Orchestrator生命周期状态机:如何保守判定Agent死亡,避免误杀活跃会话
Agent Orchestrator(项目代号 AO)是一个多编码智能体编排工具:它能从规划到合并(plan to merge)统一调度 Claude Code、Codex 等 27 种编码 Agent 组成的团队,支持桌面、Web、移动端与云端运行。当同时管理几十个 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)统一裁决。这种"观测层只报事实、写状态层唯一裁决"的分层,是避免误杀的第一道架构保险。
死亡判定第二道门:探针 + 近期活动双确认
就算探针报告 ProbeDead,LCM 也不会立刻动手。在 backend/internal/lifecycle/runtime.go 中,"明确死亡"(runtimeClearlyDead)需要同时满足两个条件:
- 探针结果为
ProbeDead; - 该会话在观察时刻的 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 对应的看板界面中直接看到每个会话的活动状态:
几个实用提示:
- 看到会话停在 waiting_input:这是 Agent 在等你下指令,直接发消息即可,系统会认为它是安全的可注入目标;
- 看到 blocked:说明 Agent 卡在权限确认对话框,需要你在界面上完成决策,自动化流程不会替你按键;
- 会话被标为 exited 且
is_terminated置位:说明它已经通过了上面全部四道门的保守判定,可以安全地清理工作区(或按 docs/plans/session-lifecycle-persistence.md 描述的保存/恢复机制取回未提交的工作)。
总结:保守判定是编排系统的第一性原理
Agent Orchestrator 的判死策略可以浓缩为四句话:
- 观测层只报事实:探针结果三态分明,"未知"永远不等于"死";
- 双条件判死:探针确认死亡 + 60 秒内无近期活动(粘性状态豁免);
- 断路器兜底:一轮内多数会话"集体死亡"视为基础设施故障,整轮降级为"结论存疑";
- 写操作世代围栏:终止动作分两阶段提交,并发变更会让误杀自动失效。
这套机制让 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/(注入前的最后一道实时守卫)。


