在爆火仅四个月后，Manus AI 突然几乎全面撤出中国市场，不仅清空全部社交账号内容，而且国行版本的 Manus 也疑似暂停推进。
早在上个月，Manus 联合创始人张涛便曾宣布，公司已将全球总部迁至新加坡，并在东京和加州设有办公室。尽管官方未正面回应，只称是「基于经营效率的调整」，但出海所引发裁员等一连串争议问题，也让外界普遍猜测其是否正在「跑路」。
风波之中，今天凌晨，Manus 联合创始人季逸超发布了一篇技术博客，试图将外界关注点重新拉回产品技术本身。
经过四次重构和数百万真实交互，他在文中坦诚地总结了团队在构建 Manus 过程中积累的经验教训。内容既有实操干货，也不乏反思，对业内同行与普通用户来说，都不失为一份值得一读的参考材料。
技术博客地址：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
省流版：
1. 押注上下文，不再训练模型 与其耗时训练，不如围绕大模型构造「记忆」和流程。上下文工程让你在几小时而不是几周内发布产品更新。
2. KV-Cache 命中率至关重要 输入越稳定，缓存命中率越高，成本和延迟越低。三条实战建议： - 避免提示中使用时间戳； - 只追加上下文，避免修改历史记录； - 手动标记缓存断点，保障前缀一致性。
3. 工具不要动态添加，而是用「遮蔽」法控制选择 动态修改工具列表会让缓存失效、模型混乱。Manus 使用「遮蔽 token logits」的方法，让模型「看不见」不应调用的工具。
4. 用文件系统承载持久上下文 大模型上下文再长也会被打满。Manus 让模型把长期记忆写入虚拟文件系统，按需读写，实现「外部记忆」，规避信息丢失。
5. 重写 ToDo 清单，是操控注意力的重要方法 模型容易「中途忘记目标」。Manus 会不断用自然语言更新并重述 todo.md 文件，把全局目标拉回注意力焦点，防止任务跑偏。
6. 错误不是要掩盖，而是要保留 失败是构建 Agent 过程中的一部分。保留错误日志（如失败的操作、堆栈信息），能帮助模型更新内部信念，减少重复错误。
7. 少样本提示不是灵丹妙药，要防「同质化陷阱」 模型会盲目模仿上下文中的行为模式。Manus 通过引入结构化变化（如不同措辞或顺序），避免模型在长任务中陷入复制粘贴式幻觉。
AI Agent 的上下文工程：从构建 Manus 中学到的经验
在 Manus 项目的最初阶段，我和我的团队面临一个关键决定：我们应该使用开源基础模型训练一个端到端的 Agent，还是基于前沿模型的上下文学习能力构建一个 Agent？
在我从事 NLP 的第一个十年，我们没有这种选择的奢侈。在遥远的 BERT 时代（是的，已经过去七年了），模型必须先进行微调——并评估——才能转移到新任务。这个过程通常每次迭代需要数周时间，即使与今天的 LLM 相比，这些模型都很小。对于快速发展的应用，特别是在产品市场契合度（PMF）之前，这种缓慢的反馈循环是一个致命问题。
这是我上一个创业公司的惨痛教训，我从头开始为开放信息提取和语义搜索训练模型。然后 GPT-3 和 Flan-T5 出现了，我的内部模型一夜之间变得无关紧要。讽刺的是，这些相同的模型标志着上下文学习的开始——以及一条全新的前进道路。
这个来之不易的教训使选择变得明确：Manus 将押注于上下文工程。这使我们能够在几小时内而非几周内推出改进，并使我们的产品与底层模型保持正交：如果模型进步是上涨的潮水，我们希望 Manus 成为那条船，而不是固定在海床上的柱子。
然而，上下文工程证明并非那么直截了当。它是一门实验科学——我们已经重建了我们的 Agent 框架四次，每次都是在发现了更好的塑造上下文的方式之后。我们亲切地将这种手动架构搜索、提示调整和经验猜测的过程称为「随机研究生下降法」。它不够优雅，但很有效。
这篇文章分享了我们通过自己的「SGD」所达到的局部最优解。如果你正在构建自己的 AI Agent，我希望这些原则能帮助你更快地收敛。
围绕 KV-Cache 进行设计
如果我必须选择仅一个指标，我认为 KV-cache 命中率是生产阶段 AI Agent最重要的单一指标。它直接影响延迟和成本。为了理解原因，让我们看看典型 Agent 如何运作：
在接收用户输入后，Agent 通过一系列工具使用来完成任务。在每次迭代中，模型根据当前上下文从预定义的动作空间中选择一个动作。然后该动作在环境（例如，Manus 的虚拟机沙盒）中执行以产生观察结果。动作和观察结果被附加到上下文中，形成下一次迭代的输入。这个循环持续直到任务完成。
正如你可以想像，上下文随著每一步而增长，而输出——通常是结构化的函数调用——保持相对简短。这使得Agent 程序中的预填充和解码比例与聊天机器人相比高度倾斜。例如，在 Manus 中，平均输入与输出 token 比率约为 100:1。
幸运的是，具有相同前缀的上下文可以利用 KV-cache，这大大减少了首个 token 的时间 (TTFT) 和推理成本——无论你使用的是自托管模型还是调用推理 API。我们谈论的不是小额节省：以 Claude Sonnet 为例，缓存的输入 token 成本为 0.30 美元/MTok(每百万 token)，而未缓存的成本为 3 美元/MTok——相差 10 倍。
从上下文工程的角度来看，提高 KV-缓存命中率涉及几个关键实践：
1.
保持提示前缀稳定。 由于 LLM 的自回归特性，即使单个标记的差异也会使该标记之后的缓存失效。一个常见的错误是在系统提示的开头包含时间戳——尤其是精确到秒的时间戳。没错，它可以让模型告诉你当前时间，但它也会降低你的缓存命中率。
2.
使你的上下文仅追加。 避免修改先前的操作或观察。确保你的序列化是确定性的。许多程式语言和库在序列化 JSON 对象时不保证稳定的键排序，这可能会悄悄破坏缓存。
3.
在需要时明确标记缓存断点。 某些模型提供商或推理框架不支持自动增量前缀缓存，而是需要在上下文中手动插入缓存断点。在分配这些断点时，要考虑潜在的缓存过期，并至少确保断点包含系统提示的结尾。
此外，如果你正在使用 vLLM 等框架自托管模型，请确保启用前缀/提示缓存，并且你正在使用会话 ID 等技术来一致地路由分布式工作节点间的请求。
遮蔽，而非移除
随著你的 Agent 获得更多能力，其行动空间自然变得更加复杂——简单来说，工具数量爆炸性增长。最近流行的 MCP 只会火上浇油。如果你允许用户配置工具，相信我：总会有人不可避免地将数百个神秘工具插入到你精心策划的行动空间中。结果，模型更可能选择错误的行动或采取低效的路径。简而言之，你的全副武装的 Agent 变得更笨了。
一个自然的反应是设计一个动态行动空间——也许使用类似 RAG 的东西按需加载工具。我们在 Manus 中也尝试过这种方法。但我们的实验表明一个明确的规则：除非绝对必要，避免在迭代过程中动态添加或移除工具。这主要有两个原因：
1. 在大多数 LLMs 中，工具定义在序列化后位于上下文的前部，通常在系统提示之前或之后。因此，任何更改都将使所有后续操作和观察的 KV-缓存失效。
2. 当先前的操作和观察仍然引用在当前上下文中不再定义的工具时，模型会变得困惑。没有约束解码，这通常会导致模式违规或幻觉行为。
为了解决这个问题，同时仍然改进行动选择，Manus 使用上下文感知的状态机来管理工具可用性。它不是移除工具，而是遮蔽 token logits，在解码过程中防止（或强制）基于当前上下文选择某些行动。
在实践中，大多数模型提供者和推理框架支持某种形式的回应前缀预填充，这允许你在不修改工具定义的情况下限制动作空间。通常有三种函数调用模式（我们将使用来自 NousResearch 的 Hermes 格式作为例子）：
•自动 – 模型可以选择调用函数或不调用。通过仅预填充回复前缀来实现：<|im_start|>assistant
•必需 – 模型必须调用函数，但选择不受限制。通过预填充到工具调用标记来实现：<|im_start|>assistant
•指定 – 模型必须从特定子集中调用函数。通过预填充到函数名称的开头来实现：<|im_start|>assistant{「name」: "browser_
使用这个，我们通过直接遮蔽 token 的 logits 来限制动作选择。例如，当用户提供新输入时，Manus 必须立即回复而不是采取动作。我们还特意设计了具有一致前缀的动作名称——例如，所有与浏览器相关的工具都以 browser_开头，命令行工具则以 shell_开头。这使我们能够轻松地强制 Agent 在给定状态下只从某个特定工具组中进行选择，而无需使用有状态的 logits 处理器。
这些设计有助于确保 ManusAgent 循环保持稳定——即使在模型驱动的架构下。
使用文件系统作为上下文
现代前沿大语言模型现在提供 128K 个 token 或更多的上下文窗口。但在真实世界的 Agent 场景中，这通常不够，有时甚至是一种负担。有三个常见的痛点：
1. 观察可能非常庞大，尤其是当 Agent 与网页或 PDF 等非结构化数据互动时。很容易超过上下文限制。
2. 模型性能往往会下降，超过一定的上下文长度后，即使技术上支援该窗口大小。
3. 长输入成本高昂，即使使用前缀缓存。你仍需要为传输和预填充每个标记付费。
为了解决这个问题，许多 Agent 系统实现了上下文截断或压缩策略。但过度激进的压缩不可避免地导致信息丢失。这个问题是根本性的：Agent 本质上必须基于所有先前状态预测下一个动作——而你无法可靠地预测哪个观察可能在十步之后变得至关重要。从逻辑角度看，任何不可逆的压缩都带有风险。
这就是为什么我们在 Manus 中将文件系统视为最终上下文：大小不受限制，本质上持久存在，并且可由 Agent 自身直接操作。模型学会按需写入和读取文件——不仅将文件系统用作储存，还用作结构化的外部记忆。
我们的压缩策略始终设计为可恢复的。例如，只要保留 URL，网页的内容就可以从上下文中删除，如果沙盒中仍然有文件路径，则可以省略文件的内容。这使 Manus 能够缩短上下文长度而不会永久丢失信息。
在开发这个功能时，我发现自己在想像状态空间模型 (SSM)要在 Agent 环境中有效运作需要什么条件。与 Transformers 不同，SSMs 缺乏完整的注意力机制，并且在处理长距离的向后依赖关系时表现不佳。但如果它们能够掌握基于文件的记忆——将长期状态外部化而不是保持在上下文中——那么它们的速度和效率可能会开启一种新型Agent。基于 Agent 的 SSMs 可能是神经图灵机的真正继承者。
通过复述操控注意力
如果你使用过 Manus，你可能注意到一个有趣的现象：在处理复杂任务时，它倾向于创建一个 todo.md 文件——并在任务进行过程中逐步更新它，勾选已完成的项目。
这不仅仅是可爱的行为——这是一种操控注意力的刻意机制。
Manus 中的典型任务平均需要大约 50 次工具调用。这是一个很长的循环——由于 Manus 依赖 LLM 进行决策，它很容易偏离主题或忘记早期目标，尤其是在长上下文或复杂任务中。
通过不断重写待办事项列表，Manus 将其目标重述到上下文的末尾。这将全局计划推入模型的近期注意力范围，避免了「迷失在中间」的问题，并减少了目标错位。实际上，它正在使用自然语言来使自己的焦点偏向任务目标——而无需特殊的架构更改。
保留错误的内容
Agent 会犯错。这不是一个错误—这是现实。语言模型会产生幻觉，环境会返回错误，外部工具会出现异常，而意外的边缘情况随时都会出现。在多步骤任务中，失败不是例外；它是循环的一部分。
然而，一个常见的冲动是隐藏这些错误：清理追踪记录，重试动作，或重置模型的状态，并将其留给神奇的「温度」。这感觉更安全，更受控制。但这是有代价的：抹去失败会移除证据。而没有证据，模型就无法适应。
在我们的经验中，改善 Agent 行为最有效的方法之一出奇地简单：将错误尝试保留在上下文中。当模型看到失败的行动——以及由此产生的观察结果或堆栈跟踪——它会隐式地更新其内部信念。这会使其先验远离类似的行动，减少重复相同错误的可能性。
事实上，我们相信错误恢复是真正 Agent 行为的最清晰指标之一。然而，在大多数学术工作和公开基准测试中，这一点仍然代表性不足，这些测试通常关注理想条件下的任务成功。
不要被少样本提示所困
少样本提示是提高 LLM 输出的常见技术。但在 Agent 系统中，它可能以微妙的方式适得其反。
语言模型是优秀的模仿者；它们模仿上下文中的行为模式。如果你的上下文充满了类似的过去行动-观察对，模型将倾向于遵循该模式，即使它不再是最优的。
这在涉及重复决策或行动的任务中可能很危险。例如，当使用 Manus 帮助审查 20 份简历时，Agent 常常会陷入一种节奏——仅仅因为这是它在上下文中看到的内容而重复类似的行动。这导致偏移、过度泛化，或有时出现幻觉。
解决方法是增加多样性。Manus 在行动和观察中引入少量的结构化变化——不同的序列化模板、替代措辞、顺序或格式的微小噪声。这种受控的随机性有助于打破模式并调整模型的注意力。
换句话说，不要让自己陷入少量样本的窠臼。你的上下文越统一，你的 Agent 就越脆弱。
结论
上下文工程仍然是一门新兴科学——但对于 Agent 系统来说，它已经是必不可少的。模型可能变得更强大、更快速、更便宜，但再多的原始能力也无法取代对记忆、环境和反馈的需求。你如何塑造上下文最终定义了你的 Agent 的行为方式：它运行的速度、恢复的效果以及扩展的程度。
在 Manus，我们通过反复重写、死胡同和跨数百万用户的真实世界测试学到了这些教训。我们在这里分享的内容并非普遍真理——但这些是对我们有效的模式。如果它们能帮助你避免哪怕一次痛苦的迭代，那么这篇文章就达到了它的目的。
Agent 化的未来将取决于一次次对上下文的精雕细琢。好好设计它们吧。
本文来自微信公众号“APPSO”，作者：发现明日产品的，36氪经授权发布。
