引言

随着大语言模型能力的快速提升，AI Agent 被赋予了越来越复杂的任务：从自动化编写代码、跑通测试，到自主构建完整的全栈应用。然而，当任务的复杂度超过单个上下文窗口所能容纳的范围时，Agent 的表现往往会出现明显退化。

这就引出了”Agent Harness（智能体执行框架）”这一概念。Harness 不是模型本身，而是围绕模型构建的一套调度机制和工程脚手架，用来解决长时运行任务中出现的上下文切换、任务衔接、状态管理等核心问题。Anthropic 工程团队在实际构建长时 Agent 系统的过程中，系统地探索了 Harness 的设计方法，并将经验总结在两篇工程博客中（见文末参考资料）。本文将基于这些内容，介绍 Agent Harness 的核心概念与设计模式。

什么是 Agent Harness

Agent Harness（智能体执行框架）是指围绕大语言模型构建的一套外部调度与工程机制，其目的是让 Agent 能够在长时任务中保持稳定、高效地运行。

可以用一个比方来理解：如果 Agent 是一名工程师，那么 Harness 就是这名工程师的工作环境——包括交接文档、任务清单、版本控制系统、测试流程等。没有这些基础设施，即便是经验丰富的工程师在换班时也会不知所措。

一个典型的 Harness 通常包含以下要素：

  • 初始化机制：在任务开始时建立清晰的工作环境和任务上下文
  • 状态持久化：保存任务进度，供下一个 Agent 实例恢复工作
  • 任务分解结构：将复杂任务拆解为可独立完成的子任务
  • 测试与验证流程：确保每个阶段的输出符合预期
  • 上下文管理策略：应对上下文窗口用尽的情况

长时运行 Agent 的挑战

为什么朴素实现会失败

当给 Agent 一个高层次的指令（如”构建一个 claude.ai 的克隆版本”）时，如果没有额外的 Harness 支持，Agent 通常会出现两类典型的失败模式：

第一类是”一次性完成”的冲动。Agent 倾向于试图在单个上下文窗口内完成整个任务，结果是在实现到一半时上下文耗尽，留下半完成的、未文档化的代码，导致下一个会话的 Agent 必须花费大量时间猜测之前发生了什么。

第二类是”提前宣告完成”。在一些功能已经实现之后，后续的 Agent 实例可能看到已有进展就认为任务基本完成，直接宣告胜利并停止工作，忽略了大量尚未实现的功能。

上下文焦虑问题

除了上述两类失败，还有一个更微妙的问题：上下文焦虑（context anxiety）。某些模型在感知到上下文窗口即将用尽时，会开始提前收尾工作——匆匆生成结论、跳过未完成的功能、草率地标记任务为”完成”。这并非模型能力不足，而是对上下文限制的一种错误应对。

上下文压缩（compaction）技术虽然能够延长上下文寿命，但并不能完全解决焦虑问题——因为模型仍然处于同一个会话中，感知到的上下文压力没有从根本上消除。

核心 Harness 设计要素

Anthropic 的工程团队通过实验，总结出了一套有效的 Harness 设计方案，核心是”初始化 Agent + 编码 Agent”的两阶段结构。

初始化 Agent

初始化 Agent 只在任务的第一个会话中运行，负责搭建整个工作环境，为后续所有会话提供清晰的上下文。具体包括：

  • 生成功能需求列表（feature_list.json）：将高层次的用户需求展开为具体、可验证的功能点，初始状态均标记为”未通过”
  • 编写启动脚本（init.sh）：记录如何启动开发服务器，避免每个编码 Agent 都要重新摸索
  • 创建进度文件（claude-progress.txt）：记录任务进展，为后续会话提供历史摘要
  • 建立初始 git 仓库，并提交初始代码

功能需求列表是其中最关键的组件。以 claude.ai 克隆项目为例，该列表包含了超过 200 个具体功能点，例如：

1
2
3
4
5
6
7
8
9
10
11
12
{
  "category": "functional",
  "description": "新建对话按钮能创建一个全新的会话",
  "steps": [
    "导航到主界面",
    "点击"新建对话"按钮",
    "验证新会话已被创建",
    "检查对话区域显示欢迎状态",
    "确认会话出现在侧边栏中"
  ],
  "passes": false
}

Agent 被明确要求只能通过修改 passes 字段来更新功能清单，且禁止删除或修改测试描述本身，以防止因”减少测试数量”来刷通过率的投机行为。使用 JSON 格式而非 Markdown，也是为了降低模型无意间修改结构的概率。

增量进展策略

在初始化完成之后，编码 Agent 的核心工作原则是：每次只做一件事，做完一件再做下一件。

具体而言，每个编码会话开始时，Agent 会：

  • 读取进度文件和 git 日志，了解上次做到了哪里
  • 从功能列表中选择优先级最高的未完成功能
  • 专注实现该功能，并在完成后提交 git commit（附带描述性提交信息）
  • 更新进度文件，记录本次会话的工作内容

这种增量式的方式从根本上避免了”一次性完成”的冲动，同时确保每次会话结束时，代码库都处于干净、可提交的状态。

端到端测试

在没有明确提示的情况下，Agent 容易将”代码写完”等同于”功能实现”，而实际上功能可能存在端到端的集成问题。Anthropic 的实践表明，明确提示 Agent 使用浏览器自动化工具（如 Puppeteer MCP）进行端到端测试，可以显著提升功能的最终质量。

一个典型的会话开始序列如下：

  • 启动开发服务器
  • 通过浏览器自动化工具执行一次基础端到端测试（如发起一个对话、接收回复）
  • 确认应用处于可工作状态后，再开始新功能的开发

这样的流程能够在第一时间发现遗留 bug，避免”边开发新功能，边埋下旧问题”的情况。

进阶 Harness 设计：生成器与评估器

在基础 Harness 能够让 Agent 稳定运行之后，Anthropic 的工程师进一步引入了一个更强大的设计模式：受生成对抗网络（GAN）启发的”生成器 - 评估器”双 Agent 架构。

为什么需要双 Agent

单个 Agent 在评估自己输出时，存在明显的乐观偏差：它倾向于认为自己的工作是好的，即便在旁观者看来质量明显不足。这个问题在主观性强的任务（如前端设计）中尤为突出。

将生成和评估分离到两个 Agent 中，是解决这个问题的有效手段。评估 Agent 专注于发现问题，而生成 Agent 则根据反馈进行改进。更重要的是，把一个针对 LLM 生成内容保持怀疑态度的评估者提示进行精心调优，要比让生成 Agent 自我批评容易得多。

前端设计的评估标准化

在前端设计场景中，Anthropic 定义了四个可量化的评估维度：

  • 设计质量：设计是否整体协调、具有统一的视觉语言，而不只是零散组件的堆砌
  • 原创性：是否有明显的定制化决策，而非直接使用模板、库的默认样式或 AI 生成的俗套模式（如紫色渐变白卡片）
  • 工艺水准：字体层级、间距一致性、色彩对比等技术执行质量
  • 功能性：用户能否理解界面用途，顺利完成操作

评估 Agent 配备了 Playwright MCP，可以直接与生成的网页进行真实交互（而非只看静态截图），逐项打分后生成详细评审报告，反馈给生成 Agent 进行下一轮改进。实验中每次构建跑 5 到 15 次迭代，每轮迭代评估分数稳步提升，直到趋于平稳。

全栈开发的三 Agent 架构

将双 Agent 模式扩展到全栈开发时，Anthropic 进一步演进为三 Agent 架构：

规划者（Planner）：接受用户的简短描述（1-4 句话），将其扩展为详细的产品功能规格，并主动寻找将 AI 特性融入产品的机会。规划者只关注”要做什么”，刻意避免指定”怎么做”，以防止早期的错误假设传导到后续实现中。

生成者（Generator）：按照规格逐步构建应用，每次完成一个功能点（sprint），并在每个 sprint 结束时进行自我评估后移交给评估者。

评估者（Evaluator）：使用 Playwright MCP 像真实用户一样操作已部署的应用，根据预先约定的验收标准逐项检验，将 bug 和质量问题列表反馈给生成者进行修复。

生成者和评估者在每个 sprint 开始前会先”协商合同”（sprint contract）：明确这个 sprint 要实现什么、如何验证完成。这一协商步骤有效弥合了高层规格与可测试实现之间的鸿沟。

两个 Agent 之间通过文件来传递信息——一个 Agent 写文件，另一个读文件并回应。这种方式简单可靠，避免了复杂的实时通信依赖。

上下文管理：压缩与重置

上下文重置 vs. 上下文压缩

处理上下文窗口耗尽问题，主要有两种策略：

上下文压缩（compaction）是在同一会话内，将较早的对话历史进行摘要，腾出空间继续执行。这种方式保留了会话的连续性，但并不给 Agent 一个”全新的开始”，上下文焦虑问题可能仍然存在。

上下文重置（context reset）是完全清空上下文，启动一个全新的 Agent 实例，通过结构化的交接文档（handoff artifact）将必要的状态传递给新 Agent。这能彻底消除上下文焦虑，但需要交接文档足够完整，才能让新 Agent 顺利接手。

在早期使用 Claude Sonnet 4.5 的实验中，上下文焦虑问题足够严重，必须采用上下文重置才能保证长时任务的稳定性。而在 Opus 4.6 上，模型的长上下文能力显著提升，自带的压缩机制已经足够，无需再做额外的重置处理。

Harness 复杂度随模型能力而演化

这一点值得特别关注：Harness 的每个组件都对应着对模型能力的一个假设。模型更强了，某些组件就可能不再必要。

Anthropic 的实践表明，Opus 4.6 相比 4.5 在长时任务规划、大型代码库操作、自我 Debug 等方面有显著提升，这使得原本需要”sprint 分解”才能保持稳定的任务，现在可以由模型在一次连续会话中完成。因此，工程师将原来按 sprint 触发的评估者，改为在整个构建完成后做一次性评估，既降低了系统复杂度，又保留了评估者在关键边界任务上的价值。

Anthropic 总结的原则是：遵循”找到最简单有效的方案，只在必要时增加复杂度”的原则，并在每次新模型发布后，重新审视 Harness 中哪些组件仍然必要。

常见失败模式与解决方案

失败模式 初始化 Agent 的对策 编码 Agent 的对策
Agent 过早宣告任务完成 生成包含所有功能点的功能清单文件 每次会话开始时读取功能清单，选取单个未完成功能作为本次目标
Agent 遗留 bug 或未记录进展 创建初始 git 仓库和进度文件 会话开始时读取进度文件和 git 日志；会话结束时提交 commit 并更新进度
Agent 未做真实测试就标记功能为完成 生成功能清单，明确验证步骤 使用浏览器自动化进行端到端测试，通过真实操作验证功能
Agent 每次会话都要重新摸索如何启动应用 编写 init.sh 启动脚本 会话开始时读取并执行 init.sh

总结

Agent Harness 是构建长时运行 AI Agent 系统的关键工程基础。它的核心价值不在于让模型变得更聪明，而在于为模型提供稳定、结构化的工作环境：清晰的任务边界、持续的状态传递、独立的质量评估反馈。

从 Anthropic 的实践中可以提炼出以下设计原则：

  • 从最简单的方案开始，只在遇到真实问题时才增加复杂度
  • Harness 中每个组件都应有明确的存在理由，随着模型能力提升及时精简
  • 将生成与评估分离，有助于打破模型的自我乐观偏差
  • 用结构化文件（功能清单、进度文件、交接文档）而非依赖上下文记忆来传递状态
  • 端到端测试是发现集成问题的唯一可靠手段

随着模型能力的持续提升，Harness 的具体形式也在不断演化。但其核心思想——通过工程手段补足模型的系统性短板——将长期保持其价值。

参考资料