上下文工程的本质：为什么上下文是新的代码

第 1 章：上下文工程的本质：为什么上下文是新的代码

Chapter 1: The Essence of Context Engineering — Why Context Is the New Code

在 2025 年的最后一个季度，frontier model 的 benchmark 呈现出一个悖论式的图景：GPT-5、Claude 4 Opus、Gemini 2.5 Pro，以及国内头部大模型在 MMLU、GPQA、HumanEval 上的得分差异已经收敛到 3–5 个百分点。曾经支撑「换模型」决策的能力鸿沟，正在变成统计噪声。

In the closing quarter of 2025, frontier model benchmarks paint a paradoxical picture: GPT-5, Claude 4 Opus, Gemini 2.5 Pro, and the leading domestic large models cluster within 3–5 percentage points on MMLU, GPQA, and HumanEval. The capability chasm that once justified switching APIs has collapsed into statistical noise.

然而，well-engineered AI system 与 poorly-engineered AI system 之间的鸿沟，却比任何时候都宽。这个鸿沟不再由 model weights 决定，而由 context 决定。

Yet the chasm between a well-engineered AI system and a poorly-engineered one has never been wider. This chasm is no longer decided by model weights — it is decided by context.

你在哪个位置放置一个事实、以什么顺序排列、在哪条 instruction 之后、用什么 tone 包裹——这些决定正在塑造你的 AI system 是 hallucinate、confabulate，还是 reason。它们决定了一个 200,000 token 的 context window 究竟会交付 5 页有用信号，还是 200,000 token 的昂贵噪声。

Where you place a fact, in what order, after which instruction, wrapped in what tone — these decisions now shape whether your AI system hallucinates, confabulates, or reasons. They determine whether a 200,000-token context window delivers five useful pages of signal or 200,000 tokens of expensive noise.

这是本书的起点：context 已经从 input field 升级为一等工程对象。

This is the starting point of this book: context has graduated from an input field to a first-class engineering object.

过去十年，我们习惯了「prompt 是字符串」的范式：把一个精心设计的 instruction 放进 input box，得到一个 output。这种范式假设 context 是静态的、一次性的、被丢弃的。当 context window 从 4K 扩展到 200K、1M、10M，当 model 从单轮对话转向 multi-turn agent，当一次推理可能跨越 hours of conversation 与 thousands of documents，context 不再是字符串——它是一整套 runtime environment。

For the past decade we lived under the "prompt is a string" paradigm: drop a carefully crafted instruction into an input box, receive an output. That paradigm assumes context is static, one-shot, disposable. As context windows expand from 4K to 200K, 1M, 10M, as models shift from single-turn dialogue to multi-turn agents, as a single inference may span hours of conversation and thousands of documents, context is no longer a string — it is an entire runtime environment.

理解这个转变，是构建 long-memory AI system 的第一步。本章将建立四个支点：(1) 上下文的四维定义；(2) 上下文是模型的运行时操作系统；(3) Prompt、上下文、记忆、状态的层次关系；(4) 长度 ≠ 质量——effective context 的概念。最后给出一个最小可运行的 Python 骨架与一份 10 条上下文健康度检查清单。

Understanding this shift is the first step toward building long-memory AI systems. This chapter establishes four pillars: (1) the four-dimensional definition of context; (2) context as the model's runtime operating system; (3) the layered relationship among prompt, context, memory, and state; (4) length ≠ quality — the concept of effective context. We close with a minimal Python skeleton and a 10-item context-health checklist.

---

1.1 上下文的四维定义：从「输入」到「四元结构」

1.1 The Four-Dimensional Definition: From "Input" to a "Quadripartite Structure"

工业界对 context 的理解，长期停留在「输入 token 的集合」这个粗粒度定义上。这一定义在 2020 年之前是有效的：模型只支持 4K context，prompt engineering 的核心议题就是「如何在 4K 内塞进所有必要信息」。但当 context 容量跨越三个数量级之后，这种粗粒度定义迅速崩塌。

The industry's understanding of context has long been stuck at the coarse-grained definition of "the set of input tokens." That definition held before 2020: models supported only 4K context, and the central concern of prompt engineering was "how to fit all necessary information within 4K." Once context capacity crossed three orders of magnitude, this coarse definition collapsed.

我们需要更细的颗粒度。本书提出 context 的 四维定义 (quadripartite definition)，按 生命周期 (lifecycle) 与 变更频率 (mutation frequency) 两个正交轴展开：

We need finer granularity. This book proposes a quadripartite definition of context, organized along two orthogonal axes: lifecycle and mutation frequency.

| 维度 / Dimension | 核心问题 / Core Question | 典型内容 / Typical Content | 生命周期 / Lifecycle | |---|---|---|---| | 任务上下文 (Task Context) | 模型要做什么？/ What should the model do? | 指令、约束、输出格式、评估标准 / Instructions, constraints, output format, evaluation criteria | 单次推理 / Single inference | | 领域上下文 (Domain Context) | 模型工作的世界长什么样？/ What does the world look like? | 知识库、规范、API schema、术语表 / Knowledge bases, regulations, API schemas, glossaries | 长期稳定 / Long-term stable | | 状态上下文 (State Context) | 当前推理处在什么状态？/ What state is the inference in? | 对话历史、工具调用栈、中间结果 / Dialogue history, tool-call stack, intermediate results | 会话级别 / Session-level | | 记忆上下文 (Memory Context) | 模型过去学到了什么？/ What has the model learned before? | 用户偏好、跨会话经验、关键决策 / User preferences, cross-session experience, key decisions | 跨会话持久 / Cross-session persistent |

下面我们逐维展开，并指出每一维在工程实践中常见的反模式。

We expand each dimension below and surface the common anti-patterns in engineering practice.

1.1.1 任务上下文 (Task Context)：一次推理的「指令系统」

1.1.1 Task Context: The "Instruction System" of a Single Inference

任务上下文回答的是「此刻，模型要做什么」这个问题。它包含三个层次：

Task context answers "what is the model supposed to do at this moment." It contains three layers:

1. 目标层 (Goal Layer)：用户或上游 agent 提出的具体诉求。例如：「请将以下对话翻译成商务英语，并保持原语气」。 Goal Layer: the specific demand from the user or upstream agent. Example: "Translate the following dialogue into business English while preserving the original tone."

2. 约束层 (Constraint Layer)：限制模型输出空间的规则。例如：「不超过 200 字」「使用第一人称」「避免出现公司名」。 Constraint Layer: rules bounding the model's output space. Example: "No more than 200 words," "use first person," "avoid mentioning the company name."

3. 评估层 (Evaluation Layer)：定义输出质量的隐含或显式标准。例如：「流畅度优先于字面忠实度」「保留专业术语的英文原文」。 Evaluation Layer: implicit or explicit criteria for output quality. Example: "Fluency takes priority over literal fidelity," "preserve original English terms for technical jargon."

任务上下文的最大特征是 短生命周期 (short lifecycle)：它服务于一次具体的推理调用，调用结束即被丢弃。但它的设计质量直接决定模型在这一刻的表现。一个常被忽视的细节是：评估层往往比目标层更难写。多数工程师只能写出「做什么」，写不出「做到什么程度算好」。

Task context's defining feature is its short lifecycle: it serves a single inference call and is discarded afterward. Yet its design quality directly determines the model's performance at that moment. A frequently overlooked detail is that the evaluation layer is harder to write than the goal layer. Most engineers can specify *what* the model should do, but struggle to specify *how well* is "well enough."

一个常见错误是把领域知识塞进任务上下文：

A common mistake is stuffing domain knowledge into task context:

```python

反例：领域知识污染任务上下文

Anti-pattern: domain knowledge polluting task context

task_prompt = """ 你是一位资深心血管医生，拥有 30 年临床经验，熟悉 ACC/AHA 指南... [此处 2000 字领域知识] 现在请回答：患者主诉胸痛，应该如何诊断？ """

改进：分层管理

Improvement: layer the responsibilities

domain_context = load_clinical_guidelines("ACC/AHA-2024") task_context = "患者主诉胸痛，请给出鉴别诊断。" final_prompt = compose(domain_context, task_context) ```

这种写法的问题在于 任务上下文与领域上下文的边界被破坏。任务上下文应保持「指令清晰、约束明确」，领域知识应放在独立的领域上下文中管理。这与软件工程中的「单一职责原则 (SRP)」如出一辙。

The problem with the anti-pattern is that the boundary between task context and domain context is broken. Task context should remain "instructions clear, constraints explicit"; domain knowledge belongs in the independent domain context slot. This mirrors software engineering's Single Responsibility Principle (SRP).

1.1.2 领域上下文 (Domain Context)：模型工作的「世界模型」

1.1.2 Domain Context: The "World Model" Within Which the Model Operates

领域上下文回答的是「模型工作的世界长什么样」这个问题。它包括三类内容：

Domain context answers "what does the world look like in which the model operates." It contains three categories:

• **静态知识 (Static Knowledge)**：术语表、规范手册、API 文档、合规要求——这些更新频率低，可走 git-ops 流程；

Static Knowledge: glossaries, specification manuals, API documentation, compliance requirements — these update infrequently and can ride a git-ops pipeline;

• **动态知识 (Dynamic Knowledge)**：实时行情、新闻流、传感器数据——通常以 retrieval 方式按需注入；

Dynamic Knowledge: real-time quotes, news feeds, sensor data — typically injected on demand via retr