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

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

这两年，AI Agent 的发展方向其实发生了挺大的变化。一开始大家都在琢磨怎么把提示词写得更好，后来又开始研究怎么把上下文组织得更聪明，到了现在，行业里一个更清晰的概念开始落地——

。LangChain 团队有一句话说得特别直白：。翻译过来就是，一个真正能用的智能体，不是光靠一个大模型就行的，它还需要一套完整的外围支撑系统。这篇文章会从实战代码、分层架构、核心组件到落地逻辑，把这套体系掰开揉碎讲清楚，帮你看懂 Harness 到底是什么，以及它为什么能让 Agent 从“演示 Demo”真正走向“生产可用”。

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

如果我们把最近几年 AI 应用的技术路线拉出来看看，会发现一个很清晰的趋势：每一次升级，研发的重心都在往模型外围迁移，模型本身的重要性反而在相对下降。

1. 2023-2024 年：提示词工程（Prompt Engineering）。那时候大家的核心工作是跟模型“对话”，想方设法通过精心设计的提示词，让模型输出你想要的内容。所有功夫都花在

   单次交互的文本打磨
   上。
2. 2025 年：上下文工程（Context Engineering）。这时候大家发现，光靠一句提示词不够用了，得把对话历史、参考资料、结构化信息这些都组织好。重点变成了管理模型的“输入信息池”，解决长对话和信息匹配的问题。
3. 2026 年：Harness 工程（Harness Engineering）。现在的思路完全打开了，视野从模型本身扩展到了全链路的基础设施——工具调用、记忆存储、任务规划、安全管控、多智能体协作、上下文压缩，这些通通被纳入了工程体系。大家不再纠结“模型怎么想”，而是琢磨怎么搭一套让模型

   真正干活
   的完整系统。

Harness 这个词从字面上看是“马具”，这个比喻非常形象：

。光有一匹好马，没有这身行头，它也干不了运输的活儿。同理，一个裸模型，再聪明也只能做文本输入输出，根本没法对接真实的业务场景。

所以说到底，

。裸模型天生有太多短板：不能执行代码、不能读写本地文件、没有持久化的对话记忆、拆解不了复杂任务、缺乏安全防护机制，更别提多智能体协作。Harness 的核心使命，就是用工程化手段把这些能力缺口一个一个补上，把模型的“原生智能”转化成可落地、可管控、可复用的“工作引擎”。

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

接下来，我们从工程实现的角度，把 Harness 的七个核心模块逐一拆开来看。每个模块都对应着明确的能力补充和代码实现，它们层层递进、环环相扣，共同构成了这套系统的完整骨架。

1. 工具 + 执行循环：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、项目配置文件，本质上都属于这个模块。

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. 上下文压缩：解决“上下文腐烂”问题

随着对话轮次增加，历史消息越堆越多，就会出现一个很头疼的问题——

。关键信息被大量冗余内容淹没，模型的推理效率和准确率都会明显下降。上下文压缩，就是 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 的层级协作关系

把上面这七个组件串起来，就能梳理出一套完整的分层架构。这套架构清晰地展示了

的运行模式，也是生产级 Agent 的通用标准架构：

1. 最上层：规则、技能、MCP 工具
   。负责知识注入、行为约束和工具扩展，统一整合后拼接为系统提示词；

2. 信息层：记忆 + 上下文压缩
   。管理对话历史、精简输入内容，解决信息过载和记忆丢失的问题；

3. 核心层：大模型（Model）
   。它的唯一职责就是接收结构化输入、完成推理决策、输出工具调用或文本结果；

4. 校验层：Hook 钩子管道
   。对模型输出做安全拦截、人工确认和格式修正，过滤掉风险操作；

5. 执行层：工具执行循环
   。落地文件读写、命令行、API 调用这些实际操作；

6. 协作层：子 Agent + 多 Agent 团队
   。负责任务委派、多智能体通信和生命周期管理。

整套架构的核心逻辑始终如一：

。市面上同类模型的产品体验之所以差别很大，几乎都来自 Harness 的设计优劣，而不是模型本身。

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

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

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

很多开发者觉得，Agent 的效果完全取决于大模型的能力。但实际情况是，

。像 Claude Code、OpenClaw 这些热门的代码智能体，它们用的模型普通开发者也能调，但核心竞争力根本不在于模型，而在于经过打磨的工具链、记忆策略、安全规则、上下文压缩算法这些整套的 Harness 体系。说句更直白的：模型决定的是智能的下限，而 Harness 才决定产品的上限。

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

对于做 Agent 开发的工程师，工作内容其实可以用一句话来概括：

。平时写的工具函数、配置的规则文档、设计的记忆策略、搭建的安全拦截、开发的多智能体编排逻辑——这些东西全都属于 Harness 的范畴。哪怕未来大模型的能力再强，它也没办法脱离这套配套基础设施独立运转。这就跟人类一样，再聪明的人，也需要办公设备、规章制度和协作体系才能把工作做好。

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

在 Harness 这个概念普及之前，行业里对模型外围系统的叫法五花八门：Agent 框架、编排层、中间件、工具链……边界模糊，沟通成本很高。而Agent = Model + Harness这个公式给出了一个极简又清晰的定义：

。这个标准让全球的 AI 开发者有了统一的架构认知，也让 Agent 项目的设计、迭代和运维变得更加标准化。

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

1. 入门与原型阶段
   。可以按照这七个组件循序渐进地搭建：先搞定

   工具 + 执行循环
   这个最小骨架，再逐步叠加记忆、规则和安全能力。这也是那系列文章的学习路径，整套核心代码只有 507 行，门槛相当低。

2. 项目迭代阶段
   。优先优化

   上下文压缩
   和

   安全 Hook
   ，这两个模块直接影响系统的稳定性和线上风险。遇到复杂的任务场景，再接入子 Agent 和多 Agent 协作。

3. 生产部署阶段
   。完善 MCP 工具扩展、Ralph Loop 长任务续跑机制和日志可观测体系，对标 Claude Code、OpenClaw 这些商业产品，把能力补全。

六、写在最后

AI Agent 的竞争，已经从“模型能力比拼”悄悄转到了

。提示词和上下文优化只是单点上的打磨，而 Harness 是一套完整的工程体系。掌握了 Harness 的组件逻辑、代码实现和架构思想，就等于抓住了把大模型能力落地为商业化产品的核心能力。