# Manus: Context Engineering for AI Agents — Lessons from Building Manus

> 原文链接：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
> 作者/来源：Manus
> 阅读日期：2026-04-02

## 一句话总结
Manus 团队分享了从数百万用户的真实使用中提炼的 context engineering 六大核心策略，其中 **KV-cache 命中率是生产环境 agent 最关键的性能指标**。

## 核心论点
Manus 选择了基于 frontier model 的 in-context learning 而非 fine-tuning 自定义模型，这一决策优先保证了快速迭代能力——"在数小时而非数周内交付改进"，同时使产品独立于底层模型的进步。

文章的核心贡献是从真实生产环境（数百万用户）中提炼的六条 context engineering 原则。**第一也是最重要的是 KV-cache 命中率优化**。Agent 系统通常有约 100:1 的输入/输出 token 比率，创造了巨大的缓存机会。Claude Sonnet 的缓存 token 成本为 $0.30/M，未缓存则为 $3/M——10倍差异。具体策略包括维护稳定的 prompt 前缀、使用 append-only context 设计和确定性序列化。

**第二是 masking 替代动态工具移除**。动态移除工具会使 KV-cache 失效，Manus 改用"context-aware state machine"在解码阶段通过 logits masking 约束行动选择。**第三是文件系统作为扩展 context**，将文件系统视为"无限、持久"的外化记忆，压缩是可逆的（存 URL 而非页面内容，存文件路径而非文档内容）。

**第四是通过"复述"操控注意力**。复杂任务时创建 todo.md 文件并持续更新，将目标"复述"到 context 末尾，对抗"lost-in-the-middle"效应。**第五是保留失败证据**而非隐藏错误，让模型"隐式更新内部信念"。**第六是控制多样性而非过度 few-shot**，引入少量结构化变化来防止模型陷入重复模式。

## 关键概念
- **KV-Cache Hit Rate**：生产环境 agent 的首要性能指标。通过稳定前缀、append-only 设计和确定性序列化来最大化命中率，可降低10倍成本。
- **Logits Masking**：替代动态工具移除的技术方案。通过在解码阶段约束 token 概率来限制可用行动，而不改变 context 内容（从而保持 KV-cache）。
- **Context-Aware State Machine**：配合 logits masking 的状态机设计，根据当前 context 状态决定哪些行动可用。
- **File System as Extended Context**：将文件系统视为 context window 的"无限持久"扩展。压缩是可逆的——存储指针而非内容。
- **Attention Manipulation via Recitation（复述操控注意力）**：通过让 agent 持续更新 todo.md 文件，将关键目标"放置"在 context 末尾，利用 recency bias 对抗 lost-in-the-middle 问题。
- **Failure Evidence Preservation**：保留错误轨迹作为 context 的一部分，帮助模型避免重复相同错误。
- **Stochastic Graduate Descent**：作者对开发过程的戏称——迭代式的经验测试而非理论优化。框架经历了四次重建。

## 实践建议
1. **将 KV-cache 命中率作为首要优化目标**：设计 append-only 的 context 结构，使用确定性序列化，维护稳定的 prompt 前缀。
2. **用 logits masking 替代动态工具集变更**：保护 KV-cache 不失效。精心设计行动名称前缀（如 `browser_`、`shell_`）以支持高效的约束执行。
3. **利用文件系统作为外化记忆**：不要激进地截断 context，而是将信息外化到文件中，在 context 中保留可逆的指针。
4. **让 agent 维护 todo.md 来保持目标对齐**：在平均约50次工具调用的任务中，这是维持长期目标一致性的关键机制。
5. **保留错误轨迹而非清除它们**：失败证据帮助模型建立"什么不管用"的隐式知识。
6. **在 few-shot 示例中引入结构化变化**：避免过度相似的示例导致模型陷入重复行为模式。

## 独到观点
这篇文章最独特的贡献在于其**极度实用主义和工程导向**。KV-cache 命中率优化是所有文章中最底层、最"硬核"的性能优化建议——它不是关于"如何设计更好的 prompt"，而是关于"如何让推理引擎更高效"。Logits masking 的方案也展示了超越"prompt 层"的 context 管理思路。此外，"失败证据保留"和"复述操控注意力"这两个策略来自对模型行为的深刻理解，而非表面的工程最佳实践。"Stochastic Graduate Descent"的自嘲也诚实地承认了这个领域仍处于经验驱动的阶段。

## 与其他文章的关联
- Context rot 的应对策略与 [Anthropic: Context Engineering](09-anthropic-context-engineering.md) 中的 compaction 和 [LangChain](04-langchain-anatomy-of-harness.md) 中的 context rot 讨论相关，但 Manus 提供了更底层的技术方案（KV-cache、logits masking）。
- 文件系统作为扩展 context 与 [LangChain](04-langchain-anatomy-of-harness.md) 中 "filesystems for durable storage" 和 [Anthropic: Context Engineering](09-anthropic-context-engineering.md) 中 "structured note-taking" 理念一致。
- todo.md 的"复述"机制与 [Anthropic: Effective Harnesses](02-anthropic-effective-harnesses.md) 中的 `claude-progress.txt` 功能类似。
- 失败证据保留与 [OpenAI: Harness Engineering](01-openai-harness-engineering.md) 中 feedback loops 的理念相通。
- 控制多样性的建议与 [HumanLayer: Advanced Context](12-humanlayer-advanced-context.md) 中的 context 优化策略相关。