深入理解 Context Engineering 基础:注意力预算、上下文窗口解剖与质量优先原则
深入理解 Context Engineering 基础:注意力预算、上下文窗口解剖与质量优先原则
导读:本文是 Agent Skills for Context Engineering 仓库中 context-fundamentals 技能(skills/context-fundamentals/SKILL.md)的完整解读,它回答上下文工程中最根本的问题:上下文到底是什么、注意力机制如何约束 Agent 行为、为什么上下文质量比数量更重要。读完本文,你将掌握注意力预算、U 形注意力曲线、渐进式披露等核心思维模型,并能使用仓库提供的 context_manager.py 工具完成上下文组装、token 估算与预算管理,为后续学习诊断(context-degradation)、优化(context-optimization)与压缩(context-compression)等操作型技能打下概念地基。
什么是 Context Engineering
Context(上下文)是语言模型在推理时刻可用的完整状态:系统指令、工具定义、检索文档、消息历史与工具输出的总和。上下文工程(Context Engineering)则是这样一门学科:精心挑选一组最小的、高信号密度的 token 集合,以最大化期望结果出现的概率。
在 skills/context-fundamentals/SKILL.md 中,这一技能被明确定位为整个技能集合的概念地基——它只负责回答"为什么",不负责"怎么做"。具体的操作工作被路由到专门技能:
- 调试注意力失败(lost-in-middle、上下文投毒等):
context-degradation - 降低 token 成本(掩码、分区、前缀缓存、预算):
context-optimization - 将长会话压缩为交接摘要:
context-compression - 将大型工具输出卸载到文件系统、维护持久草稿板:
filesystem-context - 决定 LLM 项目或管线的形态:
project-development
这个"概念技能 + 操作技能"的分层设计本身就是一个渐进式披露的实践案例:系统启动时只加载技能名称与摘要,只有任务真正匹配时才加载完整内容。
何时激活此技能
应该激活的场景(概念性工作)
- 解释上下文是什么,以及注意力机制如何约束 Agent 行为
- 新贡献者入职培训——在深入操作技能之前,先建立思维模型
- 基于第一性原理推演上下文相关的设计决策(这个约束意味着什么?这个权衡为什么存在?),再选择具体战术
- 编写或评审需要以底层机制为依托的文档
不应激活的场景(操作性工作)
此技能明确声明不拥有操作工作。诊断、优化、压缩、文件卸载、项目塑形分别属于上面列出的五个专门技能。这条边界本身就是文章后面要讲的"路由思维":先问"这是什么、为什么重要",再问"该用哪种技术",两者不能混为一谈。
核心概念:把上下文当作有限的注意力预算
原文档给出的第一原则是:
Treat context as a finite attention budget, not a storage bin.
把上下文当作有限的注意力预算,而不是存储箱。 每增加一个 token,都在与模型的注意力竞争,并消耗一份推理中途无法补充的预算。工程问题是在三个约束下最大化每个 token 的效用:
- 硬性 token 上限——模型窗口的额定大小;
- 更软的"有效容量"天花板——远低于额定窗口的实际可用容量;
- U 形注意力曲线——处于上下文中间位置的信息更容易被遗忘。
这一论断在仓库的 researcher/claims/index.jsonl 中登记为可追溯的主张(claim_id: claim-context-degradation-lost-middle-ruler),其证据来源指向 docs/claude_research.md,表述为:"长上下文系统存在中间位置召回退化,且宣传的上下文长度并不能保证在该长度下的任务表现。"仓库的独立研究循环为这类技能主张建立了可审计的证据链,这正是"以证据支撑设计决策"的体现。
组装上下文的四条原则
- 信息性优于穷尽性(Informativity over exhaustiveness)——只保留对当前决策重要的内容,并设计能在需要时按需检索额外信息的系统。
- 位置感知放置(Position-aware placement)——把关键约束放在上下文开头和结尾,因为长上下文评测反复表明:中间位置信息的可靠恢复率低于边缘位置。
- 渐进式披露(Progressive disclosure)——启动时只加载技能名称与摘要;技能为具体任务激活时才加载完整内容。
- 迭代策展(Iterative curation)——上下文工程不是一次性写提示词的活动,而是每次向模型传递内容时都要执行的持续纪律。
上下文的解剖(The Anatomy of Context)
系统提示词(System Prompts)
使用 XML 标签或 Markdown 标题将系统提示词组织成清晰的区块(背景、指令、工具引导、输出格式)。系统提示词在整场对话中持续存在,因此最关键的约束必须放在开头和结尾——那里注意力最强。
指令高度的校准(Altitude Calibration) 需要平衡两种失败模式:
- 过低的高度:把脆弱的逻辑硬编码进去,条件一变化就失效;
- 过高的高度:指引过于含糊,无法为期望行为提供具体信号。
目标是启发式驱动(heuristic-driven)的指令:足够具体以引导行为,又足够灵活以泛化——例如带编号的步骤,每一步保留判断空间。
skills/context-fundamentals/references/context-components.md 给出了三种高度的对比示例:
# Too Low (Brittle) —— 过低,脆弱
If the user asks about pricing, check the pricing table in docs/pricing.md.
If the table shows USD, convert to EUR using the exchange rate in
config/exchange_rates.json. ...
# Too High (Vague) —— 过高,含糊
Help users with pricing questions. Be helpful and accurate.
# Optimal (Heuristic-Driven) —— 最优,启发式驱动
For pricing inquiries:
1. Retrieve current rates from docs/pricing.md
2. Apply user location adjustments (see config/location_defaults.json)
3. Format with appropriate currency and tax considerations
Prefer exact figures over estimates. When rates are unavailable,
say so explicitly rather than projecting.
另一个实践要点是从最小开始、按需增加:先写最小集合,再根据观察到的失败模式反应式地补充指令,而不是预防式地塞入所有边界情况。few-shot 示例应精选多样化、能代表期望行为的样本,而非罗列所有可能的场景。
工具定义(Tool Definitions)
工具描述要回答三个问题:做什么、何时用、返回什么。还要包含使用上下文、参数默认值和错误情况——如果人类工程师都无法区分两个工具,Agent 也无法区分。
工具集合要保持精简。合并重叠的工具,因为臃肿的工具集会制造模糊的决策点,并且经 JSON 序列化后会消耗不成比例的大量上下文——工具 schema 序列化后通常膨胀为等效纯文本描述的 2-3 倍(这一数字同时出现在本技能与 skills/context-optimization/SKILL.md 的注意事项中)。
参考文档给出了工具定义的推荐结构:
{
"name": "tool_function_name",
"description": "Clear description of what the tool does and when to use it",
"parameters": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "What this parameter controls",
"default": "reasonable_default_value"
}
},
"required": ["param_name"]
},
"returns": {
"type": "object",
"description": "What the tool returns and its structure"
}
}
强描述示例(来自参考文档):
Retrieve customer information by ID or email.
Use when:
- User asks about a specific customer's details, history, or status
- User provides a customer identifier and needs related information
Returns customer object with:
- Basic info (name, email, account status)
- Order history summary
- Support ticket count
Returns null if customer not found. Returns error if database unreachable.
检索文档(Retrieved Documents)
维护轻量级标识符(文件路径、已存查询、网页链接),并通过即时检索(just-in-time retrieval) 动态地把数据加载进上下文。这模仿了人类认知——维护索引,而不是副本。
强标识符(如 customer_pricing_rates.json)让 Agent 即使没有搜索工具也能定位相关文件;弱标识符(如 data/file1.json)则会强制进行不必要的加载。参考文档列举了对比:
- 弱标识符:
data/file1.json、ref/ref.md、2024/q3/report - 强标识符:
customer_pricing_rates.json、engineering_onboarding_checklist.md、2024_q3_revenue_report.pdf
对大型文档做分块时,应在自然语义边界(章节标题、段落分隔)处切分,而不是用任意的字符长度限制把概念拦腰切断。参考文档给出了语义分块的伪代码骨架:先找出章节标题、段落分隔与逻辑断点作为边界候选,再过滤掉过小或过大的分块。
消息历史(Message History)
消息历史充当 Agent 的草稿板内存:追踪进度、维护任务状态、跨轮保留推理。对长期任务而言,它可能膨胀到主导上下文占用——必须监控,并在它挤占活跃指令之前执行压缩。
循环式精炼历史:一旦某个工具在对话深处被调用过,其原始结果很少需要逐字保留。把过时的工具输出替换为紧凑摘要或引用,以减少低信号的大块内容。
参考文档给出了消息的推荐结构(role、content、可选的 reasoning、tool_calls、tool_output、长会话的 summary),以及一个摘要注入模式:每 N 条消息(示例为 20)后,把最近的 N 条消息汇总为一条 role: "system" 的 is_summary: True 消息注入会话。
工具输出(Tool Outputs)
工具输出往往是 Agent 轨迹中最大的上下文占用者。仓库的 researcher/claims/index.jsonl 明确登记了这条主张(claim_id: claim-context-optimization-tool-output-dominance):"工具输出频繁主导 Agent 轨迹的 token 占用,因此观察掩码(observation masking)往往带来最大的上下文容量收益。"其证据来源同样是 docs/claude_research.md。
应对手段是观察掩码(Observation Masking):Agent 处理完结果后,把冗长输出替换为紧凑引用,只保留最近相关的文件内容,压缩或逐出更老的内容。参考文档的掩码实现示意:
def mask_observation(output, max_length=500):
"""Replace long observations with compact references."""
if len(output) <= max_length:
return output
reference_id = store_observation(output)
return f"[Previous observation elided. Full content stored at reference {reference_id}]"
这种方式在降低 token 消耗的同时,通过外部存储 + 引用 ID 保留了信息可恢复性。
上下文窗口与注意力机制
注意力预算(The Attention Budget)
对 n 个 token,注意力机制要计算 n 的平方 个两两关系。上下文增长时,模型维持这些关系的能力会退化——这不是陡峭的悬崖,而是性能梯度。主要在较短序列上训练的模型,缺少足够多的专用于上下文级依赖的参数,形成了远低于额定窗口大小的有效容量天花板。
设计时必须正视这个梯度:在针对目标负载实测之前,假定有效容量远低于宣传的窗口大小。大额定上下文窗口并不能免除针对任务的退化测试——这条主张对应 claim-context-degradation-lost-middle-ruler。
位置编码的限制(Position Encoding Limits)
位置编码插值(interpolation)可以把序列处理扩展到训练长度之外,但会引入位置精度退化。相比短输入,在扩展上下文中做信息检索和长程推理时,准确率会下降。
渐进式披露的实践(Progressive Disclosure in Practice)
渐进式披露在三个层级落地:
- 技能选择——启动时只加载名称与描述,按需激活完整技能内容;
- 文档加载——先加载摘要,任务需要时再抓取细节章节;
- 工具结果保留——近期结果完整保留,更早的结果压缩或逐出。
边界要清晰:一旦激活某个技能或文档,就完整加载,而不是部分加载——部分加载会制造令人困惑的空洞,降低推理质量。
上下文质量 vs 数量(Context Quality Versus Quantity)
原文档明确拒绝"更大上下文窗口就能解决记忆问题"的假设:
- 处理成本随上下文长度不成比例地增长——不仅是线性成本,还有超出有效容量阈值后的模型性能退化;
- 长输入即使有前缀缓存也依然昂贵;
- 判断依据是信号密度测试:对每一条上下文,问"删除它是否会改变模型输出"——如果不会,就删除它。冗余内容不仅浪费 token,还会主动稀释高信号内容获得的注意力。
参考文档给出一个粗略的预算估算基准:英语文本约 4 字符/token,1000 words ≈ 7500 characters ≈ 1800-2000 tokens。同时给出了上下文预算分配表,可用于会话开始前的规划:
| 组件 | 典型范围 | 说明 |
|---|---|---|
| 系统提示词 | 500-2000 tokens | 整个会话保持稳定 |
| 工具定义 | 每个工具 100-500 tokens | 随工具数量增长 |
| 检索文档 | 不定 | 往往占用最大 |
| 消息历史 | 不定 | 随对话增长 |
| 工具输出 | 不定 | 可能主导上下文 |
源码级实操:用 context_manager.py 组装与审计上下文
本技能附带一个可直接运行的实用工具 skills/context-fundamentals/scripts/context_manager.py,它是上述概念(优先级感知组装、token 预算、结构校验、渐进式披露)的可执行实现。
高层入口:build_agent_context
from context_manager import build_agent_context
result = build_agent_context(
task="Refactor auth module",
system_prompt="You are a senior Python engineer.",
documents=["# Auth module docs ..."],
)
print(result["usage_report"])
该函数内部演示了优先级驱动的上下文组装:系统提示词优先级最高(10,跨轮次持久),任务描述次之(9),检索文档最低(5,即时加载)。返回值包含 context(拼装好的字符串)、usage_report(token 用量报告)与 validation(结构校验结果)。
ContextBuilder:按优先级分配硬预算
builder = ContextBuilder(context_limit=80_000)
builder.add_section("system", prompt, priority=10)
builder.add_section("task", task_text, priority=9)
built = builder.build()
ContextBuilder 在预算紧张时按优先级从高到低保留区块,并提供一个状态机式的健康判定:利用率 > 0.9 为 critical,> 0.7 为 warning,否则 healthy。这与各操作技能的触发阈值(如 skills/context-optimization/SKILL.md 的 70-80% 压缩触发点)完全对齐。
模块内置的审计函数
estimate_token_count(text):按 4 字符/token 粗略估算(仅限开发期快速检查,代码、URL、非英语文本比率差异很大);estimate_message_tokens(messages):每条消息额外计入约 10 token 的 role/格式开销;count_tokens_by_type(context):按系统提示词、工具定义、检索文档、消息历史等维度剖析 token 去向,用于优先压缩最大开销组件;truncate_context(context, max_tokens, preserve_start=True):单块文本的截断,支持保留开头或结尾;truncate_messages(messages, max_tokens):保留系统提示词、既有摘要消息与最近消息的结构化截断;validate_context_structure(context):检查空区块、超长(> 80K token 告警)、缺失推荐区块(system/task)与潜在重复内容。
ProgressiveDisclosureManager:按需加载 + 会话缓存
pdm = ProgressiveDisclosureManager(base_dir="docs")
overview = pdm.load_summary("docs/api_summary.md")
# ... 稍后真正需要细节时 ...
detail = pdm.load_detail("docs/api/endpoints.md")
这个类实现"先摘要、后细节"的懒加载模式:摘要与细节文件首次加载后按路径缓存,load_detail(..., force=True) 可绕过缓存强制重读;get_contextual_info() 依据参考字典中的 need_detail 标志决定返回摘要还是细节。这正是"维护索引而非副本"与三级渐进式披露中"文档加载"一层的直接落地。
注意:模块文档字符串明确警告,
estimate_token_count的字符比率启发式仅供演示。生产系统必须换成真实 tokenizer——OpenAI 模型用tiktoken,Anthropic 用其 token 计数 API。这个警告与下方"陷阱"部分的字符估算漂移问题互为印证。
用思维模型推演上下文决策
本技能的核心产出是分离概念问题与操作问题的思维框架:
- 概念问题:"这是什么、为什么重要"——由本技能回答;
- 操作问题:"该用哪种具体技术"——路由到对应的专门技能。
以"是否要对一个长 Agent 会话做摘要"为例:
- 为什么需要摘要(概念层):注意力预算有限、U 形曲线会劣化中间内容、信号密度比体积更重要——本技能负责;
- 用哪种压缩策略、在什么利用率阈值触发(操作层):
context-compression负责。
仓库还为此提供了真实的基准验证环境:researcher/benchmarks/effectiveness/tasks/001-filesystem-context-offload 是一个"文件系统上下文卸载"有效性的测评任务,要求 Agent 在 tool_output.txt 与可选的 scratch/ 目录间组织内容——它把本技能描述的"轻量标识符 + 即时检索 + 文件型草稿板"变成了可执行、可评分的实战场景。
新贡献者阅读顺序
一个初次接触上下文工程的贡献者应该按以下顺序阅读(见 skills/context-fundamentals/SKILL.md 的 Practical Guidance):
- 本技能:内化注意力预算框架与 U 形曲线;
context-degradation:了解上下文失败在实践中的表现与诊断方法(可参考 skills/context-degradation/references/patterns.md 中的注意力分布测量、投毒追踪、健康监控与告警阈值配置);- 再按项目关切选读
context-optimization、context-compression、filesystem-context、memory-systems中的两三个。
跳过第 1 步,会产生"只会用技术、不知道为什么"的操作者;跳过操作技能,则会产生"不知道哪种技术适配哪种失败模式"的理论家。
操作路由图(Integration)
本技能是概念地基,操作工作全部路由出去:
context-degradation:诊断注意力失败、lost-in-middle、投毒、干扰;context-optimization:token 效率战术(掩码、分区、缓存、预算);context-compression:压缩长会话并保留决策、文件、风险;filesystem-context:卸载大输出、以文件作为持久草稿板;memory-systems:跨会话记忆架构与实体追踪;multi-agent-patterns:何时拆分工作到多 Agent 以获得上下文隔离;tool-design:编写正确路由的工具描述与 schema;project-development:判断 LLM 适配性、塑形多阶段管线。
先读本技能建立思维模型,动手做事时再读匹配任务的操作技能。
实践指南清单(Guidelines)
- 把上下文视为收益递减的有限资源
- 把关键信息放在注意力受偏爱的位置(开头与结尾)
- 用渐进式披露推迟加载直到需要时
- 用清晰的区块边界组织系统提示词
- 开发期间持续监控上下文占用
- 在 70-80% 利用率处实现压缩触发
- 为上下文退化做设计,而不是指望避开它
- 宁可要小的高信号上下文,不要大的低信号上下文
常见陷阱(Gotchas)
- 额定窗口 ≠ 有效容量:宣传大窗口的模型在复杂检索或推理任务上可能远未到极限就退化。在自己的退化测试证明之前,按低于额定窗口来规划预算。
- 基于字符的 token 估算会静默漂移:英语散文约 4 字符/token,但代码约 2-3 字符/token,URL 与文件路径中每个斜杠、点、冒号都是独立 token,非英语文本往往 1-2 字符/token。预算敏感的计算必须使用厂商真实 tokenizer(OpenAI 用 tiktoken,Anthropic 用 token 计数 API)。
- 工具 schema 经 JSON 序列化后膨胀 2-3 倍:源码中看起来紧凑的定义,序列化后括号、引号、冒号、逗号各自消耗 token。十个中等 schema 的工具可能在发送第一条消息前就消耗 5,000-8,000 tokens。审计的是序列化后的 token 数,不是源码行数。
- 消息历史在 Agent 循环中静默膨胀:每次工具调用都会把请求和完整响应加入历史。20-30 次迭代后,历史可能占用窗口的 70-80%,而 Agent 直到推理质量崩溃前都无明显症状。要为历史设置硬性 token 上限并主动触发压缩。
- 中间位置的关键指令会丢失:U 形注意力曲线意味着上下文中间位置的召回准确率比开头和结尾低 10-40%。永远不要把安全约束、输出格式要求或行为护栏放在长系统提示词的中间——锚定在顶部或底部。
- 过度热切的渐进式披露会弄巧成拙:一出现"可能相关"就加载所有技能或文档,等于重建上下文塞填问题。设置严格的激活阈值——技能只应在任务明确匹配其触发条件时加载,而不是主题沾边就加载。
- 混合指令高度导致行为不一致:在同一提示词里混用超具体规则("永远恰好用 3 个要点")与含糊指令("要乐于助人")会制造冲突信号。按高度分组指令,保持每个区块内部一致——要么启发式驱动,要么规定式,不要交错。
进一步阅读
- 本技能的详细技术参考:Context Components Reference——在调试某个具体上下文组件,或实现分块、观察掩码、预算分配表时阅读;
- 配套实用工具:context_manager.py——可直接运行交互式演示(
python context_manager.py); - 下游操作技能:context-degradation(上下文占用超过 60% 容量或对话变长导致性能下降时)、context-optimization(token 成本过高或需要压缩/压缩策略时);
- 可追溯的主张索引:researcher/claims/index.jsonl(本技能引用的 U 形曲线、工具输出主导等论断均有登记与证据来源)。
(本文基于仓库中 skills/context-fundamentals/SKILL.md 及其参考资料撰写,技能元数据:版本 2.2.0,创建于 2025-12-20,最后更新于 2026-05-15。)