题记与说明
标题：Context Engineering for AI Agents: Lessons from Building Manus
作者：Yichao 'Peak' Ji（Manus 核心成员）
来源 URL：https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
发布日期：2025-07-18
存档日期：2026-11-01
标签：上下文工程 / AI Agent / KV-Cache / Agent 架构 / Manus / 工具设计
这篇讲什么
Manus 早期面临抉择：训练端到端 agent 模型，还是在前沿模型的 in-context learning 之上搭 agent？作者吸取上一段创业的教训（自训模型在 GPT-3 出现后一夜过时）选择后者——押注上下文工程。他们把 agent 框架推倒重建了四次，戏称这种"架构搜索 + prompt 手调 + 经验猜测"为 "Stochastic Graduate Descent"。这篇文章就是四次重建沉淀出的局部最优解。
核心观点
- 围绕 KV-cache 设计一切：KV-cache 命中率是生产级 agent 最重要的单一指标。实践是：prompt 前缀保持稳定（别在开头放秒级时间戳）、上下文 append-only、序列化确定性、必要时显式标缓存断点。
- Mask, don't remove：不要在迭代中途动态增删工具——那会打爆 KV-cache 且让模型幻觉出不存在的动作。Manus 用状态机在解码时遮蔽 logits，并让工具名带统一前缀（browser\_、shell\_）来约束选择。
- 把文件系统当上下文：任何不可逆压缩都有风险（你无法预知哪条观测十步之后变得关键）。文件系统是"无限大、持久、agent 可直接操作"的外部记忆；压缩必须可还原——网页内容可丢但 URL 要留，文档可省但路径要在。
- 用 todo.md 复述操纵注意力：Manus 平均一个任务要 50 次工具调用，长循环易跑偏；不断重写 todo 等于把全局目标复述到上下文末端，对抗 lost-in-the-middle。
- Keep the wrong stuff in：把失败和报错留在上下文里，抹掉失败就抹掉了证据；错误恢复是真正 agentic 行为最清晰的指标之一。
- 别被 few-shot 套牢：上下文太均匀会让模型模仿模式陷入节奏（如批改 20 份简历越改越像），需注入结构化变化打破惯性。
最值得记住的金句与数据
- 「If model progress is the rising tide, we want Manus to be the boat, not the pillar stuck to the seabed.」——模型进步是涨潮，agent 产品要做船，不做钉死在海床上的柱子。
- 「Erasing failure removes evidence. And without evidence, the model can't adapt.」——抹掉失败就是抹掉证据。
- 数据：Claude Sonnet 缓存命中的输入 0.30 USD/MTok、未命中 3 USD/MTok，差 10 倍；Manus 输入输出 token 比约 100:1；平均任务约 50 次工具调用；agent 框架重建了 4 次。
对我的启发
- Agent 系统：五条原则可直接照抄进自己的 agent loop——尤其"把 KV-cache 命中率当第一指标"，上下文从设计起就该 append-only。
- AI 编程工具：解释了为什么 coding agent 会话要只追加、为什么调试时保留报错在上下文里反而更聪明——"清理轨迹"是反模式。
- 个人知识管理：'文件系统即外部记忆、压缩必须可还原'与个人 KM 同构——正文可以不在眼前，但 URL 和路径必须留痕；todo.md 复述对应每日索引/回顾机制。
- 写作：一线复盘式技术写作的范本——每原则一节、给出具体机制（prefill 三模式）、结尾诚实声明局限性。
适合谁读
在做或想动手做 AI agent 的工程师（KV-cache、constrained decoding、状态机 mask 全是干货）；想理解 agent 内部机制的产品与研究者；以及想把"上下文管理"思维迁移到知识管理和工作流的人。与 Anthropic 的《Effective context engineering for AI agents》互补阅读效果最好。