1. 上下文工程到底在解决什么问题先把话说直白一点上下文工程Context Engineering这个词这两年被聊得很多但真正落到 AI Agent 项目里它不是一个学术概念而是一套“怎么把正确的信息在正确的时机用正确的格式塞进模型窗口”的工程方法。你可以把它理解成给模型配一个“随身助理”助理再聪明你给他一堆乱七八糟、过期、互相矛盾的资料他也干不好活。我最早做 Agent 的时候踩的最大一个坑就是——以为提示词写得好就万事大吉。结果一个能查数据库、能调接口、能多轮对话的 Agent跑到第三轮就开始胡言乱语工具调用参数错得离谱。排查了两天才发现根本不是模型不行是上下文被污染了历史对话越堆越长工具返回的原始 JSON 全塞进去了中间还夹着一堆无关的系统提示。模型窗口就那么大信息密度一低注意力就被稀释表现自然崩。所以上下文工程要解决的核心问题就三个信息过载窗口有限但可塞的东西无限必须做取舍。信息错位该给的信息没给不该给的塞了一堆模型抓不住重点。信息衰减多轮之后早期关键约束被淹没Agent 开始“忘事”。这三个问题任何一个没处理好Agent 就会从“智能体”退化成“智障体”。而上下文工程就是围绕这三个问题建立的一整套设计、压缩、检索、编排、校验的机制。适合谁来参考这篇内容如果你正在用 LangChain、LangGraph、Spring AI、扣子这类平台搭 Agent或者自己手写 ReAct 循环只要涉及多轮对话、工具调用、长任务这篇里的思路和参数你都能直接抄。纯小白也能看懂因为我会尽量用生活化的例子把原理讲透。2. 上下文工程的整体设计思路拆解2.1 为什么不能只靠“把提示词写长”很多人对上下文的第一反应是那我多写点提示词不就行了把规则、示例、约束全堆进去。这个思路在小 Demo 里能跑通但一上生产就废。原因很简单——注意力是有成本的。我用一个类比你给一个新员工写工作手册写 3 页他能记住重点写 300 页他反而抓不住关键。模型也一样上下文越长单个 token 分到的“注意力权重”越低。业界有个经验值当有效信息占比低于某个阈值时模型对关键指令的遵循度会明显下降。这个阈值不是固定的但你可以用一个简单指标自查关键指令 token 数 / 总上下文 token 数。我一般要求这个比例不低于 15%低于这个数就要考虑压缩或重构。所以上下文工程的第一原则是不是塞得多而是塞得准。这直接决定了后面所有的设计取舍。2.2 上下文的四层结构模型我在实际项目里习惯把 Agent 的上下文拆成四层从外到内分别是层级内容特点更新频率系统层角色设定、全局约束、安全规则稳定、必须常驻极低任务层当前目标、子任务拆解、进度随任务推进变化中记忆层历史对话摘要、长期事实需要压缩和检索高工具层工具定义、调用结果、错误信息量大、易污染极高这个分层不是为了好看而是为了决定谁该被压缩、谁该被丢弃、谁必须保留。系统层几乎不动任务层按阶段更新记忆层做摘要工具层做裁剪。你把这四层分开管理上下文就不会变成一锅粥。2.3 ReAct 循环里上下文是怎么被“吃掉”的ReActReasoning Acting是现在 Agent 最主流的执行范式思考 → 行动 → 观察 → 再思考。问题在于每一轮循环都会往上下文里追加内容。一个 10 步的任务如果每步工具返回 500 token光工具结果就 5000 token再加上思考过程轻松破万。我实测过一个查数据库的 Agent原始实现下第 8 轮时上下文已经到 12000 token模型开始重复调用同一个工具因为它“看不到”前面已经查过了。后来我加了工具结果摘要和去重同样的任务上下文稳定在 4000 token 以内成功率从 60% 提到 92%。这就是上下文工程的价值它不改变模型能力但决定了模型能力能不能发挥出来。3. 核心细节解析与实操要点3.1 系统提示的“锚点”设计系统提示是上下文的锚它必须满足两个条件短和硬。短是指尽量精简硬是指约束要明确、可执行。我见过太多系统提示写成小作文什么“你是一个乐于助人的助手请尽力帮助用户……”这种话占了大量 token 却毫无约束力。我的做法是把它拆成三段身份与边界一句话说清你是谁、不做什么。输出格式约束明确要求结构化输出比如 JSON schema。失败处理规则工具失败时怎么办信息不足时怎么办。举个我实际用的模板结构角色你是订单查询助手只处理订单相关请求。 边界不回答与订单无关的问题不编造订单信息。 输出所有回复必须是 JSON字段为 {status, data, message}。 失败工具报错时返回 statuserror并说明原因不重试超过2次。这四行比 200 字的“人设描述”有用得多。原因是它把可验证的约束放在了最前面模型每轮都能看到不容易被后续内容冲淡。注意系统提示里千万不要放具体业务数据那些应该走检索或工具。系统提示只放“规则”不放“事实”。3.2 工具结果的裁剪与摘要策略工具层是上下文污染的重灾区。一个 API 返回 2000 token 的 JSON模型真正需要的可能就 3 个字段。我的处理策略分三步第一步字段白名单。在工具封装层就只提取需要的字段不要把原始响应直接丢给模型。比如查订单只取 order_id、status、amount其余全丢。第二步超长截断。对列表类结果只保留前 N 条并明确告诉模型“还有 X 条未展示”。N 我一般设 5超过就分页。第三步结果摘要。对必须保留但冗长的内容用一次轻量模型调用做摘要把 1000 token 压到 100 token。这三步下来工具层 token 通常能压掉 70% 以上。代价是多一次摘要调用但相比上下文爆炸导致的任务失败这个成本完全值得。3.3 记忆压缩什么时候摘要什么时候丢弃多轮对话里历史消息不能无限保留。我的经验规则是最近 3 轮完整保留因为模型需要精确的上下文。4 到 10 轮做摘要保留关键决策和事实。10 轮以上只保留摘要中的摘要或者转入长期记忆检索。这里有个容易忽略的点摘要不是简单概括而是提取“状态”。比如用户说“我要查上个月的订单”摘要应该记成“用户目标查询 2025-05 订单”而不是“用户表达了查询意愿”。前者是可执行的后者是废话。我一般用一个固定的摘要模板强制模型按字段填充目标当前任务目标 已完成已完成的步骤 待办未完成的步骤 关键事实用户提供的重要信息这样每轮摘要都结构化后续检索和拼接都方便。3.4 上下文窗口的预算分配窗口就那么大必须做预算。我通常按这个比例分配以 8K 窗口为例用途预算占比说明系统提示10%固定不超 800 token任务状态15%当前目标和进度历史摘要20%压缩后的记忆工具定义15%工具 schema工具结果25%裁剪后的返回输出预留15%留给模型生成这个比例不是死的任务型 Agent 可以加大工具结果占比对话型 Agent 可以加大历史占比。关键是你要有预算意识而不是等爆了再救。4. 实操过程与核心环节实现4.1 搭建一个带上下文管理的 ReAct 循环下面用一个简化但可运行的 Python 结构说明。这里不依赖具体框架思路通用你换成 LangGraph 或 Spring AI 也一样。核心是维护一个ContextManager它负责在每轮循环前组装上下文循环后更新记忆。class ContextManager: def __init__(self, max_tokens8000): self.system_prompt SYSTEM_PROMPT self.task_state {} self.history_summary [] self.recent_turns [] self.max_tokens max_tokens def build(self, tool_resultsNone): parts [self.system_prompt] parts.append(self._format_task_state()) parts.append(self._format_summary()) parts.append(self._format_recent()) if tool_results: parts.append(self._trim_tool_results(tool_results)) return self._fit_budget(parts) def update(self, turn): self.recent_turns.append(turn) if len(self.recent_turns) 3: old self.recent_turns.pop(0) self.history_summary.append(self._summarize(old))关键在_fit_budget它按优先级裁剪先砍工具结果再砍历史摘要最后才动系统提示。系统提示永远不砍因为它是锚。4.2 工具结果的裁剪函数怎么写def trim_tool_result(result, whitelist, max_items5): if isinstance(result, list): trimmed [ {k: item.get(k) for k in whitelist} for item in result[:max_items] ] if len(result) max_items: trimmed.append({note: f还有{len(result)-max_items}条未展示}) return trimmed if isinstance(result, dict): return {k: result.get(k) for k in whitelist} return str(result)[:500]这个函数看着简单但它是上下文工程里性价比最高的代码之一。白名单机制强制你思考“模型到底需要什么字段”而不是偷懒全塞。4.3 摘要调用的参数选择摘要用轻量模型就行不需要用最强的。我一般用同系列的小模型温度设 0.1 到 0.3保证稳定。提示词固定为请将以下对话压缩为结构化摘要只保留 目标、已完成、待办、关键事实。 不要添加任何解释直接输出字段。温度低是为了让摘要格式稳定避免每次输出结构不一样导致后续解析失败。这个细节很多人不注意结果摘要本身成了新的污染源。4.4 上下文组装顺序的讲究组装顺序不是随便排的。我的经验是越重要的越靠前越新的越靠后。因为模型对开头和结尾的注意力相对更高中间容易“迷失”。所以顺序是系统提示 → 任务状态 → 历史摘要 → 最近对话 → 工具结果。工具结果放最后是因为它最容易被裁剪放最后砍起来不影响前面的结构。提示如果你发现模型总是忽略某个约束试着把它从中间挪到系统提示或任务状态里往往立竿见影。5. 常见问题与排查技巧实录5.1 Agent 多轮后开始“失忆”怎么办这是最典型的问题。表现是前面说过的约束后面不遵守了已经查过的信息又查一遍。排查顺序先看上下文长度是不是超了预算导致早期内容被裁。再看摘要质量是不是摘要丢了关键事实。最后看组装顺序关键约束是不是被埋在中段。我的解决套路是把关键约束同时放在系统提示和任务状态里双保险。任务状态每轮更新确保它始终在靠前位置。5.2 工具调用参数总是错这通常不是模型笨是工具 schema 描述不清。检查三点参数名是否语义明确别用p1、p2这种。是否给了示例值。是否说明了参数之间的依赖关系。我习惯在工具描述里加一句“调用前请确认 X 字段已从上下文获取”能显著降低瞎调的概率。5.3 上下文压缩后效果反而变差压缩是有损的压过头就会丢信息。判断标准是压缩后模型是否还需要重新询问已经提供过的信息。如果是说明压太狠了。我的做法是保留一个“不可压缩清单”用户明确给出的关键事实、当前任务的硬约束、已确认的决策。这些永远不压。5.4 常见问题速查表现象可能原因排查方向解决手段多轮后失忆上下文超限看 token 数加摘要、提预算工具参数错schema 不清看工具定义补示例、加依赖说明重复调用工具结果未去重看工具层加去重和已调用标记输出格式乱约束被冲淡看系统提示位置前移约束、加 schema压缩后变差压过头看摘要内容设不可压缩清单5.5 几个我踩过的坑第一个坑把工具原始返回直接拼进上下文结果一个接口返回 3000 token三轮就爆。后来强制走白名单问题消失。第二个坑摘要用大模型成本高还慢。换成小模型后质量没降速度翻倍。第三个坑以为系统提示越长越安全结果关键约束被自己的废话淹没。精简到四行后遵循度反而提升。第四个坑没有预算概念等报错才处理。后来在组装函数里加了 token 计数超预算自动触发裁剪稳定多了。6. 上下文工程的进阶扩展方向6.1 从静态上下文到动态检索当 Agent 接入的知识库很大时不可能全塞进上下文。这时候要引入检索根据当前任务动态拉取最相关的片段。这就是 RAG 和上下文工程的结合点。关键在检索的时机和数量。我的经验是每轮最多检索 3 个片段每个片段不超过 300 token并且要带上来源标识方便模型判断可信度。6.2 多 Agent 场景下的上下文隔离多个 Agent 协作时上下文不能共享否则互相污染。我的做法是每个 Agent 独立维护自己的 ContextManager只通过结构化的消息传递关键信息而不是把整个上下文丢过去。6.3 上下文质量的可观测性上线后要能观测上下文健康度。我一般埋三个指标平均上下文长度、有效信息占比、裁剪触发次数。这三个指标异常往往先于任务失败出现能提前预警。6.4 面向长任务的上下文持久化长任务可能跨会话上下文要能存能取。我的做法是把任务状态和摘要持久化到数据库下次会话时按任务 ID 恢复。注意只恢复状态和摘要不恢复原始对话否则又爆了。7. 我个人在实际操作中的体会做了这么多 Agent 项目我最大的体会是上下文工程不是锦上添花而是决定生死的地基。模型能力再强上下文管理不到位一样跑不出稳定结果。反过来哪怕用中等模型只要上下文管得好很多任务也能跑得又稳又准。我现在的习惯是每接一个新 Agent 需求先不写业务逻辑先把 ContextManager 的骨架搭好把预算、裁剪、摘要、组装这几件事定下来。地基打牢了后面加工具、加流程都是顺水推舟。最后分享一个小技巧如果你不确定某段信息该不该放进上下文问自己一句——“模型不看这段会不会做错”如果答案是“不会”那就别放。这个简单的判断标准帮我省下了大量 token也省下了大量排查时间。