Harness Engineering：AI Agent复杂长任务的工程秘方

Harness Engineering：AI Agent复杂长任务的工程秘方 Harness Engineering：AI Agent复杂长任务的工程秘方 Modified February 27 No access 0b2eqmbeoaacw4agudu2uvuvfa6di6bqerya.f10002 00:00 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的价值不在于“服务器更快”，而在于“让基础设施可管理、可扩展、可靠”。 No access 0b2eqmbeoaacw4agudu2uvuvfa6di6bqerya.f10002 00:00 No access 0b2eqmbeoaacw4agudu2uvuvfa6di6bqerya.f10002 00:00 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 与人类工作流程、合规要求、安全边界集成”