深入解析Manus的“上下文工程”实战心法

在构建高级AI代理的征途上，一个核心问题摆在所有架构师面前：是投入漫长的周期去端到端地训练一个新模型，还是在现有前沿模型强大的“上下文学习”能力之上构建代理？Manus团队选择了后者，并由此深入到一个新兴但至关重要的领域——上下文工程 (Context Engineering)。

这篇文章将深入剖析Manus团队在反复迭代和实践中沉淀下的核心经验。这些原则不仅是技术选型的结果，更是对如何与大型语言模型（LLM）高效协同，构建出稳定、智能且可扩展代理的深刻洞察。

原则一：围绕KV-Cache进行设计——性能与成本的命脉

对于生产级的AI代理而言，KV-Cache命中率是衡量其性能与成本效益的黄金指标。 代理的工作模式是“思考-行动”循环：接收上下文、选择工具、执行、获得观察结果，然后将行动与结果追加到上下文中，开启下一轮循环。 这导致输入上下文的长度远超输出（在Manus中，输入输出Token比例高达100:1），因此，能否利用KV-Cache（一种能缓存相同上下文前缀计算结果的技术）直接决定了代理的响应速度和推理成本。

Manus的实践总结出三大关键准则：

  1. 保持提示词前缀的绝对稳定：任何微小的变动，哪怕是精确到秒的时间戳，都会导致后续缓存全部失效。
  2. 确保上下文的“只增”特性：避免修改历史记录，并确保序列化方法（如JSON）的输出顺序是确定性的，以防无形中破坏缓存。
  3. 在必要时显式标记缓存断点：当模型或框架不支持自动增量缓存时，需要手动指定缓存的终点，至少要包含系统提示词的末尾。

原则二：掩蔽而非移除——动态工具集的优雅管理

随着代理能力增强，其工具集会急剧膨胀。一个自然的冲动是动态地从上下文中增删工具，但这是一种“陷阱”。 Manus的实验表明，动态修改工具集会产生两大问题：

  1. 缓存失效：工具定义通常位于上下文前部，任何改动都会使其后的KV-Cache完全失效。
  2. 模型混淆：当历史记录中引用的工具在当前上下文中消失时，模型会感到困惑，容易产生格式错误或幻觉。

更优越的策略是**“掩蔽”（Masking）**。 Manus利用一个上下文感知的状态机，在不改变工具定义的前提下，通过在解码阶段“掩蔽”特定Token的Logits，来动态禁止或强制模型选择某些工具。 例如，通过为浏览器工具设置browser_前缀，为命令行工具设置shell_前缀，就可以在特定状态下，轻松地将模型的选择范围约束在某一类工具中，既保证了灵活性，又维持了上下文的稳定性。

原则三：视文件系统为终极上下文——突破窗口限制的“外存”

即便拥有百万级Token的上下文窗口，在真实的代理场景中也常常捉襟见肘。 巨大的观察结果（如网页、PDF内容）能轻易撑爆窗口，并且过长的上下文不仅会降低模型性能，还会带来高昂的成本。

对此，Manus的解决方案是将文件系统视为终极上下文。它容量无限、本质持久，且能被代理直接操作。 模型被教会按需读写文件，从而将文件系统用作一种结构化的外部记忆体。 这种策略下的上下文压缩是无损且可逆的：网页内容可以被其URL替代，文档内容可以被其路径替代，当需要时，代理可以随时从“外存”中恢复信息。 这种设计让代理在不丢失信息的前提下，极大地缩减了上下文长度。

原则四：通过“复述”操纵注意力——让代理保持专注

你可能会观察到Manus在处理复杂任务时，会反复地创建和更新一个名为todo.md的文件。 这并非装饰性行为，而是一种精巧的注意力操纵机制。

长任务链（平均超过50次工具调用）很容易让LLM“中途迷失”，忘记最初的目标。 通过在每一轮循环的末尾重写待办事项列表，Manus相当于在不断地向模型“复述”其核心目标。 这将全局计划推向了模型注意力的最前沿，有效对抗了“迷失在中间”（lost-in-the-middle）的问题，确保了代理行为与最终目标的一致性。

原则五：保留失败记录——从错误中学习的关键

代理会犯错，这是无法回避的现实。 许多开发者倾向于隐藏这些错误：清理失败轨迹、重试操作，试图呈现一个完美的执行路径。但这剥夺了模型最宝贵的学习机会。

Manus的经验恰恰相反：将错误、异常和失败的尝试完整地保留在上下文中。 当模型看到一个失败的动作及其返回的错误堆栈时，它会隐式地更新其内部认知，从而在后续决策中降低采取类似错误行动的概率。 这种从失败中恢复的能力，是衡量真正“智能体”行为的关键指标，远比在理想条件下一次性成功更有价值。

原则六：警惕“少样本陷阱”——以多样性破除行为僵化

少样本提示（Few-shot Prompting）是LLM的常用技巧，但在代理系统中可能适得其反。 LLM是强大的模仿者，如果上下文中充满了高度相似的“动作-观察”范例，模型会陷入机械重复的“节奏”中，即便当前情况需要改变策略。

为了打破这种行为僵化，Manus的对策是为上下文引入结构化的多样性。 通过在序列化模板、措辞、格式或顺序上引入微小的、受控的随机性，可以有效“扰动”模型的注意力，打破固化模式，使其保持灵活性和适应性。 简而言之，不要让你的代理被自己过去的成功经验“少样本”地困住。

结论：上下文是代理的未来

上下文工程是一门新兴的、以实验为导向的科学。 模型的基座能力在飞速发展，但无论模型多强大，它始终需要通过上下文来理解记忆、环境和反馈。 你如何设计上下文，最终决定了你的代理如何思考、如何行动、如何从失败中学习，以及它能走多远。 Manus团队通过四次重构和海量测试总结的这些经验，为所有AI代理的构建者提供了宝贵的“捷径”，帮助我们更好地驾驭这股AI浪潮，一次一个上下文，精心构建智能的未来。

参考文档

欢迎关注+点赞+推荐+转发