本文由 Manus 的开发者 Yichao 'Peak' Ji 撰写，分享了在构建 AI Agent（智能体）过程中关于“上下文工程”（Context Engineering）的核心经验。作者指出，相比于耗时且难以迭代的端到端模型微调，Manus 选择基于前沿模型的上下文学习能力进行构建，通过优化上下文结构来实现快速迭代。

文章总结了六大核心原则：

1. 围绕 KV-Cache 设计：KV-Cache 命中率是生产环境的关键指标，直接影响延迟和成本。开发者应保持 Prompt 前缀稳定、采用“仅追加”模式并明确缓存断点。
2. 掩码而非删除：面对庞大的工具库，不应动态删除工具（这会破坏缓存并导致模型困惑），而应通过 Logit 掩码（Masking）在解码阶段限制动作空间。
3. 将文件系统视为上下文：针对长上下文导致的性能下降和高成本，Manus 将文件系统作为外部持久化存储，让模型按需读写，实现可恢复的上下文压缩。
4. 通过“背诵”操纵注意力：利用如 todo.md 的任务列表，让模型在长任务中不断重申目标，防止注意力漂移。
5. 保留错误记录：不要清理失败的尝试，错误记录是模型学习和自我修正的关键证据。
6. 避免过度 Few-shot：过多的同质化示例会导致模型陷入行为模式的死循环，应引入结构化变体以增强鲁棒性。

作者强调，上下文工程是定义 Agent 行为、效率和扩展能力的关键，是构建智能体未来的基石。

---

围绕 KV-Cache 设计以优化性能与成本

在生产级 AI Agent 的开发中，KV-Cache（键值缓存）的命中率是衡量系统优劣的核心指标。Agent 的工作模式通常是“思考-行动-观察”的循环，随着步骤增加，上下文会迅速膨胀。在 Manus 中，输入与输出的 Token 比例高达 100:1，这意味着大部分计算资源消耗在预填充（Prefilling）阶段。如果能有效利用 KV-Cache，不仅能显著降低首字延迟（TTFT），还能大幅削减成本（例如 Claude Sonnet 的缓存 Token 价格仅为非缓存的十分之一）。

为了最大化缓存效率，开发者必须遵循以下实践：首先，保持 Prompt 前缀绝对稳定。LLM 是自回归的，系统提示词中哪怕多了一个随时间变化的秒数，都会导致后续所有缓存失效。其次，上下文应采用“仅追加”（Append-only）模式。避免修改历史记录，并确保 JSON 序列化等操作具有确定性的顺序，防止因键值对排序变动破坏缓存。最后，明确标记缓存断点。在不支持自动增量缓存的框架中，手动在系统提示词结束处设置断点是保证基础性能的底线。此外，在自托管模型（如 vLLM）时，应利用 Session ID 将请求路由到同一节点，以复用物理缓存。

动作空间的管理：掩码（Mask）优于删除

随着 Agent 功能的增强，工具（Tools）的数量会呈爆炸式增长。如果将数百个工具全部塞进上下文，模型极易产生误判或效率低下。一种直觉的做法是根据需求动态加载工具（类似 RAG），但 Manus 的实践证明这并不可取。动态增删工具会改变上下文结构，导致 KV-Cache 全面失效；同时，如果历史记录中引用的工具在当前上下文中消失，模型会感到困惑，甚至产生幻觉或违反 Schema 约束。

Manus 采用的解决方案是基于状态机的 Logit 掩码技术。我们不从上下文中移除工具定义，而是在模型解码（Decoding）阶段，通过限制 Token 的生成概率来“屏蔽”当前不可用的动作。例如，当用户刚输入信息时，我们强制模型必须先回复而非调用工具。通过为工具设置统一的前缀（如 browser_ 或 shell_），我们可以轻松地在不改变上下文的情况下，根据当前状态约束模型的选择范围。这种方法既保留了缓存的稳定性，又确保了模型在复杂任务中的决策精准度。

文件系统：Agent 的无限外部存储

尽管现代 LLM 支持 128K 甚至更长的上下文窗口，但在实际应用中，长上下文会带来三大问题：海量观察结果（如网页源码）易撑爆窗口、模型在长文本下的推理能力下降（Lost in the Middle）、以及高昂的传输和计算成本。简单的截断或压缩往往会导致关键信息的永久丢失，因为 Agent 很难预判十步之后的行动是否需要当前的某个细节。

Manus 的策略是将文件系统视为终极上下文。我们将文件系统作为 Agent 的外部化、结构化记忆，让模型学会按需读写文件。所有的上下文压缩策略都必须是“可逆”的：例如，可以从上下文中移除网页内容，只要保留 URL；或者移除文档全文，只要保留沙盒中的文件路径。这样，当模型需要细节时，它可以重新读取文件。这种方式不仅解决了容量问题，还为未来基于状态空间模型（SSM）的 Agent 铺平了道路——SSM 虽然不擅长长程注意力，但如果能熟练操作文件存储，其效率优势将得到释放。

操纵注意力与错误处理的艺术

在执行长达数十步的复杂任务时，Agent 容易“跑偏”或忘记初衷。Manus 发现，让模型维护并不断更新一个 todo.md 文件是一种极佳的注意力操纵机制。通过在上下文末尾不断“背诵”当前的全局计划和进度，模型能始终将目标置于其最近的注意力跨度内，有效解决了长上下文带来的目标对齐问题。

同时，对待错误的态度决定了 Agent 的进化上限。开发者往往倾向于清理失败的尝试以保持上下文“干净”，但 Manus 坚持保留错误记录。失败的动作、报错的堆栈信息是模型更新内部信念的重要依据。看到错误记录后，模型会自动降低重复该错误动作的概率。真正的智能体行为不仅体现在成功时，更体现在如何从失败中自我修复。此外，为了防止模型在处理重复性任务（如批量审核简历）时陷入 Few-shot 带来的行为惯性，Manus 会主动引入结构化的随机性（如改变格式、微调措辞），防止模型因过度模仿历史记录而产生幻觉或僵化。

---

问答

问：为什么 KV-Cache 对 AI Agent 如此重要？ 答：Agent 的输入 Token 远多于输出，且上下文随步骤累积。KV-Cache 能避免重复计算相同的前缀，将推理成本降低高达 90%，并显著减少响应延迟。

问：动态增删工具（Tools）会有什么副作用？ 答：这会破坏 KV-Cache 的连续性，导致计算开销激增；同时，如果模型在历史记录中看到已删除的工具，容易产生逻辑混乱或生成无效的指令。

问：Manus 如何处理超出上下文限制的长信息？ 答：Manus 将文件系统作为外部记忆。它会从上下文中移除冗长数据（如网页源码），但保留其路径或链接，让模型在需要时通过读取工具重新获取信息，实现无损压缩。

问：为什么要在上下文中保留失败的尝试？ 答：错误记录提供了关键的负反馈。模型通过观察失败的后果，可以调整后续决策，避免陷入死循环，这是实现真正“自我修复”能力的基础。

问：如何防止 Agent 在执行重复任务时变得“机械化”？ 答：通过在上下文序列化时引入微小的随机性（如改变模板、增加噪声），打破模型对历史模式的过度模仿（Few-shot 陷阱），从而提高其在复杂场景下的灵活性。