外观
概念定义 · 什么是上下文工程(Context Engineering)?
单轮对话拼的是怎么写一句好提示词(Prompt Engineering);而当 Agent 跑上几十轮工具调用、不断塞进海量网页和代码片段时,核心挑战变成了上下文工程(Context Engineering)——也就是像管理稀缺内存一样,精细编排每一轮到底该把什么信息放进有限的上下文窗口。
做得好不好直接决定两件事:一是避免塞入过多噪音导致注意力稀释(Context Rot),二是保持前缀稳定以最大化命中 Prompt Caching,把推理成本打折 80% 以上。
01 为什么要发明它:桌面越大,越容易找不到那张关键纸条
前几年大模型圈还在拼命卷上下文窗口长度:从 4K 涨到 128K,又一路拉到 100 万 Token。很多人天真地以为“窗口够大就万事大吉”,干脆把整座代码仓库、五十个工具说明书、过去三十轮终端报错全一股脑倒进 Prompt 里。
结果一上真实生产环境就翻车了:模型明明离窗口上限还远着呢,却开始频频漏看最开头的核心禁令、把三轮前废弃的旧方案当成现状、逻辑准确率肉眼可见地滑坡——业界管这种退化叫 上下文腐烂(Context Rot)。更扎心的是账单:一个连续执行 30 步的 LLM Agent,每走一步都要把前面攒的所有文字重新读一遍,输入 Token 呈平方级暴涨,跑完一个任务可能烧掉好几美元。
类比 · 一公里长的办公桌 vs 严谨的幕僚长
把 100 万 Token 的 长上下文窗口 想象成一张一公里长的办公桌。桌子上摊满 500 份文件,绝不意味着你的大脑能同时精准比对第 12 页和第 487 页的数字——满桌废纸只会让你眼花缭乱、注意力被彻底稀释。
上下文工程(Context Engineering) 就是给模型配一位精明的幕僚长:它不再纠结某一句提示词写得漂不漂亮,而是专职管控“每一轮到底把哪几页纸摆到模型眼前”,让有限的注意力预算全部花在刀刃上。
核心设问
当 Agent 必须连续运转几十甚至上百轮时,如何既让模型的“眼前视野”始终干净锋利(对抗 Context Rot),又把重复阅读历史记录的算力与费用压到极致?
02 核心直觉:四把桌面整理手术刀与“前半段冻结”秘诀
Anthropic 工程团队(2025) ↗ 将工业界打磨出的上下文治理方案归纳为四个清晰动作:写出去(Write)、选进来(Select)、压变瘦(Compress)、隔离开(Isolate)。
第一刀:Write(外置落盘)
工具一次吐出 3 万字测试报错日志?千万别直接塞进主对话!把它原封不动存成外部文件,只在上下文里留一张小便利贴:“日志已存为 obs_8a3f,共 3 万字,前 3 行摘要是……需要哪几行再按行精读”。
第二刀:Select(按需选入与渐进式工具披露)
查资料时借助 RAG 检索 精准捞出最相关的几段证据;面对 80 个外部 MCP 工具时绝不一上来全摊开,而是采用渐进式披露——先只展示一份几百字的精简工具目录,等模型选定某个领域工具,再按需加载对应的完整 JSON 参数说明书。
第三刀:Compress(旧观测清理与检查点摘要)
十轮之前读过的冗长网页或编译日志早已被模型消化完毕,留在窗口里只会干扰视线。优先执行可逆清理——把早期工具返回正文折叠成一行路径指针;等到总占用逼近 75%–80% 红线时,再一次性把早期历程压成结构化检查点摘要(保留目标、已验证事实、已排除死路与待办清单)。
第四刀:Isolate(子智能体隔离)
要翻遍几十个文件排查一个隐蔽线索?千万别在主会话里亲自乱翻!派一个拥有空白窗口的 Sub-agent 去隔壁房间做重度探查,不管它翻了多少废纸、试错多少次,最后只允许它把一页精炼结论递回主会话,主窗口永远一尘不染。
类比 · 活页笔记本的“只增不改”铁律(Prefix KV Caching)
想要同时省钱提速,核心武器是 Prefix KV Caching(前缀缓存)。底层推理引擎(如 PagedAttention 与 RadixAttention)会把读过的词元中间状态缓存在显存里:
把 Prompt 想象成一本带复写缓存的活页笔记本。只要你每次只在最后一页往后追加新内容(Append-Only),前面已经算好的几十页缓存就全部有效,模型只需算最新添的那几行,前缀命中部分费用通常直接打一折;但如果你手痒去改了封面第一行的“当前时间:14:05:23”,整本笔记本的缓存瞬间全盘作废,引擎被迫从第一页头重脚轻地重算一遍。
类比 · 外科主刀与化验室的分工(Isolate 隔离直觉)
为什么一定要用 Sub-agent 做隔离?就像手术室里主刀医生(主 Agent)只盯着核心病历做决策,绝不亲自去化验室翻看三百张原始血检底片——化验室(子 Agent)在独立房间处理完所有脏活累活,最后只递回一张干干净净的化验单。
03 把关键公式读成人话
为什么无关日志一多,模型就会变笨?看看 自注意力机制 给每个历史词分配权重的方式:
把公式读成直觉:-
是堆在上下文里的废话和过时报错,哪怕每条废话本身几乎不吸引注意力( 很小),一旦废话数量 滚雪球般涨到几万词,分母里的 就会把关键线索分到的注意力份额硬生生稀释掉。 - 这就是 Context Rot 的数学本质:Softmax 的总注意力预算永远只有
,噪声占的地盘越多,真信息分到的光就越暗。
再算一笔 20 步 Agent 任务的真实成本账——对比无缓存与严格命中前缀缓存:
把公式读成直觉:- 设开头的系统规则与工具目录长
- 不开缓存时,步数
翻倍总费用按 翻四倍,20 步总共要付约 44.5 万 输入 Token;而一旦严格守住前缀不变(缓存读取打一折 ,首写 ),等效账单骤降到约 8.4 万 Token——直接省下 81% 以上的输入费用,首字响应速度也肉眼可见地变快。
04 它在模型里怎么工作 & 与上下游的关系
让我们把上面四把刀串起来,看一个真实的 20 轮线上故障排查 里,上下文引擎每一秒都在忙什么:
- 第 0 轮(冻结静态前缀):把系统指令、安全禁令与精简版工具目录按固定顺序锁死在 Prompt 最前端,让后续 19 轮全都免费搭 Prefix Cache 的顺风车。
- 第 1–8 轮(Write + Isolate 并行):主 Agent 派两个 Sub-agent 分别查数据库慢查询日志和微服务链路追踪,各自消化完 10 万字原始日志后只回传两段核心结论;主会话里产生的超长工具返回自动落盘为
obs_xxxx句柄。 - 第 15 轮(批量 Compress):眼看上下文占用爬到 78% 水位线,管理器一次性把第 1–10 轮已经用完的旧工具观测折叠成单行索引,顺便留下一份四栏结构化进度清单,瞬间腾出一半空间。
在整个大模型技术栈中,上下文工程正好卡在“底层推理系统”和“上层智能体应用”的咽喉位置:
- 向下吃透硬件与推理规律:它顺应 自注意力机制 的信噪比特征与 KV Cache 分页前缀复用 规则,并与底层的 KV 缓存压缩 形成文本治理 + 张量压缩的双重减负。
- 向上托举长周期 Agent:把单次会话里的外置读写(Write / Select)延伸到跨天、跨周的持久化状态管理,就演化成了 Agent 长期记忆系统;而在需要连续修改上百个文件的 编程 Agent 中,上下文工程更是决定解决率和账单生死的命门。
05 演化对比与避坑备忘
| 阶段 / 策略 | 核心思路 | 效果与局限 |
|---|---|---|
| 初代 Prompt Engineering | 精心打磨单轮措辞与角色扮演 | 适合单轮问答,管不了多轮轨迹膨胀 |
| 暴力大窗口硬塞 | 把所有文档和日志直接拼进 Prompt | 触发 Lost in the Middle ↗ 退化,费用二次爆炸 |
| 现代 Context Engineering | Write / Select / Compress / Isolate + Prefix Cache | 保持高信噪比,同时将多轮 Prefill 成本压降 80%+ |
三个最容易踩的实战坑:
- 在 System Prompt 里放秒级时间戳或随机 Request ID:这相当于每轮都在涂改活页本封面第一行,瞬间把价值数万 Token 的 Prefix Cache 全盘击穿。任何动态变化的变量都必须追加在消息列表末尾。
- 每轮用滑动窗口切掉最老的一条消息:表面上省了几百 Token,实际上每切一次头,整段前缀起点就错位一次,导致前缀缓存命中率直接归零——算总账反而贵了好几倍!正确做法是允许历史平滑追加,等到触达 75%–80% 高水位时再一次性批量压缩。
- 压缩时把“走过的死胡同”抹得一干二净:如果把失败的工具尝试全删光,模型失忆后下一轮还会兴冲冲地拿一模一样的参数再撞一次南墙。应该删掉几千行冗长报错堆栈,但务必保留“试过 X、因 Y 失败”的一行墓碑记录。
想查看 Context Rot 完整推导、Prefix Cache 成本对比模型以及可运行的 Python
ContextBudgetManager源码?按快捷键M或点击顶部技术 Wiki随时切换。
上下文工程(Context Engineering) 是围绕大语言模型有限的注意力预算,系统性设计、筛选、压缩、隔离并缓存推理输入(System Prompt、工具定义、外部证据、对话轨迹与记忆状态)的工程方法论。与关注单次措辞润色的 Prompt Engineering 不同,上下文工程将上下文视为稀缺的动态运行态工作内存,核心目标是在每一轮 Agent 决策循环 中以最低 Token 成本提供最高信噪比的最小充分信息集。
直观理解
百万级上下文窗口好比一张一公里长的办公桌,能摊开上千份文件并不意味着大脑能同时精准比对其中任意两行数字。上下文工程就像一位严谨的幕僚长:把固定不变的规章制度钉死在桌角方便速查(Prefix Caching),把过期草稿收进档案柜(Write / Compress),每次开会只把最关键的三页材料推到眼前(Select),繁杂的专项调查则派专员到隔壁房间做完再交一页结论(Isolate)。
起源背景与演进脉络
随着现代模型将上下文上限推至 128K 乃至 1M Token(见 长上下文建模),早期工程界曾产生“把一切原始资料全塞进 Prompt 即可替代检索与状态管理”的乐观预期。然而在多轮自主 Agent 生产实践中,三个结构性瓶颈迅速暴露:
- 注意力稀释与上下文腐烂(Context Rot):实验(如 Lost in the Middle 与 Chroma Context Rot 基准)反复证实,即使输入远未触达窗口物理上限,随着无关日志、历史试错残片和冗余工具文档堆积,模型召回关键约束与跨文档推理的准确率仍呈单调下滑。
- 多轮轨迹的二次费用与延迟爆炸:Agent 每执行一步工具调用,都必须把历史前缀重新送入模型 Prefill;若无前缀缓存复用,长达
步的轨迹将产生 级别的输入计费与首字延迟(TTFT)。 - 上下文污染与目标漂移(Context Poisoning & Distraction):早期失败尝试中的错误假设、过时代码片段或外部网页中的噪声,会持续占据 自注意力机制 权重,诱导模型陷入重复试错。
2025 年起,Anthropic、LangChain 与 Manus 等团队正式将这套多轮状态治理实践提炼为 Context Engineering,标志着大模型应用开发从“静态提示词调优”迈入“动态上下文系统设计”阶段。
核心原理与数学推导
1. Context Rot 的注意力稀释机理
在标准 缩放点积自注意力 中,第
其中
即使单条噪声得分极低(
2. 四大上下文治理原语(Write / Select / Compress / Isolate)
- Write(外置写入):将中间计划、工具长输出或阶段状态落盘至外部文件系统或草稿本(Scratchpad),仅在上下文中保留轻量路径指针与摘要,避免原始大块文本滞留工作区。
- Select(按需选入):在每步推理前通过语义检索(RAG)、符号索引或记忆打分动态拉取高相关证据;对工具定义采用渐进式披露(Progressive Disclosure)——初始仅暴露高层路由目录,命中后再展开完整 JSON Schema。
- Compress(分层压缩):优先执行可逆的旧观测清理(Tool Result Clearing)(剥离早期冗长返回体但保留外置文件句柄),仅在触及高水位时对早期轨迹生成结构化检查点摘要。
- Isolate(隔离执行):采用 Orchestrator-Worker(主从子智能体) 架构,将重度探索与跨文件检索下放给拥有独立空白窗口的 Sub-agent,主上下文只接收其精炼结论,从根源阻断中间噪声回流。
3. 前缀不变性与 Prefix KV Caching 成本模型
推理引擎借助 PagedAttention / RadixAttention 以词元前缀树组织 KV Cache:只要两次请求的词元序列在
当
架构数据流与治理闭环
图表加载中...
上下文治理原语与缓存策略横向对比
| 治理原语 / 策略 | 核心操作 | 信息保真度 | Prefix Cache 友好度 | 典型适用场景 |
|---|---|---|---|---|
| Write(外置落盘) | 长日志与快照落盘,窗口仅保留句柄 | 高(随时可重读) | 极高(不改动历史前缀) | 终端测试输出、网页抓取正文、多阶段清单 |
| Select(动态检索) | 按子目标检索证据或延迟加载工具 Schema | 中高(依赖召回率) | 中(宜追加尾部而非改前缀) | 大型知识库问答、超 50 个 MCP 工具动态路由 |
| Compress(观察清理 / 摘要) | 折叠早期工具返回体或生成检查点摘要 | 低至中(有损) | 低(改写历史会击穿缓存,宜批量触发) | 超长多轮会话触达 75%~85% 预算水位 |
| Isolate(Sub-agent 隔离) | 独立窗口执行探索,仅回传精炼摘要 | 高(主窗口零污染) | 高(主从各自维护稳定前缀) | 跨百文件代码库排查、并行文献调研 |
| Prefix Pinning(前缀冻结) | 严禁动态变量进入 System Prompt 与工具区 | 无损 | 极高(命中率可达 90%+) | 所有多轮 Agent 循环与高并发共享模板 |
核心 Python 参考实现
下面实现一个轻量级 ContextBudgetManager:冻结静态前缀区保护 Prefix Cache,对超长工具观测自动执行外置落盘(Write),在触达水位时批量折叠旧观测(Compress),并核算前缀缓存命中率与等效计费比。
python
from __future__ import annotations
import hashlib
from dataclasses import dataclass, field
from typing import Any
def estimate_tokens(text: str) -> int:
return max(1, len(text) // 4)
@dataclass
class ContextEntry:
role: str
content: str
artifact_id: str | None = None
compacted: bool = False
@property
def tokens(self) -> int:
return estimate_tokens(self.content)
@dataclass
class ContextBudgetManager:
"""支持前缀缓存保护、大观测外置落盘与水位压缩的上下文管理器。"""
system_prompt: str
tool_catalog_summary: str
max_tokens: int = 32_000
compact_trigger_ratio: float = 0.78
offload_char_threshold: int = 2_400
history: list[ContextEntry] = field(default_factory=list)
artifact_store: dict[str, str] = field(default_factory=dict)
_last_prefix_hashes: list[str] = field(default_factory=list)
def _static_prefix_messages(self) -> list[dict[str, str]]:
# 冻结静态前缀顺序,严禁混入时间戳或随机 ID,最大化 Prefix Cache 命中
return [
{"role": "system", "content": self.system_prompt},
{"role": "system", "content": f"[Tool Index]\n{self.tool_catalog_summary}"},
]
def append_turn(self, role: str, content: str) -> None:
if role == "tool" and len(content) > self.offload_char_threshold:
aid = f"obs_{hashlib.sha1(content.encode()).hexdigest()[:8]}"
self.artifact_store[aid] = content
preview = content[:240].replace("\n", " ")
self.history.append(ContextEntry(role, f"[Offloaded: {aid} | chars={len(content)}] {preview}...", aid))
else:
self.history.append(ContextEntry(role, content))
def maybe_compact(self, keep_recent: int = 4) -> int:
static_tok = sum(estimate_tokens(m["content"]) for m in self._static_prefix_messages())
if static_tok + sum(e.tokens for e in self.history) < int(self.max_tokens * self.compact_trigger_ratio):
return 0
saved = 0
for entry in self.history[: max(0, len(self.history) - keep_recent)]:
if entry.role == "tool" and not entry.compacted:
old_tok = entry.tokens
entry.content = f"[Compacted Tool Observation (artifact={entry.artifact_id})]"
entry.compacted = True
saved += max(0, old_tok - entry.tokens)
return saved
def build_request_and_meter(self) -> tuple[list[dict[str, Any]], dict[str, float]]:
self.maybe_compact()
messages = self._static_prefix_messages() + [{"role": e.role, "content": e.content} for e in self.history]
cur_hashes = [hashlib.md5(f"{m['role']}:{m['content']}".encode()).hexdigest() for m in messages]
lcp = 0
for h_old, h_new in zip(self._last_prefix_hashes, cur_hashes):
if h_old != h_new:
break
lcp += 1
cached = sum(estimate_tokens(m["content"]) for m in messages[:lcp])
uncached = sum(estimate_tokens(m["content"]) for m in messages[lcp:])
self._last_prefix_hashes = cur_hashes
raw = max(1, cached + uncached)
return messages, {
"raw_tokens": float(raw), "cached_tokens": float(cached),
"cache_hit_ratio": round(cached / raw, 3),
"effective_cost_ratio": round((cached * 0.10 + uncached * 1.25) / raw, 3),
}
if __name__ == "__main__":
mgr = ContextBudgetManager("你是严谨的研发助手。" * 200, "read_artifact; run_tests; grep")
mgr.append_turn("user", "请排查支付模块超时原因")
_, m1 = mgr.build_request_and_meter()
mgr.append_turn("assistant", "先运行集成测试定位超时接口。")
mgr.append_turn("tool", "TIMEOUT traceback line...\n" * 400)
_, m2 = mgr.build_request_and_meter()
print("Step 1:", m1, "\nStep 2:", m2)工程实践与常见陷阱
工程实践
- 保持上下文严格 Append-Only 并冻结静态前缀:系统规则、Few-shot 与固定工具 Schema 置于最前端且保持 JSON 键顺序确定;动态时间或状态变量应追加在轨迹尾部。
- 分层渐进披露工具定义:当 MCP 工具超过数十个时,先暴露紧凑目录或元搜索工具,命中后再加载完整 Schema,避免大体积工具说明挤占注意力。
- 结构化检查点摘要:触发压缩时强制保留四栏核心状态——当前目标、已验证文件路径与事实、已排除的错误路径、下一步待办清单。
常见陷阱
- 在 System Prompt 头部塞入秒级时间戳或随机 Trace ID:哪怕第 10 个 Token 发生变化,整段数万 Token 的 Prefix KV Cache 也会瞬间全部失效,导致账单暴涨 5~10 倍。
- 每轮滑动窗口删掉最早的一条消息:逐轮删头会让前缀起点每步偏移、缓存命中率归零;应允许轨迹平滑增长,仅在触及高水位(75%~85%)时一次性批量压缩。
- 过度净化上下文抹除失败教训:删掉几千行报错正文是合理的,但必须保留“试过何种参数、为何失败”的一行墓碑记录,否则模型失忆后会重复撞墙。
延伸阅读与参考论文
- Anthropic Engineering (2025). Effective Context Engineering for AI Agents. Anthropic Engineering ↗
- Liu, N. F., Lin, K., Hewitt, J., et al. (2023). Lost in the Middle: How Language Models Use Long Contexts. TACL 2024. arXiv:2307.03172 ↗
- Gim, I., Chen, G., Lee, S., et al. (2024). Prompt Cache: Modular Attention Reuse for Low-Latency Inference. MLSys 2024. arXiv:2311.04934 ↗
- Zheng, L., Yin, L., Xie, Z., et al. (2024). SGLang: Efficient Execution of Structured Language Model Programs (RadixAttention). NeurIPS 2024. arXiv:2312.07104 ↗
- Manus AI (2025). Context Engineering for AI Agents: Lessons from Building Manus. Manus Blog ↗