挑战: 上下文工程是一门实验科学，充满了手动架构搜索和提示调整，作者称之为“随机研究生下降”。
目标: 分享通过实践总结出的6个核心原则，帮助其他AI代理构建者更快地找到有效方法。
AI代理的上下文工程：构建Manus的经验教训
[[AI代理的上下文工程：构建Manus的经验教训-2025-07-21]]
背景: 面对从头训练模型（慢）和基于上下文学习（快）的选择，Manus选择了后者，以实现快速迭代并与基础模型进步保持同步。
核心思想: KV-cache命中率是生产环境中AI代理最关键的指标，直接影响延迟和成本（可达10倍差异）。代理的输入/输出token比例（~100:1）使其尤其重要。
- 保持提示前缀稳定: 避免在提示开头使用易变内容（如精确时间戳），因为单个token的变化就会使后续缓存失效。
问题: 工具数量爆炸导致代理“变笨”。动态加载工具（如RAG）会因破坏KV缓存和引起模型困惑而适得其反。
- 使上下文只追加: 避免修改历史记录，并确保序列化（如JSON）是确定性的，防止键顺序变化破坏缓存。
解决方案: 使用上下文感知的“状态机”来管理工具可用性。不是移除工具，而是在解码时“遮蔽”不可用工具的logits，从而阻止或强制选择某些动作。
实现: 利用响应预填充（自动、必需、指定模式）和一致的动作命名（如browser_*）来约束动作空间，而无需修改上下文中的工具定义。
- 明确标记缓存断点: 在不支持自动增量缓存的框架中，手动插入缓存断点以保护系统提示等核心部分。
问题: 即使有128K+的上下文窗口，也常因观察结果庞大、长上下文性能下降和高成本而捉襟见肘。激进的压缩会导致不可逆的信息丢失。
解决方案: 将文件系统视为终极上下文——无限、持久且可由代理直接操作。模型学会按需读写文件，将其用作结构化的外部记忆。
现象: Manus在处理复杂任务时，会创建一个todo.md文件，并随着任务进展不断更新它。
机制: 这是一种刻意的注意力操控。通过在上下文末尾不断重写（复述）目标，将全局计划推入模型的近期注意力范围，避免“迷失在中间”和目标漂移。
实现: 压缩策略设计为“可恢复”的。例如，从上下文中移除网页内容但保留URL，或省略文档内容但保留其路径，从而在不丢失信息的情况下缩短上下文。
问题: LLM是强大的模仿者。如果上下文中充满了相似的“少样本”示例，模型会陷入遵循旧模式的陷阱，即使这已不是最优解，从而导致过度泛化或幻觉。
解决方案: 增加多样性。在行动和观察中引入受控的随机性（如不同的序列化模板、措辞、微小噪音），以打破模式并调整模型注意力。
现实: 代理会犯错，失败是循环的一部分，而非例外。
解决方案: 将错误的尝试及其结果（如堆栈跟踪）保留在上下文中。这能隐式地更新模型的内部信念，降低其重复犯错的概率。
错误冲动: 隐藏或清理错误会移除模型赖以学习和适应的证据。
结论
上下文工程是构建智能体必不可少的科学。你如何塑造上下文（记忆、环境、反馈）最终决定了你的智能体的行为方式：它运行的速度、恢复的效果以及扩展的范围。