1. 先搞清楚 context-mode 到底在解决什么——一次“失忆”的排查经历

1.1 没有上下文模式时，多步任务是怎么失控的

最早接触到 context-mode 这个词，是在一次多轮工具链集成翻车之后。我给内部的文档处理工具加一条自动化链路：接收用户上传的文件，提取关键信息，生成摘要，再按用户指定的格式输出。单看每一步，模型都调得很顺；但连起来跑的时候，问题立刻冒出来了——第三步根本不知道第二步总结出了什么。

当时的处理方式很笨：手动把第二步的输出拼进第三步的 prompt。流程只有三四步的时候还好，我可以在代码里一处处写死；但用户中途改需求、失败重跑、步骤加多之后，拼接逻辑就全乱了。更难受的是，每次排查都要把十几个变量翻出来逐个对。后来我才意识到，这根本不是 prompt 写得好不好的问题，而是整个链路缺一套 context-mode，也就是上下文模式机制：让任务在多个步骤之间，能稳定地保存、传递和恢复状态。

这里有个特别容易混淆的点：很多人以为 context 就是“把历史消息塞进模型输入”那么朴素。实际上，如果只是在单次请求里多塞几段历史文本，那还称不上模式；真正的 context-mode 要解决的是整个任务生命周期内，每一步都知道自己从哪来、需要继承什么、执行完要留下什么。它不是某一段 prompt 的补丁，而是贯穿任务编排流程的一种状态管理思维。

1.2 两种主流落地形态：显式传参链与全局上下文对象

我实际落地下来，发现实现 context-mode 基本只有两条路，各有各的代价。

第一种是显式传参链。每一步的方法签名里都带一个 context 参数，从上一步拿到结果，更新 context，再传给下一步。好处是数据流向直白，代码审查时很容易追根溯源；坏处是当链路超过五六步，几乎所有方法的参数列表都会被 context 污染，改一个字段往往要连带改一串调用。比较适合流程短、团队规范强的场景。

第二种是全局上下文对象。系统在任务启动时创建一个 context 实例，后续所有步骤共享这个实例，读写非常方便。坏处同样明显：如果并发控制、生命周期清理没做好，就会出现数据串扰，一个任务的脏数据跑到另一个任务里。这也是我在生产环境里栽得最狠的地方，后面会专门展开讲。

用个生活化的类比：显式传参像接力赛交接棒，每一棒都清清楚楚；全局上下文像一块公告栏，大家都可以贴通知，但不定期清理的话，今天的通知就会被昨天的盖住。到底选哪种，我的经验是：链路短、团队规范强，选显式传参；链路长、模块多、需要断点恢复，就必须上全局上下文，但一定要把隔离和清理做好。

提示：不管选哪种，先别急着写代码。把任务拆成“步骤边界”和“状态字段”两件事——哪一步结束需要保存什么、哪一步开始需要读取什么，定义清楚之后，实现难度会下降一大截。

1.3 一个必须厘清的定义：“带历史消息”不等于 context-mode

我见过不少人把“prompt 里塞历史记录”直接等同于 context-mode，这是最容易踩的概念误区。你可以把最近十轮对话全部塞进请求里，模型确实能“记住”前面的内容，但这一步做完之后呢？如果下一次执行不是接着这个请求继续，而是从另一个入口重新发起，刚才那十轮历史就彻底丢了。

context-mode 更强调生命周期内的状态可保存、可注入、可恢复。历史消息只是注入层的一种表现形式，真正的核心在于“状态在任务边界内流转，而不是被一次性消费”。举个例子，模型生成摘要后把结果存进了 context，后续格式化步骤读取时并不需要重新调用模型，而是直接消费上一轮的产出。这种跨步骤复用，才是“模式”二字的含义。

理解了这一点，再回头看各种框架和工具，你会发现它们其实都在做同一件事：定义状态的边界、传递方式、恢复手段和清理时机。把这件事做好，上下文模式才真正落地；做不好，那就只是给巨长的 prompt 再加了几段文字罢了。

2. 从零实现一个可恢复的 context-mode：状态保存、注入与遗忘

2.1 核心数据结构：一张 context 表管理任务状态

前面聊了理论，这里给一份我常用的最小实现。我习惯用 Python 写快速原型，核心是一个 Context 对象，典型结构长这样：

@dataclass class TaskContext: trace_id: str # 一次任务的唯一标识，用来隔离并发 stage: str # 当前执行到哪个步骤 payload: dict # 实际保存的状态数据 step_token: str # 幂等标识，防止重试时重复执行 created_at: float updated_at: float expire_at: float # 过期时间，防止上下文永远占用存储

落到存储里时，我会先做成 JSON 快照，方便调试时直接打开看：

{ "trace_id": "task_20240518_001", "stage": "extract_done", "payload": { "file_path": "/data/uploads/report_q1.pdf", "extracted_summary": "一季度营收同比增长12%", "output_format": "markdown" }, "step_token": "stage_extract_done_v1", "expire_at": 1716100000 }

每个字段都有存在的理由。trace_id是隔离的第一道锁，没有它，并发场景必然出事；stage让你一眼看出任务卡在哪一步；payload存放真正的业务状态；step_token是给失败重试用的，后面会细说；expire_at是兜底的“遗忘保险丝”。

关键设计点在于 payload 里不要存大对象。比如文档处理场景，你只需要存“提取后的摘要文本、文件路径、目标格式”，而不是把整个文档内容堆进去。这样能避免上下文膨胀，也能降低后续注入时的 token 消耗——尤其是跟大模型交互时，上下文过长会直接影响响应速度和质量。

2.2 注入与回写：每一步的前后都做了什么

有了数据结构后，真正要设计的是“读”和“写”的时机。我最开始犯过错误，只在任务完成后统一写一次上下文，结果中途任何一步失败，整个链路就丢了前面的进度。

正确做法是每步执行前读、执行后写。可以做一个简单的编排入口：

def run_stage(ctx: TaskContext, stage_fn): # 1. 从存储恢复上下文（或按 trace_id 新建） ctx = load_context(ctx.trace_id) or new_context(ctx.trace_id) # 2. 根据当前步骤声明所需字段，构造注入数据 stage_input = build_stage_input(ctx, stage_fn) # 3. 执行步骤，拿到本步新增的状态 result = stage_fn(stage_input) # 4. 把新增状态合并进 payload，并更新步骤标识 ctx.stage = stage_fn.__name__ ctx.payload.update(result.new_state) ctx.step_token = stage_fn.__name__ ctx.updated_at = time.time() save_context(ctx) return ctx

这四步看起来平平无奇，但每一行都有讲究。第 1 步保证任务可以从断点恢复；第 3 步我要求所有 stage 方法都返回new_state，而不是直接改全局变量，目的是让每个步骤的产出显式化，后面排查“谁改了什么”时特别有用；第 4 步的update采用合并而不是整体覆盖，否则上一步留下的字段会被意外清掉。

build_stage_input很多人会忽略。我的做法是让每个步骤声明自己需要哪些字段，编排层按声明做白名单过滤，只暴露该步骤真正用得到的状态。这样既避免步骤之间隐式依赖，也能在字段缺失时报错，而不是硬着头皮传 None 进去。

2.3 遗忘机制：什么时候清空、靠什么防止脏数据

context-mode 里最容易被忽略的是“遗忘”。很多问题不是出在没保存，而是出在不该有的东西被一直保留。

我设置了三类清理策略：

• 任务完成时主动清理：无论成功还是失败，只要走到了终止分支，就立刻删除或给 context 打上“已结束”标记。
• TTL 过期清理：给每条 context 设置expire_at，配合定时清理任务扫描。这样即使进程崩溃、主动清理没执行到，上下文也不会永久驻留。
• 敏感字段过滤：在写入 payload 前做字段白名单校验，只允许写入配置过的业务字段，其他临时变量一概不允许进入 context。

为什么要强调遗忘？因为失败的清理往往比成功的清理更重要。我碰到过一次事故：某个环节异常，代码抛异常后直接跳过了清理逻辑，结果 context 里残留了上一个用户的文件名，下一个任务在拼接路径时读到了脏数据，排查了整整两小时。设置 TTL 后，兜底效果立刻体现出来。

2.4 重试场景下的幂等：step_token 如何避免重复执行

长链路任务没有重试机制是不现实的，但重试会带来一个隐形问题：第 3 步已经成功执行，网络刚好在“回写”前断掉，导致从存储角度看第 3 步没完成。重试时第 3 步会被再次执行。如果第 3 步是调模型生成摘要这种有副作用的操作，重复执行不仅浪费成本，还可能产出完全不同的结果。

这时候step_token就派上用场了。执行前检查当前 token 是否已经等于目标阶段，如果相等，说明本步骤执行过，直接返回现有状态，不再调用步骤函数：

def run_stage(ctx, stage_name, stage_fn): if ctx.step_token == stage_name: logging.info(f"skip {stage_name}, already done") return ctx result = stage_fn(build_stage_input(ctx, stage_fn)) ctx.payload.update(result.new_state) ctx.step_token = stage_name ctx.stage = stage_name save_context(ctx) return ctx

这个设计把“执行步骤”和“标记完成”绑定在同一个回写事务里，虽然我们不能保证进程级原子性，但至少可以在重试时避免重复执行。实际应用中，我会再把save_context改成条件更新，确保 token 已变更时拒绝覆盖，进一步降低并发重试的冲突概率。

到这里，一个能够“保存、注入、遗忘”的 context-mode 最小闭环就成型了。接下来聊我踩得最惨的部分——生命周期管理。

3. 真实项目里最容易翻车的是生命周期管理

3.1 第一个大坑：上下文污染，上一个任务的残留数据串到下一个任务

先说现象。某天我发现测试环境里，用户 A 的周报里出现了用户 B 的部门名称。第一反应是数据查错了，但查完发现数据库没问题，问题出在上下文层。排查链路大致是这样的。

第一步，先看 context 的写入端，确认是不是同一个 key 被多个业务共用。那里我确实偷懒了，直接把“部门”存成了全局 key，没有按trace_id做维度隔离。这是根源之一。

第二步，再看清理时机的边界。我发现清理逻辑只在任务正常完成的路径上执行，失败分支用的是另一个入口，两处代码各自维护了一套 context 操作，失败分支漏了清理调用。

第三步，复现验证。在失败分支后立刻发起新任务，发现新任务启动时load_context()读到的还是旧任务留下的 payload。最终问题定位在“没有按任务维度隔离 + 失败分支未清理”两个因素叠加。

修复方案很直接：所有 context 的读写强制带上trace_id作为第一层 key；清理逻辑统一收敛到一个finally块里，任何退出路径都必须经过它。这里再用守护式代码演示下：

def run_pipeline(trace_id, stages): try: ctx = load_context(trace_id) or new_context(trace_id) for stage_fn in stages: ctx = run_stage(ctx, stage_fn.__name__, stage_fn) finally: # 无论成功失败，统一走这里 if ctx: complete_task(ctx.trace_id)

3.2 并发场景下 context 互相覆盖

另一个翻车点是并发。早期我用一个全局 dict 当存储，A 请求刚写入payload["file_path"]，B 请求进来直接覆盖成自己的路径，A 下一步执行时读到的完全是 B 的数据。

用一张表格可以看得很清楚：

排查时让我印象深刻：单线程压测完全正常，一上并发就随机出现“灵异数据”。后面把并发数调到 10，加上 trace_id 日志，才发现是两个请求共用了同一个 context 实例。

解决方式是用trace_id做隔离分桶：

class ContextStore: def __init__(self): self._buckets = {} # trace_id -> TaskContext def get(self, trace_id: str) -> TaskContext: return self._buckets.setdefault(trace_id, new_context(trace_id)) def remove(self, trace_id: str): self._buckets.pop(trace_id, None)

这个改动看似简单，背后是一个核心认知转变：context 不是一个全局变量，而是一组按任务维度隔离的变量集合。先把隔离做对，再谈状态共享才有意义。

如果你用的是 Redis 这类外部存储，同样要给 key 加上trace_id前缀，并注意设置过期时间。千万别把不同任务的 context 塞进同一个 hash 结构里无脑追加字段，那样等于回到全局 dict 的老路。

3.3 调试 context 时的 diff 日志，省掉一半排查时间

踩过几次坑后，我养成了一个习惯：不管哪一步执行完，都打一段 context diff 日志，记录本次注入了哪些字段、新增了哪些字段、哪些字段发生了变化。不要求复杂的链路追踪工具，一个极简函数就够用：

def log_context_diff(before: dict, after: dict): added = set(after) - set(before) removed = set(before) - set(after) changed = { k for k in set(before) & set(after) if before[k] != after[k] } logging.info(f"added={added}, removed={removed}, changed={changed}")

实际输出大概长这样：

added={'extracted_summary', 'output_format'} removed=set() changed={'stage': 'upload_done' -> 'extract_done'}

有了这段日志，大部分问题都能快速定位：谁写多了、谁删少了、谁改错了，一目了然。我甚至建议在测试环境把 diff 日志调到 debug 级别常开，配合 trace_id 过滤，能覆盖 90% 的上下文问题排查场景。生产环境则至少保留 error 级别的 diff 日志，方便事后回溯。

3.4 上线前的生命周期检查清单

基于前面这些坑，我整理了一份上线前必过的清单，现在每次接入 context-mode 都会照着走一遍：

• 每个 context 是否都带trace_id隔离？有没有漏掉写操作的路径？
• 清理逻辑是否收敛到统一出口？失败分支和异步回调里有没有遗漏？
• 是否设置了 TTL？过期时间是否覆盖任务最大执行时长？
• 每个步骤写入的字段是否经过白名单校验？
• 重试场景下有没有step_token做幂等保护？
• 有没有为每个步骤打 diff 日志？

这份清单帮我挡掉过至少三次线上事故。上下文模式的复杂度大多不在“能不能跑通”，而在“跑着跑着会不会被历史状态污染”。

4. context-mode 到底该怎么选型：什么场景值得上，什么场景别硬上

4.1 真正适合 context-mode 的场景

聊到选型，很多人容易走极端：要么觉得 context 很麻烦，一律不用；要么想把所有状态都塞进去。我的经验是看三个信号。

第一，任务是否跨步骤依赖历史。比如 AI 多轮工具调用：第一轮用户说“帮我看一下上个月的报表”，第二轮说“按部门拆一下”，系统必须知道“上个月的报表”指哪个文件。这就是典型的跨步骤依赖，没有 context-mode 的话，每轮都要重新解释上下文，成本不可控。

第二，是否允许断点恢复。长耗时流水线、审批流、数据同步任务，一旦中间失败就要从头再来，代价很高。此时 context-mode 的保存与恢复能力非常值钱，可以让任务从最近成功的步骤继续往下跑。

第三，是否存在多个模块共享同一份业务快照。比如订单处理链路里，支付模块、库存模块、通知模块都需要知道订单号、金额、用户 ID。与其各自查库，不如通过 context 统一注入，既减少重复计算，也保证模块间看到的数据版本一致。

符合其中两条，基本就可以放心引入 context-mode 了。架构上它会成为任务编排的中枢，之后加新步骤、改流程顺序，改动成本都会明显下降。

4.2 不该上或要慎用的场景

反过来也要说清楚，有些场景硬上 context-mode 只会徒增复杂度。

单一无状态接口是最典型的不该用场景。用户请求一次、返回一次，没有任何后续环节，那就保持纯粹的函数式调用，不要额外引入 context 存储，否则每次请求都要多一次读写，延迟和故障点都多了。

跨模块访问非常低频的场景也不必用。如果两个模块一年难碰一次面，各自独立查库更简单直接。强行引入共享上下文，反而增加模块间的隐式耦合，排查问题时还得追踪上下文在哪个环节被谁改了。

对一致性要求极高、同时对延迟敏感的核心交易链路，也要谨慎。context 的快照机制天然有“短暂不一致”窗口：写入上下文和真正完成业务操作并不是原子的。如果系统不允许这种窗口，就得配合事务消息或数据库事务来解决，复杂度会远超上下文模式本身的收益。

我用一张表总结自己的选型判断：

4.3 现成生态里的参考：从 React Context 到 AI 对话框的新对话按钮

最后想扩一下视野。context-mode 不只是后端任务编排专用的东西，很多你已经在用的工具，本质都是它的变体。

前端开发里的 React Context，解决的是“跨组件层级共享状态而不必逐层透传 props”的问题，底层实现就是维护一个组件树级别的上下文对象。组件挂载时提供上下文，消费组件读取上下文，卸载时清理。这在思想上跟任务编排里的上下文注入完全同构。

AI 聊天工具里的“新对话”按钮，本质上就是一次清空上下文。你在一个对话里聊得再深，开启新对话后模型就完全“失忆”了。这正是上下文生命周期管理在消费端产品里的体现——可以说，“新对话”就是最优雅的上下文清理入口。

CI/CD 系统里的 workspace 持久化也一样。流水线的不同 stage 共享同一个工作区，每个 stage 运行完留下的中间产物，下一个 stage 通过固定路径读取。这就是文件系统维度的 context-mode，只是载体从内存换成了磁盘。

理解了这层同构关系，再看自己的项目就会多一个视角：凡是需要跨步骤、跨模块、跨时间保持一种可恢复的状态，都可以用上下文模式的思维重新审视一遍。而一旦你看清了边界在哪，也就知道哪些场景根本不需要引入这套复杂度。

我个人的体会是，context-mode 最核心的价值不在技术本身，而在于它逼着你把“任务的边界”想清楚——每一步需要什么、产生什么、丢弃什么。想清楚这三件事，代码怎么写都不会乱；想不清楚，再高级的框架也只是在给混乱叠 buff。