<p align="right"><font color="#3f3f3f">2025年07月19日</font></p> > 原文链接：[AI代理的上下文工程：构建Manus的经验教训](https://manus.im/zh-cn/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) ## 文章概述 作者Yichao 'Peak' Ji分享了构建AI代理产品Manus过程中在上下文工程方面的实践经验。这是一篇技术经验总结，重点讨论了如何通过优化上下文设计来提升AI代理的性能。 ## 核心决策：选择上下文学习而非端到端训练 ### 关键观点 作者团队选择基于前沿模型的上下文学习能力构建代理，而非从开源基础模型训练端到端的代理模型。 ### 注解与理解 **历史背景**：在BERT时代（2018年），模型需要针对每个新任务进行微调，这个过程通常需要数周时间。作者在上一个创业项目中就遭遇了这种缓慢的反馈循环问题。 **技术转折点**：GPT-3和Flan-T5的出现标志着上下文学习时代的开始，使得无需训练即可适应新任务成为可能。 **实用考量**：选择上下文学习的核心原因是迭代速度——从数周缩短到数小时。这对于尚未达到产品市场契合度(PMF)的快速迭代产品至关重要。 **形象比喻**：作者用"潮水和船"比喻模型进步与产品的关系——如果模型进步是涨潮，那么产品应该是随潮水上升的船，而不是固定在海底的柱子。 ## 核心原则1：围绕KV-Cache设计 ### 技术原理 KV-cache是大语言模型推理优化的关键技术，通过缓存相同前缀的键值对来减少重复计算。 ### 重要性量化 - **成本差异**：以Claude Sonnet为例，缓存的输入tokens成本为0.30美元/百万tokens，未缓存的成本为3美元/百万tokens——10倍差异 - **使用模式**：在Manus中，平均输入输出token比例约为100:1，这使得缓存优化变得极其重要 ### 实践策略 **1. 保持提示前缀稳定** - **常见错误**：在系统提示开头包含精确到秒的时间戳 - **问题根源**：由于LLM的自回归特性，即使单个token的差异也会使该token之后的整个缓存失效 - **实用建议**：如果需要时间信息，考虑放在提示的末尾或使用相对稳定的时间格式 **2. 确保上下文仅追加** - **避免修改**：不要修改之前的动作或观察结果 - **序列化一致性**：确保JSON对象的键值顺序稳定（许多编程语言的序列化库不保证键的顺序） - **技术细节**：这种不一致会悄无声息地破坏缓存效果 **3. 明确标记缓存断点** - **应用场景**：某些模型提供商或推理框架不支持自动增量前缀缓存 - **最低要求**：确保断点至少包含系统提示的结尾 - **考虑因素**：需要考虑潜在的缓存过期问题 ## 核心原则2：掩码而非移除工具 ### 问题背景 随着代理能力扩展，工具数量急剧增长。特别是用户可配置工具的情况下，可能会有数百个工具被加入到动作空间中。 ### 动态工具管理的问题 **1. 缓存失效** - **技术原因**：工具定义通常位于上下文前部（系统提示前后），任何变更都会使后续所有动作和观察的KV-cache失效 - **性能影响**：这种失效会显著增加推理时间和成本 **2. 上下文不一致** - **具体问题**：当之前的动作和观察仍然引用已不再定义的工具时，模型会产生困惑 - **后果**：在没有约束解码的情况下，这通常导致架构违规或幻觉动作 ### Manus的解决方案：状态机+掩码 **技术实现**：使用上下文感知的状态机管理工具可用性，通过掩码token logits来阻止或强制选择特定动作。 **响应预填充技术**： - **Auto模式**：模型可选择调用或不调用函数 - **Required模式**：模型必须调用函数，但选择不受限制 - **Specified模式**：模型必须从特定子集中调用函数 **命名规范策略**： - **前缀设计**：所有浏览器相关工具以`browser_`开头，命令行工具以`shell_`开头 - **实用优势**：允许轻松强制代理仅从特定工具组中选择，无需使用有状态的logits处理器 ## 核心原则3：文件系统作为上下文 ### 现有方案的局限性 **上下文窗口问题**： - **容量限制**：虽然现代前沿LLM提供128K+tokens的上下文窗口，但在真实代理场景中往往不够 - **性能衰减**：模型性能在超过特定上下文长度后会下降 - **成本问题**：长输入成本高昂，即使有前缀缓存 **传统压缩方案的风险**： - **信息丢失**：过度压缩不可避免地导致信息丢失 - **预测困难**：无法预测哪个观察结果在十步之后可能变得关键 - **逻辑风险**：任何不可逆的压缩都存在风险 ### Manus的文件系统方案 **核心理念**：将文件系统视为终极上下文——无限大小、天然持久、可直接操作。 **可恢复压缩策略**： - **网页内容**：只要保留URL，就可以丢弃网页内容 - **文档内容**：只要保留沙箱中的路径，就可以省略文档内容 - **优势**：在不永久丢失信息的情况下缩减上下文长度 **对未来架构的思考**： 作者推测，如果状态空间模型(SSM)能够掌握基于文件的内存——将长期状态外化而非保持在上下文中——那么它们的速度和效率优势可能会开启新一类代理。代理式SSM可能是神经图灵机的真正继承者。 ## 核心原则4：通过复述操控注意力 ### 观察到的行为模式 Manus在处理复杂任务时会创建`todo.md`文件，并在任务进展过程中逐步更新，勾选已完成的项目。 ### 技术原理 **注意力机制问题**： - **任务复杂性**：Manus中的典型任务平均需要约50次工具调用 - **注意力漂移**：在长上下文或复杂任务中，模型容易偏离主题或忘记早期目标 - **"迷失在中间"问题**：长序列中间的信息容易被忽略 **复述机制的作用**： - **强化目标**：通过不断重写todo列表，将目标复述到上下文的末尾 - **注意力引导**：将全局计划推入模型的近期注意力范围 - **自然语言偏置**：使用自然语言来引导模型关注任务目标，无需特殊架构变更 ## 核心原则5：保留错误信息 ### 常见的错误处理误区 传统做法倾向于隐藏错误：清理跟踪记录、重试动作或重置模型状态。这种做法看似更安全、更可控，但代价是消除了证据。 ### 错误作为学习材料的价值 **学习机制**： - **隐式更新**：当模型看到失败的动作及其结果观察或堆栈跟踪时，会隐式更新其内部信念 - **先验调整**：这会使其先验远离类似动作，降低重复相同错误的概率 - **适应能力**：错误恢复是真正代理行为的最清晰指标之一 **实践建议**：将错误轨迹保留在上下文中，让模型从失败中学习。 ### 学术研究的不足 作者指出，错误恢复在大多数学术工作和公共基准测试中仍然代表性不足，这些测试往往关注理想条件下的任务成功。 ## 核心原则6：避免Few-shot陷阱 ### Few-shot提示的副作用 **模仿本性**：语言模型是优秀的模仿者，它们会模仿上下文中的行为模式。如果上下文充满了相似的过去动作-观察对，模型会倾向于遵循该模式，即使不再是最优选择。 **危险场景**： - **重复决策任务**：当使用Manus帮助审查20份简历时，代理经常陷入节奏——仅仅因为在上下文中看到了这种模式就重复类似的动作 - **负面后果**：导致漂移、过度泛化或有时出现幻觉 ### 解决方案：增加多样性 **结构化变化**： - **序列化模板**：使用不同的序列化模板 - **表述变化**：采用替代措辞 - **格式噪声**：在顺序或格式上引入轻微噪声 **受控随机性**：这种受控的随机性有助于打破模式并调整模型的注意力。 **核心原则**：上下文越统一，代理就越脆弱。 ## 总结与思考 ### 上下文工程的本质 作者将上下文工程描述为一门新兴科学，对代理系统来说已经是必需的。无论模型变得多么强大、快速和便宜，都无法替代对内存、环境和反馈的需求。 ### 迭代学习的重要性 Manus团队通过反复重写、死胡同和数百万用户的真实世界测试学到了这些经验。作者强调这些不是普遍真理，而是对他们有效的模式。 ### 实践哲学 文章以"Stochastic Graduate Descent"（随机梯度下降）来形容他们的手动架构搜索、提示调整和经验猜测过程——不够优雅，但确实有效。 ### 未来展望 作者以"代理的未来将一次一个上下文地构建"结尾，强调了上下文工程在AI代理开发中的基础性作用。 ## 关键技术概念补充 **KV-Cache**：键值缓存，是Transformer架构中的优化技术，通过缓存之前计算的键值对来避免重复计算。 **约束解码**：限制模型输出必须符合特定格式或结构的技术。 **状态空间模型(SSM)**：一种不同于Transformer的神经网络架构，在处理长序列时具有效率优势，但缺乏完全注意力机制。 **响应预填充**：在模型生成响应之前预先填充部分内容，用于引导或约束输出格式。