Harness（执行引擎/运行时框架）是 AI 应用中最核心但最容易被忽略的底层架构——它是连接大语言模型（LLM）、工具调用（Tool Calling）、模型上下文协议（MCP）和智能体（Agent）之间的"操作系统"，负责协调、调度和执行所有组件的交互。

本教程将深入讲解 Harness 的概念、架构、工作原理和实际应用场景，帮助你理解 AI 系统"幕后"的运行机制。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

1. 什么是 Harness

1.1 概念定义

Harness（直译"马具/挽具"，在软件工程中译为"执行引擎"或"运行时框架"）是指一套完整的执行环境，它负责管理 AI 模型与外部世界之间的所有交互——接收输入、调用工具、编排流程、整合结果并生成最终输出。

借用 Anthropic 官方文档中的表述：

Harness is the orchestration layer that manages the lifecycle of AI interactions, tool execution, and agent behaviors. It handles the flow of information between the LLM, tools, and external services.

翻译过来就是：Harness 是管理 AI 交互、工具执行和智能体行为全生命周期的编排层，负责处理 LLM、工具和外部服务之间的信息流。

1.2 直观理解 Harness 在系统中的位置

最简化的 LLM 调用流程：

graph LR A[用户输入] --> B[LLM] B --> C[文本输出] style A fill:#ebdef0,stroke:#7d3c98,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

加上 Tool Calling 后：

graph LR A[用户输入] --> B[LLM] B -->|生成指令| C[工具调用指令] C --> D[应用程序
执行工具] D --> E[返回结果] E --> B B --> F[最终输出] style A fill:#ebdef0,stroke:#7d3c98,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style D fill:#fadbd8,stroke:#c0392b,stroke-width:2px style E fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

而有了 Harness 之后：

graph LR subgraph Harness[Harness 执行引擎] direction TB L1[输入解析层] L2[意图路由层] L3[工具调度层] L4[结果整合层] L5[权限与安全层] end A[用户输入] --> Harness Harness --> B[LLM] Harness --> C[Tool Calling] Harness --> D[MCP] Harness --> E[Agent] B --> H[最终输出] C --> H D --> H E --> H style Harness fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B fill:#ffecd6,stroke:#d35400,stroke-width:2px style C fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style D fill:#fadbd8,stroke:#c0392b,stroke-width:2px style E fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px

如果把 AI 应用比作一台计算机，那么 LLM 是 CPU，Prompt 是指令，Tool Calling 是 IO 接口，MCP 是硬件协议标准——而 Harness 就是操作系统，统一管理所有组件的协调运行。

1.3 为什么需要 Harness

现代 AI 应用的需求已超越了"一问一答"的简单模式：

需求 简单模式 需要 Harness 的原因
多工具调度 LLM 一次只调用一个工具 Harness 管理多工具的注册、发现、调用和结果路由
权限控制 用户自行判断是否执行 Harness 内置审批机制，可配置自动/手动批准
流程编排 每次交互都是孤立的 Harness 支持多步骤工作流，步骤间共享上下文
错误处理 工具调用失败直接报错 Harness 实现重试、降级、超时等容错机制
并行执行 串行执行所有操作 Harness 支持并发工具调用、并行 Agent 执行
状态管理 每次调用无状态 Harness 维护会话上下文、缓存中间结果

没有 Harness，开发一个涉及多工具、多步骤的 AI 应用，你需要手动处理上述所有问题——这正是 Harness 存在的价值。

2. Harness 的核心架构

Harness 并非单一块的代码，它由多个协作的子系统组成。以下是从逻辑角度拆解的 Harness 典型架构：

2.1 架构总览

Harness 架构分为四大层级，自上而下逐层依赖：

graph TD subgraph IO[输入/输出层
━━━━━━━━━━━━] IO1[用户输入
接收用户的原始输入信息] IO2[系统消息
注入系统级提示和配置指令] IO3[上下文管理
维护对话历史、窗口管理和上下文压缩] end subgraph ORCH[编排调度层
━━━━━━━━━━━━] ORCH1[意图分析
分析用户输入的意图和目标] ORCH2[路由决策
决定将请求分发到哪个处理模块或工具] ORCH3[流程编排
编排多步骤工作流，协调各模块协作顺序] ORCH4[响应生成
根据执行结果生成最终回复] end subgraph TOOL[工具管理层
━━━━━━━━━━━━] TOOL1[工具注册
注册和登记可用工具的信息] TOOL2[工具发现
搜索与当前任务匹配的合适工具] TOOL3[工具执行
实际调用和执行工具逻辑] TOOL4[状态管理
维护工具调用间的状态和中间数据] end subgraph INFRA[基础设施层
━━━━━━━━━━━━] INFRA1[MCP集成
通过MCP协议连接外部服务和数据源] INFRA2[权限管理
控制工具和资源的访问权限] INFRA3[错误处理
捕获和恢复运行时异常] INFRA4[反馈机制
收集执行结果反馈，支持持续优化] end IO --> ORCH ORCH --> TOOL TOOL --> INFRA style IO fill:#e3f2fd,stroke:#1565c0 style ORCH fill:#fff3e0,stroke:#e65100 style TOOL fill:#e8f5e9,stroke:#2e7d32 style INFRA fill:#fce4ec,stroke:#c62828

2.2 各层的职责说明

层次 核心组件 主要职责
输入/输出层 输入解析、上下文管理、输出格式化 接收用户输入，注入系统提示和上下文，格式化最终输出
编排调度层 意图分析、路由决策、流程编排 分析用户意图，决定调用哪个模型或工具，编排多步骤流程
工具管理层 工具注册、工具发现、工具执行 管理所有可用工具的生命周期，将工具描述提供给 LLM，执行工具调用
基础设施层 MCP 集成、权限管理、错误处理 提供跨协议通信能力、安全审批机制、容错与重试策略

2.3 Harness 的工作流程（完整周期）

以下是 Harness 处理一次用户请求的完整生命周期：

sequenceDiagram participant User as 用户 participant Harness as Harness 引擎 participant LLM as 大语言模型 participant ToolMgr as 工具管理器 participant MCP as MCP 服务器 User->>Harness: 1. 发送请求（含用户身份/租户信息） Harness->>Harness: 2. 解析输入，注入上下文 & 权限策略 Harness->>LLM: 3. 发送完整 Prompt（含系统指令 + 工具定义） LLM-->>Harness: 4. 返回响应（文本 或 工具调用指令） alt 需要调用工具 Harness->>Harness: 5. 解析并校验工具调用请求 Harness->>ToolMgr: 6. 通过 MCP 协议执行工具 ToolMgr->>MCP: 执行工具 MCP-->>ToolMgr: 7. 返回工具执行结果（含状态码） ToolMgr-->>Harness: 8. 返回结果（已脱敏/过滤） Harness->>LLM: 9. 将工具结果加入对话历史，要求继续生成 LLM-->>Harness: 10. 生成最终响应（含引用说明） else 无需工具调用 LLM-->>Harness: 直接处理文本响应 end Harness->>Harness: 11. 执行权限审计 & 敏感信息脱敏 Harness->>User: 12. 输出最终结果（含置信度/来源）

3. Harness 与相关概念的关系

Harness 作为一个底层执行环境，与 AI 领域的其他核心概念有紧密的关联。理解这些关系有助于构建完整的技术图景。

3.1 概念关系图谱

graph LR Prompt[Prompt
沟通的语言] --> Harness[Harness
执行引擎] Harness --> ToolCall[Tool Call
能力接口] Harness --> Agent[Agent
智能体] ToolCall --> MCP[MCP
集成标准] Agent --> Skill[Skill
行为模板] Agent --> Workflow[Workflow
工作流] style Prompt fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style Harness fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style ToolCall fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style MCP fill:#fadbd8,stroke:#c0392b,stroke-width:2px style Agent fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style Skill fill:#fdebd0,stroke:#e67e22,stroke-width:2px style Workflow fill:#fdebd0,stroke:#d35400,stroke-width:2px

3.2 Harness vs Tool Calling

维度 Tool Calling Harness
本质 一种交互机制 完整的执行环境
范围 单次工具调用 全生命周期管理
职责 定义 LLM 如何输出工具调用指令 管理工具注册、发现、执行、结果整合全流程
错误处理 由外部应用处理 内置重试、降级、超时机制
并发 支持（并行工具调用） 支持 Agent 级、工具级多层级并发

核心区别：Tool Calling 是"接口规范"，定义 LLM 如何请求调用工具；Harness 是"运行时系统"，负责端到端地执行和管理全部流程。

3.3 Harness vs MCP

维度 MCP Harness
本质 开放协议标准 执行引擎实现
焦点 工具与服务的集成规范 系统级协调与编排
范围 定义 Client/Server 通信方式 管理整个 AI 应用生命周期
作用 让不同工具用统一方式接入 让 LLM、工具、数据、逻辑协同工作

核心关系：MCP 是 Harness 的"集成标准"——Harness 通过 MCP 协议连接外部工具和服务。一个符合 MCP 标准的工具，可以被任何实现了 MCP 客户端功能的 Harness 使用。

3.4 Harness vs Agent

维度 Agent（智能体） Harness
本质 一个独立的任务执行单元 运行所有任务的底层环境
存在形式 会话级的实体 系统级的框架
生命周期 从创建到任务完成 贯穿整个应用运行期间
职责 完成特定子任务 管理所有组件（含 Agent）的执行
示例 Claude Code 中的 @agent-name Claude Code 本身的执行引擎

核心关系：Agent 运行在 Harness 之上——Harness 为 Agent 提供运行环境、工具访问、上下文管理等功能。可以理解为：Agent 是在 Harness 这个"操作系统"上运行的"应用程序"。

3.5 Harness 与 Skill / Workflow 的关系

概念 定义 与 Harness 的关系
Skill（技能） 预定义的行为指令模板 Harness 注入 Skill 内容到系统提示，影响模型行为
Workflow（工作流） 编排多步骤、多 Agent 的脚本 Harness 解释和执行 Workflow 脚本，管理子 Agent 生命周期

Skill 和 Workflow 都是 Harness 的"上层建筑"——Harness 负责将它们翻译为可执行的操作序列。

4. Harness 的典型应用场景

Harness 并非纯理论概念，它在实际的 AI 应用中有非常具体的实现。以下从 Claude Code 出发，介绍 Harness 的典型形态。

4.1 Claude Code 执行引擎

Claude Code 本身就是 Harness 的一个具体实现。当你在终端中运行 Claude Code 时，幕后有以下 Harness 组件在工作：

graph TD User[用户输入
User Input] --> Harness[Claude Code Harness] Harness --> Analysis[意图分析与路由决策
Intent & Route] Analysis --> |纯文本对话| LLM[LLM生成回复
LLM Response] Analysis --> |调用Skill| Skill[Skill引擎
Skill Engine] Analysis --> |创建Agent| Agent[Agent管理器
Agent Manager] LLM --> ToolCall[工具调用
Tool Calling] ToolCall --> ToolMgr[工具管理器
Tool Manager] ToolMgr --> MCPClient[MCP客户端
MCP Client] MCPClient --> MCPServer[MCP服务器
MCP Server] Skill --> Output[输出整合器
Output] Agent --> Output LLM --> Output Output --> |后续对话| Harness Output --> Return[返回用户
Return] style Harness fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style LLM fill:#ffecd6,stroke:#d35400,stroke-width:2px style Skill fill:#fdebd0,stroke:#e67e22,stroke-width:2px style Agent fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style ToolCall fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style ToolMgr fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style MCPClient fill:#fadbd8,stroke:#c0392b,stroke-width:2px style MCPServer fill:#fadbd8,stroke:#c0392b,stroke-width:2px

Claude Code Harness 负责的关键职责：

Harness 功能 Claude Code 中的实现
工具管理 内置文件读写、搜索、终端执行等工具
MCP 集成 通过 MCP 客户端连接外部 MCP 服务器
Agent 管理 通过 @agent-name 创建子会话 Agent
Skill 注入 通过 /skill-name 加载并注入行为模板
Workflow 编排 通过 Workflow 工具执行多步骤脚本
权限控制 用户审批机制 + autoApprove 配置
上下文管理 摘要机制，管理长会话等

4.2 智能体（Agent）运行环境

Agent 是 Harness 能力的重要体现。当你在 Claude Code 中创建一个 Agent 时，Harness 在幕后做了这些事情：

  1. 读取 Agent 定义文件（.claude/agents/*.md）
  2. 解析 YAML 元数据（模型、系统提示、工具列表）
  3. 创建一个独立的子会话（新的上下文窗口）
  4. 注入 Agent 的系统提示和工具定义
  5. 监听 Agent 输出并转发回主线会话
  6. Agent 任务完成后，清理子会话资源

Agent 本身不需要处理"如何创建会话"、"如何管理上下文"、"如何调用工具"等底层问题——这些全部由 Harness 完成。Agent 只需要关注"要做什么"。

4.3 技能（Skill）调度系统

Skill 的执行同样依赖 Harness 的能力：

  1. 用户输入 /skill-name
  2. Harness 在 .claude/skills/ 目录下查找对应的 SKILL.md
  3. 读取 Skill 内容并注入到当前会话的系统提示中
  4. 后续对话受 Skill 指令约束，直到会话结束或重新加载

Skill 本身只是一个 .md 文件，不含任何可执行代码。它的执行"能力"完全来自 Harness——是 Harness 将 Skill 的文本指令转化为实际的行为约束。

4.4 工作流（Workflow）编排引擎

Workflow 是 Harness 能力的最高级体现——它涉及多步骤、多 Agent、条件分支和并行执行：

能力 说明
并发控制 管理同时运行的 Agent 数量上限
资源隔离 可为 Agent 创建工作树（worktree），实现文件系统隔离
结果聚合 收集所有 Agent 的输出并传递给下一阶段
条件分支 根据阶段结果决定后续流程（继续/重试/终止）
预算管理 跟踪 Token 消耗，在达到限额时停止
缓存与恢复 缓存已完成 Agent 的结果，支持断点续跑

5. 总结

5.1 核心内容回顾

  • Harness（执行引擎） 是 AI 应用中连接 LLM、工具、MCP、Agent、Skill、Workflow 等所有组件的底层执行环境，相当于 AI 系统的"操作系统"。
  • Harness 的核心架构分为 输入/输出层、编排调度层、工具管理层和基础设施层，各层各司其职。
  • Harness 与 Tool Calling 的关系：Tool Calling 是接口规范，Harness 是完整的运行时系统。
  • Harness 与 MCP 的关系：MCP 是集成标准，Harness 是执行引擎；Harness 通过 MCP 连接外部工具。
  • Harness 与 Agent 的关系：Agent 运行在 Harness 之上，Harness 为 Agent 提供运行环境。
  • Harness 在 Claude Code 中体现为完整的执行引擎，管理工具、Agent、Skill 和 Workflow 的全生命周期。

5.2 常见问题与解答

问：Harness 和 Framework（框架）有什么区别？ Framework 是开发阶段的工具，帮助开发者编写代码；Harness 是运行时的系统，管理组件执行。

问：Harness 是 Claude Code 独有的概念吗？ 不是。Harness 是 AI 工程领域的通用概念。OpenAI 的 Assistants API、LangChain 的 Agent 执行器、Dify 的工作流引擎等都有自己的 Harness 实现。

问：Harness 自己会不会调用工具？ Harness 本身不直接调用工具——它负责任务调度和流程管理。实际的工具调用由工具管理器（Tool Manager）通过 MCP 或其他协议执行，调用结果再经由 Harness 返回给 LLM。

问：我是否需要自己实现一个 Harness？ 通常不需要。成熟的 AI 工具（如 Claude Code、Dify、LangChain）已经内建了完善的 Harness。只有在需要自定义底层执行逻辑时（如开发自己的 AI 开发平台），才需要考虑实现 Harness。