Munder Difflin源码解读五Stop Hook循环——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本文带你解读 Munder Difflin 多智能体框架中最关键的机制Stop Hook 循环。它利用 Claude Code 的 Stop 生命周期钩子让 Agent 在准备下班的瞬间自动领取新任务实现Agent 自主循环同时靠stop_hook_active标志、每 Agent 邮件游标、电路熔断器三道防线防死循环、防烧钱。读懂这一篇你就掌握了自主循环的核心原理与安全防护设计。从停止到继续Stop Hook 循环如何工作Claude Code 在 Agent 准备结束当前回合时会触发Stop钩子。钩子可以返回一个特殊响应{ decision: block, reason: 你还有未处理的消息请继续 }返回block意味着不许停——Agent 会把reason当作新指令继续干活。这就是自主循环引擎每次 Agent 想收工钩子都能递给它下一份活。Munder Difflin 正是靠这个机制让一群 Agent 在无人值守时持续消化任务队列。但钩子本身只是接口真正干活的是钩子背后的管道。每个 Agent 启动时都会挂上一个极简的hook shim钩子垫片它读取钩子 payload、打上自己的 Agent ID通过 Unix 域套接字转发给主进程再把主进程的响应原样传回 Claude。shim 的完整定义在 src/main/hive.tsclaude ──钩子触发──▶ shim ──Unix套接字──▶ 主进程 HookServer ▲ │ └────── 响应 ◀─────────┘shim 被刻意设计得又笨又稳socket 不存在或出错就直接退出5 秒超时兜底绝不在 Agent 的关键路径上阻塞。所有重逻辑都住在主进程。防死循环的三道防线自主循环的安全网能阻止 Agent 停止的能力天然存在无限循环的风险——Agent 收不了工、循环烧 token是自主循环最经典的事故。Munder Difflin 在源码里布了三道防线。第一道stop_hook_active 标志永远不连续拦截两次Claude Code 的钩子 payload 里带有一个stop_hook_active布尔值如果上一轮 Stop 钩子已经 block 过本轮它就是true。主进程收到 Stop 事件后的第一件事就是检查它若stop_hook_active为真直接放行让 Agent 停下来。这段逻辑在 src/main/hooks.ts。它的含义很简单粗暴却有效同一个回合最多只被按回去一次循环永远有出口从机制上杜绝了你不停我不放、我放了你又停的死锁式往复。第二道每 Agent 邮件游标一条消息只投递一次Agent 之间的协作靠文件收件箱inbox。早期设计中Stop 钩子会检查收件箱有未读消息就block并附上消息内容让 Agent 去处理——这就是 drainForStop 函数。关键细节是游标cursor每次投递后把最后处理的消息 ID 写进cursor.json。下次 Stop 时只取 ID 更新的新邮件。于是同一条消息只会被递到 Agent 手上恰好一次循环不可能围着旧邮件空转。值得注意的是当前版本的进一步演进主进程在 Stop 边界不再把未读邮件转成强制继续而是让渲染端通过仅空闲时投递的守护通道唤醒 Agent见 src/main/hooks.ts 的注释。原因很现实——旧路径会绕过终端草稿态和人在环安全可能在用户正回答 Agent 提问时偷偷烧掉订阅额度。邮箱文件依然是持久的只是投递时机更保守了。第三道电路熔断器CircuitBreaker循环失控的总保险前两道防线管的是Stop 边界但 Agent 也可能在回合内部打转反复调用同一个工具、不停重试报错、或疯狂生成 token。这类失控由独立的熔断器兜底它像电网的断路器一样按四级阶梯升级healthy → steering发纠正消息→ constrained加约束→ stopped终止并归档熔断器监听几类失控信号默认阈值见 src/main/breaker.ts重复工具调用连续 8 次名称参数完全相同的工具调用判定为循环。参数指纹用截断后的 SHA-256 哈希src/main/breaker.ts避免长命令前缀相同造成的误判错误风暴连续 5 次 API 错误/重试没有实质进展Token 速度输出 token 超过 60k/分钟的粗粒度背板无进展臂在持续烧 token 的同时四个进展时钟协作文件、工具调用、工作目录、人类对话全部过期且连续 2 个心跳满足才触发防止单次抖动误伤。它的安全设计同样值得学习每拍最多升一级绝不一觉跳到 kill每拍健康就降一级自动恢复最狠的hardStop默认关闭。压缩上下文/compact期间还有豁免窗口避免自己压缩触发了自己的熔断这类自伤issue #109。数据流全景钩子事件如何穿过 IPC 边界把前面拼起来一次 Stop 事件的数据流是这样的Claude 触发 Stop → shim 读取 stdin payload打上AGENT_ID经 Unix 套接字发出主进程 HookServer 按换行分帧接收单帧上限 256KB超限直接断连记日志检查stop_hook_active→ 有则放行事件转发给渲染端前先过一道 validateHookEvent 白名单校验——不信任任何跨进程 payload无进展、重复调用等信号同步喂给熔断器由心跳统一裁决。自主循环清单给想自建 Agent Harness 的你读完源码可以提炼出一份写自己的自主循环时可直接抄的清单✅尊重stop_hook_active任何能 block 的 Stop 钩子都必须查它否则必造死循环✅投递幂等用游标或已处理标记保证每份任务只递一次✅失败开放fail-openshim 出错就静默退出钩子绝不能卡死 Agent✅循环检测独立于 Stop 边界回合内打转靠重复工具调用 错误风暴等信号另设熔断✅升级要克制熔断阶梯每拍只动一级且能自动降级避免误杀好 Agent✅跨进程数据先校验不可信 payload 过白名单再进渲染层。Stop Hook 循环是 Munder Difflin 让 Agent 团队下班后还在干活的心脏而上面这几道防线是让这颗心脏敢放心跳下去的底气。想深入钩子生命周期全貌可延伸阅读项目博客中的 Claude Code Hooks 详解。【免费下载链接】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），仅供参考