夜雨聆风
Harness机制解析:51万行源码泄露背后,多Agent系统协同工作的关键技术突破
一、查询循环：一个”不信任模型”的 while(true)
Harness 的心脏是一个查询循环（Query Loop），核心逻辑简单到令人意外——就是一个 while(true) 循环。
每一轮迭代的流程是：压缩检查 → 组装消息 → 调用API → 处理响应 → 执行工具 → 判断是否继续。看起来平平无奇，但魔鬼藏在细节里。
源码注释中有一句话格外醒目：“stop_reason is unreliable”。
这意味着 Claude Code 的工程团队做了一个非常关键的决策：不依赖模型返回的”我说完了”信号来判断任务是否结束。取而代之的方案是检测 toolUseBlocks 数组是否为空——也就是说，不看模型”说了什么”，而看”还有没有事要做”。
这个设计哲学贯穿了整个 Harness 的灵魂：对模型保持适度的不信任，用工程化手段兜底。 就像你不会因为实习生说”我做完了”就直接合并代码，你会去看他的PR里还有没有未处理的TODO。
二、流式工具执行：不等人齐就开干
传统的工具调用方式是”收集所有请求 → 统一执行 → 返回结果”。但 Claude Code 的 StreamingToolExecutor 采用了一种更激进的策略：收到一个 tool_use 就立即开始执行，不等所有工具请求到齐。
这就像一个高效的厨房——不会等所有菜单都下完才开始备菜，而是来一张单就开始处理。
但并行执行有一个天然的风险：如果两个工具同时修改同一个文件怎么办？Claude Code 的解决方案是引入了 isConcurrencySafe 标记。Read、Grep、Glob 这类只读操作可以并行执行；而 Edit、Write、Bash 这类写操作必须串行排队。底层用队列系统调度，并且有一条硬规则：并行工具中有一个失败，则取消所有兄弟工具。
这套机制让 Agent 的工具调用效率大幅提升，同时又不会因为并发冲突导致状态混乱。工程上的取舍拿捏得相当精准。
三、多层权限系统：Agent 安全落地的生命线
如果说前两个模块解决的是”能不能干活”的问题，那权限系统解决的就是”敢不敢让它干活”的问题。
Claude Code 设计了一套从严到宽的权限模式：plan → default → acceptEdits → auto → dontAsk → bypassPermissions。每一次工具调用都要经过五步检查流水线：否决规则 → 询问规则 → 工具自身权限 → 模式决策 → Hook一票否决。
其中最值得关注的是 Bash 命令的风险评估机制。它没有采用传统的”危险命令黑名单”这种硬编码方式，而是结合了 shell-quote 进行结构化解析，再加上 LLM 的语义理解来综合判断一条命令是否安全。
为什么不用黑名单？因为黑名单永远是滞后的。rm -rf / 你能拦住，但 find / -delete 呢？cat /dev/null > important_file 呢？只有让模型真正”理解”命令的语义，才能应对千变万化的风险场景。
这套权限系统是 Agent 从”玩具”走向”生产工具”的关键一步。没有它，没有任何企业敢把 Agent 放进真实的开发环境。
四、四层记忆系统：让 Agent 拥有”工作记忆”
人类程序员之所以能高效工作，很大程度上依赖记忆——项目的代码规范、上次讨论的技术决策、当前任务的进展。Claude Code 为 Agent 构建了一套四层记忆体系，每一层解决不同时间尺度的记忆需求。
CLAUDE.md 是手动编写的项目级和用户级指令，按目录层级从根目录到当前目录逐层加载，越近的优先级越高。你可以把它理解为项目的”.editorconfig”或”CONTRIBUTING.md”——告诉 Agent 这个项目的规矩是什么。
MEMORY.md 是模型自动维护的长期记忆，由子代理在后台默默提取和更新。这就像你的笔记本，Agent 会把重要的发现和决策记下来，下次用到时自动调取。
Session Memory 面向当前会话，记录的是这一轮对话的运行摘要。类似于你打开IDE时的”最近操作历史”。
最后是上下文压缩机制，分为两个层级：Micro压缩负责清理旧的工具返回值（那些已经用过的中间结果没必要一直占着上下文窗口）；完整压缩则通过 Session Memory 摘要或 API 生成摘要来大幅缩减上下文长度。
这四层记忆系统协同工作，让 Agent 既能记住长期规则，又能灵活应对当前任务，还不会因为上下文爆炸而”失忆”。
五、Prompt Cache 友好设计：省钱才是硬道理
这个模块听起来不那么”性感”，但它直接关系到 Agent 系统的运营成本——而成本，往往是决定一个技术方案能否大规模落地的关键因素。
Claude Code 的做法是将系统提示词分为静态段落和动态段落两部分。静态段落（比如基础指令、工具定义）在多轮对话中保持不变，对缓存非常友好；动态段落（比如当前上下文、用户最新输入）每轮刷新。
还有一个细节值得玩味：工具列表按字母排序。为什么？因为如果工具列表的顺序每次都不一样，缓存就会失效。按字母排序保证了顺序的稳定性，从而最大化缓存命中率。
效果如何？缓存命中时，成本降低约90%。对于一个需要频繁调用API的 Agent 系统来说，这不是优化，这是生存线。
六、子代理模式：让”管家”和”干活的”各司其职
最后一个模块是子代理模式。Claude Code 把”管理对话”和”回答问题”拆成了两个独立的关注点。
压缩上下文、提取记忆、整理会话摘要——这些”家务活”不由主代理亲自处理，而是创建子代理来完成。子代理共享父对话的 prompt cache，所以创建成本极低。
这个设计的精妙之处在于：主代理可以专注于用户的问题，不会被”家务事”打断思路。 就像一个高效的团队，有人负责写代码，有人负责整理文档和会议纪要，各司其职，互不干扰。
回过头来看，Claude Code 这51万行源码真正揭示的，不是某个模型有多强大，而是工程化能力才是 Agent 落地的真正护城河。
正如人人都是产品经理热榜上那篇文章所指出的：多Agent系统的真正瓶颈从来不是智能，而是治理。 单个Agent再聪明，如果没有稳定的执行循环、安全的权限管控、可靠的记忆系统和高效的协作机制，它在真实环境中就是一个”高智商但不靠谱”的队友。
Harness 机制的意义在于，它给出了一个经过工业级验证的答案：长链路执行、工具并发、权限分层、记忆沉淀、压缩恢复、子代理协作——这六个维度，构成了把AI从”会说”推向”能干活”的完整工程骨架。
2026年，我们正站在 Agent 大规模落地的前夜。模型能力的竞赛固然重要，但下一阶段的胜负手，很可能不在模型本身，而在谁能把 Harness 做得更稳、更安全、更高效。
毕竟，天才不缺，缺的是让天才稳定输出的那套系统。
