context-fundamentals

上下文工程基础

上下文是语言模型在推理时可用的完整状态：系统指令、工具定义、检索到的文档、消息历史记录和工具输出。上下文工程是一门通过筛选，保留最精简、信号最强的 token 集合，从而最大限度提高获得预期结果可能性的学科。

本技能不负责实际操作：注意力失效问题的调试归 context-degradation 负责，token 效率优化技巧归 context-optimization 负责。

何时启用

适用于概念性工作：

• 解释上下文是什么，以及注意力机制如何限制 Agent 的行为。
• 为新贡献者提供入门指导，让他们在深入了解操作性技能之前掌握心智模型。
• 从基本原理出发，分析与上下文相关的设计决策（此约束意味着什么，为什么会存在这种权衡），然后再选择具体策略。
• 编写或审阅文档，为操作性指南阐明底层机制。

操作性工作请勿启用此技能。具体执行工作由专门的技能处理：

• 诊断中间丢失、上下文污染或注意力失效问题：context-degradation。
• 通过屏蔽、分区、前缀缓存和预算控制来降低 token 成本：context-optimization。

核心概念

将上下文视为有限的注意力预算，而非存储箱。每增加一个 token，都会与其他 token 争夺模型的注意力，并消耗一份无法在推理过程中补充的预算。工程上的难题是，在三个约束条件下最大化每个 token 的效用：硬性 token 上限、较软的有效容量上限，以及呈 U 形的信息注意力曲线——它会惩罚放在上下文中间的信息（claim-context-degradation-lost-middle-ruler）。

组装上下文时应用以下四项原则：

1. 重视信息量，而非面面俱到——仅包含当前决策所需的信息；设计能够按需检索更多信息的系统。
2. 根据位置安排内容——将关键约束放在上下文开头和结尾，因为长上下文评测表明，模型对位于中间的信息的提取可靠性低于对位于边缘的信息（claim-context-degradation-lost-middle-ruler）。
3. 渐进式披露——启动时加载技能名称和摘要；只有在特定任务激活某项技能时，才加载完整内容。
4. 迭代式筛选——上下文工程不是一次性的提示词编写，而是一门持续应用的学科，每次向模型传递内容时都要运用。

详细主题

上下文剖析

系统提示词 使用 XML 标签或 Markdown 标题将系统提示词组织成不同部分（背景、指令、工具指南、输出格式）。系统提示词会贯穿整个对话，因此应将最关键的约束放在开头和结尾，因为这两处最容易引起注意。

校准指令的抽象程度，以平衡两种失败模式。抽象程度过低会将逻辑硬编码，导致条件变化时难以适应；抽象程度过高则会提供含糊的指导，无法为期望行为给出具体信号。目标是采用启发式指令：具体到足以引导行为，同时灵活到足以泛化——例如，提供分步编号的指引，并为每一步留出判断空间。

从最精简的指令开始，再根据观察到的失败模式逐步添加指令，而不是提前塞入各种边缘情况。精心挑选多样且具有代表性的少样本示例，展示期望行为，而不是罗列所有可能的场景。

工具定义 编写工具描述时，回答三个问题：工具的作用、何时使用，以及它会返回什么。包含使用场景、参数默认值和错误情况——如果人类工程师都无法区分工具，Agent 也无法区分。

尽量精简工具集。整合功能重叠的工具，因为臃肿的工具集会造成决策点模糊，并在 JSON 序列化后占用不成比例的上下文（工具架构通常会比等价的纯文本描述膨胀 2～3 倍）。

检索到的文档 保留轻量级标识符（文件路径、已存储的查询、网页链接），并通过按需检索动态加载数据到上下文中。这与人类认知方式相似——维护索引，而非副本。强标识符（例如 customer_pricing_rates.json）能让 Agent 即使没有搜索工具也能找到相关文件；弱标识符（例如 data/file1.json）则会导致不必要的加载。

拆分大型文档时，应按自然的语义边界（章节标题、段落分隔）切分，而不是按任意字符数限制切分，以免在概念中间截断。

消息历史 消息历史充当 Agent 的草稿记忆，用于跟踪进度、维护任务状态，以及在不同轮次间保留推理过程。对于长时间运行的任务，消息历史可能会不断增长并占据大部分上下文用量——应监控其增长，并在它挤占当前指令之前进行压缩。

循环精简历史记录：当工具在对话较早阶段被调用后，通常无需逐字保留原始结果。将过时的工具输出替换为精简摘要或引用，以减少低价值内容。

工具输出 在 Agent 的执行轨迹中，工具输出往往占据大部分上下文（主张-上下文优化-工具输出主导）。应用观察结果屏蔽：Agent 处理完冗长输出后，将其替换为精简引用。仅保留最近仍相关的文件内容；压缩或移除较早的内容。

上下文窗口与注意力机制

注意力预算 对于 n 个 token，注意力机制会计算 n 平方个成对关系。随着上下文增长，模型维持这些关系的能力会下降——这不是断崖式骤降，而是性能逐步退化。主要使用较短序列进行训练的模型，专门处理全上下文依赖关系的参数较少，因此实际有效上限远低于名义窗口大小。

围绕这种性能梯度进行设计：在针对目标工作负载完成测量之前，假设实际有效容量明显低于标称窗口。名义上下文窗口再大，也不能免除针对特定任务的退化测试（claim-context-degradation-lost-middle-ruler）。

位置编码限制 位置编码插值可以将序列处理范围扩展到训练长度之外，但会降低位置精度。在扩展上下文中，信息检索和长程推理的准确性预计会低于较短输入时的表现。

渐进式披露实践 在三个层面实施渐进式披露：

1. 技能选择 — 启动时只加载名称和描述；按需启用完整技能内容。
2. 文档加载 — 先加载摘要；仅在任务需要时获取详细章节。
3. 工具结果保留 — 完整保留近期结果；压缩或逐出较早的结果。

保持边界清晰：如果启用了某项技能或文档，就完整加载，而不要只加载部分内容——部分加载会造成令人困惑的缺漏，降低推理质量。

上下文质量与数量

不要假设更大的上下文窗口就能解决记忆问题。处理成本会随着上下文长度以不成比例的速度增长——不仅仅是线性成本增加，超过有效容量阈值后，模型性能也会下降。即使使用前缀缓存，长输入仍然成本高昂。

应用信号密度测试：对于每一段上下文，都要问自己，删除它是否会改变模型的输出。如果不会，就将其删除。冗余内容不只是浪费 token，还会主动分散模型对高信号内容的注意力。

实践指南

本节提供概念层面的应用建议，并明确指出了相关操作技能。

思考上下文决策

在需要做出与上下文有关的设计决策时，应将概念问题与操作问题分开。概念问题是“这意味着什么，为什么重要”；操作问题是“具体采用什么技术”。使用本技能回答前者；对于后者，则转到负责该问题的专门技能。

例如，决定是否总结一段较长的 Agent 会话，包含两个部分：（1）为什么需要总结（注意力预算有限，U 形曲线会导致中间内容退化，信号密度比内容量更重要——本技能）；（2）采用什么压缩策略才能保留正确状态，以及在利用率达到什么阈值时触发压缩（转到负责会话压缩的操作技能）。

新贡献者阅读顺序

首次接触上下文工程的贡献者应阅读：

1. 本技能，以理解注意力预算的框架和 U 形曲线。
2. context-degradation，了解上下文失效在实践中的表现及其诊断方法。
3. 根据项目中最相关的操作问题，阅读 context-optimization、memory-systems 中的两到三个技能。

跳过第 1 步，会导致操作人员不理解原因便直接应用技术；跳过操作技能，则会导致理论人员不知道哪种技术适合哪种失效模式。

示例

示例 1：组织系统提示词

说明这一概念：关键约束应放在注意力优先的位置（开头和结尾），明确的分节边界有助于模型解析提示词：

<BACKGROUND_INFORMATION>
You are a Python expert helping a development team.
Current project: Data processing pipeline in Python 3.9+
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- Write clean, idiomatic Python code
- Include type hints for function signatures
- Add docstrings for public functions
- Follow PEP 8 style guidelines
</INSTRUCTIONS>

<OUTPUT_DESCRIPTION>
Provide code blocks with syntax highlighting.
Explain non-obvious decisions in comments.
</OUTPUT_DESCRIPTION>

示例 2：将注意力预算作为心智模型

大上下文模型并不会对上下文中的所有内容给予同等关注。有效容量取决于具体工作负载，而 U 形曲线会降低对中间位置内容的关注度。在决定加载多少上游知识库内容时，可以采用这一心智模型：不要问“能不能装下”，而要问“模型是否仍会关注重要内容”。

与之对应的操作层面问题（应使用哪种技术来减少负载）属于 context-optimization。

指南

1. 将上下文视为边际收益递减的有限资源
2. 将关键信息放在注意力优先的位置（开头和结尾）
3. 使用渐进式披露，在需要时再加载内容
4. 用清晰的分节边界组织系统提示词
5. 在开发过程中监控上下文用量
6. 在使用率达到 70-80% 时触发压缩
7. 针对上下文退化进行设计，而不是寄希望于避免退化
8. 优先使用信号密度高的较小上下文，而不是信号密度低的较大上下文

注意事项

1. 名义窗口不等于有效容量：即使模型宣称拥有较大的上下文窗口，在复杂的检索或推理任务中，也可能远未达到上限就开始退化。在自己的退化测试证明情况并非如此之前，应将预算设在名义窗口以下。

2. 基于字符的 token 估算会悄然产生偏差：英语文本中“约 4 个字符/token”的经验法则不适用于代码（2-3 个字符/token）、URL 和文件路径（每个斜杠、句点和冒号都是独立 token），也不适用于非英语文本（通常为 1-2 个字符/token）。对于任何预算关键型计算，都应使用提供商的实际分词器（例如，OpenAI 模型使用 tiktoken，Anthropic 使用 token 计数 API）。

3. 工具架构经 JSON 序列化后会膨胀 2-3 倍：源代码中看起来简洁的工具定义，序列化后会显著扩展——括号、引号、冒号和逗号都会占用 token。发送一条消息之前，10 个架构适中的工具就可能消耗 5,000-8,000 个 token。应审查序列化后的工具 token 数量，而不是源代码行数。

4. Agent 循环中的消息历史会悄然膨胀：每次工具调用都会将请求和完整响应都添加到历史记录中。经过 20-30 次迭代后，历史记录可能占用窗口的 70-80%，而 Agent 在推理质量骤降之前都不会表现出明显症状。应为历史记录设置严格的 token 上限，并主动触发压缩。

5. 位于中间的关键指令容易丢失：U 形注意力曲线意味着，对上下文中间部分的回忆准确率比开头和结尾低 10-40%。切勿将安全约束、输出格式要求或行为护栏放在较长系统提示词的中间——应将它们置于开头或结尾。

6. 过早加载的渐进式披露会适得其反：一出现相关迹象就加载每项“可能相关”的技能或文档，会重现上下文填塞问题。应设置严格的激活阈值——只有当任务明确符合触发条件时才加载技能，而不仅仅是主题稍有关联时就加载。

7. 混合不同层级的指令会导致行为不一致：在同一个提示词中，将高度具体的规则（“始终使用恰好 3 个项目符号”）与模糊指令（“提供帮助”）组合起来，会造成信号冲突。应按指令层级对其分组，并确保每个部分内部一致——要么基于启发式，要么明确规定，不要交错混用。

集成

此技能是概念基础。它不负责实际操作；它提供实际操作技能所依赖的思维模型。

实际操作任务的路由图：

• context-degradation：诊断注意力失效、信息丢失于中间、投毒和干扰。
• context-optimization：提高令牌效率的策略（屏蔽、分区、缓存、预算）。
• memory-systems：带实体跟踪的跨会话记忆架构。
• multi-agent-patterns：何时应将工作拆分给多个 Agent，以隔离上下文。
• tool-design：编写能够正确路由的工具描述和架构。

请先阅读此技能，建立思维模型；实际执行任务时，再阅读与任务匹配的操作技能。

参考资料

内部参考：

• 上下文组件参考 - 适用于：调试特定上下文组件（系统提示词、工具定义、消息历史记录、工具输出），或实现分块、观察屏蔽或预算分配表

此集合中的相关技能：

• context-degradation - 适用于：随着对话增长或上下文占用超过 60% 容量，Agent 性能下降
• context-optimization - 适用于：令牌成本过高，或需要压缩策略

外部资源：

• Anthropic 的《Effective Context Engineering for AI Agents》——介绍压缩、子 Agent 和混合检索的生产实践模式
• 关于 Transformer 注意力机制和信息丢失于中间效应的研究
• 关于 Agent 软件工程令牌分布的 Tokenomics 研究