长效智能体的高效工具链

随着 AI 智能体能力的不断增强，开发者越来越多地要求它们承担需要数小时甚至数天才能完成的复杂任务。然而，如何让智能体在多个上下文窗口之间保持持续稳定的进展，仍然是一个悬而未决的问题。

长时间运行的智能体面临的核心挑战在于，它们必须在离散的会话中工作，而每个新会话开始时都对之前发生的事情毫无记忆。想象一下，一个软件项目由轮班工作的工程师组成，每位新到岗的工程师对上一班发生的事情一无所知。由于上下文窗口是有限的，而且大多数复杂项目无法在单个窗口内完成，智能体需要一种方法来弥合编码会话之间的鸿沟。

我们开发了一套双重解决方案，使 Claude Agent SDK 能够有效地跨越多个上下文窗口工作：一个 初始化智能体在首次运行时设置环境，以及一个 编码智能体负责在每个会话中取得增量进展，同时为下一个会话留下清晰的工件。你可以在配套的快速入门中找到代码示例。

长时间运行的智能体问题

Claude Agent SDK 是一个强大的通用智能体框架，不仅擅长编码，还擅长其他需要模型使用工具来收集上下文、规划和执行的任务。它具备上下文管理能力，例如压缩（compaction），使智能体能够在不耗尽上下文窗口的情况下处理任务。从理论上讲，在这种设置下，智能体应该能够持续进行有用的工作，时间可以任意长。

然而，仅靠压缩是不够的。开箱即用的情况下，即使是像 Opus 4.5 这样的前沿编码模型，在 Claude Agent SDK 上跨多个上下文窗口循环运行，如果只给出一个高层级的提示（例如“构建一个 claude.ai 的克隆版”），也无法构建出生产级质量的 Web 应用。

Claude 的失败表现为两种模式。首先，智能体倾向于试图一次性做太多事情——本质上是试图一口气完成整个应用。这通常导致模型在实现过程中用尽上下文，使得下一个会话开始时面对的是一个实现了一半且没有文档记录的功能。智能体随后不得不猜测发生了什么，并花费大量时间试图让基本应用重新运行起来。即使有压缩功能，这种情况也会发生，因为压缩并不总是能向下一个智能体传递完全清晰的指令。

第二种失败模式通常发生在项目的后期。在一些功能已经构建完成后，后来的智能体实例会环顾四周，看到已经取得了进展，然后宣布工作完成。

这将问题分解为两个部分。首先，我们需要建立一个初始环境，为给定提示所要求的所有功能奠定基础，从而让智能体能够逐步、逐个功能地工作。其次，我们应该提示每个智能体在朝着目标取得增量进展的同时，在会话结束时将环境保持在干净的状态。所谓“干净状态”，我们指的是适合合并到主分支的代码：没有重大错误，代码整洁且有良好的文档，通常开发者可以轻松地开始开发新功能，而无需先清理不相关的混乱。

在内部实验中，我们使用两部分解决方案来解决这些问题：

初始化器代理：第一个代理会话使用一个专门的提示词，要求模型设置初始环境：一个 init.sh 脚本、一个记录代理所做工作的 claude-progress.txt 文件，以及一个显示添加了哪些文件的初始 git 提交。
编码代理：之后的每个会话都要求模型取得增量进展，然后留下结构化的更新。¹

这里的关键洞察是找到一种方法，让代理在使用全新的上下文窗口开始工作时能快速了解工作状态，这通过 claude-progress.txt 文件与 git 历史记录配合实现。这些实践的灵感来源于了解高效的软件工程师每天都在做什么。

环境管理

在更新后的 Claude 4 提示词指南中，我们分享了一些多上下文窗口工作流的最佳实践，包括一种使用“针对第一个上下文窗口使用不同提示词”的框架结构。这个“不同的提示词”要求初始化器代理设置环境，并包含未来编码代理有效工作所需的所有必要上下文。在此，我们将深入探讨此类环境的一些关键组成部分。

功能列表

为了解决代理一次性完成整个应用或过早认为项目已完成的问题，我们提示初始化器代理编写一个全面的功能需求文件，扩展用户的初始提示词。在 claude.ai 克隆示例中，这意味着超过 200 个功能，例如“用户可以打开新聊天、输入查询、按回车并看到 AI 响应”。这些功能最初都被标记为“失败”，以便后续的编码代理能清楚了解完整功能是什么样的。

{
    "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
  }

我们提示编码代理只能通过更改 passes 字段的状态来编辑此文件，并且我们使用措辞强烈的指令，例如“删除或编辑测试是不可接受的，因为这可能导致功能缺失或存在缺陷。”经过一些实验后，我们决定使用 JSON，因为与 Markdown 文件相比，模型不太可能不当地更改或覆盖 JSON 文件。

增量进展

在有了这个初始环境脚手架之后，编码代理的下一次迭代被要求一次只处理一个功能。事实证明，这种增量方法对于解决代理一次性做太多事情的倾向至关重要。

一旦开始增量工作，模型在进行代码更改后将环境保持在干净状态仍然至关重要。在我们的实验中，我们发现引发这种行为的最佳方式是要求模型将其进展提交到 git，附带描述性的提交信息，并在进度文件中写下进展总结。这使模型能够使用 git 回退糟糕的代码更改并恢复代码库的工作状态。

这些方法还提高了效率，因为它们消除了代理猜测发生了什么并花费时间尝试让基本应用重新运行的需要。

测试

我们观察到的最后一个主要失败模式是 Claude 倾向于在没有适当测试的情况下将功能标记为完成。在没有明确提示的情况下，Claude 倾向于进行代码更改，甚至使用单元测试或针对开发服务器的 curl 命令进行测试，但未能认识到该功能无法端到端运行。

在构建 Web 应用的场景中，一旦明确提示 Claude 使用浏览器自动化工具并像人类用户一样进行所有测试，Claude 在端到端验证功能方面大多表现出色。

Screenshots taken by Claude through the Puppeteer MCP server as it tested the claude.ai clone. — Claude 通过 Puppeteer MCP 服务器在测试 claude.ai 克隆版时截取的屏幕截图。

为 Claude 提供这类测试工具显著提升了性能，因为智能体能够识别并修复仅从代码本身难以发现的缺陷。

仍存在一些问题，例如 Claude 的视觉能力以及浏览器自动化工具的局限性，使得识别所有类型的缺陷变得困难。例如，Claude 无法通过 Puppeteer MCP 看到浏览器原生的 alert 弹窗，依赖这些弹窗的功能因此往往存在更多缺陷。

熟悉环境

在上述所有准备工作就绪后，每个编码智能体都会被提示执行一系列步骤来熟悉环境，其中一些相当基础但仍有帮助：

运行 pwd 以查看你正在操作的目录。你只能编辑此目录中的文件。
阅读 git 日志和进度文件，以了解最近的工作内容。
阅读功能列表文件，选择尚未完成的最高优先级功能进行开发。

这种方法为 Claude 在每次会话中节省了一些 token，因为它不必再弄清楚如何测试代码。此外，让初始化智能体编写一个可以运行开发服务器的 init.sh 脚本，并在实现新功能之前先运行一次基本的端到端测试，也很有帮助。

对于 claude.ai 克隆版而言，这意味着智能体总是先启动本地开发服务器，并使用 Puppeteer MCP 开启新聊天、发送消息并接收回复。这确保了 Claude 能够快速发现应用是否处于损坏状态，并立即修复任何现有缺陷。如果智能体转而开始实现新功能，很可能会使问题恶化。

综上所述，一次典型的会话会以以下助手消息开始：

[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>
[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.
<Starts work on a new feature>

总结长期运行的 AI 智能体中四种常见的失败模式及其解决方案。

未来工作

本研究展示了一套可能的解决方案，用于长期运行的智能体框架，使模型能够在多个上下文窗口之间取得渐进式进展。然而，仍存在一些未解的问题。

最值得注意的是，目前尚不清楚是单一的通用编码智能体在跨上下文场景中表现最佳，还是通过多智能体架构能获得更好的性能。像测试智能体、质量保证智能体或代码清理智能体这样的专用智能体，在软件开发生命周期的子任务上似乎能够做得更好，这似乎是合理的。

此外，本演示针对全栈 Web 应用开发进行了优化。未来的一个方向是将这些发现推广到其他领域。这些经验中的一部分或全部很可能可以应用于例如科学研究或金融建模等领域所需的长期运行的智能体任务。