Hive崩溃安全设计揭秘:状态持久化、游标恢复与park/resume完全解析
Hive崩溃安全设计揭秘:状态持久化、游标恢复与park/resume完全解析
Hive 是一个面向生产环境的多智能体运行框架(Multi-Agent Harness for Production AI),让"蜂后"(Queen)带领一群 Worker 智能体持续干活。但生产环境最怕进程崩溃、断电或用户误杀——Hive 的答案是三层崩溃安全设计:状态持久化、游标恢复、park/resume。本文带你从零看懂这些机制,让你放心让 Agent 无人值守跑一整天。
一、为什么多智能体系统最怕"掉线"
单个 Agent 卡死,重跑一次就行;但多智能体系统里,Queen 可能已经派发了 5 个 Worker、改了 3 个数据库、积累了 200 条对话。此时进程一挂:
- 💥 对话历史丢了 → 重启后 Agent"失忆",重复劳动
- 💥 工具调用计数清零 → 预算控制(防无限循环)失效
- 💥 用户明明点了"停止",重启后 Agent 却自己复活 → 体验灾难
Hive 的解法核心就一句话:每一步都把"断点"写到磁盘,重启后从断点精确续跑。
二、状态持久化:每轮循环都落一个"快照游标"
Agent 主循环的每一步结束时,Hive 都会写入一个 cursor(游标) 文件,记录当前进度。核心实现见 cursor_persistence.py。
游标里到底存了什么?看 write_cursor 函数,一共 6 类关键状态:
| 字段 | 作用 |
|---|---|
iteration |
当前是第几轮循环,恢复后从 iteration+1 继续 |
outputs |
已产出的中间结果(累加器快照) |
recent_responses / recent_tool_fingerprints |
卡死检测 & 死循环检测的"指纹窗口" |
pending_input |
正等用户回答的问题,重启后继续等,而不是瞎编一个续写 |
user_stopped |
用户是否手动点了停止 |
其中两个细节特别能体现"生产级"的严谨:
🔒 user_stopped 必须落盘。源码注释写得很直白:这个标志如果不持久化,进程被杀后标志就丢了,Queen 重启后会自动"复活"——正是用户停止功能要防止的 Bug(见 cursor_persistence.py)。
🔒 tool_calls_used 跨恢复累计。工具调用预算是"整个任务生命周期"的上限,而不是"每次重启后重新充满"——否则反复崩溃重启就能无限刷工具调用。
底层写入同样讲究原子性:Hive 采用临时文件 + fsync + os.replace 的原子写模式(见 _atomic_write_json),即使写到一半断电,磁盘上也只会留下"旧文件"或"完整新文件",绝不会是半截垃圾数据。
三、游标恢复:重启后如何"无缝续跑"
进程重启后,Hive 会调用 restore 从对话存储中重建完整现场:
- 加载对话历史 —— 按
agent_id/run_id过滤,让每个 Worker 只看到自己那条消息线 - 重建输出累加器 —— 恢复已产出的中间结果
- 读取游标 —— 拿到迭代计数、卡死/死循环检测窗口、待回答的输入
- 智能区分"崩溃恢复"与"新任务" —— 如果按
run_id过滤后消息数为 0,说明是用户主动发起了新运行,直接走全新会话路径,而不是错误地"续命"旧任务
恢复完成后,主循环从 start_iteration 继续,配合注入队列排空(drain_injection_queue),崩溃期间用户发来的消息也会带时间戳补进对话——消息不丢,顺序不乱。
四、park/resume 机制完全解析
park(泊车)是 Hive 里非常优雅的概念:Agent 遇到"必须等人回答"的情况时,不是空转等待,而是把循环暂停、状态封存,等输入到达后再 resume(续跑)。
4.1 什么情况下会 park?
Hive 定义了一组显式的 ParkReason 枚举,全部原因可枚举、可观测:
ASK_USER/CREDENTIAL_FORM:要问用户问题 / 需要填写凭据AWAITING_QUEEN:Worker 在等 Queen 的下一步指令DOOM_LOOP/EMPTY_RESPONSES/LLM_ERROR:检测到死循环、空响应或模型报错USER_STOPPED/COLD_INTERRUPTED:用户停止 / 冷中断TURN_DONE:一轮任务完成,等待新指令
每次 park 都会同步更新"活跃度状态"(见 agent_loop.py),前端 UI 能准确显示"这个 Agent 是在睡觉还是在等输入"。
4.2 Sentinel:让"等人回答"跨重启存活
真正生产级的 park/resume,还要回答一个问题:Agent park 着等人回复,这时服务器重启了,用户半天后才在 Telegram 里回了消息,怎么办?
Hive 的 Sentinel 哨兵模块就是为此设计的(sentinel/):
- 📁 每条待办升级都落盘成一个 JSON 记录:
~/.hive/colonies/<id>/escalations/<id>.json。磁盘是唯一事实来源,所以重启后用户回复依然能正确路由(设计说明见 store.py 顶部注释) - 📡 管理器启动时会扫描磁盘上所有 open 记录,重建内存索引(list_all_open)
- 📬 用户回复到达后,manager.py 的 _resume 方法把答案注入回"泊车中"的 Queen,循环从断点 resume,就像中断从未发生过
默认走内置 Hive Inbox 通道,也可配置 Telegram / Slack 通知,配合文档 hive-inbox-design.md 可以了解完整设计。
4.3 事件游标:重启后历史"不断流"
还有一处容易忽略的游标:事件总线序号。冷启动恢复的会话必须产生单调递增的事件序号,前端重放历史时才能正确拼接——这是 event_bus.py 中冷恢复(cold resume)路径专门处理的部分,保证崩溃重启不会让前端时间线出现乱序或跳号。
五、如何验证这套机制?(附源码入口)
Hive 为崩溃安全提供了成体系的测试与文档入口:
- 🧪 游标恢复与事件循环:test_event_loop_node.py、test_cancel_user_stop_flow.py
- 🧪 Sentinel park/恢复链路:test_sentinel_park_tail.py、test_sentinel_manager.py
- 📖 对话与状态存储:conversation_store.py
- 📖 总体架构文档:docs/architecture/
- 📖 多入口智能体设计:multi-entry-point-agents.md
想动手验证,可以直接阅读 agent_loop.py 中 _await_user_input 与 _park_reason_from_cursor 的调用链,观察一次"park → 杀进程 → 重启 → resume"的完整闭环。
六、总结:三层防线让 Agent 敢"过夜"
Hive 的崩溃安全不是补丁式防御,而是贯穿主循环的系统设计:
- 状态持久化——每轮循环写原子游标,进度、预算、停止标志全落盘
- 游标恢复——重启后精确续跑,还能区分"崩溃恢复"与"新任务"
- park/resume——用显式原因枚举暂停循环,配合磁盘化的 Sentinel 记录,让"等人回答"也能跨重启存活
正是这套组合拳,Hive 才能名如其义地成为 Production AI 的多智能体框架——你可以关掉浏览器去睡觉,明天回来时,你的蜂群还在断点处继续工作。🐝
