Context Engineering上下文工程的5W1H

本文缘起

6.25 Karpathy转发Shopify CEO的一条推文表达对"Context engineering"重要性的强调，7.19 Manus Peak发布一篇构建Agent Context engineering的经验分享文章，CE开始替代PE，成为每个能够处理好复杂任务的Agent必备的技术。

无论Manus的工程经验是否能在每个Agent产品中复用，但Karpathy的观点足够引起我的重视，毕竟他是少见的在x上不吹逼说实话又有前瞻性的人。

什么是CE

context中文称为“上下文”，不止用户发送给模型的内容，而是指模型生成输出前接收的所有内容。上图是目前公认的context范围，以下逐一表述：

• Instructions / System Prompt（指令或系统提示词）：定义模型在对话期间行为的初始指令集，包括示例和规则（examples and rules）
• User Prompt（用户提示词）：用户输入的即时任务或问题
• State / History (short-term Memory)（状态/历史 短期记忆）：当前对话，此刻之前的用户和模型响应
• Long-term Memory（长期记忆）：长期知识库，从此前的许多对话中收集，包含学习到的用户偏好、历史项目的摘要或被告知要记住以备将来使用的事实
• Retrieced Information（检索信息）：外部最新知识，来自文档、数据库或 API 的相关信息，以回答特定问题
• Available Tools（可用工具）：可以调用的所有函数或内置工具的定义（例如 check_inventory, send_email）
• Structured Output（结构化输出）：模型响应格式的定义，如JSON对象

CE和PE的区别

CE代表了传统PE的范式转变。CE是一个系统，而不是一个静态的提示词模版，是在调用LLM之前的系统性的输出。

PE

• 专注于巧妙和特定的措辞
• 仅限于表达任务诉求
• 像给别人的一张便利贴

CE

• 提供全面背景信息的完整系统
• 包括文档、示例、规则、模式和验证
• 像写一个包含所有细节的完整剧本

CE有什么作用

之前为提升 Agent 输出效果，主要focus在提升输出方式的路径上，例如ReAct框架，但CE强调除了关注如何响应，收集LLM完全实现其目标所需的信息也非常重要，然后才调用LLM。

如果Agent是一个厨师，炒菜过程的火候和调料顺序重要，但炒菜前的食谱、原料准备也很重要。

CE使得关注点不再focus在更智能的模型和更聪明的算法上，而是关注在为目标任务提供更准确的上下文上。

• 减少 AI 错误：大多数 Agent 错误不是模型错误，而是上下文错误
• 确保一致性：AI 能循环你的项目模式和规则惯例
• 实现复杂功能：AI 在合适的上下文中可以处理多步骤任务
• 自我纠正：验证循环允许 AI 修复自己的错误

如何使用CE

构建CE包含哪些方面——完整的CE应该在建设时check：

• 设计和管理prompt chains
• 调整指令或系统提示词
• 管理提示词的动态元素，例如用户输入、日期或时间等
• 搜索和准备相关知识，例如RAG
• 增强查询 query augmentation
• 在构建Agent系统时进行工具定义与说明
• 准备和优化少样本提示 few-shot demonstrations
• 构建输入和输出，例如分隔符 JSON模式
• 短期记忆（例如管理状态/历史上下文）和长期记忆（例如从向量存储中检索相关知识）
• 许多其他有助于优化LLM系统提示词以实现所需任务的技巧

以下用n8n构建的Agent为例，阐述CE的内容。

系统提示词，在System prompt里需要明确提供哪些上下文能有效地执行任务，把待解决的问题拆分成核心组件，这不仅是一个简单的提示和指令，输出system prompt的过程需要实验并为模型提供重要的上下文，以最佳方式执行任务。

-- Instructions用于准确提示System要做什么
-- 有助于模型理解用户输入是什么以及希望system输出什么内容
-- <user_query> What's the latest dev news from OpenAI? </user_query>
You are an expert research planner. Your task is to break down a complex research query (delimited by <user_query></user_query>) into specific search subtasks, each focusing on a different aspect or source type.
--调用工具
The current date and time is: {{ $now.toISO() }}
--结构化输入
For each subtask, provide:
1. A unique string ID for the subtask (e.g., 'subtask_1', 'news_update')
2. A specific search query that focuses on one aspect of the main query
3. The source type to search (web, news, academic, specialized)
4. Time period relevance (today, last week, recent, past_year, all_time)
5. Domain focus if applicable (technology, science, health, etc.)
6. Priority level (1-highest to 5-lowest)
        
All fields (id, query, source_type, time_period, domain_focus, priority) are required for each subtask, except time_period and domain_focus which can be null if not applicable.
        
Create 2 subtasks that together will provide comprehensive coverage of the topic. Focus on different aspects, perspectives, or sources of information.
--结构化输出
Each substask will include the following information:

id: str
query: str
source_type: str  # e.g., "web", "news", "academic", "specialized"
time_period: Optional[str] = None  # e.g., "today", "last week", "recent", "past_year", "all_time"
domain_focus: Optional[str] = None  # e.g., "technology", "science", "health"
priority: int  # 1 (highest) to 5 (lowest)

After obtaining the above subtasks information, you will add two extra fields. Those correspond to start_date and end_date. Infer this information given the current date and the time_period selected. start_date and end_date should use the format as in the example below:

"start_date": "2024-06-03T06:00:00.000Z",
"end_date": "2024-06-11T05:59:59.999Z",

CE最佳实践

以互联网上现有的工程实践和学术研究为例，阐述CE的实现重难点以及通过什么技术手段解决Agent的什么问题。

重难点

Context engineering的核心在于巧妙地组织和呈现信息给AI Agent，以引导其行为和决策，区别于Prompt engineering，通过“对话”和“示例”来塑造AI的“思维过程”。虽然潜力巨大，但绝非易事。

• 缓慢的反馈循环 (Slow Feedback Loop)： 传统的模型微调需要数周时间，对于快速发展的应用而言不够高效。虽然上下文工程本身加快了迭代，但如何高效地找到最优的上下文策略仍然是一个“随机研究生下降”（Stochastic Gradient Descent，即试错）的过程。
• 上下文长度限制与成本 (Context Length Limitations & Cost)：
• 观察结果可能非常庞大： 特别是当代理处理网页或PDF等非结构化数据时，很容易超出模型的上下文窗口限制。
• 模型性能下降： 即使模型技术上支持很大的上下文窗口，但其性能往往会在超过一定长度后下降。
• 长输入成本高昂： 即使启用了前缀缓存，传输和预填充每个token的成本依然很高。
• KV缓存失效 (KV-cache Invalidation)： 大模型在处理输入时会利用KV缓存来加速，但上下文中的微小变化（哪怕是一个token的差异）都会导致缓存失效，从而显著增加延迟和成本。
• 动作空间管理 (Action Space Management)： 随着代理能力增强，可用的工具（动作空间）会爆炸式增长。动态地添加或移除工具会带来两个问题：
• 缓存失效： 工具定义通常在上下文的前部，任何更改都会使后续所有动作和观察的KV缓存失效。
• 模型困惑： 当模型引用了当前上下文中不再定义的工具时，会导致“模式违规或幻觉动作”。
• 模型注意力分散 (Model Attention Drift)： 在复杂的多步骤任务中（如Manus平均需要50次工具调用），模型很容易“偏离主题”或“忘记早期目标”，尤其是在长上下文或复杂任务中。
• 错误处理 (Error Handling)：Agent会犯错，常见的冲动是隐藏这些错误，但“擦除失败会移除证据”，导致模型无法从错误中学习和适应。
• 少样本示例的陷阱 (Few-Shot Trap)： 语言模型是优秀的模仿者。如果上下文中充满了高度相似的过去行动-观察对，模型会倾向于重复这种模式，即使它不再是最优的，这可能导致“偏离、过度泛化或有时产生幻觉”。

关键技术

• 围绕KV缓存进行设计
• 重要性： KV缓存命中率是生产阶段AI代理最重要的单一指标，直接影响延迟和成本。代理与聊天机器人不同，其输入与输出的token比例高度倾斜（例如Manus中平均约为100:1），这意味着大量的输入token需要被高效处理。缓存的输入token成本可能比未缓存的低10倍。
• 实现方法：
•                 保持提示前缀稳定： 由于LLM的自回归特性，即使单个标记的差异也会使该标记之后的缓存失效。一个常见的错误是在系统提示的开头包含精确到秒的时间戳，这会降低缓存命中率。
• 使上下文只追加： 避免修改之前的操作或观察。确保序列化是确定性的，例如，许多编程语言和库在序列化JSON对象时不保证键顺序的稳定性，这可能会悄无声息地破坏缓存。
• 在需要时明确标记缓存断点： 某些模型提供商或推理框架可能不支持自动增量前缀缓存，需要手动插入缓存断点。在分配这些断点时，要考虑潜在的缓存过期问题，并至少确保断点包含系统提示的结尾。
• 启用前缀/提示缓存和会话ID： 如果你正在自托管模型（如使用vLLM框架），请确保启用了前缀/提示缓存，并且使用会话ID等技术在分布式工作节点之间一致地路由请求。
• 遮蔽，而非移除 (Masking, Not Removing)
• 实现方法：
• 使用上下文感知的状态机管理工具可用性： Manus通过在解码过程中掩蔽token的logits来阻止（或强制）选择某些动作，而不是物理上移除工具定义。
• 利用响应预填充 (Response Prefilling)： 大多数模型提供商和推理框架支持这种机制。它允许你在不修改工具定义的情况下约束动作空间。常见的函数调用模式有：
• 设计具有一致前缀的动作名称： 例如，Manus有意将所有与浏览器相关的工具名称以browser_开头，命令行工具以shell_开头。这使得在给定状态下，代理可以轻松地从特定工具组中进行选择，而无需使用有状态的logits处理器。
• 自动 (Auto)： 模型可以选择调用或不调用函数，通过仅预填充回复前缀实现。
• 必需 (Required)： 模型必须调用函数，但选择不受约束，通过预填充到工具调用token实现。
• 指定 (Specified)： 模型必须从特定子集中调用函数，通过预填充到函数名称的开头实现。
• 重要性： 随着代理能力的增强，其工具数量会“爆炸式增长”。设计动态动作空间（例如按需加载工具）会带来KV缓存失效和模型困惑的问题。为了在不破坏缓存的情况下管理工具可用性并改进动作选择，需要更智能的方法。
  
• 使用文件系统作为上下文
• 实现方法：
• 将文件系统视为“终极上下文”： 它大小不受限制，天然持久化，并且代理可以直接操作。
• 模型学习按需写入和读取文件： 文件系统不仅用作存储，还用作结构化的外部记忆。
• 采用“可恢复的”压缩策略： 例如，只要保留URL，网页内容就可以从上下文中移除；如果沙盒中仍然保留文档路径，则可以省略文档内容。这使得Manus能够在缩短上下文长度的同时，不永久丢失信息。
• 重要性： 即使是现代前沿LLM的128K或更长的上下文窗口，在真实世界的代理场景中也往往不够。观察结果可能非常庞大，模型性能可能下降，且长输入成本高昂。过度激进的上下文截断或压缩会导致信息丢失，因为你无法可靠预测哪个观察结果未来会变得至关重要。
  
• 通过复述操控注意力 (Manipulating Attention via Rephrasing)
• 实现方法：
  
• 将代理的目标“复述”到上下文的末尾： Manus的实践是创建一个todo.md文件，并在任务进行过程中逐步更新它，勾选已完成的项目。通过不断重写待办事项列表，Manus将其全局计划推入模型的近期注意力范围内，从而避免了“丢失在中间”的问题，并减少了目标不一致。这实际上是使用自然语言来使模型的注意力偏向任务目标，而不需要特殊的架构变更。
• 重要性： 代理在处理复杂任务时，很容易“偏离主题”或“忘记早期目标”，尤其是在长上下文或多步骤任务中。
  
• 保留错误的内容 (Retaining Error Content)
• 实现方法：
  
• 将失败的尝试保留在上下文中： 当模型看到一个失败的行动——以及由此产生的观察结果或堆栈跟踪时——它会隐式地更新其内部信念。这会改变其先验知识，降低重复相同错误的可能性。Manus团队认为，错误恢复是真正代理行为最明显的指标之一。
• 重要性： 代理会犯错（模型幻觉、环境错误、外部工具异常行为等）。但常见的冲动是隐藏这些错误。然而，“擦除失败会移除证据”，没有证据，模型就无法适应和学习。
  
• 不要被少样本示例所困 (Don't Get Stuck in Few-Shot Examples)
• 增加多样性： 在行动和观察中引入少量的结构化变化。例如，使用不同的序列化模板、替代性措辞、顺序或格式上的微小噪音。这种“受控的随机性”有助于打破模式并调整模型的注意力。
• 记住： “你的上下文越单一，你的智能体就变得越脆弱”。
• 重要性： 少样本提示是提高LLM输出的常用技术，但在代理系统中，如果上下文充满了相似的过去行动-观察对，模型将倾向于模仿该模式，即使这不是最优的，从而导致“偏离、过度泛化，或有时产生幻觉”。
  

如何评估

对于用CE构建的一个更复杂的AI系统而言，其效果真的好吗？任务失败如何定位问题？

对于此类AI系统的评估，核心是测试模型在长序列中的信息保持、位置偏差和推理连贯性，可以使用现有的许多评测集来测试，也可以by modules测试单个模块的输入输出是否准确，或者构建一些评估专家的AI系统，用一个LLM去评价另一个LLM的输出，也能作为分数之外的另一个衡量标准。

最后想说

Context engineering的前提是大众已经认可了Agentic AI的长远价值，CE是对Multi-agent system应用现有问题打补丁的最佳工程实践。

如果把Agent应用比做一盘菜，那CE是让菜更加色香味俱全的调料，把现有的能吃但填不饱肚子也卖不起高价的菜做得更好吃更下饭更具备壁垒和商业价值。

但反过来想，Agentic AI并不是AGI最佳的呈现形式，完成复杂任务或许在目前的模型能力上始终无法尽善尽美，当有了更强的模型，CE价值会随着模型能力跃升而递减——当模型对上下文、工具、环境的理解趋近人类水平时，CE 会退到「安全护栏」与「个性微调」的位置，不再是“满汉全席全靠调料”。

AI更多的想象力或许不在处理复杂任务，而是更多的模态交互或更垂直的数据应用。更强的模型会让「任务完成」变得傻瓜化，Agent 的卖点不再是“能把事做完”，而是“让人愿意用它做更多事”。