AI Agent 现在能处理需要数小时甚至数天的任务。但有个难题:它们无法在多个上下文窗口之间保持进度。
核心问题在哪?Agent 以离散会话方式工作,每次新会话启动时完全不记得之前发生的事。想象一个软件项目,工程师轮班作业,但每位新工程师上岗时对前一班的工作一无所知。上下文窗口容量有限,大多数复杂项目无法在单个窗口内完成。Agent 需要找到跨越这些间隙的方法。
我们为 Claude Agent SDK 构建了双管齐下的解决方案:初始化 agent 在首次运行时搭建环境,编码 agent 在每次会话中实现增量进展,同时为下次会话留下清晰记录。代码示例见快速开始文档。
长期运行 agent 的难题
Claude Agent SDK 擅长处理编码及其他需要工具、收集上下文、规划和执行的任务。它通过压缩管理上下文,避免 agent 耗尽上下文窗口。理论上,agent 应该能持续工作下去。
但光靠压缩还不行。即使是 Opus 4.5 在 Claude Agent SDK 上跨多个上下文窗口运行,也无法仅凭「构建一个 claude.ai 克隆」这样的指令构建出生产级 Web 应用。
Claude 会以两种方式失败。第一,它试图一次性完成太多任务——企图一口气搞定整个应用。这导致实现过程中耗尽上下文,给下一个会话留下半成品、无文档的功能。Agent 只能靠猜测还原经过,浪费时间修复基础应用。即便有压缩机制,这种情况依然会发生,因为压缩并不总能给下一个 agent 传递明确指令。
第二种失败出现在项目后期。构建了部分功能后,后续 agent 实例四下查看,发现有进展,就过早宣告任务完成。
这分解为两个问题。第一,我们需要搭建初始环境,为所有功能打好基础,让 agent 按步骤逐个功能推进。第二,每个 agent 要在实现增量进展的同时,保持环境整洁——代码达到可合并至主分支的标准:无重大 bug、结构清晰、文档完备,便于下一个 agent 无缝衔接。
我们用两步方案解决:
1. 初始化 agent:首次会话搭建 init.sh脚本、claude-progress.txt日志文件,以及标明新增文件的初始 git 提交。2. 编码 agent:后续每次会话实现增量进展,随后留下结构化更新记录。
关键洞察:agent 需要在启动新上下文窗口时迅速掌握工作状态。我们通过 claude-progress.txt 文件配合 git 历史实现——借鉴优秀软件工程师的日常实践。
环境管理
在更新的 Claude 4 提示指南中,我们分享了多上下文窗口工作流的最佳实践,包括「首个上下文窗口使用不同提示」。这个提示指导初始化 agent 搭建环境,涵盖未来编码 agent 所需的全部上下文。下面深入探讨关键组件。
功能清单
为阻止 agent 一次性完成应用或过早宣告成功,我们让初始化 agent 基于用户提示编写全面的功能需求文件。对于 claude.ai 克隆,这意味着 200 多项功能,例如「用户可以开启新聊天,输入查询,按回车,接收 AI 响应」。所有功能初始状态为「失败」,后续编码 agent 由此获得完整功能的清晰蓝图。
{
"category":"functional",
"description":"新建聊天按钮创建新对话",
"steps":[
"导航至主界面",
"点击「新建聊天」按钮",
"验证新对话已创建",
"检查聊天区显示欢迎状态",
"确认对话出现在侧边栏"
],
"passes":false
}
编码 agent 只能通过修改 passes 字段来编辑此文件。我们用措辞严厉的指令,比如「删除或编辑测试绝不可接受,因为这可能导致功能缺失或出现 bug」。经测试,我们选择 JSON 格式——模型修改或覆写 JSON 文件的不当操作比 Markdown 少。
增量进展
有了这套框架,我们要求编码 agent 每次只处理一项功能。这种增量方法对解决 agent 试图一次性完成过多任务的问题至关重要。
增量工作只有在模型每次修改后保持环境整洁时才有效。我们发现,最佳方法是要求模型用描述性提交信息将进度提交至 git,并在进度文件中记录摘要。这样模型可用 git 回滚错误修改,恢复工作状态。
这也提升了效率,省去 agent 猜测经过和浪费时间修复基础应用的麻烦。
测试
Claude 最后一个主要失败点:未经充分测试就将功能标记为完成。如果没有明确提示,Claude 会修改代码,甚至对开发服务器运行单元测试或 curl 命令,但无法验证功能是否端到端正常工作。
对于 Web 应用,一旦明确告知 Claude 使用浏览器自动化工具并像真实用户那样测试,它就能很好地完成端到端验证。
MCP 服务器测试 claude.ai 克隆时的截图" class="rich_pages wxw-img" data-ratio="0.5625579240037072" data-w="1079" style="display: block;max-width: 100%;margin: 0.1em auto 0.5em;border-radius: 4px;">这些测试工具大幅提升了性能。Agent 能识别并修复仅从代码无法发现的 bug。
部分问题仍未解决。Claude 的视觉能力和浏览器自动化工具存在局限,难以捕获所有类型的 bug。例如,Claude 无法通过 Puppeteer MCP 看到浏览器原生 alert 模态框,依赖这些模态框的功能往往更易出现 bug。
快速进入状态
现在每个编码 agent 都会执行以下步骤来定位自己:
1. 运行 pwd查看工作目录。你只能编辑该目录内的文件。2. 阅读 git 日志和进度文件,了解近期工作。 3. 查看功能清单,选择优先级最高的未完成功能。
这为每个会话节省了 Claude 的 token,因为它无需费心弄清如何测试代码。让初始化 agent 编写运行开发服务器的 init.sh 脚本,然后在实现新功能前执行基本端到端测试,也很有帮助。
对于 claude.ai 克隆,agent 总是先启动本地开发服务器,用 Puppeteer MCP 开启新聊天、发送消息并接收响应。这让 Claude 能快速发现应用是否损坏,立即修复 bug。如果 agent 直接着手实现新功能,反而会加剧问题。
典型会话这样开始:
[Assistant] 我先了解项目当前状态。
[ToolUse]<bash-pwd>
[ToolUse]<read-claude-progress.txt>
[ToolUse]<read-feature_list.json>
[Assistant]让我查看git日志,看看最近做了什么。
[ToolUse]<bash-gitlog--oneline-20>
[Assistant]现在检查是否有init.sh脚本来重启服务器。
<启动开发服务器>
[Assistant]很好!现在导航到应用,验证部分基础功能是否正常。
<测试基本功能>
[Assistant]根据验证测试,基础功能运行良好。核心聊天功能、主题切换、对话加载和错误处理都正常。现在更全面地查看tests.json文件,了解下一步要实现什么。
<开始处理新功能>
Agent 失败模式及解决方案
| 问题 | 初始化 Agent 做法 | 编码 Agent 做法 |
|---|---|---|
init.sh 脚本 | init.sh |
未来工作
这项研究展示了长期运行 agent 框架中的一组可能解决方案,能让模型在多个上下文窗口间实现增量进展。但仍有悬而未决的问题。
最显著的是:单一通用编码 agent 在各类上下文中表现最佳,还是多 agent 架构效果更好?专门的 agent——测试 agent、质量保证 agent 或代码清理 agent——可能在软件开发生命周期的各项子任务中做得更出色。
这个演示针对全栈 Web 应用开发优化。未来方向是将这些发现推广至其他领域。部分或全部经验教训可能适用于科研或金融建模中的长期运行 agent 任务。
