Context Engineering

Prompt Engineering 关心「话怎么说」，Context Engineering 关心「给它看什么」。前者影响措辞，后者决定判断依据是否齐全。而在有成本约束的系统里，上下文还是一项必须做预算的资源——什么常驻、什么按需、什么必须压缩，这三件事构成效果与成本的分水岭。

编辑部注 · 本章是全站篇幅最长的一章，因为它同时影响效果上限与成本下限。建议读完后来回看两遍图 1。

一个被反复验证的现象：把提示词从「请仔细分析」改成更花哨的措辞，效果几乎不动；而把该给的数据补齐、把无关的噪音删掉，效果会明显变化。原因很朴素——模型只能基于看到的信息做判断，你不知道的信息它也不知道。

一、上下文的四种成分

把一次请求的上下文拆开，实际上只有四类内容。分清这四类，上下文工程（Context Engineering） 的 上下文预算（Context Budget） 该给谁就有答案了——而真实判断依据的占比，就是 信噪比（Signal-to-Noise Ratio）：

一个反直觉的观察：真正吃掉上下文的大头通常是「状态」而不是「知识」。检索来的资料一般几千 token，而十几轮之后的对话历史 + 工具返回结果可以轻松到几十万 token。

二、顺序会影响成本：前缀稳定性

在第 5 章（KV Cache）里我们已经知道了规则，这里给出它在 Harness 里的落地版排序原则——排序的核心目的之一是让 前缀缓存（Prefix Cache） 命中率最大化：

三、给知识加来源标注

检索到的内容如果不带来源，模型无从判断可信度，也无法在回答里给出可验证的引用。最小可行的做法是给每段知识打三个标签，也就是按 知识层级（Knowledge Tier） 标注它是事实、推断还是观点：

from dataclasses import dataclass
import json, time
@dataclass
class KnowledgeChunk:
    source: str          # 来源标识（可点开的链接或文件路径）
    updated_at: str      # 更新时间：模型据此判断时效
    tier: str            # fact（可溯源事实）| inference（推断）| opinion（观点）
    text: str
    score: float = 0.0   # 相关性得分，用于排序与截断
def render_knowledge(chunks: list[KnowledgeChunk], budget_chars: int = 6000) -> str:
    """
    按相关性排序、按预算截断，并且**每一条都带来源与层级**。
    来源不是装饰，它是模型判断「该不该相信」的依据。
    """
    if not chunks:
        return "（本次未检索到相关资料。若信息不足，请明确说明而不是猜测。）"
    ordered = sorted(chunks, key=lambda c: -c.score)
    lines, used = [], 0
    for c in ordered:
        block = (f"[{c.tier}] {c.text.strip()}\n"
                 f"    来源：{c.source}　更新时间：{c.updated_at}")
        if used + len(block) > budget_chars:
            break                      # 硬性截断，防单条超长资料挤爆预算
        lines.append(block)
        used += len(block)
    dropped = len(ordered) - len(lines)
    tail = f"\n（另有 {dropped} 条相关资料因预算限制未纳入。）" if dropped else ""
    return "\n\n".join(lines) + tail
def build_messages(
    instructions: str,
    tool_defs: list[dict],
    task: str,
    progress_summary: str,
    knowledge: list[KnowledgeChunk],
    new_input: str,
) -> list[dict]:
    """
    严格按「稳定度递减」排列，保证前缀缓存命中率最大化。
    注意：instructions 与 tool_defs 里绝对不能出现时间戳等动态内容。
    """
    stable_head = json.dumps(tool_defs, ensure_ascii=False, sort_keys=True)
    return [
        {"role": "system", "content": instructions},                     # ① 最稳定
        {"role": "system", "content": f"可用工具：\n{stable_head}"},      # ② 顺序固定
        {"role": "user", "content": f"任务目标：{task}"},                 # ④ 一轮内不变
        {"role": "user", "content": f"已完成步骤：\n{progress_summary}"},  # ⑤ 压缩后
        {"role": "user", "content": f"参考资料：\n{render_knowledge(knowledge)}"},  # ③/⑤
        {"role": "user", "content": new_input},                          # ⑥ 变化最频繁，放最后
    ]
def summarize_progress(steps: list[dict]) -> str:
    """
    阶段摘要必须结构化。自由文本摘要会越摘越糊。
    固定四段：目标 / 已完成 / 关键结论 / 待办
    """
    done = [s for s in steps if s.get("status") == "ok"]
    failed = [s for s in steps if s.get("status") not in ("ok", None)]
    return (
        f"· 已完成（{len(done)} 步）："
        + "；".join(f"{s['tool']}({s.get('brief','')})" for s in done[-8:])
        + f"\n· 失败/放弃（{len(failed)} 步）："
        + "；".join(f"{s['tool']}→{s.get('status')}" for s in failed[-5:])
        + "\n· 待办：见任务目标未覆盖的部分"
    )

四、什么时候该压缩：三个触发信号

不要等上下文满了才压——那时候往往已经来不及（压缩本身要花一次模型调用，而你已经没有余量了）。三个提前量信号对应三种策略：短任务用 滚动窗口（Rolling Window），中长任务用 阶段摘要（Phase Summary），长任务还要叠加 状态外置（State Externalization）；单条超长结果则做 头尾保留裁剪（Head-Tail Truncation）。这些都属于 压缩触发信号（Compression Trigger）：

五、常见误区与追问

5.1 误区：等上下文快满了再压缩也来得及

错在哪：把压缩当成一个不花成本的本地操作。为什么自然：压缩就是删内容，删东西怎么会来不及。判据：压缩本身要发起一次模型调用，而它要读的恰恰是那段已经很满的上下文——压缩的输入就是那个逼近上限的输入。数字：128k 窗口下，60% 触发时还有约 51k 余量，从容；90% 触发时只剩 12.8k，而摘要必须把 115k 读一遍，一旦按总长校验就直接失败。所以取值依据不是「还能塞多少」，而是「压缩动作本身要花掉多少」——按 60% 触发，并为摘要预留一次完整调用。

5.2 误区：窗口到 1M 了，上下文越长效果越好

错在哪：把「模型收得下」当成「模型用得上」。为什么自然：上下文越多，可用信息看起来越多，何况现在真有一百万的窗口。判据：效果变量是真实判断依据的占比，不是总长度——把十万 token 里真正被引用的那部分数出来，占比从约 18% 被稀释到 10% 时，任务从第 15 轮前后开始跑偏。可操作的验证：同一个任务跑两组，A 组带全量历史，B 组只带结构化结论摘要；如果完成率没有下降，说明你原来塞的那些过程性内容本来就没被用到——直接砍掉，既提效果又降成本。

5.3 误区：上下文治理的重点是「知识」，所以先去优化检索

错在哪：把注意力放在检索片段上，放过了真正的大头。为什么自然：检索结果看起来才是「内容」，历史消息只是聊天记录，不像能吃预算的东西。判据：先量再说，按四类成分逐个数 token 占比。典型分布是：一次检索 3–8k token，而十几轮之后的历史消息加工具返回值可以到 20 万 token 量级，指令与工具定义合计往往不到 10%。所以第一刀应该砍向状态：中间产物外置、历史压成结构化摘要、单条超长结果做头尾保留裁剪——先优化检索是小马拉大车。

5.4 误区：压缩就是把内容变短

错在哪：把压缩当成一次自由发挥的改写。为什么自然：摘要嘛，写短一点就算完成了任务。判据：自由文本摘要会「越摘越糊」——每压一次丢一部分细节，压上三次往往连任务目标都变形了。正确做法是让摘要结构化，固定四段：目标 / 已完成 / 关键结论 / 待办；并且必须保留可回查的指针（文件路径、轮次号、来源链接），需要细节时能按指针回读。判据：压完之后拿摘要做一次「无原历史」的任务续跑，如果模型还能说清任务目标与已完成的步骤，这次压缩合格；如果说不出，说明它压掉的不是过程而是结论。

5.5 误区：状态外置就是把中间产物写进文件

错在哪：只做了「写文件」，没做「让模型知道文件在哪、要不要读」。为什么自然：外置听起来就是找个地方存起来。判据：外置的验收标准有两条——上下文里只剩指针，且指针是可读、可发现的。文件名如果叫 tmp_001.json，模型既不知道里面是什么，也没理由去读，等于没外置；叫 orders-2025-删除影响分析.md，模型看一眼就知道该不该打开。数字：20 万 token 的中间产物外置之后，上下文里应该只剩一份三五行的目录清单（约 200 token）。

5.6 误区：标了来源就不会有引用幻觉

错在哪：把「给了判断依据」当成「已经校验过」。为什么自然：每条知识都带了来源与层级，看起来已经足够严谨。判据：来源只让幻觉变得可被发现，并不阻止它发生——模型完全可能标注一个证据清单里根本不存在的来源，或者把 opinion 层的内容当成 fact 用。所以要补一步后置校验：生成完成后，把回答里每一条引用回查一遍，看它在证据清单里是否真实存在、层级有没有被升格；对不上就降级或删掉引用。判据：随机抽 20 条带引用的回答逐条点开核对，如果存在对不上的编号，说明你的引用体系目前只是装饰。

六、自测

七、小结

效果上限不是由提示词的精妙程度决定的，而是由「该给的信息有没有给、不该给的噪音有没有删」决定的。本刊编辑部

下一章处理一个更长期的问题：如果这些信息不该每一轮都重新塞进去，那该存在哪里、什么时候取出来。

八、参考与延伸

这一层的实践材料比理论多。下面按「先看原则、再看机制、最后看极端案例」排好。全站不做原文转载，这里只登记链接与「为什么值得读」。

先看原则（该给什么、不该给什么）

• Anthropic · Effective Context Engineering for AI Agents —— 把上下文工程从「提示词怎么写」里彻底拆出来，讲成一件「在有限的注意力预算下做取舍」的事，并且明确说上下文会「腐烂」（信息还在，但已经不该信了）。本章第一节的四类成分与它是同一件事的两种表述；如果你要给自己的项目定一份预算比例，先看它给的原则再看自己的数。
• Anthropic · Prompt Engineering Overview —— 与上一份对着读：哪些属于措辞问题、哪些属于信息供给问题。如果你的团队还在用「优化提示词」去解决「该给的信息没给」的问题，把这一页发给对方，比争论有用。

再看机制（前缀到底怎么被复用）

• vLLM · Automatic Prefix Caching —— 服务端视角的前缀复用：以块为单位做哈希命中，能命中多少取决于前缀里有多少个完整块逐字节相同。本章第二节说「把变化频率当排序键」，这里能让你看到它背后的匹配粒度——为什么首部改一个字符不是「慢一点」，而是整段作废。
• vLLM 博客：用 PagedAttention 把大模型服务做到又快又省 —— 重点看显存碎片与块管理那几张图。理解「前缀会被淘汰」之后，你就不会把「又长又稳定」当成缓存友好的默认答案：长前缀反而更容易在并发压力下被换出。

最后看极端案例（长上下文到底能干什么）

• Efficient Memory Management for Large Language Model Serving with PagedAttention（arXiv:2309.06180） —— 只读它的 KV 块管理一节即可。它解释了一个反直觉现象的成因：为什么你在应用层把前缀写得再稳定，命中率依然不完全由你决定——调度与淘汰也在你之外发生。