前置课 · 第二部分 Agent · A5

上下文工程：每一轮让模型看到什么

20 min · prompt 工程的升级版——管理的不是一段话，是整个信息流和 token 账单

🎒 预备知识：完成上一课「A4 工具设计」（零基础入口：第 0 课）

本课唯一结论：模型每轮看到的只是一串 token 序列，而这份序列要花真金白银、有硬性预算。上下文工程就是管这份账的学问，四原则：预算有限、稳定前缀、渐进披露、蒸馏不搬运。

一、一张真实的 token 账单（工作示例）

假设你做一个有 30 个工具、10 轮历史的客服 agent，128K 窗口，每轮账单长这样：

system prompt（人格+规则）              800 token   常驻
30 个工具的 schema                    4500 token   常驻 ← 大头！
10 轮历史（含工具结果）              20000 token   随轮增长 ← 更大的头！
本轮注入（用户信息/检索结果）         1500 token   可变
─────────────────────────────────────────────
合计 ≈ 26800 token / 每轮全价重算（若无缓存）

三个立刻能看出的动作点：工具太多该瘦身（A2 的按需加载）；历史要压缩（A6）；注入内容要蒸馏（本课第四节）。上下文工程的第一步永远是先记账—— 大多数"模型变笨了"的真相是窗口被垃圾挤满。

二、原则②稳定前缀：prompt cache 的钱在哪省

provider 按前缀匹配缓存：开头完全一致的部分命中缓存，价格约为原价的 1/10，且时延更低。推论：

✗ system = "你是助手。当前时间：14:32:05。用户ID：8817。"   # 每秒都变 → 缓存全废
✓ system = "你是助手。"（稳定） + "当前时间：14:32:05。"（放在消息末尾的可变区）

OpenClaw 源码里有一行注释把这件事写成了军规："Approval UI and owner identity vary by turn, so keep both below the stable prefix"（system-prompt.ts:1146）——可变内容必须排在稳定边界之后。经典事故：往 system prompt 顶部塞时间戳/请求 ID/随机欢迎语，团队账单翻十倍还没人知道为什么。

三、原则③渐进披露：三级加载

级	什么时候进上下文	Easel 实例
索引常驻	每轮都在	114 个技能的 frontmatter（name+description 一行）
触发加载	模型选定后才进	SKILL.md 正文（<200 行）
执行中读取	跑流程时按需读，甚至不进 prompt	references/ 按引用读；scripts 永不进 prompt 只被执行

这是把 L1 的"窗口稀缺"变成体系的设计——token 只为正在做的事付费。你自己做 agent 时最少要分出前两级：能力索引常驻，能力本体按需。

四、原则④蒸馏不搬运：指针思维

新手最常见的浪费：工具返回 3000 字原文直接进上下文、检索结果整段塞入、上游产物全文转发。蒸馏不搬运要求传摘要 + 指针：

✗ "以下是竞品分析全文：……（3000 字）"
✓ "竞品分析已完成，结论：价格带 199-299 缺位（详见 outputs/竞品/analysis.md）"

模型需要细节时自己按指针去读——这就是 agentic 检索（A8）。 Easel 的 manifest 是这个原则的制度化：跨层只传"产物路径 + 一句结论"，禁止整块转发（正课 L03）。

五、常见踩坑

坑 1：system prompt 塞动态内容毁缓存（见上，账单级事故）。

坑 2：历史无限增长。没有压缩机制的长会话，第 20 轮起每轮都为前 19 轮全价买单，且窗口溢出直接报错。压缩策略要在第一天就设计（A6）。

坑 3：什么都进 system。只有"每一轮都需要的规则"才配常驻；偶尔需要的知识放检索，特定任务需要的放技能正文。判断标准：这条信息被用到的频率。

六、检索练习

七、出口检验

为一个"代码评审 agent"做上下文工程，交三样东西： ① token 账单（system ≤500、工具索引、历史策略、本轮注入各多少预算）； ② 哪些内容必须排在稳定前缀、哪些放可变区； ③ 检索到 3000 字的相关代码时，进上下文的应该是什么。发到对话里我批改。

一手源：Anthropic · Effective context engineering for AI agents。