前阵子帮同事排查一个线上问题到现在印象都很深。订单模块里有个生成临时文件名的工具方法单测全绿线上跑了几个月也没事。结果工单系统复用同一个方法之后时不时冒出来空指针。代码一行一行读过去逻辑没问题传参也没问题。最后顺着调用链往上翻发现方法内部读的是一个静态变量这个静态变量要求在入口处通过拦截器手动初始化。订单模块的入口做了工单模块的入口漏了。更隐蔽的是工单流程有时候走的是异步任务线程拦截器根本不经过那个线程静态变量在那边就是空的。这个问题和代码写错了没关系是上下文没传对。这类问题我这些年遇到无数回今天借 context-mode 这个关键词把我在项目里积累的上下文管理经验完整梳理一遍从代码运行时的上下文传递到模块设计再到 AI 编程工具里的上下文选择一次讲透。1. context-mode 是从报错现场反向摸出来的概念上下文到底是什么1.1 同一个方法为什么换了个入口就翻车工单系统那个空指针第一眼看上去像是数据问题。我打日志看出参工具方法是拿到完整文件路径之后调用File.createTempFile时临时目录为 null。临时目录没从参数上拿而是从一个静态类里读的。也就是说这个方法能不能工作取决于调用之前有没有人把临时目录这个环境信息塞进静态类。这不是特例。我复盘过手头几个项目的故障有相当一批是同类问题方法内部读取全局配置但新服务没加载那部分配置方法内部用线程局部存储拿当前用户但异步任务里根本没有用户上下文方法内部依赖某个拦截器预先设置的数据但新接口忘了挂拦截器方法内部从环境变量读开关但部署环境的变量名被写错了这些问题都有一个共同点代码本身没错代码所处的环境不对。环境就是上下文。你能把逻辑写得再漂亮只要上下文没传对生产环境照样给你翻脸。1.2 上下文在代码世界里可以拆成哪几层我习惯把上下文分成环境上下文、请求上下文和代码上下文三层它们的生命周期完全不同。环境上下文是程序启动后基本不变的请求上下文是单个请求生命周期内才有效的代码上下文则是理解某段代码时需要的周边信息偏知识性。上下文类型典型内容生命周期常见失效场景环境上下文配置项、Feature Flag、运行环境进程级别新服务没加载配置、环境变量拼写错误请求上下文当前用户、租户 ID、权限、语言、时区单次请求异步线程丢失、跨服务传递遗漏代码上下文调用关系、类型定义、模块职责、历史决策持续存在文档缺失、读代码的人不了解背景这三层如果管理得好写代码就是在清晰管道里灌水管不好就是水漫金山到处都摸不到底。1.3 context-mode 就是管理当前状态的整套方式按我的理解context-mode 是一套用于定义、收集、传递、隔离和遗忘上下文的模式。它不是一个具体库而是一种工程意识。传统开发里我们通过函数参数、依赖注入、线程局部变量、日志 MDC、链路追踪 Header 来做这件事。到了 AI 辅助编程时代它又多了新维度怎么把项目背景和代码片段组织好喂给模型让 AI 拿到正确的上下文再回答。1.4 上下文失控的五个常见前兆如果你所在的项目出现了下面这些现象说明上下文管理已经欠债了代码在单测里正常一到生产环境就随机异常重启后可能又好了异步任务里日志的 TraceID 是空的一次请求的日志串不起来新同事读代码时总要追问这个变量是在哪设置的这个全局状态谁在改AI 编程工具给出的代码总是跟仓库实际风格对不上反复用已删除的 API一个看似小重构改动面却像涟漪一样往外扩散因为一堆隐藏依赖被触发出现任意一条都值得停下来排查一下上下文链路。2. 程序世界里的上下文传递参数、隐式变量与协程变量的取舍2.1 显式传参是底线但不是银弹最稳妥的上下文传递方式就是把依赖当作参数传进去。比如def generate_temp_filename(file_name: str, temp_dir: str) - str: return os.path.join(temp_dir, file_name)temp_dir由调用方负责提供方法本身不再去猜临时目录应该在哪。这种做法好处明确方法内部没有隐藏依赖单测可以直接传各种临时目录做边界测试。但项目一大每个函数都把所有上下文参数带一遍同样很痛苦。一个下单接口可能涉及用户、语言、时区、优惠策略、渠道标识、TraceID要是每个方法都把这些参数逐个传一遍接口签名会膨胀成一长串环境变量。这也是为什么很多开发者宁可读全局属性也不愿意改签名——签名一长调用方和读代码的人都累。2.2 隐式上下文的诱惑与代价为了解决签名膨胀很多框架引入了隐式上下文。Java 的ThreadLocal、Slf4j MDCPython 的contextvars本质上都是想在不改每个函数签名的情况下让代码链路上的成员共享某些上下文。以 Python 的contextvars为例import contextvars import uuid request_id contextvars.ContextVar(request_id, default) async def api_entry(order_id: str): request_id.set(uuid.uuid4().hex) await process_order(order_id) async def process_order(order_id: str): # 在调用链的任意协程里都能取到入口处设置的 request_id print(f[{request_id.get()}] processing {order_id})这套机制在有异步任务时尤其有用因为asyncio的create_task会自动拷贝当前上下文子协程拿到的还是入口设置的值。但隐式上下文最坑的一点是它不会自动清理。如果用的是线程池线程执行完任务后没有显式移除下一个被复用的线程可能读到上一个请求留下的用户信息。这是典型的上下文串号表现出来就是偶尔出现别人的数据。我曾经排查过一起数据错乱最后定位到ThreadLocal里的用户身份在任务完成后没有被清理。2.3 跨服务链路的上下文透传让请求有迹可循单机内部靠协程变量或线程局部存储到了分布式系统上下文必须跨进程透传。最常见的载体是 HTTP Header 或消息队列的消息头。我在 Go 项目里习惯这样组织type ctxKey int const traceIDKey ctxKey iota func WithTraceID(ctx context.Context, traceID string) context.Context { return context.WithValue(ctx, traceIDKey, traceID) } func GetTraceID(ctx context.Context) string { if v, ok : ctx.Value(traceIDKey).(string); ok { return v } return }入口中间件从 Header 里取 TraceID塞进context.Context业务方法统一接收一个ctx参数。这个ctx表面上是多传了一个参数实际上把所有与这次调用相关的环境信息打包好了。再配合日志组件自动从ctx里提取 TraceID排查问题时就能把一次请求的所有日志串成链路。2.4 选型判断标准上下文类型推荐传递方式主要风险实践建议环境/配置依赖注入或配置对象全局读取导致难测试启动时组装业务代码不直接读环境变量请求级显式参数或请求上下文对象签名膨胀核心入口用上下文对象内部用显式参数用户/租户框架隐式上下文线程复用导致串号用 try-finally 保证清理TraceID链路透传异步边界忘记传递封装异步执行器统一透传选型没有标准答案但有一条底线任何被并发或异步复用的代码路径上下文必须显式清理。否则排查成本会成倍增加。3. 让模块自带上下文消灭幽灵状态的接口设计3.1 幽灵状态是复杂系统的副产物代码看多了会发现最让人头疼的往往不是算法而是那些不知道从哪冒出来的隐藏状态。你可能见过这种写法def create_order(order_data): user current_user.get() lang get_current_lang() tz get_timezone() ...在单线程、同步调用、入口固定的项目里这套写法可能一直正常。但只要时间线一拉长入口从一个变成十个同步变成异步单机变成多线程这些幽灵状态就开始作妖。3.2 用上下文对象重构入口逻辑我的做法是把一次业务请求需要的环境信息统一收进一个上下文对象在入口处组装好往下传递。改造后的 Python 示意dataclass class OrderContext: user_id: str lang: str timezone: str trace_id: str is_vip: bool def create_order(ctx: OrderContext, order_data: dict): if ctx.is_vip: ...这样做最直接的好处是一个方法的依赖是什么看签名就知道。测试时随手构造一个OrderContext想测 VIP 就传is_vipTrue想测普通用户就传is_vipFalse不需要关心全局变量里现在是什么状态。3.3 上下文不漏的三个细节第一个细节是入口收敛。无论是 Web 接口、定时任务还是消息队列消费都应该在最外层构造上下文对象后续方法只负责接收。不要在业务方法中重新装配上下文否则很容易出现这边补一个字段、那边漏一个字段。第二个细节是异步边界。如果上下文对象需要跨协程或跨线程传递一定要在创建异步任务时显式传入不要依赖隐式传播。Python 的asyncio.create_task会自动拷贝协程上下文但如果你用的是ThreadPoolExecutorcontextvars默认不会自动传过去必须手动包装。第三个细节是敏感信息隔离。上下文对象里不要塞密码、Token、身份证号这类敏感数据。它只承载当前是谁、当前在哪个范围这种坐标信息而不是承载隐私数据本身降低日志泄露和误用的风险。4. 把 context-mode 用到 AI 编程工具自动、手动与全库检索的选择题4.1 AI 工具获取代码上下文的三种路径现在主流 AI 编程工具在理解代码库时基本靠三种机制拿到上下文。自动感应工具默认读取当前打开的文件、光标附近的代码、最近改动的文件。适合局部修改比如改一个函数、补一个单测。优点是零操作缺点是视野窄。手动引用通过 文件、符号、粘贴代码等方式把指定内容作为上下文显式提供给 AI。适合跨模块改动比如新增一个接口需要同时看 model、service、controller。优点是指哪打哪缺点是要求使用者对项目结构有一定了解。全库检索工具先把整个仓库做成索引再根据问题语义做相似度召回自动找出相关代码片段。适合这条请求链路为什么会卡住这个状态在哪些地方被修改这类需要全局视角的问题。优点是省事缺点是召回质量依赖索引和模型能力偶尔会漏掉关键文件。4.2 实操时我怎么选择任务类型优先使用的方式原因改当前文件里的某个函数自动感应上下文刚好覆盖省事一个需求涉及三四个模块手动引用核心文件让 AI 看到完整链路避免瞎猜排查全局变量被谁改了全库检索只有全局搜索才能列全修改点新项目刚开始AI 不了解业务先贴 README 和架构说明先给它建立项目背景再问细节4.3 一套可以直接照抄的 prompt 模板为了让 AI 拿到足够上下文又不至于被填太满我平时在对话开头套一个模板目标{一句话说清要做什么} 背景{这个模块目前的职责以及为什么需要这个改动} 相关文件{逐个列出并说明每个文件的作用} 参考实现{如果需要参考某段已有写法贴进来} 约束{接口兼容、性能要求、不能动哪些模块等}实际用例如下目标给订单导出功能新增按日期筛选。 背景导出模块目前只支持按状态筛选controller 在 export_controller.py service 在 export_service.py参数校验集中在 schemas.py。 相关文件 - src/api/export_controller.py入口 API - src/services/export_service.py业务逻辑 - src/schemas/export_schema.py入参模型 约束不要改动已有的导出进度查询接口保持响应结构与现有一致。用了这个模板之后AI 回答质量明显提升不再反问你的 query 参数叫什么这类基础问题而是直接给出可用实现。因为你要的上下文都已经摊在它面前了。5. 排查实录一次 AI 重构错误背后的上下文过期5.1 现象AI 一直输出已经删掉的旧方法名有一回我把项目里的buildToken(token, userId)工具方法重命名成createToken(userId, token)参数顺序也调换了。重命名完毕后我在 AI 编程工具里让它重构几个调用方结果它连续三四次输出buildToken(token, userId)的旧写法。我一开始以为是模型能力不行甚至换了个模型重试仍然不对。5.2 排查链路从模型问题查到真正的根因第一步我检查自己的 prompt目标写得很清楚不是提示词问题。第二步我把 AI 输出的代码和仓库里的实际代码逐行对比确认旧方法确实已经不存在了。第三步我怀疑是索引没更新重新索引了项目再问一次还是旧 API。第四步我把当前工具类的最新代码片段手动贴进对话相当于手动提供上下文再问一次一次通过。问题出在对话底层的上下文来源AI 拿到的相关代码片段是旧版本或者它根本没有把重命名后的文件纳入检索范围。无论如何手动补充最新代码后问题立刻消失说明不是模型笨也不是 prompt 不够好而是上下文过期了。5.3 四类上下文问题的识别信号与处置办法我把 AI 编程中遇到的上下文问题分成四类每类都有典型信号问题类型典型信号处置办法上下文缺失AI 频繁问这个类在哪定义这个参数是什么意思先提供项目背景和核心文件再提问上下文污染AI 把无关模块的代码混进答案思路跑偏明确告诉它忽略哪些文件只聚焦引用列表上下文爆炸回答越来越笼统改到后半段忘了开头要求拆小任务一次只处理一个文件或一个函数上下文过期AI 反复使用已被删除的 API 或旧逻辑手动补充当前版本代码并确认索引已更新遇到 AI 回答不准别急着换模型先问自己一句它现在看到的是哪份代码 这是排查一切 AI 编程上下文问题的总纲。6. 把 context-mode 变成团队习惯文档、评审与提示词工程6.1 设计文档里写清决策上下文而不是只写结果很多项目文档习惯写我们把 XX 模块改成了 XX 实现怎么改写得清楚为什么改却不写。但维护成本和 AI 理解成本恰恰都集中在为什么上。我现在写设计文档会专门留一小节叫决策上下文记录当时的备选方案、选择原因、放弃原因。过了几个月无论新同事还是 AI 工具再看到这份文档都能快速进入状态不会重复踩同一个坑。6.2 Code Review 时像查上下文一样查代码我自己的评审清单里固定有几条上下文相关检查新方法是否依赖未在签名中体现的隐藏状态异步或线程池代码里的线程局部变量 / 协程变量有没有清理日志里是否包含 requestId、订单号这类可用于回溯的上下文错误信息是否能让下一个开发者甚至 AI看懂当时发生了什么这几条看似简单但很多线上问题最后都能反推回评审时的疏忽。6.3 一个让我受益匪浅的实践不少开发社区流传代码即文档但我的体会是在复杂系统里光有代码不够还得有上下文。我给自己定的规矩很简单凡是超过三个人维护的模块入口函数必须用一个上下文对象接住环境信息不允许在业务方法里反查全局状态凡是让 AI 干活之前先把背景、相关文件、约束条件装进模板再提问。坚持大半年后无论是人写代码还是 AI 辅助写代码来回返工的次数都少了很多。这套 context-mode 的思路说穿了就是让当前处于什么环境从玄学变成显式事实。你不需要一次把所有模块都改完挑一个让你最头疼的模块先开工就能很快感受到差别。