上下文工程：概念与落地实践
本文整理 Context Engineering（上下文工程） 的核心观念与可执行做法，主要依据 Anthropic 工程博客 Effective context engineering for AI agents（2025-09），并结合本仓库已有模式做对照说明。目标读者：在构建多轮 Agent、工具链或长任务自动化时，需要系统管理「模型每一轮能看到什么」的工程师。
1. 上下文工程在讲什么
1.1 定义
- 上下文（Context）：某次推理时，实际进入大语言模型、参与采样的全部 token 集合（系统提示、工具定义、MCP、外部检索结果、消息历史、中间产物等）。
- 上下文工程 ：在约束与目标 之下，持续遴选、裁剪、更新 这些 token，使模型在多轮、长时域 任务上稳定产出期望行为。它不是一次性「写好 prompt」，而是每次调用前都要做的策展（curation）。
1.2 与 Prompt 工程的关系
| 维度 | Prompt 工程 | 上下文工程 |
|---|---|---|
| 焦点 | 指令怎么写、怎么分段、示例怎么放 | 整盘状态：本轮该放进哪些信息、历史怎么处理、工具返回怎么截断 |
| 典型场景 | 单次分类、单轮生成 | Agent 循环、多工具、长对话、跨会话任务 |
| 迭代单位 | 改 system prompt / few-shot | 改「进窗策略」：检索、摘要、外部笔记、子 Agent 边界 |
可以把它理解为：Prompt 工程是上下文工程的一个子集；Agent 时代的主战场在「整窗管理」。
1.3 为什么必须认真对待
- Context rot（上下文衰减） ：窗口变长后，模型对其中细节的准确回忆与利用会下降；并非无限堆字就能变强。
- 注意力预算 ：上下文在工程上应视为有限资源；新 token 会稀释对其它部分的有效「注意力」。
- Agent 循环产数据：每轮工具输出、中间推理都会膨胀「可能相关」的信息；若不治理，噪声会淹没信号。
原则（原文精神） ：在可接受的行为目标下，追求 尽可能小、但信号足够强 的 token 集合。
2. 上下文的组成部分与做法要点
2.1 系统提示（System prompt）
- 高度（altitude）：避免两端------一端是把复杂 if-else 业务规则全写进提示（脆弱、难维护）；另一端是过于空泛、默认模型「已经懂你的业务」。
- 结构：用 Markdown 标题或 XML 风格分段（如背景、指令、工具说明、输出格式）帮助模型解析；格式本身不如「信息是否必要且清晰」重要。
- 起步方式 ：用当前最强模型先试最小可用提示 ，再针对失败模式增量补规则与示例，而不是一上来堆砌边角案例。
2.2 工具（Tools）
- 工具是 Agent 与环境的契约 ；设计目标包括：返回尽量省 token 、语义不重叠 、失败可恢复。
- 反模式：工具过多或边界模糊------若人类工程师无法明确说清「此情此景用哪个工具」，不能指望模型更稳。
- 实践 ：维护 MVP 工具集，随任务演化再扩展；工具描述与参数名应对模型友好（自解释、歧义少）。
2.3 示例（Few-shot）
- 继续推荐 少量、多样、能代表期望行为 的范例。
- 不推荐 ：把无数 edge case 规则塞进 prompt；应提炼成典型范式，其余交给运行时检索或工具。
2.4 消息历史与其它动态信息
- 默认假设：历史越长，策展越重要。
- 对工具结果：深历史里的原始大段输出，往往可以清除或替换为摘要（轻量 compaction 的一种），只要不影响当前决策所需事实。
3. 运行时检索：从「预灌全文」到 Just-in-time
3.1 思路
- Embedding 预检索 仍常见；更 Agent 化的做法是保留 轻量引用（路径、URL、查询 ID、片段定位），需要时再用工具拉取。
- 类比人类：不背整本书，而是用目录、书签、索引 按需加载。
- 渐进披露（progressive disclosure）：通过探索（列表、预览、head/tail）逐步缩小相关子集，避免一次性把大对象塞进上下文。
3.2 混合策略
- 一部分 关键材料 upfront（如项目里的
AGENTS.md/CLAUDE.md类说明）；一部分 靠 grep/glob/读文件 即时 拉取。 - 边界取决于任务：静态域可多读一点；高动态或大体量数据域更依赖 JIT + 强工具习惯。
4. 长时域任务的三类技术
当 token 规模持续超过「舒适区」时，原文归纳三类手段（可组合）：
| 手段 | 作用 | 适用直觉 |
|---|---|---|
| Compaction（压缩） | 将临近上限的对话/轨迹 摘要 后开启新窗口，丢掉冗余工具输出等 | 需要保持对话连贯、长链工具调用 |
| 结构化笔记 / 外部记忆 | 把进度、决策、依赖写入 上下文外 持久存储，需要再读回 | 里程碑清晰、跨多会话 |
| 子 Agent 架构 | 子任务在干净子窗口 深挖，主 Agent 只收 浓缩摘要（如 1k--2k tokens） | 复杂检索/研究、可并行探索 |
Compaction 注意 ：过度激进会丢掉「当时看起来次要、后来才关键」的细节；实现上可先偏 召回 ，再迭代 精度（删冗余）。
5. 落地实践清单（可直接当评审表）
5.1 设计阶段
- 是否明确列出「必须始终在窗内 」与「仅按需加载」的信息类？
- 系统提示是否达到合适 高度（不过度硬编码、不过度模糊）？
- 工具集是否为 最小可用 且 无职责重叠？
- few-shot 是否为 canonical 集合，而非规则大全？
5.2 运行阶段
- 工具返回是否有 默认截断/结构化摘要（尤其列表、大 JSON、长网页）？
- 多轮后是否有 清除旧工具原始输出 或 滚动摘要 的策略？
- 是否用 引用 + 工具 代替「把整库贴进 prompt」？
- 长任务是否具备 Compaction / 笔记 / 子 Agent 中至少一种预案？
5.3 观测与迭代
- 能否从日志中看到「每轮进窗 token 量级」与主要来源（历史 / 工具 / RAG）？
- 失败案例是否先区分：指令问题 vs 上下文噪声/缺失 vs 工具契约问题？
6. 延伸阅读
- Anthropic：Effective context engineering for AI agents
- 同系列：Building effective AI agents（工作流 vs Agent 等定义）
- 平台能力：Claude Developer Platform 上的 Memory / context management 与 tool result clearing 等特性（原文有提及，具体以官方文档为准）。
7. 一句话备忘
上下文工程 = 把上下文当作有限注意力预算，在每一轮推理前做高信号、小体积的策展； 与 Prompt 工程并行，是构建可靠 Agent 的基础能力。