原文：Effective harnesses for long-running agents

智能体在跨多个上下文窗口工作时仍面临诸多挑战。我们从人类工程师的工作模式中汲取灵感，打造出了更高效的长期运行智能体管控框架。

随着 AI 智能体能力的不断提升，开发者越来越多地要求它们承担需要耗时数小时甚至数天的复杂任务。然而，如何让智能体在多个上下文窗口中保持稳定的进度推进，至今仍是一个待解难题。

长期运行智能体的核心挑战在于，它们必须在离散的会话中开展工作，且每个新会话启动时都不具备前序工作的记忆。这就好比一个软件项目由轮班工作的工程师负责，而每位接班的工程师都对之前班次的工作毫无记忆。由于上下文窗口存在长度限制，且多数复杂项目无法在单个窗口内完成，智能体需要一种能衔接不同编码会话的机制。

为使 Claude Agent SDK 能在多个上下文窗口中高效运行，我们设计了一套双重解决方案：一是负责在首次运行时搭建环境的初始化智能体；二是承担 “在每次会话中实现增量式进度推进，并为下一会话留存清晰工作产物” 任务的编码智能体。相关代码示例可参考配套的快速入门指南。

1 长期运行智能体的核心难题

Claude 智能体 SDK 是一款功能强大的通用型智能体管控工具，不仅擅长编码任务，还能处理各类需要调用工具来收集上下文、制定计划并执行的任务。它具备上下文压缩等上下文管理能力，可让智能体在不耗尽上下文窗口额度的前提下推进任务。理论上，基于这一架构，智能体应当能无限期地持续开展有效工作。

但仅靠上下文压缩还远远不够。即便像 Opus 4.5 这样前沿的编码模型，在 Claude 智能体 SDK 中循环跨多个上下文窗口运行时，若仅给出 “构建一个 claude.ai 的克隆版本” 这类高层级指令，也无法成功搭建出生产级别的网页应用。

Claude 的失效主要呈现为两种模式：

• 其一，智能体倾向于一次性包揽过多工作 —— 本质上是试图 “一次性完成” 整个应用的搭建。这往往会导致模型在实现过程中耗尽上下文，使得下一个会话只能从某个未完成且无文档说明的功能开始。随后，智能体不得不去猜测此前的工作进展，还要花费大量时间修复基础应用，使其恢复可用状态。即便启用了上下文压缩，这类问题仍会出现，因为压缩机制未必能将指令清晰无误地传递给下一个智能体。
• 其二，失效模式常出现在项目后期。在部分功能已完成搭建后，后续的智能体实例会在查看项目状态后，错误地判定任务已全部完成。

由此，我们可将该问题拆解为两部分。

• 首先，需要搭建一个初始环境，为用户指令所需的所有功能奠定基础，让智能体能够按步骤、按功能逐步推进工作；
• 其次，要引导每个智能体在向目标迈进的过程中实现增量式进度更新，同时在会话结束时将环境恢复至整洁状态。这里所说的 “整洁状态”，指的是代码达到可合并至主分支的标准：无重大缺陷、代码结构规整且文档完备，总体而言，后续开发者无需先清理无关的混乱代码，就能直接开展新功能的开发工作。

在内部实验中，我们通过一套双组件方案解决了上述问题：

1. 初始化智能体：首个智能体会话通过专用指令，让模型搭建初始环境，包括init.sh脚本、用于记录智能体工作内容的claude-progress.txt文件，以及能展示新增文件的初始 git 提交记录。
2. 编码智能体：后续每一个会话都会要求模型实现增量式进度推进，再留存结构化的进度更新记录。

该方案的核心洞见在于，找到了让智能体在全新上下文窗口启动时快速掌握工作状态的方法 —— 借助claude-progress.txt文件和 git 提交历史即可实现。而这些实践方案的灵感，正来源于人类高效软件工程师的日常工作模式。

2 环境管理

在更新后的《Claude 4 指令优化指南》中，我们分享了多上下文窗口工作流的若干最佳实践，其中就包括 “为首个上下文窗口配置专属指令” 的管控架构。这一 “专属指令” 会要求初始化智能体搭建好环境，并预置未来编码智能体高效工作所需的全部必要上下文。本文将深入剖析这类环境的几个核心组件。

2.1 功能清单

为解决智能体 “一次性搭建完整应用” 或 “过早判定项目完工” 的问题，我们让初始化智能体基于用户的初始指令，编写一份详尽的功能需求文件。以 claude.ai 克隆项目为例，这份清单包含了 200 余项功能，例如 “用户可新建聊天、输入查询、按下回车并查看 AI 回复”。所有功能初始状态均标记为 “未达标”，以便后续编码智能体能清晰掌握完整功能的实现蓝图。

我们仅允许编码智能体修改该文件中的passes字段状态，同时会通过强语气指令进行约束，例如 “严禁删除或编辑测试项，此举可能导致功能缺失或出现缺陷”。经过多次实验，我们最终选择 JSON 格式存储该文件，因为相比 Markdown 文件，模型对 JSON 文件进行不当修改或覆盖的概率更低。

2.2 增量式进度推进

在完成初始环境搭建后，新版编码智能体被要求每次仅专注于开发一个功能。这种增量式工作模式，被证实是解决智能体 “贪多求全” 问题的关键。

即便采用了增量式工作，模型在完成代码修改后，仍需将环境恢复至整洁状态。实验表明，实现这一目标的最佳方式，是让模型将进度提交至 git 并撰写描述性的提交信息，同时在进度文件中记录工作摘要。这一机制能让模型借助 git 回滚有问题的代码变更，恢复代码库的可用状态。

这些方法还能提升工作效率，因为智能体无需再耗费时间猜测过往工作进展，也不必为修复基础应用而反复调试。

2.3 测试环节

我们观察到的最后一个主要失效模式是，Claude 常会在未完成充分测试的情况下，就标记某功能为 “已完成”。若未进行明确指令引导，Claude 虽会执行代码修改，甚至通过单元测试或向开发服务器发送curl命令开展测试，但往往无法识别功能的端到端链路是否真正可用。

在搭建网页应用的场景中，一旦明确要求 Claude 使用浏览器自动化工具，并完全模拟人类用户的流程开展测试，它就能较好地完成端到端功能验证。

为 Claude 配备这类测试工具后，其性能得到了显著提升，因为智能体能够识别并修复那些仅从代码层面无法发现的潜在缺陷。

当然，目前仍存在一些待解决的问题，例如 Claude 的视觉能力限制和浏览器自动化工具的局限性，导致它无法识别所有类型的缺陷。举例来说，Claude 无法通过 Puppeteer MCP 识别浏览器原生的警示弹窗，因此依赖这类弹窗的功能往往更容易出现缺陷。

2.4 快速上手工作流

在完成上述所有配置后，每个编码智能体都会按照一系列步骤进入工作状态，部分步骤虽基础但实用性极强：

1. 执行pwd命令确认当前工作目录，且仅可编辑该目录下的文件；
2. 查阅 git 日志和进度文件，了解近期工作进展；
3. 读取功能清单文件，选择优先级最高的未完成功能开展开发。

这种流程能为 Claude 在每个会话中节省一定的 token 消耗，因为它无需再自行摸索代码测试方法。此外，让初始化智能体编写可启动开发服务器的init.sh脚本，并在开发新功能前完成基础端到端测试，也能大幅提升工作效率。

以 claude.ai 克隆项目为例，智能体会先启动本地开发服务器，再通过 Puppeteer MCP 新建聊天、发送消息并接收回复。这一流程可确保 Claude 快速识别应用是否处于故障状态，并立即修复现存缺陷。若智能体直接跳过这一步骤开展新功能开发，很可能会让现有问题进一步恶化。

基于上述流程，一个典型的会话通常会以如下助手消息开启：

2.5 智能体失效模式及对应解决方案。

表格说明：总结了长期运行 AI 智能体的四类常见失效模式及对应解决方案

3 未来工作方向

本研究提出了一套可让模型在多上下文窗口中实现增量式进度推进的长期运行智能体管控方案，但仍存在诸多待探索的问题。

最值得关注的是，目前尚未明确 “单一通用型编码智能体” 是否能在跨上下文场景中实现最优性能，或是通过 “多智能体架构” 可达成更优效果。从合理性角度推测，诸如测试智能体、质量保障智能体、代码清理智能体等专业化智能体，或许能在软件开发生命周期的各子任务中表现更出色。

此外，本演示方案是针对全栈网页应用开发场景进行优化的。未来的一个研究方向是将这些成果推广至其他领域，例如科学研究、金融建模等场景下的长期智能体任务，很可能也能借鉴部分或全部相关经验。