MANUS 上下文工程经验
https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
中文版的是低级的机翻。这个是使用GPT4.1的翻译结果，并加上了富文本标记。
Manus 上下文工程经验
背景与抉择
在项目伊始，我和我的团队面临一个关键决策：我们是要基于开源基础训练端到端的智能体模型，还是要在前沿大模型的能力之上构建智能体？
回想我在NLP领域的第一个十年，我们根本没有这种选择的奢侈。在遥远的（是的，已经七年了）年代，模型必须经过微调和评估，才能迁移到新任务。即使模型体量远小于今天的LLM，每次迭代也常常需要数周。对于快速迭代的应用，尤其是PMF（产品市场契合）前阶段，这种缓慢的反馈循环简直是致命的。这是我上一家创业公司痛苦的教训——我曾为和语义搜索从零训练模型。后来，和出现了，我自研的模型一夜之间变得无关紧要。讽刺的是，正是这些模型开启了in-context learning（上下文学习）的时代，也带来了全新的发展路径。
这个惨痛的教训让选择变得清晰：Manus要押注于上下文工程。
这让我们能在数小时内发布改进，而不是数周，并且让我们的产品与底层模型解耦：如果模型进步是潮水，我们希望Manus是船，而不是被困在海床的柱子。
然而，上下文工程远非易事。这是一门实验科学——我们已经重构了四次智能体框架，每次都是在发现更好的上下文塑造方式后。我们戏称这种架构搜索、提示调优和经验性猜测的手工过程为“随机研究生下降法（Stochastic Graduate Descent）”。它不优雅，但确实有效。
这篇文章分享了我们通过“SGD”走到的局部最优解。如果你也在构建AI智能体，希望这些原则能帮你更快收敛。
围绕KV-Cache设计
如果只能选一个指标，我认为KV-cache命中率是生产级AI智能体最重要的指标。它直接影响延迟和成本。
为什么？
收到用户输入后，智能体会通过一系列工具链完成任务。每次迭代，模型会根据当前上下文从预定义的动作空间中选择一个动作，然后在环境中（如Manus的虚拟机沙箱）执行该动作，产生观察结果。动作和观察会被追加到上下文中，作为下一轮的输入。如此循环，直到任务完成。
可以想象，随着每一步推进，上下文会不断增长，而输出（通常是结构化的函数调用）却很短。这导致智能体的预填充与解码比例远高于聊天机器人。例如在Manus中，输入与输出的token比例大约是100:1。
幸运的是，拥有相同前缀的上下文可以利用缓存，大幅降低首token延迟（TTFT）和推理成本——无论你用的是自托管模型还是API。
节省可不是小数目：以Claude Sonnet为例，缓存输入token的费用是
0.30美元/百万token，未缓存则是3美元/百万token，相差10倍。
提高KV-cache命中率的关键做法：
- 保持提示前缀稳定。 由于LLM的缓存特性，哪怕只差一个token，后续缓存都会失效。常见错误是把时间戳（尤其是精确到秒的）放在system prompt开头。这样虽然能让模型报时，但会极大降低缓存命中率。
- 让上下文只追加，不要修改之前的动作或观察。 确保序列化是确定性的。许多编程语言和库在序列化JSON对象时不保证键顺序稳定，这会悄悄破坏缓存。
- 需要时显式标记缓存断点。 有些模型服务商或推理框架不支持自动增量前缀缓存，需要手动在上下文中插入缓存断点。分配断点时要考虑缓存过期，至少要确保断点包含system prompt结尾。
- 分布式一致性。 如果你用如vLLM这样的框架自托管模型，务必开启KV-cache，并用session ID等技术确保请求在分布式worker间一致路由。
使用掩码，不要移除
随着智能体能力增强，动作空间自然变得更复杂——说白了，就是工具数量爆炸。最近Function Calling的流行更是火上浇油。如果你允许用户自定义工具，相信我：总有人会往你的动作空间塞进上百个神秘工具。结果就是模型更容易选错动作或走弯路。武装到牙齿的智能体反而变笨了。
直觉反应是设计动态动作空间——比如用插件机制类似的方式按需加载工具。我们在Manus也试过。但实验表明：
除非万不得已，避免在迭代中动态增删工具。
原因有二：
- 大多数LLM在序列化后，工具定义都在上下文前部，通常在system prompt前后。任何变动都会让后续动作和观察的KV-cache全部失效。
- 如果之前的动作和观察还引用了当前上下文已不存在的工具，模型会困惑。没有一致性，常常导致schema违规或幻觉动作。
解决方案：
Manus用上下文感知的掩码进行工具可用性管理。不是移除工具，而是在解码时掩码token logits，根据当前上下文阻止（或强制）某些动作被选中。
实际上，大多数模型服务商和推理框架都支持某种形式的响应预填充，可以在不修改工具定义的情况下约束动作空间。
函数调用一般有三种模式（以NousResearch的为例）：
Auto——模型可选择是否调用函数。只预填充回复前缀：<|im_start|>assistantRequired——模型必须调用函数，但选择不受限。预填充到工具调用token：<|im_start|>assistant<tool_call>Specified——模型必须从特定子集调用函数。预填充到函数名开头：<|im_start|>assistant<tool_call>{"name": “browser_”}
借此，我们直接通过掩码token logits约束动作选择。例如，用户有新输入时，Manus必须立即回复而不是执行动作。我们还特意让动作名有统一前缀——如所有浏览器相关工具以browser_开头，命令行工具以shell_开头。这样无需有状态logits处理器，也能轻松限定某一状态下只能选某类工具。
这些设计确保了Manus智能体循环即使在模型驱动架构下也能稳定运行。
用文件系统做上下文
现代前沿LLM的上下文窗口已达128K token甚至更大。但在真实智能体场景下，这往往还不够，有时甚至是负担。常见三大痛点：
- 观察结果可能很大，尤其是处理网页、PDF等非结构化数据时，很容易超出上下文上限。
- 模型性能在超长上下文下往往下降，即使窗口理论上支持。
- 长输入即使有前缀缓存也很贵——每个token都要传输和预填充。
为此，许多智能体系统实现了上下文截断或压缩策略。但压缩过度必然丢失信息。问题本质在于：智能体必须基于所有历史状态预测下一步——你无法预知哪条观察十步后会变得关键。 从逻辑上讲，任何不可逆的压缩都有风险。
我们的做法：
我们在Manus把文件系统视为终极上下文：容量无限、天然持久、智能体可直接操作。模型学会按需读写文件——把文件系统当作结构化、外部化的记忆，而不仅仅是存储。
我们的压缩策略始终可还原。例如，网页内容可以从上下文中移除，只要保留URL；文档内容可以省略，只要沙箱里有路径。这样Manus能缩短上下文长度而不永久丢失信息。
开发这个特性时，我常常想象：如果状态空间模型（SSM）能在智能体场景下有效工作，需要什么？与Transformer不同，SSM没有全局注意力，难以处理长距离依赖。但如果能掌握基于文件的记忆——把长期状态外部化而不是全放上下文里——它们的速度和效率或许能催生新一代智能体。Agentic SSMs或许才是真正的继任者。
用复述操控注意力
用过Manus的朋友可能注意到一个有趣现象：处理复杂任务时，它会创建一个todo.md文件，并在任务推进时逐步更新，勾掉已完成项。
这不是可爱行为，而是有意为之的注意力操控机制。
Manus平均每个任务要调用约50次工具。循环很长——而且Manus依赖LLM决策，容易在长上下文或复杂任务中跑题或忘记早期目标。
通过不断重写todo清单，Manus把目标复述到上下文末尾。这样全局计划就进入了模型的近期注意力范围，避免“中间丢失”问题，减少目标偏移。实质上，它用自然语言把注意力偏向任务目标，无需特殊架构改动。
把错误留在上下文里
智能体会犯错。这不是bug，而是现实。大模型会幻觉，环境会报错，外部工具会失灵，边界情况随时出现。多步任务中，失败不是例外，而是常态。
但常见冲动是隐藏这些错误：清理trace、重试动作，或重置模型状态交给“魔法”。这样看似更安全可控，但代价是：抹去失败就抹去了证据。没有证据，模型无法适应。
我们的经验是，提升智能体行为最有效的方式之一其实很简单：把错误路径留在上下文里。模型看到失败的动作和对应的观察或堆栈后，会隐式更新内部信念，减少重复同类错误的概率。
事实上，我们认为错误恢复是智能体行为最清晰的标志之一。但在学术界和公开基准中，这一能力仍被低估，大家更关注理想条件下的任务成功率。
别被few-shot困住
few-shot是提升LLM输出的常用技巧。但在智能体系统中，可能会带来微妙的副作用。
大模型是优秀的模仿者，会复制上下文中的行为模式。如果上下文里充满了类似的历史动作-观察对，模型就会倾向于重复这种模式，即使它已不再最优。
这在需要重复决策的任务中尤其危险。例如用Manus批量审阅20份简历时，智能体常常陷入节奏——只是因为上下文里都是类似操作，就不断重复，导致漂移、过度泛化甚至幻觉。
解决办法：
Manus在动作和观察中引入少量结构化变化——不同的序列化模板、不同表述、顺序或格式上的微小噪声。这种受控随机性能打破模式，微调模型注意力。
换句话说，别让few-shot把自己困死。上下文越单一，智能体越脆弱。
结语
上下文工程仍是一门新兴科学，但对智能体系统来说已是必需。模型越来越强大、快速、便宜，但再强的能力也无法替代记忆、环境和反馈。你如何塑造上下文，最终决定了智能体的行为：速度、恢复力和可扩展性。
浙公网安备 33010602011771号