1.5 Harness 架构深度解析：Claude Code 为什么强？

词元Max2026-04-02 16:44

Harness 架构深度解析：Claude Code 为什么强？

[进阶选读] 本篇深度解析 Claude Code 的底层架构设计。如果你的目标是快速上手用好 Claude Code，可以先跳过，等用顺手之后再回来读。读完之后，你对 CLAUDE.md、Hooks、MCP 的理解会上一个台阶------知道自己在调什么，而不只是知道怎么调。

时效说明：本文内容以 2026 年 3 月为基准。

很多人都问过这样一个问题：Claude Code 最懂工程，究竟强在哪里？

这个问题背后还有另一个问题：同样是调用 Claude 模型，为什么 Claude Code 能做到裸 API 做不到的事？

答案只有一个词：Harness。

先做一个对比实验，感受 Harness 的存在。用裸 API 和 Claude Code 分别执行同一个任务：

bash 复制代码 
# 方式一：裸 API 调用（没有 Harness）
curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role":"user","content":"找出当前目录下所有 TODO 注释并列出文件名和行号"}]
  }'

# 方式二：通过 Claude Code（有 Harness）
claude -p "找出当前目录下所有 TODO 注释并列出文件名和行号" --output-format text

裸 API 的回答 ：它会告诉你"你可以用 grep -rn 'TODO' . 命令来搜索"------因为它没有手脚，只能说。

Claude Code 的回答 ：它会直接执行 Grep 工具搜索 TODO，返回完整的文件名、行号和上下文------因为 Harness 给了它行动的能力。

同一个大脑，有没有 Harness，结果天壤之别。

同一个模型，有无 Harness 的能力差距------左侧只能说，右侧能干活

8.1 Harness 是什么

Anthropic 官方文档给出了这样的定义：

Claude Code serves as the agentic harness around Claude: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.

（Claude Code 是包裹在 Claude 模型外面的智能体编排框架，提供工具、上下文管理和执行环境，把一个语言模型变成有能力的编码 Agent。）

注意这个定义里的三个关键词：工具、上下文管理、执行环境。

模型本身只会生成文本。是 Harness 给了它读文件的能力、写代码的能力、搜索代码库的能力、在终端执行命令的能力。没有 Harness，Claude 就是一个只会说话的大脑------有智力，没有手脚。

业界对 Harness 的核心共识是：

Agent Harness = 包裹 LLM 的运行时基础设施，管理工具调度、上下文工程、安全执行、状态持久化和会话连续性。LLM 只负责推理决策。

2026 年的关键洞察：竞争差异化的重心已从 Model 转移到 Harness。同一个模型在不同 Harness 中的表现差距，远大于不同模型在同一个 Harness 中的差距。

8.2 Harness 的五个组件

Agent = Model + Harness。

模型是核心，但它不能独立行动。真正让它变成 Agent 的，是包裹在它周围的五个 Harness 组件。

复制代码 
┌─────────────────────────────────────────────────────┐
│                      Harness                        │
│                                                     │
│   ┌─────────┐    ┌──────────┐    ┌───────────┐     │
│   │  Tools  │    │ Context  │    │  Memory   │     │
│   │ (手脚)  │    │ (记忆    │    │ (长期存储)│     │
│   │         │    │  加载器) │    │           │     │
│   └────┬────┘    └────┬─────┘    └─────┬─────┘     │
│        │              │                │            │
│        └──────────────┼────────────────┘            │
│                       │                             │
│              ┌────────▼────────┐                    │
│              │      Model      │                    │
│              │   (推理决策)    │                    │
│              └────────┬────────┘                    │
│                       │                             │
│        ┌──────────────┼────────────────┐            │
│        │              │                │            │
│   ┌────▼────┐    ┌────▼─────┐          │            │
│   │  Hooks  │    │Permissions│         │            │
│   │ (神经   │    │ (安全    │          │            │
│   │  反射)  │    │  围栏)   │          │            │
│   └─────────┘    └──────────┘          │            │
└─────────────────────────────────────────────────────┘

模型不直接接触外部世界，所有交互都通过 Harness 的组件中转。Harness 是模型和现实之间的唯一接口。

Harness 整体架构------Model 居中，五个组件（Tools/Context/Memory/Hooks/Permissions）环绕，共同构成完整的 Agent 运行环境

8.2.1 Tools：模型的手脚

Read、Write、Edit、Bash、Grep......这些工具赋予模型与文件系统、终端、网络交互的能力。没有工具，模型只能说，不能做。

Claude Code 内置了 20+ 个工具，覆盖软件工程的五个原子操作：

原子操作 代表工具 能做什么
读 Read、Glob、Grep 读文件、搜索内容、匹配路径
写 Write、Edit、NotebookEdit 创建/修改文件
执行 Bash 运行任何 Shell 命令
联网 WebFetch、WebSearch 查资料、抓页面
编排 Task 启动子 Agent 并行工作

工具设计背后有一个深刻的哲学------少而精。Claude Code 没有内置重构工具、测试工具、部署工具，它只给了最基础的原语。重构是 Read + Edit + Bash 的组合涌现；测试是 Bash + Read 的组合涌现；部署还是 Bash。

这就像计算机只需要几条指令就能图灵完备一样。Harness 不需要为每种场景造一个工具，它只需要确保基础工具的组合空间足够大。

Bash 是个例外。Bash 工具是一个图灵完备的逃逸舱------通过它，Claude 可以执行任何 Shell 命令：安装依赖、运行测试、调用 API、操作数据库。这意味着 Claude Code 的能力上限，理论上等于操作系统的能力上限。这也是为什么 Harness 需要权限控制的原因。

8.2.2 Context：模型的记忆加载器

CLAUDE.md、系统提示词、对话历史、工具定义------这些上下文在每一轮循环中被注入模型，决定了模型看到什么、知道什么。

上下文管理的精妙之处是，它不只是被动的信息传递，还包括主动的压缩和重注入策略（详见 8.4 节）。

8.2.3 Memory：模型的长期存储

跨会话的记忆持久化，让模型能"记住"你的偏好、项目规则和历史决策。

  • CLAUDE.md：显式记忆，你主动写进去的规则和背景
  • ~/.claude/memory/：隐式记忆，Claude 自动积累的项目知识

没有 Memory，每次对话都从零开始。有了 Memory，Claude 知道你的项目用什么框架、代码风格是什么、有哪些约定不能违反。

8.2.4 Hooks：模型的神经反射

事件驱动的自动化机制，在工具执行前后触发自定义逻辑。比如：

  • 每次保存文件前自动格式化
  • 每次提交前自动运行 lint
  • 每次 Bash 命令执行后自动记录日志

Hooks 让 Harness 有了"条件反射"的能力------不需要模型主动决策，某些行为会自动发生。

8.2.5 Permissions：模型的安全围栏

哪些工具可以自由使用，哪些需要人工审批，哪些完全禁止------权限系统是 Harness 的安全底线。

它解决了一个核心矛盾：你希望 Agent 足够自主以提高效率，但又不希望它自主到失控。

8.3 Agentic Loop：Harness 的心脏

如果 Harness 是一台机器，Agentic Loop 就是它的发动机。整个 Claude Code 的运转，归根到底就是一个循环：

复制代码 
① 用户输入任务
        │
        ▼
② 模型推理：该做什么？需要哪个工具？
        │
        ▼
③ 执行工具（读文件/写代码/运行命令）
        │
        ▼
④ 工具结果回注到上下文
        │
        ▼
⑤ 模型继续推理：任务完成了吗？
        │
    ┌───┴───┐
  完成     未完成
    │         │
    ▼         └──→ 回到 ②
⑥ 输出最终回复

关键点在于步骤 ② 和步骤 ④ 之间的循环。模型不是一次性给出最终答案的。它可能先读一个文件，看完结果后决定再搜索一下，搜索完又决定编辑某行代码，编辑完再运行测试------每一步都是一次循环。一个复杂任务可能跑几十轮循环。

Agentic Loop 完整流程------从用户输入到任务完成，中间经历"推理→工具执行→结果回注"的多次循环

循环什么时候结束？ 满足下面两个条件之一：

  1. 模型主动停止 ：Claude 认为任务完成，生成纯文本回复，不再请求工具调用。API 返回 stop_reason: "end_turn"。
  2. 达到最大轮次 ：Harness 设置了 --max-turns 限制，防止无限循环。

这就是为什么有时候 Claude 花了 20 秒还没给你回答------它在认真跑循环，不是卡住了。

8.4 上下文管理：被低估的关键能力

大多数人讨论 Agent 框架时，只关心工具和循环。但 Harness 最精巧的部分，其实是上下文管理。

Claude 的上下文窗口是有限的（200K tokens）。一个真实的编码任务------读 20 个文件、搜索 50 次、执行 30 条命令------产生的对话历史会迅速膨胀到几十万 tokens。如果不管理，要么爆掉上下文窗口，要么模型开始"遗忘"早期信息。

Claude Code 的解决方案是自动压缩。当对话历史接近上下文窗口的 92% 时，Harness 会触发一次压缩操作：

复制代码 
对话历史（180K tokens）
        │
        ▼ 压缩触发（92% 阈值）
┌────────────────────────────────┐
│ 保留：最近的消息（完整）         │
│ 压缩：早期消息 → 摘要           │
│ 重注入：CLAUDE.md 内容          │
│ 重注入：系统提示词               │
│ 重注入：工具定义                 │
└────────────────────────────────┘
        │
        ▼
压缩后对话历史（~80K tokens）
        │
        ▼
继续工作

注意最后三行------CLAUDE.md、系统提示词、工具定义在每次压缩后都会重新注入。这意味着即使对话历史被截断了，模型仍然知道项目的规则、自己有哪些工具、应该遵循什么约定。

这就是为什么你在 CLAUDE.md 里写的东西那么"持久"------不是因为模型记住了它，而是 Harness 在每次压缩后都重新塞给模型。

理解了这个机制，你就知道 CLAUDE.md 应该写什么：不是写"你好，我叫张三"这类一次性信息，而是写每次压缩后都需要重新提醒模型的项目规则和约定。

8.5 开源还是闭源？一个被误解的事实

很多人以为 Claude Code 是开源的。毕竟它在 GitHub 上有一个仓库（github.com/anthropics/claude-code），截至 2026 年 3 月已有 81K+ stars。

但打开仓库的 LICENSE 文件，你会看到：

复制代码 
© Anthropic PBC. All rights reserved.
Use is subject to Anthropic's Commercial Terms of Service.

Claude Code 不是开源软件，它是专有软件。

GitHub 仓库里有什么？安装脚本、插件模板、GitHub Action、文档、示例配置。核心的 Agentic Loop、工具执行引擎、上下文管理器------这些 Harness 的核心代码------以编译后的 npm 包（@anthropic-ai/claude-code）分发，源码并不可见。

2026 年 1 月，GitHub 上出现了一个 issue（#22002），请求 Anthropic 将 Claude Code CLI 以 Apache 2.0 或 MIT 许可证开源。截至目前，这个 issue 仍然是 Open 状态。

8.6 Claude Agent SDK：可编程的 Harness

虽然 Claude Code CLI 本身不开源，但 Anthropic 在 2025 年发布了 Claude Agent SDK------一套可编程的 Harness 接口。

bash 复制代码 
# TypeScript 版本
npm install @anthropic-ai/claude-agent-sdk

# Python 版本
pip install claude-agent-sdk

Agent SDK 提供了与 Claude Code 完全相同的 Agentic Loop、内置工具、上下文管理、权限系统、Hooks、Sub-Agent 支持和 MCP 集成。区别在于：Claude Code 是面向终端用户的交互式产品，Agent SDK 是面向开发者的编程库。

用 Agent SDK，你可以构建自己的 Harness------一个定制化的 Agent 应用，嵌入到你自己的产品、工作流或 CI/CD 系统中：

python 复制代码 
from claude_agent_sdk import AgentClient

client = AgentClient(api_key="...")

# 创建一个有工具能力的 Agent
result = client.run(
    prompt="审查这个 PR 的安全问题",
    tools=["Read", "Grep", "Glob", "Bash"],
    max_turns=20,
    allowed_tools={"Bash": ["npm test", "npm run lint"]}  # 只允许特定命令
)

print(result.text)

如果说 Claude Code 是一辆出厂配置的整车，Agent SDK 就是发动机总成------你可以把它装进任何车身里。

8.7 Harness 生态：竞争与张力

Claude Code 的成功证明了一件事：模型 + Harness = 10× 生产力。这个公式吸引了大量第三方工具来构建自己的 Harness。

截至 2026 年 3 月，主要 Harness 产品格局：

产品 定位 特点
Claude Code 官方 CLI 深度集成 Claude，Harness 最完整
OpenCode（前 SST） 第三方，多平台 Client-Server 架构，119K stars，月活 65 万+
Cursor IDE 集成 编辑器原生体验，支持多模型
Windsurf IDE 集成 Codeium 出品，强调 Flow 模式
Codex CLI OpenAI 官方 对标 Claude Code，2026 年发布

OpenCode 的故事值得一说。它用 Client-Server 架构解决了 Claude Code 的"单表面"局限------TUI、桌面 App、IDE 插件、Slack 机器人共享同一个后端。截至 2026 年 3 月，OpenCode 的 GitHub star 数超过了 Claude Code 本身。

但 2026 年 1 月，Anthropic 采取了一个争议性举措：封堵了第三方工具通过消费者 OAuth Token 调用 Claude API 的通道。这直接影响了 OpenCode、Cursor、Windsurf 等工具的用户------他们之前可以用 Claude Pro 订阅的 Token 在这些第三方工具里使用 Claude，封堵后必须购买独立的 API Key。

这件事揭示了 Harness 生态的核心张力：

  • 模型提供商希望控制 Harness 层，因为 Harness 决定了 API 调用量和用户体验
  • 第三方 Harness希望模型层是可替换的商品，因为这样它们才能建立独立的价值

这个张力不会消失，它会持续塑造整个 AI 工具生态的格局。

8.8 为什么 2026 年是 Harness 之年

2025 年的关键词是 Agent。2026 年的关键词是 Agent Harness。

为什么？因为行业已经意识到：模型本身正在商品化------Claude、GPT、Gemini、DeepSeek 的能力差距在缩小。但同一个模型在不同 Harness 中的表现差距，远大于不同模型在同一个 Harness 中的差距。

几个佐证数据点：

  • Claude Code 在 2025 年 11 月达到 10 亿美元年化收入------这是一个 Harness 产品的收入，不是模型本身的收入
  • Anthropic 在 2026 年 3 月收购了 Bun（JavaScript 运行时），明确表示要加强 Claude Code 的基础设施。收购一个运行时来加强一个 Harness------这说明 Anthropic 把 Harness 视为战略级资产
  • 开源社区出现了"Agent Harness"作为独立品类，GitHub 上以 "harness" 为关键词的新仓库数量在 2026 年 Q1 翻了三倍

对我们开发者来说，这意味着什么？

理解 Harness 比理解模型更重要。

模型的能力由 Anthropic/OpenAI 决定，你无法改变。但 Harness 的配置------CLAUDE.md 怎么写、工具权限怎么设、Hooks 怎么接、MCP 怎么连------这些全在你手中。你在这门课里学的每一讲，本质上都是在调教 Harness。

8.9 小结

核心要点 一句话总结
Harness 是什么 包裹 LLM 的运行时基础设施，把模型的智力转化为行动力
五个组件 Tools（手脚）、Context（记忆加载器）、Memory（长期存储）、Hooks（神经反射）、Permissions（安全围栏）
Agentic Loop 推理 → 工具调用 → 结果回注 → 继续推理，复杂行为从循环中涌现
上下文压缩 92% 阈值触发压缩，CLAUDE.md 在每次压缩后重新注入------这就是它"持久"的原因
开源误解 Claude Code 核心代码闭源，GitHub 仓库只有脚本和文档
Agent SDK 可编程的 Harness 接口，用于构建定制化 Agent 应用
Harness > Model 同一模型在不同 Harness 中的差距，大于不同模型在同一 Harness 中的差距

思考题

  1. 如果你要为自己的团队构建一个定制化的 Harness（比如专门用于数据分析），你会保留 Claude Code 的哪些内置工具，去掉哪些，新增哪些？为什么？

  2. Claude Code 的上下文压缩策略是"摘要早期消息 + 重注入 CLAUDE.md"。你能想到这种策略的局限性吗？在什么场景下会出问题？

  3. 从商业角度看，Anthropic 选择"开放 Agent SDK、封闭 Claude Code CLI"的策略是否合理？如果你是 Anthropic 的竞争对手，你会怎么应对？

参考资料

以下是 Harness 主题下，质量最高的一手资料：

AI 实验室官方文档

学术论文

行业高影响力文章

相关推荐
yy55272 小时前
Mysql 主从复制与读写分离
android·数据库·mysql
Batac_蝠猫2 小时前
Claude Code 源码架构与模块功能详解
架构·claude·源码泄露
AI创界者2 小时前
基于 C++ 架构的高性能远程管理技术探究（附 V7.4 优化解析）
人工智能·架构
GOWIN革文品牌咨询2 小时前
B2B品牌升级路径判断：架构型、结构型、表达型三类问题怎么分
架构·工业软件·b2b品牌设计·b2b全案策划
mrchen2463 小时前
XAI工程实现可能
架构
zhenxin01223 小时前
万字详解 MySQL MGR 高可用集群搭建
android·mysql·adb
做萤石二次开发的哈哈3 小时前
萤石云硬件接入如何完成云对讲套件低代码集成？
android·低代码·rxjava
EDPJ4 小时前
从 Grounding DINO 到 DINO-X：开放集目标检测的架构演进与细节拆解
目标检测·计算机视觉·架构·图像分割·图像分类
恋猫de小郭5 小时前
2026 AI 时代下，Flutter 和 Dart 的机遇和未来发展，AI 一体化
android·前端·flutter
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）04Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services05UV安装并设置国内源06让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南07AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南08如何解决 OpenClaw “Pairing required” 报错：两种官方解决方案详解09深扒 Claude Code Buddy 模式：一只仙人掌背后的确定性随机算法10OpenClaw Exec Approvals 机制：在安全与效率之间寻找平衡