Manus：Agent的上下文工程经验总结
进度0%
7月19日
date
Jul 20, 2025
slug
Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
status
Published
tags
Agent
Context Engineering
summary
type
Post
Manus Agent 工程实践深度解读：上下文工程的核心原则
精简解读
1. 核心决策（一句话）
不训练端到端模型，完全依赖前沿大模型的上下文学习能力（in-context learning），实现小时级迭代、与底层模型解耦。
2. 六大原则速览
# | 原则 | 原文标题 | 目的 | 关键做法（原文摘录） |
1 | 把 KV-Cache 当生命线 | Design Around the KV-Cache | 延迟↓ 成本↓ | • 提示前缀字节级稳定
• 上下文仅追加、序列化确定
• 显式 cache breakpoint |
2 | 掩码优于增删 | Mask, Don’t Remove | 稳定工具空间 & 缓存不失效 | • 用 logits mask 屏蔽/强制工具
• 工具定义常驻上下文 |
3 | 文件系统即无限上下文 | Use the File System as Context | 解决超长输入 & 可恢复压缩 | • 内容可裁剪，URL/路径留档
• 代理自主读写文件 |
4 | 用复述操控注意力 | Manipulate Attention Through Recitation | 防目标漂移 | • 维护 todo.md 并持续追加到最新上下文 |
5 | 保留失败轨迹 | Keep the Wrong Stuff In | 让模型自我纠错 | • 失败动作与异常栈全部保留 |
6 | 拒绝同质化 Few-shot | Don’t Get Few-Shotted | 防行为僵化 | • 模板、措辞、顺序引入可控噪声 |
3. 原文金句提炼
- “KV-cache hit rate is the single most important metric.”
- “Mask, don’t remove.”
- “File system = unlimited, persistent, operable memory.”
- “Recitation biases attention without architectural changes.”
- “Erasing failure removes evidence.”
- “Don’t few-shot yourself into a rut.”
4. 一句话结论
如何塑造上下文，决定了 Agent 能多快、多稳、走多远——Context is the Agent.
详细分析
这篇文章分享了 Manus 团队在构建 AI Agent 过程中的核心经验，他们将其总结为“上下文工程”（Context Engineering）。其核心论点是，在当前技术阶段，与其投入巨大成本对模型进行端到端的训练，不如基于前沿大模型的上下文学习能力（in-context learning）进行构建，这能带来更快的迭代速度和产品灵活性。 Manus 将其探索过程戏称为“随机研究生下降”（Stochastic Graduate Descent），即一个通过架构搜索、提示词调整和经验猜测等手动过程不断寻找局部最优解的实践科学。
以下是 Manus 从实践中总结出的六大上下文工程核心原则的深度解读。
1. 围绕 KV-Cache 进行设计（Design Around the KV-Cache）
核心原则：KV-Cache 命中率是衡量生产级 AI Agent 最重要的单一指标，直接影响延迟和成本。
原理解读：
Agent 的工作模式是“思考-行动”循环。在每一轮迭代中，模型根据当前上下文选择一个动作，执行后产生观察结果，然后将“动作”和“观察结果”都附加到上下文中，为下一步决策做准备。 这导致 Agent 的上下文会随着任务步骤的增加而变得非常长，而其输出（通常是结构化的函数调用）则相对较短。 Manus 提到，其输入与输出的平均 Token 比例高达 100:1。
KV-Cache 是一种缓存技术，对于拥有相同前缀（prefix）的上下文，它可以极大地降低首次生成 Token 的时间（TTFT）和推理成本。 文本提到，使用 Claude Sonnet 模型时，命中缓存的 Token 成本仅为未命中时的十分之一。 因此，最大化 KV-Cache 命中率对于优化性能和控制成本至关重要。
实践方法：
- 保持提示词前缀稳定：任何微小的改动（如精确到秒的时间戳）都会导致缓存失效。
- 上下文采用仅追加模式 (Append-only)：避免修改历史动作或观察，并确保序列化（如 JSON）的顺序是确定的，以防静默地破坏缓存。
- 必要时显式标记缓存断点：在一些推理框架下，需要手动指定缓存结束的位置，至少要包含系统提示词的末尾。
深度解读：
这个原则揭示了 Agent 工程的经济学本质。它不再仅仅是追求功能的实现，而是必须在性能和成本之间做出精妙的权衡。将 KV-Cache 命中率提升到战略高度，意味着团队必须从底层设计上就贯彻“确定性”和“可复用性”的思想。这迫使开发者将 Agent 的“记忆”或“上下文”不仅仅看作一个动态增长的对话历史，而是一个需要被精心管理、以实现最高计算效率的“资产”。这种思维方式是从学术研究走向生产环境的关键一步。
2. 使用掩码，而非移除（Mask, Don't Remove）
核心原则：当 Agent 的工具集（Action Space）变得庞大时，不要在迭代中动态增删工具定义，而应通过掩码（Masking）在解码阶段限制模型的选择。
原理解读：
动态地从上下文中增删工具定义会带来两个严重问题：
- 工具定义通常位于上下文的靠前位置，任何修改都会使得后续所有内容的 KV-Cache 失效，成本高昂。
- 如果历史记录中引用了已被移除的工具，模型会感到困惑，可能导致输出格式错误或产生幻觉。
实践方法：
Manus 使用一个上下文感知的状态机来管理工具的可用性。它并不移除工具，而是在模型生成下一个 Token 时，通过“掩码”技术在解码层面直接屏蔽或强制选择某些工具。 他们利用了模型推理服务提供的不同函数调用模式（如自动、必须调用、指定调用），并通过预设函数名称前缀（如
browser_ 或 shell_）来简化按组别屏蔽或启用的操作。深度解读：
这一原则体现了在与“黑箱”模型（LLM）协作时的一种巧妙思路。我们无法直接修改模型的内部逻辑，但可以通过塑造其“视野”来引导其行为。使用掩码而非移除，是一种“软控制”而非“硬删除”的策略。它在不破坏上下文连贯性和缓存效率的前提下，实现了对 Agent 在特定状态下行为的精确约束。这好比是给 Agent 配备了齐全的工具箱，但根据当前工序，只高亮显示它应该使用的工具。这是一种既能保持系统稳定性，又能实现动态逻辑控制的优雅方案。
3. 将文件系统作为上下文（Use the File System as Context）
核心原则：面对超长上下文窗口的限制、性能衰减和高成本问题，应将文件系统视为最终的、无限大小的持久化上下文。
原理解读：
现代模型虽然支持数十万 Token 的上下文，但在实际 Agent 场景中仍然捉襟见肘，因为网页、PDF 等非结构化数据的观察结果可能非常巨大。 同时，过长的上下文不仅成本高昂，还可能导致模型性能下降（即“迷失在中间”问题）。 激进的压缩策略则必然导致信息丢失，因为无法预知哪一段历史信息会在未来变得至关重要。
实践方法：
Manus 的核心思想是：压缩必须是可恢复的。例如，网页内容可以从上下文中丢弃，只要保留其 URL；文档内容可以省略，只要其文件路径在沙箱中可用。 模型被训练成能够按需读写文件，将文件系统不仅用作存储，更用作一种结构化的外部记忆体。
深度解读：
这是对“上下文”概念的一次延伸，从模型的内部记忆（in-context memory）扩展到了外部环境记忆（externalized memory）。它借鉴了早期“神经图灵机”的思想，即计算单元可以与外部存储交互。通过让 Agent 学会使用文件系统，Manus 将上下文的瓶颈从 LLM 的窗口大小转移到了几乎无限的硬盘空间。这不仅解决了信息容量问题，更重要的是，它促使 Agent 学习一种更高级的智能行为：信息管理。Agent 必须自己决定何时将信息“卸载”到文件，何时再将其“加载”回注意力中，这是一种更接近人类工作方式的智能。
4. 通过“复述”来操控注意力（Manipulate Attention Through Recitation）
核心原则：通过让 Agent 在执行任务时反复读写一个“任务清单”（如
todo.md 文件），将全局目标和计划“复述”到上下文的末尾，从而强化模型的注意力。
原理解读：
对于需要几十步才能完成的复杂任务，Agent 很容易偏离最初的目标，尤其是在长程依赖和复杂干扰下。 这种现象被称为“目标漂移”。
实践方法：
Manus 设计了一种行为模式，让 Agent 在处理复杂任务时，创建一个
todo.md 文件，并随着任务的进展不断更新它（例如勾掉已完成项）。 这个行为看似简单，但其本质是将任务规划反复写入上下文的最新部分。由于 Transformer 模型的注意力机制对最近的 Token 更敏感，这种“复述”行为相当于在不断提醒模型：“别忘了，我们现在要做的总体目标是这个”。深度解读：
这是一种非常精妙的“心理学技巧”，完全基于对 Transformer 注意力机制的深刻理解。它没有修改任何底层模型架构，而是通过设计一种特定的行为模式，利用模型的自身特性来克服其弱点。这说明，优秀的 Agent 设计不仅是技术问题，也是一种“行为设计”。通过让 Agent “自言自语”或“写任务清单”，Manus 创造了一种内部反馈循环，有效地对抗了长序列任务中的注意力衰减和目标遗忘问题。
5. 保留失败记录（Keep the Wrong Stuff In）
核心原则：不要隐藏或清理 Agent 的失败尝试。将错误动作和其产生的异常信息（如堆栈跟踪）保留在上下文中，是提升 Agent 鲁棒性的最有效方法之一。
原理解读：
一个常见的诱惑是当 Agent 犯错时，试图通过重试或重置状态来“粉饰太平”，让执行记录看起来干净。 但这样做抹去了宝贵的学习证据。 模型如果看不到失败的案例，就无法学会如何避免和修正错误。
实践方法：
当模型看到一个失败的动作和由此产生的错误观察时，它会隐式地更新其内部信念，从而降低在后续步骤中重复同样错误的可能性。 Manus 认为，错误恢复能力是衡量真正智能行为的关键指标，但在学术界和公开基准测试中，这一点往往被忽视。
深度解读：
这个原则挑战了传统软件工程中“优雅处理异常”的观念。在 Agent 工程中，“异常”不是需要被隐藏的“程序 bug”，而是需要被学习的“宝贵经验”。保留失败记录，本质上是在上下文中为模型提供负样本（negative examples）。这使得 Agent 的学习过程更接近现实世界——试错是常态，从失败中学习是进步的关键。一个真正强大的 Agent 不在于从不犯错，而在于犯错后能从中吸取教训并自我修正。
6. 避免陷入“少样本”陷阱（Don't Get Few-Shotted）
核心原则：在上下文中，过于相似和重复的成功案例（Few-shot examples）会固化模型的行为，使其在面对需要变化的场景时变得脆弱。
原理解读：
语言模型是出色的模仿者。如果上下文中充满了大量重复的“动作-观察”对，模型会倾向于机械地模仿这种模式，即使情况已经变化，不再适用。 文章举例说，在处理 20 份相似的简历时，Agent 很容易陷入一种“节奏”，仅仅因为历史记录里都是这么做的，从而导致行为僵化、过度泛化甚至幻觉。
实践方法：
Manus 的解决方案是在动作和观察的序列化中引入少量、结构化的变体。 这可能包括使用不同的序列化模板、改变措辞、或在顺序和格式上引入微小的“噪音”。 这种受控的随机性有助于打破模式，调整模型的注意力，防止其陷入思维定式。
深度解读：
这揭示了 Few-shot Prompting 在 Agent 场景下的一个悖论。虽然提供范例能引导模型，但提供过多高度同质化的范例则会扼杀其灵活性。Agent 需要的不是刻板的模仿，而是在理解模式的基础上进行适应和推理。通过主动在上下文中引入“多样性”，Manus 相当于在训练过程中加入了“扰动”（perturbation），这迫使模型不能仅仅依赖表层模式匹配，而是要去理解更深层的任务逻辑。这确保了 Agent 在面对长序列重复性任务时，依然能保持“清醒”和适应性。
总结
Manus 的分享为 AI Agent 的落地实践提供了极其宝贵的路线图。其核心思想是，当前阶段的 Agent 开发者更应该成为一名“上下文工程师”而非“模型训练师”。 通过精心设计 Agent 与其上下文（记忆、环境、反馈）的交互方式，可以在不改变底层模型的情况下，极大地提升 Agent 的性能、稳定性和扩展性。 这些原则——无论是围绕 KV-Cache 的成本优化，还是通过“复述”和“保留失败”来操控模型行为——都体现了一种戴着镣铐跳舞的智慧，是通往更智能、更可靠的 Agent 系统必经的实践之路。