Manus 内部的 Context 工程经验（精校、高亮要点）

构建AI智能体时，上下文工程是塑造其行为的核心。如何通过优化KV缓存、动态管理工具、利用文件系统拓展记忆等策略，让智能体更高效、稳定地运转？这些来自实践的经验，或许能为智能体开发提供关键指引。

Manus 团队刚分享了他们构建 Agent 的 Context 工程经验。

想来会对同样做 Context 工程、Agent 开发的朋友有所帮助。

刚好我在自己读的过程中，对全文进行了精校翻译，并高亮要点与排版。来自一线的分享，总共 6 条经验，共 5K 字。

也提炼了一份思维导图。不过还是建议直接阅读，不要省流。

分享给你们，enjoy～

From：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

译文：《 AI 智能体的上下文工程：构建 Manus 的经验》

2025 年 7 月 18 日，Peak @Manus

在 Manus 项目启动之初，我们面临一个关键抉择：

是应该利用开源基础模型，训练一个端到端的智能体模型？还是基于前沿大模型已有的上下文学习（in-context learning）能力，构建我们的智能体？

在我投身 NLP 领域的头十年里，我们没有这样的选择。

在遥远的 BERT 时代（没错，已经过去七年了），模型必须经过微调和评估，才能迁移到新任务上。即便那时的模型与今天的 LLM 相比小得可怜，但这个过程的每次迭代也常常需要数周时间。

我上一个创业项目给我留下了一个惨痛的教训：对于快速迭代的应用，尤其是还没找到 PMF 之前，缓慢的反馈循环是致命的。

当时我为开放信息提取（Open information extraction）和语义搜索从零开始训练模型。然而，GPT-3 和 Flan-T5 相继问世，我自研的模型一夜之间就过时了。颇具讽刺意味的是，也正是这些模型，开启了上下文学习的时代，并由此揭示了一条全新的路径。

这个来之不易的教训让我们的选择变得清晰：Manus 决定押注在上下文工程上。

这让我们能将改进的发布周期从数周缩短到几小时，并使我们的产品与底层模型的发展保持“正交”关系：如果说模型的进步是水涨船高的浪潮，我们希望 Manus 成为潮头上的船，而不是被固定在海底的石柱。

尽管如此，上下文工程的实践远比想象的要复杂。

上下文工程是一门实验科学——我们已经重构了四次 Agent 的框架，每一次都是因为发现了塑造上下文的更优方法。

我们亲切地称这个手动进行架构搜索、调试提示词和经验猜测的过程为“随机研究生下降法”（Stochastic Graduate Descent）。

虽然听起来不那么优雅，但确实有效。

译者注：“研究生”在学术界和科技界，常常与“做实验、调参数、熬夜、靠直觉和运气”等形象挂钩，形容这个过程不是一个严谨、自动化的数学优化过程（如梯度下降），而是充满了人工调试、反复试错和“体力活”的探索。

本文将分享我们通过自己的“SGD”找到的局部最优解。如果你也在构建自己的 AI Agent，希望这些原则能帮助你更快地收敛。

• Manus：https://manus.im/
• In-context learning：https://arxiv.org/abs/2301.00234
• BERT：https://arxiv.org/abs/1810.04805
• Open information extraction：https://en.wikipedia.org/wiki/Open_information_extraction
• GPT-3：https://arxiv.org/abs/2005.14165
• Flan-T5：https://arxiv.org/abs/2210.11416

如果非要我只选一个指标，我会说 KV 缓存命中率 是生产环境中 AI 智能体最关键的单一指标。它直接影响延迟和成本。

要理解其中缘由，我们先来看看典型 AI Agent （a typical agent）是如何运作的：在收到用户输入后，智能体通过一系列的工具调用链来完成任务。在每次迭代中，模型根据当前上下文，从预定义的动作空间中选择一个动作。该动作随后在环境（例如 Manus 的虚拟机沙箱）中执行，并产生一个观测结果。这个动作和观测结果会被追加到上下文中，形成下一次迭代的输入。这个循环持续进行，直到任务完成。

你可以想象，上下文在每一步都会增长，而输出通常是结构化的 Function Call，相对较短。

与聊天机器人相比，这使得智能体中预填充（prefilling）和解码（decoding）的比例严重倾斜。以 Manus 为例，其输入与输出的 token 数量比平均达到manus 教程了 100:1。

幸运的是，拥有相同前缀的上下文可以利用 KV 缓存（KV-cache）机制。

无论你是自部署模型还是调用推理 API，都能极大降低首个 token 生成时间（TTFT）和推理成本。

这带来的成本节约非同小可：以 Claude Sonnet 为例，命中缓存的输入 token 成本为 0.30 美元/百万 token，而未命中缓存的成本则为 3 美元/百万 token——相差整整十倍。

从上下文工程的角度看，提升 KV 缓存命中率涉及几个关键实践：保持提示词前缀的稳定性。 由于大模型的自回归（autoregressive）特性，哪怕只有一个 token 的差异，也可能使缓存从该 token 之后开始失效。一个容易犯的错误是，在系统提示词的开头包含时间戳（尤其是精确到秒的时间戳）。它确实能让模型告诉你当前时间，但也会直接破坏你的缓存命中率。只对上下文进行追加（append-only）。 避免修改之前的动作或观测结果。确保你的序列化（serialization）过程是确定性的。许多编程语言和库在序列化 JSON 对象时，不保证键的顺序是固定的，这会在不知不觉中破坏缓存。在需要时明确标记缓存断点。 一些模型提供商或推理框架不支持自动的增量前缀缓存，而是需要手动在上下文中插入缓存断点。在分配断点时，要考虑到缓存可能的过期时间，并至少确保断点包含在系统提示词的末尾。

此外，如果你在使用 vLLM 等框架自部署模型，请确保启用了 prefix / prompt caching ，并用 Session IDs 等技术保持分布式工作节点间的一致路由。

• A typical agent：https://arxiv.org/abs/2210.03629
• KV-cache：https://medium.com/@joaolages/kv-caching-explained-9
• Autoregressive：https://en.wikipedia.org/wiki/Autoregressive_model
• vLLM：https://github.com/vllm-project/vllm
• prefix / prompt caching：https://docs.vllm.ai/en/stable/design/v1/prefix_caching.html

随着智能体能力的增加，其动作空间（action space）自然会变得愈发复杂。直白地说，就是工具的数量会爆炸式增长。

最近 MCP 的流行更是火上浇油。如果你允许用户配置工具，相信我：总会有人把你精心构造的动作空间里，塞进上百个来历不明的工具。其后果是，模型更容易选错行动或采取低效路径。

简而言之，你构造出来的智能体反而会变笨。

一种自然的想法是设计一个动态的动作空间——比如类似 RAG 一样，按需动态加载工具。（我们在 Manus 中也尝试过）

但我们的实验揭示了一条清晰的规则：除非绝对必要，否则避免在迭代中途动态增删工具。

主要原因有二：

1. 在大多数大模型中，工具定义在序列化后通常位于上下文的靠前位置，通常位于系统提示词之前或之后。因此，任何更改都会导致后续所有动作和观测的 KV 缓存失效。

2. 当此前的动作和观测仍然引用着当前上下文中不再定义的工具时，模型会感到困惑。如果没有约束解码（constrained decoding），这通常会导致模式违规或产生幻觉动作。

为了解决这个问题，同时又能优化动作选择，Manus 使用一个上下文感知的状态机（state machine）来管理工具的可用性。它并不移除工具，而是在解码阶段遮蔽掉 token logits，从而根据当前上下文，阻止（或强制）模型选择某些动作。

在实践中，大多数模型提供商和推理框架都支持某种形式的响应预填充，这允许你在不修改工具定义的情况下约束动作空间。

函数调用通常有三种模式（我们以 NousResearch 的 Hermes format 为例）：自动（Auto）：模型可以选择调用函数，也可以不调用。通过仅预填充回复前缀实现：<|im_start|>assistant必需（Required）：模型必须调用一个函数，但具体调用哪个不受限制。通过预填充至工具调用 token 实现：<|im_start|>assistant

指定（Specified）：模型必须从一个特定的子集中调用函数。通过预填充至函数名的开头实现：<|im_start|>assistant

)” />