从单终端到一支 Agent 团队Munder Difflin 如何把并行的 Claude Code 会话升级为协调协作的 Agent 团队【免费下载链接】munder-difflinA local multi-agent harness that works with your existing Claude Code, Codex subscriptions, allows you to run an office of agents项目地址: https://gitcode.com/GitHub_Trending/mu/munder-difflin大多数团队并不是决定要跑一支 Agent 大军而是一次多开一个终端直到工作流被撑爆。这篇指南完整梳理这条演进弧线——一个会话 → 几个手工终端 → 一支协调的团队——并在每一步讲清楚哪里会出问题、为什么出问题、靠什么机制解决同时以 Munder Difflin 开源仓库中的 Hive 协调层实现 为源码证据说明角色、共享记忆、消息传递与编排器这四根支柱在底层是如何落地的。读完之后你将能判断自己的工作流处于哪个阶段、什么时候该迈出升级的那一步以及 Munder Difflin 为每个痛点提供了哪些现成机制。三个阶段从单会话到团队Stage 1一个终端——吞吐量的天花板你运行一个claude会话。它专注、易于跟进对大多数任务来说已经足够。唯一的瓶颈是吞吐量——一个 Agent 同一时刻只能做一件事而房间里唯一的并行度就是你本人。推动你前进的痛点你在等 Agent 的时候另外三件本可并行的事闲置着。Stage 2几个手工终端——三座大山于是你打开更多终端——这是 如何并行运行多个 Claude Code Agent 中描述过的经典动作。一个写测试一个做重构一个改文档。吞吐量上去了。对两三个相互独立的任务这确实管用。但一旦任务开始重叠三个问题立刻浮现文件冲突Collisions两个 Agent 编辑同一个文件互相竞争在 git 仓库里你会看到index.lock错误和只应用了一半的改动。健忘Amnesia每个会话都有自己的上下文。Agent A 学到的东西 Agent B 无法使用——于是你成了信使在窗口之间复制粘贴发现。失控Lost track开着六个标签页现在每个人在干什么没有答案。推动你前进的痛点你变成了消息总线、冲突解决者和项目唯一的记忆。Agent 变快了你成了瓶颈。值得注意index.lock并非手工多开场景独有的问题。即便在 Munder Difflin 的 Hive 内部多人/多进程并发写同一个 git 仓库同样会触发它——仓库在 Hive 的 git 提交实现 中对此做了两层防御提交重试最多 5 次遇到index.lock时按 50ms×(attempt1) 退避并在每次提交前清理超过 10 秒的陈旧锁文件index.lock/HEAD.lock见 clearStaleLock。这说明锁冲突是任何多写者场景的通用敌人需要显式的协调规则来解决而不是靠多开几个窗口。Stage 3一支协调的团队——四根支柱修复方案不是更多的标签页而是一个协调层。三项/四样东西把并行的会话变成一支团队角色Roles——每个 Agent 守在自己的车道上这件事归谁做一目了然。共享记忆Shared memory——整个团队读写同一份长期记忆不再重复学习项目。消息 编排器Messaging an orchestrator——Agent 之间通过信箱直接交接工作协调者负责路由而不是经由你来中转。这就是从摆弄 Claude Code Agent 到运行多 Agent harness 的跨越——也是加 Agent 不再增加开销的阶段。更完整的办公室运转起来需要什么可参见 run-an-office-of-ai-agents它补充了第四根支柱护栏Guardrails让人不在场时例行工作继续、风险动作排队等你批准。前后对比同一件事两种跑法同一个上午两种方式手工终端协调团队分配工作你逐个标签页描述意图编排器路由上下文共享你在窗口间复制粘贴共享记忆Agent 自己读交接你来转发结果Agent 之间直接发消息文件冲突index.lock、手工清理协调规则提前防止现在什么情况Alt-Tab 加猜测扫一眼办公室地板floor你的角色消息总线管理者Agent 本身没有任何变化——它们还是那些 Claude Code 会话。变的是环绕它们的那一层而这正是把你从操作员变成管理者的东西。什么时候该跳你不需要一支团队才能用 Claude Code。当以下情况出现时你就需要了你同时开着三个或更多会话并且快跟不上了你不断重复解释上下文因为每个会话都会忘记Agent 在同一批文件上冲突。如果符合这些描述下一步就是协调层——而且整个过程可以保持本地优先。自然的终点是一支在你登出后仍持续交付的 Agent 办公室。源码视角协调层在 Munder Difflin 里是怎么落地的上面的表格是对协调层最直观的概括。落到开源仓库里这层由 Hiveon-disk 多 Agent 协调层与若干配套模块共同实现。以下按四根支柱逐一展开。支柱一角色——identity.md与 registry 的角色保真在 Hive 中每个 Agent 拥有独立工作区agents/id/其中identity.md是我是谁的权威描述由 harness 写入Agent 只读registry.json保存每个 Agent 的持久角色。关键设计约束是角色必须是持久的工作描述job而不是瞬时的运行状态。agentRole.ts 里有一份瞬时状态正则把standby、idle、paused、working、thinking、starting up这类状态词判为非持久角色从而保证重启/同步时preferredAgentRole()会优先保留真正的工作描述比如 test-writer而不是被一条 on standby 的状态字幕覆盖。这正是让每个 Agent 各守车道、谁来做这件事一目了然的底层机制角色跟着 Agent 走状态单独记录。支柱二共享记忆——markdown 优先 MemPalace 语义召回Stage 2 的健忘问题在源码里对应 memory.ts 的MemoryManager。它实践了写持久事实到 markdown 语义索引的两层模型写每个 Agent 的memory.md存放持久事实决策、约定、坑hive 启动时若不存在则自动创建模板见 ensureAgent 中的 memory 初始化。存mempalace mine agentDir --wing id --agent id把每个 Agent 的记忆挖进共享 palace 的独立 wing。mine 循环每 10 分钟一轮跳过memory.md未变化的 Agent并保证串行palace 只允许单写者。取mempalace search q --results N按语义召回最相关的笔记mempalace wake-up生成约 600–900 token 的会话开始摘要注入 Agent 上下文——上下文窗口保持小知识库再大也能即时召回。设计中还有一处与多写者撕裂呼应的细节Agent 的.gitignore会排除settings.json、cursor.json、inbox/、outbox/、.codex/等非记忆文件避免它们被挖进语义索引或撑爆 hive 的 git 历史。而每份记忆文件单写者的原则见 memory 文档建议与 hive 整体单提交者 git的设计一脉相承。支柱三消息传递——文件信箱 路由器 防循环协议Stage 2 的你成了消息总线在源码里对应 Hive 的信箱模型每个 Agent 有inbox/与outbox/Agent 只往自己的outbox/写 JSON 文件harness 负责投递Never write into another agents folder见 hive 协议。消息结构{ to, act, subject, body, conversation?, in_reply_to? }to可以是某个 agentId、god或broadcastact取request | inform | propose | query | agree | refuse | done。id、from、hops、时间戳由 harness 补齐HiveMessage 类型。防死循环只有request、query、propose期待回复inform和done是终态消息——协议明确要求不要回复它们否则两个 Agent 会无限互 ping。路由层还有HOP_CAP 12的跳数上限HiveMessage.hops 处理超过即视为循环并处理。容错投递前对 outbox JSON 做防御性修复——只修复字符串内部的字面换行\n/\r其余结构性坏 JSON 会被隔离quarantine而不是阻塞投递。这一点有专门的测试覆盖hive-malformed-outbox.test.cjs 验证了字面 LF 被修复并路由字面 CRLF 被修复并保留不可修复的结构性 JSON 被记录并隔离三个场景。人机回环没有单独的审批队列。需要人的决策时Agent 把消息发给godto: human会被路由到 god即人的代理人的批准直接发生在该 Agent 自己的 Claude Code 会话里可通过/remote-control远程批准。支柱四编排器与可见性——GOD、地板floor与护栏GOD 编排器你像对经理说话一样向它描述意图它分解并把任务路由给空闲 Agent。它还可以主动孵化临时 worker在spawn-requests/id.json写一个 JSON含objective、cwd等字段由 harness 拉起新会话。在 agentRole.ts 中 god 的默认角色是orchestrator (god)。可见性hive 根目录的fleet.json持续刷新每个 Agent 的 token、成本、状态、熔断等级、最近工具调用、最后活跃时间与收件箱积压registry.json是花名册log.jsonl是追加式事件流专门排除了可能含密钥的原始 PTY 转储。这就是扫一眼地板的实现。PROTOCOL.md 特别提醒claude agents命令看不到hive 的兄弟会话fleet.json才是真相来源。操作控制control.ts 的ControlRegistry提供 pause / gateTool / steer / halt 四类操作员控制暂停或门控某个工具时hook 返回permissionDecision:denysteer 把一段引导文本作为additionalContext注入 Agent 的下一次 hook 边界每 Agent 最多排队 20 条满了丢最旧的halt 让 Agent 在下一个 hook 边界干净地停止continue:false而不是强杀 PTY。所有控制都走 Claude Code 自己的 hook 返回协议无需往 PTY 里打字。护栏熔断器监视每个 Agent 的失控行为重复同一工具、错误风暴、超支按steer → constrain → stop升级token 预算跨整个地板生效每个 Agent 可单独设限。这对应routine 工作继续、风险动作排队等你的护栏承诺。持久化与备份roster 的防丢失设计协调层还包含对团队状态本身的持久化保障。roster.ts 的RosterStore把地板卡片、笔记、队列、worktree 路径镜像到harnessHome/roster.json并有三条硬性规则每次写入前先把旧文件复制进只追加的roster-backups/绝不修剪写入走临时文件 rename原子替换崩溃不会留下半截文件空快照在本次运行尚未有过非空写入前会被拒绝防止首次启动时空 localStorage 冲掉真实 roster。此外消息正文在跨出主进程前会经过 redactSecrets 脱敏——密钥形状PEM、JWT、sk-ant-前缀、bearer token、keyvalue赋值等会被替换为[redacted]渲染层永远拿不到原始密钥。落地建议如何用这套认知升级自己的工作流先评估自己处在哪个阶段如果只有一两个独立任务手工终端足够一旦出现三座大山中的任意一座就是引入协调层的信号。从角色开始给每个 Agent 命名并限定职责test-writer / reviewer / refactorer让谁做什么显式化——这也正好对齐agentRole.ts中持久角色 vs 瞬时状态的区分原则。补齐记忆为每个 Agent 建立memory.md并约定学到持久事实就追加再叠加语义召回避免重复解释。让交接走信箱把你转发结果改成 Agent 间直接发消息注意只对request/query/propose回复避免死循环。用编排器分配、用地板监督描述意图而不是逐条指派用fleet.json/ 地板视图掌握全局靠熔断与 token 预算兜底。Munder Difflin 正是 Claude Code Agent 的协调层——角色、共享记忆、消息、编排器与护栏全部本地运行本地优先的意义见 why-local-first-matters-for-ai-agents。想了解更大的图景可继续阅读 多 Agent harness 是什么 与 Hive 设计文档。【免费下载链接】munder-difflinA local multi-agent harness that works with your existing Claude Code, Codex subscriptions, allows you to run an office of agents项目地址: https://gitcode.com/GitHub_Trending/mu/munder-difflin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考