笔记 · Agent ·

让缓存命中,错误也留着

Manus 的六条经验很工程化:保护 KV 缓存、用文件当记忆、反复复述目标、把失败留在上下文里。

读书笔记原文:《Context Engineering for AI Agents: Lessons from Building Manus》↗Yichao 'Peak' Ji(季逸超) · Manus

为什么读

这是做过真实产品的人总结的一线经验,每条都有具体做法,官方也有中文版。写于 2025 年 7 月,团队自己说框架已经重写过四次,所以要当作阶段性经验来看。

我记下的要点

  1. 围绕 KV 缓存设计: Manus 输入和输出的 token 比例大约 100:1,用 Claude Sonnet 时缓存命中的输入价格是未命中的十分之一。所以提示词开头要稳定(别放精确到秒的时间戳),上下文只追加不修改,JSON 序列化顺序要固定。
  2. 屏蔽工具,而不是删掉: 任务中途增删工具会让缓存失效,还会让模型困惑。他们用状态机在解码时屏蔽某些工具,工具名统一用 browser_、shell_ 这样的前缀,方便按组限制。
  3. 把文件系统当上下文: 即使有 128K 窗口也不够。压缩要能还原,比如网页内容可以丢,只要保留网址;文档内容可以省,只要文件路径还在。
  4. 用复述控制注意力: 一个任务平均要调用约 50 次工具,Agent 会建一个 todo.md,边做边勾。反复重写计划,就是把总目标推回模型最近的注意力里,防止跑偏。
  5. 把错误留在上下文里: 失败的动作和报错不要藏起来或悄悄重试,模型看到了才会少犯同样的错。
  6. 别被少样本的套路困住: 上下文里重复的动作模式会让模型照着节奏做,比如连续审 20 份简历就容易千篇一律。办法是加入一点受控的变化。

我的想法

前两条是给做 Agent 产品的人看的,我作为使用者不太会碰到。但后面几条用户也能借鉴:让 Claude Code 维护一份待办文件,出错时不急着让它清空重来,把报错留着让它自己看。

「文件当记忆,压缩要能还原」这个想法和 Anthropic、Vercel 的文章都对上了:大家都在往文件系统上靠。

第六条最反直觉。我原本以为上下文越整齐越好,这里却说太整齐反而让 Agent 变脆。我还没想明白普通用户能怎么用上这一条。

我打算试试

  • 下次做多步任务时,让 Claude Code 先写一个 todo.md,每完成一步就更新