读懂 Harness，掌握智能体工程化的核心骨架

读懂 Harness，掌握智能体工程化的核心骨架

当下 AI Agent 领域的技术重心正在发生明显迁移。从早期打磨提示词，到优化上下文组织，如今行业正式迈入Harness Engineering（Harness 工程） 阶段。LangChain 团队成员提出核心论断：Agent = Model + Harness ，直白点说，完整的智能体绝非单纯的大模型，而是模型本体 加上外围全套支撑系统。本文结合实战代码、分层架构、核心组件与落地逻辑，全方位拆解 Harness 的概念、构成、运行原理与工程价值，帮你彻底搞懂这一驱动 Agent 从 "演示 Demo" 走向 "生产可用" 的关键体系。

一、技术演进：从 Prompt 到 Harness，研发重心全面外移

梳理近三年 AI 应用的技术迭代脉络，能清晰看到研发视角的转变，每一轮升级都在弱化对模型本身的依赖，强化模型外围工程体系的构建：

1. 2023-2024 年：提示词工程（Prompt Engineering）核心目标是优化人与模型的对话话术，通过精细化 Prompt 引导大模型输出符合预期的内容，所有优化都聚焦在单次交互文本上。
2. 2025 年：上下文工程（Context Engineering）不再局限于单条提示词，重点研究对话历史、参考资料、结构化信息的组织方式，解决长对话、信息匹配等问题，核心是管理模型的 "输入信息池"。
3. 2026 年：Harness 工程（Harness Engineering）视野拓展到模型之外的全链路基础设施，涵盖工具调用、记忆存储、任务规划、安全管控、多智能体协作、上下文压缩等模块。不再纠结 "模型怎么想"，而是搭建一套让模型真正落地干活的完整系统。

Harness 本义为 "马具"，这是一个非常形象的比喻：大模型是骏马，拥有思考与推理的能力；Harness 就是马鞍、缰绳、道路、围栏整套配套设施。脱离马具，骏马无法完成运输工作；脱离 Harness，裸大模型仅能实现文本输入输出，无法对接真实业务场景。

从本质定义来讲：Harness 就是大模型之外的所有工程代码、配置规则、执行逻辑与配套组件。裸模型天生存在诸多短板：无法执行代码、读写本地文件，没有持久化对话记忆，不能拆解复杂任务，缺少安全防护机制，也无法实现多智能体协作。而 Harness 的核心使命，就是用工程化手段补齐这些能力缺口，把模型的 "原生智能" 转化为可落地、可管控、可复用的 "工作引擎"。

二、Harness 七大核心组件：从代码视角拆解完整骨架

原系列文章用七篇实战内容搭建出了 Harness 的完整核心骨架，七个模块层层递进、环环相扣，每一个组件都对应明确的能力补充与代码实现。下面结合原始代码片段、功能定位、应用场景逐一解析，还原整套系统的运行逻辑。

1. 工具 + 执行循环：Harness 的底层地基（基础行动能力）

这是整套体系的最底层核心 ，也是最小可用 Harness 单元。它打破了裸模型 "只能输出文本" 的局限，赋予模型操作外部环境的能力，构建起模型决策→Harness 执行→结果回传的闭环运行逻辑。

核心代码片段

# 最小Harness：工具 + 循环执行框架
tools = [execute_bash, read_file, write_file]  # 定义可用工具：命令行、文件读写
max_iterations = 10  # 最大执行轮次

for _ in range(max_iterations):
    # 1. 模型接收消息，输出工具调用意图（Model负责思考决策）
    response = llm.call(messages, tools)
    # 2. Harness拦截模型输出，执行对应工具动作
    if response.tool_calls:
        result = execute(tool_call)
        # 3. 将执行结果追加到对话消息，回传给模型进入下一轮循环
        messages.append(result)

功能解读

• 模型仅负责判断 "需要调用什么工具、传入什么参数"，实际操作由 Harness 完成；
• 循环机制保障多步任务持续推进，是代码助手、自动化运维、项目构建类 Agent 的基础；
• 该模块仅用 115 行代码即可实现，也是 OpenClaw、Claude Code 等主流代码智能体的底层底座。

2. 记忆 + 规划：赋予模型时间维度与任务拆解能力

裸模型无持久记忆，每一次调用都是独立会话，同时面对复杂长任务时无法自主拆分。该模块通过外部存储实现记忆 ，通过任务编排实现规划，相当于给模型配备 "笔记本" 和 "任务地图"。

核心代码片段

# 记忆模块：Harness接管历史对话存储与加载
memory = load_memory()  # 从文件/数据库读取历史会话
system_prompt += memory  # 将历史记忆注入模型输入

# 规划模块：Harness拆解复杂任务，分步执行
steps = create_plan(task)  # 拆分主任务为多个子步骤
for step in steps:
    run_agent_step(step, messages)  # 逐步骤执行Agent逻辑

功能解读

• 记忆并非模型原生能力：所有历史对话、用户偏好、任务进度都由 Harness 持久化存储，再拼接至 Prompt 中模拟 "记忆效果"；
• 规划是工程层能力：由 Harness 先完成任务拆分，引导模型按步骤执行，避免模型因任务过杂出现逻辑混乱；
• 广泛应用于长会话客服、个人知识库、项目全流程自动化等场景。

3. 规则 + 技能 + MCP 工具：知识注入与行为约束

该模块负责给模型划定行为边界、注入专属业务知识、动态扩展工具集，相当于给模型配备规章制度手册、专业技能库、可扩展工具箱。

核心代码片段

# 加载规则、技能、历史记忆，拼接为系统提示词（知识注入）
system_prompt = 基础指令 + Rules + Skills + Memory

# 动态加载工具：基础工具 + MCP扩展工具（灵活扩展能力）
all_tools = base_tools + mcp_tools

功能解读

• Rules（规则） ：定义项目规范、输出格式、禁止行为，约束模型越界操作；
• Skills（技能） ：沉淀专属业务能力，例如生成 Word 文档、对接第三方 API、特定领域问答等；
• MCP：作为工具扩展协议，支持外部服务快速接入，实现工具池的动态扩容；
• 日常开发中编写的CLAUDE.md、项目配置文件，本质都属于该模块，是 Harness 的组成部分。

4. 子 Agent（SubAgent）：临时任务委派能力

面对细分专项任务时，单一模型效率有限。Harness 支持临时创建子智能体，将专项任务委派给对应角色的子 Agent 处理，实现 "专人专事"。

核心代码片段

# 生成临时子Agent，独立上下文、独立执行循环
def subagent(role, task):
    sub_messages = [{"role": "system", "content": f"You are a {role}"}]
    # 子Agent拥有独立对话与执行逻辑，主Agent不介入内部流程
    # 子任务执行完成后，结果回传给主Agent

功能解读

• 子 Agent 由 Harness 统一创建、销毁与调度，主模型感知不到子 Agent 的运行细节；
• 适用于大型项目拆解、多模块协同、专项数据分析等场景，降低主 Agent 的负载。

5. 多 Agent 团队（Teams）：常驻智能体协作编排

区别于临时子 Agent，该模块面向长期运行的多智能体团队，由 Harness 统一管理所有常驻 Agent 的生命周期、通信通道、消息收发，构建稳定的协作体系。

核心代码片段

# 常驻Agent类：包含独立记忆与通信通道
class Agent:
    def __init__(self, name, role):
        self.messages = [...]  # 独立持久记忆
        self.inbox = []        # 跨Agent通信收件箱

功能解读

• 每个 Agent 拥有独立身份、记忆与通信队列，Harness 充当 "团队管理者"，调度消息流转与任务分配；
• 是多角色协作系统、分布式智能集群、企业级流程 Agent 的核心模块。

6. 上下文压缩：解决 "上下文腐烂" 问题

随着对话轮次增加，历史消息不断累积，会出现上下文腐烂（Context Rot） ：关键信息被冗余内容淹没，模型推理效率下降、准确率降低。上下文压缩是 Harness 对抗该问题的核心手段。

核心代码片段

# 每轮执行前压缩对话消息：旧消息摘要化，最新消息完整保留
messages = compact_messages(messages)

配套优化策略

1. 工具输出分流：超大工具执行结果存入本地文件，Prompt 中仅保留摘要；
2. 技能按需加载：不一次性注入所有技能，根据当前任务动态加载，精简输入 Token；

• 该模块是长会话 Agent、海量知识库 RAG 应用的必备优化项，直接决定系统运行成本与稳定性。

7. 安全防线 + 执行钩子（Hook）：风险拦截与流程管控

裸模型没有安全意识，可能执行rm -rf /等高风险命令、输出违规内容。Harness 在模型与真实环境之间搭建钩子管道 ，在动作执行前后做拦截、校验、处理，构建安全防线。同时延伸出Ralph Loop机制，解决任务提前终止问题。

7.1 通用 Hook 安全管道代码

# 前置钩子：执行工具前拦截（黑名单、人工确认）
before_hooks = [check_blacklist, ask_confirmation]
# 后置钩子：执行工具后处理（内容截断、格式修正）
after_hooks = [truncate_output]

def execute_with_hooks(tool_name, args, func):
    # 执行前安全校验
    for hook in before_hooks:
        blocked, msg = hook(tool_name, args)
        if blocked:
            return msg
    # 执行真实工具逻辑
    result = func(**args)
    # 执行后内容处理
    for hook in after_hooks:
        result = hook(tool_name, result)
    return result

7.2 Ralph Loop：迭代续跑机制（解决任务中途退出）

原始执行循环设置了max_iterations硬上限，轮次用尽后无论任务是否完成都会强制退出。Ralph Loop作为退出前置钩子，将硬上限改为软检查点，实现长任务自动续跑。

def ralph_loop_hook(messages, result):
    # 检测是否达到最大迭代轮次，即将退出
    if result == "Max iterations reached":
        # 调用模型判断任务是否真正完成
        check = llm.call("Based on the conversation, is the task fully completed? Reply YES or NO.")
        if "NO" in check:
            # 任务未完成，注入提示，阻止退出，继续循环
            messages.append({"role": "user", "content": "任务还没完成，请继续。"})
            return False
    # 任务完成，允许正常退出
    return True

功能解读

• 安全 Hook 可拦截高危命令、敏感操作，是线上 Agent 必备的风控能力；
• Ralph Loop 配合文件持久化、上下文压缩，可支撑 Agent 连续运行上百轮，完成大型项目开发、全流程运维等超复杂任务。

三、整体架构全景：Model 与 Harness 的层级协作关系

结合七大组件，我们可以梳理出一套完整的分层架构，清晰展示模型居中、Harness 全链路包裹的运行模式，也是生产级 Agent 的标准架构：

1. 最上层：规则、技能、MCP 工具负责知识注入、行为约束、工具扩展，统一整合后拼接为系统提示词；
2. 信息层：记忆 + 上下文压缩管理对话历史、精简输入内容，解决信息过载与记忆丢失问题；
3. **核心层：大模型（Model）**唯一职责：接收结构化输入、完成推理决策、输出工具调用或文本结果；
4. 校验层：Hook 钩子管道对模型输出做安全拦截、人工确认、格式修正，过滤风险操作；
5. 执行层：工具执行循环落地文件读写、命令行、API 调用等实际操作；
6. 协作层：子 Agent + 多 Agent 团队负责任务委派、多智能体通信与生命周期管理。

整套架构的核心逻辑自始至终保持统一：模型只负责 "思考"，Harness 负责 "执行、管控、扩展、防护" 。市面上同类模型的产品体验差距，几乎都来自 Harness 的设计优劣，而非模型本身。

四、Harness 工程的核心价值：重新定义 Agent 开发逻辑

理解 Harness 的概念与架构，不仅是掌握一项新技术，更是重塑 AI Agent 的研发思维，其行业价值体现在三大维度：

1. 打破 "模型决定一切" 的误区

很多开发者误以为 Agent 的效果完全取决于大模型能力。但实际落地中，同款模型搭配不同 Harness，最终体验天差地别。Claude Code、OpenClaw 等热门代码智能体，所使用的模型普通开发者均可调用，但其核心竞争力并非模型，而是经过打磨的工具链、记忆策略、安全规则、上下文压缩算法等整套 Harness 体系。模型决定智能下限，Harness 决定产品上限。

2. 明确 Agent 工程师的核心工作边界

对于 Agent 开发者而言，工作内容可以一句话概括：你不是在训练大模型，就是在搭建和优化 Harness。日常编写的工具函数、配置的规则文档、设计的记忆策略、搭建的安全拦截、开发的多智能体编排逻辑，全部属于 Harness 范畴。即便未来大模型能力持续增强，也无法脱离配套基础设施 ------ 就像人类再聪明，也需要办公设备、规章制度、协作体系才能开展工作。

3. 统一行业术语与架构标准

在 Harness 概念普及之前，行业对模型外围系统的称呼杂乱：Agent 框架、编排层、中间件、工具链等，边界模糊、沟通成本高。而Agent = Model + Harness给出了极简且清晰的定义：模型之外的所有工程体系，都属于 Harness。这一标准让全球 AI 开发者拥有统一的架构认知，也让 Agent 项目的设计、迭代、运维变得更加标准化。

五、落地总结：从实战到生产的落地启示

1. 入门与原型阶段 按照七大组件循序渐进搭建：先实现工具 + 执行循环最小骨架，再叠加记忆、规则、安全能力，这也是原系列七篇文章的学习路径，整套核心代码仅 507 行，门槛极低。
2. 项目迭代阶段 优先优化上下文压缩 和安全 Hook，这两个模块直接影响系统稳定性与线上风险；复杂任务场景接入子 Agent 与多 Agent 协作。
3. 生产部署阶段完善 MCP 工具扩展、Ralph Loop 长任务续跑机制、日志可观测体系，对标商用产品（Claude Code、OpenClaw）完成能力补全。

六、写在最后

AI Agent 的竞争，已经从 "模型能力比拼" 悄然转向Harness 工程能力比拼。提示词、上下文只是单点优化，而 Harness 是一套完整的工程体系。掌握 Harness 的组件逻辑、代码实现与架构思想，就等于掌握了将大模型能力落地为商业化产品的核心能力。

---