context-fundamentals

上下文工程基础

上下文是语言模型在推理时可用的完整状态：系统指令、工具定义、检索文档、消息历史和工具输出。上下文工程是一门学科，旨在策划最小的高信号令牌集，以最大化期望结果的可能性。

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

何时激活

当工作是概念性时激活此技能：

• 解释什么是上下文以及注意力机制如何约束智能体行为。
• 为新贡献者提供入门培训，使其在深入操作性技能之前掌握思维模型。
• 从基本原理出发推理与上下文相关的设计决策（这个约束意味着什么，为什么存在这种权衡），然后再选择具体策略。
• 编写或审查需要将操作指导建立在底层机制基础上的文档。

不要为操作性工作激活此技能。专门技能负责执行：

• 诊断中间丢失、上下文中毒或注意力失败：context-degradation。
• 通过掩码、分区、前缀缓存、预算降低令牌成本：context-optimization。
• 将长会话压缩为交接摘要：context-compression。
• 卸载大型工具输出或维护持久草稿板：filesystem-context。
• 决定LLM项目或管线的形态：project-development。

核心概念

将上下文视为有限的注意力预算，而不是存储箱。添加的每个令牌都会竞争模型的注意力，并消耗一个在推理过程中无法补充的预算。工程问题是在三个约束下最大化每令牌的效用：硬令牌限制、较软的有效容量上限，以及惩罚放置在上下文中间信息的U型注意力曲线（claim-context-degradation-lost-middle-ruler）。

在组装上下文时应用四个原则：

1. 信息性优于详尽性 — 只包含对当前决策重要的内容；设计能够按需检索额外信息的系统。
2. 位置感知放置 — 将关键约束放在上下文的开头和结尾，因为长上下文评估表明中间位置的信息比边缘位置的信息更难可靠恢复（claim-context-degradation-lost-middle-ruler）。
3. 渐进式披露 — 启动时加载技能名称和摘要；仅在技能为特定任务激活时加载完整内容。
4. 迭代策划 — 上下文工程不是一次性的提示编写练习，而是在每次将内容传递给模型时应用的持续学科。

详细主题

上下文的构成

系统提示
使用XML标签或Markdown标题（背景、指令、工具指导、输出格式）将系统提示组织成不同的部分。系统提示在整个对话中持续存在，因此将最关键的限制放在注意力最强的开头和结尾。

校准指令高度以平衡两种失败模式。高度过低会硬编码脆弱的逻辑，当条件变化时失效。高度过高提供模糊的指导，无法为期望行为提供具体信号。目标是启发式驱动的指令：足够具体以指导行为，足够灵活以泛化——例如，编号步骤，每个步骤留有判断空间。

从最小开始，然后根据观察到的失败模式反应性地添加指令，而不是预先填充边缘情况。策划多样化的、规范的少量示例，展示期望行为，而不是列出每个可能的场景。

工具定义
编写回答三个问题的工具描述：工具做什么、何时使用、返回什么。包括使用上下文、参数默认值和错误情况——如果人类工程师无法区分工具，智能体也无法区分。

保持工具集最小化。合并重叠的工具，因为臃肿的工具集创建模糊的决策点，并在JSON序列化后消耗不成比例的上下文（工具模式通常比等效的纯文本描述膨胀2-3倍）。

检索文档
维护轻量级标识符（文件路径、存储查询、网页链接），并使用即时检索动态将数据加载到上下文中。这模仿了人类认知——维护索引，而不是副本。强标识符（例如customer_pricing_rates.json）让智能体即使没有搜索工具也能定位相关文件；弱标识符（例如data/file1.json）强制不必要的加载。

在分块大型文档时，在自然语义边界（章节标题、段落分隔符）处分割，而不是在任意字符限制处切断概念。

消息历史
消息历史作为智能体的草稿板内存，用于跟踪进度、维护任务状态和跨轮次保留推理。对于长时间运行的任务，它可能增长到主导上下文使用——监控并在其挤占活动指令之前应用压缩。

循环优化历史：一旦工具在对话深处被调用，原始结果很少需要逐字保留。用紧凑摘要或引用替换过时的工具输出，以减少低信号体积。

工具输出
工具输出通常在智能体轨迹中主导上下文（claim-context-optimization-tool-output-dominance）。应用观察掩码：一旦智能体处理完结果，用紧凑引用替换冗长输出。仅保留最近相关的文件内容；压缩或驱逐较旧的内容。

上下文窗口与注意力机制

注意力预算
对于n个令牌，注意力机制计算n平方的成对关系。随着上下文增长，模型维护这些关系的能力下降——不是硬性悬崖，而是性能梯度。主要在较短序列上训练的模型，用于上下文范围依赖的专门参数较少，从而在标称窗口大小以下产生有效上限。

为此梯度设计：假设有效容量在目标工作负载上测量之前，实质上低于广告窗口。大的标称上下文窗口并不消除任务特定退化测试的需要（claim-context-degradation-lost-middle-ruler）。

位置编码限制
位置编码插值将序列处理扩展到训练长度之外，但会引入位置精度的退化。与较短输入的性能相比，在扩展上下文上，信息检索和长程推理的准确性预计会降低。

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

1. 技能选择 — 启动时仅加载名称和描述；按需激活完整技能内容。
2. 文档加载 — 先加载摘要；仅在任务需要时获取详细部分。
3. 工具结果保留 — 完整保留最近结果；压缩或驱逐较旧结果。

保持边界清晰：如果技能或文档被激活，则完全加载而不是部分加载——部分加载会创建令人困惑的空白，降低推理质量。

上下文质量与数量

拒绝认为更大的上下文窗口解决内存问题的假设。处理成本随上下文长度不成比例地增长——不仅是线性成本缩放，而且超出有效容量阈值时模型性能下降。即使使用前缀缓存，长输入仍然昂贵。

应用信号密度测试：对于每段上下文，询问删除它是否会改变模型的输出。如果不会，则删除它。冗余内容不仅浪费令牌——它还会主动稀释对高信号内容的注意力。

实用指导

本节提供概念性应用建议。指向操作性技能的指针是明确的。

推理上下文决策

当需要做出与上下文相关的设计决策时，将概念性问题与操作性问题分开。概念性问题是“这意味着什么以及为什么重要”；操作性问题是我们应用哪种具体技术。使用此技能回答第一个问题；路由到拥有第二个问题的专门技能。

例如，决定是否总结一个长的智能体会话有两个部分：(1) 为什么需要总结（注意力预算有限，U型曲线降低中间内容，信号密度比数量更重要——此技能）和 (2) 哪种压缩策略保留正确的状态以及在什么利用率阈值触发它（context-compression）。

新贡献者阅读顺序

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

1. 此技能，以内化注意力预算框架和U型曲线。
2. context-degradation，了解上下文失败在实践中是什么样子以及如何诊断。
3. 根据项目最相关的操作问题，选择context-optimization、context-compression、filesystem-context、memory-systems中的两到三个。

跳过步骤1会产生应用技术而不理解原因的操作者；跳过操作技能会产生不知道哪种技术适合哪种失败模式的理论家。

示例

示例1：组织系统提示

说明了关键约束应放在注意力偏好的位置（开头和结尾），以及明确的章节边界有助于模型解析提示的概念点：

<BACKGROUND_INFORMATION>
你是一名Python专家，帮助开发团队。
当前项目：Python 3.9+数据处理管线
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- 编写干净、惯用的Python代码
- 为函数签名包含类型提示
- 为公共函数添加文档字符串
- 遵循PEP 8风格指南
</INSTRUCTIONS>

<OUTPUT_DESCRIPTION>
提供带有语法高亮的代码块。
在注释中解释非显而易见的决策。
</OUTPUT_DESCRIPTION>

示例2：注意力预算作为思维模型

大上下文模型并不具有同等关注的上下文。有效容量是工作负载特定的，U型曲线惩罚放置在中间的信息。在决定加载多少上游知识库时，这是思维模型：不要问“能装下吗”，而是问“模型还会关注重要的部分吗”。

相应的操作性问题（哪种技术应减少加载）属于context-optimization。

指南

1. 将上下文视为具有递减回报的有限资源
2. 将关键信息放在注意力偏好的位置（开头和结尾）
3. 使用渐进式披露延迟加载直到需要
4. 用清晰的章节边界组织系统提示
5. 在开发期间监控上下文使用
6. 在70-80%利用率时实施压缩触发器
7. 为上下文退化设计，而不是希望避免它
8. 优先选择较小的高信号上下文，而不是较大的低信号上下文

陷阱

1. 标称窗口不是有效容量：宣传大上下文窗口的模型可能在复杂检索或推理任务上远在该限制之前退化。在您自己的退化测试证明之前，预算低于标称窗口。

2. 基于字符的令牌估计会悄然漂移：英语散文约4字符/令牌的启发式方法在代码（2-3字符/令牌）、URL和文件路径（每个斜杠、点和冒号都是单独的令牌）以及非英语文本（通常1-2字符/令牌）上失效。对于任何预算关键的计算，使用提供者的实际分词器（例如OpenAI模型的tiktoken，Anthropic的令牌计数API）。

3. 工具模式在JSON序列化后膨胀2-3倍：在源代码中看起来紧凑的工具定义在序列化时会显著扩展——括号、引号、冒号和逗号各自消耗令牌。十个具有中等模式的工具在发送一条消息之前可能消耗5,000-8,000令牌。审计序列化的工具令牌计数，而不是源代码行数。

4. 消息历史在智能体循环中悄然膨胀：每次工具调用都会将请求和完整响应添加到历史中。经过20-30次迭代，历史可能消耗窗口的70-80%，而智能体直到推理质量崩溃才显示可见症状。对历史设置硬令牌上限，并主动触发压缩。

5. 中间的关键指令会丢失：U型注意力曲线意味着上下文中间位置的召回准确率比开头和结尾低10-40%。切勿将安全约束、输出格式要求或行为护栏放在长系统提示的中间——将它们锚定在顶部或底部。

6. 过于急切加载的渐进式披露会适得其反：在第一次提示相关性时加载每个“潜在相关”的技能或文档会重新创建上下文填充问题。设置严格的激活阈值——技能仅应在任务明确匹配其触发条件时加载，而不是在主题仅仅相邻时。

7. 混合指令高度导致不一致的行为：在同一提示中结合超具体规则（“始终使用恰好3个要点”）和模糊指令（“有帮助”）会创建冲突信号。按高度级别分组指令，并保持每个部分内部一致——要么是启发式驱动，要么是规定性，而不是两者交织。

集成

此技能是概念基础。它不负责操作性工作；它提供操作技能所假设的思维模型。

操作性工作的路由图：

• context-degradation：诊断注意力失败、中间丢失、中毒、分心。
• context-optimization：令牌效率策略（掩码、分区、缓存、预算）。
• context-compression：压缩长会话同时保留决策、文件、风险。
• filesystem-context：卸载大型输出并使用文件作为持久草稿板。
• memory-systems：跨会话内存架构与实体跟踪。
• multi-agent-patterns：何时跨智能体拆分工作以实现上下文隔离。
• tool-design：编写正确路由的工具描述和模式。
• project-development：决定LLM适合度并塑造多阶段管线。

首先阅读此技能以构建思维模型；在实际工作时阅读适合任务的操作技能。

参考

内部参考：

• 上下文组件参考 - 何时阅读：调试特定上下文组件（系统提示、工具定义、消息历史、工具输出）或实施分块、观察掩码或预算分配表

本集合中的相关技能：

• context-degradation - 何时阅读：当对话增长或上下文填充超过60%容量时智能体性能下降
• context-optimization - 何时阅读：当令牌成本过高或需要压缩/压缩策略时

外部资源：

• Anthropic的“AI智能体有效上下文工程”——压缩、子智能体和混合检索的生产模式
• 关于Transformer注意力机制和中间丢失效应的研究
• 关于智能体软件工程令牌分布的Tokenomics研究

---

技能元数据

创建日期：2025-12-20
最后更新：2026-05-15
作者：上下文工程贡献者智能体技能
版本：2.2.0