一、引言：什么是 Agent Harness

1.1 Harness 的核心定义

在 AI Agent 领域中，"Harness"（缰绳/套具）是一个至关重要的工程概念。它指的是围绕大语言模型构建的、使 Agent 能够在特定领域中有效运作的完整基础设施体系。

正如 shareAI-lab/learn-claude-code 项目所精确定义的：

Claude Code 是 Anthropic 官方推出的命令行编码 Agent 工具，其源代码于 2026 年 3 月 31 日因 npm 发布包中的 source map 文件意外暴露而公开。该仓库共计约 1,900 个文件、512,000+ 行 TypeScript 代码，为我们提供了一个前所未有的深入理解工业级 Agent Harness 架构的机会。

本报告将从 Harness 工程的角度出发，系统性地拆解 Claude Code 的源码架构。核心理念是：

1.2 研究背景与源码来源

Claude Code 的源码并非由 Anthropic 主动开源。研究者 @Fried_rice（Chaofan Shou）发现 Claude Code 在 npm 发布包中暴露了 .map 文件，该文件引用了存储在 Anthropic R2 存储桶中的未混淆 TypeScript 源码，使得完整的 src/ 目录可以被公开下载。

这一事件揭示了软件供应链安全中的一个重要问题：构建产物的泄露（build artifact leak）。从研究角度来看，这份源码快照为我们提供了一个分析现代 AI Agent 系统架构的珍贵标本。

二、整体架构

Claude Code 的架构可以用一个极简公式概括其本质：

这个公式揭示了 Claude Code 作为 Harness 的最核心设计哲学：不试图成为智能体本身，而是为智能体（Claude 模型）提供一个功能完备的操作环境。每一个组件都是一个 Harness 机制——为 Agent 提供手（Tools）、眼（Observation）、记忆（Context/Memory）、协作（Team）和边界（Permissions）。

2.1 目录结构与模块划分

Claude Code 的源码按照功能职责清晰地划分为 30+ 个顶层目录，每个目录对应一个 Harness 子系统：

2.2 关键文件概览

三、核心循环

Claude Code 的 Harness 体系建立在最基础的 Agent Loop 之上。这个循环模式是所有 AI Agent 系统的通用骨架：模型接收消息、决定行动、执行工具、获取结果、再次决策。

3.1 QueryEngine：Harness 的大脑中枢

QueryEngine.ts（约 46K 行）作为 Claude Code 的 LLM 查询引擎，承担了以下关键 Harness 职责：

（1）流式响应处理（Streaming Response）

QueryEngine 负责处理来自 Anthropic API 的流式响应，用户可以实时看到模型生成的内容，而不是等待完整响应返回。这种设计对于终端交互体验至关重要，让用户能够即时感知 Agent 的"思考过程"。流式处理还与终端 UI 组件（React+Ink）紧密集成，实现实时渲染。

（2）工具调用循环（Tool-Call Loop）

这是 Agent Loop 的核心机制。当模型的 stop_reason 为 "tool_use" 时，QueryEngine 会自动执行对应的工具，将结果作为 tool_result 追加到消息列表中，然后再次调用模型。这个循环持续进行，直到模型返回 "end_turn" 或其他非工具使用的停止原因。伪代码如下：

（3）思考模式集成（Extended Thinking）

QueryEngine 支持 Claude 的扩展思考模式，允许模型在执行工具之前进行更深层的推理。这是 Harness 为 Agent 提供的"认知增强"机制，使 Agent 能够在复杂任务中进行更周密的规划。

（4）重试逻辑与 Token 计数

引擎内置了完善的重试机制来应对 API 错误和速率限制，同时精确追踪每次调用的 Token 消耗，支持成本控制（通过 cost-tracker.ts）。

3.2 最小循环模式的 Harness 意义

从 Harness 的视角看，这个循环模式的设计哲学是：循环属于 Agent，机制属于 Harness。Claude Code 的所有其他 Harness 机制——工具系统、技能加载、上下文压缩、子智能体——都是在这个循环之上层层叠加的，而不改变循环本身的结构。

四、工具系统：Agent 的双手

工具系统是 Harness 最核心的组成部分。它定义了 Agent 在环境中能够执行的每一个原子操作。在 Claude Code 中，Tool.ts（约 29K 行）定义了所有工具的基础类型和接口（基于 Zod v4），每个工具模块都是自包含的，定义了自己的输入验证、权限要求和执行逻辑。

4.1 核心工具清单与 Harness 功能映射

4.2 工具设计的 Harness 原则

从上述工具清单可以提炼出 Claude Code 工具系统的三条核心设计原则：

原子性（Atomicity）：每个工具只做一件事，职责单一且明确。例如 FileReadTool 只负责读取文件，FileEditTool 只负责编辑文件，两者不混用。这种设计使得模型的工具选择更加精准，减少了误操作的风险。

可组合性（Composability）：工具之间可以灵活组合。模型可以先使用 GrepTool 搜索代码，再用 FileReadTool 读取匹配文件，然后用 FileEditTool 修改目标位置。每个工具的输出都是下一个工具的自然输入。

自我描述性（Self-Describing）：每个工具都通过 Zod v4 Schema 精确定义了输入输出格式，模型通过工具描述就能理解何时以及如何使用它。此外，ToolSearchTool 实现了"延迟工具发现"（Deferred Tool Discovery），允许 Agent 在运行时动态发现和使用新工具，而不需要在系统提示中预加载所有工具描述，这大大节省了上下文窗口空间。

4.3 命令系统：用户驱动的工具接口

除了 Agent 自动调用的工具外，Claude Code 还提供了约 50 个用户可手动触发的斜杠命令（src/commands/）：

五、知识与技能系统

在 Harness 工程中，"知识"不是预先灌入系统提示的静态信息，而是按需加载的动态资源。Claude Code 的技能系统（src/skills/）完美诠释了这一原则。

5.1 按需知识加载（On-Demand Knowledge Loading）

Claude Code 的技能系统采用了 "需要时才加载，而非预先加载" 的设计哲学。具体实现方式是：

1.技能定义以 .md 文件存储在 skills/ 目录中

2.每个技能文件包含 YAML frontmatter（描述触发条件和简短描述）和详细的知识体

3.当模型判断需要某个技能时，通过 SkillTool 加载对应文件

4.内容通过 tool_result 注入到对话上下文中

这种设计的关键优势在于：避免了上下文窗口的浪费。在一个编码会话中，Agent 可能需要不同领域的知识（前端框架、数据库设计、API 设计等），如果将所有知识都预加载到系统提示中，会快速消耗宝贵的 Token 预算。

5.2 Progressive Disclosure（渐进式披露）

更先进的 Harness 实现进一步发展了 "渐进式披露" 策略。技能内容被分为三个层次：

Agent 首先只看到触发描述，判断是否需要该技能；如果需要，再加载主体内容；如果还需要更深入的信息，才加载引用资料。这种多层次的信息架构最大化了上下文利用效率，是 Harness 工程中"知识管理"子系统的高级实践。

5.3 插件架构

src/plugins/ 实现了插件加载系统，允许内置和第三方插件扩展 Claude Code 的能力。插件可以定义自己的工具、命令和技能，通过标准的注册机制集成到 Harness 中。

六、上下文管理：Agent 的记忆工程

上下文管理是 Harness 工程中最具技术挑战性的环节之一。由于大语言模型的上下文窗口有固定大小限制，Harness 必须在"保留有用信息"和"腾出空间"之间找到平衡。

6.1 三层压缩策略

Claude Code 实现了一套三层上下文压缩策略来应对无限会话的需求：

第一层：子智能体隔离（Subagent Isolation）

通过 AgentTool 生成的子智能体拥有独立的 messages[] 数组，它们的操作历史不会污染主会话的上下文。主会话只接收子智能体返回的最终结果摘要，而非完整的执行过程。这种设计从根本上防止了噪音从子任务泄漏到主对话中。

第二层：上下文压缩（Context Compression）

由 src/services/compact/ 实现，当对话历史接近上下文窗口限制时，系统会自动将早期的对话内容压缩为摘要。压缩过程中保留关键信息（如代码变更、决策理由、用户反馈），丢弃冗余细节。

第三层：任务持久化（Task Persistence）

通过 src/tasks/ 和 src/memdir/ 实现，目标任务被持久化到磁盘文件中。即使单个会话结束，任务状态也可以在下次启动时恢复（通过 /resume 命令）。这种机制将 Agent 的"记忆"从易失的对话上下文扩展到了持久化的文件系统。

6.2 系统提示与上下文收集

context.ts 负责收集和组装发送给模型的系统提示，包括：

• 用户自定义指令（CLAUDE.md 文件）

• 项目级配置

• 环境信息（操作系统类型、可用工具列表）

• 当前工作目录的代码结构摘要

系统提示的构建是动态的——根据当前会话状态和可用资源，每次请求都可能生成略有不同的系统提示，以最大化利用有限的上下文窗口。

七、多智能体协调

当单个 Agent 无法独立完成复杂任务时，Harness 需要提供多智能体协调能力。Claude Code 在 src/coordinator/ 中实现了一套完整的多智能体编排系统。

7.1 子智能体生成与隔离

AgentTool 是实现子智能体生成的核心工具。当主 Agent（Lead Agent）判断需要将子任务委派给独立智能体时，它通过调用 AgentTool 来生成一个全新的子智能体实例。每个子智能体拥有完全独立的执行环境：

• 独立的 messages[] 数组：确保上下文隔离

• 独立的工作目录：通过 Git Worktree 实现文件系统隔离

• 独立的权限边界：子智能体的权限不超出主 Agent 授权范围

子智能体完成后，只将结果摘要返回给主 Agent。主 Agent 甚至不知道子智能体的具体执行过程——它只知道任务完成的结果。

7.2 团队协作与异步通信

Claude Code 进一步提供了 TeamCreateTool、TeamDeleteTool 和 SendMessageTool 来支持更复杂的团队协作模式：

• Teammates：持久化的团队成员智能体实例

• JSONL Mailbox：基于 JSONL 文件的异步邮箱通信机制

• 统一请求-响应模式：包括关闭协商和计划审批等状态机管理

• 自主任务认领：团队成员在空闲时自动扫描任务面板，识别并认领适合自己技能的任务

7.3 六种架构模式

根据对 Claude Code Harness 生态的研究（特别是 RevFactory Harness 插件的分析），Claude Code 的多智能体协调支持以下六种经过验证的架构模式：

7.4 Worktree 隔离：并行执行的安全保障

EnterWorktreeTool 和 ExitWorktreeTool 实现了基于 Git Worktree 的文件系统隔离。每个子智能体或并行任务可以在独立的 Worktree 中工作，修改自己的文件副本而不影响主分支或其他任务。任务完成后通过 Git Merge 将结果合并回主分支。

八、权限系统：Agent 的安全边界

权限控制是 Harness 工程中"安全工程"的核心体现。Claude Code 在 src/hooks/toolPermission/ 中实现了精细化的权限管理系统。

8.1 多级权限模式

8.2 细粒度权限控制

权限系统的实现非常精细。每次工具调用时，toolPermission hook 都会介入检查。系统支持基于以下维度的细粒度规则配置：

• 工具类型：不同工具有不同的默认权限级别

• 操作类型：读取操作通常比写入操作更容易获得批准

• 文件路径模式：可以限制 Agent 只在特定目录下操作

• 命令模式：BashTool 中可以配置允许的命令白名单

此外，Git Worktree 隔离机制提供了文件系统级别的沙箱——每个子智能体在自己的 Worktree 中工作，不会影响主分支的文件。这种多层防护确保了 Agent 在拥有强大操作能力的同时，不会意外造成不可逆的损害。

九、Bridge 系统

Claude Code 最初是一个终端（CLI）工具，但通过 src/bridge/ 实现的桥接系统，它能够无缝嵌入到 IDE 环境中（如 VS Code、JetBrains）。这是一个双向通信层，包含以下核心组件：

从 Harness 的视角看，Bridge 系统的意义在于：它将 Agent 的操作环境从纯终端扩展到了 IDE。用户可以在熟悉的编辑器界面中使用 Claude Code 的全部能力，同时享受 IDE 提供的代码高亮、文件导航、Git 集成等增强功能。

十、性能优化

Claude Code 作为生产级 Harness，在性能优化方面展现了极高的工程水准。

10.1 并行预取启动优化

在应用启动阶段，Claude Code 采用了并行预取策略来最小化启动延迟。main.tsx 在模块评估开始之前，就通过副作用代码并行启动了：

当用户看到命令行提示符时，这些耗时操作已经在后台并行完成了。

10.2 懒加载与死代码消除

重量级模块（如 OpenTelemetry、gRPC、分析服务和部分特性门控子系统）通过动态 import() 延迟加载。更关键的是，Claude Code 利用 Bun 运行时的 bun:bundle 特性标志实现了编译时死代码消除：

主要特性标志包括：

10.3 技术栈分析

十一、Harness 工程的核心洞察

11.1 模型即智能体，代码即缰绳

Claude Code 的架构最深刻的教训在于：

Claude Code 不试图通过复杂的规则引擎、决策树或工作流编排来模拟智能——它完全信任 Claude 模型的决策能力，将全部工程精力投入到为模型提供一个清晰、丰富、安全的工作环境中。

正如 learn-claude-code 项目所总结的：

11.2 Harness 工程师的五大职责

基于 Claude Code 的源码分析，Harness 工程师的核心职责可以归纳为以下五个维度：

(1) 实现工具（Implement Tools） — 给 Agent 双手

• 工具的原子性、可组合性和自我描述性直接决定了 Agent 的操作精度

• 每个工具都应该像一个精心设计的 API——输入明确、输出可预测、错误可处理

(2) 策划知识（Curate Knowledge） — 给 Agent 专业知识

• 按需加载、渐进式披露的策略确保了知识的高效利用

• 领域文档、架构决策记录、编码规范等知识资源的组织和触发条件设计是 Harness 质量的关键

(3) 管理上下文（Manage Context） — 给 Agent 清洁记忆

• 子智能体隔离、上下文压缩、任务持久化三层策略共同确保 Agent 在长时间会话中保持高效

• "Context will fill up; you need a way to make room"

(4) 控制权限（Control Permissions） — 给 Agent 安全边界

• 多级权限模式、细粒度规则配置和 Worktree 文件系统隔离构成了多层次安全防护

• 这是 Harness 工程中安全工程的核心

(5) 收集训练信号（Collect Task-Process Data） — 改进下一代 Agent

• 每一次 Agent 在 Harness 中执行的感知-推理-行动序列都是宝贵的训练信号

• Harness 不仅服务于当前的 Agent，还可以帮助改进下一代 Agent 模型

11.3 通用化启示

Claude Code 作为编码 Agent Harness 的设计模式具有广泛的通用性。同样的 Harness 架构原则可以应用于任何需要 AI Agent 操作的领域：

核心循环始终相同：模型接收消息、决定行动、执行工具、获取结果、再次决策。改变的只是工具、知识和权限——这些正是 Harness 工程师的工作范畴。

通过对 Claude Code 源码快照的 Harness 视角深度解读，我们发现 Claude Code 是一个经过精心设计的、工业级的 Agent Harness 系统。其核心架构可以用一句话概括：

从工具系统（40+ 个原子工具、分层行动-感知体系）到知识管理（按需加载、渐进式披露），从上下文工程（三层压缩策略）到多智能体协调（六种架构模式、异步邮箱通信），从权限治理（多级模式、细粒度控制）到性能优化（并行预取、懒加载、死代码消除），Claude Code 在每一个 Harness 子系统上都展现了成熟的工程决策和优雅的实现方式。

Claude Code 给我们的最重要启示是：