Harness Engineering工程化教程（非常详细），AI Agent复杂长任务从入门到精通，收藏这一篇就够了！

Views are my own.

“Yet Another Chapter”，Generated by Google Lyria

OpenAI 的一个团队在五个月内用 Codex 写了一百万行代码，三个工程师平均每天合并 3.5 个 PR，没有一行代码是工程师手写的。Anthropic 的 Claude Code 能连续工作数天构建完整应用。LangChain 的 Coding Agent 在 Terminal Bench 2.0 上从 52.8% 跃升至 66.5%，却只改了 harness，模型没动。

随着 Coding Agent 能力过去一段时间的突飞猛进，软件工程师的工作变了：从“写代码”变成了“设计让 AI 可靠工作的环境”。

这种设计能力，有个名字：Harness Engineering。

一、什么是 Harness Engineering?

Anthropic 在其官方文档中给出了它们的定义：

“An agent harness (or scaffold) is the system that enables a model to act as an agent: it processes inputs, orchestrates tool calls, and returns results.”

“Agent Harness（或称 scaffold）是让模型能够作为 Agent 工作的系统：它处理输入、编排工具调用、返回结果。”

——Anthropic, Demystifying evals for AI agents

Parallel AI 提供了更详细的定义：

Harnesses emerged as a way to formalize planning and guardrails so that the agent’s output is actually useful and correct. Especially for long-running agents, harnesses provide a way to maintain state and continuity.

Harness 的出现是为了形式化规划和护栏，使 Agent 的输出真正有用且正确。对于长时间运行的 Agent，Harness 提供了一种维护状态和连续性的方法。

用直白的话说：Harness 是设计一个系统，让 AI 能可靠地完成复杂任务。

从一个简单例子开始

假设要让 AI Agent 帮你重构一个 10 万行的代码库。

裸 Agent：把代码扔给 GPT 5.2 或者 Claude 4.6，说“帮我重构”
→ Agent 看了 1000 行就开始瞎改，3 小时后代码库崩了

有 Harness:

1. 先给 Agent 注入架构文档
2. 限制每次只能改一个模块
3. 强制改完后必须跑测试
4. 检测到失败时自动回滚

→ Agent 花了 2 天，成功重构了 80% 的代码

Harness Engineering 的作用是：设计一个环境，让 AI 能可靠地完成复杂工作。

核心维度

常见的误区是把 harness 当作“给 LLM 接工具的胶水层”，但实际的 Harness Engineering 包含三个核心维度：

Context Engineering：提供充分的结构化上下文

• 不是把所有信息扔给 Agent，而是给它一个“地图”
• OpenAI 的 AGENTS.md 只有 100 行，但它指向完整的知识库

Tool Engineering：设计受控的高效工具

• 不是让 Agent 直接操作数据库，而是提供封装好的、带约束的 API
• Hightouch 的 Agent 不能执行任意 SQL，只能调用预定义的查询函数

Workflow Engineering：构建信任的验证循环

• 不是让 Agent 自己判断“做完了”，而是用外部标准验证
• LangChain 的 middleware 强制 Agent 在退出前跑测试

解决的核心问题是：如何让 LLM 在长时间、多步骤的复杂任务中保持一致性和可靠性。

二、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应用最关键的问题是如何让概率性系统在生产环境中可靠运行，这是一个独立于大模型能力的系统工程问题。

学AI大模型的正确顺序，千万不要搞错了

🤔2026年AI风口已来！各行各业的AI渗透肉眼可见，超多公司要么转型做AI相关产品，要么高薪挖AI技术人才，机遇直接摆在眼前！

有往AI方向发展，或者本身有后端编程基础的朋友，直接冲AI大模型应用开发转岗超合适！

就算暂时不打算转岗，了解大模型、RAG、Prompt、Agent这些热门概念，能上手做简单项目，也绝对是求职加分王🔋

📝给大家整理了超全最新的AI大模型应用开发学习清单和资料，手把手帮你快速入门！👇👇

学习路线:

✅大模型基础认知—大模型核心原理、发展历程、主流模型（GPT、文心一言等）特点解析
✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑
✅开发基础能力—Python进阶、API接口调用、大模型开发框架（LangChain等）实操
✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用
✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代
✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经

以上6大模块，看似清晰好上手，实则每个部分都有扎实的核心内容需要吃透！

我把大模型的学习全流程已经整理📚好了！抓住AI时代风口，轻松解锁职业新可能，希望大家都能把握机遇，实现薪资/职业跃迁～

这份完整版的大模型 AI 学习资料已经上传ZEEKLOG，朋友们如果需要可以微信扫描下方ZEEKLOG官方认证二维码免费领取【保证100%免费】