跳转至

claude code harness deep understanding

Ch01.367 claude code harness deep understanding

📊 Level ⭐⭐ | 9.7KB | entities/claude-code-harness-deep-understanding.md

深入理解 Claude Code 源码中的 Agent Harness 构建之道

上周， ** Anthropic ** 旗下闭源的 AI 编程工具 Claude Code 曝出源码泄露事件。这次事件并非黑客入侵或内部泄密，而是因 npm 打包未排除包含完整源码的 .map 映射文件， ** 导致 1900 余个 Typescript 文件、超 51 万行核心代码意外曝光 ** 。相关代码迅速被归档至 Github，数小时内收获超 1100 颗星。 这是迄今为止生产级 AI Agent 系统最完整的一次公开审视，也让外界得以验证此前对 Claude Code 架构的推断，同时窥见其诸多未发布的核心功能与底层设计逻辑。 本文将借助这次源代码泄露机会，顺着一个请求的完整生命周期：从你输入消息到 Agent 交付可工作的代码，我们一步步拆解每个环节。你会发现， ** LLM 调用本身只是一行代码 ** ，真正让 Agent 可用的，是围绕这行代码精心设计的 ** Agent Harness ** 。

Agent Harness 的核心循环

相关实体

→ 原文存档

深度分析

1. Agent Harness 的本质：围绕 LLM调用的工程化包装

Claude Code 源码揭示了一个核心事实：LLM 调用本身只是一行代码，真正让 Agent 可用的，是围绕这行代码精心设计的 ** Agent Harness **。这个 harness 包含八个核心环节：上下文组装、API 调用与异步生成、响应解析、权限检查、工具执行、结果反馈、上下文管理、终止与错误恢复。

这种设计思路体现了 "模型即服务，框架即产品" 的工程哲学。Anthropic 并不只是提供一个强大的模型，而是构建了一整套让模型能力得以落地的运行环境。

2. 上下文工程：Agent 成败的关键因素

Claude Code 的上下文组装机制极为精密，呈现出 分层缓存 的架构特征：

  • 缓存部分（边界之前）：只算一次，后面每一轮直接复用。包括系统信息、项目结构、编码规范等
  • 非缓存部分（边界之后）：每一轮都会重新计算。如 MCP 服务器相关的指令

通过 SYSTEM_PROMPT_DYNAMIC_BOUNDARY 标记分隔，边界之前的内容可以使用 API 的全局缓存范围（在所有用户之间共享），这是极其精妙的工程优化。

3. 权限控制：分层决策树

Claude Code 的权限系统采用 四层递进式判断，一旦某层做出决定就立即结束：

  1. 拒绝规则 → 直接拦掉
  2. 允许规则 → 直接放行
  3. 分类器 → 异步判断（最多等 2 秒）
  4. 交互提示 → 询问用户

这种设计在用户体验和安全性之间取得了精妙的平衡：日常操作（读文件、搜代码）无感通过，涉及改文件时才触发确认。

4. 工具执行的并发策略

Claude Code 的工具执行并非简单串行，而是采用了 智能分组策略：

  • 只读操作并发执行（默认最多 10 个）
  • 写操作串行执行，避免冲突

每个工具通过 isConcurrencySafe() 标记自己的并发安全性，系统在执行前通过 partitionToolCalls() 将工具分成若干批次。这解释了为什么 Claude Code 在「读代码」阶段会感觉特别快。

5. 上下文压缩的三层策略

面对长对话的上下文膨胀，Claude Code 设计了三层递进式压缩：

  1. 微压缩：保留工具的输入/输出，精简中间的冗长解释
  2. 会话记忆压缩：将整段对话总结成一条精简信息
  3. 反应式压缩：当 prompt_too_long 错误发生时，当场做一次压缩然后重建请求

更值得注意的是，系统加入了 断路器机制：连续失败 3 次后不再尝试自动压缩，防止无限循环和 API 资源浪费。注释显示这一优化每天节省约 25 万次 API 调用。

6. 递归子 Agent 的受控边界

Claude Code 支持子智能体递归调用，但通过 三种隔离模式 保持复杂度可控：

  • 同 CWD：共享工作目录
  • Worktree：独立的 git worktree 副本
  • 后台：异步运行，父 Agent 继续自己的任务

子智能体不能无限制地产生更多子智能体，也不能调用敏感或受限的工具。递归的边界很清楚：子智能体的行为完全在父循环管理之下。

实践启示

启示 1：上下文工程是 Agent 开发的核心战场

Claude Code 的架构证明，在实际应用中，LLM 调用本身往往是最简单的部分，真正的难点在于：

  • 如何组织、缓存、压缩上下文
  • 如何设计有效的系统提示词结构
  • 如何管理长会话的上下文膨胀

对于 Agent 开发者而言，投入大量精力在上下文工程上往往比调优模型参数更有价值。

启示 2：权限系统需要"渐进式信任"

Claude Code 的四层权限判断提供了一个优秀范例：默认放行只读操作，对写操作进行渐进式确认。

这种设计理念可以迁移到其他 Agent 应用中：

  • 对于数据读取类操作，可以默认放行或仅做简单确认
  • 对于数据修改、删除、执行命令等操作，需要更严格的确认机制
  • 分类器可以在后台异步运行，不阻塞用户操作

关键是找到用户体验和安全性之间的平衡点。

启示 3：工具执行应充分利用并发

Claude Code 通过 isConcurrencySafe() 和 partitionToolCalls() 实现了工具执行的智能调度。在实际开发中：

  • 识别哪些工具是只读的，可以安全并发
  • 对于写操作，确保有适当的同步机制
  • 利用异步流式处理提升用户体验

这对于需要同时读取多个文件或调用多个 API 的场景尤为重要。

启示 4：技能系统需要预算控制

Claude Code 的技能系统展示了如何在大上下文窗口中管理大量技能：

  • 所有技能描述加起来最多占上下文的 1%
  • 每个技能描述不超过 250 个字符
  • 超过预算时按优先级自动截断

这提示我们在构建技能/工具注册表时，需要设计相应的预算控制和按需加载机制，而不是一次性把所有信息塞入上下文。

启示 5：错误恢复需要断路器思维

Claude Code 的断路器机制（连续失败 3 次后停止重试）是一个重要的工程教训：在设计 Agent 循环时，必须考虑：

  • 防止无限重试和资源浪费
  • 设置最大重试次数和超时限制
  • 对不同类型的错误采用不同的恢复策略

这一原则同样适用于 API 调用、工具执行、上下文压缩等所有可能失败的环节。

启示 6：Harness 本身是产品的核心价值

Claude Code 的架构揭示了一个重要事实：对于 AI 应用公司而言，真正的护城河往往不在于模型本身，而在于围绕模型构建的 Harness。

这包括：

  • 上下文管理和优化机制
  • 权限控制和安全保障
  • 工具系统的设计和调度
  • 错误恢复和用户体验优化

这些都是需要大量工程投入的部分，也是 Agent 产品的核心价值所在。