你用的 Claude Code 和 Codex，差距不在模型，在 Harness

Table of Contents

🤖 AI 摘要你的 Agent 表现不好，可能真不是模型的问题。LangChain 只换了模型外围的架构，TerminalBench 排名就从 30 开外冲到第 5。这篇文章把包裹在 LLM 之外的完整工程体系拆成了 12 个可操作的组件，是今年以来在 Agent 工程领域最有框架感的文章之一。

🔑 核心要点 1、Harness 是 Agent 的操作系统 2、生产级 Harness 有 12 个核心组件 3、上下文管理是最容易翻车的地方 4、模型越强，Harness 应该越薄

来源：Akshay (@akshay_pachaar)《The Anatomy of an Agent Harness》，2026-04-06

同一个模型，两种命运

你可能已经用 Claude Code 写过不少代码，或者让 Codex 帮你重构过一个项目。但有没有想过一个问题：为什么同样一个模型，在你的系统里表现平平，在别人手里却能完成复杂的长链路任务？

答案可能出乎意料——不在模型本身，而在模型外面那层东西。

LangChain 最近做了一个实验，非常能说明问题。他们没有换模型，没有调参数，仅仅是重新设计了包裹在 LLM 外面的底层架构。结果呢？系统在 TerminalBench 2.0（一个衡量 Agent 命令行任务能力的权威基准测试）上的排名，从 30 名开外直接冲到了第 5 名。

另一项研究更激进：让 LLM 自己去优化这套架构，最终实现了 76.4% 的通过率，甚至超过了人类精心设计的系统。

这说明什么？模型是发动机，但决定车好不好开的，是底盘和变速箱。

这套"底盘和变速箱"，现在有了一个正式的名字：Agent Harness。

🤖 AI 摘要你的 Agent 表现不好，可能真不是模型的问题。LangChain 只换了模型外围的架构，TerminalBench 排名就从 30 开外冲到第 5。这篇文章把包裹在 LLM 之外的完整工程体系拆成了 12 个可操作的组件，是今年以来在 Agent 工程领域最有框架感的文章之一。

🔑 核心要点 1、Harness 是 Agent 的操作系统 2、生产级 Harness 有 12 个核心组件 3、上下文管理是最容易翻车的地方 4、模型越强，Harness 应该越薄

来源：Akshay (@akshay_pachaar)《The Anatomy of an Agent Harness》，2026-04-06

同一个模型，两种命运

答案可能出乎意料——不在模型本身，而在模型外面那层东西。

另一项研究更激进：让 LLM 自己去优化这套架构，最终实现了 76.4% 的通过率，甚至超过了人类精心设计的系统。

这说明什么？模型是发动机，但决定车好不好开的，是底盘和变速箱。

这套"底盘和变速箱"，现在有了一个正式的名字：Agent Harness。

Harness 到底是什么

如果你不是模型本身，那你就是 Harness。

这是 LangChain 的 Vivek Trivedy 给出的定义，简洁到令人拍案。一个更形象的类比来自 Beren Millidge 2023 年的博文：原生的 LLM 就像一颗裸 CPU——没有内存、没有硬盘、没有输入输出设备。而 Harness，就是给这颗 CPU 装上的操作系统。

具体来说，Harness 包含了编排循环、工具系统、记忆管理、上下文管理、状态持久化、错误处理和安全护栏等一整套软件架构。Claude Code 的官方文档甚至直截了当地说：他们的 SDK 就是"驱动 Claude Code 的 Agent Harness"。OpenAI 的 Codex 团队也用了同样的说法。

这里有一个容易混淆的区别需要厘清：Agent 是用户看到的行为，Harness 是产生这些行为的机器。当有人说"我开发了一个 Agent"，他的真实意思是"我开发了一套 Harness，并把它接入了模型"。

说实话，这个区分在过去一年的行业讨论中一直非常模糊。太多人把"接了个 API 调了几次工具"就称为 Agent 开发了，好像给模型套个壳就万事大吉。这篇文章的价值，恰恰在于把这种模糊给捅破了。

工程化的三个同心圆

围绕 LLM，工程化可以分为三个层次，由内到外：

提示词工程（Prompt Engineering）——精心设计模型接收到的指令。这是最内层，也是最被广泛讨论的——可能也是被过度讨论的。

上下文工程（Context Engineering）——管理模型在什么时间点能看到什么内容。这是中间层，也是很多团队忽视的。上下文放什么、不放什么、什么时候放、放多少——这些决策的质量，直接决定了模型输出的质量。

Harness 工程（Harness Engineering）——涵盖上述两者，再加上工具编排、状态持久化、错误恢复、验证循环、安全执行和生命周期管理。这是最外层，也是最硬核的。

注意，Harness 不是 AI Wrapper。Wrapper 只是套了个壳，Harness 是一套让 Agent 能自主行动的完整系统。如果你做的只是一个"对话 + 工具调用"的 Demo，那是 Wrapper；只有当你的系统能处理错误、管理状态、自我验证、安全降级，才算得上 Harness。

12 个核心组件

综合 Anthropic、OpenAI、LangChain 以及一线从业者的经验，一个生产级的 Agent Harness 由 12 个组件构成。我们逐一拆解。

编排循环：心脏

这是整个系统的动力源。它实现的是"思考→行动→观察"（TAO）循环，技术上通常就是一个 while 循环。但难点不在循环本身，而在于循环需要处理的各种状态和逻辑。

Anthropic 把他们的运行时描述为一个"笨循环"——所有的智慧都在模型里，Harness 只负责管理回合的切换。这个设计哲学很值得玩味：不要让 Harness 聪明到抢模型的活。 过度设计编排逻辑，反而会限制模型的能力发挥。

工具：双手

工具是 Agent 接触外部世界的唯一途径。Claude Code 提供六大类工具：文件操作、搜索、执行、网页访问、代码分析和子 Agent 创建。OpenAI 的 Agents SDK 则支持函数工具、托管工具和 MCP 服务器工具。

一个关键设计原则：工具不是越多越好。暴露当前步骤所需的最小工具集，往往效果最佳。工具太多会稀释模型的注意力，增加选错工具的概率。这个道理很简单，但很多团队在实践中仍然倾向于"全给上"，生怕模型找不到趁手的。

记忆：时间维度

记忆分为短期和长期。短期记忆是单次会话的对话历史；长期记忆则跨会话持久存在。

Claude Code 的三层记忆架构很值得借鉴：一个轻量级索引（始终加载）、按需调用的详细主题文件、以及仅通过搜索访问的原始对话记录。一个核心设计原则是：Agent 把自己的记忆视为一种"提示"，在行动前必须根据实际状态验证。

换句话说，记忆不是档案，而是需要校验的线索。这跟人类记忆的运作方式很像——你以为自己记得某件事，但真正行动前最好再确认一下。

上下文管理：最容易翻车的地方

这可能是整篇文章中最重要的一节，也是我认为大多数 Agent 系统翻车的根本原因。

核心问题叫上下文腐烂：当关键信息处于上下文窗口的中间位置时，模型表现会下降 30% 以上。这是斯坦福大学发现的"迷失在中间"现象。即便是百万级 Token 的窗口，随着上下文增长，指令遵循能力也会退化。

很多人有个误区：窗口大了，就不需要管理上下文了。错。窗口大了只是意味着你能塞更多东西进去，但不代表塞进去的东西模型都能用好。信号被噪音淹没的概率，反而更高了。

生产环境的应对策略有四种：

压缩：在接近限制时总结对话历史。Claude Code 会保留架构决策和未修复的 Bug，丢弃冗余的工具输出。
观察掩码：隐藏旧的工具输出，但保留工具调用的记录。这样模型知道"做过这件事"，但不会被海量输出淹没。
即时检索：只保留轻量级标识符，动态加载数据。Claude Code 倾向于用 grep 或 head 命令，而不是加载整个文件。
子 Agent 委托：让每个子 Agent 深度探索，但只返回 1000 到 2000 Token 的浓缩摘要。

Anthropic 的上下文工程指南总结得很好：目标是找到能最大化达成目标概率的、信号最强的最小 Token 集合。这句话值得贴在每位 Agent 开发者的工位上。

提示词构建：组装线

这决定了模型在每一步具体能看到什么。它是层级化的：系统提示词、工具定义、记忆文件、对话历史，以及当前的用户消息。

OpenAI 的 Codex 使用严格的优先级栈：服务器控制的系统消息（最高优先级）、工具定义、开发者指令、用户指令，最后才是对话历史。这种分层设计确保了关键指令不会被冗长的对话历史冲淡。

输出解析：翻译官

现代 Harness 依赖原生工具调用——模型返回结构化的 tool_calls 对象，而不是需要费力解析的自由文本。Harness 检查是否有工具调用：有就执行并继续循环，没有就输出最终答案。

这里有个细节值得一提：早期很多 Agent 系统喜欢用正则表达式从自由文本中提取工具调用，这种方式脆弱且容易出错。原生工具调用标准化之后，这层解析的复杂度大幅降低了。

状态管理：存档点

LangGraph 用类型化字典模拟状态，在关键步骤进行"存档"，中断后可以恢复，甚至支持"时间旅行"式调试。Claude Code 采用了另一种思路：Git 提交作为存档点，进度文件作为结构化的草稿纸。

我个人更欣赏 Claude Code 的做法。Git 是每个开发者都熟悉的工具，用 Git 提交作为状态存档，不需要引入额外的状态管理系统。而且 Git 本身就提供了版本历史、分支管理和回滚能力——这些正好是 Agent 长任务所需要的。

错误处理：防线

一个包含 10 个步骤的流程，即使每步成功率高达 99%，全流程的成功率也只有约 90.4%。错误是会滚雪球的。

如果每步成功率降到 95%，10 步之后只剩 59.9%。如果你的 Agent 需要执行 50 步呢？95% 的单步成功率意味着全流程成功率为 7.7%。这不是数学题，这是生产事故。

LangGraph 把错误分成四类：临时性的（带延迟重试）、模型可恢复的（把错误返回给模型，让它自己调整）、用户可修复的（暂停等人类介入）、以及意外错误（上报调试）。这个分类很实用，值得直接借鉴。

护栏与安全：守门人

OpenAI 的 SDK 实现了三层护栏：输入护栏（Agent 运行前检查）、输出护栏（检查最终结果）和工具护栏（每次调用工具前检查）。Anthropic 的做法更彻底：权限执行与模型推理分离。模型决定想做什么，Harness 决定允许做什么。

这个分离至关重要。它意味着无论模型多"聪明"，都不能绕过安全边界。前段时间 Cursor Agent 在 10 秒内删掉 PocketOS 生产数据库的事件，本质上就是一个护栏缺失的典型案例——Agent 有权执行毁灭性操作，且没有任何确认机制。

验证循环：分水岭

这是区分"玩具 Demo"和"生产级 Agent"的关键，我认为也是最被低估的一个组件。

Anthropic 推荐三种验证方式：基于规则的反馈（测试、代码检查）、视觉反馈（通过 Playwright 截取 UI 截图）、以及 LLM-as-judge（用另一个子 Agent 评估输出）。

Claude Code 的创造者 Boris Cherny 指出，让模型能验证自己的工作，产出质量可以提升 2 到 3 倍。这不是小数，这是质的飞跃。想想看：一个不能验证自己工作的 Agent，就像一个从不自测的程序员——你敢把他的代码直接上生产吗？

子 Agent 编排：分身术

Claude Code 支持三种子 Agent 模式：克隆（复制父级上下文）、队友（通过文件邮箱通信的独立窗口）和工作树（独立 Git 分支）。OpenAI 则支持将 Agent 作为工具调用，或直接移交控制权。

子 Agent 的核心价值不在于"并行"，而在于上下文隔离。每个子 Agent 有自己的上下文窗口，不会污染主 Agent 的判断。这在处理复杂任务时尤其关键——你不会希望一个子任务产生的 5000 行日志把主任务的指令冲掉。

主流框架：同一套骨架，不同的味道

了解了组件，再来看看业界主流框架是怎么组装它们的：

Anthropic（Claude Agent SDK）——极简主义路线。通过一个简单的 query() 函数暴露 Harness，运行时就是一个"笨循环"。所有智慧在模型里，Harness 只管回合切换。这种设计相信模型的能力，也意味着对模型质量的依赖最高。

OpenAI（Agents SDK）——“代码优先"策略。工作流逻辑直接用 Python 表达，而不是复杂的图形语言。好处是开发者可以用熟悉的编程模式来控制 Agent 行为，坏处是容易把 Harness 写得过于复杂，反而限制了模型的发挥空间。

LangGraph——将 Harness 建模为显式的状态图，强调对流程的精细控制。适合需要复杂分支和条件逻辑的场景，但学习曲线较陡。

CrewAI——基于角色的多 Agent 协作，由"流程层"管理确定性的骨干逻辑。适合多人协作场景，但角色定义的粒度很考验设计能力。

AutoGen——微软出品，支持多种编排模式：顺序执行、群聊、移交和动态任务管理。功能全面，但配置复杂度也最高。

有意思的是，这些框架表面上看差异很大，但拆到底层，12 个核心组件都在那里。区别只在于：谁做得多、谁做得少、谁交给模型、谁自己扛。

7 个关键设计决策

每个 Harness 的架构师都面临 7 个核心选择，这些选择的组合决定了系统的性格：

1、单 Agent 还是多 Agent

官方建议是：先充分挖掘单 Agent 的潜力。多 Agent 会带来额外的开销和信息损耗。很多时候你觉得"需要多个 Agent”，其实只是单 Agent 的上下文管理没做好。

2、ReAct 还是先规划后执行

ReAct（每步都推理+行动）灵活但成本高，因为每一步都要调模型。“先规划后执行"速度更快——模型先想好整体方案，然后按计划执行。复杂任务适合前者，确定性任务适合后者。

3、上下文管理策略

是总结对话历史，还是动态加载？是全部保留，还是选择性遗忘？这个选择直接影响系统的记忆质量和 Token 成本。

4、验证循环设计

用硬性的代码测试？还是用另一个 LLM 来打分？前者可靠但覆盖面窄，后者灵活但可能引入新的不确定性。

5、权限与安全架构

追求速度自动批准，还是追求安全步步确认？在开发环境和生产环境中，这个天平应该倾斜到完全不同的方向。

6、工具范围管理

工具越多，模型越容易选错。暴露当前步骤所需的最小工具集，往往效果最佳。这个原则说起来简单，但在实际系统中落地需要精细的工具分类和动态加载机制。

7、Harness 的厚度

多少逻辑写死在系统里，多少逻辑留给模型发挥？这是最根本的架构选择。Harness 太厚，模型变成了执行器，能力被限制；Harness 太薄，模型自由度太高，容易跑偏。

我个人倾向于"中等厚度”——在安全、验证和状态管理等关键节点上设置硬约束，但在推理路径和工具选择上给模型足够的自由。毕竟，我们选 LLM 而不是规则引擎，就是看中了它的判断力。

脚手架的隐喻

文章最后用了一个精彩的比喻：Harness 就像建筑脚手架。

脚手架是临时性的基础设施，让工人能触及原本够不到的高度。脚手架本身不盖房子，但没有它，工人就上不去高层。关键在于：房子盖好后，脚手架是要拆除的。

随着模型能力提升，Harness 的复杂程度应该逐渐降低。这就是协同进化原则——现在的模型在训练时，就已经考虑了 Harness 的存在。如果你的 Harness 设计得好，当模型升级时，不需要增加复杂度，性能就会自动提升。

但 Harness 永远不会消失。即便最强大的模型，也需要系统来管理上下文窗口、执行代码、保存状态并验证工作。脚手架会变薄，但建筑永远需要脚手架。

为什么这篇文章重要

过去一年，Agent 生态经历了爆发式增长。Claude Code、Codex、Cursor、Windsurf——每个人都在用，但很少有人系统性地思考：为什么同样的模型，在不同产品里表现差异如此之大？

行业里充斥着两种极端声音：一种觉得"模型够强就行，工程不重要"，另一种觉得"模型不可靠，什么都要自己控"。这篇文章的价值在于，它给出了一个中间地带——模型和 Harness 是协同进化的关系，不是谁替代谁的关系。

更实际地说，这篇文章给了每个 Agent 开发者一张检查清单。你的编排循环健壮吗？上下文管理有策略吗？错误处理分了几类？验证循环做了吗？护栏到位吗？

如果你正在做 Agent 相关的产品或项目，这篇文章不是"值得一读"，而是"应该打印出来贴在墙上"。

下次当你的 Agent 表现不佳时，别光顾着抱怨模型——去检查一下你的 Harness。

参考来源：

原文：Akshay (@akshay_pachaar)《The Anatomy of an Agent Harness》，2026-04-06
中文翻译：宝玉 (baoyu.io)
相关研究：LangChain TerminalBench 2.0 排名提升、Stanford “Lost in the Middle” 现象