上下文工程入门¶

这篇先不讲源码，也不讲复杂架构。

先记住一句话：

上下文工程，就是让 Agent 在合适的时候看到合适的信息。

先用一个例子理解¶

假设你让一个 Agent 帮你改代码。

它要做好这件事，不能只看你一句“帮我修一下 bug”。

它还需要知道：

你在哪个项目里。
你想修哪个问题。
当前打开了哪个文件。
哪段代码被你选中了。
项目有什么编码规范。
能不能改文件。
能不能联网查资料。
改完后要不要跑测试。
之前有没有做过相关决定。

这些信息加起来，就是 Agent 的“上下文”。

上下文工程，就是设计这些信息怎么被收集、整理、筛选、注入给模型。

Prompt 不是全部¶

很多人一开始会以为：

Agent 效果好不好，主要看提示词写得好不好。

提示词当然重要，但 Agent 产品里更关键的是：

哪些信息默认给模型？
哪些信息按需再查？
哪些信息太旧了要压缩？
哪些信息只是参考，不能当命令？
哪些行为必须受权限控制？

所以，提示词工程像是“怎么说一句话”。

上下文工程更像是“怎么布置整个工作现场”。

三类最重要的上下文¶

刚开始可以先只记三类。

1. 任务上下文¶

告诉 Agent 现在要做什么。

例如：

用户的当前请求。
当前任务进度。
下一步要做什么。
哪些事情还没完成。

2. 资料上下文¶

告诉 Agent 可以参考什么。

例如：

文件内容。
搜索结果。
代码片段。
文档。
历史对话记录。
记忆和知识库。

3. 规则上下文¶

告诉 Agent 应该怎么做、什么不能做。

例如：

代码规范。
输出格式。
权限限制。
安全要求。
团队约定。
当前渠道的回复方式。

如果一个 Agent 经常乱答、乱改、忘记任务，大概率就是这三类上下文没有管理好。

动态 Prompt 是什么¶

动态 prompt 可以先理解成：

产品在运行时临时贴给模型的“便签”。

比如：

用户在 IDE 里选中了代码，产品就贴一张便签：“这是当前选区”。
当前不能联网，产品就贴一张便签：“不要尝试访问外部网络”。
上下文快满了，产品就贴一张便签：“请总结当前进度，方便之后继续”。
当前是语音聊天，产品就贴一张便签：“只返回适合朗读的短句”。

这些便签不是用户手写的，而是产品根据运行状态自动注入的。

这就是运行时上下文工程。

它发生在 API 和 Transformer 之间¶

前面学过 LLM API 后，可以这样看上下文工程：

用户请求
  ↓
HTTP JSON
  ↓
上下文工程：选信息、排顺序、加规则、加工具 schema、压缩历史
  ↓
prompt / chat template
  ↓
tokenizer
  ↓
Transformer

也就是说，上下文工程不是 Transformer 内部结构。

它更像是服务端在调用模型前做的一层组织工作：

哪些 message 放进请求。
system、developer、user、tool 如何分层。
检索结果放前面还是后面。
工具说明怎么写进 tools 或 prompt。
历史对话是保留原文还是压缩。
哪些稳定前缀要保持不变，方便 prefix cache 命中。

一个 Agent 产品大概怎么工作¶

可以先用这条简单流程理解：

用户请求
  ↓
收集上下文
  ↓
筛选重要信息
  ↓
注入提示词和资料
  ↓
模型思考并调用工具
  ↓
记录结果和进度
  ↓
必要时压缩或写入记忆

上下文工程贯穿整条链路。

它不是某个单独功能，而是 Agent 产品的底层组织方式。

Codex / Claude Code / OpenClaw 怎么看¶

先不要看源码，先看它们各自解决什么上下文问题。

Codex¶

Codex 主要面对代码仓库。

它关心：

当前工作目录。
项目规则。
文件内容。
终端命令结果。
是否能改文件。
是否要申请权限。
修改后如何验证。

所以 Codex 的上下文工程偏“代码任务现场”。

Claude Code¶

Claude Code 也主要面对代码任务。

它特别强调：

CLAUDE.md 里的项目说明。
自动记忆。
上下文窗口。
压缩。
子 agent 隔离大任务。

所以它很重视“长期代码会话怎么不断片”。

OpenClaw¶

OpenClaw 更像常驻个人助手。

它关心：

消息来自哪个聊天软件。
是群聊还是私聊。
是否是语音。
是否是定时唤醒。
要不要查记忆。
要不要路由给另一个 agent。

所以 OpenClaw 的上下文工程偏“多渠道、长期在线、跨任务”。

学习路线¶

建议按这个顺序学：

先理解：上下文就是 Agent 工作时能看到的信息。
再理解：上下文分为任务、资料、规则。
再理解：动态 prompt 是产品运行时贴给模型的便签。
再看：Codex、Claude Code、OpenClaw 分别在管理哪些上下文。
最后才看源码里的 prompt 清单。

源码清单是工具书，不是第一课。

下一步¶

读完这篇后，再看：什么是上下文工程。

那篇会进入更完整的定义、产品机制和 Java 设计。

如果你想继续理解上下文工程如何变成完整 Agent 产品，读：Harness Engineering：把模型变成可用 Agent 的工程。

如果你想理解 Agent 为什么会一轮轮调用工具，以及如何停止，读：Loop Engineering：Agent 循环、停止条件与恢复。

如果你还没读 API 链路，建议先补：LLM API：从 HTTP 到 Transformer。