Manus —— 上下文工程为王的通用Agent-开发者社区

引子：一个“不做模型”的Agent，为什么能超过GPT-4+插件

Manus在GAIA基准测试上的成绩，是理解这个产品的最佳入口。Level 1（单步任务）完成率86.5%，Level 2（多步推理）70.1%，Level 3（复杂长程任务）同样领先，比次优的通用Agent高出20到28个百分点。作为对比，GPT-4开启插件后的GAIA得分显著更低。

但Manus没有训练自己的模型。它整合了Claude 3.5、DeepSeek等多种大模型的能力，通过智能路由机制根据任务类型选择最优模型处理具体环节。它做的事情，用联合创始人季逸超的话说，是押注“上下文工程”而非端到端模型训练。

这个选择背后的逻辑很清晰。季逸超在上一篇创业中从零训练模型做开放信息抽取和语义搜索，GPT-3和Flan-T5出现后，“自研模型一夜之间变得无足轻重”。这个教训让Manus团队做出了一个明确的判断：“如果模型技术的进步是上涨的潮汐，我们希望Manus是水面上的船，而不是被固定在海床上的柱子”。

但“上下文工程”的实践远非一帆风顺。Manus团队四次完整重构了Agent框架，把这种“手动进行架构搜索、调试提示和基于经验猜测的过程”戏称为“Stochastic Graduate Descent”（随机研究生下降）。本文沿着这条“SGD”路径，拆解Manus在上下文工程上到达的“局部最优解”。

一、KV缓存命中率：生产级Agent最重要的单一指标

Manus团队给出了一个非常明确的判断：“如果非要我只选一个指标，我认为KV缓存命中率是生产阶段AI Agent最重要的单一指标。它直接影响延迟和成本”。

要理解这个判断，需要先看清Agent的Token消耗结构。Manus的工作循环是：模型根据当前上下文从预定义动作空间选择一个动作，在虚拟机沙箱中执行产生观察结果，动作和观察结果被追加到上下文，形成下一轮输入。上下文随每一步增长，而输出——通常是结构化的函数调用——保持相对简短。Manus中平均输入输出Token比约为100:1，远高于Chatbot接近1:1的比例。

这个100:1的比例意味着绝大部分计算成本花在“读上下文”上。具有相同前缀的上下文可以利用KV缓存，大幅降低首Token生成时间和推理成本。节省幅度有多大？以Claude Sonnet为例，缓存输入的Token成本是0.30美元/百万Token，未缓存则高达3美元/百万Token——相差10倍。

Manus从工程实践中总结了提升KV缓存命中率的三项核心操作：

第一，保持提示前缀绝对稳定。由于LLM的自回归特性，即使一个Token的差异也会使该Token之后的所有缓存失效。一个常见的错误是在系统提示中写入精确到秒的时间戳——每次请求时间戳都不同，前缀的第一段就无法命中缓存。

第二，上下文只追加不修改。避免修改先前的操作或观察。如果对上下文中的已有内容进行删改，缓存的前缀连续性就被打断。Manus的设计中，上下文修改只允许追加操作，JSON序列化的键序也必须保持确定性。

第三，显式标记缓存断点。在不支持自动增量前缀缓存的框架中，手动插入缓存断点，并至少覆盖系统提示结尾部分。若采用vLLM等自托管框架，须启用前缀缓存并借助会话ID保障分布式节点间请求路由一致性。

Java视角：Agent的KV缓存优化和Java中连接池+缓存预热的思路完全一致。连接池的核心价值是避免每次请求都重新建立TCP连接。KV缓存也是同理：把上下文前缀的注意力计算结果缓存起来，避免每次迭代都从头计算。Manus对“稳定前缀”的执着，相当于Java中做缓存预热时强调“热路径上的数据不要频繁变动”。而“只追加不修改”的策略，和Java中事件溯源（Event Sourcing）的设计原则一致——状态通过追加事件来演进，而不是原地修改已有记录。

二、压缩与隔离：上下文装不下时的两种策略

即使KV缓存优化到位，上下文仍会随任务推进不断膨胀。这时候需要两个补充策略：压缩和隔离。

文件系统即上下文：可恢复压缩的核心

Manus最独特的工程决策是将文件系统视为扩展上下文的核心基础设施。

面对观测数据庞杂（如网页、PDF）、模型长上下文性能衰减及长输入高成本三大痛点，截断或压缩策略存在不可逆信息丢失风险。Manus采用“可恢复压缩”：保留URL即可丢弃网页内容，维持沙箱内路径即可省略文档全文。文件系统由此承担起持久化、无限容量、结构化记忆的功能，模型直接读写文件以完成状态外化。

这个设计的精妙之处在于：它不丢失信息，只是把信息从“热路径”移到了“冷存储”。当Agent后续需要某个被“压缩”掉的内容时，它可以通过文件路径重新读取，而不是依赖LLM的摘要能力来“回忆”它。这比任何基于LLM的摘要压缩都更可靠——摘要是有损的，文件读取是无损的。

Java视角：文件系统即上下文≈把Redis缓存持久化到磁盘。你在Java中做缓存设计时，热数据放Redis（内存，快但有限），冷数据放数据库（磁盘，慢但无限）。Agent的上下文窗口≈Redis内存，文件系统≈数据库。Manus的“可恢复压缩”相当于在缓存淘汰时，不是丢弃数据，而是把数据从Redis持久化到数据库，并在Redis中保留一个指针（文件路径）。

工具管理的“掩码而非移除”原则

工具数量的增长会引发动作空间膨胀。Manus摒弃了动态增删工具的方案，转而采用“掩码而非移除”（Mask, Don’t Remove）的原则。

实验表明，工具定义通常位于上下文前部，任何增删操作均导致全部后续动作与观测的KV缓存失效。同时，历史动作若引用已移除的工具，将诱发模型混淆与幻觉动作。为此，Manus构建了一个上下文感知的状态机，通过实时掩码token logits来约束解码过程，而非变更工具集合本身。

具体实现上，所有浏览器工具统一以browser_开头、命令行工具以shell_开头。状态机通过实时掩码token logits，在解码阶段精准限定可选动作子集——需要浏览器工具时只允许browser_前缀的token被采样，其余工具的定义仍然在上下文中，只是被“遮蔽”为不可用状态。

Java视角：掩码而非移除≈Java中的接口鉴权而非动态类加载。你在微服务中做权限控制时，不是“把没有权限的方法从Service中删除”，而是通过AOP在方法调用前检查权限，无权限则抛出异常。方法的定义（字节码）仍然存在，只是在运行时被“遮蔽”了。Manus的token masking做的是同一件事——工具的定义在上下文中保持不变（缓存前缀稳定），但在解码阶段被“遮蔽”。

三、注意力操控：用“复述”对抗“迷失在中间”

Manus的典型任务涉及约50次工具调用，上下文长度可能达到数万Token。在这种规模下，模型容易出现“迷失在中间”（lost-in-the-middle）现象——位于上下文中间的信息被注意力机制“忽略”。

Manus的解法是“复述”（Recitation）机制：系统主动创建并持续更新一个todo.md文件，将全局计划反复推至上下文末尾，使模型的近期注意力始终锚定在任务目标上，无需修改模型或微调。

这个设计的工程含义很直接：注意力机制对上下文末尾的内容有天然的偏好（近因效应）。与其让Agent“记住”50步之前设定的目标，不如每几步就把目标重新写一遍，放到上下文的最末尾——模型在生成下一个动作时，最先“看到”的就是最新的任务状态。

Java视角：复述机制≈心跳检测中的状态上报。在分布式系统中，Worker节点定期向Coordinator发送心跳，报告当前状态。Coordinator不需要维护一个全局状态表（容易过期），而是每次都从最近的心跳中获取最新状态。Manus的todo.md就是Agent的“心跳文件”——每执行几步就更新一次，确保任务目标始终在“最近的心跳”中。这和你在Spring Batch中让每个Step更新JobExecution的状态、确保后续Step能看到最新进度的做法一致。

四、“保留错误痕迹”：让Agent从失败中学习

一个违反直觉但极其重要的设计原则是：不要清除错误痕迹。

Manus团队指出，“清除错误移除证据，模型无法自适应。让失败的动作及其产生的观察结果或堆栈跟踪留在上下文中，模型看到失败会隐式更新内部信念”。Manus认为错误恢复能力是“真正智能体式行为的清晰指标”，但多数学术研究和基准测试只关注理想条件下的任务成功率。

这个设计的工程价值在于：当Agent在第10步遇到一个错误（比如某个API返回403），如果这个错误被清除，Agent在第30步可能再次尝试同一个API并再次失败。如果错误痕迹保留在上下文中，模型在后续推理中会“看到”这个失败，并隐式地调整策略——它可能换一条路径，或者先解决权限问题。

Java视角：保留错误痕迹≈保留异常堆栈的完整调用链。你在Java中调试一个分布式调用问题时，不会只看“最终错误码”，而是看完整的异常堆栈——每一层的异常信息都保留了从入口到故障点的完整路径。Manus保留错误痕迹的做法，和你在日志中记录完整的异常链而非只记录错误消息的思路一致。区别在于，Java的异常堆栈是给人看的，Manus的错误痕迹是给模型看的——模型从堆栈中学习“什么策略行不通”。

五、Wide Research：当Agent规模扩展到100倍

Manus的Wide Research功能将上下文工程的原则扩展到了多Agent协作场景。

Wide Research是一个系统级的并行处理机制，也是Agent间协作的协议。不同于基于预定义角色的传统多Agent系统（如“管理者”、“编码者”、“设计者”），Wide Research中的每个子Agent都是一个完全通用的Manus实例——拥有完整的上下文窗口、完整的工具集、完整的执行环境。每个子Agent收到自己专用的上下文，并独立处理一个项目。这个架构解决了“上下文窗口限制”的问题——不是让一个Agent处理100个项目，而是让100个Agent各自处理一个项目。

Wide Research依托Manus的虚拟化云计算底座运行，每次对话背后都运行着一个专属虚拟机。Wide Research不需要用户提供Token或登录凭证，系统自动匹配各平台公开API入口或模拟浏览器沙箱环境。

Java视角：Wide Research的架构≈ForkJoinPool的work-stealing + 主线程协调。主线程（Manus核心）将大任务分解为100个独立子任务，Worker线程（子Manus实例）在各自的虚拟机中并行执行。每个子Manus拥有独立的上下文窗口≈每个Worker线程拥有独立的栈空间。区别在于，ForkJoinPool的子任务通常是计算密集型的短任务，而Wide Research的子任务是“研究一个公司”这样的长程任务。但架构约束相同：局部上下文隔离是并行化的前提。

六、Java开发者的Manus上下文工程实践

Manus的上下文工程原则可以直接映射到Java生态。Spring AI Alibaba已经发布了OpenManus的Java实现，包含完整的多智能体任务规划、思考与执行流程。

架构映射

Spring AI Alibaba OpenManus的架构是：Planning Agent负责任务分解与规划，调用Planning Tool生成一个串行的Manus Agent子工作流。多个Manus Agent组成一个链式、可顺序依次执行的子工作流，每个Agent都是一个ReAct架构设计。Summary Agent用来做最后的任务总结。

这个架构和Python版OpenManus的设计理念相似，但有一个值得关注的差异：Java版的Spring AI Alibaba Graph提供了更结构化的编排能力。官方文档指出，“当前OpenManus实现中80%代码都在解决流程编排问题”，而Spring AI Alibaba Graph的目标是让这部分工作“交给高度抽象的agent框架实现，以简化开发复杂度”。

KV缓存优化的Java实现

在Spring AI中，KV缓存优化主要依赖两个机制。ChatMemory的append-only设计：Spring AI的ChatMemory接口只提供add操作，不提供remove或update操作——这天然保证了上下文的“只追加不修改”原则，和Manus的KV缓存优化要求一致。

序列化确定性：在将工具调用结果写入上下文时，确保JSON序列化的键序一致。Spring AI内部使用Jackson序列化，你可以通过配置ObjectMapper的MapperFeature.SORT_PROPERTIES_ALPHABETICALLY来保证键序确定性。

文件系统作为上下文的Java实现

在Spring Boot应用中，可以将文件系统上下文与AutoMemoryTools（Spring AI Agent Utils）结合。AutoMemoryTools提供了六个文件操作工具（View、Create、StrReplace、Insert、Delete、Rename），让Agent自己决定哪些信息值得写入文件。这和Manus的“文件系统即上下文”设计一致——Agent通过读写文件来外化状态，而不是把所有信息都压在上下文窗口里。

两个值得注意的局限

Spring AI Alibaba OpenManus的官方文档坦诚地指出了当前的不足。规划及工作流程中无法人为介入进行review、动态修改、回退等动作——这意味着Agent的规划一旦生成，用户只能等待执行完成，不能中途调整。这和Devin的Interactive Planning（执行前展示计划、用户确认后才消耗ACU）形成了对比。工具覆盖度与执行效果一般——浏览器使用、脚本执行等工具的实际效果和Python版Manus存在差距。

对于Java开发者，这意味着当前的OpenManus实现适合验证上下文工程原则和架构模式，但在生产环境中还需要补充人工审核环节和工具增强。

小结：Manus上下文工程的三个关键判断

第一，KV缓存命中率是Agent成本结构的“第一性原理”，不是可选的优化项。100:1的输入输出Token比意味着Agent的成本几乎完全由“读上下文”决定。Manus对“稳定前缀”“只追加不修改”“掩码而非移除”的执着，本质上都是在保护KV缓存的连续性。Java开发者在做缓存设计时积累的“热路径不变动”“事件溯源”“连接池复用”经验，可以直接迁移到Agent的上下文管理——区别在于，你缓存的不再是数据库查询结果，而是Transformer的注意力Key-Value矩阵。

第二，文件系统作为上下文的核心价值不是“省Token”，而是“信息无损”。基于LLM的摘要压缩是有损的——一个架构决策背后的推理过程，一旦被删除，Agent可能就丧失了理解“为什么不能这样做”的依据。文件系统的“可恢复压缩”保留了重新读取的可能性。这和你在Java中把冷数据从Redis持久化到数据库的思路一致——不是丢弃，是分层存储。

第三，Manus的“Stochastic Graduate Descent”方法论本身就是最有价值的工程输出。四次框架重构、手工架构搜索、经验猜测——这个过程不优雅，但它是真实的。它告诉Java开发者一个重要的信号：上下文工程没有“标准答案”，需要实验、测量、迭代。你在Java中做性能调优时的方法论——先测量、再优化、每次只改一个变量、观察指标变化——在Agent上下文工程中同样适用。Manus的“SGD”就是Agent时代的“性能调优实验”。

下一篇进入3.2.3 OpenClaw（小龙虾），拆解它的“文件优先、本地优先”设计哲学、四条独立桌面控制路径的架构设计，以及Skill系统如何让Agent从“会做”到“知道怎么做”。

🍃 系列专栏导航