上下文工程的核心实践：来自Manus的启示

引言

构建高效、可靠且可扩展的AI Agent，其成功的关键很大程度上取决于我们如何设计和管理模型的“上下文”（Context）。上下文不仅是Agent与外界交互的窗口，更是其记忆、推理和决策的基础。近期，Manus团队通过其博客文章《Context Engineering for AI Agents: Lessons from Building Manus》分享了他们在构建自家Agent过程中沉淀的宝贵经验。本文将提炼并整理其核心观点，为正在构建AI Agent的开发者提供一份实用的实践指南。

六大核心上下文工程实践

Manus团队通过大量的实验和四次框架重构，总结出了六个关键的上下文工程原则。这些原则并非普适真理，但它们是在真实世界应用中被证明行之有效的“局部最优解”。

1. 围绕KV缓存进行设计 (Design Around the KV-Cache)
2. 掩蔽而非移除 (Mask, Don’t Remove)
3. 使用文件系统作为上下文 (Use the File System as Context)
4. 通过复述来操纵注意力 (Manipulate Attention Through Recitation)
5. 保留错误信息 (Keep the Wrong Stuff In)
6. 避免陷入少样本陷阱 (Don’t Get Few-Shotted)

原则详解

1. 围绕KV缓存进行设计

• 问题: Agent的运行涉及大量的迭代，每次迭代都会向上文文中添加新的信息，导致输入（上下文）远大于输出（动作）。这种不平衡使得推理成本和延迟成为主要瓶颈。
• 解决方案: 最大化利用KV缓存。KV缓存可以极大地减少处理相同上下文前缀所需的时间和成本（例如，Claude Sonnet的缓存与非缓存输入成本相差10倍）。
• 实施要点:
  • 保持前缀稳定: 避免在系统提示的开头部分加入动态变化的内容，如精确到秒的时间戳，因为即使是单个token的改变也会让后续缓存失效。
  • 上下文只增不减: 确保上下文是“追加式”的，避免修改历史动作或观察。
  • 序列化确定性: 保证将对象（如JSON）序列化到上下文时，键的顺序是固定的，否则会无形中破坏缓存。

2. 掩蔽而非移除

• 问题: 随着Agent能力的增强，其工具集（Action Space）会变得异常庞大和复杂。动态地从上下文中添加或移除工具定义似乎是一种自然的解决方案，但这会直接破坏KV缓存，因为工具定义通常位于上下文的前部。
• 解决方案: 使用“掩蔽”（Masking）技术代替“移除”。即，保留所有工具的定义，但在模型进行解码（选择下一个动作）时，通过操纵token的logits来动态地限制或强制模型选择某个子集的工具。
• 实施要点:
  • 利用模型推理服务提供的response prefill或类似功能，约束模型的输出范围。
  • 可以设计具有特定前缀的工具名称（如browser_*, shell_*），以便于按组进行掩蔽。

3. 使用文件系统作为上下文

• 问题: 现代LLM虽然拥有巨大的上下文窗口（如128K+），但在处理网页、PDF等非结构化数据时，依然容易超出限制。此外，长上下文不仅昂贵，还可能导致模型性能下降（“大海捞针”问题）。
• 解决方案: 将文件系统视为无限、持久且可由Agent直接操作的外部记忆。Agent学会按需读写文件，从而将庞大的信息“外化”存储。
• 实施要点:
  • 设计可恢复的压缩策略。例如，在上下文中只保留网页的URL或文件的路径，而不是其全部内容。当Agent需要时，可以随时通过URL或路径重新读取完整信息。
  • 这种方式实现了信息的无损压缩，有效缩减了上下文长度。

4. 通过复述来操纵注意力

• 问题: 在执行包含数十个步骤的长任务时，Agent很容易“跑偏”或忘记最初的目标，这被称为“迷失在中间”（lost-in-the-middle）问题。
• 解决方案: 通过“复述”（Recitation）来操纵模型的注意力。让Agent在一个外部文件（如todo.md）中维护一个任务清单，并在每一步完成后更新它。
• 实施要点:
  • Agent不断地重写任务清单，这个动作会将全局计划和当前进展“推”到上下文的末尾。
  • 由于LLM的注意力机制倾向于更关注最近的token，这种方式相当于用自然语言不断提醒Agent“不要忘了目标”，从而有效对抗目标漂移。

5. 保留错误信息

• 问题: Agent在执行任务时不可避免地会犯错。开发者往往倾向于隐藏这些错误，清理痕迹，然后重试。但这剥夺了模型从失败中学习的机会。
• 解决方案: 将失败的动作、返回的错误信息或堆栈跟踪（stack trace）完整地保留在上下文中。
• 实施要点:
  • 当模型看到一个失败的记录时，它会隐式地更新其内部信念，从而降低在后续步骤中重复同样错误的可能性。
  • 错误恢复是衡量真正智能体行为的关键指标之一。让Agent看到自己的错误，是提升其鲁棒性的最有效方法之一。

6. 避免陷入少样本陷阱

• 问题: LLM是出色的模仿者。如果上下文中充满了大量相似的、重复的动作-观察对（Action-Observation Pairs），模型会陷入一种“思维定势”，机械地模仿之前的行为模式，即使当前情况需要不同的策略。
• 解决方案: 在上下文中引入结构化的多样性。
• 实施要点:
  • 在序列化动作和观察时，引入一些微小的、受控的变化，例如使用不同的模板、措辞或格式。
  • 这种“受控的随机性”有助于打破上下文的单调性，调整模型的注意力，防止其因过度模仿而变得脆弱和低效。

总结

上下文工程是一门新兴的、实验性的科学，但它对于构建真正有用的AI Agent至关重要。模型的原始能力固然重要，但如何塑造其记忆、环境和反馈循环，最终决定了Agent的行为：它的运行速度、恢复能力和扩展潜力。Manus团队的经验告诉我们，精心设计的上下文是通往更强大、更智能的Agent的必经之路。未来的Agent，将由一个个精心设计的上下文构建而成。