
上下文工程:构建高效、可恢复、可扩展智能体的系统方法
本文翻译整理自 Yichao “Peak” Ji 于 2025 年 7 月 18 日发表的文章《Context Engineering for AI Agents》,并结合 dev.to 社区和 r/MachineLearning 讨论进行补充。
https://medium.com/@peakji/context-engineering-for-ai-agents-lessons-from-building-manus-71883f0a67f2
一、Context Engineering 胜于重训模型
在 Manus 项目早期,团队面临两个方向选择:训练专属 Agent 模型,还是基于最先进 LLM 做“上下文工程”。历史告诉我们:BERT 微调时代迭代慢、成本高,GPT-3 出现后 in-context 的范式更灵活。所以,Manus 坚决押注上下文工程:
- 迭代周期从周级 -> 小时级;
- 与底层模型解耦,可以随模型能力提升迅速接入新能力。
二、KV‑Cache 命中率:主导 latency 与成本的关键指标
上下文增长快是 Agent 的常态。Manus 统计上下文输入输出比为 100:1。因此:
- KV‑Cache 命中率直接决定延迟(TTFT)与费用。
- 以 Claude Sonnet 为例:缓存命中 token 约 $0.30/百万,冷缓存则约 $3/百万,10 倍差距。
实践建议:
1. 前缀稳定:去除每次调用中可能变化的元素,如时间戳等。
2. 追加不修改上下文,不变序列化顺序。
3. 手动 cache breakpoints,保障缓存失效时有明确切割 (manus.im)。
三、Mask 不 Remove:静态定义 + 动态遮-mask
Agent 中工具(function calls)爆炸增长,会导致:
- Context 改动 → KV‑cache 无效;
- 上下文历史中提到的工具如果被删除,容易混淆或造成幻觉。
Manus 的策略:
- 保留所有工具定义不变;
- 根据当前状态,用logits mask 阻止模型选用不应启用的工具;
- 对命名做统一前缀(如browser_,shell_),便于批量 mask 控制。
四、用本地文件系统扩展上下文长度
上下文窗口虽已 128K+,但实际 agent 场景仍有三大痛点:
1. 大量网页/PDF内容会迅速用满上下文;
2. 非结构化文本过长会拖慢模型;
3. 即使有缓存,传输与 KV-prefill 费用仍高。
Manus 的实践:
- 将历史记录写入 sandbox 文件系统;
- 上下文中只保留路径和摘要——如网页 URL 而非全文;
- 模型按需读取、重构 Context;
- 所有压缩手段可逆,能按需完全恢复信息。
五、Recitation 技巧:todo.md 持续强化注意力机制
复杂任务中,Manus 往往包含 50+ 次工具调用。在这种长循环里容易 “中途走神”。
解决方式:
- 使用todo.md 文件存储当前待办列表;
- 每轮迭代追加检查,结束后 recitation(复述)到上下文结尾;
- 自然语言将全程焦点重新引导进 attention window,避免任务漂移。
六、错误保留 ≠ 隐藏
Agent 执行失败是在所难免的事实。Manus 的做法是:
- 不隐藏错误输出,而是将 stack trace / error 留在上下文;
- 这相当于给模型一个 implicit 学习信号,告诉它“这类操作容易失败”,减少重复错误。
如 LinkedIn 上总结所说:“leaving error information … helps models avoid repeating mistakes”
七、不要陷入 Few-shot 模式化陷阱
Few-shot 能改善单步输出,但会导致 Agent 在长任务中陷入“套路化”模式:
- Manus 遇到简历批处理等任务时,若上下文模板一致,容易反复走相似路径 → 发散或幻觉。
对策:
- 在示例 action-observation 中引入微小变化:模板排版、措辞、序列调整;
- 控制随机性“打散”套路,让模型对不同情况适应更灵活。
八、Stochastic Graduate Descent:上下文架构的实验式重构
上下文工程不是理论推导,而是 “实验科学”。Manus 已重构框架 4 次,每一次都是为了优化 context 结构、prompt 机制、cache 效率等指标 (manus.im)。
团队称此过程为“Stochastic Graduate Descent”:在 prompt + 架构空间持续迭代搜索 → 不聪明,但实用奏效。
小结:Manus 提炼的上下文工匠心法
方法 | 目的 | 效果 |
前缀稳定 + append‑only | 提升 KV‑Cache 命中率 | ⬇️ 延迟 & 成本,快速响应 |
Mask 不 Remove 工具 | 控制 action 空间 | 避免 cache 断裂、context confusion |
文件系统做上下文扩展 | 实现无限上下文 | 支持长任务与恢复能力 |
todo.md Recitation | 强化注意力 | 减少任务漂移、中途 off‑target |
错误上下文保留 | 引导模型学习失败 | 提高鲁棒、降低重复出错 |
Few-shot 多样化 | 避免套路陷阱 | 增强灵活性与准确率 |
多轮 SGD 实践迭代 | 提炼工程思路 | 快速优化与系统稳定性提升 |
未来展望:从 Transformer 到 SSM-contextual Agents
最后,作者提出一个大胆愿景:如果 SSM(State Space Models)能配合“文件记忆”机制,解决跨长距离依赖问题,它们也许能成为真正高效的 Agent engine,继承 Neural Turing Machine 的设想。
写在最后
上下文工程不是“高级技巧”,而是构建高效 AI Agent 的 必须工序。Manus 用真金白银和使用反馈告诉我们:只有结构良好、缓存高效、上下文完整、行为鲁棒、可恢复、可管理,智能 Agent 才可能从实验室走向产线上线。
本文转载自PyTorch研习社,作者:南七无名士
