上下文工程记忆注入、技能披露与Prompt缓存优化Prompt的顺序不是排版问题——它直接决定Prompt Cache命中率。顺序错了Token消耗和响应延迟会显著增加。一、上下文工程Agent框架的第一性竞争力很多人讨论Agent框架时关注的是工具数量、模型能力、多Agent编排。但有一个更底层的竞争力常常被忽视上下文工程。什么是上下文工程一句话在正确的时间把正确的信息以正确的形式放进正确的上下文位置。这四个正确背后是一系列棘手的问题LLM的上下文窗口有限哪些信息值得放进去每次请求都在变化的信息怎么放才不会破坏缓存大量技能文档全部塞进PromptToken能用几次对话历史越来越长裁掉哪些、保留哪些记忆文件几百行每次都全量加载吗DeepAgents在上下文工程上的设计是其架构中最精妙的部分之一。它通过三个MiddlewareMemoryMiddleware、SkillsMiddleware、SummarizationMiddleware和一套动静态分离的Prompt策略把上下文管理从人工调参变成了架构约束。二、动静态分离的黄金法则为什么分离是必须的Claude等大模型的Prompt Cache机制基于system prompt的哈希值。只要system prompt的内容不变缓存就能命中后续计算成本大幅降低可节省90%以上Token开销。因此任何动态的、每次请求都可能变化的内容绝不能混入system prompt。这引出了DeepAgents Prompt工程的黄金法则静态行为定义归于System Prompt动态任务指令归于User Message。具体怎么做最终的system prompt由两部分完全静态的内容构成段位内容性质说明BASESDK行为纪律静态核心定义Agent的核心行为范式构建期冻结SUFFIX模型调优后缀静态调优最终行为调优指令置于末尾最大化效力动态的用户指令、上下文、具体问题 → 作为独立的User Message发送。BASE段的四条工程纪律BASE段定义了Agent不可篡改的四条行为契约纪律核心含义核心行为回应简洁直接遇歧义先澄清对怎么做类问题先解释后执行专业客观准确性优先敢于并礼貌地纠正错误避免不必要的情感化表达任务流控制遵循理解→实现→验证流程长任务拆分迭代失败先分析再重试进度同步长任务执行时必须主动同步进度已完成什么、下一步做什么这四条纪律是DeepAgents将工程共识编译为底层契约的体现——不是靠开发者记得住而是靠代码强制。SUFFIX为什么在最后顺序是BASE → SUFFIX不可颠倒。原因有二缓存稳定性BASE作为恒定前缀确保system prompt哈希值稳定——这是缓存命中的基石指令效力研究表明模型对system prompt末尾的内容关注度最高。将最重要的调优指令SUFFIX放在最接近后续对话历史的位置效力最大化三、正确的数据流结构很多人的直觉做法是把所有东西——静态规则、动态指令——全拼进一个system prompt。这是灾难性的错误。正确的做法User Message - 动态每次请求变化用户指令、上下文、具体问题System Prompt - 完全静态构建期冻结BASE行为纪律SUFFIX模型调优System Prompt的哈希值恒定 → Cache命中 → Token成本大幅降低。任何将动态内容前置到system prompt的做法都会直接破坏缓存机制导致成本失控。四、MemoryMiddleware记忆的结构化注入记忆存哪里MemoryMiddleware负责加载AGENTS.md等长期记忆文件。但关键设计是记忆不是直接写进对话而是存进私有状态Private State。# 记忆存储在私有状态中不混入对话消息memory_content → PrivateStateAttr → 按请求注入为什么要存进私有状态因为记忆是参考材料不是对话内容。把它放进对话消息会污染上下文历史而且模型可能混淆记忆中的指令和用户刚说的指令。什么时候注入在LLM调用前注入。具体是在wrap_model_call()节点MemoryMiddleware从私有状态读取记忆内容以结构化形式附加到system prompt中。这个时机至关重要注入早了后续中间件可能修改它注入晚了模型已经生成了缺少背景的回答。记忆与缓存的顺序铁律MemoryMiddleware的注入位置必须在AnthropicPromptCachingMiddleware之后。因为Memory的注入是动态的不同会话、不同用户可能加载不同的记忆文件。如果先注入记忆再缓存缓存哈希就会包含动态内容——不同会话的system prompt哈希不同缓存命中率为零。Tail段正确顺序_ToolExclusionMiddleware工具裁剪AnthropicPromptCaching缓存处理MemoryMiddleware记忆注入HumanInTheLoop人工审批这是中间件三段式装配中Tail段排序的关键依据之一。五、SkillsMiddleware渐进式披露策略技能为什么不全部注入一个企业级Agent可能有十几个技能模块每个技能文档可能几百行。如果全部注入system prompt不仅消耗大量Token每次请求白花几万Token还会让模型分心——它面对浩如烟海的技能文档时反而更难抓住核心指令。渐进式披露怎么做SkillsMiddleware只向模型注入技能的目录技能名称如code-review、“deploy-check”一句话描述技能文档的读取路径而不是文档内容本身模型看到目录后如果判断某个技能与当前任务相关可以通过工具调用按需读取完整技能文档。这就像你查API文档——不会把整本手册背下来只会在需要时翻开对应章节。文件系统LLM模型SkillsMiddleware文件系统LLM模型SkillsMiddleware仅在需要时消耗Token读取完整内容注入技能目录名称 描述 读取路径判断技能与任务是否相关按需调用 read_file读取完整技能文档返回完整技能文档工程收益Token大幅节省目录几十行 vs 全部文档几千行每次请求省下数万Token模型注意力聚焦窄信息面 → 更精准的决策技能热更新技能文档可以随时更新不改变system prompt的缓存哈希六、SummarizationMiddleware冷热分层不粗暴删历史上下文爆了怎么办对话越来越长迟早撞上模型的上下文窗口上限。传统的做法是粗暴截断——砍掉最早的几轮对话。但这会丢失关键上下文用户最初的需求描述、中间做过的决策、已经验证过的结论。DeepAgents的做法冷热分层保留在上下文中热层最近的对话轮次模型可以直接引用转存到后端冷层被驱逐的较老内容保存摘要和可恢复线索可恢复如果模型后续需要冷层中的信息可以通过文件读取工具按线索找回这相当于日志归档的思路——不删数据分层存储。热数据在内存供快速访问冷数据在磁盘供按需回溯。接近阈值 80%最近20轮对话较早的80轮对话模型按需回溯对话上下文窗口有限容量SummarizationMiddleware触发压缩冷热分流热层保留在上下文模型可直接引用冷层转存到后端保存摘要 可恢复线索通过 read_file按线索找回冷数据什么时候触发基于模型上下文窗口的阈值判断。当对话长度接近窗口上限的某个比例如80%时自动触发截断和转存。不是等爆了再救火而是提前预防。七、上下文工程的经济学这三层设计的经济收益值得算一笔账。假设一次典型的Agent会话场景全量注入做法DeepAgents做法节省技能文档10个模块各500行令牌~15000 Token/请求~500 Token/请求仅目录~14500 Token/请求记忆文件AGENTS.md 300行注入混入对话消息私有状态 按请求注入避免上下文污染长期对话历史100轮全部保留上下文窗口爆满冷热分层热层保留最近20轮节省80%上下文占用Prompt缓存动态内容混入system prompt → 0%命中完全静态system prompt → 90%命中Token成本降低90%对于一个日均万次调用的生产系统上下文工程优化带来的成本节省不是几块钱而是成千上万倍的差异。这就是为什么上下文工程是Agent框架的第一性竞争力。八、小结DeepAgents的上下文工程围绕一个核心公式展开正确的上下文 正确的信息 × 正确的时机 × 正确的形式 × 正确的位置具体落地为四层保障动静态分离—— System Prompt完全静态保缓存命中动态指令走User Message结构化记忆注入—— 记忆存私有状态LLM调用前注入不污染对话历史渐进式技能披露—— 目录给模型看完整文档按需读取冷热分层压缩—— 热数据保留上下文冷数据转存可恢复这四层设计的工程价值不是让Agent更聪明而是让Agent的上下文始终干净、缓存始终命中、成本始终可控。对一个生产级Agent系统来说这些比模型能力本身更重要。