以下内容为 《Context Engineering for AI Agents: Lessons from Building Manus》 一文的完整中文翻译，标题、小节标题与原文保持一致，段落顺序、要点与举例均忠实呈现，仅对个别行文做了符合中文语境的微调。源文发表于 2025 年 7 月 18 日，作者 Yichao “Peak” Ji。(Manus)
2025 年 7 月 19 日
引子
在 Manus 项目伊始，我的团队面临一条关键抉择：
基于开源模型，端到端训练一套“纯代理”模型？
还是利用前沿大模型的上下文学习（in‑context learning）能力，在其之上打造代理？
回顾我在 NLP 的头十年，这种奢侈的选择根本不存在。BERT 年代，想让模型迁移到新任务就得细调加评估——每轮迭代耗时数周，而模型规模还远小于今日 LLM。对于节奏飞快、尚未找到产品‑市场契合点（PMF）的应用而言，如此缓慢的反馈循环无异于判死刑。那段苦涩经历让我们这次下定决心：押注上下文工程（context engineering）。它能把“数周级”迭代压缩到“数小时级”，并使产品与底层模型解耦：当模型进步如同潮水上涨，我们想做乘风而行的船，而非被定在海床的柱。(Manus)
然而，实践告诉我，上下文工程并不简单。这是一门“实验科学”；我们已重写框架四次，每次都是在发现更优上下文构造方式后推倒重来。我们戏称这套凭直觉调参、迭代试错的流程为 “随机研究生下降法（SGD：Stochastic Graduate Descent）”——不优雅，却确实有效。本文分享我们迭代出的“局部最优解”，希望能帮正在打造代理的你少走弯路。(Manus)
1. 围着 KV‑Cache 做设计
KV‑缓存命中率 是生产级 AI 代理最关键的单一指标——它直接左右延迟与成本。代理通常按下述循环运行：
输入 → 选择动作 → 执行动作 → 得到观察 → 上下文追加动作+观察 → 下一轮……
上下文随步数线性增长，而每轮输出（多为结构化函数调用）相对很短。以 Manus 为例，输入/输出 token 均值约 100 : 1。幸运的是，只要前缀相同，就能用 KV‑Cache 大幅降低 TTFT 和推理费用：在 Claude Sonnet 里，缓存 token 每百万仅 0.30 美元，而未缓存高达 3 美元，相差 10 倍。(Manus)
提升命中率的三条铁律：
固定提示词前缀——哪怕多一个时间戳 token，都可能使后续内容失去缓存价值；
上下文只追加、不修改——序列化须确定性；JSON 键序随语言/库改变往往暗中破坏缓存；
必要时手动标注缓存断点——自托管框架（如 vLLM）要确认启用了前缀缓存并正确使用 session ID。(Manus)
2. 去“删除”，用“掩码”
随着能力扩展，代理的动作空间（工具数目）会爆炸式增长。简单把工具动态加载/卸载看似合理，实测却会：
破坏前缀缓存——工具定义常位于上下文前部；
让模型对已“消失”的工具混乱，导致调用架构错误或幻觉。
Manus 改用 状态机 + token Logits 掩码：工具始终留在上下文，但在解码阶段动态屏蔽或强制某些前缀（如 browser_、shell_），既保命中率又防误用。(Manus)
3. 把文件系统当“终极上下文”
128K token 窗口听起来巨大，现实任务依旧会：
观察巨大（网页、PDF）；
上下文越长模型质量下降；
即便缓存也需付传输+预填费用。
我们的策略：文件系统即记忆。代理学会按需读写文件，把长内容 URL/路径留在上下文，可随调、可恢复，避免信息不可逆压缩。展望未来，若**状态空间模型（SSM）**能掌握这种外部记忆，或许能凭速度和效率诞生新一代代理。(Manus)
4. 用“复述”操控注意力
Manus 在处理复杂任务时常生成 todo.md，并随进度勾选。这不只是可爱，而是把全局目标不断写入上下文尾部——把模型注意力拉回任务，缓解“中间遗忘”（lost‑in‑the‑middle）与目标漂移，无须特殊架构改动。(Manus)
5. 把“错误”留在上下文
多步任务里，失败本就是循环的一环。若把错误栈跟踪、异常输出清理掉，模型就失去事实依据，无法调整策略。保留错误反而能显式更新模型先验，降低重复犯错概率。我们认为，错误恢复能力是衡量真正代理行为的明确信号，却在学术基准中常被忽视。(Manus)
6. 别被“少样例”框死
少样例提示（few‑shot prompting）在代理系统里可能反作用：上下文中高度相似的过往动作‑观察对，会诱导模型机械重复旧模式，导致漂移、过拟合或幻觉。Manus 故意引入微小结构化随机性——不同序列化模板、措辞变体、顺序轻扰——以打破刻板节奏、增强鲁棒性。(Manus)
结语
上下文工程仍是新兴学科，但对 AI 代理而言已经必不可少。无论模型多强，都替代不了对记忆、环境与反馈的设计。如何塑造上下文，决定代理运行速度、恢复能力与可扩展性。这些经验来自 Manus 数百万用户、高频迭代的血汗教训，并非放之四海而皆准；若能帮你少一次痛苦重写，这篇文章就值了。未来的代理时代，将由一段又一段精心雕琢的上下文铺就。(Manus)
原文
AI代理的上下文工程：构建Manus的经验教训
星期六, 7月 19
技术
2025/7/18 --Yichao 'Peak' Ji
在项目的最初阶段，我和我的团队面临一个关键决策：我们是应该使用开源基础模型训练一个端到端的智能体模型，还是基于前沿模型的能力构建一个智能体？ 在我的NLP生涯的第一个十年里，我们没有这种选择的奢侈。在遥远的时代（是的，已经过去七年了），模型必须先进行微调——和评估——才能迁移到新任务。这个过程通常每次迭代需要数周时间，尽管与今天的LLM相比，这些模型非常小。对于快速发展的应用，特别是在产品市场匹配(PMF)之前，这种缓慢的反馈循环是一个致命缺陷。这是我上一个创业公司的惨痛教训，当时我从头开始训练模型用于和语义搜索。然后和出现了，我的内部模型一夜之间变得无关紧要。具有讽刺意味的是，这些相同的模型标志着上下文学习的开始——以及一条全新的前进道路。 这个来之不易的教训使选择变得明确：Manus将押注于上下文工程。这使我们能够在几小时而非几周内交付改进，并使我们的产品与底层模型保持正交：如果模型进步是上涨的潮水，我们希望Manus成为那条船，而不是固定在海床上的柱子。
尽管如此，上下文工程证明绝非易事。这是一门实验科学——我们已经重建了我们的代理框架四次，每次都是在发现了更好的塑造上下文的方式之后。我们亲切地将这种手动架构搜索、提示调整和经验猜测的过程称为"随机研究生下降"。这并不优雅，但它有效。
这篇文章分享了我们通过自己的"SGD"所达到的局部最优解。如果你正在构建自己的AI代理，我希望这些原则能帮助你更快地收敛。
围绕KV缓存进行设计
如果我必须选择一个指标，我认为 KV-cache命中率 是生产阶段AI代理最重要的单一指标。它直接影响延迟和成本。为了理解原因，让我们看看是如何运作的：
在接收用户输入后，代理通过一系列工具使用链来完成任务。在每次迭代中，模型根据当前上下文从预定义的动作空间中选择一个动作。然后在环境中执行该动作（例如，Manus的虚拟机沙盒）以产生观察结果。动作和观察结果被附加到上下文中，形成下一次迭代的输入。这个循环持续进行，直到任务完成。 正如你所想象的，随着每一步的推进，上下文不断增长，而输出——通常是结构化的函数调用——保持相对简短。这使得代理（agents）相比聊天机器人的预填充和解码比例高度倾斜。例如在Manus中，平均输入与输出的token比例约为100:1。
幸运的是，具有相同前缀的上下文可以利用，这大大减少了首个token的生成时间(TTFT)和推理成本——无论你是使用自托管模型还是调用推理API。我们说的不是小幅度的节省：例如使用Claude Sonnet时，缓存的输入token成本为0.30美元/百万token，而未缓存的成本为3美元/百万token——相差10倍。
从上下文工程的角度，提高KV缓存命中率涉及几个关键实践：
保持你的提示前缀稳定。 由于LLM的特性，即使是单个标记的差异也会使该标记之后的缓存失效。一个常见的错误是在系统提示的开头包含时间戳——尤其是精确到秒的时间戳。虽然这让模型能告诉你当前时间，但也会降低你的缓存命中率。
使你的上下文只追加。 避免修改之前的操作或观察。确保你的序列化是确定性的。许多编程语言和库在序列化JSON对象时不保证键顺序的稳定性，这可能会悄无声息地破坏缓存。
在需要时明确标记缓存断点。 某些模型提供商或推理框架不支持自动增量前缀缓存，而是需要在上下文中手动插入缓存断点。在分配这些断点时，要考虑潜在的缓存过期问题，并至少确保断点包含系统提示的结尾。
此外，如果你正在使用像 这样的框架自托管模型，请确保启用了，并且你正在使用会话 ID 等技术在分布式工作节点之间一致地路由请求。
遮蔽，而非移除
随着代理能力的增强，其行动空间自然变得更加复杂——简单来说，工具数量爆炸式增长。最近流行的只会火上浇油。如果你允许用户自定义工具，相信我：总会有人将数百个神秘工具插入到你精心策划的行动空间中。结果，模型更可能选择错误的行动或采取低效的路径。简而言之，你武装过度的代理变得更加愚蠢。
一个自然的反应是设计一个动态行动空间——可能是使用类似于的方法按需加载工具。我们在Manus中也尝试过这种方法。但我们的实验表明了一个明确的规则：除非绝对必要，避免在迭代过程中动态添加或移除工具。这主要有两个原因：
在大多数LLM中，工具定义在序列化后位于上下文的前部，通常在系统提示之前或之后。因此任何更改都会使后续所有动作和观察的KV缓存失效。
当先前的动作和观察仍然引用当前上下文中不再定义的工具时，模型会感到困惑。如果没有，这通常会导致模式违规或幻觉动作。
为了解决这个问题并仍然改进动作选择，Manus使用上下文感知的来管理工具可用性。它不是移除工具，而是在解码过程中掩蔽token的logits，以基于当前上下文阻止（或强制）选择某些动作。
在实践中，大多数模型提供商和推理框架支持某种形式的响应预填充，这允许你在不修改工具定义的情况下约束动作空间。函数调用通常有三种模式（我们将使用 NousResearch 的 作为示例）：
自动 – 模型可以选择调用或不调用函数。通过仅预填充回复前缀实现：<|im_start|>assistant
必需 – 模型必须调用函数，但选择不受约束。通过预填充到工具调用令牌实现：<|im_start|>assistant<tool_call>
指定 – 模型必须从特定子集中调用函数。通过预填充到函数名称的开头实现：<|im_start|>assistant<tool_call>{"name": "browser_ 通过这种方式，我们通过直接掩码token的logits来约束动作选择。例如，当用户提供新输入时，Manus必须立即回复而不是执行动作。我们还有意设计了具有一致前缀的动作名称——例如，所有与浏览器相关的工具都以browser_开头，命令行工具以shell_开头。这使我们能够轻松确保代理在给定状态下只从特定工具组中进行选择而无需使用有状态的logits处理器。
这些设计有助于确保Manus代理循环保持稳定——即使在模型驱动的架构下。
使用文件系统作为上下文
现代前沿LLM现在提供128K令牌或更多的上下文窗口。但在真实世界的代理场景中，这通常不够，有时甚至是一种负担。有三个常见的痛点：
观察结果可能非常庞大，尤其是当代理与网页或PDF等非结构化数据交互时。很容易超出上下文限制。
模型性能往往会下降，超过一定的上下文长度后，即使技术上支持该窗口大小。
长输入成本高昂，即使使用前缀缓存。你仍然需要为传输和预填充每个token付费。
为了解决这个问题，许多代理系统实现了上下文截断或压缩策略。但过度激进的压缩不可避免地导致信息丢失。这个问题是根本性的：代理本质上必须根据所有先前状态预测下一个动作——而你无法可靠地预测哪个观察结果可能在十步之后变得至关重要。从逻辑角度看，任何不可逆的压缩都带有风险。 这就是为什么我们在Manus中将文件系统视为终极上下文：大小不受限制，天然持久化，并且代理可以直接操作。模型学会按需写入和读取文件——不仅将文件系统用作存储，还用作结构化的外部记忆。
我们的压缩策略始终设计为可恢复的。例如，只要保留URL，网页内容就可以从上下文中移除；如果沙盒中仍然保留文档路径，则可以省略文档内容。这使得Manus能够缩短上下文长度，而不会永久丢失信息。 在开发这个功能时，我发现自己在想象**状态空间模型(State Space Model, SSM)**在智能体环境中有效工作需要什么条件。与Transformer不同，SSM缺乏完整的注意力机制，并且在处理长距离的后向依赖关系时表现不佳。但如果它们能够掌握基于文件的记忆——将长期状态外部化而不是保存在上下文中——那么它们的速度和效率可能会开启一类新型智能体。基于SSM的智能体可能是真正的继任者。
通过复述操控注意力
如果你使用过Manus，你可能注意到一个有趣的现象：在处理复杂任务时，它倾向于创建一个todo.md文件——并在任务进行过程中逐步更新它，勾选已完成的项目。
这不仅仅是可爱的行为——这是一种操控注意力的刻意机制。
Manus中的一个典型任务平均需要大约50次工具调用。这是一个很长的循环——由于Manus依赖LLM进行决策，它很容易偏离主题或忘记早期目标，尤其是在长上下文或复杂任务中。
通过不断重写待办事项列表，Manus将其目标复述到上下文的末尾。这将全局计划推入模型的近期注意力范围内，避免了"丢失在中间"的问题，并减少了目标不一致。实际上，它使用自然语言来使自己的注意力偏向任务目标——而不需要特殊的架构变更。
保留错误的内容
代理会犯错。这不是bug——这是现实。语言模型会产生幻觉，环境会返回错误，外部工具会出现异常行为，意外的边缘情况随时都会出现。在多步骤任务中，失败不是例外；它是循环的一部分。
然而，一个常见的冲动是隐藏这些错误：清理痕迹，重试操作，或重置模型的状态并将其留给神奇的""。这感觉更安全，更受控制。但这是有代价的：擦除失败会移除证据。没有证据，模型就无法适应。
根据我们的经验，改善代理行为最有效的方法之一出奇地简单：将错误的尝试保留在上下文中。当模型看到一个失败的行动——以及由此产生的观察结果或堆栈跟踪——它会隐式地更新其内部信念。这会改变其先验，降低重复相同错误的可能性。 事实上，我们认为错误恢复是真正代理行为的最明显指标之一。然而，在大多数学术工作和公共基准测试中，这一点仍然代表性不足，它们通常关注理想条件下的任务成功。
不要被少样本示例所困
是提高LLM输出的常用技术。但在代理系统中，它可能会以微妙的方式适得其反。 语言模型是优秀的模仿者；它们模仿上下文中的行为模式。如果你的上下文充满了类似的过去行动-观察对，模型将倾向于遵循该模式，即使这不再是最优的。
这在涉及重复决策或行动的任务中可能很危险。例如，当使用Manus帮助审查20份简历时，代理通常会陷入一种节奏——仅仅因为这是它在上下文中看到的，就重复类似的行动。这导致偏离、过度泛化，或有时产生幻觉。
解决方法是增加多样性。Manus在行动和观察中引入少量的结构化变化——不同的序列化模板、替代性措辞、顺序或格式上的微小噪音。这种受控的随机性有助于打破模式并调整模型的注意力。 换句话说，不要让自己陷入少样本学习的窠臼。你的上下文越单一，你的智能体就变得越脆弱。
结论
上下文工程仍然是一门新兴的科学——但对于智能体系统来说，它已经是必不可少的。模型可能变得更强大、更快速、更经济，但再多的原始能力也无法替代对记忆、环境和反馈的需求。你如何塑造上下文最终决定了你的智能体的行为方式：它运行的速度、恢复的效果以及扩展的范围。
在Manus，我们通过反复的重写、死胡同以及面向数百万用户的实际测试学到了这些经验。我们在这里分享的内容并非放之四海而皆准的真理——但这些是对我们有效的模式。如果它们能帮助你避免哪怕一次痛苦的迭代，那么这篇文章就达到了它的目的。
智能体的未来将一次构建一个上下文。好好设计它们吧。
深度解读
Context Engineering 是什么？为什么 Manus 团队花千万美金踩坑，只为搞懂「怎么喂模型」？
这不只是 prompt 工程的进化版，而是 AI Agent 时代真正的关键技术。
21 Jul 2025 — 7 分钟阅读
什么是上下文工程（Context Engineering）？
在生成式 AI 崛起后，越来越多开发者开始打造 AI Agent：让语言模型像助理一样，连续思考、多步操作、甚至自己规划任务。
这些 Agent 不需要自己「从零训练一个模型」，因为 GPT-4、Claude、Gemini 等模型已经够聪明了—— 真正的挑战，变成了「你喂进去的上下文好不好」。
所谓「上下文」，其实就是模型的输入
对语言模型来说，它不记得你是谁，也不会主动学习，它只会根据「这一次输入的内容」来猜下一个字要说什么。
这次的输入，就是上下文（context）。
所以，如果你希望一个 AI Agent 有记忆、有逻辑、有工具使用能力，那你就必须：
给它一个设计好的系统提示（system prompt）
让它记得前面发生过什么事（历史输入/输出）
教它怎么执行工具（Tool 使用规则）
帮它整理信息（压缩 / 存储观察到的资料）
这一系列的「设计上下文流程」的技术，就叫做 Context Engineering。
你可以把 Context Engineering 想象成「喂模型吃好吃的 prompt 食谱」：
就像一位语言模型是天才厨师，但你不给食材、或乱给食材，它也做不出你想吃的食物。Context Engineering 就是那位掌控食材的人——
它决定：
Prompt 要怎么写 ：清楚、具体、有格式
资料怎么整理 ：要 JSON 吗？还是 YAML？还是像自然语言？
记忆怎么存储 ：要放进上下文吗？还是写进文件？
任务怎么规划 ：先做什么？做完要不要复查？错了要怎么补救？
这一切都不改变模型本身，只通过喂它更好的上下文 ，就能大幅改变它的表现。
Manus 团队：用千万元美金踩坑后得出的设计哲学
Manus 是一个 AI agent 平台，从一开始就做出了一个与众不同的决定：
❝ 不自己训练模型，也不靠微调，而是全力投注在 Context Engineering 上 。 ❞
他们在实作过程中踩遍各种地雷、重写了6次框架，最终把经验整理成一套极具参考价值的准则，称得上是「实战中淬炼出的上下文工程七大原则」。
这些原则背后，并不是空泛的哲学，而是与现实中的 API 成本、执行延迟、错误率、使用体验息息相关的架构设计关键 。
接下来，我们就来逐条拆解这七个 Manus 团队的「Context Engineering 生存法则」，看看如何通过 prompt、记忆、工具与错误处理的精细设计，让一个 AI Agent 真的能用、能学、能修正。
Manus AI 团队七大实战心法：反共识却实用
上下文工程比自行训练模型更优越
❝ 不必自己造轮子，只需为模型铺设道路即可。 ❞
Manus 团队一开始就做出战略选择： 不训练自己的模型 ，而是用现成的大模型＋自己控制上下文 。这样不但能更快出产品，每次模型更新（例如 Claude、GPT 升级）也能立刻受益。
KV-Cache 命中率是效能的瓶颈
一个 prompt prefix 不稳定，就让你损失 10 倍成本。
KV-Cache（Key-Value Cache） 是大模型记忆机制的一部分，若上下文前缀保持一致，就能节省大量重复计算。
例如：Claude Sonnet 的 cache 命中每 1M tokens 仅需0.3 美元，未命中则要 3！
避免 cache 失效的技巧包括：
Prompt 前缀不能动（不能加时间戳）
JSON 序列要稳定（key 顺序一致）
不更新旧内容，只追加新信息
上下文只能「加」，不能「改」
就像写日记，不能删昨天的内容。
这是为了保持上下文一致性与缓存命中率。哪怕只改了一行错字或换了格式，都可能导致重新编码整个上下文。最好的做法是： 永远追加、永不修改 。
工具多，不代表要乱加减
❝ 遮蔽代码比删除更聪明。 ❞
当 Agent 能使用的工具越来越多（例如 plugin、生成功能等），你会想根据任务删掉无用工具。但这会让上下文改变， 导致 cache 崩溃＋模型混乱 。
Manus 的做法是「 不删除工具，只在解码时用 token 掩码遮住它们 」，让模型看不到不该选的选项。
例如：
browser_开头的是网页工具shell_是终端工具
这种命名让模型能按情境选工具， 上下文却维持不变 。
文件系统是「外挂记忆」
大型语言模型的记忆有限，但文件系统没有限制。
当 agent 执行复杂任务时，可能会与 PDF、网页、Codebase 等交互，大量内容无法塞进上下文。
Manus 的解决方案：直接让模型学会写入/读取 sandbox 中的文件。
只要记住「文件路径」，需要时再抓内容回过来，这让 context 永远保持轻巧，但 agent 却像有无限记忆一样聪明。
错误记录是 agent 成长的关键
别删除错误信息，那是模型学会“别再做傻事”的依据。
模型会犯错，像选错工具、看错格式、工具回传错误等。不要清除这些记录，因为 留下错误记录，模型才能调整行为 。这是一种“自然语言式的强化”。
Few-shot 太单一，模型会陷入套路
多样化提示，才有多样化行为。
过去提示学习讲究「一致性」，但对 Agent 来说， 过度一致会导致「模式僵化」。 例如让 Agent 检查 20 份履历，它会逐渐「进入机械模式」，开始复制粘贴、不看上下文。
解法是： 加入微小变异（phrasing、顺序、格式等），让模型「保持清醒」，不被自己的例子误导。
结论：真正的 Agent 时代，不靠大模型，而靠上下文工程
AI Agent 的真正威力，不在于模型有多强，而在于能不能处理复杂上下文、连续任务与不确定环境。
这篇 Manus 团队的 blog，展示了 「模型升级靠 OpenAI，Agent 智慧靠你自己」 的关键观念。如果你正要做 AI 应用，这 7 条上下文设计原则，可能会让你少走 3 个月冤枉路、少烧 3 万美金。
Source:
Context Engineering for AI Agents: Lessons from Building Manus