context-fundamentals

上下文工程基础

上下文是语言模型在推理时可用的完整状态：系统指令、工具定义、检索到的文档、消息历史记录和工具输出。上下文工程是一门整理最小高信号词元集合的学科，旨在最大限度地提高预期结果出现的可能性。

这项技能是本集合中其他所有技能的概念基础。它阐释了什么是上下文、注意力机制如何运作、为什么上下文质量比数量更重要，以及理解其他上下文工程决策所需的思维模型。它不负责具体操作：调试注意力失效归 context-degradation 负责，词元效率策略归 context-optimization 负责，对话摘要归 context-compression 负责，基于文件的卸载归 filesystem-context 负责，项目结构决策归 project-development 负责。

何时启用

当工作涉及概念层面时，启用此技能：

• 解释什么是上下文，以及注意力机制如何限制 Agent 的行为。
• 为新贡献者提供入门指导，让他们在深入操作技能之前掌握相关思维模型。
• 从第一性原理推理与上下文相关的设计决策（这一限制意味着什么、这种权衡为何存在），然后再选择具体策略。
• 编写或审查文档，为操作指南奠定底层机制方面的基础。

操作性工作不要启用此技能。具体执行由专门技能负责：

• 诊断中间信息丢失、上下文污染或注意力失效：context-degradation。
• 通过屏蔽、分区、前缀缓存和预算控制来降低词元成本：context-optimization。
• 将长会话压缩成交接摘要：context-compression。
• 卸载大型工具输出或维护持久的草稿区：filesystem-context。
• 决定大模型项目或流水线的结构：project-development。

核心概念

将上下文视为有限的注意力预算，而不是存储箱。添加的每个词元都会争夺模型的注意力，并消耗推理过程中无法补充的预算。工程上的问题是在三项约束下最大化每个词元的效用：硬性词元上限、较软的有效容量上限，以及会惩罚上下文中间位置所含信息的 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）采用什么压缩策略来保留恰当的状态，以及在利用率达到什么阈值时触发压缩（context-compression）。

新贡献者的阅读顺序

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

1. 本技能，以理解注意力预算的思路和 U 型曲线。
2. context-degradation，了解上下文故障在实践中的表现以及诊断方法。
3. 根据项目中最相关的操作性问题，从 context-optimization、context-compression、filesystem-context、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：提高令牌效率的策略（屏蔽、分区、缓存、预算）。
• context-compression：压缩长会话，同时保留决策、文件和风险。
• filesystem-context：将大型输出转存到文件，并将文件用作持久的草稿区。
• memory-systems：带实体跟踪功能的跨会话记忆架构。
• multi-agent-patterns：判断何时应将工作拆分给多个 Agent，以隔离上下文。
• tool-design：编写能正确路由的工具描述和架构。
• project-development：判断大模型是否适用，并设计多阶段流水线。

先阅读此技能以建立思维模型；实际开展工作时，再阅读适用于该任务的实际操作技能。

参考资料

内部参考：

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

此合集中的相关技能：

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

外部资源：

• Anthropic 的《面向 AI Agent 的有效上下文工程》——关于精简、子 Agent 和混合检索的生产实践
• 关于 Transformer 注意力机制和信息中段丢失效应的研究
• 关于 Agent 软件工程令牌分布的令牌经济学研究

---

技能元数据

创建时间：2025-12-20 上次更新：2026-05-15 作者：Agent Skills for Context Engineering Contributors 版本：2.2.0