在构建 Agent 系统、优化 prompt 调度、处理 RAG 链路、日志记录时，我们常常会踩到各种"坑"：cache miss、上下文错乱、模型行为漂移......这些问题让人既熟悉又头痛。明明知道问题出在哪里，却难以总结成一条普适的法则；明明优化了性能，却无法从认知层面解释其原理。这时，Manus 的上下文工程法则就像一盏明灯，系统化地总结了这些经验教训，用优雅的方式为我们指明方向。以下是我对 Manus 六大上下文工程法则的拆解，总结为"智能体上下文系统设计的六个底层约束"，希望能为 Agent 系统开发者提供启发。
法则一：围绕 KV-Cache 进行设计核心理念：
优化智能体性能的关键不在于生成速度，而在于最大化缓存命中率，减少预填充阶段的计算成本。在聊天机器人场景中，输入和输出 token 量通常较为均衡，但在 AI 智能体场景中，输入上下文可能高达几千甚至上万 token，而输出仅几十 token。这种输入输出的严重失衡使得预填充阶段的计算成本成为系统延迟的罪魁祸首。特别是在多 Agent 系统或低延迟交互场景中，重复预填整个上下文会导致性能雪崩。实践要点：
- 保持提示词前缀稳定：任何前缀变动（如在系统提示中加入秒级时间戳）都会导致缓存失效。确保提示词前缀固定，避免不必要的重算。
- 确保上下文 append-only：避免修改历史记录或观察结果，同时保证序列化方式（如 JSON 键顺序）确定，防止悄无声息地破坏缓存。
- 显式标记缓存断点：在推理框架中，手动设置缓存断点（如在系统提示末尾），提升缓存利用率。
启发：将 KV-Cache 命中率视为核心优化指标，哪怕牺牲部分 prompt 灵活性，也能显著提升系统性能。
法则二：掩码，而非移除核心理念：
通过掩码技术约束模型行为，保持工具定义集稳定，避免动态增删工具带来的缓存失效和模型困惑。随着智能体能力的增强，可用工具集不断扩展。许多开发者尝试通过 RAG 技术动态加载工具定义，以实现模块化管理。然而，动态增删工具会导致两大问题：
- 缓存失效：工具定义通常位于上下文前部，任何变化都会导致后续 KV 缓存失效。
- 模型困惑：当历史记录引用了已移除的工具时，模型可能生成错误格式或幻觉出不存在的动作。
实践要点：
- 使用 logits 处理器屏蔽工具：通过在解码阶段动态屏蔽或强制选择某些 token，控制模型仅调用允许的工具，无需修改上下文。
- 统一工具命名规范：为工具设计统一前缀（如 browser_ 或 shell_），便于按类别约束工具选择。
- 预填充回复前缀：在特定状态下，预设回复前缀强制模型直接响应用户，而非调用工具。
启发：与其让模型"理解"限制，不如直接通过掩码消除其错误选择的可能性，简单高效。
法则三：将文件系统作为上下文核心理念：
上下文不是无限堆料，而是构建随取即用的语义型记忆索引。即使模型提供 128K 或更大的上下文窗口，面对网页 HTML、嵌套 JSON 或用户上传的 PDF，上下文依然可能被撑爆。超长上下文不仅增加计算延迟，还会导致注意力混乱和性能下降。实践要点：
- 外置存储：将文件系统作为无限持久化的语义存储空间，记录路径、摘要和索引，智能体在需要时通过"读文件"工具访问。
- 可恢复压缩：即使因上下文限制丢弃详细内容，保留 URL 或文件路径，允许智能体重新访问。
- 语义索引：训练模型"知道信息在哪"，而非将所有信息塞入上下文。
启发：智能体的高级认知结构在于"知道去哪里找答案"，而非记住所有内容，文件系统是实现这一目标的理想工具。
法则四：通过复述操控注意力核心理念：
通过每轮复述目标和状态，偏置模型注意力，防止目标漂移。在 Agent 系统运行中，模型常因注意力失焦而偏离原始目标，陷入"迷失在中间"的困境。Manus 的解法是通过每轮更新目标和当前状态，并将其置于上下文末尾，利用 LLM 注意力机制对近期信息的偏好，保持模型聚焦核心任务。实践要点：
- 复述目标：在上下文末尾定期插入当前目标和计划的简要描述。
- 利用注意力偏置：无需修改模型架构，依靠自然语言复述引导注意力分配。
- 动态更新状态：确保复述内容反映最新任务进展，避免模型"忘记"目标。
启发：复述看似简单，却模拟了人类自我提醒的认知行为，是低成本、高效率的注意力管理方式。
法则五：保留错误的内容核心理念：
失败是推理链上的必要节点，保留错误信息帮助模型隐式学习，降低重复犯错概率。许多 Agent 系统在出错时清空上下文、重新调用，导致模型无法从错误中学习，陷入"工具轮回"。Manus 选择保留所有错误信息（失败调用、错误观察、栈追踪），让模型在后续推理中更新信念模型，自动规避相似错误。实践要点：
- 完整保留错误：将失败调用、错误日志等全部记录在上下文。
- 隐式学习：通过错误信息调整模型行为先验，降低重复错误概率。
- 避免清空上下文：保留历史记录，让模型"吃一堑，长一智"。
启发：错误是智能体成长的基石，保留错误信息比追求"干净"上下文更有价值。
法则六：不要被少样本示例所困核心理念：
few-shot 示例需引入结构化变体，避免模型陷入模式依赖，提升行为多样性和鲁棒性。few-shot prompting 在多轮动态任务中可能导致模型"照猫画虎"，生成过于保守或格式化的输出。Manus 通过刻意设计语义一致但表达多样的示例，打破模型对固定模式的依赖。实践要点：
- 结构化变体：在动作和观察示例中引入多样化表达，保持语义一致。
- 避免模式依赖：防止模型陷入模仿固定格式的"安全区"。
- 提升鲁棒性：通过多样化示例训练模型适应不同场景。
启发：few-shot 不是 few-clone，设计多样化示例让模型成为策略探索者，而非格式模仿者。
Manus 的六大上下文工程法则为智能体系统设计提供了结构化的指导
从 KV-Cache 优化到错误保留，从文件系统索引到注意力操控，这些法则不仅解决了实际工程中的痛点，还从认知层面揭示了智能体行为的底层约束。它们提醒我们：构建高效的 Agent 系统不仅是技术问题，更需要对模型行为、上下文管理和认知机制的深刻理解。如果你也曾在 Agent 系统中绕过弯、爬过坡，不妨对照这些法则，重新审视你的设计。或许，你会发现那些"坑"早已被优雅地总结和解决。