MUNDERDIFFLIN / LEARN
CHAPTER 10
03 · ORCHESTRATION14 分钟阅读进阶

Hive:文件邮箱、任务账本与生命周期协调层

Hive 不是一个内嵌 LLM planner,而是主进程中的本地协调协议:registry + agent directories + task files + poll router + hooks + safety controllers。

本课核心问题多个真实 CLI 进程如何形成一个可协作团队?
学完你能
  • 理解 god/worker、task、mailbox 与 router 的职责。
  • 区分协调协议与模型推理。
01
概念关系

Office 是可视化;Agent 是长期身份;Worker 是一次运行实例

Office/Floor 主要存在于 renderer。Hive registry 保存 agent 身份、角色、cwd、session 与状态;PTY session 是这次运行。Ephemeral worker 由 spawn-requests 文件触发,通常带独立 worktree。

交互图解

Worktree 隔离与保全策略

检查 Git repomainRepoRoot
创建 agent/<id>worktrees/<id>
Agent 执行独立 cwd
退出审计dirty / ahead?
保留或清理fail safe
隔离是 best-effort;清理则偏向保全,脏或领先分支不会被自动删除。
02
消息路由

Agent 用 outbox 写信,Hive 每 1.5 秒路由到 inbox

发送者目录决定真实 from,路由器规范化消息、应用 hop cap、解析 god/human/broadcast、检查 provider 的安全投递能力,再写目标 inbox 或发出 terminal handoff。

  • 01human 不对应独立审批队列;消息被路由给 god/orchestrator 代理。
  • 02broadcast 只面向 active registry,排除归档 agent 与 send-only assistant。
  • 03未知收件人、hookless provider 或失败的 terminal handoff 会记录 drop/bounce,避免静默丢信。
  • 04outbox 文件成功路由后移动到 `.sent`;inbox 处理后进入 `.done`。
交互图解

Hive 文件协议与投递分支

INTENT
tasks.jsontodo · doing · blocked · done
ROUTER · 1.5s
HiveManagerregistry · route · log · Git
↙ inboxhandoff ↘
Hook / inbox Agent文件投递 + idle nudge
Terminal-only AgentRenderer 安全队列
Task ledger 表示工作意图;mailbox / terminal queue 才承担实际投递。
03
任务与状态

Task 状态与 Agent 状态是两套状态机

tasks.json 的卡片只有 todo / doing / blocked / done。Agent registry 记录 idle / working / blocked / gone;renderer 另外从 hook 与终端输出映射 idle / working / waiting / blocked。不要把 Kanban 状态当成进程状态。

04
防失控与收尾

Circuit Breaker 逐级升级;Closing Time 先保存再退出

Breaker 综合重复工具、错误风暴、token cap、速度与无进展信号,在 healthy → steering → constrained → stopped 间变化;hardStop 默认关闭。Closing Time 广播收尾、等待每个 worker ACK、验证 god COMPLETE 后才 teardown。

05
一致性模型

Hive 接受短暂不一致,但必须最终收敛且可解释

文件轮询、多个进程与终端 handoff 意味着 UI、mailbox 和 Agent 认知可能短暂不同。设计重点不是假装同步,而是定义状态推进、重试和最终证据。

任务板、收件箱和员工口头确认不会同一毫秒更新;系统要保证它们最终对上账。

LESSON CHECKPOINT

能用自己的话回答核心问题了吗?

Hive 用文件事实与安全投递协调进程,不代理它们的推理。