价值千万！Manus技术精华：如何高效构建 AI智能体的上下文工程？

Manus 官网周末更新了一篇文章，分享了他们为 Manus 搭建合适的上下文工程的经验教训。作者季逸超 (Peak)，Manus 公司联合创始人、首席科学家。

原文需要魔法去看，且是英文，网站的中文翻译很差，我用Claude4翻译一遍，学习完，再总结了技术要点，希望对大家有帮助！

而且我没想到的是，最核心的竟然是KV cache，这个我熟啊！泪流满面，后端工程师的第二春？第一个技术核心点像是后端的JD哈哈！

省流版全文核心技术要点

1. 1. KV-Cache优化策略（这个很关键）（后端工程师看到了自己的熟悉领域和价值！）
   问题核心：Agent的输入输出比例严重不平衡（100:1），前缀填充成本巨大
   解决方案：
   保持prompt前缀稳定（别在开头加时间戳，你们这些新手老爱犯这错误！）
   确保上下文只追加，不修改
   显式标记缓存断点
   成本影响：缓存命中可降低10倍成本（Claude: 0.30 vs 3 USD/MTok）

2. 2. 工具空间管理（掩码策略）
   核心思想："掩码，不要删除"
   技术实现：使用响应预填充约束动作空间
   Auto模式：<|im_start|>assistant
   Required模式：<|im_start|>assistant
   Specified模式：<|im_start|>assistant{"name": "browser_
   避免的坑：动态添加/删除工具会破坏KV缓存且让模型困惑

3. 3. 文件系统作为上下文存储
   痛点：128K token窗口在真实场景下不够用，且性能下降、成本高
   解决思路：将文件系统作为无限大、持久化的上下文
   压缩策略：可恢复性压缩（保留URL/文件路径，内容可重新获取）

4. 4. 注意力操控机制
   实现方式：通过todo.md文件持续更新任务列表
   技术原理：将全局计划"背诵"到上下文末尾，避免"迷失在中间"问题
   效果：50步平均任务中保持目标对齐

5. 5. 错误保留策略
   反直觉做法：保留错误trace而不是清理
   技术依据：让模型从失败中学习，更新内部先验
   实际效果：错误恢复是真正智能体行为的标志

6. 6. 反Few-shot策略
   问题：过度相似的示例会让模型陷入模式固化
   解决：引入结构化多样性，打破模式，增加序列化变化
   技术含量评估

   高价值点：
   KV-Cache优化策略非常实用，直击生产环境痛点
   工具空间管理的掩码方法很巧妙
   文件系统作为外部记忆的思路有创新性

7. 一般性观点：
   错误保留、反Few-shot等更多是经验总结
   缺乏定量evaluation和对比实验

全文翻译：

AI智能体的上下文工程：构建Manus的经验教训

2025年7月18日 - Yichao 'Peak' Ji

在Manus项目的初期，我和团队面临一个关键决策：是基于开源基础模型训练端到端的智能体模型，还是在前沿模型的上下文学习能力之上构建智能体？

回顾我在NLP领域的第一个十年，我们没有这样的选择权。在遥远的BERT时代（是的，已经过去七年了），模型必须经过微调和评估才能迁移到新任务。这个过程每次迭代都需要数周时间，尽管那时的模型相比今天的大语言模型来说非常小。对于快速发展的应用，特别是在产品市场契合（PMF）之前，如此缓慢的反馈循环是致命的。这是我上一家初创公司的痛苦教训，当时我从零开始训练开放信息抽取和语义搜索模型。然后GPT-3和Flan-T5横空出世，我的内部模型一夜之间变得毫无意义。讽刺的是，正是这些模型标志着上下文学习时代的开始——以及一条全新的发展道路。

这个惨痛的教训让选择变得明确：Manus将押注上下文工程。这让我们能够在几小时而非几周内发布改进，并保持产品与底层模型的正交性：如果模型进步是涨潮，我们希望Manus是船，而不是固定在海底的柱子。

然而，上下文工程远非直截了当。这是一门实验科学——我们已经重构了四次智能体框架，每次都是在发现更好的上下文塑造方法之后。我们亲切地将这种架构搜索、提示调优和经验猜测的手动过程称为"随机研究生下降"。这不优雅，但有效。

本文分享我们通过自己的"SGD"（"Stochastic Gradient Descent"（随机梯度下降，SGD），网站中文翻译是"随机研究生下降" 。。。）达到的局部最优解。如果你正在构建自己的AI智能体，我希望这些原则能帮助你更快收敛。

围绕KV-Cache设计

如果我必须选择一个指标，我认为KV缓存命中率是生产级AI智能体最重要的单一指标。它直接影响延迟和成本。要理解原因，让我们看看典型智能体的运作方式：

接收用户输入后，智能体通过一系列工具使用来完成任务。在每次迭代中，模型基于当前上下文从预定义的动作空间中选择一个动作。该动作随后在环境中执行（例如Manus的虚拟机沙箱）以产生观察结果。动作和观察被追加到上下文中，形成下一次迭代的输入。这个循环持续到任务完成。

可以想象，上下文随着每一步增长，而输出——通常是结构化的函数调用——相对较短。这使得智能体中前缀填充和解码之间的比例相比聊天机器人严重倾斜。例如，在Manus中，平均输入输出令牌比约为100:1。

幸运的是，具有相同前缀的上下文可以利用KV缓存，这大大减少了首令牌时间（TTFT）和推理成本——无论你使用自托管模型还是调用推理API。我们谈论的不是小额节省：以Claude Sonnet为例，缓存输入令牌成本为0.30美元/百万令牌，而未缓存的成本为3美元/百万令牌——相差10倍。

从上下文工程的角度来看，提高KV缓存命中率涉及几个关键实践：

1. 1. 保持提示前缀稳定 ：由于LLM的自回归性质，即使单个令牌的差异也会使从该令牌开始的缓存失效。一个常见错误是在系统提示开头包含时间戳——特别是精确到秒的时间戳。确实，这让模型能告诉你当前时间，但也会杀死你的缓存命中率。

2. 2. 使上下文仅追加 ：避免修改之前的动作或观察。确保序列化是确定性的。许多编程语言和库在序列化JSON对象时不保证稳定的键排序，这可能悄无声息地破坏缓存。

3. 3. 在需要时显式标记缓存断点 ：一些模型提供商或推理框架不支持自动增量前缀缓存，而是需要在上下文中手动插入缓存断点。分配这些断点时，要考虑潜在的缓存过期，至少确保断点包含系统提示的结尾。

此外，如果你使用vLLM等框架自托管模型，确保启用前缀/提示缓存，并使用会话ID等技术在分布式工作器间一致路由请求。

掩码，不要删除

随着智能体承担更多能力，其动作空间自然变得更加复杂——简言之，工具数量爆炸性增长。最近MCP的流行只是火上浇油。如果你允许用户配置工具，相信我：总有人会将数百个神秘工具插入你精心策划的动作空间。结果，模型更可能选择错误动作或采取低效路径。简而言之，你的重装智能体变笨了。

自然反应是设计动态动作空间——也许使用类似RAG的方式按需加载工具。我们在Manus中也尝试过。但我们的实验表明一个明确规则：除非绝对必要，避免在迭代中动态添加或删除工具。主要有两个原因：

1. 1. 在大多数LLM中，工具定义在序列化后位于上下文前端附近，通常在系统提示之前或之后。因此任何更改都会使所有后续动作和观察的KV缓存失效。

2. 2. 当之前的动作和观察仍然引用当前上下文中不再定义的工具时，模型会困惑。没有约束解码，这通常导致模式违规或幻觉动作。

为了解决这个问题同时仍然改进动作选择，Manus使用上下文感知状态机来管理工具可用性。我们不删除工具，而是在解码期间掩码令牌logits来防止（或强制）基于当前上下文选择某些动作。

在实践中，大多数模型提供商和推理框架支持某种形式的响应预填充，这允许在不修改工具定义的情况下约束动作空间。通常有三种函数调用模式（我们使用NousResearch的Hermes格式作为例子）：

• 自动 – 模型可以选择调用函数或不调用。通过仅预填充回复前缀实现：<|im_start|>assistant

• 必需 – 模型必须调用函数，但选择不受约束。通过预填充到工具调用令牌实现：<|im_start|>assistant

• 指定 – 模型必须从特定子集调用函数。通过预填充到函数名开头实现：<|im_start|>assistant {"name": "browser_

使用这个，我们通过直接掩码令牌logits来约束动作选择。例如，当用户提供新输入时，Manus必须立即回复而不是采取动作。我们还故意设计了具有一致前缀的动作名称——例如，所有浏览器相关工具以browser_开头，命令行工具以shell_开头。这让我们能够轻松强制智能体只从给定状态的某个工具组中选择，而无需使用有状态的logits处理器。

这些设计有助于确保Manus智能体循环保持稳定——即使在模型驱动的架构下。

使用文件系统作为上下文

现代前沿LLM现在提供128K令牌或更多的上下文窗口。但在现实世界的智能体场景中，这通常不够，有时甚至是负担。有三个常见痛点：

1. 1. 观察可能很庞大，特别是当智能体与网页或PDF等非结构化数据交互时。很容易超过上下文限制。

2. 2. 模型性能往往在超过某个上下文长度后下降，即使窗口技术上支持它。

3. 3. 长输入很昂贵，即使有前缀缓存。你仍然要为传输和预填充每个令牌付费。

为了应对这个问题，许多智能体系统实施上下文截断或压缩策略。但过于激进的压缩不可避免地导致信息丢失。问题是根本性的：智能体本质上必须基于所有先前状态预测下一个动作——而你无法可靠预测哪个观察在十步后可能变得关键。从逻辑角度看，任何不可逆压缩都有风险。

这就是为什么我们将文件系统视为Manus的终极上下文：大小无限、本质持久，并且智能体本身可以直接操作。模型学会按需写入和读取文件——将文件系统不仅用作存储，还用作结构化的外部化记忆。

我们的压缩策略总是设计为可恢复的。例如，只要保留URL，网页内容就可以从上下文中删除，只要路径在沙箱中仍然可用，文档内容就可以省略。这允许Manus缩短上下文长度而不永久丢失信息。

在开发这个功能时，我发现自己在想象状态空间模型（SSM）在智能体设置中有效工作需要什么。与Transformer不同，SSM缺乏完全注意力并且在长程反向依赖方面有困难。但如果它们能掌握基于文件的记忆——外部化长期状态而不是在上下文中保持——那么它们的速度和效率可能解锁新一类智能体。智能体SSM可能是神经图灵机的真正继承者。

通过背诵操控注意力

如果你使用过Manus，你可能注意到一些奇怪的事情：处理复杂任务时，它倾向于创建todo.md文件——并随着任务进展逐步更新，勾选完成的项目。

这不仅仅是可爱的行为——这是操控注意力的刻意机制。

Manus中的典型任务平均需要约50个工具调用。这是一个长循环——由于Manus依赖LLM进行决策，它容易偏离主题或忘记早期目标，特别是在长上下文或复杂任务中。

通过不断重写待办事项列表，Manus将其目标背诵到上下文末尾。这将全局计划推入模型的近期注意力范围，避免"迷失在中间"问题并减少目标错位。实际上，它使用自然语言偏向自己对任务目标的关注——无需特殊架构变更。

保留错误内容

智能体会犯错误。这不是缺陷——这是现实。语言模型会产生幻觉，环境返回错误，外部工具行为异常，意外边缘情况时常出现。在多步任务中，失败不是例外；它是循环的一部分。

然而，一个常见冲动是隐藏这些错误：清理跟踪，重试动作，或重置模型状态并寄希望于神奇的"温度"。这感觉更安全、更可控。但这是有代价的：抹除失败就是移除证据。没有证据，模型无法适应。

根据我们的经验，改进智能体行为最有效的方法之一出人意料地简单：在上下文中保留错误转向。当模型看到失败动作——以及结果观察或堆栈跟踪——它隐式更新其内部信念。这将其先验从类似动作中转移，减少重复同样错误的机会。事实上，我们相信错误恢复是真正智能体行为最清晰的指标之一。然而，它在大多数学术工作和公共基准中仍然代表性不足，这些通常关注理想条件下的任务成功。

不要陷入Few-shot陷阱

Few-shot提示是改进LLM输出的常见技术。但在智能体系统中，它可能以微妙的方式适得其反。

语言模型是优秀的模仿者；它们模仿上下文中的行为模式。如果你的上下文充满相似的过去动作-观察对，模型会倾向于遵循那个模式，即使不再是最优的。

这在涉及重复决策或动作的任务中可能很危险。例如，使用Manus帮助审查一批20份简历时，智能体经常陷入节奏——重复相似动作仅仅因为这是它在上下文中看到的。这导致漂移、过度泛化或有时产生幻觉。

解决方案是增加多样性。Manus在动作和观察中引入少量结构化变化——不同的序列化模板、替代措辞、顺序或格式的轻微噪声。这种受控随机性有助于打破模式并调整模型注意力。换句话说，不要让few-shot把自己困在老路上。你的上下文越统一，你的智能体就越脆弱。

结论

上下文工程仍然是一门新兴科学——但对智能体系统来说，它已经是必需的。模型可能变得更强、更快、更便宜，但再多的原始能力也无法替代对记忆、环境和反馈的需求。你如何塑造上下文最终定义了你的智能体如何行为：运行多快、恢复多好、扩展多远。

在Manus，我们通过反复重写、死胡同和跨数百万用户的真实世界测试学到了这些教训。我们在这里分享的都不是普遍真理——但这些是对我们有效的模式。如果它们能帮助你避免哪怕一次痛苦的迭代，那么这篇文章就完成了它的使命。

智能体的未来将一次一个上下文地构建。好好工程化它们。

参考链接：Context Engineering for AI Agents: Lessons from Building Manus ， https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

回复【智能体】，讨论研究智能体技术、智能体平台和智能体搞钱。

其实后端工程师转型AI专家，有很多成功的例子。下一篇，我打算写一下Gemini的研发之路，聊聊Jeff Dean是如何从掌舵谷歌的大数据三驾马车核心基础设施研发，转型到谷歌大脑负责人，做出Gemini这样能跟chatGPT抗衡的AI多模态神器。Jeff Dean，YYDS！

我是刀哥，大厂架构师，出海创业者，深入研究AI工具和AI编程。关注我，了解更多AI知识！