本文受到 Manus 团队最新技术分享的启发，基于他们的原文《Context Engineering for AI Agents: Lessons from Building Manus》进行解读和通俗化阐述。
原文链接: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
构建一个真正有用的 AI Agent 并不简单。Manus 团队在这条路上走了很多弯路，重写了四次架构，最终总结出了一套实用的经验。今天我们来解读他们的核心发现，看看如何避开那些看似聪明却适得其反的陷阱。
在深入探讨之前，让我们先理解几个关键概念：
KV-Cache（键值缓存）是大语言模型的一个重要优化机制。模型在处理文本时会生成键值对来存储注意力机制的计算结果，当输入文本有相同前缀时，就可以复用之前的计算结果，从而大幅减少重复计算，显著降低延迟和成本。
掩码（Masking）通过修改模型输出的概率分布来控制特定 token 的生成，可以强制或禁止模型选择某些特定选项，实现更精准的行为控制。
状态机（State Machine）是一种经典的计算模型，它根据当前状态和输入来决定下一个状态和输出，在管理复杂系统的行为流程方面表现出色。
核心决策：为什么选择"站在巨人肩膀上"
在项目初期，Manus 团队面临一个关键选择：是训练一个端到端的 Agent 模型，还是基于现有大模型的能力来构建？
他们的选择很明确：选择现有模型的上下文学习（In-Context Learning）能力。这个决定基于三个现实考量：首先是速度优势，改进可以在几小时内完成，而不是几周的漫长等待；其次是适应性，当更强的模型出现时，可以无缝切换；最后是成本效益，避免了大规模训练的巨额资源投入。
感兴趣的小伙伴可以阅读:
正如团队所说："如果模型进步是涨潮，我们希望 Manus 是船，而不是固定在海底的柱子。"
原则一：把 KV-Cache 当作生命线
如果只能关注一个指标，那就是 KV-Cache 命中率。这直接影响响应速度和成本。
Agent 的工作模式有着独特性：输入的上下文往往很长，包含历史对话、工具调用记录等大量信息，而输出却相对很短，通常只是一个结构化的工具调用。在 Manus 中，平均输入输出比例高达 100:1。
当上下文可以复用缓存时，成本差异令人震惊。以 Claude Sonnet 为例，缓存的 token 成本仅为 0.30 美元每百万 token，而未缓存的 token 则需要 3 美元每百万 token，整整 10 倍的差异！
实用技巧
要优化 KV-Cache 命中率，关键在于三个方面。保持提示词前缀稳定是首要原则，千万不要在系统提示开头加精确到秒的时间戳，这样看似让模型知道当前时间，实际上却杀死了缓存命中率。只追加，不修改的策略同样重要，确保上下文是只增不改的，避免任何对历史内容的修改。最后要确保序列化确定性，因为许多编程语言和库不保证 JSON 对象的键顺序稳定，这种随机性会悄无声息地破坏缓存效果。
原则二：掩码工具，而不是删除
随着 Agent 能力增强，工具数量会爆炸式增长。用户可能会接入数百个工具，这会让 Agent "选择困难症"，反而变笨。
常见错误做法
很多团队会选择动态添加或删除工具，但这种做法问题重重。首先会导致 KV-Cache 失效，因为工具定义通常位于上下文前部，任何变动都会让后续的缓存作废。更糟糕的是，这还会让模型陷入混乱状态，因为之前的操作记录中引用了现在已经不存在的工具。
正确做法：状态机 + 掩码
Manus 使用上下文感知的状态机（State Machine）来管理工具可用性，通过掩码（Masking）token 概率来控制工具选择，而不是删除工具定义。
这套机制支持三种工作模式：Auto 模式下，模型可以自由选择是否调用函数；Required 模式则强制模型必须调用函数，但不限制具体选择；而Specified 模式最为严格，只允许从预定义的特定子集中选择工具。
原则三：文件系统就是你的无限上下文
现代 LLM 的上下文窗口虽然很大（128K+ tokens），但在实际应用中经常捉襟见肘。观察结果往往出人意料地庞大，特别是处理网页、PDF 等非结构化数据时，很容易就超出上下文限制。更麻烦的是，超长上下文会明显降低模型性能，而且长输入的成本也相当高昂。
Manus 的解决方案
把文件系统当作外部记忆是一个巧妙的解决方案。文件系统拥有容量无限、天然持久化的特点，更重要的是 Agent 可以直接对其进行操作，就像使用自己的大脑一样自然。
他们的压缩策略总是设计为可恢复的：网页内容可以从上下文中删除，但会保留 URL 以便随时重新获取；文档内容可以省略，但文件路径会始终保留在沙盒中。这样既节省了上下文空间，又确保不会永久丢失任何关键信息。
"我发现自己在想象，要让状态空间模型（State Space Model, SSM）在 Agent 环境中有效工作需要什么。如果它们能掌握基于文件的记忆——将长期状态外化而不是保存在上下文中——那么它们的速度和效率可能会开启一类新的 Agent。Agent 版SSM 可能是神经图灵机（Neural Turing Machines）的真正继承者。"
原则四：通过"复述"操纵注意力
Manus 在处理复杂任务时会创建 todo.md 文件，并逐步更新进度。这里使用了注意力操纵机制。
一个典型任务需要约 50 次工具调用，这是一个相当长的执行循环。在如此漫长的过程中，模型很容易偏离主题，逐渐忘记早期设定的目标，或者陷入"中间迷失"（Lost-in-the-Middle）的困境，无法有效处理上下文中间部分的重要信息。
解决方案
通过不断重写待办事项列表，Manus 将目标"复述"到上下文末尾，让关键信息进入模型的近期注意力范围。
原则五：保留错误，不要隐藏
Agent 会犯错——这是现实，不是 bug。常见冲动是清理错误：重试操作、重置状态。
但这样做会失去证据，模型无法学习。
更好的做法
让错误留在上下文中。当模型看到失败的操作和结果时，会隐式更新内部信念，降低重复同样错误的概率。
"事实上，我们认为错误恢复是真正 Agent 行为的最清晰指标之一。"
原则六：避免"Few-Shot 陷阱"
少样本提示（Few-shot Prompting）是常见技术，但在 Agent 系统中可能适得其反。
语言模型是优秀的模仿者。如果上下文充满相似的历史操作，模型会倾向于重复这种模式，即使不再合适。
例如：用 Manus 审查 20 份简历时，Agent 常常陷入节奏——仅仅因为上下文中有类似模式就重复相似操作。
解决方案
增加多样性是关键策略。Manus 巧妙地在操作和观察中引入少量结构化变化，比如使用不同的序列化模板、采用替代表述方式，或者在顺序和格式上加入微小的噪声。这种受控的随机性非常有效，既能打破固化的模式，又能重新调整模型的注意力分布。
上下文工程（Context Engineering）仍是新兴科学，但对 Agent 系统已经是必需的。模型可能变得更强、更快、更便宜，但这些都不能替代对记忆、环境和反馈的需求。
如 Manus 团队所说："智能体化的未来将在一个又一个的情境中构建。好好设计它们。"