前言

今天这篇文章，我强烈建议我亲爱的粉丝们能从头到尾阅读一遍，首先，我肯定不是为了赚你几毛钱的阅读广告费，而是我真心的希望能帮助到各位。

这篇文章源于 Manus 公司联合创始人兼首席科学家季逸超（Peak）的一篇博客《Context Engineering for AI Agents: Lessons from Building Manus》，分享的是他们在构建 Manus 智能体过程中，关于上下文工程（Context Engineering）的实战经验与踩过的坑。

为什么 Manus 放弃微调，选择了上下文工程？

在构建通用型 AI Agent 的技术路线中，目前业界主要分为两种思路：端到端训练 和 上下文工程。

模型厂商掌握强大的闭源模型和丰富的训练经验，因此更倾向于走端到端训练的路线，以发挥自己的独特优势；而 Manus，则选择了上下文工程这条路线。

博客原文内容（前言部分中文翻译）：

在 Manus 项目伊始，我和团队就面临一个关键抉择：是利用开源基础模型训练一个端到端的智能体，还是依托前沿模型的上下文学习能力，在其之上构建智能体？

在我投身 NLP 的第一个十年里，我们并没有这种奢侈的选择。遥想当年 BERT 问世（没错，那已是七年前），模型必须先经过微调——还要评估——才能迁移到新任务。每次迭代往往耗时数周，尽管那时的模型体积与今日的 LLMs 相比微不足道。对于快速迭代的应用，尤其是 PMF 之前的阶段，如此缓慢的反馈循环几乎是致命的。这是我上一家初创公司留下的惨痛教训：当时我从零开始训练模型，用于开放信息抽取和语义搜索。随后 GPT-3 与 Flan-T5 横空出世，我那些自研模型一夜之间便失去了意义。颇具讽刺意味的是，正是这些新模型开启了上下文学习的大门——也为我们指明了一条全新的道路。

这个来之不易的教训让选择变得清晰：Manus 将押注于上下文工程。这让我们能在几小时内发布改进，而非几周，同时也让我们的产品与底层模型保持正交：如果模型进步是上涨的潮水，我们希望 Manus 是船，而不是钉在海床上的柱子。

然而，上下文工程远非一帆风顺。它是一门实验科学——我们已经四次重构了智能体框架，每一次都是在发现更好的上下文塑造方式之后。我们亲切地把这个手动进行架构搜索、提示微调和经验猜测的过程称为「随机梯度下降」（Stochastic Graduate Descent）。它并不优雅，但确实有效。

这篇文章分享了我们通过自身「SGD」抵达的局部最优解。如果你正在构建自己的 AI 智能体，希望这些原则能帮助你更快收敛。

接下来进入正文部分，也就是本篇文章的重点内容。

这一部分汇总了 Manus 团队在服务数百万用户、历经四次系统重构后总结出的六项核心工程实践。

这部分内容不会按照原文进行翻译，会融入我自身的理解，以帮助没有算法背景的小白也能看懂。

01｜围绕 KV-Cache 进行设计

如果只能选一个最重要的性能指标，那我会选 KV 缓存命中率。它能直接决定一个 AI 智能体的响应速度和运行成本。

KV 缓存命中率（KV Cache Hit Rate）可以理解为“模型记住旧内容的效率”。

当 AI 每次生成回答时，它要先“回忆”之前的对话或操作步骤，如果这些内容已经被缓存住了，模型就能跳过重复计算、直接用结果。命中率越高，速度越快、成本越低；命中率低，就像每次都要从头回忆一遍，又慢又费钱。

为什么这么说？我们先来看看一个智能体是怎么工作的：

当用户发来一个请求时，智能体不会一下子就给出答案。它需要调用多个工具，反复尝试，逐步完成任务。

在每一步中，模型都会根据当前的“上下文”（也就是对话历史、工具调用记录等），从一堆预设的“动作”中选出一个，然后在一个模拟环境里执行，比如 Manus 的虚拟机沙箱。执行后，它会得到一个“观察结果”——比如工具的输出或任务的反馈。

接下来，这一步的“动作”和“观察”就会被加到上下文里，变成下一轮模型思考的输入。这个过程会不断循环，直到智能体判断任务完成为止。

类似一个人在一步步试错、一步步总结经验。就是因为这样的循环结构，所以 KV 缓存很重要——它能让模型在每轮思考时，不必重新处理那些没变的部分，节省大量时间和算力。

可以想象一下，AI 智能体在每一步处理时都会把前面所有的对话、操作记录“读一遍”再继续思考，而它最终输出的内容可能只有一句话甚至一个函数调用。这就像你读了一本书，只是为了写一句评语。

以 Manus 为例，模型平均会读进大约 100 个 token，却只生成 1 个 token 的输出。
这种“读得多、写得少”的模式非常浪费时间和资源。

好在，大部分上下文其实是重复的，如果前缀部分没有变，就可以通过 KV 缓存的机制让模型“跳过重复阅读”。这样不光速度快了很多，成本也大大降低。

举个例子：以 Claude Sonnet 为例，缓存过的输入每百万个 token 只花，而没缓存的要3——相差 10 倍！

提高 KV 缓存命中率的几个关键点

从上下文工程的角度来看，如果你想提高 KV 缓存命中率，下面这几点是关键：

1. 保持 Prompt 内容稳定

大模型在生成时是“逐字预测”的，也就是说，从某个词开始不同，后面全都得重新计算。哪怕你只在开头多加了一个字符，也会让整个缓存失效。

比如，有些人喜欢在系统提示里加上“当前时间是 2025-07-21 14:38:56”，这样虽然模型能说出准确时间，但每次都变，缓存就用不了，性能直接打折。

简单原则：只要你希望被缓存的内容，就别让它每次都变。

2. 上下文要“只加不改”

智能体每次执行后的“动作”和“观察结果”会被追加进上下文，如果你去改动历史内容，模型就无法复用原来的缓存。

还有一个隐藏坑：很多人在拼接 JSON 等结构化数据时，忘了保证顺序一致。比如 Python 默认输出 JSON 字典时，键的顺序可能变来变去，看起来一样，其实 token 不一样，也会破坏缓存。

建议：用固定的格式和顺序构建上下文，别动历史记录，也别让结构变来变去。

3. 设置好“缓存断点”

有些模型服务（或者框架）不支持自动识别上下文的哪些部分可以缓存，这时候就需要你手动告诉它：“从这里往前可以缓存”。这个点就叫缓存断点。

比如你可以在系统 Prompt 末尾或者历史记录结束的位置加上特殊标记。注意，断点之后的内容也要保持稳定，否则缓存依然无效。

4. 额外说明

如果你是用类 vLLM 之类的框架自己部署模型，还要注意是否启用了 Prompt 缓存功能，并使用“会话 ID”来确保每个请求都能路由到正确的模型节点，否则缓存也可能失效。

02｜通过“掩码”而不是“移除”来限制智能体的行为选择

随着智能体具备的能力越来越多，它可以调用的“工具”也会迅速膨胀，比如搜索、数据库、计算器、函数调用等等。更别说现在很多人还允许用户自定义工具 —— 一下子塞进几十个、上百个稀奇古怪的能力。

结果就是：工具越多，模型越容易选错，甚至卡壳。

我们原本想让它更聪明，最后却发现它“什么都会，什么都乱用”。

动态增删工具？听起来好，但有坑

一种看起来很合理的思路是：干脆把工具做成“动态加载”的，像搜索文档那样，用的时候再放进来 —— 我们在 Manus 里也试过类似的方式。

但实际效果告诉我们一个明确的经验：

除非真的必要，不要在推理过程中动态增删工具。

为什么？有两个关键原因：

一、改动工具 = 改变上下文结构，缓存就废了

大多数模型会把工具的定义放在上下文的前面，比如系统提示的开头或之后。这意味着你哪怕只动了工具列表的一个小部分，也会让后面的缓存全部失效，模型每轮都得重新计算，性能直接“归零”。

二、模型可能搞不清楚工具到底还在不在

如果前面的推理步骤用过一个工具，而你后来把它删掉了，模型在“记忆”里还保留着这个工具。它一旦尝试再次使用，就可能出错、幻觉，甚至生成完全错误的动作。

替代方案：不删工具，而是“假装它不存在”

为了解决这个问题，Manus 采用了一种更稳妥的方法：不真正移除工具，而是用掩码隐藏它。

具体来说，我们用一个“上下文感知的状态机”来判断哪些工具在当前状态下是“可用”的。但我们不去修改上下文，而是在模型生成动作时，屏蔽掉对应工具的 token，让模型“看不见”它们。

也就是说，工具还在那里，但模型不会选到它。

利用“回复预填充”和命名规则，巧妙限制模型行为

很多同学会问：如果不在上下文中动态增删工具，那怎么让模型只用“当前能用”的那些工具呢？

其实，现在主流的模型和推理框架，大多都支持一种叫做 “响应预填充”（response prefixing）的机制。

简单来说，你可以提前“喂”一部分回复内容给模型，让它在这个基础上继续生成，从而“引导”它的行为方向。

函数调用的三种“预填充”模式（以 Hermes 模型为例）

不同的预填充方式，会对应不同程度的“行为约束”：

Auto 模式：模型自己决定要不要调用函数。预填充形式：<|im_start|>assistant
Required 模式：模型必须调用某个函数，但哪个函数由它自己选。预填充形式：<|im_start|>assistant
Specified 模式：模型只能从某个子集里选函数，比如只选浏览器类工具。预填充形式：<|im_start|>assistant{"name": "browser_...

在 Manus 中，我们正是借助这些机制，配合 token 掩码，来限制模型的“行为空间”。

如何精准控制可选工具？

我们为不同类型的工具设计了统一的命名规则：

所有浏览器相关的工具都以 browser_ 开头；
命令行工具统一用 shell_ 前缀；
数据库操作工具可能是 db_ 开头……

这样一来，当模型处于某个特定状态（比如刚收到用户提问，还没调用任何工具），我们就可以很轻松地在 logits 阶段屏蔽不相关的工具 token，只让它看到符合条件的选项。

比如：刚收到用户提问时，我们就会屏蔽掉所有工具调用的 token，只允许模型直接回复文本。

为什么这套做法好用？

这种方式有几个优点：

无需动态修改上下文内容，缓存稳定不失效；
模型行为清晰可控，不容易“越权”；
简洁通用，不依赖复杂的状态追踪或外部插件；
在大规模部署中也能保持智能体行为稳定。
这让我们的智能体可以在“模型驱动”的架构中，保持清晰、稳健的执行流程，不至于在复杂工具堆里“迷路”。

03｜把文件系统当成“超大号记忆体”

现在的大模型（LLM）上下文窗口越来越大，已经能支持 128K token，甚至更多了。

但现实中，当智能体真正处理一些复杂任务时，我们发现这个“大容量”还是不够用，甚至可能带来新的麻烦。

比如：为什么上下文越长，问题反而越多？

信息太多装不下：比如智能体在处理网页、PDF 或数据库结果这类“大块信息”时，很容易就把上下文撑爆了。
模型越长越糊涂：很多模型在上下文超过某个长度后，准确率其实会下降，不是越大越好。
用得起不代表用得爽：每多一个 token，你都要多付一点钱和时间。即使有缓存优化，传输 + 预处理成本也很可观。

能不能压缩上下文就行了？

很多系统尝试通过“上下文压缩”或“截断历史”来解决这个问题。

但这里有个大坑：你很难预判哪些信息是重要的，哪些可以删。

举个例子：模型在第 3 步看到的一段网页描述，可能要到第 10 步才真正用上。你提前删了它，智能体可能就“断片”了。

所以，我们做了什么？

在 Manus，我们选择了一条不同的思路：

把文件系统当作上下文的一部分，也就是模型的“外部记忆”系统。

模型可以学会将重要信息写入文件，未来再按需读取。就像我们自己会记笔记一样——不是全靠脑子记，而是把关键信息存到能随时翻的地方。

这有什么好处？

无限容量：文件系统几乎可以存下任何量级的信息。
结构化：智能体写入的是有格式的内容，查起来更方便。
可持久使用：写入一次就能反复使用，不用每次都塞进上下文。
不怕忘：不像缓存那样会被新内容挤掉。

这让我们的智能体有了一个“外挂大脑”，可以灵活应对复杂任务，而不必总跟上下文长度作斗争。

让压缩“可还原”，才真正安全

在 Manus，我们采用了一种更稳妥的压缩策略：只压缩可以还原的内容。
比如：

网页内容可以删掉，只要保留它的 URL，之后就能重新抓取回来；
文档内容也可以移除，只要它的路径还在沙盒中可访问，未来模型仍能加载。这样，我们既控制了上下文长度，又不永久丢失任何信息，做到了两全其美。

为什么这对未来的模型架构也很重要？

在开发这些机制的过程中，我开始思考：
如果我们未来用状态空间模型（SSM）来替代 Transformer，会发生什么？

Transformer 的强大，在于它的注意力机制，能处理远距离的信息依赖。
但 SSM 更轻量、速度更快，却不擅长“回头看”，也就是处理长距离依赖。如果 SSM 想在智能体环境中高效工作，它就需要一个“外挂记忆系统” 把长期状态写入文件系统，而不是全都塞在上下文里。这样一来，SSM 不用记住所有历史，只需学会存信息、查信息，就能像大脑一样调取外部记忆。

这种设计有潜力催生一种全新范式的智能体
更快、更轻、更稳，甚至可能成为“神经图灵机”的真正继承者。

04 | 通过“复述”操控注意力

如果你用过 Manus，可能注意到一个小细节：
在处理复杂任务时，它常常会创建一个名为 todo.md 的文件，并在任务推进过程中不断更新
每完成一项就打个勾，有条不紊地推进任务。
这并不是在“卖萌”或凑热闹，而是一种刻意设计的注意力引导机制。

为什么要复述任务？

LLM 是单向解码的语言模型，没有持续注意力机制，随着上下文长度变长，它很容易“忘记”任务目标。
尤其是在处理多轮任务时，模型可能因为中间步骤太多而偏离初衷。

为了缓解这个问题，Manus 让模型自己复述任务目标，甚至主动维护一个待办列表。

这样一来，模型每轮都能重新聚焦在关键目标上，
就像一个人时不时回顾“我到底在干什么”，从而提高整体规划和执行力。

文件系统 + 可视化记忆 = 更稳的任务管理

todo.md 不只是一个“提醒”，还是一种“结构化的外部注意力”机制：

写入任务结构：帮助模型“记住”多步流程。
勾选完成项：形成清晰的进度感与反馈循环。
留在文件系统中：可以随时读取，不占上下文空间。

这种做法也为未来更加稳健的多步规划能力打下了基础。

在 Manus 中，一个典型任务平均会调用约 50 次工具。这意味着智能体需要在几十轮的上下文中持续保持目标清晰，并做出准确决策。

但现实是：
由于 Manus 依赖语言模型（LLM）逐步决策，任务越复杂，模型就越容易跑偏，比如：

忘记最初的任务目标
在中间步骤中陷入细节
偏离正确路径，做出无关决策

“背诵”目标，让模型记得自己在干什么

为了解决这个问题，Manus 会不断重写和更新待办清单，把当前目标、剩余任务，甚至下一步计划持续推送到上下文末尾。

这样一来：

任务目标始终处于模型最近的“视野”中
避免被中间大量上下文“淹没”或“忘记”
不依赖任何模型结构改动，仅靠自然语言方式完成“注意力操控”

你可以把它理解为：Manus 在不断“念叨”任务目标，提醒自己要做什么——这不仅稳定了执行路径，也显著提高了任务完成的准确率。

05 | 保留错误内容，不要“掩盖现场”

智能体会犯错，这并不意味着系统有 bug，而是语言模型运行过程中的正常现象：

模型可能出现幻觉（hallucination）
工具调用出错或环境响应异常
遇到意料之外的边缘情况在多步骤任务中，失败不是例外，而是常态的一部分。

常见误区：掩盖错误 = 掩盖学习机会

很多开发者在遇到错误时，会有一种“清理冲动”：

删除报错记录
重置模型状态再试
调整 temperature 参数重新生成结果看上去是“解决问题”，但本质上是掩盖了失败的证据。

而一旦没有了这些证据，模型就很难理解失败原因、更别说从中调整行为。

在 Manus 中，我们有意识地保留每一次错误、失败和中断的记录，并将它们写入上下文。
这不仅帮助模型逐步修正行为，也让后续的分析和改进变得更加可追踪。

把“走错的路”留在上下文里

根据我们的经验，有一个简单但非常有效的提升方式：不要删除失败的记录，而是把它保留下来。

当模型看到自己之前“走错的路”——包括错误的动作、报错提示、异常堆栈等——它会潜移默化地调整策略。这些“负面样本”能帮助它：

避免重复犯同样的错误
修正对工具或环境的误解
更贴近真实的任务反馈机制

从这个角度来看，错误恢复其实才是智能体真正“智能”的体现。

它能从失败中学会调整，而不是一味重置、清空状态、重新来过。

现实 vs 基准测试

可惜的是，在很多学术研究和公开基准中，这种能力被严重低估。

它们通常只关注“成功率”或“是否完成任务”，而忽略了真实场景中最常见的情况：失败、试错和修正。

06 | 小心被 Few-Shot「反噬」

Few-Shot Prompting（少样本提示）是提升大模型表现的经典技巧。但在智能体系统中，它有时会变成一把“双刃剑”。

语言模型非常擅长模仿。

当它看到上下文中重复出现的行为模式，就会不加判断地沿用，哪怕这个模式已经不合适。

比如你让 Manus 批量审阅 20 份简历，它在处理前几份时表现得不错。

但到了后面，模型就可能“带着节奏走”——因为上下文里全是相似的处理方式，它就不断照抄照搬，哪怕每份简历的内容大不相同。

这种“路径依赖”会带来问题：

决策漂移：不再因内容变化而调整策略
过度泛化：看到一点相似就复制整套流程
甚至幻觉：凭空生成看起来“像是对的”内容

解决这个问题的关键，是增加上下文的多样性。

Manus 的做法是在“动作”和“观察”中，故意加入一些小小的变化 —— 比如换一种格式、调整下顺序、或者用不同的表达方式。

这些看似微妙的差异，其实能有效打破模型对固定模式的依赖，让它保持“思考”而不是“复制”。

换句话说：不要让智能体只活在几个死板例子里。上下文越单一，Agent 越容易出错。

总结

总体来看，Manus 团队分享的这些工程实践，最大的价值在于方法的通用性与系统性，尤其适合对性能有精细化控制需求的场景。

不过需要说明的是，对于 RAGFlow、Dify 等封装程度较高的开源框架，这些底层优化手段难以直接应用，还需结合具体项目做适配与取舍。

文章内容来自公众号：亲爱的缪斯