搞懂Harness：AI代理高效工作的关键

作者：@rohit4verse

你并非因为没找到正确的模型而用错了 AI。

你用错 AI，是因为你没有构建正确的环境。

有些团队用三名工程师交付了百万行代码，另一些团队却连 agent 流水线里一次稳定的重构都难以实现 ——原因不在于 GPT-5 还是 Claude Opus 的差别，不在于 temperature 设置或 max tokens，甚至不在于提示词，尽管大家为提示词争论耗费了无数岁月。

差别在于 harness。

本文要讲的，就是这个词在技术层面和观念层面究竟意味着什么 ——因为整个行业已经养成了一个坏习惯：把这个词用得漫不经心。

harness不是系统提示词，不是对 API 调用的封装，不是评估框架、提示词模板，也不是带记忆功能的聊天机器人。

 harness 是语言模型运作其中的完整设计环境，包括它可以调用的工具、它所接收信息的格式、它的历史记录如何被压缩和管理、在错误级联之前捕获它的护栏，以及让它能够将工作移交给未来的自己而不失去连贯性的脚手架。

当你审视 Anthropic 为使 Claude Code 真正奏效而构建的东西， OpenAI 为通过 Codex 以零手写代码交付百万行代码而构建的东西，以及普林斯顿 NLP 组在其关于 agent-计算机接口的里程碑论文 SWE-agent 中所发表的内容，你会开始看到一个相同的模式从每一个认真工作于这一领域的团队中浮现出来。

模型几乎无关紧要。 harness 就是一切。

这是一份关于这一理念如何成为 2025 至 2026 年应用 AI 工程核心洞察的详细技术分析。它涵盖了相关研究、真实的实现案例、驱动设计决策的失败模式，以及无论你在构建编程 agent、研究 agent 还是长期运行的自主软件工程师时都会反复出现的那些模式。

读完之后，你不仅会理解 harness 是什么，更会明白为何正确地构建一个 harness，已经成为当今行业中最有价值的工程技能。

第一部分：无人谈论的问题

为什么原始能力还不够

2024 年中， AI 基准测试领域发生了一件奇怪的事。研究人员开始注意到，同一个前沿模型在完全相同的编程任务上，会因任务呈现方式和可用工具的不同而产生截然不同的结果。模型没有变，底层智能没有变，变的只是接口。

这本不应令人惊讶。几十年来我们早已知晓，合适的工具能让工程师的效率大幅提升。一名拥有现代 IDE、调试器、版本控制和 CI/CD 流水线的软件开发者，其效能数量级地高于同一个人只用文本编辑器在纯终端中工作。 IDE 并未让开发者变得更聪明，它减少了摩擦，在恰当的时机浮现信息，尽早捕获错误，并将工作组织成可导航的单元。

语言模型亦然。它们不是从某个无限内部知识库进行推理的通用推理机，而是在上下文窗口中对 token 进行操作的精密模式匹配引擎。它们在某一时刻所知道的一切，由上下文窗口中的内容决定；它们产出的一切，以该上下文的结构为条件。输入的格式不是装饰，它是 agent 的认知架构。

接口不是便利层。对于语言模型 agent 而言，接口就是心智本身。

这是普林斯顿 NLP 组 2024 年发表的 SWE-agent 论文的核心主张，经得起推敲。该论文引入了 Agent-计算机接口（ ACI）的概念，并证明一个精心设计的 ACI 与同一模型通过标准 Linux shell 交互相比，可在基准测试性能上产生 64% 的相对提升。

相同的模型，相同的任务，相同的计算预算，唯一的变量是接口。

让这个数字沉淀片刻。64% 不是边际收益，这是有效工具与无效工具之间的差距。而它完全来自环境设计，而非来自底层模型的任何改进。

上下文窗口不是内存插槽

对 AI agent 的朴素认知模型，将上下文窗口视为内存。你加载数据，模型处理，你得到输出。上下文越多等于性能越好，提示词越长等于理解越深。这个心智模型是错误的，而且错误的方式会毁掉你以此为基础构建的 agent。

上下文窗口实际上更接近于 agent 在特定会话中的整个工作意识。窗口中的每个 token 都有计算成本。每一条无关信息都在与相关信息争夺注意力。模型没有能够干净地忽略噪声的选择性注意机制 ——噪声在场，就会影响推理。

这对 agent 设计有具体的、可测量的后果。当你在 agent 循环内部对大型代码库运行 grep 并返回一万行匹配结果时，你并没有给 agent 更多可以利用的信息，你是在用无关数据淹没它的工作记忆，这将降低后续每一个步骤的质量，直到上下文被清空。

当你因为 agent 想看两个函数就用 cat 把整个文件倾倒出来时，你在它需要一杯水的时候递给了它一根消防水管。

 SWE-agent 的研究者详细记录了这些失败模式。标准 bash 接口会导致 agent 陷入反复横跳：它们会发出返回数千行结果的 grep 命令，迷失于自己在寻找什么，再发出更多 grep 命令，逐渐用噪声填满上下文，最终要么给出错误答案，要么彻底停止进展。

问题不在于模型智能，而在于接口没有任何机制来保护 agent 免于被自身淹没。

 ACI 的解决方案是构建一个返回有上限、经过汇总的结果列表的搜索工具。如果你的搜索返回超过 50 条匹配，工具会抑制输出并告知 agent 缩小查询范围。

这个设计决策回头看来几乎简单得令人发笑，却是整篇论文中杠杆效益最高的改变之一。它将一个上下文淹没的失败模式，转化为一个自然的精炼循环。

第二部分： SWE-Agent 论文与 ACI 的诞生

 Agent-计算机接口究竟是什么

 ACI 在 SWE-agent 论文中被定义为位于语言模型 agent 与计算机环境之间的一个抽象层。与人机接口（ HCI）的类比是有意为之的。正如 HCI 研究追问如何设计契合人类认知架构的接口， ACI 研究追问如何设计契合语言模型认知架构的接口。

人类认知架构涉及视觉模式识别、空间记忆、跨屏幕的并行注意力，以及略读和选择性聚焦的能力。

语言模型的认知架构根本不同 ——它涉及顺序 token 处理、对上下文顺序和格式的敏感性、有限的工作记忆，以及倾向于锚定在提示词中最突出信息的特性。设计一个好的 ACI，意味着理解这些约束并围绕它们构建，而非与之对抗。

 SWE-agent面向编程任务的 ACI 有四个主要组件，每一个都反映了对语言模型在获得原始计算机访问权限时如何失败的特定洞察。

搜索与导航

搜索组件用专门构建的工具取代了标准的 grep 和 find 命令： find_file、 search_file和 search_dir。关键差异不在于语法，而在于输出管理。结果上限为 50 条。

如果查询超出该限制，工具会返回一条说明结果过多的消息，并提示 agent 精炼其搜索。这听起来微不足道，实际上却是论文中最具影响力的决策之一。

它之所以重要，是因为 agent 与认知负荷下的人类一样，在感到不确定时往往会延续既有行为。当一个人在大型代码库中迷失时，会越搜越广，产生越来越多的噪声。带上限的搜索工具通过创造一个强制函数打断了这个模式：你无法靠模糊来推进，你必须精确。这推动 agent 朝着更审慎、更有针对性的行为方向发展。

文件查看器

文件查看器是论文对认知架构洞察最为具体的体现。研究人员测试了多种查看器配置，发现每次显示 100 行是一个恰到好处的数字。行数更少（他们测试了 30 行）会导致 agent 失去对周边代码的上下文，从而出现编辑错误；行数更多（或显示完整文件）会导致 agent 迷失方向，遗漏重要细节。

查看器是有状态的，在多次交互之间保持文件中的位置。更重要的是，它在每一个可见行前面加上了明确的行号。这最后一个细节看似纯属表面，实则不然。

当 agent 需要发出一条针对第 47 至 52 行的编辑命令时，它需要能够直接从视图中读取这些数字，而不是数行数或做算术。将这个认知任务从 agent 的工作记忆中移除，为真正的问题求解释放了认知容量。

带 Linting 的文件编辑器

文件编辑器的核心创新是带护栏的即时反馈。 edit 命令接受起始行、结束行和替换文本作为单次操作。每次编辑后，工具会自动对修改后的文件运行 linter 并报告结果。如果编辑引入了语法错误，该编辑在应用之前就会被拒绝， agent会收到一条清晰的错误消息，同时显示原始代码和失败的编辑内容。

这封闭了在朴素 agent 实现中导致级联失败的反馈回路。没有 linter 时， agent 可能引入一个语法错误，运行测试套件，看到一个看似不相关的失败（因为真正的错误在别处），花费多个步骤追逐错误的问题，最终耗尽上下文窗口追踪一个幽灵。

将 linter 直接集成到编辑器中，语法错误就能在引入的那一刻被捕获，修复被本地化，问题无法传播。

对比使用原始 bash 工具时的情况：使用 sed 或输出重定向，没有集成反馈，编辑静默执行，多行修改需要极易出错的复杂参数格式化。 Agent 可能成功运行了命令，却引入了 linter 本可捕获的细微格式错误，然后花接下来的十个步骤纳闷测试为何失败。

上下文管理

第四个组件解决了一个在长会话中不断累积的问题：过时上下文的堆积。随着 agent 推进任务，其历史记录充满了旧的观察、中间状态以及不再反映当前环境状态的探索步骤。

所有这些历史记录占用上下文窗口的空间，并可能通过提供过时信息而主动误导 agent。

 ACI 的上下文管理系统将较早的观察记录 ——最后五轮之前的内容 ——压缩为单行摘要。这使活跃上下文聚焦于近期的相关信息，同时保留了整体轨迹的压缩记录。

 Agent 随时能看到自己最近做了什么、当前状态是什么，而不会被自己曾经运行过的每一条命令的完整未压缩历史所淹没。

基准测试结果及其真正含义

 SWE-agent 论文在 SWE-bench 数据集上对其 ACI 进行了基准测试，该数据集收录了来自热门 Python 代码库的真实 GitHub Issue。任务是接收一份自然语言的 bug 报告，并产出一个解决它的代码补丁。这是一项困难的实际任务，需要在陌生的代码库中导航、理解错误消息、编写正确的代码并验证修复效果。

使用 GPT-4 配合标准 bash shell 接口，系统解决了 3.97% 的问题；使用 GPT-4 配合专门构建的 ACI，系统解决了 12.47% 的问题。这就是前文提到的 64% 相对提升，完全来自接口设计。

研究人员还进行了消融研究，每次移除一个组件，以隔离每项设计决策的贡献。 Linter 集成始终是杠杆效益最高的组件之一；带上限的搜索对于防止上下文淹没至关重要；带行号的有状态文件查看器显著优于原始 cat 命令和更简单的查看器设计。

性能差异与模型智能无关，而与认知负荷管理有关。 ACI 减少了模型追踪状态所需的工作量，为真正重要的工作腾出了空间。

这些启示远远超出了编程 agent 的范畴。任何长期 agent 任务都涉及相同的根本挑战：在大型信息空间中导航、在多个步骤中保持连贯的状态、捕获错误并从中恢复，以及管理上下文窗口注意力这一有限资源。 ACI 的设计原则是可泛化的，具体工具会变，底层问题的架构不会变。

第三部分： Anthropic 的 Harness 工程（长期运行的 Agent 问题）

为什么上下文窗口边界是核心难题

 SWE-agent 论文解决的是如何为单个 agent 会话设计接口的问题。 Anthropic 的工程团队在开发 Claude Agent SDK 和 Claude Code 的过程中，遭遇了一个不同的问题：如果一项任务过于庞大，无法在单个上下文窗口内完成，该怎么办？

这不是小众的边缘情况。大多数真实的软件项目都太大，无法装进任何上下文窗口。一个生产级 Web 应用包含数百个文件、数千个函数、测试套件、配置、文档和依赖项。

即便拥有 20 万 token 的上下文窗口，你也无法同时将完整项目装进脑海。人类工程师通过外部记忆、文档、版本控制，以及数周乃至数月在代码库中积累的理解来解决这个问题。而一个开启全新会话的 agent，什么都没有。

朴素的解决方案是压缩（ compaction），它在一定程度上有效。 Claude Agent SDK 内置了压缩能力，能够在窗口填满时对旧上下文进行摘要。但仅靠压缩是不够的。

 Anthropic 的内部实验表明，即使有压缩机制，像 Opus 4.5 这样的前沿编程模型在跨多个上下文窗口循环运行时，也会持续失败，无法仅凭高层提示词构建出生产级质量的 Web 应用。

失败呈现出两种模式，两者都颇具启发意义。

第一种失败模式是试图一次性完成太多。当给定"构建一个 claude.ai