Manus 揭秘自己的七大核心技术：上下文工程架构设计与落地经验 原创 精华

随着 AI 智能体技术的快速发展，如何高效构建和优化 AI 智能体系统已成为业界关注的焦点。本文是对 7月19日 Manus 联合创始人兼首席科学家季逸超（Yichao 'Peak' Ji）在撰写的《Context Engineering for AI Agents: Lessons from Building Manus》一文的整理。

Image

Manus 团队在构建 AI 智能体过程中关于上下文工程的宝贵经验，包括： KV 缓存优化设计、动态动作空间管理设计以及利用文件系统作为扩展上下文等7大核心技术架构设计。

这些经验不仅揭示了当前 AI 智能体开发的技术架构设计的挑战和解决思路，也为未来  AI 智能体技术的发展提供了重要参考。

下文我们详细剖析之，

Manus 智能体6大核心技术剖析

1、围绕 KV 缓存进行设计

如果必须选择一个关键指标，KV 缓存命中率无疑是生产环境中 AI 智能体最重要的指标。KV 缓存是 Transformer 模型中用于存储注意力计算结果的机制，高命中率意味着可以重用之前的计算结果，从而显著降低延迟和成本。

第一、KV 缓存的重要性

典型 AI 智能体的运作流程如下：

用户输入后，AI 智能体通过一系列工具调用来完成任务。在每次迭代中，模型根据当前上下文从预定义的动作空间中选择一个动作，并在环境中执行（比如：Manus 的虚拟机沙盒环境，用于确保代码安全运行），从而产生观测结果。动作和观测结果被附加到上下文中，形成下一次迭代的输入，循环直到任务完成。

由于 AI 智能体的上下文随着每一步增长，而输出（通常是结构化的函数调用）相对较短，因此 AI 智能体的预填充（prefilling，一次性处理输入 token 的阶段）和解码（decoding，逐个生成输出 token 的阶段）比例与聊天机器人相比高度倾斜。比如：在 Manus 中，平均输入与输出 token 比例约为100:1。

幸运的是，具有相同前缀的上下文可以利用 KV 缓存，这大大减少了首 token 时间（TTFT，Time-To-First-Token）和推理成本。比如：使用Claude Sonnet 时，缓存的输入 token 成本为0.30美元/百万 token，而未缓存的成本为3美元/百万 token，相差10倍。

第二、提高 KV 缓存命中率的关键实践

• 保持提示词前缀稳定

由于 LLMs 的自回归特性（模型按顺序生成 token，每个 token 的生成都依赖于之前的所有 token），即使是单个 token 的差异也可能使该 token 之后的缓存失效。一个常见错误是在系统提示词的开头包含时间戳（特别是精确到秒的时间戳），这虽然能让模型告诉你当前时间，但会直接降低缓存命中率。

• 使上下文仅追加（append-only）

避免修改之前的动作或观测结果，确保序列化过程是确定性的。许多编程语言和库在序列化 JSON 对象时不保证稳定的键排序，这可能会悄无声息地破坏缓存。

• 明确标记缓存断点

一些模型提供商或推理框架不支持自动增量前缀缓存，而是需要在上下文中手动插入缓存断点。分配这些断点时，要考虑潜在的缓存过期时间，并确保断点包含在系统提示词的末尾。

此外，如果你使用 vLLM（一个高性能的 LLM 推理框架）等框架自托管模型，请确保启用前缀/提示词缓存，并使用会话 ID 等技术在分布式工作节点间一致地路由请求。

2、遮蔽（Mask），而非移除

随着 AI 智能体能力的提升，其动作空间（action space）会变得愈发复杂，工具数量也会呈爆炸式增长。最近 MCP 的流行更是加剧了这一问题。如果允许用户配置工具，总有人会将大量不明来源的工具塞入精心设计的动作空间中，导致模型更容易选错行动或采取低效路径，从而使 AI 智能体变得迟钝。

一种自然的想法是设计一个动态的动作空间，按需动态加载工具，在 Manus 中也尝试过这种方法。但实验表明，除非绝对必要，否则应避免在迭代中途动态增删工具，原因主要有以下两点：

1. 在大多数大模型中，工具定义在序列化后通常位于上下文的靠前位置，通常在系统提示词之前或之后。因此，任何更改都会导致后续所有动作和观测的 KV 缓存失效。
2. 当此前的动作和观测仍然引用着当前上下文中不再定义的工具时，模型会感到困惑。如果没有约束解码（constrained decoding），这通常会导致模式违规或产生幻觉动作。

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

Image

在实践中，大多数模型提供商和推理框架都支持某种形式的响应预填充，这允许你在不修改工具定义的情况下约束动作空间。函数调用通常有以下三种模式（以 NousResearch 的 Hermes format 为例）：

• 自动（Auto）：模型可以选择调用函数，也可以不调用。通过仅预填充回复前缀实现：​​<|im_start|>assistant​​。
• 必需（Required）：模型必须调用一个函数，但具体调用哪个不受限制。通过预填充至工具调用token实现：​​<|im_start|>assistant<tool_call>​​。
• 指定（Specified）：模型必须从一个特定的子集中调用函数。通过预填充至函数名的开头实现：​​<|im_start|>assistant<tool_call>{"name": "browser_"}​​。

利用这一点，我们通过直接遮蔽 token logits 来约束动作选择。比如：当用户提供新输入时，Manus 必须立即回复，而不是执行动作。

我们还设计了具有一致性前缀的动作名称，比如：所有浏览器相关的工具都以​​browser_​​​开头，而命令行工具则以 ​​shell_ ​​开头。这使得我们能够在特定状态下，轻松地强制 AI 智能体只能从某一类工具中进行选择，而无需使用有状态的 logits 处理器。

这些设计有助于确保 Manus 的 AI 智能体 loop 在模型驱动的架构下，依然保持可靠稳定。

3、将文件系统作为上下文

尽管现代前沿大模型已经能够支持高达 128K 甚至更长的上下文窗口，但在实际的 AI 智能体应用场景中，这往往仍然不够，甚至有时会成为负担。以下是三个常见的痛点：

• 观测结果过于庞大

当 AI 智能体与网页、PDF 等非结构化数据交互时，观测结果可能极其庞大，很容易超出上下文长度的限制。

• 模型性能下降

即使模型在技术上支持长上下文窗口，其性能通常会在上下文长度超过一定阈值后显著下降。

• 成本高昂

长输入的成本非常高，即使有前缀缓存，你仍然需要为每个 token 的传输和预填充支付费用。

为了解决这些问题，许多 AI 智能体系统采用了上下文截断或压缩策略。然而，过于激进的压缩不可避免地会导致信息丢失。这是一个根本性问题，因为 AI 智能体需要基于所有先前的状态来预测下一个动作，而你无法可靠地预测哪些观测结果在未来会变得至关重要。从逻辑上讲，任何不可逆的压缩都伴随着风险。

第一、文件系统作为终极上下文

因此，我们将文件系统视为 Manus 的终极上下文解决方案。文件系统具有以下优势：

• 无限容量：文件系统的容量几乎是无限的。
• 天然持久：文件系统是持久化的，数据不会因为上下文的限制而丢失。
• 直接操作：AI 智能体可以直接操作文件系统，按需读写文件。

模型不仅将文件系统用作存储，更是将其视为一个结构化的外部记忆体。通过这种方式，模型可以按需读写文件，而不是将所有信息都保留在上下文中。

第二、可恢复的压缩策略

我们的压缩策略始终被设计为可恢复的，比如：

• 网页内容：只要保留了网页的 URL，其内容就可以从上下文中丢弃。
• 文档路径：只要文档在其沙箱中的路径可用，其内容也可以被省略。

通过这种方式，Manus 可以在不永久丢失信息的前提下，有效缩减上下文长度。

第三、对状态空间模型的思考

在开发此功能时，我常常思考，如何让一个状态空间模型（SSM）在 AI 智能体场景中有效工作。与 Transformer 不同，SSM 缺乏全局注意力，难以处理长程的回溯依赖。但如果它们能够掌握基于文件的记忆——将长期状态外化，而不是保留在上下文中——那么它们的速度和效率或许能开启一类全新的 AI 智能体。具备 AI 智能体能力的 SSM，或许才是 Neural Turing Machines 真正的继承者。

4、通过“复述”来操控注意力

如果你使用过 Manus，可能已经注意到一个有趣的现象：在处理复杂任务时，Manus 会创建一个名为 ​​todo.md ​​的文件，并随着任务的进展逐步更新它，勾掉已完成的项。这并非只是为了看起来“可爱”，而是一种精心设计的注意力操控机制。

在 Manus 中，一个典型任务平均需要约50次工具调用。这是一个相当长的循环，由于 Manus 依赖大模型进行决策，很容易出现偏离主题或忘记早期目标的问题，尤其是在长上下文或复杂任务中。

通过不断更新待办事项列表，Manus 实际上是在将任务目标“复述”到上下文的末尾。这将全局计划注入到模型的近期注意力范围，从而避免“中间遗忘”（lost-in-the-middle）问题，并减少目标偏离。实际上，这是一种用自然语言引导自身注意力的方式，使其聚焦于任务目标，而无需依赖特殊的架构。

5、保留出错记录

 AI 智能体会犯错，这不是一个缺陷，而是现实的一部分。语言模型可能会产生幻觉，运行环境可能会返回错误，外部工具可能会出现故障，各种意想不到的边界情况也屡见不鲜。在多步骤任务中，失败并不是例外，而是整个流程的组成部分。

然而，一个常见的做法是隐藏这些错误：清理错误痕迹、重试动作，或者重置模型状态，然后将其交给所谓的“温度（Temperature）”参数来调整。这种做法看似更安全、更可控，但却有代价：它消除了失败的记录，也就抹去了过往行动的证据。而没有这些证据，模型就无法从中学习和适应。

根据我们的经验，提升 AI 智能体行为表现最有效的方法之一其实非常简单：将失败的尝试保留在上下文中。当模型看到一个失败的动作——以及由此产生的观测结果或堆栈跟踪（stack trace）——它会隐式地更新其内部认知，改变对相似动作的先验判断，从而减少重复犯同样错误的可能性。

事实上，我们认为错误恢复能力是真正 AI 智能体行为最明确的标志之一。然而，在大多数学术研究和公开基准测试中，这一点仍然没有得到充分的体现，它们往往只关注理想条件下的任务成功率。

6、不要陷入 Few-Shot 陷阱

Few-shot Prompting 是一种常用技术，用于通过少量示例提升大语言模型的输出表现。然而，在构建 AI 智能体系统时，它可能会带来一些意想不到的问题。

语言模型本质上是出色的模仿者，它们会学习并模仿上下文中呈现的行为模式。如果上下文中充斥着大量相似的“动作-观测结果”对，模型往往会倾向于遵循这些模式，即使这些模式已经不再是最优选择。

这在涉及重复性决策或动作的任务中尤其危险。比如 ：在使用 Manus 协助审阅 20 份简历时，AI 智能体可能会陷入一种惯性节奏，仅仅因为它在上下文中看到了类似的行为，就不断重复相似的动作。这不仅会导致行为漂移和过度泛化，有时甚至会产生幻觉。

为了解决这一问题，Manus 在动作和观测结果中引入了少量结构化的变动，比如：使用不同的序列化模板、变换措辞、在顺序或格式上引入微小的噪音。这种受控的随机性有助于打破单一的模式，调整模型的注意力，使其更加灵活。

简而言之，不要让自己陷入“少样本”的思维定势中。上下文的模式越单一，AI 智能体的行为就越脆弱。多样化是提升 AI 智能体稳定性和适应性的关键。

7、上下文工程：AI 智能体系统的核心

上下文工程虽然还是一门新兴学科，但对于 AI 智能体系统来说，它已经变得至关重要。无论模型变得多么强大、快速或低成本，都无法替代对记忆、环境和反馈的需求。你如何塑造上下文，最终决定了AI 智能体的行为方式：它的运行速度、恢复能力和扩展潜力。

第一、Manus 的经验

在 Manus，我们通过不断的重构、失败的尝试以及面向数百万用户的真实世界测试，才逐步积累了这些宝贵的经验。我们分享的这些经验并非放之四海而皆准的真理，但它们对 Manus 来说是行之有效的。如果这些经验能帮助你减少哪怕一次痛苦的迭代，那么我们的分享就达到了目的。

第二、AI 智能体的未来

AI 智能体的未来将由一个个精心设计的上下文构建而成。希望你能精心设计它们，让AI 智能体发挥出最大的潜力。