最近，Manus AI 全面退出中国市场，其社交媒体内容全部清空，国内的网站也打不开，引发大家对 Manus “跑路”的猜测。
今天凌晨，Manus 联合创始人季逸超（Yichao 'Peak' Ji）在博客撰文，分享 Manus 研发过程中，围绕 Agent 构建中的一些实践经验和技术。整体阅读下来，非常有收获，对于 Agent 开发者和日常使用大模型的普通人，都可能会有启发。
我自己看下来的感受是，构建 Agent 已经超越了 LLM 工程，成为一个全新的系统工程学科。它需要考虑状态管理、记忆架构、错误恢复等传统 NLP 不涉及的问题。
核心洞察：
1. KV-缓存是生产级智能体的生命线； 2. Agent 工具调用中，要使用屏蔽而非移除； 3. 将文件系统作为无限、持久、可操作的上下文； 4. 保留错误让模型从失败中学习适应，引入结构化多样性避免重复模式。
以下是全文翻译，原始博客链接：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
在 Manus 项目初期，团队面临一个关键决策：
应该使用开源基础模型训练一个端到端的智能体模型，还是在前沿模型的上下文学习（in-context learning）能力基础上构建智能体？
回想我在NLP领域的第一个十年，我们并没有这样选项。在 BERT 时代（是的，已经过去七年了），模型必须经过微调和评估才能迁移到新任务上。即使当时的模型相比今天的大语言模型来说，参数量微不足道，这个过程每次迭代也需要数周时间。对于快速发展的应用，特别是在产品市场契合度（PMF）之前，如此缓慢的反馈循环是致命的。
这是我从上一个创业项目中学到的痛苦教训，当时我从零开始训练开放信息抽取和语义搜索的模型。然后 GPT-3和 Flan-T5 出现了，我的内部模型一夜之间变得毫无意义。讽刺的是，正是这些模型标志着上下文学习的开始——以及一条全新的前进道路。
这个来之不易的教训让选择变得明确：Manus 将押注于上下文工程。这让我们能够在几小时而不是几周内发布改进，并保持我们的产品与底层模型的正交性：如果模型进步是涨潮，我们希望 Manus 是船，而不是被固定在海床上的柱子。
然而，上下文工程并不简单直接。它是一门实验科学——我们已经重建了四次智能体框架，每次都是在发现更好的上下文塑造方法之后。我们将这个包含架构搜索、提示调优和经验猜测的手动过程称为"随机玄学下降（ Stochastic Graduate Descent）"。它不够优雅，但确实有效。
这篇文章分享我们通过自己的 "SGD-Stochastic Graduate Descent" 达到的局部最优解。如果你正在构建自己的AI智能体，我希望这些原则能帮助你更快收敛。
围绕KV-Cache进行设计
如果我选择一个指标，我认为 KV-cache 命中率是生产阶段 AI 智能体最重要的单一指标。它直接影响延迟和成本。为了理解原因，让我们看看典型智能体的运作方式：
在接收到用户输入后，智能体通过一系列工具使用来完成任务:
在每次迭代中，模型基于当前上下文从预定义的动作空间中选择一个动作。然后在环境中执行该动作（例如，Manus的虚拟机沙箱）以产生观察结果。动作和观察结果被追加到上下文中，形成下一次迭代的输入。这个循环持续进行，直到任务完成。
正如你所想象的，上下文随着每一步而增长，而输出(通常是结构化的函数调用)保持相对较短。
这使得智能体中预填充(prefilling)和解码(decoding)之间的比例相比聊天机器人更高。例如，在 Manus 中，平均输入与输出的 token 比例大约是100:1。
幸运的是，具有相同前缀的上下文可以利用 KV-cache，这大大减少了首个 token 时间（TTFT）和推理成本——无论你使用的是自托管模型还是调用推理API。我们谈论的不是小幅节省：以 Claude Sonnet 为例，缓存的输入token成本为0.30美元/MTok，而未缓存的成本为3美元/MTok——相差10倍。
从上下文工程的角度来看，提高KV-cache命中率涉及几个关键实践：
1. 保持提示前缀稳定。
由于大语言模型的自回归特性，即使是单个 token 的差异也会使从该 token 开始的缓存失效。一个常见错误是在系统提示的开头包含时间戳——特别是精确到秒的时间戳。当然，这让模型能够告诉你当前时间，但也会破坏你的缓存命中率。
2. 让上下文只进行追加。
避免修改之前的动作或观察结果。确保你的序列化是确定性的。许多编程语言和库在序列化 JSON 对象时不保证稳定的键排序，这可能会无声地破坏缓存。
3. 在需要时明确标记缓存断点。
一些模型提供商或推理框架不支持自动增量前缀缓存，而是需要在上下文中手动插入缓存断点。在分配这些断点时，要考虑潜在的缓存过期，至少确保断点包含系统提示的结尾。
此外，如果你使用vLLM等框架自托管模型，请确保启用前缀/提示缓存，并使用会话ID等技术在分布式工作节点间一致地路由请求。
屏蔽而非移除
随着智能体承担更多功能，其动作空间自然变得更加复杂，即工具数量激增。最近MCP的流行更是火上浇油。如果允许用户配置工具，相信我：总会有人将数百个神秘工具插入你精心策划的动作空间。结果，模型更容易选择错误的动作或采取低效的路径。
这也就是说，装备精良的智能体变得更笨了。
自然的反应是设计一个动态动作空间——也许使用类似 RAG 的方法按需加载工具。我们在 Manus 中也尝试过这种方法。但我们的实验表明了一个明确的规则：除非绝对必要，避免在迭代过程中动态添加或删除工具。
主要原因有两个：
1. 在大多数大语言模型中，工具定义在序列化后位于上下文的前端，通常在系统提示之前或之后。因此任何更改都会使所有后续动作和观察的 KV-cache 失效。 2. 当之前的动作和观察仍然引用当前上下文中不再定义的工具时，模型会感到困惑。在没有约束解码（constrained decoding）的情况下，这通常导致模式违反或幻觉动作（schema violations or hallucinated actions）。
为了解决这个问题同时改进动作选择，Manus 使用上下文感知状态机（context-aware state machine）来管理工具可用性。它不是移除工具，而是在解码过程中屏蔽 token 概率，以根据当前上下文阻止（或强制）选择某些动作。
在实践中，大多数模型提供商和推理框架都支持某种形式的响应预填充，这允许你在不修改工具定义的情况下约束动作空间。一般有三种函数调用模式（我们以NousResearch的Hermes格式为例）：
• 自动 – 模型可以选择调用函数或不调用。通过仅预填充回复前缀实现：<|im_start|>assistant
• 必需 – 模型必须调用函数，但选择不受约束。通过预填充到工具调用token实现：<|im_start|>assistant<tool_call>
• 指定 – 模型必须从特定子集中调用函数。通过预填充到函数名开头实现：<|im_start|>assistant<tool_call>{"name": "browser_
使用这种方法，我们通过直接屏蔽 token 概率来约束动作选择。例如，当用户提供新输入时，Manus必须立即回复而不是采取动作。
我们还故意设计了具有一致前缀的动作名称——例如，所有浏览器相关工具都以browser_开头，命令行工具以shell_开头。这使我们能够轻松强制智能体在给定状态下只从特定工具组中选择，而无需使用有状态的概率处理器。
这些设计帮助确保 Manus 智能体循环保持稳定——即使在模型驱动的架构下。
使用文件系统作为上下文
前沿大语言模型现在提供 128K token或更多的上下文窗口。但在现实世界的智能体场景中，这通常是不够的，有时甚至是负担。有三个常见痛点：
1. 观察结果可能很庞大，特别是当智能体与网页或PDF等非结构化数据交互时。很容易超过上下文限制。 2. 超过一定上下文长度后，模型性能往往下降，即使窗口技术上支持它。 3. 长输入很昂贵，即使有前缀缓存。你仍然需要为传输和预填充每个 token 付费。
为了解决这个问题，许多智能体系统实施上下文截断或压缩策略。但过度激进的压缩不可避免地导致信息丢失。因为智能体本质上必须基于所有先前状态预测下一个动作，而你无法可靠地预测哪个观察可能在十步后变得关键。从逻辑角度来看，任何不可逆的压缩都带有风险。
这就是为什么我们在 Manus 中将文件系统视为最终上下文（file system as the ultimate context）：大小不受限制，本质上持久，并且可由智能体本身直接操作。模型学会按需读写文件——使用文件系统不仅作为存储，而且作为结构化的外部化内存。
我们将压缩策略设计为可恢复的。例如，只要URL被保留，网页的内容就可以从上下文中删除，如果文档的路径在沙箱中仍然可用，文档的内容就可以省略。这允许 Manus 缩短上下文长度而不永久丢失信息。
在开发这个功能时，我发现自己在想象状态空间模型（State Space Model，SSM）在智能体设置中有效工作需要什么。
与Transformer不同，SSMs 缺乏完全注意力，在长程反向依赖方面有困难。但如果它们能掌握基于文件的内存——外部化长期状态而不是在上下文中保持它——那么它们的速度和效率可能会解锁新一类智能体。智能体SSMs可能是神经图灵机的真正继承者。
重述操作注意力
如果你使用过 Manus，你可能注意到了一些有趣的事情：在处理复杂任务时，它倾向于创建一个 todo.md 文件——并随着任务进展逐步更新它，勾选已完成的项目。
这是操作注意力（manipulate attention）的深思熟虑的机制。
Manus中的典型任务平均需要大约50次工具调用。这是一个长循环——由于Manus依赖大语言模型进行决策，它容易偏离主题或忘记早期目标，特别是在长上下文或复杂任务中。
通过不断重写待办事项列表，Manus 将其目标重述到上下文的末尾。这将全局计划推入模型的近期注意力范围，避免"在中间丢失"问题并减少目标不对齐。
实际上，它使用自然语言来偏向其自身对任务目标的关注——而无需特殊的架构更改。
保留错误信息
智能体会犯错误。这不是bug——这是现实。LLM 会产生幻觉，比如环境返回错误，外部工具行为异常，意外的边缘情况总是出现。在多步任务中，失败不是例外；它是循环的一部分。
然而，一个常见的冲动是隐藏这些错误：清理跟踪，重试动作，或重置模型状态并交给"temperature"参数。这感觉更安全，更可控。但这是有代价的：擦除失败会移除证据。没有证据，模型无法适应。
根据我们的经验，改进智能体行为最有效的方法之一看似简单：
将错误保留在上下文中（leave the wrong turns in the context）。
当模型看到失败的动作——以及结果观察或堆栈跟踪——它隐式更新其内部信念。这将其先验从类似动作中转移，减少重复同样错误的机会。
事实上，我们认为错误恢复（error recovery）是真正智能体行为最清晰的指标之一。然而，在大多数学术工作和公共基准测试中，它仍然代表性不足，这些测试通常专注于理想条件下的任务成功。
避免被少样本提示困住
少样本提示是改进 LLM 输出的常见技术。但在智能体系统中，它可能适得其反。
LLM 是优秀的模仿者；它们模仿上下文中的行为模式。如果你的上下文充满了类似的过去动作-观察对，模型会倾向于遵循该模式，即使它不再是最优的。
这在涉及重复决策或动作的任务中可能很危险。例如，当使用 Manu s帮助审查20份简历时，智能体经常陷入这样的无效循环：重复相同的动作，仅仅因为这是它在上下文中看到的。这导致漂移、过度泛化，或有时幻觉。
解决方案是增加多样性。Manus 在动作和观察中引入少量结构化变化——不同的序列化模板、替代措辞、顺序或格式中的轻微噪声。这种受控的随机性有助于打破模式并调整模型的注意力。
换句话说，不要让少样本提示把自己困在窠臼中（don't few-shot yourself into a rut）。你的上下文越统一，你的智能体就越脆弱。
结论
上下文工程仍然是一门新兴科学——但对于智能体系统来说，它已经是必不可少的。模型可能变得更强、更快、更便宜，但再多的原始能力都无法替代对内存、环境和反馈的需求。
如何塑造上下文最终定义了智能体如何行为：它运行多快，恢复得多好，以及扩展到多远。
在 Manus，我们通过反复重写、dead ends 和数百万用户的现实世界测试学到了这些教训。我们在这里分享的没有一个是普遍真理——但这些是对我们有效的模式。如果它们能帮助你避免哪怕一次痛苦的迭代，那么这篇文章就完成了它的使命。
Agent 的未来，始于上下文的精雕细琢。
