在2026年那个充满意外的春天一次npm发布包的配置失误，让Anthropic精心构建的Claude Code——这个命令行编码领域的顶尖Agent——意外地揭开了它的面纱。超过51万行未混淆的TypeScript代码，如同一个巨大的宝库，展现在了开发者面前。这不仅仅是一次代码泄露，geng是一次对工业级AI Agent系统架构的公开课。

当我们深入剖析这庞大的代码库时一个名为“Harness”的架构概念浮出水面。它不是简单的模型调用，而是一套精密的工程体系，旨可靠、安全且高效地行动？

今天我们就来拆解这个Claude Code Harness Agent架构，kankan它是如何通过系统化的设计，将一个聊天机器人进化为一个强大的“数字劳动力”的。

一、 核心哲学：Agent的本质是什么？

在深入代码细节之前，我们必须先回答一个“达芬奇之问”。hen多人误以为Agent就是geng聪明的模型，或者只是挂载了几个API接口的Chatbot。但Claude Code的源码告诉我们，Agent的公式远比这复杂：

Agent = 模型 + 循环 + 工具 + 判断

模型只是大脑，它负责思考和推理。但要成为Agent，它还需要一个循环来持续地与环境交互；需要工具来改变世界；geng需要判断力来决定何时该停、何时该继续、何时该请求许可。Claude Code的Harness架构，正是为了支撑这四个要素而生的。它定义了方向，让多个Agent协同推进，让多个项目并行展开，整个过程持续演化；你Ke以随时介入、修正、回滚，让研究形成真正的闭环。

二、 宏观架构：金字塔式的分层管理

从宏观视角来kan，Claude Code的架构呈现出一种清晰的分层结构，就像金字塔一样，每一层dou有其独特的职责。

Zui顶层是用户交互层，无论是REPL、CLI命令行、SDK调用，还是IDE/Web端的Bridge，它们dou只是入口。真正的核心在于中间的Agent Loop。

在这个循环层中，我们Ke以kan到几个关键的子系统在协同工作：

Context Mgmt这是Agent的记忆中枢，负责compact、snip、collapse等操作，确保模型不会因为记忆过载而“失忆”。

API Call + Stream负责与Claude的大脑进行流式通信，支持重试机制。

Tool Execution这是Agent的手脚，支持并行或串行执行，通过StreamingToolExecutor实现边说边Zuo。

Permission Gate这是安全卫士，通过Rules、Hooks、Classifier和用户确认，构建起多层次的防御体系。

Hooks System这是可 性的骨架，允许在PreToolUse、PostToolUse、SessionStart等关键节点插入自定义逻辑。

Zui底层则是外部系统，包括文件系统、Shell进程、MCP服务器、LSP服务器以及Git/GitHub等。这种分层设计使得系统各司其职，既保证了核心逻辑的纯粹性，又提供了极强的 Neng力。

三、 Agent Loop：循环的艺术与流式控制

Ru果说Harness是骨架，那么Agent Loop就是心脏。源码中的`src/query.ts`文件就是这颗心脏的起搏器。

这里有一个非常有趣的设计选择：为什么Claude Code使用Async Generator而不是简单的`while`循环？

这不仅仅是一个工程技巧，geng是一个哲学问题的工程解。Agent Loop同时是生产者和消费者。Async Generator的`yield`语义天然支持这种双向数据流。它允许调用方实时接收每一个token、每一个工具的进度geng新，而不必傻傻地等待整个Turn结束。这种实时性对于用户体验至关重要。

1. 状态机的流转

Agent Loop本质上是一个有限状态机在无限可Neng性空间中的导航器。每一轮迭代，状态dou会被整体替换而非局部修改，这保证了每轮开始时状态的一致性。

一个典型的Turn N流程是这样的：

上下文管理 检查预算，应用`applyToolResultBudget`，然后通过`snipCompact`裁剪Zui旧的消息，或者进行`microcompact`。Ru果还不够，就触发`contextCollapse`甚至`autoCompact`。

API调用将消息标准化后通过`callModel`发起流式请求。这里使用了`withRetry`机制，包含指数退避策略。在流式传输过程中，系统会一边yield消息给UI，一边通过`StreamingToolExecutor.addTool`准备执行工具。

错误恢复Ru果API报错，系统不会直接崩溃。Ru果是“Prompt Too Long”，它会尝试上下文压缩；Ru果是“Max Output Tokens”，它会尝试升级到64k上下文；Ru果是“Media Size Error”，它会剥离图片重试。

工具执行获取流式期间Yi启动的工具结果，或者直接运行`runTools`。这里会处理所有的Stop Hooks。

决策Zui后系统判断是否需要继续。Ru果`needsFollowUp`且未达到Zui大轮次状态geng新，循环继续；否则，返回Terminal状态。

2. 流式工具执行：核心创新

这里有一个极具前瞻性的设计：为什么不等模型说完再执行工具？

传统的Zuo法是模型生成完所有Tool Use Block后再统一执行。但这浪费了宝贵的时间。模型输出可Neng需要几秒钟，而读取文件可Neng只需要50毫秒。Claude Code的答案是：流式工具执行让工具与模型输出并行。

在模型还在输出下一个tool_use block的时候，前一个工具可NengYi经完成了。`StreamingToolExecutor`类负责核心的并发控制。它会维护一个队列，一旦有工具进入且满足并发条件，就立即尝试执行。这种设计极大地提升了Agent的响应速度。

四、 工具系统：声明与执行的二元性

在Claude Code中，工具不仅仅是函数，它们是“一等公民”。源码中的`src/Tool.ts`定义了这一核心接口。

工具具有一种有趣的二元性：它们既是声明，又是执行。这种二元性决定了工具系统必须同时关注模型可见性和运行时安全性。

每个工具dou包含四个维度的信息： 1. 声明侧`name`、`description`、`inputSchema`，这是给模型kan的。 2. 执行侧`call`方法、`validateInput`、`checkPermissions`，这是运行时调用的。 3. 元数据侧`isConcurrencySafe`、`isReadOnly`、`isDestructive`，这是系统决策用的。 4. 渲染侧`renderToolResultMessage`，这是给UI展示用的。

工具的执行管线也是相当严谨的：查找工具 -> 输入验证 -> 输入回填 -> Pre-Hooks -> 权限检查 -> 执行 -> 结果映射 -> 结果持久化 -> Post-Hooks。

五、 权限系统：安全与便利的平衡术

如何让一个拥有Shell执行权限的AI既强大又安全？Claude Code给出的答案是分层判决。

安全和便利往往是对立的。Ru果太安全，每次操作dou要弹窗确认，用户体验极差；Ru果太便利，Agent可Neng会误删数据库。Claude Code通过一个多层的权限管线解决了这个问题：

工具级禁止 检查是否有全局的Deny规则。

Pre-Hook决策运行预置的Hook，HookKe以直接返回Allow/Deny/Ask，甚至修改输入。

规则匹配检查用户配置的Allow/Deny/Ask规则，支持通配符匹配。

工具自检每个工具内部有自己的自定义权限逻辑。

自动模式分类器对于Bash工具，有一个小模型专门用来打分，判断操作是Safe、Risky还是Dangerous。

用户交互Zui后才是弹出对话框，让用户选择允许、拒绝或始终允许。

这种渐进式信任模型意味着，hen多低风险操作Ke以在前几层就被自动放行，只有真正不确定的操作才会打扰用户。权限规则来源也非常丰富，支持用户设置、项目设置、企业策略甚至命令行参数。

六、 上下文管理：记忆的经济学

上下文窗口是AIZui昂贵的资源。当对话越来越长，历史消息填满了窗口怎么办？Claude Code的设计哲学是：不是“丢掉什么”，而是“保留什么Zui有价值”。

为此，它设计了一套五级压缩体系，像计算机的存储层次结构一样，逐级升级成本：

Level 1: 工具结果预算。限制每条消息的工具结果总字节数。超出部分持久化到磁盘，只返回预览和文件引用。成本几乎为零。

Level 2: Snip Compact。从Zui旧的消息开始移除，保留系统消息和Zui近N轮。成本是丢失早期上下文。

Level 3: Microcompact。这是Anthropic直连API的特有福利。使用特殊的Prompt策略，清除旧工具调用的输入输出，只保留Zui近的。这由API侧处理，无额外推理开销。

Level 4: Context Collapse。分阶段折叠粒度较高的上下文，保留结构化信息，移除细节。需要中等推理开销。

Level 5: Auto Compact。终极手段。使用模型生成完整摘要，Zui大输出预算50K tokens。这会消耗一次完整的API调用，成本Zui高。

这种精细化的管理，确保了Agent在长时间运行中依然保持清醒，不会因为“老年痴呆”而无法工作。

七、 错误恢复与重试：韧性的工程

在分布式系统中，失败是常态。Claude Code的设计哲学是永远不在可恢复的错误上崩溃。

源码中的`withRetry.ts`展示了强大的韧性。它实现了指数退避策略，并加入了随机抖动防止惊群效应。针对不同的错误类型，有不同的恢复路径：

对于401/403错误，它会刷新凭据重试。

对于ECONNRESET/EPIPE，它会禁用keep-alive重试。

对于429错误，它会尊重Retry-After头。

对于Max Output Tokens错误，它会尝试调整token限制重试。

甚至在极端情况下系统还支持“快速模式降级”或“模型降级”。这种对失败的包容，是工业级系统与玩具级脚本的分水岭。

八、 Hooks System：可 性的骨架

如何让系统在不修改核心代码的情况下改变行为？Claude Code引入了Hooks系统。这不仅是事件监听，geng是控制流的改变点。

Hook支持多种类型： * Command Hook执行外部命令。 * Prompt Hook调用LLM进行判断。 * HTTP Hook请求外部API服务。 * Agent Hook启动子代理进行验证。

在PreToolUse阶段，Hook的退出码决定了工具的命运：0表示通过隐藏执行，2表示阻塞并显示输出，其他非零错误则记录日志但继续。这种机制让用户Ke以在配置文件中编写复杂的逻辑，比如“在执行`git push`之前，必须先通过`npm test`的Hook检查”，完全无需修改Claude Code的源码。

九、 MCP集成与子代理：无限的可Neng

Claude Code并没有试图把所有工具dou内置，因为它知道世界上的工具是无限的。它选择了拥抱MCP。通过MCP，Claude CodeKe以连接任何符合协议的工具服务器，无论是GitHub、Jira还是公司内部系统。工具名称采用三段式命名，完美解决了命名冲突问题。

而当一个Agent不够用时Claude Code支持Subagent系统。主AgentKe以派生出子Agent，子AgentKe以是Forked、Fresh或Worktree模式。这种分治法的智慧，让复杂任务Ke以被拆解、并行处理。

十、 ：构建Harness Agent的Zui佳实践

通过对这51万行代码的梳理，我们Ke以提炼出构建顶级Agent的路线图：

从Zui小可行Agent开始，实现基本的Loop和工具；然后加入流式执行和并发控制以提升性Neng；接着引入权限规则和上下文压缩以保证生产级稳定性；Zui后通过Hooks、MCP和子代理系统实现企业级的可 性。

Claude Code的Harness架构不仅仅是一套代码，它是一套经过实战检验的设计模式。它告诉我们，AI的未来不在于模型参数的无限堆砌，而在于如何用精妙的工程架构，将模型的智Neng转化为可靠的生产力。这或许就是这次源码泄露事件带给我们Zui大的价值。

---