Harness Engineering & 驾驭工程 & 智能体长时间运行机制系列 - 2

若天明

10人浏览 · 2026-03-31 12:22:03

若天明 · 2026-03-31 12:22:03 发布

The long-running agent problem 长时间运行智能体的问题

Claude是一款强大的通用智能体工具，擅长编码以及其他需要模型使用工具收集上下文、规划和执行的任务。它具备上下文管理功能，如上下文压缩/compaction，使智能体能够在不耗尽上下文窗口的情况下完成任务。理论上，在这种设置下，一个智能体应该可以持续进行有用的工作一段时间任意长的时间。但是实际上仅有上下文压缩远远不够。

典型失败模式

Anthropic 在做长时间运行 Agent 的过程中，总结了几个 Agent 常见的失败模式：

失败模式 1：试图一步到位（One-shotting）。
1. Agent 倾向于一次性做太多事情，这常常导致模型在实现过程中耗尽上下文，使下一个会话只能从一个半成品且未文档化的功能开始。
2. 下一个会话启动时看到的是半成品、没有文档的代码，只能花大量时间猜测之前发生了什么，并试图恢复工作状态。
3. 结果：中途上下文爆掉，下一个会话接不上，项目陷入失败。
失败模式 2：过早宣布任务完成。第二种失败模式通常出现在项目后期。在某些功能已经建立后，后续的智能体实例看到已有进展，便误判任务已经完成，从而放弃剩余特性，导致项目整体的失败。
失败模式 3：过早标记功能完成。在没有明确提示的情况下，Agent 写完代码就标记为“passing”，却没有做端到端测试。单元测试或 curl 命令通过了不代表功能真正可用。
失败模式 4：环境启动困难。
1. 每次新会话启动时，Agent 需要花费大量 token 弄清楚如何运行应用、如何启动开发服务器，而不是把时间花在实际开发上。
2. 即便做了记录 /摘要 /compaction，如果缺少结构化环境和进度管理，Agent 仍然会迷路而发生第一个模式下一个会话启动失败的情况。因为压缩并不能总是将清晰的指令完美传递给下一个智能体。

除此之外，还有三种额外的失败模式，随着长期任务的进行会加剧：

上下文内容过多Context rot：上下文窗口会显示工具输出、历史和先前推理。随着填充，模型失去了对原始说明的思考。即使有 20 万+个窗口，密集的中间上下文内容也会被忽略。
工具调用幻觉：没有验证，智能体会调用参数类型错误的函数或引用不存在的API。如果没有拦截器拦截调用，智能体会消耗token重试同一个无法使用的工具调用。
失败时失去状态：任何网络超时或服务器重启都会清除内存进度。下一次直接从零开始。

例如：上下文窗口的有效区间

Dex Horthy 有个很实用的经验观察：上下文填得越满，LLM输出质量越差。以 168K token 的上下文窗口为例，大约用到 40% 就开始走下坡路了：

Smart Zone（前约 40%）：聚焦、准确的推理。Agent 拥有相关、精炼的信息。
Dumb Zone（超过约 40%）：幻觉、循环、格式错误的工具调用、低质量代码。更多 token 反而损害性能。

给Agent塞大量MCP工具、冗长文档和累积的对话历史，不会让它聪明，反而会变笨

出现“You’re absolutely right” 是一个不好的迹象

===>

这提示 Anthropic 需要：

设置一个初始环境，为给定提示所要求的所有功能奠定基础，从而让智能体能够逐步、按功能分步工作。
提示每个智能体在朝着目标前进的同时，以干净状态结束会话，即适合合并到主分支的代码：没有重大错误，代码有序且文档齐全，总体而言，开发者可以轻松开始新功能，而无需先清理无关的混乱。

===>

引出一个更大的话题：Harness Engineering

The long-running agent problem 长时间运行智能体的问题

【When & Who】发展历程与演变

【Why】为什么 Harness Engineering 会在 2026 年突然变热？

【How】Harness 工程的应用与案例

【Anthropic的实践】：两步方案【环境搭建+增量开发】

【全栈网页应用开发】：案例 - 克隆claude.ai网页

【Initializer Agent】：搭建环境的初始化智能体

【关键组件1】init.sh：快速启动环境

【关键组件2】Claude-progress：进程日志

【关键组件3】Git 仓库：版本化的工程记忆

【关键组件4】Feature list ：功能列表

【Coding Agent】：多轮增量开发的编码智能体

【关键功能1】Getting up to speed：快速开发

【关键功能2】Incremental progress：渐进式开发

【关键功能3】Testing:测试

【When & Who】发展历程与演变

2025 年底已经有人零星提到过这个说法，但真正结晶成术语是 2026 年 2 月的事：

时间	来源	核心贡献	链接
2025.11.26	Anthropic	Justin Young发表长期运行 Agent 的 Harness 设计方法论	Effective harnesses for long-running agents
2026.02.05	Mitchell Hashimoto	首次明确命名了这一实践，提出核心理念	My AI Adoption Journey
2026.02.11	OpenAI	Ryan Lopopolo披露百万行代码实验，首次系统阐述 Harness 实践	Harness engineering: leveraging Codex in an agent-first world
2026.02.17	Martin Fowler	Birgitta Böckeler从软件工程视角深度分析 Harness 的未来影响	Harness Engineering
2026.02.17	LangChain	用 Harness 优化将 Benchmark 排名从 30+ 提升到前 5	Improving Deep Agents with harness engineering
2026.03.05	Latent Space	发起 “Big Model vs Big Harness” 行业大辩论	Is Harness Engineering real?

2025年11月 – Anthropic 发布《Effective harnesses for long-running agents》。文章指出，长时任务下智能体面临跨多会话（无记忆）执行的问题，需要为第一轮和后续轮设计不同的环境（初始化智能体和持续编码智能体），并利用进度日志和Git历史等机制跨会话传递上下文。这一工作虽然未使用“Harness Engineering”一词，但奠定了跨会话编码时构造框架的思路。
2026年2月5日 – Mitchell Hashimoto（HashiCorp创始人）发表博客《My AI Adoption Journey》，首次明确使用“Harness Engineering”术语。他提出“工程Harness”的理念："每当发现 Agent 犯错，就花时间设计一个解决方案，确保 Agent 永远不会再犯同样的错误"，用来描述他在多阶段 AI 采纳路线中，从调 prompt走向系统性改造 Agent 所在环境的关键步骤。
2026年2月11日 – OpenAI团队（Ryan Lopopolo 等）发布博客《Harness engineering: leveraging Codex in an agent-first world》。该文首次以“Harness engineering”为题，报告了一个全自动编码产品的实践：用GPT-5 Codex在空仓库中生成初始框架、代码和文档，在5个月内由3-7人团队无人工编写地构建出百万行代码。
2026年2月17日 – ThoughtWorks的Martin Fowler 发布《Harness Engineering》专文，将 OpenAI 的实践抽象为三大支柱：Context Engineering、Architectural Constraints、Garbage Collection（熵管理），并正式把 Harness Engineering 作为一种新兴软件工程分支加以讨论。
2026年2月17日 – LangChain团队（Harrison Chase 等）发表博客《Improving Deep Agents with harness engineering》。他们展示在不改底层模型的前提下，仅通过迭代优化Harness，使基于GPT-5.2-Codex的深度编码Agent在Terminal Bench评测中的正确率从52.8%提升到66.5%。
2026年3月10日 – LangChain的Vivek Trivedy发布《The Anatomy of an Agent Harness》，明确给出“Agent = 模型 + Harness”公式，将Harness定义为“赋予模型状态、工具执行、反馈回路等能力的所有东西”。文章系统归纳了构建智能体所需的Harness组件，推动该领域概念进一步清晰。
2026年3月中旬 – AI工程师Cobus Greyling在Medium撰文《The Rise of AI Harness Engineering》指出，继SDK、Framework、Scaffolding三大范式后，Harness已成为第四种重要架构层。文章称OpenAI和Anthropic都正式使用了“Harness”一词，并将其比作操作系统层（管理上下文、初始化、工具驱动等），标志着业界对Harness概念的广泛关注。

总体而言，2025年底至2026年初是Harness Engineering概念快速兴起的阶段：OpenAI、Anthropic等公司在最前沿实践中总结经验，新思想传播到LangChain、学术界和社区，并出现了相关学术论文和工具支持。

【Why】为什么 Harness Engineering 会在 2026 年突然变热？

核心原因只有一个：AI 生成代码的速度，已经明显快过人类逐行审查和验证代码的速度。我们从"人写代码"进入了"AI 写代码"的时代，但配套的工程体系还停留在"人写代码"的范式里。 Harness Engineering 就是为了填补这个空白而生的。

这意味着软件工程的主要瓶颈发生了迁移：

过去的瓶颈是“写得慢”
现在的瓶颈越来越变成“不能快速信任产出”

当Agent可以持续读仓库、改代码、跑测试、提交PR 时，团队真正要解决的问题就不再只是怎么写prompt，而是：

如何让它拿到正确的上下文
如何限制它的权限边界
如何让它自动验证结果
如何在失败后快速纠偏
如何把同类错误一次性工程化消灭

这套问题的总和，就是 Harness Engineering。

Harness Engineering 之所以在 2026 年初迅速走红，不是因为它是全新的概念——而是因为它终于给了工程师一个词来描述他们已经在做的事情。

Harness Engineer（架构工程师）

职能转变：在智能体优先（agent-first）的世界中，工程师的主要工作不再是手动编写代码，而是设计环境、指定意图，并构建反馈循环，从而使智能体能够可靠地工作。这是一种专注于系统、脚手架（scaffolding）和杠杆作用的新型工程模式。
核心任务：工程师的任务是为智能体准备并交付上下文，使其能够自主完成工作。这涉及多种调节旋钮，包括设计系统提示词、选择工具、定义执行流程、构建记忆系统以及子智能体委派等。
持续优化与纠错：每当智能体犯错时，工程师会通过工程化方案确保其不再犯同样的错误。
- 这通常表现为两种形式：
  - 一是优化隐性提示词（如更新仓库中的 AGENTS.md 文件）；
  - 二是开发程序化工具（如自动截屏脚本或测试过滤器），帮助智能体验证其工作的正确性。
构建可理解性：Harness Engineering 致力于提升环境对智能体的“可理解性”，例如将应用程序的 UI、日志和指标直接暴露给智能体，使其能够自主发现错误并验证修复结果。

简而言之，Harness Engineer（架构工程师）的角色是充当智能体与执行环境之间的桥梁，通过设计严密的架构、约束条件和自动化反馈机制，确保智能体能够在无需人类持续干预的情况下规模化地构建和维护复杂软件。

【How】Harness 工程的应用与案例

【Anthropic的实践】：两步方案【环境搭建+增量开发】

在内部实验中，Claude采用两步解决方案解决了这些问题：即把长任务拆成环境搭建 + 增量开发两个阶段：

Initializer agent 初始化智能体：

首个智能体会话使用专门的提示，要求模型设置初始环境：一个init.sh脚本、一个记录智能体已完成工作的claude-progress.txt文件，一个显示添加了哪些文件的初始git提交。

第一次会话的职责是搭建可持续工作的环境，而不是立刻写很多业务代码，典型做法包括：
- 关键发现：使用 JSON 格式追踪 feature 状态比 Markdown 更有效，因为 Agent 不太可能不恰当地修改或覆盖结构化数据。
作用：
1. 写一个 init.sh：一键启动开发环境（dev server、依赖安装等）。
2. 创建 claude-progress.txt：所有后续会话都要追加自己的工作日志。
3. 生成初始的Git 仓库和首个提交。
4. 也可以加上创建feature_list.json。
5. 决定后续 Agent的运行环境。
6. 为长期任务提供一个可复现、可重启、可追踪的基线。
Coding agent 编码智能体：

后续每次会话都要求模型进行增量式进展，然后留下结构化更新。

每次后续会话，只负责一个 feature/功能的增量推进，要做的固定步骤大致是：
1. 运行 pwd 查看工作目录；
2. 读取 claude-progress.txt + Git log，理解当前状态；
3. 查看 features list（JSON/文本）确定下一个要完成的feature；
4. 修改代码实现该特性；
5. 运行init.sh ，启动开发服务器，运行基础端到端测试；
6. 测试通过后：
  1. 更新 features list 中该特性 passes: true；
  2. 写入 progress.txt 摘要；
  3. 提交 Git。
7. 确认基本功能正常后，开始新功能开发。

关键约束：

不允许一次性试图完成大量特性。
不允许“把错误掩盖掉”（禁止删除测试，禁止篡改测试条目）。
会话结束时，代码库要处于干净可合并状态（可用、可测试）。

这里的关键是找到一种方法，让智能体在使用全新上下文窗口时快速理解工作状态，这可以通过 claude-progress.txt 文件和 git 历史一起实现。这些实践的灵感来自于了解有效软件工程师每天所做的工作。

【全栈网页应用开发】：案例 - 克隆claude.ai网页

一个典型的长时间运行、长任务智能体实验场景：让单智能体，在跨多次会话、跨上下文窗口的约束下，逐步实现一个完整的claude.ai 网页克隆应用。

不是一次对话内把页面全写完，而是：
- 分成上百次独立会话；
- 每次会话上下文是新的，不共享聊天历史；
- 依靠外部文件、Git、测试脚本等持久化状态来接续工作。
功能目标被拆成200多个细粒度特性列表，例如：
- “用户可以点击 New Chat 创建一个新会话”
- “发送消息后能看到 AI 回复，并在侧边栏持久显示该会话”等。

===>

案例采用上面的两阶段架构：环境搭建 + 增量开发

【Initializer Agent】：搭建环境的初始化智能体

在第一次运行时，只做一件事：把长期开发环境和长期状态框架搭好。

关键：不是写多少业务代码，而是搭建一个让智能体长期运行的工程环境，让之后的每次会话都能轻松接上。

它会自动完成：

创建 init.sh

内容类似于：安装依赖、启动 dev server 的一键脚本。
目的：以后每次 Coding Agent 只需执行 ./init.sh 就能启动环境，避免反复摸索“怎么跑项目”。

【关键组件1】init.sh：快速启动环境

作用：

标准化“如何运行项目”的流程；

消除每次会话都要推理如何启动环境的开销token。

创建 claude-progress.txt（进度日志）

文本文件，记录：
- 已完成的里程碑
- 当前项目结构
- 尚未解决的问题
这是人类和模型都能读懂的项目进程记录。

【关键组件2】Claude-progress：进程日志

内容：

作为线性时间轴式工作日志，记录每次会话的高层摘要：

这次修了哪个特性

有没有疑问或 TODO 留给下一次

相当于一个简化版项目日报；

作用：

对智能体：新会话快速理解并且上手项目；

对人类：调试时也能看懂智能体的决策过程。

初始化 Git 仓库并做初始提交

记录初始化时的文件和结构。
为之后的每次增量修改提供版本对比和回滚能力。

【关键组件3】Git 仓库：版本化的工程记忆

作用：

所有改动都可追溯、可回滚；

git log 就是另一种结构化记忆：包含时间顺序、内容摘要。

让系统可以在出现严重 bug 时退回到某个干净状态的 checkpoint；

从工程视角保证了长期运行的可控性。

生成 feature_list.json（功能清单）

包含 200+ 个特性，每条特性都有：
- category：类别（如 functional）
- description：特性描述
- steps：验证该特性的端到端测试步骤
- passes: false（表示尚未通过）
例如“New Chat 按钮创建新会话”这一条，就会列出：
- 打开主界面
- 点击 “New Chat”
- 验证新会话被创建
- 聊天区是欢迎态
- 侧边栏出现该会话
所有特性初始为 passes: false，只有在真正按步骤验证后才能改为 true。

【关键组件4】Feature list ：功能列表

为了解决智能体一次性完成应用或过早认为项目已完成的问题，我们促使初始化智能体编写一份全面的功能需求文件，扩展用户最初的提示。

在案例中，这意味着超过200个功能，例如“用户可以打开新聊天，输入查询，按回车键，并看到AI响应”等。这些功能最初都被标记为失败false，以便后续的编码智能体能清楚地了解完整功能的样子。

提示词要求编码智能体：【相当于一份只读的规范 + 只写布尔状态的测试清单】

Coding Agent 不能随意改动结构，只能修改 passes 值；

不允许删除条目、改写测试步骤；

作用：

防止“过早宣称全部完成”——要宣布完成，必须所有 passes 都变为 true；

新会话只需扫一眼 passes: false 的条目就知道“还有啥没做”。

{
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": [
      "Navigate to main interface",
      "Click the 'New Chat' button",
      "Verify a new conversation is created",
      "Check that chat area shows welcome state",
      "Verify conversation appears in sidebar"
    ],
    "passes": false # 标记为失败
  }

【Coding Agent】：多轮增量开发的编码智能体

这使得每一次 Coding Agent 会话，都像是一个守纪律的工程师：只做一个明确特性，收尾干净，给下一位留下清晰交接。

之后的每次会话，都由 Coding Agent 负责，它的行为模式被严格“脚本化”：

先搞清楚当前状态：

在以上所有措施到位后，每个编码智能体都会被提示执行一系列步骤以熟悉环境，尽管这些步骤相当基础，但仍很有帮助：

【关键功能1】Getting up to speed：快速开发

pwd 看当前目录结构，只能编辑此目录中的文件；

读取 claude-progress.txt进程日志，理解最新进度；

读取 feature_list.json，找到所有特性和状态；

查看 git log，了解最近的工作内容和改动；

确认 init.sh 存在，并用它启动开发服务器。

选择下一个要做的特性：

在建立了上述初始环境结构后，接下来的编码智能体被要求一次只处理一个功能。这种增量方法对于解决智能体一次性做太多事的倾向至关重要。一旦开始增量式工作，确保模型在做出代码更改后将环境置于干净状态仍然至关重要。

在Claude的实验中，发现最有效激发该行为的方法是要求模型用描述性的提交信息将进度提交到git，并在进度文件中写入其进展摘要。这使得模型能够利用git来回滚糟糕的代码更改，并恢复代码库的工作状态。这些方法还提高了效率，因为它们消除了智能体需要猜测之前发生了什么并花时间重新让基本应用正常运行的需求。

【关键功能2】Incremental progress：渐进式开发

从 feature_list.json 中筛选 passes: false 的特性；

选择优先级最高且尚未完成的功能开始工作；

一次会话只选一个特性来实现或修复。

实现与测试：

之前观察到的其中一个主要失败模式是Claude倾向于在未充分测试的情况下就标记功能为完成。在缺乏明确提示的情况下，Claude往往会进行代码更改，甚至使用单元测试或curl命令对开发服务器进行测试，但未能认识到功能并未端到端正常工作。

【关键功能3】Testing:测试

在构建网页应用的情况下，一旦明确提示智能体使用浏览器自动化工具并像人类用户一样进行所有测试，Claude在验证功能端到端方面表现得相当出色。

这种方法在每个会话中节省了Claude的token，因为不必再费心去弄清如何测试代码。同时，也建议初始化智能体编写一个init.sh脚本，该脚本可以运行开发服务器，然后在实现新功能前运行基本的端到端测试。

修改代码实现该特性；

使用 Puppeteer MCP 做 端到端浏览器自动化测试：

打开本地服务；

像用户一样点击按钮、输入文字、检查页面变化；

如果不符合预期，继续修代码，直到步骤全部通过。

更新状态并提交：

如果测试通过：
- 将该特性的 passes 从 false 改为 true；
并且在 claude-progress.txt 中追加日志：
- 当前会话完成的内容；
- 修改的文件；
- 已知限制或尚未解决的问题；
使用 Git 提交当前改动，写明提交改动的信息。
保证工作目录干净，方便下一轮继续。

考虑到上面的关键功能，典型的会话开头会包含以下消息：

[Assistant] 我将先理清自己的状况，了解项目的当前状态。
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] 让我检查一下git日志，看看最近的工作。
[Tool Use] <bash - git log --oneline -20>
[Assistant] 现在让我检查是否有`init.sh`脚本可以重启服务器。
<启动开发服务器>
[Assistant] 很好！现在让我导航到应用程序，验证一些基本功能是否仍然正常。
<测试基本功能>
[Assistant] 根据我的验证测试，我可以确认基本功能运行良好。核心聊天功能、主题切换、对话加载和错误处理都正常工作。现在让我更全面地查看tests.json文件，以了解下一步需要实现的内容。
<开始新功能的工作>

下面的表格总结了长期运行的人工智能智能体中常见的四种故障模式和解决方案：

问题	Harness	初始化智能体行为	编码智能体行为
试图一步到位（One-shotting）	结构化功能列表 + 每次只做一个	用 `progress.txt` + `git log` + `feature_list.json` 外化状态	下一次会话先读`progress.txt` + `git log` + `feature_list.json`获取信息再渐进式开发
过早宣告整个项目完成	所有功能初始为"失败" + 需通过测试才能标记完成	设置功能列表`feature_list.json`：基于输入规范，创建一个结构化的JSON文件，列出端到端功能描述	在会话开始时阅读功能列表文件。选择一个单一功能开始工作必须逐项把`passes: false → true`，项目完成条件被刚性定义
留下带有错误或未文档化进展的环境	强制 Git commit + 进度文件更新	写入初始`git`仓库和进度日志文件`progress.txt`	在会话开始时阅读进度笔记文件和`git`提交日志，并运行基本测试以捕捉任何未文档化的错误。在会话结束时编写git提交和进度更新
过早标记功能为完成	要求截图验证 + 端到端测试	设置功能列表文件	自我验证所有功能。每个功能都附带详细 `steps` 只有在仔细按照步骤测试后才将功能标记为`passing`
花费时间弄清楚如何运行	预置 init.sh 脚本	构造`init.sh`方便快速启动环境	在会话开始时通过`init.sh`启动环境