Harness Engineering 工程化教程：AI Agent 复杂长任务设计指南

二、Harness Engineering 为什么会出现？

Agent 的核心挑战

当我们说'AI Agent 能自主完成复杂任务'时，隐含了一个假设：Agent 能够在长时间、多步骤的复杂任务中保持一致性。

但这个假设与 LLM 的特征存在冲突：

LLM 是无状态的：每次推理都是独立的函数调用，f(context) → output
复杂工作是有状态的：需要记住'我做了什么'、'为什么这么做'、'下一步该做什么'

LLM 的模式是 next token prediction：给定 context，预测下一个 token。这个模式本身就是无状态的。但 Agent 需要完成的是 task completion：记住目标，规划步骤，执行，验证，直到完成。这是有状态的工作。

Anthropic 用一个比喻描述了这个挑战：这就像一个软件项目由工程师轮班完成，每个新工程师到来时都不记得上一班发生了什么。

Harness 在无状态的 LLM 和有状态的任务之间搭建桥梁，类似于操作系统让无状态的 CPU 运行有状态的程序。

Context 的动态性挑战

在 Agent 已成为主流应用形态的今天，业界开始意识到：Agent 的主要挑战已经从'能不能跑'转移到'能不能持续可靠地跑'。

LangChain 的 Harrison Chase 在最近的 Sequoia Training Data 访谈中给出了一个直白的洞察：

'Everything's context engineering.'

理解这句话的背后，可以想你这样一种情况：当 Agent 需要执行第 14 步操作时，它的 context 取决于前 13 步的任意组合。你无法预测它会看到什么，也无法保证它记得什么。

这与传统软件有本质区别。

传统软件的状态是确定性的：给定相同的输入和初始状态，你总能得到相同的输出。但 Agent 的 context 是动态构建的：

• 第 1 步可能调用了工具 A，返回了 100 行数据
• 第 7 步可能基于这些数据做了决策，但只保留了摘要
• 第 14 步的 context 中，可能只剩下'工具 A 返回了客户列表'这样的描述

Agent 在第 14 步'看到'的世界，是前 13 步的任意组合动态构建出来的。这就是为什么 context engineering 成为 Agent 系统的核心挑战。

这个挑战在生产环境中体现为三个具体瓶颈：

瓶颈 1：从'单步智能'到'长时程可靠性'的 机制 Gap

各种眼花缭乱 Benchmark 刷榜制造了一个幻觉：模型在单轮任务上的准确率已经很高（>85%），但这无法预测它在第 50 步、第 100 步之后的表现。

'A 1% difference on a leaderboard cannot detect the reliability if a model drifts off-track after fifty steps.'

'排行榜上 1% 的差异无法检测出模型在第 50 步之后是否会偏离轨道的可靠性。'

– Philipp Schmid

Durability（持久可靠性）是一个独立于 Capability（单步能力）的维度。一个在 MMLU 上得 90 分的模型，可能在执行 100 步的工作流时完全跑偏。

Anthropic 在构建 Claude Code 时，发现了两个典型的失败模式：

1. 'All-or-nothing' 模式：Agent 试图一次性完成所有功能，导致 context 耗尽，下一个 session 接手时发现代码写了一半、没有文档、无法继续
2. '过早胜利' 模式：Agent 看到一点进展就宣布任务完成，实际上核心功能还没实现

这两个失败模式的共同点是：Agent 缺乏'我在做什么'的持续认知。它在每个时刻都很聪明，但时间一长后就失去方向，不知道自己应该做什么了。

Feature List、Progress Notes、Git Commits 等机制给 Agent 提供'记忆的外部化存储'，让长时程任务（Long-horizon Tasks）成为可能。

瓶颈 2：Context 爆炸与 Attention 机制的限制

现在的 Agent 应用动辄需要处理 10 万+ token 的 context。但百万级别的 context window 扩大并没有解决根本问题。'Lost in the middle' 现象是 Transformer 架构 attention 机制的数学特性。

这导致了一个常见的使用困扰：把 100 页文档全部塞进 context，效果还不如给 Agent 一个 100 行的'地图'，让它按需检索。

OpenAI 的 Codex 团队在构建 100 万行代码的 Agent 维护系统时，核心策略就是'渐进式披露'：

• 不是把整个 codebase 塞进 context
• 而是给 Agent 一个 AGENTS.md（100 行），作为稳定的入口点
• Agent 从这个地图出发，通过工具调用按需检索详细内容

为什么这样更有效？因为每次检索的内容都在 attention 的有效范围内，而不是被埋在中间 60% 的 attention sink 里。

'Context engineering is not about compression, it's about architecture.'

'Context 工程的核心不是压缩，而是架构设计。'

– Harrison Chase, LangChain

文件系统、compaction、动态子 Agent 等机制把'信息检索'从 Agent 的负担变成系统的能力，让 Agent 只看到它需要的信息。

瓶颈 3：从'能跑'到'可维护'的工程化 Gap

OpenAI 的 Codex 团队用 5 个月构建了一个 100 万行代码的应用，完全由 AI 生成和维护。但他们遇到的最大挑战不是'让 AI 写代码'，而是'让 AI 写的代码可维护'。

他们的核心发现是：

'Our most difficult challenges now center on designing environments, feedback loops, and control systems.'

'我们现在面临的最大挑战集中在设计环境、反馈循环和控制系统上。'

– OpenAI Codex Team

生产系统的可靠性要求，远超 benchmark 的评估标准。

Terminal Bench 2.0 的数据也提供了佐证：

• GPT-5.2-Codex 在不同 harness 配置下的分数从 52.8% 到 66.5%（26% 的相对提升）
• 模型从 GPT-5.2-Codex 升级到 GPT-5.3-Codex，在 SWE-Bench Pro 上只提升了 0.7%（56.4% → 56.8%）

这说明：当模型能力达到一定水平后，系统设计成为效果的主要瓶颈。

LangChain 的实验也证实了这一点：他们的 deepagents-cli 在 Terminal Bench 2.0 上从 52.8% 提升到 66.5%，13.7 个百分点的提升。关键是：只改了 harness，模型固定在 GPT-5.2-Codex。

使用更大的模型已经不是性能优化的主要路径。Harness 的设计，才是决定 Agent 能否在生产环境中可靠工作的最关键因素。

可验证性：Harness 的核心价值

业界主流的 Harness Engineering 实践，都指向了同一个技术原则：

'The ability to improve a system is proportional to how easily you can verify its output.'

—— Jason Wei

如果你无法验证 Agent 在第 50 步做了什么、为什么做、做得对不对，你就无法优化它。

• Anthropic 通过 feature list（200+ 个明确的 pass/fail 标准）+ git commits，让每一步的进展都可验证
• LangChain 通过 middleware 强制验证循环，让 Agent 无法跳过测试就宣布完成
• OpenAI 通过 custom linters + structural tests，让架构约束变成可自动检查的规则

Harness Engineering 把'vague multi-step workflows'变成'structured data that we can log and grade'。这让 Agent 系统从'黑盒'变成'可观测、可调试、可优化'的工程系统。

三、如何做 Harness Engineering?

Harness Engineering 没有'标准答案'。每个团队都在从零开始构建，根据自己的瓶颈设计解决方案。

但从业界的实践中，可以提炼出一些有代表性的方法。

• OpenAI: 信息量超出 context window → 如何让 Agent 按需检索？
• Anthropic: 任务跨多个会话 → 如何让 Agent 记住'我在做什么'？
• LangChain: Agent 不会自我验证 → 如何强制验证循环？
• Hightouch: 任务太复杂 → 如何分解和隔离子任务？

这是四种实践，覆盖了大部分生产场景的核心瓶颈。实际项目中，你的瓶颈可能是多个，需要组合多种方法。

理性的做法是：先诊断瓶颈，再选择方案。

案例 1：OpenAI 的渐进式披露 - 解决信息量超出 context window

主要挑战

OpenAI 的 Codex 团队完成 100 万行无人工参与的代码项目时遇到的问题：Agent 需要理解 100 万行代码，但 context window 只能装下约 20 万 tokens。

传统方案是'压缩'（summarization、RAG），但压缩会丢失结构，Agent 不知道信息之间的关系。

解决思路

OpenAI 的核心洞察：不要压缩信息，而要构建'地图'。

以前的常见做法是把 100 万行代码压缩成 10 万行摘要，更好的方案是给 Agent 一个 100 行的 AGENTS.md（地图），让它按需检索。关键是：把'信息检索'从 Agent 的负担变成系统的能力。Manus、Claude Code 等在上下文管理方面也有很多非常有效的实战经验。

具体方法

OpenAI 的'渐进式披露'包含四个关键实践：

1. 知识库作为目录：AGENTS.md（100 行）作为稳定入口点，指向编目的设计文档和架构地图，Agent 按需检索
2. 为 Agent 优化代码库：所有关键信息必须在代码库内可检索，偏好'无聊'的技术，因为更容易建模。
3. 强制约束条件而非具体实现：要求 Codex 在边界解析数据，但不规定如何实现。约束的目的是防止架构漂移，而非限制实现方式
4. 自动偏差修复：后台任务定期扫描偏差，打开重构 PR。人类品味被捕获一次，然后持续执行

为什么有效？

给 Agent 一个 100 行的地图 + 按需检索，每次检索的内容都在高 attention 区域（前 20% 和后 20%），而不是被埋在'注意力黑洞'里。OpenAI 用系统架构的改进尝试补偿 Transformer 的 attention 衰减。

案例 2: Anthropic 的 Initializer + Coding Agent - 解决跨会话状态丢失

主要挑战

Anthropic 让 Claude 连续工作数天构建完整 Web 应用。核心问题是：Agent 必须在多个会话中工作，每个新会话开始时都'失忆'。

这导致'All-or-nothing'和'过早胜利'的两种失败模式。主要原因：LLM 是无状态的，但复杂工作是有状态的。

解决思路

既然 Agent 无法'记住'，就让它每次启动时都能'读取记录'。

不是期望 Agent '记住'上次做了什么，而是让它每次启动时读取：功能列表（200+ 个 pass/fail 标准）+ git commits（进展记录）+ progress notes（当前状态）。

把'记忆'从 Agent 的内部状态外化为可读取的文件系统。

具体方法

Anthropic 的'Initializer + Coding Agent'是两阶段系统：

阶段 1: Initializer Agent — 构建'记忆基础设施'：init.sh（环境初始化）、功能需求文件（200+ 个功能，全部标记'失败'）、claude-progress.txt（进度追踪）、初始 git 提交。

阶段 2: Coding Agent — 每个会话遵循严格流程：读取状态 → 做一件事（一次只处理一个功能）→ 验证（端到端测试）→ 记录状态（git commit + 更新 progress notes）。如果写错代码，下个会话用 git 回滚。

为什么有效？

这个方法把有状态任务分解为一系列无状态操作。每个 Coding Agent 会话转换成了纯函数：

 f(功能列表 + git history + progress notes) → 完成一个功能 + 更新记录 

Agent 不需要'记住'，因为所有信息都在输入中。Anthropic 用'外部化状态管理'替代'内部记忆'，类似于操作系统让无状态的 CPU 运行有状态的程序。

案例 3：LangChain 的强制验证循环 - 解决 Agent 不会自我验证

主要挑战

LangChain 在 Terminal Bench 2.0 上用同一个模型（GPT-5.2-Codex），只改 harness，分数从 52.8% 提升到 66.5%，实现了 26% 的相对提升。

他们当时遇到的问题是：Agent 不会自然地验证自己的工作。比如，Agent 写了代码，重新阅读，确认'看起来没问题'，停止，但实际上代码根本跑不通。

为什么？这不是'模型不够聪明'，而是训练数据偏差：LLM 的训练数据主要是'写代码'（GitHub commits），而非'写代码 - 测试 - 修复'的完整循环。模型学会了'生成看起来正确的代码'，但没学会'验证代码是否真的正确'。

解决思路

不依赖 prompt 而是让 Agent 自己验证，用确定性机制强制验证循环。

不是在 prompt 里写'记得测试'，因为 Agent 可能会忽略，需要在 Agent 退出前用 middleware 拦截它，强制运行验证。

把'验证'从 Agent 的自主决策变成系统的强制流程。

具体方法

LangChain 的'强制验证循环'包含三个关键机制：

1. PreCompletionChecklistMiddleware：Agent 准备退出时拦截它，检查是否运行测试、测试是否通过，用代码逻辑强制执行。
2. LocalContextMiddleware：启动时自动映射工作目录、查找可用工具、注入环境信息。Agent 不会主动'探索环境'，Harness 负责准备和交付 context
3. LoopDetectionMiddleware：跟踪每个文件的编辑次数。编辑 N 次后添加上下文：'你已经编辑这个文件 5 次了，考虑重新考虑方法'。

为什么有效？

这个方法把'软约束'（prompt）变成'硬约束'（代码逻辑）。Prompt 的问题是 Agent 可能忽略，Middleware 用确定性逻辑保证验证循环，Agent 无法绕过。

LangChain 用'系统设计'补偿'训练数据偏差'，LLM 的训练数据主要是'写代码'（GitHub commits），而非'写代码 - 测试 - 修复'的完整循环。把验证从 Agent 的'学习任务'变成系统的'强制流程'。

案例 4：Hightouch 的动态子 Agent - 解决单个 Agent 处理不了的复杂任务

主要挑战

Hightouch 构建了一个通用营销 Agent，可以规划活动、分析数据、分析创意和文案。他们当时遇到的核心问题是：单个 Agent 的 context 装不下复杂任务的所有中间步骤。

典型场景：分析 1000 个客户的购买行为。Agent 需要查询 1000 次（每次 500 tokens），总共 50 万 tokens，远超 context window。强行压缩会丢失细节，只分析部分客户结论不可靠。

解决思路

Hightouch 的核心洞察：不要压缩 context，而要隔离 context。

主 Agent 不处理 1000 次查询的详细数据，而是生成 1000 个并行'子 Agent'，每个处理一个客户，生成摘要。主 Agent 只看 1000 个摘要（每个 50 tokens，共 5 万 tokens）。关键是：用'分层处理'替代'线性压缩'。

具体方法

Hightouch 的'动态子 Agent'包含四个关键机制：

1. 规划与执行分离（动态更新）：通过特殊工具调用（make_plan、execute_step_in_plan、update_plan），Agent 管理自己的思维过程，计划可根据新信息动态更新。
2. 文件缓冲：工具返回大量数据时，Agent 调用 write_file 缓冲到磁盘，context 中只保留指针（文件名 + 描述）。类似学生的'草稿纸'。
3. 动态子 Agent：主 Agent 识别复杂子任务，生成独立 LLM 线程（子 Agent）处理，子 Agent 完成后生成摘要，只有摘要返回主 Agent。
4. 扇出模式：对非结构化数据（如 1000 个客户评论），主 Agent 生成数百个并行调用到小模型（Haiku），每个处理一个评论，主 Agent 汇总结果。比 RAG 更便宜、更可靠

为什么有效？

传统方法的的瓶颈是，单个 Agent 的 context 固定，而压缩则会丢失细节。

Hightouch 的方法是：主 Agent 的 context 只存储'地图'（计划 + 摘要），详细信息在子 Agent 的独立 context 中，系统总'工作记忆'可远超单个 context window。这类似分布式系统的'分而治之'：水平扩展 context，局部处理后全局汇总。

用'分层抽象'替代'线性压缩'，因为压缩是有损的，但分层抽象可以无损。细节在子层，摘要在主层）。

如何选择适合你的方案？

如何让 LLM 在有限的 context window 内，完成超出 context window 的复杂任务？

上面的几种实践共同策略是：构建'信息检索 + 状态管理 + 验证循环'的系统。区别在于侧重点：

• OpenAI 的渐进式披露：重信息检索（AGENTS.md 地图 + 按需检索）
• Anthropic 的 Initializer + Coding Agent：重状态管理（git commits + progress notes）
• LangChain 的强制验证循环：重验证（middleware 强制测试）
• Hightouch 的动态子 Agent：三者都重，但用'隔离'而非'压缩'

怎么借鉴？先诊断瓶颈，再选择设计思路：

• 信息量超出 context window → 渐进式披露
• 任务跨多个会话 → 外部化状态管理
• Agent 不会自我验证 → 强制验证循环
• 任务太复杂 → 动态子 Agent

实际项目中的瓶颈可能是多个，需要组合多种设计思路。这并不是'产品组合'，而是可以在你自己的 harness engineering 中同时实现的设计原则。

四、未来会怎样？

Harness Engineering 目前处于'百花齐放'阶段，OpenAI、Anthropic、LangChain、Hightouch 等都在非常积极地各自探索不同方向。这些实践背后，有三个相对清晰的演化方向：

趋势 1: 模型与 Harness 的协同演化

通常的假设是：更强的模型 → 更简单的 Harness。但实际可能相反。

OpenAI 的 Codex 团队在五个月内构建了越来越复杂的 harness。LangChain 的 deepagents 自 2024 年 3 月以来被重新架构了五次。生产系统的要求远超 benchmark。

Harness 把'可靠性'从模型转移到系统层面。未来可能出现'Harness-optimized'的模型——不追求'通用智能'，而是'在 Harness 约束下的高效执行'。就像 RISC 架构：简化指令集，让编译器承担更多优化。

趋势 2: 从压缩到架构的转变

早期 context engineering 关注压缩技术（summarization、compaction、RAG）。但 OpenAI 和 Hightouch 的实践显示：问题不是'如何压缩'，而是'如何组织'。

为什么'地图式'比'百科全书式'更有效？因为 Transformer 的 attention 对中间 tokens 衰减。把 100 页文档全部塞进 context，模型对后 50 页的 attention 显著降低。给它一个 100 行的地图 + 按需检索，每次检索的内容都在高 attention 区域。

OpenAI 的 AGENTS.md 只有 100 行，但指向结构化知识库。Hightouch 的动态子 agent 隔离上下文。这是对 Transformer 架构特性的深刻理解。

未来的 harness 不会更简单，而会更结构化。就像 Kubernetes 不是让容器更简单，而是让容器可管理。

趋势 3: Harness 作为持久竞争优势

即使模型变得完美，harness 仍然重要。因为 harness 积累的是领域知识、工作流程模式、安全策略，这些不会因新模型发布而过时。

OpenAI 的 Codex App Server 提供的不仅是 agent loop，还有身份认证、模型发现、配置管理。Anthropic 的 harness 包括审批流程、权限控制。这些是系统集成问题。

Harness 不解决'模型不够聪明'的问题，它解决的是'如何让 AI 与人类工作流程、合规要求、安全边界集成'。即使模型完美，这些问题依然存在。

构建优秀 harness 的公司有持久护城河。就像 CSP 的价值不在于'服务器更快'，而在于'让基础设施可管理、可扩展、可靠'。

结语

为什么 OpenAI、Anthropic、LangChain 都在投入大量资源构建 Harness?

传统软件系统的核心是确定性：给定相同输入，总能得到相同输出。工程师通过测试、类型系统、静态分析，把所有可能的执行路径控制住。

但当执行层从 CPU 变成 LLM，系统变成了概率性的。Agent 在第 50 步会做什么，取决于前 49 步动态构建的 context。这种不确定性无法通过'写更好的代码'消除，因为它是 LLM 的本质特征。

Harness Engineering 尝试用工程的方法解决 AI 落地时的关键问题：如何让概率性系统可靠运行。它并不是消除不确定性，而是限制边界：

• OpenAI 用 AGENTS.md + 渐进式披露，把 Agent 可能看到的 context 限制在结构化的信息空间内
• Anthropic 用 feature list + git commits，把任务分解成 200+ 个可验证的小步骤
• LangChain 用强制验证循环，让 Agent 无法跳过测试就宣布完成
• Hightouch 用动态子 Agent，把执行路径隔离在独立的上下文中

这些设计的共同点：通过结构化、可验证性、隔离性，把概率性执行约束在可管理的范围内。

可以看出，Harness Engineering 的技术本质有点类似于操作系统：提供抽象层，让不可预测的硬件变成可管理的资源。Harness 让不可预测的 LLM 输出变成可管理的 Agent 行为。

未来即使更新更强的大模型持续发布，Harness 依然非常重要。因为行业场景 AI 应用最关键的问题是如何让概率性系统在生产环境中可靠运行，这是一个独立于大模型能力的系统工程问题。