本文作者：meng shao（@shao__meng）。版权归作者所有，未经授权禁止转载。
曾经的 Manus 又回来了
传闻 Manus 从 Meta 拆分后，以 40 亿美金估值得到了 5 亿美金融资，相比 Meta 收购价格又翻了一倍（这些信息目前都还是外部传闻，还没有正式官宣！）
从 @ManusAI 最早把 Agent 的概念和实际场景传达出来，一夜爆火，到后来被 Meta 收购让很多人看到 AI 创业的前景，再到后来因为各种原因拉扯大半年最终从 Meta 拆分重新独立运营。真心佩服 Manus 团队的意志力，也对这个团队 @Red_Xiao_ @hidecloud @peakji 的技术能力依然很有信心！
周末重新阅读 Manus 团队 @peakji 一年多前发布的这篇工程博客「Context Engineering for AI Agents」，仍然还是对 Context Engineering 理解非常透彻和有技术前瞻性的：
文章的中心论点是什么？
当时还没有 Harness 的概念，Context 被视为 Agent 的运行时系统。一个能长期执行任务的 Agent，它的表现既取决于模型能力，也取决于上下文的布局、记忆的可恢复性、工具选择的约束、错误的保留方式和目标的重述机制。
一个 Agent 会在数十轮循环中不断读取上下文、选择工具、接收观察结果，再决定下一步。每一轮产生的动作和观察都会反过来塑造下一轮的输入。
因此，上下文工程涵盖对整个执行轨迹的编排。它至少包括五项工作：确定长期稳定的内容，管理追加的执行记录，将大信息移出模型窗口并保留取回路径，限定当前状态可选的工具，以及在长任务中重新强调最初目标。
Peak 把这条路线与模型训练路线对照。训练或微调专用模型的迭代周期长，并且容易被更强的基础模型替代；上下文工程能以小时为单位调整 Agent 行为，并使上层产品随底层模型进步而受益。文中“让 Manus 成为随着潮水上升的船”的比喻，强调了这种对模型进步的适应力与快速迭代能力。
文章把不断重构框架、反复试验提示与架构的过程戏称为 “Stochastic Graduate Descent”。它不对应正式算法。这个说法如实描述了当前 Agent 系统的工程现实：许多有效设计来自高频实验、线上失败与局部经验，统一理论仍在发展中。
六条原则分别解决什么问题
| 原文原则 | 它解决的直接问题 | 更深一层的工程含义 |
| --- | --- | --- |
| 围绕 KV-cache 设计 | 多轮任务的延迟与输入成本过高 | 把上下文的**字节级稳定性**当作产品性能的一部分 |
| Mask：保留工具模式，再约束选择 | 工具过多造成错选；动态工具集破坏缓存与一致性 | 保持工具协议稳定，把“是否能用”移至解码控制层 |
| 用文件系统充当上下文 | 原始观察过大，长上下文成本高且效果变差 | 让模型窗口成为工作记忆，让文件成为可操作的外部记忆 |
| 用复述操纵注意力 | 长任务中跑题、遗忘目标 | 在上下文末端持续重放当前计划，管理模型的注意力位置 |
| 保留错误轨迹 | 失败后重复同样的错误 | 将失败观察保留为下一步决策的证据 |
| 不要被自己的 few-shot 带偏 | 重复动作形成机械模仿与漂移 | 控制上下文样本的同质性，避免“执行历史”变成错误示范 |理解这些原则时，应把它们放在同一个系统中考察。
1. KV-cache：为什么“稳定前缀”会成为核心架构约束
Transformer 在生成新 token 前，需要处理输入序列，这一阶段通常称为 prefill；随后才逐 token 生成输出，即 decoding。KV-cache 会复用相同前缀已经计算出的注意力键和值。对于 Agent，动作往往是很短的结构化工具调用，但输入包含系统提示、工具定义和越来越长的历史。作者给出的 Manus 平均输入／输出 token 比约为 100:1，所以节约输入的预填充成本比优化短输出更关键。
文章最有用的提醒是：缓存命中通常要求前缀在 token 层面完全一致；语义相同本身不足以保证复用。系统提示开头加入精确到秒的时间戳、JSON 字段输出顺序漂移、回头修改历史观察记录，都可能从变化点开始失去缓存复用。由此得到三个看似细小、实际上会改变架构的要求。
第一，稳定内容应放在最前面，包括系统规则、工具模式和长期不变的能力描述。第二，运行轨迹应尽量只追加、不回写。第三，序列化必须是确定性的；实践中不应依赖语言或库的偶然遍历顺序，而应明确采用规范化 JSON、固定字段顺序和稳定的格式化规则。
“How you shape the context ultimately defines how your agent behaves: how fast it runs, how well it recovers, and how far it scales.” — 原文结论
这里的深层变化在于：传统软件工程通常把缓存看成基础设施优化；本文将缓存友好的上下文格式视为 Agent 协议的一部分。若每一步都改变工具定义或重写历史，即使模型本身更快，上层 Agent 仍会在大量重复 prefill 中损失成本和响应速度。
原文用 Claude Sonnet 的缓存输入与未缓存输入价格作 10 倍对比，意在说明数量级的重要性。 这应被视为文章写作时的示例，不能作为今天仍有效的价格表；供应商价格、缓存期限和计费策略会变化。真正可迁移的结论是：应监控缓存命中率、首 token 时间（TTFT）、每成功任务的输入 token 成本，并结合总 token 与模型单价共同判断。
2. Mask：将“工具定义”与“可选工具”分离
工具越多，模型的可选动作空间越大，错选工具、生成错误参数或绕远路的概率也会升高。直觉方案是按需把工具加入或移出上下文，类似工具版 RAG。作者的经验却是：除非必要，不要在一次任务的中途动态增删工具。
理由有两层。其一，工具定义通常处于上下文靠前位置，任何变化都会破坏后续所有轮次的 KV-cache。其二，历史里已出现的调用若引用了当前不再定义的工具，模型会看到一个内部不一致的世界；在没有严格约束解码时，这容易导致模式违例或虚构工具调用。
Manus 采用的替代方案是：保持完整工具模式稳定存在，但依据当前状态机对解码 logits 做掩码。logits 是模型生成下一个 token 前对各 token 的原始分数。对某些 token 置为不可选，相当于在不改写工具说明的前提下，禁止模型在此状态调用特定工具。文章提到 response prefill 还可把生成位置推进到“必须调用工具”或“只能在一组工具中选”的位置，再配合掩码收紧动作空间。
这也是为什么命名约定会成为可靠性设计。若浏览器工具都以 browser_ 开头，命令行工具都以 shell_ 开头，状态机可以在函数名开头直接约束一组动作，而不必修改整个工具列表。换言之，命名空间不仅服务人类可读性，也服务 token 级控制。
需要注意边界。掩码和预填充依赖模型供应商或推理框架的能力；状态机若定义错误，也可能把完成任务所需的合法工具锁死。设计目标是保持工具协议稳定，让授权面随状态收紧，并保留可观测的逃逸与诊断路径。
3. 文件系统作为上下文：可恢复的外部记忆
长上下文并不自动解决记忆问题。原文指出三个现实限制：网页、PDF 等观察结果可能迅速耗尽窗口；即使窗口没满，模型在超长输入上的效果也会退化；而且每次传输和预填充长输入仍有成本。
常见做法是截断或摘要，但摘要是不可逆压缩。执行到第十步时，系统未必能在第五步就准确判断哪段网页细节会重新变得关键。因此 Manus 将文件系统用作 Agent 的外部记忆：原始网页可由 URL 再取回，文档内容可从 sandbox 路径重读，长错误日志也可保存在文件中。上下文里保留的是可恢复的指针、路径与必要摘要。
这里必须区分两种“记忆”。模型上下文适合存当前决策所需、需要被注意力机制直接访问的工作记忆。文件系统适合保存容量大、持久、可检索和可操作的事实工件。前者追求短而相关，后者追求可恢复、可审计。文件系统为单次上下文窗口提供了更大的持久层。 其物理容量仍受实际存储限制。
若将这一思路用于系统设计，文件不应只是随手堆放的文本。每个工件至少应有稳定路径、来源或获取时间、简要描述、内容类型和与当前任务的关系。否则 Agent 虽然“有记忆”，却不知道该读哪个文件。文件型记忆也引入了权限、过期、敏感数据留存和清理策略等治理问题；这些是原文没有展开、但生产系统必须补上的部分。
4. Todo 清单：注意力调度器
Manus 在复杂任务中持续写入、更新 todo.md，并将完成项打钩。原文将这一机制用于把总目标重新放到上下文末端。
模型在长上下文中不会对每段信息均等关注。任务初始目标放在很早的位置，又经过约 50 次工具调用后，容易受到“lost in the middle”影响：内容仍在上下文中，但对当前生成的影响不足。每轮末尾更新计划，相当于把目标、未完成事项和下一步优先级再次“朗读”给模型。
因此，待办清单是一种注意力再定位机制。一个好的清单应陈述目标、已验证事实、剩余子任务和下一步；它必须随真实进度更新。若清单含有不真实的已完成项，或反复复制大段过时计划，反而会成为高权重的误导信息。
5. 保留错误：恢复能力依靠可见证据
多步执行必然会遇到模型幻觉、工具失败、环境错误和边缘情况。原文反对在失败后清洗记录、静默重试或重置状态，因为这样做会抹掉模型修正下一步的证据。
当模型看到“刚才调用了什么、得到什么错误、这个错误意味着哪种前提不成立”，它可以改变后验判断，减少重复同一路径。作者将错误恢复视为 Agent 行为的重要标志，并将其与最终任务成功共同纳入评价。
实践上，可采用分层的错误记录：活动上下文保留失败动作、可读的错误类别、关键诊断和替代方向；完整日志保存为可再读文件。该方式保留了文章所说的“失败是证据”，也能控制错误文本对后续推理空间的占用。还要区分可信的环境错误、暂时性错误和模型自身的猜测；未经验证的错误归因不应被当作事实反复强化。
6. 别被自己的 few-shot 绑架：执行历史会变成行为示范
few-shot prompting 通常通过示例让模型模仿正确格式或策略。文章提出一个在 Agent 循环中更微妙的问题：当上下文连续出现高度类似的动作—观察对时，模型可能沿袭最近形成的节奏，即使该节奏已经不适合当前对象。例如批量审阅 20 份简历时，前几份的操作模式可能诱发后面机械重复、过度概括或幻觉。
Manus 的对策是在动作和观察中加入小幅、结构化的变化，例如替换序列化模板、措辞或顺序中的非关键部分。其目的是打破单一行为模式对注意力和预测分布的吸引力；随机性只服务于这一目的。原文的简洁表述是：不要把自己 few-shot 到死胡同里。
这是全文最容易被误读的原则之一。所有序列化都随机化会直接破坏第一条的缓存稳定性，也降低可测试性。合理的协调方式是：将系统提示、工具模式、日志骨架等缓存前缀严格确定化；只在后部、语义不变且不影响工具协议的区域进行有限变体；并通过 A/B 评估验证这种多样性是否真的改善成功率或降低重复错误。
把六条原则连成一个统一模型
文章展示了一个由六项原则构成的分层上下文架构。
| 上下文层 | 应保存的内容 | 更新规则 | 主要目标 |
| --- | --- | --- | --- |
| 稳定前缀 | 系统规则、完整工具模式、长期策略 | 尽量不变 | KV-cache 复用与协议一致性 |
| 追加执行层 | 用户输入、工具调用、观察、错误摘要 | 只追加，格式确定 | 保留因果轨迹与恢复证据 |
| 外部工件层 | 网页、文档、原始数据、完整日志 | 文件／URL 可寻址 | 可恢复的长期记忆 |
| 目标复述层 | 当前计划、完成状态、下一步 | 在每轮末端更新 | 重新聚焦注意力 |
| 动作约束层 | 状态机、允许工具集合、解码掩码 | 随状态改变，不改工具模式 | 降低错选和模式违例 |这一框架解释了文中四组看似矛盾、其实互补的设计。
稳定与多样性并存。 缓存要求前缀稳定，避免 few-shot 偏置却需要局部多样性。答案是分层：前缀确定化，后缀有限扰动。
保留与压缩并存。 错误和原始观察不应被不可逆删除，但也不能全部常驻模型窗口。答案是把信息保留在可恢复介质中，在活动上下文留下足够的证据与指针。
完整工具定义与小动作空间并存。 工具模式保持完整稳定，实际可调用范围由状态机与解码约束决定。答案是把“定义”与“授权”解耦。
持久记忆与当前注意力并存。 文件系统确保信息没有丢，待办清单确保当前目标没有被淹没。答案是区分“可找到”与“会被当前生成关注”。
如果把文章转化成工程评审清单
对于一个已有的 Agent，应优先检查上下文生命周期是否可控。系统提示的长度只是其中一项因素。
1.前缀是否稳定。 检查系统指令、工具 schema、时间字段和 JSON 序列化。为每轮请求的稳定前缀生成哈希，找出意外变化的来源。
2.历史是否可追加与重放。 每次动作、参数、观察和错误是否以确定形式记录；是否能在不修改旧记录的前提下恢复一次任务。
3.大工件是否可恢复。 网页、文档、图片、数据表和完整日志是否保存路径与来源；上下文缩短时是否仍能按需读回。
4.工具授权是否状态化。 工具定义是否随轮次反复改写；是否可用更稳定的 schema 加状态机、强制函数调用或受限解码替代。
5.任务目标是否被持续复述。 长任务末端是否存在真实、短小、随进度更新的计划；计划应明确下一步。
6.失败是否可用于下一步。 失败后是否保留足够证据；除最终成败外，是否还能统计重复错误与成功恢复。
7.重复任务是否进入机械模式。 在批量操作中，是否出现动作序列、结论格式或错误类型的异常同质化；若有，先定位是模型、模板还是任务数据造成，再做局部变体实验。
建议把上述检查映射到一组联动指标：缓存命中率和 TTFT 衡量前缀设计；每个任务的输入成本衡量上下文负担；工具错选率与 schema 违例率衡量动作约束；重复失败率和失败后恢复率衡量错误利用；最终成功率与任务质量则用于防止局部优化损害用户结果。只提高缓存命中而降低任务质量，并不构成成功的上下文工程。
