笔记：AI 代理的上下文工程——Manus 的经验教训（KV Cache / 工具掩蔽 / 文件系统记忆）
来源： Manus Blog《Context Engineering for AI Agents: Lessons from Building Manus》
- 原文：https://manus.im/zh-cn/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus
- 作者：Yichao “Peak” Ji
- 发布时间：2025-07-18
这篇文章我很喜欢的点在于：它把“做 Agent 不是堆模型能力”这件事讲得非常工程化。作者明确选择 押注上下文工程（Context Engineering）而不是训练端到端智能体模型，核心理由是：迭代周期从“周级”缩成“小时级”，并且能把产品和底座模型解耦，模型升级是“潮水”，产品应该做“船”。
下面是文中最关键的 6 个方法论，以及我对我们体系的可落地启发。
1) 围绕 KV Cache 设计（生产代理最关键的单指标）
作者的判断很直接：如果只能选一个生产指标，那就是 KV-cache 命中率，因为它同时决定延迟（TTFT）和成本。
为什么代理更吃缓存
代理循环通常是“长输入、短输出”：每一步都把动作与观察追加进上下文，导致输入 token 远大于输出 token。文中给了 Manus 的经验比值：平均输入:输出约 100:1。这意味着 prefill 的成本/延迟是大头。
提升命中率的操作要点
- 提示前缀保持稳定：哪怕只差一个 token，后面缓存都失效。常见坑：在 system prompt 里放精确到秒的时间戳。
- 上下文只追加（append-only）：不要回写/修改历史动作或观察；序列化要确定性（尤其 JSON key 顺序）。
- 必要时明确插入缓存断点：有些框架需要手动 breakpoints。
- 自托管推理（如 vLLM）要开启 prefix cache，并用会话 ID 等方式把同一会话路由到一致的 worker。
对我们的启发
- 任何“动态变动的系统提示”（时间戳、随机数、每轮变化的说明）都应尽量挪到靠后或放到文件里，避免破坏前缀缓存。
- 工具调用参数（尤其 JSON）必须稳定序列化，避免“同样的对象每次 key 顺序不同”造成隐性退化。
2) 遮蔽（mask）而不是移除（remove）工具
当工具数量爆炸（尤其 MCP 场景）时，模型会更容易选错工具或走低效路径。
文中的反直觉结论：除非绝对必要，不要在代理迭代过程中动态增删工具。
理由有两点：
- 工具定义常出现在上下文前部，变更会导致后续 KV cache 全失效。
- 历史动作/观察还引用旧工具，当前上下文却不再定义，会让模型困惑，导致越狱式幻觉调用或 schema 违规。
Manus 的做法：用“上下文感知状态机”管理可用工具，但不是从上下文里移除工具，而是在解码阶段 掩蔽 token 的 logits，强制/禁止选择某些动作。
对我们的启发
- 工具集合尽量固定，动态权限用“选择约束”实现，而不是“改工具列表”。
- 工具命名用统一前缀分组（browser_/shell_/rss_…），便于按状态屏蔽/放行。
3) 用文件系统做上下文（把记忆外置化）
文章对长上下文的态度很务实：即使 128K+，在真实代理任务里依然不够用，或者成本太高、性能会掉。
Manus 把 文件系统视为终极上下文：容量无限、天然持久化、可读写。
它强调一个设计原则：压缩策略必须“可恢复”。比如：
- 网页内容可以从上下文移除，但只要保留 URL，随时可重新抓取。
- 文档内容可以移除，但只要沙盒里路径还在，随时可再读。
对我们的启发
- 我们做“调研/总结/跨日任务”时，最稳的做法是：把原文、证据段落、todo、草稿都写入文件（站点 repo 或 workspace），上下文里只保留指针。
- 这也是为什么“把重要内容放进网站（可维护项目）而不是聊天记录”是对的：聊天是短期上下文，网站/文件才是长期外置记忆。
4) 通过复述操控注意力（todo.md 不是可爱，是机制）
Manus 在复杂任务里会写 todo.md 并持续更新。作者说这不是装可爱，而是为了对抗长链路任务中模型偏航：
- 典型任务平均 50 次工具调用，容易“做着做着忘了目标”。
- 反复重写 todo，相当于把目标推到上下文末尾，让近期注意力不断对齐全局目标。
对我们的启发
- 对于多步骤任务（尤其“抓取-提炼-生成网页-发布-通知”这种流水线），强制维护一个 todo/plan 文件，能显著减少偏航。
5) 保留错误（不要清理失败痕迹）
代理会犯错是常态。文章认为：把失败尝试保留在上下文里，反而更利于模型隐式更新“信念”，减少重复错误。删掉错误会删掉证据，模型就难以适应。
对我们的启发
- 我们做工具链时，失败日志应该“可见且可追踪”（写到文件里），而不是把错误吞掉重试到成功为止。
6) 不要被少样本示例困住（避免模式化复读）
少样本示例在 agent 场景可能反噬：模型会模仿上下文里的行为节奏，即便不再最优。
Manus 的解法是 引入可控的多样性：不同的序列化模板、替代措辞、顺序微扰，让模型不陷入单一模式。
对我们的启发
- 对重复性任务（批量读 20 篇文章/20 份简历/20 个公告），要刻意打破“固定节奏”，避免模型机械复读导致偏航或幻觉。
我觉得最重要的 3 句话（带走就够用）
1) 生产代理最重要指标：KV cache 命中率。 2) 工具不要动态增删，优先用解码约束/掩蔽来控动作空间。 3) 文件系统/网站是长期记忆；上下文只保留指针与计划。
我们可以立刻做的行动项
- 统一约定：系统提示里不放秒级时间戳，不做会破坏前缀的“每轮变化文本”。
- 工具命名做前缀分组；权限控制优先用“选择约束”，避免改工具定义。
- 对所有长任务强制写
todo.md（或同等计划文件），每个阶段结束复述一次目标与下一步。 - 抓取/调研类内容默认进入网站 repo（可维护项目），聊天只发链接。