Context Fundamentals Zh

---
name: context-fundamentals-zh
description: 上下文工程基础概念、什么是上下文、上下文窗口的构成、注意力预算、U 形注意力曲线（中间迷失）、渐进式披露、上下文质量优于数量、系统提示词分段与「指令高度」。当用户问「什么是上下文工程」「为什么长上下文反而效果差」「系统提示词怎么组织」「工具定义占多少 token」「什么是渐进式披露」，或需要给新同事讲清楚 Agent 上下文的心智模型时使用。这是概念性技能：解释与入门；具体操作路由到专门技能——诊断注意力失效用 context-degradation-zh，压缩长会话用 context-compression-zh，工具描述与 schema 用 tool-design-zh，跨会话记忆用 memory-systems-zh。也覆盖「心智模型」「塞进提示词」「关键约束放哪」这类说法。改编自 Agent Skills for Context Engineering 的 context-fundamentals（MIT）。
author: Captain
version: 0.1.1
display_name: "上下文工程基础"
display_name_en: "Context Engineering Fundamentals (zh)"
description_zh: "上下文是推理时模型可见的全部状态：系统提示、工具定义、检索文档、消息历史、工具输出。把上下文当有限的注意力预算而不是储物箱：信息量优先于穷举、关键约束放首尾、渐进式披露、持续策展。附各组件的技术参考。"
description_en: "Context is everything the model sees at inference time. Treat it as a finite attention budget, not a storage bin: informativity over exhaustiveness, critical constraints at the edges, progressive disclosure, iterative curation. With a per-component technical reference."
tags:
  - "上下文工程"
  - "context window"
  - "注意力预算"
  - "渐进式披露"
  - "系统提示词"
  - "概念入门"
examples_zh:
  - "给我讲讲上下文工程的基本概念和心智模型"
  - "为什么我把所有文档都塞进提示词效果反而变差了"
  - "系统提示词应该怎么分段、关键约束放哪"
examples_en:
  - "Explain the core mental models of context engineering"
  - "Why did stuffing every doc into the prompt make things worse?"
  - "How should I section a system prompt and where do constraints go?"
metadata:
  { "openclaw": { "requires": { "bins": [] }, "os": ["darwin", "linux", "windows"], "emoji": "🧠" } }
---

# 上下文工程基础

上下文是语言模型推理时可用的**全部状态**：系统指令、工具定义、检索到的文档、消息历史、工具输出。上下文工程是一门策展的学问：用**最小的高信号 token 集**最大化得到期望结果的概率。

本技能是其他上下文技能共同的概念地基。它不负责操作：诊断注意力失效归「上下文退化诊断」，长会话压缩归「上下文压缩」，工具描述归「工具设计」，跨会话记忆归「记忆系统」。

## 什么时候用

概念性工作时：解释上下文与注意力机制如何约束 Agent 行为；给新成员建立心智模型；在挑具体技术之前从第一性原理推理一个上下文设计决策；写需要机制支撑的文档。操作性工作不要用它，去找上面的专门技能。

## 核心概念

把上下文当**有限的注意力预算**，不是储物箱。每加一个 token 都在争夺注意力，消耗一份推理中途无法补充的预算。工程问题是在三重约束下最大化「每 token 的效用」：硬性 token 上限、更软的有效容量天花板、以及惩罚中间位置信息的 U 形注意力曲线。

组装上下文的四条原则：
1. **信息量优先于穷举**：只放当前决策需要的东西；让系统能按需再取。
2. **位置感知**：关键约束放在开头和结尾，长上下文实验表明中间位置的信息回忆可靠性更低。
3. **渐进式披露**：启动时只加载技能名和摘要；某技能被任务激活后再加载全文。
4. **持续策展**：上下文工程不是一次性写提示词，而是每次向模型传内容时都要做的功课。

## 上下文的解剖

**系统提示词。** 用 XML 标签或 Markdown 标题分成清晰的段（背景、指令、工具指引、输出格式）。系统提示全程存在，所以最关键的约束放在注意力最强的开头和结尾。

校准**指令高度**，避开两种失败：太低（把易碎的具体逻辑写死，条件一变就崩）和太高（「要有帮助、要准确」这种给不出信号的空话）。目标是**启发式驱动**：具体到能引导行为，灵活到能泛化——例如带编号的步骤、每步留判断空间。从最小集开始，观察到失败模式再反应式地加指令，而不是预先堆满边角情况。精选少量多样、典型的示例，而不是罗列所有场景。

**工具定义。** 描述要回答三个问题：做什么、什么时候用、返回什么；带用法背景、参数默认值、错误情况。人类工程师分不清的两个工具，Agent 也分不清。工具集保持最小；合并重叠的工具，因为 JSON 序列化后 schema 通常比等价的纯文本描述膨胀 2–3 倍。

**检索文档。** 维护轻量标识符（文件路径、保存的查询、链接），按需即时加载——像人一样维护索引而不是副本。强标识符（`customer_pricing_rates.json`）让 Agent 不用搜索工具也能定位；弱标识符（`data/file1.json`）逼它盲目加载。切分大文档时按语义边界（章节标题、段落）切，不按任意字符数切。

**消息历史。** 它是 Agent 追踪进度、维持任务状态、跨轮保留推理的草稿纸；长任务里会膨胀到主导上下文。周期性精炼：工具调用一旦发生在对话深处，原始结果很少需要逐字保留，用紧凑摘要或引用替换过期的工具输出。

**工具输出。** 在 Agent 轨迹里工具输出常常占据上下文大头。做**观察遮蔽**：Agent 处理完结果后，用紧凑引用替换冗长输出；只保留最近相关的文件内容，压缩或驱逐旧的。

## 上下文窗口与注意力机制

**注意力预算。** n 个 token 要算 n² 的两两关系。上下文变大，模型维持这些关系的能力下降——不是断崖，是坡度。主要在短序列上训练的模型缺少覆盖全上下文依赖的专用参数，形成远低于标称窗口的有效天花板。设计时假设有效容量明显低于广告数字，直到在目标负载上实测。

**位置编码外推**让模型处理超过训练长度的序列，但位置精度会下降：超长上下文的检索与长程推理准确率低于短输入。

**渐进式披露的三个层次：** 技能选择（启动只加载名字与描述，按需激活全文）；文档加载（先摘要，任务需要再取细节段）；工具结果保留（最近的完整保留，旧的压缩或驱逐）。边界要干脆：一旦激活就完整加载，部分加载会制造让推理变差的信息缺口。

## 质量 vs 数量

拒绝「更大的窗口解决记忆问题」的假设。处理成本随长度不成比例增长——不只是线性成本，超过有效容量后模型表现本身会下降；即便有前缀缓存，长输入仍然昂贵。

做**信号密度测试**：对每一块上下文问「删掉它，模型的输出会变吗？」不会就删。冗余内容不只浪费 token，还主动稀释对高信号内容的注意力。

## 实践指引

**推理一个上下文决策时**，把概念问题（这意味着什么、为什么重要）和操作问题（用哪种具体技术）分开。前者用本技能回答，后者路由到对应的专门技能。例如「要不要给长会话做摘要」：为什么需要（注意力预算有限、U 形曲线、信号密度）归本技能；用哪种压缩策略、在什么占用率触发归「上下文压缩」。

**新人阅读顺序：** 1) 本技能，内化注意力预算与 U 形曲线；2) 「上下文退化诊断」，看失效在实践中长什么样；3) 按项目最相关的操作关切挑两三个：压缩、工具设计、记忆系统。跳过第 1 步的人会不知其所以然地套技术；跳过操作技能的人会空谈。

## 示例：分段的系统提示词

```
<BACKGROUND_INFORMATION>
你是帮助一个开发团队的 Python 专家。
当前项目：Python 3.9+ 的数据处理流水线。
</BACKGROUND_INFORMATION>

<INSTRUCTIONS>
- 写干净、地道的 Python
- 函数签名带类型标注
- 公开函数带 docstring
- 遵循 PEP 8
</INSTRUCTIONS>

<OUTPUT_DESCRIPTION>
提供带语法高亮的代码块。
非显然的决策在注释里解释。
</OUTPUT_DESCRIPTION>
```

关键约束在注意力偏好的位置（开头与结尾），显式的段边界帮助模型解析。

## 准则

1. 把上下文当边际收益递减的有限资源
2. 关键信息放开头或结尾
3. 用渐进式披露推迟加载
4. 系统提示词分段清晰
5. 开发期间监控上下文用量
6. 在 70–80% 占用率设置压缩触发
7. 为退化而设计，而不是指望不退化
8. 宁要小而高信号，不要大而低信号

## 坑

1. **标称窗口 ≠ 有效容量。** 复杂检索或推理任务远未到上限就会退化；在自己的退化测试证明之前，预算低于标称值。
2. **按字符估 token 会悄悄漂移。** 英文散文约 4 字符/token 的经验在代码（2–3）、URL 与路径（每个斜杠、点、冒号都是独立 token）、非英语文本（常为 1–2）上失效。预算敏感的计算用厂商的真实分词器。
3. **工具 schema 序列化后膨胀 2–3 倍。** 十个中等 schema 的工具在第一条消息之前就可能吃掉 5000–8000 token。审计序列化后的 token 数，不是源码行数。
4. **消息历史在 Agent 循环里悄悄膨胀。** 每次工具调用把请求和完整响应都塞进历史；20–30 轮后可能占掉 70–80% 的窗口，而症状要到推理质量崩塌才可见。给历史设硬上限，主动触发压缩。
5. **中间的关键指令会丢。** 中段的回忆准确率比首尾低 10–40%。安全约束、输出格式、行为护栏永远不要放在长系统提示词的中间。
6. **过于急切的渐进式披露等于没披露。** 一沾边就加载所有「可能相关」的技能或文档，重演了上下文堆砌。激活阈值要严：任务明确匹配触发条件才加载，话题相邻不算。
7. **混用指令高度导致行为不一致。** 「永远恰好三个要点」这种极具体规则和「要有帮助」这种空泛指令混在一起会打架。按高度分组，每段内部保持一致。

## 参考

- [references/context-components.md](references/context-components.md)：各组件的技术参考——系统提示分段与高度示例、工具 schema 与描述工程、标识符设计与语义切块、历史摘要注入、响应格式选项与观察遮蔽、token 预算分配表、渐进式披露实现模式。
- 同系列技能：上下文退化诊断（context-degradation-zh）、上下文压缩（context-compression-zh）、工具设计（tool-design-zh）、记忆系统（memory-systems-zh）。

---
改编自 [Agent Skills for Context Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering) 的 `context-fundamentals`（MIT）。改动见 ATTRIBUTION.md。