AI代理项目做多了之后，我慢慢意识到一个特别反直觉的事实：决定一个AI代理（AI Agent）上限的，往往不是模型有多强、代码写得有多好，而是你喂给它的那堆上下文（Context）有没有被认真对待。以前我也觉得上下文无非就是"把资料塞给模型"而已，直到栽过几次跟头，才明白这玩意儿非常像一套需要持续维护的代码库——它有自己的生命周期，会过期、会膨胀、会互相污染，甚至会在你毫不知情的时候把整套系统拖垮。
这篇文章我想从一个真实事故说起，拆解AI代理上下文为什么会"失控"，再把上下文工程（Context Engineering）的落地方法、工具思维、数据流诊断法以及上下文治理的实践思路一次讲清楚。无论你是做AI编码助手、AI Agent平台，还是单纯在用Cursor、Claude这类工具写代码，这篇文章应该都能给你一些新的视角。
1. 一次事故复盘：AI代理把整个代码仓库塞进上下文之后
1.1 事故现场：看似聪明的"全局感知"其实是灾难
先讲个我真实经历过的案例。几个月前，我让一个AI代理去重构一个内部服务的数据库访问层。任务不复杂，就是把分散在十几个文件里的查询逻辑收敛到一个新的Repository模块里。我当时的做法很简单：把整个仓库的代码全部作为上下文丢给代理，想着"信息越全，判断越准"。
结果非常惨。AI代理确实理解了全局结构，但它把几乎所有文件里的代码都当成"需要保留的细节"来对待——它不敢删任何东西，在一个根本没有用到旧方法的文件里保留了旧逻辑，然后在新模块里又"合理推测"出一堆原本不存在的兼容层。最终代码量膨胀了40%，里面还混进了一些看起来合理但实际上从未被调用的函数。
我当时的第一反应是"模型太笨"，但后来复盘时发现，问题出在我自己身上。我把上下文当成了一种静态资源，一股脑塞进去，却完全没有考虑：这个上下文在任务的不同阶段是否都有效？里面有多少信息已经过期？有多少细节是干扰项？
这就像让一个刚入职的工程师一下子读完整套系统的全部代码，然后问他"帮我改一下数据库访问层"。他能读，但读到后期，前面那些细节早就变成了噪声。AI代理的注意力会被大量低价值内容稀释，接着就会在关键地方出现"幻觉式补全"。
1.2 三类典型症状：幻觉、上下文溢出、回答漂移
那次事故之后，我开始留意AI代理在长任务里出问题的规律，总结下来无非三类症状。
第一类是幻觉。这很好理解，当上下文里塞满了互相矛盾的代码版本（比如老的配置文件和新代码里声明的环境变量不一致），模型就会挑出一条最"顺眼"的路径去生成，而那条路径往往是被淘汰的逻辑。换句话说，坏上下文是幻觉的燃料。第二类是上下文溢出（context overflow）。Claude、GPT这类模型的上下文窗口再大也是有限度的，超了就两种结果：要么直接报错，要么模型开始"选择性失忆"，只关注最近的内容，把任务早期的指令忘得一干二净。第三类是回答漂移（drift），这个最阴险，它不报错，看起来一切正常，但模型越往后越偏——一开始还按照你定的规范命名，五轮对话之后命名风格就全乱了，理由是你后面某次给的临时文件中出现了不一样的写法。元凶就是：那些不该出现在上下文里的内容，正在悄悄改写模型的"短期行为规范"。
1.3 这不仅仅是"上下文太大"的问题，是生命周期缺失
对比一下软件工程，我们对代码有版本控制、有依赖管理、有CI/CD，每个阶段都有人管。但AI代理的上下文呢？通常就是一堆塞给模型的提示词、文件片段、历史记录，没有版本、没有过期机制、没有依赖关系，用完就丢，下次再重新拼装。
所以说"上下文太大"只是表面现象，本质是上下文的生命周期没有人负责。它从出生（从代码库或对话中提取）、到成长（在多轮交互中被不断补充和改写）、再到死亡（被新的上下文章节覆盖或失效），整个过程完全是失控的。
如果你把一个AI代理当成长期运行的服务，而不是一次性的API调用，就早晚会撞上这个问题。我自己的体会是，越是复杂的Agent，越需要像管代码一样去管上下文——而第一步，就是建立"上下文工程"的思维框架。
2. 上下文工程：把"喂给模型的东西"当一等公民来对待
2.1 上下文工程到底在解决什么问题
很多人会把上下文工程和提示工程（Prompt Engineering）混为一谈。提示工程关注的是"怎么说模型才会听"，上下文工程关注的是"把什么东西放到模型面前"。这个区别非常关键。
提示词只是上下文的一部分，真正决定AI代理输出质量的，是它可访问到的全部信息：包括对话历史、代码片段、外部API返回的数据、工具调用的结果、记忆向量数据库里的相关内容，甚至还有用户上传的截图和视觉素材。上下文工程就是研究如何获取、过滤、组织、更新这些信息，让模型在正确的时间、以正确的方式看到正确的内容。
这跟运营一个实时数据管道有点像。你不能把数据库里所有的表都同步到下游分析系统——那样会把系统拖垮。你必须做分层、做增量、做预热、做淘汰。AI代理的上下文同理。
2.2 执行上下文与静态上下文的区别：跟JS的"执行上下文"做个类比
刚接触这个概念的时候，很多人会想到编程语言里的"执行上下文"，比如JavaScript里那个无数面试题涉及的this指向问题。其实这两个概念之间有一个很好的类比。
JavaScript的执行上下文是"代码运行时的环境对象"，它决定了在某一时刻，变量怎么解析、this指向哪里。AI代理的执行上下文则是"模型执行推理时可见的环境信息"，它决定了模型在生成回复时参考什么、忽略什么、遵循什么规则。
但这里有个非常有意思的分歧：在JavaScript里，函数能访问哪些变量，是由词法作用域（定义位置）决定的，是相对确定、可预期的；在AI代理里，模型能"看到"什么，却总在变化——它取决于你塞入了什么、截断了什么、排序如何。所以AI代理的上下文需要被当成"动态的执行环境"来管理，而不能当成"静态快照"。
我后来在自己项目里实践的方式是：区分"静态上下文"和"执行上下文"两层。静态上下文是任务开始前的基线信息（比如项目规范、架构文档、代码风格指南），执行上下文是每次模型调用前动态拼装的实时信息（比如当前函数签名、最近的测试输出、用户最新的诉求）。两者分开管理、分别更新，比混在一起处理要清爽得多。
2.3 上下文资产化：把上下文当成账户里的"资产"而不是垃圾场里的"废料"
还有一个思维层面的变化很关键，就是建立"上下文资产"的概念。什么是资产？有价值、可复用、可计量。上下文也应该这样对待。
比如，你喂给AI代理的一段技术架构决策记录，这不仅是本次对话的"背景资料"，更是未来所有相关任务都应该继承的"项目记忆"。你给它的一段API使用规范，也不只是用于当前任务，而是可以沉淀成团队级上下文的黄金内容。
我自己会在项目里维护一个独立的context-assets目录，里面分类存放规则、代码片段、架构说明，都是经过人工审核的。每次Agent跑任务前，先从这里面挑选最相关的部分，而不是去历史对话里翻找。这就是"上下文资产化"的雏形：上下文不再是每个任务临时拼凑的消耗品，而是可以沉淀、可以继承、可以不断增值的组织级资源。
3. 上下文生命周期五阶段：创建、蒸馏、注入、验证、回收
3.1 创建（Create）：如何从真实需求中采集上下文
上下文的创建阶段，对应的是"为当前任务找出最高价值的信息源"。这一步最忌讳的，就是把所有信息源一股脑全拉进来。
以代码库为例，你需要做一个"上下文地图"：哪些文件跟当前任务强相关，哪些文件是间接引用，哪些文件虽然路径相近但内容无关。强相关的文件必须完整读入，间接引用的文件可以先读摘要，无关的直接排除。
具体操作上，我习惯让AI代理先做一次"索引扫描"——读一遍仓库结构、关键配置、最近的提交记录，然后让它自己提出"如果要完成这个任务，我建议重点看哪些文件"。这个提议会回到我这里做确认。这种"先索引后精读"的方式，能显著压缩上下文体积，同时保住关键信息。
生活化类比：就像你准备去一家大型商超采买某个特定香料。你不会把商超的地图全部记进脑子里，你只会记住香料区的位置，以及对应的货架编号。AI代理的上下文创建，就是帮你找出"香料区的货架编号"。
3.2 蒸馏（Distillation）：压缩但不丢失关键信息
蒸馏阶段核心解决的是"信息过多"的问题。你可以用摘要、层级化压缩、或者"只保留结论不保留过程"的方式，把上下文体积降下来。
这里有一个原则：蒸馏不等于删减，而是信息重组。删减是粗暴地把东西扔掉，重组是把原始信息转化为更易被模型利用的形式。
举个例子，一段包含50个提交记录的git日志，直接塞给模型，它会因为信息过载而困惑。但如果先把它蒸馏成一份"变更主题摘要"，比如"三次提交都与身份验证模块的token刷新逻辑相关，涉及文件A、B、C，有两次bug修复和一次重构"，模型就能快速抓住要点。这个蒸馏过程可以由另一个AI模型来完成，也就是"AI代理助手+本地模型"做一个pipeline，先用本地轻量模型做初筛、压缩，再用大模型做精细推理。我实测过，本地模型执行这类"上下文粗加工"任务的效果相当不错，而且成本很低。
3.3 注入（Injection）：按需加载，而非全量投喂
注入阶段对应的是"在恰当的时机把合适的上下文放进模型窗口"。这背后有一个现代系统设计的通用原则：懒加载（lazy loading）。
在对话型AI代理中，没有必要把用户可能需要的所有信息一次全塞进去。比如用户只是问"数据库连接失败怎么办"，你不需要把整份运维手册都丢进去。更好的方式是预先设计好"上下文索引"，当模型理解了用户意图之后再去检索相应的详细内容，并注入到当前对话中。
这一点在工具的实现层面已经能看到雏形。Cursor处理项目级AI编码时，会先建立代码索引（index），然后在用户提问时检索相关片段并注入到上下文里，而不是把整个项目一次性都交给模型。这也说明了为什么"Agent不应该自己掌握全部信息，而是应当掌握取得信息的方法"。
3.4 验证（Validation）：模型输出前的一次"上下文核对"
验证阶段是最容易被忽略、也最值钱的一个阶段。它指的不是验证模型的输出对不对，而是在模型输出之前，回看一遍：注入的上下文是否完整？有没有自相矛盾的内容？是否存在某一项信息非常关键但根本不在上下文里？
这类验证有一种实操思路，就是构建"上下文自检清单"。比如我常用的清单包括：当前任务的原始目标是否还在上下文中？最近一次修改的目标文件内容是否已经更新？是否存在之前某次工具调用产生的过期输出？如果AI代理在运行过程中被外部系统回传了一段新数据（比如API改动信息），这段新数据是否被正确纳入了上下文，还是成了一个游离的"幽灵上下文"？
把这步做好，可以最大程度避免"模型在错误前提上做正确推理"的尴尬情况。很多时候你感觉模型在"一本正经地胡说八道"，其实不是模型的问题，而是上下文中前提信息已经错了，但没有任何机制发现。
3.5 回收（Recycle）：过期上下文的清洗与长期记忆的沉淀
最后一个阶段可能就是生命周期管理与普通"缓存清理"最大的区别：不是把旧上下文当垃圾扔掉，而是把其中有价值的部分萃取出来，沉淀为长期记忆；剩下真正过期的部分，才做废弃处理。
具体来说，可以在AI代理执行完一轮任务后做"记忆提炼"：把任务中发现的高价值信息（比如某个服务有隐藏的调用限制、某个目录下有个配置容易被忽略）抽取成结构化条目，写入共享的记忆库或规则文件。这样下次遇到相似任务时，新上下文可以继承这些经验，而不需要把之前几十轮对话全部重新加载。
与之对应的回收动作是"过期标记"。有些信息只对特定版本有效，一旦代码发生了大升级，旧上下文里的行为描述就不再可靠了。此时要做的是标注"此上下文已过期"，让后续的注入阶段优先排除它。这样可以避免非常典型的"旧配置污染新代码"问题。
4. 工具实战：从Cursor、Claude到FastAPI的上下文管理启示
4.1 Cursor怎么把上下文给到AI：@引用、Rules与项目记忆
如果你用过Cursor，应该对@引用不陌生。这其实是"上下文注入"在编码工具上的极佳实践。@文件名、@文件夹、@代码符号，本质上是让用户精确指定"当前任务需要哪些上下文源"，然后工具把这些源的内容转换后注入到模型窗口中。
比@引用更进一步的是Rules文件，比如.cursorrules。这相当于"静态上下文"层，是长期稳定、不随任务变化的基础约束。我会在里面写明代码风格、框架偏好、禁止事项，这样每次会话都会自动继承，而不用反复在提示词里重申。
但很多人的用法还停留在比较浅的层面：根本不关心上下文是怎么组织的，只知道"可以@文件进去就行"。实践一段时间后你会发现，@的顺序和数量非常影响模型质量。把项目规范放在最前、任务描述放中间、参考代码放最后，模型输出的效果会明显更稳定。这是因为很多大模型对上下文不同位置的内容有着不同的注意力权重，越靠前和越靠后的内容越容易被记住，中间部分容易"遗忘"。学会利用这个特性，相当于免费获得了一小段"上下文生命周期"的掌控力。
4.2 Claude超过上下文限制会怎样：不只是报错那么简单
很多人问"Claude超过上下文限制会怎么样"。经历过的人都知道，最明显的表现就是直接报错——表示对话太长，要求你开新对话。但在更隐蔽的场景下，即使没有达到硬性限制，模型也会出现"变笨"的现象，这就是所谓的"上下文稀释"或"lost in the middle"。
实测中我发现，一段长对话到了后期，即使上下文没有真正溢出，模型也会倾向于忽略中段的信息，只关注最近的问题和最开头的系统提示。你以为它"应该还记得"早期你给它的一份关键代码片段，但它其实已经把它当成背景噪声了。
所以，对于Claude这类上下文窗口很大的模型，我的经验是：不要因为窗口大就肆无忌惮地塞内容。窗口大只是给了你更多余地，但模型的有效吞吐和理解深度是有限的。把上下文压缩到任务所需的最小集，永远是收益最高的做法。
4.3 FastAPI的上下文管理给我们什么启发：作用域与生命周期
聊到FastAPI，很多人第一反应是Request对象和依赖注入系统。但我觉得FastAPI最值得AI代理开发者借鉴的，是它对"资源作用域"的管理。在FastAPI里，你可以用Depends来控制依赖的创建、共用和销毁——有的依赖在整个应用生命周期内只创建一次，有的依赖每次请求都会重新创建，还有的依赖只在特定路由下存在。
这正好对应了AI代理上下文的生命周期管理思路：有些上下文应当是"全局单例"（比如项目规范、团队代码风格），有些则应该是"请求级"的（比如当前任务的具体描述、用户这次提出的新要求），还有些应该是"局部"的（比如某个函数调用的中间输入输出）。可惜大多数AI代理项目并没有这么精细的层级划分，所有上下文都堆在同一个"对话历史"里，生命周期完全被对话长度绑架。FastAPI给我们的启示是：上下文也可以设计出"作用域"，这样生命周期就不是一个模糊的"全局球"，而是可以精确控制的分层结构。
4.4 本地模型时代的上下文预算：硬件受限时怎么活
再聊聊"AI代理助手加本地模型"这个玩法带来的额外挑战。本地模型的上下文窗口往往比云端大模型小得多，当把本地模型接入AI代理时，你就被迫做上下文"精算"。
我踩过最典型的坑是：在一个Agent任务里，用本地模型做文本分类，但忘了本地模型的上下文窗口限制，直接把几千条候选文本全部传进去，结果模型直接OOM。后来我改成"分批次+摘要前置"的方式：每批只传100条，让模型先输出汇总，再把汇总作为下一批的输入，效果立刻好了，还顺带提升了分类准确率。
这类经验说明一个道理：上下文生命周期管理不是云端大模型独有的奢侈品，它对本地模型、边缘场景、成本敏感项目而言是一项更硬的约束。上下文预算规划得越好，整个系统的性价比就越高。
5. 上下文数据流图：把不可见的问题变成可排查的故障
5.1 为什么要画上下文数据流图
排查AI代理问题的时候，有一件工具特别有用，就是上下文数据流图。这个概念不是官方的标准，而是我自己在调试复杂AI代理时养成的习惯：把"信息从哪里来、经过什么处理、最终怎么进入模型窗口"用一张图记录下来。
为什么值得这么做？因为AI代理输入的信息往往来自多个渠道：用户对话、外部API、代码检索、记忆库、工具调用返回。当输出异常时，你不去追踪这些信息流，很难定位问题到底出在哪个环节。
比如说，Agent的回答里突然出现了过时的端口号。如果你没有数据流图，你可能会以为是模型幻觉。但查一下数据流图，你会发现端口号来自一个两小时前缓存的API响应，而那次响应现在已经被更新了。问题出在"缓存未失效"，不是模型问题。这就是数据流图的威力——把"上下文问题"转化为"数据流环节问题"，有据可查，有逻辑可推。
5.2 数据流图分解的四个节点：采集、转换、注入、回流
我通常把上下文数据流图抽象成四个节点。
采集节点负责从外部获取原始信息，比如读取文件、调用API、查询数据库。转换节点负责把原始信息变成模型友好的形式，包括蒸馏、格式化、去重。注入节点负责把转换后的信息编码进模型的输入序列，这一步往往跟提示词模板交错在一起。回流节点则负责把模型的一轮输出、工具调用的新结果、用户的反馈重新纳入上下文池，供下一轮使用。
画图的时候，只需要标注清楚每个节点的输入输出即可。重点是找出"过期的信息在哪里被注入"和"新的信息在哪里回流失败"。
5.3 实战案例：用数据流图排查AI代理的"失忆"
说一个我用这个方法解决的真实问题。当时一个AI客服代理，经常在回答到第五、六轮的时候就"忘掉"最初用户提供的会员等级信息，导致优惠计算错误。
乍一看像是上下文限制问题，但我画完数据流图后发现，这个客服代理有一个"多轮记忆模块"，专门负责保留用户的关键属性。按理说会员等级应该在每一轮都被重新注入，但数据流图显示：第一轮的时候，会员等级确实被正确写入了记忆模块；但第二轮的时候，由于另一个功能调用了"重置用户摘要"，把会员等级这个字段覆盖成了默认值。之后每轮注入的都是这个默认值——"失忆"根本不是模型的问题，是上游的回流覆盖了正确的上下文。
修复也很简单：在数据流图中增加一个"关键属性不可被覆盖"的合并规则。改完后问题彻底消失。这个案例让我深信，上下文数据流图的分解和检测能力，比凭感觉调试上下文要高效十倍。
6. 治理与前瞻：上下文从"凭感觉"走向"有标准"
6.1 上下文质量的评估指标体系
当上下文管理进入治理层面，就需要一套评估指标，否则你没办法回答"这次的上下文组织得怎么样"。我目前在项目里使用的指标有几个：
完整性：任务所需的关键信息是否都在上下文中，有没有缺失项。时效性：上下文中的信息是否仍然有效，有没有过期内容。一致性：不同来源的信息之间是否存在矛盾。紧凑度：上下文的实际信息密度有多大，有没有大量无关冗余内容。
这些指标不一定要很复杂，但每个项目都应该定义清楚。比如"紧凑度"可以用"有效信息token数/总token数"来简单估算。当这个比例低于某个阈值（比如不到50%），就说明上下文开始发福了，该考虑蒸馏了。
6.2 上下文版本控制与自动化运维
另一个发展方向是把上下文的版本控制和自动化运维做起来。就像代码有Git，上下文也应该有"版本"。我在实践中发现，最简单的做法是：每次AI代理运行完一轮任务后，把实际注入模型的上下文快照存下来，连同输出结果和任务指标一起归档。
这样做的收益是"可回放、可比对"。当一个任务失败了，你可以回放当时的上下文快照，判断是上下文组织的锅，还是模型的锅；还可以对同一任务跑两版不同的上下文策略，用同一模型做A/B测试。这不就是自动化运维的标准动作吗？监控、日志、灰度、回滚，在上下文领域完全可以复用。
6.3 视觉上下文与多模态上下文的新挑战
最后再聊聊一个越来越常见的场景：视觉内容上下文模型。现在很多AI代理不仅仅处理文字，还接收截图、图表、产品原型图、图片等视觉信息。这些视觉内容同样需要走生命周期管理，但它的挑战比纯文本大得多。
纯文本的蒸馏相对成熟，摘要、关键词提取都有现成方案。但视觉内容的"蒸馏"要难得多：你没法简单地把一张设计稿"摘要"成几个词而不丢失布局细节，也无法轻易判断一张截图中哪个区域对当前任务重要。一个实际做法是，让多模态模型在注入前先做"视觉预检"——识别出截图里有价值的关键区域（比如报错弹窗、数值指标、按钮状态），并把注意力引导到这些区域，缩小视觉上下文的体积。这个思路还可以和上一节讲的"数据流图"结合：视觉内容进入上下文前，先经过一个"视觉蒸馏节点"，输出结构化描述，再注入模型窗口。
对长期运行的Agent来说，视觉上下文的生命周期管理尤其重要，不然图片会快速消耗上下文窗口——一张高清截图顶得上几千个tokens，两三轮下来就触顶了。
6.4 我可以坦率地说：上下文是AI代理真正的"战场"
在我目前的认知里，AI代理之间的差距，很多时候不是模型选型的差距，而是上下文管理的差距。同样的模型、同样的任务，上下文组织得当，效果可以好非常多；组织混乱，则大概率会跌进幻觉、遗忘、漂移的坑里。这也是为什么我会把上下文从"随手塞给模型的东西"升级成一个需要维护、需要评估、需要演进的生命体——它有自己的生命周期。
落到实际操作上，不用等"完美方案"落地才动手，你可以今天就开始做两件事：第一，给你正在用的AI编码工具（Cursor、Claude Code等）写一份严格的Rules文件，把项目规范静态化，作为上下文的稳定底座；第二，在复杂任务开始时，先花两分钟画一下数据流草图，标出关键信息从哪里来、在哪里注入、会不会过期。就这两步，足以让你避开大部分上下文陷阱。
如果你也在做AI代理或者吃了上下文管理的亏，欢迎带着你的数据流图来聊，我很想看看你的上下文生命周期里，哪个环节最容易"暴雷"。
