Agent 跑到一半上下文先爆了这是所有搞过 LLM Agent 的人都会撞上的墙。这个系列写到这里已经是第十六篇前面一直在拆 DeepSeek-Harness 这个框架怎么把 Agent 的调度、工具调用、多轮推理组织起来但这几期内容做完之后你会发现真正决定一个 Agent 能不能在长任务里活下来的不是它能想多少步而是它能不能在上下文撑爆之前把该留的东西留下来在进程崩掉之后把该救的东西救回来。所以这一篇专门聊两个机制上下文压缩 Compaction以及 Checkpoint 持久化。前者解决“上下文太长模型记不住重点”后者解决“任务跑了一半进程没了一切归零”。这两件事单独拎出来都能写不少但放在一个 Agent 执行框架里它们其实是同一个问题的两面如何让长时间运行的 Agent 保持状态的可控性。这篇文章我把设计思路、触发时机、序列化方案、恢复流程以及我实际踩过的坑全部展开。1. 为什么 Agent 跑着跑着就“忘重点”Compaction 与 Checkpoint 要解决什么1.1 上下文爆炸是怎么来的很多人在第一次跑多步骤 Agent 的时候都会有一个直观感受前几轮还挺聪明十几轮之后就开始胡言乱语甚至频繁报错。原因不复杂——上下文里塞进了太多东西模型被迫在大量低信息量的内容里寻找那一点点关键线索。Agent 的执行方式和单次问答完全不一样。单次问答你给它一个问题、一段资料它答完就结束。Agent 则是循环式的思考 → 调用工具 → 拿到结果 → 再思考 → 再调用。每一轮思考会生成推理文本每一次工具调用会带回 JSON 返回、日志、错误信息、表格数据甚至整个文件内容。这些内容全部追加到历史消息里越积越多。举个例子。一个做资料汇总的 Agent先检索到 10 篇文档每篇 5000 token 的内容都会被打包成工具返回结果。然后又调用了两轮筛选、一轮摘要整合。等它开始写最终报告的时候上下文里已经堆了七八万 token。这里面真正对最终决策有用的可能只有最开始的需求描述、筛选条件、还有最后几轮的判断中间那一大坨原始文档早就没用了但它们仍然占着窗口。更麻烦的是所谓的“迷失在中间”现象。模型对上下文开头和结尾的内容感知力最强中间部分很容易被忽略。几千行工具返回的 JSON 夹在历史中间模型要么扫一眼就略过要么被干扰最后给出的决策质量明显下降。上下文不是越大越好而是“有效信息密度”越高越好。1.2 不压缩的代价不只是“报错”这么简单如果上下文只是超限报错那问题反而好解决。真正麻烦的是还没到上限模型已经开始降智。我不知道你们有没有遇到过这种情况Agent 明明还在运行错误率却明显上升重复调用同一个工具或者绕来绕去就是不执行关键步骤。这就是上下文信噪比太低导致的。还有两个容易被忽略的代价成本和延迟。现在主流的 API 计费方式里输入 token 是要真金白银付钱的。一个任务跑两个小时假设有 10 万 token 的固定历史一直被重复发送那每多一步推理就多付一次这 10 万 token 的费用。延迟也一样——每次请求都要处理完整的历史首 token 延迟会随着上下文变长而逐渐上升长任务到后期会明显感觉“变慢”不只是模型思考慢是传输和预填充都在变慢。Compaction 的定位就在这里在上下文达到危险水位之前主动对历史做一次“提炼”把冗长的工具结果和重复的推理过程压缩成一段结构化摘要让模型继续带着最关键的信息往前跑。1.3 Checkpoint 解决的是“一切归零”的恐惧上下文压缩解决的是“模型记不住”Checkpoint 持久化解决的是“进程活不长”。Agent 任务往往不是几秒钟就能跑完的。一个复杂的调研任务、一个批处理的数据分析任务、一个需要多轮人工确认的流程跑几十分钟甚至几小时都很正常。而在这段时间里进程可能因为各种原因挂掉线上环境中被 OOM kill、网络抖动导致 API 连续超时、底层的 Worker 节点被重新调度甚至只是某人手滑重启了服务。如果没有持久化机制所有这些场景的结果都一样任务状态丢失下次启动从零开始。这个代价在短任务上还好在长任务上就是灾难。想象一下一个数据分析任务前 40 分钟已经把数据拉取、清洗、特征工程全做完了就剩最后一步建模结果进程崩了。重来一遍不仅浪费 40 分钟还可能要重新支付所有中间步骤的 API 费用和工具调用费用。Checkpoint 就是游戏里的存档点。定期把 Agent 的运行状态——对话历史、任务队列、中间变量、工具调用记录——全部写到持久化存储里。进程挂了不要紧重新拉起找到最近的存档点继续往下跑。1.4 两者为什么必须配合使用单独做压缩或者单独做持久化都有点偏科。只做压缩不持久化上下文是短了但进程一崩溃压缩后的摘要也一起没了。只做持久化不压缩你确实能把完整历史存下来但恢复之后还是要面对一个上下文爆炸的问题甚至可能因为历史太长根本无法恢复。所以两者是配套关系运行过程中定期压缩让上下文保持低水位压缩完成后立即打一次 checkpoint把提炼过的状态固化下来。这样每次存档的内容都是精炼过的恢复时不用重新读入大量无用历史直接带着摘要继续跑。DeepSeek-Harness 里对这两件事的整合逻辑本质上就是一条流水线执行 → 验证 → 压缩 → 存档 → 继续执行。2. 上下文压缩 Compaction不是“砍内容”是“换组织方式”2.1 先说清楚压缩到底在压什么很多第一次写压缩逻辑的人会犯一个错误把历史消息截断只留最后几轮。这种做法确实能快速降低 token 数但基本等于让 Agent 失忆。任务目标、关键约束、已经确认过的事实全都丢了后续根本没法做正确决策。正确的思路是压缩掉的应该是“可还原性低”的内容保留的应该是“决策依赖度高”的内容。什么意思呢工具返回的一整份 JSON 原始数据如果它只是中间产物后续决策仅仅依赖其中几个字段那这份 JSON 就可以被压缩成一个“事实列表”而用户最初的任务描述、系统的安全约束、Agent 自己已经做出的关键决策和未完成计划这些是模型每一步推理都必须看到的绝对不能丢。我习惯把需要压缩的内容分成三类可以丢弃的过程噪音重复的失败尝试、无关的日志、已经完成且不再引用的中间步骤细节。这些东西压缩时可以直接丢弃不进入摘要。可以摘录的原始数据工具返回的大块内容如果后续可能用到保留其中的关键字段或结论如果后续不会再用到直接不留。必须原样保留的决策上下文任务目标、用户偏好、系统规则、当前进度、尚未执行完的待办清单。这些内容即使已经出现在前面的对话里压缩后的摘要里也要有一份完整的“复议版本”。这里有个原则值得写下来压缩的目标不是让历史变短而是让历史里的“信息密度”变高。哪怕压缩后的摘要仍然有几千 token只要它是高密度的关键信息就比原来几万 token 的混杂堆更有效。2.2 主流压缩策略怎么选实际操作中压缩策略主要有这么几类各自适用场景不一样先说说摘要式压缩。这是目前最通用的一种方式调用一次 LLM让它阅读当前的历史消息输出一段结构化的摘要。优点是可以做到语义上的提炼缺点是多一次模型调用有延迟和费用。摘要模型可以比主模型小比如主模型用大参数模型压缩用一个小一号的模型就够。然后是抽取式压缩。不用 LLM规则化地从历史里抽取关键信息比如所有工具调用里的成功标记、错误码、返回结果里匹配特定 pattern 的字段。优点是快几乎零延迟缺点是理解力有限如果原始内容里没有显式的关键标记容易漏掉重要信息。还有结构化压缩。这是摘要方式的变体不要求 LLM 输出自由文本而是要求它把历史整理成 JSON比如{facts: [...], decisions: [...], pending_tasks: [...], obsolete: [...], compaction_strategy: full}。这种方式的最大好处是机器可读后续如果再叠加别的处理逻辑比如自动检索摘要里的某个字段会非常方便。最后一类比较少用但值得提的是滚窗压缩。它不是单次把全部历史压缩而是只保留最近 N 轮完整消息更早的全部并成一段摘要。这样实现简单但对 N 的选择比较敏感N 太小模型的短期记忆不够N 太大窗口一样会被占满。在实际项目里我比较推荐结构化摘要作为主策略因为它把“信息是否保留”的决策更多地从模型手里移交到了工程手里。模型只负责把历史朗读为结构化事实工程负责决定哪些事实进最终上下文。这比让模型自由发挥写一段“总结”要稳得多。2.3 触发时机别等窗口满了才动手压缩触发得太晚上下文已经逼近模型上限就算压缩也会因为历史太长导致压缩质量下降触发得太早频繁调用压缩模型浪费时间不说还可能把尚未完成的关键任务信息误伤。我建议设定两个水位线。第一个是告警水位比如上下文占用达到模型窗口的 60% 或 70%。到了这个水位启动压缩逻辑。第二个是危险水位80% 或者 90%。如果压缩还没来得及执行或者压缩失败至少要强制丢弃一些最低价值的内容比如最早的调试日志绝不能让请求真的超限。在 DeepSeek-Harness 的执行流程里我使用的是以 token 计数为基础、以事件为辅助的混合触发方式每一轮推理结束后统一次 token另外在工具调用返回超大结果时不等到下一轮结束就立即触发压缩因为超大的工具结果往往是上下文暴涨的元凶。token 计数这个细节不要省。不同模型的 tokenizer 不一样用字符长度估 token 数误差很大最好直接用模型对应的 tokenizer 来数。如果框架里没集成可以简单按“英文约 4 字符一个 token、中文约 1.5 到 2 字一个 token”的经验公式做估算但在告警水位附近要留出余量。2.4 压缩流程的执行要点一次完整的压缩我建议至少走这几步第一步是盘点。把当前消息列表拆成几个分区系统提示区、任务目标区、历史对话区、工具结果区、最近对话区。前两类无论如何都完整保留工具结果区是压缩的主要目标历史对话区里较早的部分也纳入压缩最近对话区保持原样。第二步是生成摘要。调用压缩模型时给它明确的指令格式要求输出结构化 JSON。一个实用的压缩提示词大概长这样你是信息压缩器。请把以下对话历史压缩为 JSON 对象包含 - summary: 一段 200 字以内的整体进展摘要 - facts: 已确认且后续仍需引用的事实列表 - decisions: Agent 已做出的关键决策及其理由 - pending: 尚未完成的步骤或待办事项 - discarded: 被丢弃的无价值内容描述 要求不要新增任何原文不存在的信息不要修改事实尽量保留可验证的细节。第三步是把摘要插入消息列表。插入位置应该在原始历史之前同时给摘要消息加一个特殊的role: system或者自定义标记比如compaction_marker让模型知道从这之后的内容是历史压缩包不是当前正在发生的对话。第四步是校验。压缩完成后先别急着继续跑。检查摘要里是否包含任务目标关键词、是否包含所有 pending 项、是否因为摘要过长而仍然超限。如果摘要质量不过关宁可降低压缩比例重新压也不要拿一个残缺摘要去糊弄主模型。这里有一个实操细节压缩后的摘要不要放在消息列表的末尾要放在历史开头。原因很简单模型对上下文开头的内容注意力最强把压缩摘要放在开头相当于给模型一个“先看重点”的线索。3. Checkpoint 持久化状态清单、序列化与恢复流程3.1 到底要保存哪些状态很多人写 checkpoint 的时候只想着“把 messages 存起来”。但真正跑起来就会发现光有 messages 并不足以恢复一个 Agent 任务。一个完整的 checkpoint 至少需要包含五类信息第一是任务元数据任务 ID、启动时间、最近更新时间、compaction 次数、当前阶段编号。这些信息在任务编排、监控、故障排查时都要用缺了任何一项后续都很难定位问题。第二是对话历史包括原始 messages 数组和已压缩的摘要。这里需要注意的是消息对象的 schema 必须稳定。每一条消息至少包含role、content、timestamp、step_id有工具调用的还要带tool_call_id。缺少时间戳和 step_id恢复时顺序一乱上下文就废了。第三是 Agent 的内部状态。不同框架的内部状态不一样可能是状态机里当前正处于哪个节点也可能是决策树里已经走过的分支。这部分必须和对话历史一起保存否则恢复后模型“失忆”内部的执行器也不知道自己该干吗。第四是待执行队列和进行中的工具调用。比如 Agent 已经发起了一个工具调用结果还没回来。checkpoint 里要记录这个调用是“已发出未返回”还是“已返回未处理”。这两者的恢复策略完全不同前者需要等待或者重试后者可以直接消费结果。第五是环境信息。包括当前工作目录、已经创建临时文件路径、依赖的会话 ID 等。很多 Agent 框架会调用本地环境或者外部系统这些环境侧的“副作用状态”不保存恢复后 Agent 就找不到自己之前留下的临时文件了。3.2 序列化与存储选型存储方案的选择直接影响 checkpoint 的可靠性和性能。我梳理一下常见的选型。首先是 JSON 文件存储。最简单直接把 checkpoint 对象 dump 成 JSON 写到一个指定目录。优点是可读性好、排查方便缺点是体积大、写盘慢。适合任务量不大、单机运行的场景。然后是 SQLite。把每一条消息、每一个状态字段拆成表结构写入。优点是有事务支持不容易写坏缺点是需要多做一层 schema 设计。适合需要频繁读写、担心写入中间态损坏的场景。还有 MessagePack 这类二进制序列化。体积比 JSON 小很多、解析快缺点是调试不直观。适合对性能要求高、checkpoint 体积较大的场景。最后是外部 KV 存储比如 Redis 或对象存储。优点是天然支持分布式场景多实例可以共享缺点是需要额外维护这份基础设施。如果 Agent 框架跑在集群里或者有跨节点容错需求这一步基本是必选项。我自己在 DeepSeek-Harness 这个项目里的建议是做一个可插拔的 Storage 接口本地开发用 JSON 文件、生产环境接 SQLite 或对象存储。不要刚起步就套一个复杂的数据库等真的有并发和持久化需求了再升级。但接口隔离这件事要一开始就做好不然后面改起来会很痛。3.3 保存时机事件驱动加定期快照checkpoint 保存太频繁性能扛不住保存太稀疏恢复时损失太大。怎么平衡我用的策略是“事件驱动 周期快照”。事件驱动指的是在某些关键节点强制保存工具调用完成之后、Agent 做出重大决策之后、上下文压缩完成之后。这些节点是任务状态最容易发生质变的时候也是“恢复后继续跑”需要的最低起点。举个例子Agent 刚执行完一个耗时很长的工具调用并拿到结果如果在这时候崩溃结果就丢了所以拿到结果后的第一件事就应该是保存。周期快照则是一个兜底不管有没有关键事件每运行 N 步比如 N20或者在固定时间间隔比如 60 秒保存一次。这样即使某些状态变更没有被事件驱动捕捉到也能保证整体进度不会丢失太多。还有一个细节压缩完成后必须立即保存。压缩本身是有损操作一旦压缩完但没保存就崩溃恢复时你是该用压缩前的完整历史还是压缩后的摘要都没有。所以压缩和保存绑定成同一步——先换组织方式再落地存档这种方式从根上保证恢复时一致性。写入动作本身要注意原子性。直接写目标文件不是一个好主意因为如果写入过程中进程崩溃文件可能处于半写状态。建议先写临时文件写完 fsync 落盘再用 rename 替换旧文件。这套“临时文件 rename”的操作在很多基础软件里都是标准做法成本极低安全性提升很多。3.4 恢复流程比保存更考验设计恢复流程的设计比保存更容易翻车。我见过一个项目checkpoint 保存的时候好好的恢复后 Agent 还是行为异常后来发现是恢复顺序有问题。一个清晰的恢复流程大概是这样的第一步是定位。根据传入的任务 ID 找到最近的 checkpoint 文件并解析为对象。如果最近的一份损坏自动回退到上一份。所以保存的时候建议保留最近 2 到 3 个轮转版本别每次都覆盖唯一文件。第二步是校验。检查 checkpoint 的 schema 版本号确认和当前代码兼容不兼容则报错停止绝不尝试硬恢复。校验消息列表连续完整。校验待执行队列里的工具调用 ID 是否在历史中有对应记录。第三步是重建上下文。把压缩摘要和最新的原始消息按顺序重新拼接成完整的 messages 数组。然后做一次 token 统计如果恢复后的上下文已经接近窗口上限立即先执行一次压缩再继续。第四步是恢复 Agent 状态。把内部状态机、待执行队列、工具调用进度全部加载回内存。第五步是继续执行。不要从头开始跑而是直接从最后的事件点恢复执行。这里特别要注意工具调用的幂等性如果某次工具调用在 checkpoint 之前已经成功执行但结果还没来得及记录这种窗口很难完全消除恢复后可能会重复执行。解决办法是给每次工具调用生成唯一 ID在执行器层做去重已经处理过的 ID 直接复用结果不真实执行。4. 实操记录一条带压缩与存档的执行主循环4.1 执行流程的骨架实现这一节直接给一个可参考的实现骨架演示如何把 Compaction 与 Checkpoint 嵌入 Agent 的主循环。这里用 Python 风格的伪代码核心逻辑可以直接搬到自己的框架里。class AgentRuntime: def __init__(self, storage, token_counter, max_context_tokens): self.storage storage self.token_counter token_counter self.max_context_tokens max_context_tokens self.alert_watermark int(max_context_tokens * 0.65) self.danger_watermark int(max_context_tokens * 0.85) def run(self, task_id, initial_messages): ckpt self.storage.load(task_id) if ckpt: history, agent_state, pending_queue self.restore(ckpt) else: history initial_messages agent_state {} pending_queue [] for step_index in range(agent_state.get(step, 0), MAX_STEPS): # 1. 执行一步推理 result self.llm_step(history, agent_state, pending_queue) # 2. 如果发起工具调用执行并记录结果 if result.tool_call: tool_result self.execute_tool(result.tool_call) history self.append_tool_result(history, result.tool_call, tool_result) # 工具完成后是关键事件立即存档 self.storage.save(task_id, self.build_checkpoint(...)) # 3. 检查是否需要压缩 current_tokens self.token_counter.count(history) if current_tokens self.alert_watermark: history self.compact_history(history) self.storage.save(task_id, self.build_checkpoint(...)) # 4. 周期性存档兜底 if step_index % 20 0: self.storage.save(task_id, self.build_checkpoint(...)) self.storage.save(task_id, self.build_checkpoint(...))这段主循环看起来很直白但几个细节不处理就会出问题。第二个检查点里的“压缩完成之后立即存档”是我踩过坑才加上去的。之前我的代码是先压缩、再继续执行、等下一个保存点才存档。结果有一次压缩完成了Agent 又调了一轮工具然后崩溃。恢复的时候拿到的还是压缩前的完整历史压缩白做了而且因为工具结果已经录入历史比压缩前更长了直接从告警水位变成了危险水位。4.2 压缩模块的调用细节压缩函数的实现藏了很多细节。一份好的摘要必须保持历史中决策链条的完整性。我在项目里是这样实现的def compact_history(history): protect_roles {system, task} preserved [m for m in history if m.role in protect_roles] compactable [m for m in history if m.role not in protect_roles] compact_prompt build_compact_prompt(compactable) summary call_compact_model(compact_prompt) new_history preserved [ { role: system, content: f[COMPACTION_MARKER] {summary}, msg_type: compaction_summary timestamp: now(), } ] return new_history注意一个问题被保留的 system 和 task 消息通常已经出现在历史开头了但如果 Agent 在运行过程中动态追加过约束条件比如用户中途补了一句“不要用这个接口”这条追加的约束并不会出现在最初的 system prompt 里如果不一起保护压缩后就会丢失。所以“protected”不能简单按角色判断还要把后续对话中标记为is_constraintTrue的消息也保留下来。我在框架里给消息对象加了一个is_constraint字段工具调用结果也被允许标记成约束比如“接口返回 401后续禁止使用该接口”。压缩时凡是带这个标记的一律不纳入压缩范围。4.3 一次完整的压缩与存档记录把上面的逻辑拼起来一次“压缩 存档”的流程是这样的先看上下文计数。假设窗口是 128K token告警水位设在 83K。某轮工具返回了一个 2 万 token 的 JSON计数直接跳到 90K。触发压缩。压缩选中的范围是 40 条历史中的 35 条工具返回的原始 JSON 和早期中间推理全部交给压缩模型处理。保护的部分是任务描述、新增约束、最近 2 轮的完整对话。压缩模型返回的结构化 JSON 被解析后组装成一条 1500 token 的摘要消息插入历史开头。消息列表从 90K 降到 20K 左右。然后立即调用 storage.save把任务 ID、消息列表、Agent 内部状态、压缩次数1写入 SQLite。写入用临时文件加 rename全程大约 80ms。之后 Agent 继续下一轮推理。这个流程走顺之后热点只有一个压缩模型本身的质量。摘要模型如果是小模型可能在“事实提炼”上不够精确把关键细节漏掉。我在实际项目里遇到的解决方案是做二次校验用规则检查摘要里是否包含所有 pending 项不包含就重压缩。这个规则检查非常快值得加上。5. 常见问题与排查实录来自一线的避坑清单5.1 压缩之后 Agent 明显“变笨了”这是最常见的反馈。特征是压缩前 Agent 决策清晰压缩后开始重复问同样的问题、忽略已经确认过的事实甚至把摘要里的旧信息当成当前状态来用。排查思路先把压缩前后的消息列表拉到一起对比看摘要里是否还包含这些要素——任务目标、关键事实、已做决策、待办事项。缺哪补哪。如果摘要信息都有但 Agent 还是变笨那问题可能出在摘要的位置上它是不是被插到了特别靠后的位置或者摘要消息的role被设置成了assistant让模型误以为这是某轮输出而不是“历史说明”。把role固定为system、msg_type标记为compaction_summary并加一个显式的说明语句比如“以下是此前的对话摘要不是真实消息仅用于参考”效果会好很多。另外检查一下是不是压缩频率太高。如果每两轮就压缩一次模型每次都面对一个“新格式”的旧历史本身就容易产生混乱。把告警水位调高一点减少压缩次数通常会改善。5.2 checkpoint 恢复后上下文错乱恢复后发现顺序不对、时间线混乱、摘要和真实历史混杂。大概率是消息对象没有统一的时间戳字段或者恢复时按文件中的存储顺序直接加载而没有按时间戳排序。我的建议是在写入消息时强制带上timestamp和step_id恢复时先按step_id排序再按timestamp校验。step_id比时间戳更可靠因为多个消息可能出现在同一毫秒内而step_id是在执行循环里递增生成的保证严格有序。还有一种情况恢复时把压缩摘要和原始消息混在了一起且没有保留压缩边界标记。新模型读到摘要消息和后续的真实消息无法分辨哪些是“之前发生的事”哪些是“现在正在发生的事”。解决办法就是上面提到的在摘要消息上用compaction_marker显式标出边界。5.3 同一个工具被重复执行了多次这个问题的根因不在 Compaction而在 checkpoint 的保存时机。如果工具调用已经发出、结果也已经返回但在这两件事之间发生了崩溃恢复后 Agent 将重新发送同一个工具调用。最稳妥的解法是工具调用幂等化。给每个工具调用生成一个唯一 IDUUID在框架层维护一张“已执行调用表”。工具执行前先查表如果 ID 已存在并带有结果直接返回结果不发真实请求。这张表本身也要写进 checkpoint否则恢复后同样没意义。另外建议把“工具执行”和“结果入库”做成一个事务性操作。如果结果无法一次性安全写入至少要先把“调用已发起但结果未回”的状态写进 checkpoint这样恢复后能明确知道该去“等结果”而不是“重新发起”。5.4 checkpoint 文件损坏与版本兼容问题崩溃时正在写 checkpoint文件只写了一半或者框架升级之后旧 checkpoint 的 schema 和新代码不匹配。这类问题一旦发生任务基本就找不回来了所以预防比补救更重要。预防手段有三个层面。第一是原子写前面已经提过写临时文件再 rename保证任何时刻目标文件都是完整的。第二是轮转版本保存latest.ckpt和last_2.ckpt两份每次写入都轮转恢复时最新文件失败就自动切到上一份。第三是启动时校验解析失败的 JSON 直接判定损坏不要做“尽力恢复”防止用半份数据把任务跑飞。版本兼容方面在 checkpoint 对象的根部加上schema_version字段从第一版就写上。以后改动消息结构的时候记得提供升级函数或者允许旧版本做保守恢复。不要指望一个 schema 永远不变整套机制运行三个月之后这点体会会非常深刻。5.5 压缩本身产生了不小的延迟压缩模型调用一次要 1 到 3 秒这在长任务里累积起来确实很可观。但这里要注意压缩通常不是每轮都触发真正需要压缩的场景大约在任务执行的 10% 到 20% 节点。所以延迟的绝对值并不大。如果还是很介意可以做三层优化。第一层是压缩模型降级。摘要任务对推理能力的要求低于主任务可以换用小参数模型延迟能降一半以上。第二层是异步压缩如果 Agent 当前正处于等待外部状态比如等待用户确认可以先返回一个“正在压缩”的中间状态压缩完成后继续执行。第三层是增量压缩不是每次都把全部历史丢给压缩模型而是只压缩“上次压缩之后新增的部分”再把新摘要和旧摘要合并。这样每次压缩的输入长度小很多速度快很多。注意合并摘要时旧摘要要原样保留不能再次交给模型改写否则丢失的风险会成倍增加。5.6 多实例并发写同一份 checkpoint把多个 Agent 实例跑在容器里做容错或者同一个任务在多个节点上同时执行容易出现两个进程写同一个任务目录互相覆盖。解决方案是让 checkpoint 的存储路径严格按任务 ID 隔离并且引入文件锁或数据库事务。一个任务在一个时刻只能有一个活跃执行者这是基本原则。如果确实需要多实例热备建议把 storage 换成支持原子性和锁的外部组件靠本地文件系统搞并发写迟早会撞车。最后再分享一个小技巧我自己在做这个项目的过程中有一个体会特别深Compaction 和 Checkpoint 这两套机制要放在一起设计和验证分开做一定会出现某种“时间窗口”问题。压缩完成之后必须存档工具调用完成之后必须存档这两条规则定死很多诡异的 bug 直接就不会出现。还有一个小建议把压缩和存档的日志打全。每条压缩记录保留压缩前 token 数、压缩后 token 数、压缩了哪些消息、丢弃了什么每条存档记录保留任务 ID、step_id、文件大小。任务跑挂了、Agent 变笨了这些日志就是你定位问题的第一份证据。别嫌日志多长任务排错全靠它们了。
Agent 跑到一半上下文先爆了这是所有搞过 LLM Agent 的人都会撞上的墙。这个系列写到这里已经是第十六篇前面一直在拆 DeepSeek-Harness 这个框架怎么把 Agent 的调度、工具调用、多轮推理组织起来但这几期内容做完之后你会发现真正决定一个 Agent 能不能在长任务里活下来的不是它能想多少步而是它能不能在上下文撑爆之前把该留的东西留下来在进程崩掉之后把该救的东西救回来。所以这一篇专门聊两个机制上下文压缩 Compaction以及 Checkpoint 持久化。前者解决“上下文太长模型记不住重点”后者解决“任务跑了一半进程没了一切归零”。这两件事单独拎出来都能写不少但放在一个 Agent 执行框架里它们其实是同一个问题的两面如何让长时间运行的 Agent 保持状态的可控性。这篇文章我把设计思路、触发时机、序列化方案、恢复流程以及我实际踩过的坑全部展开。1. 为什么 Agent 跑着跑着就“忘重点”Compaction 与 Checkpoint 要解决什么1.1 上下文爆炸是怎么来的很多人在第一次跑多步骤 Agent 的时候都会有一个直观感受前几轮还挺聪明十几轮之后就开始胡言乱语甚至频繁报错。原因不复杂——上下文里塞进了太多东西模型被迫在大量低信息量的内容里寻找那一点点关键线索。Agent 的执行方式和单次问答完全不一样。单次问答你给它一个问题、一段资料它答完就结束。Agent 则是循环式的思考 → 调用工具 → 拿到结果 → 再思考 → 再调用。每一轮思考会生成推理文本每一次工具调用会带回 JSON 返回、日志、错误信息、表格数据甚至整个文件内容。这些内容全部追加到历史消息里越积越多。举个例子。一个做资料汇总的 Agent先检索到 10 篇文档每篇 5000 token 的内容都会被打包成工具返回结果。然后又调用了两轮筛选、一轮摘要整合。等它开始写最终报告的时候上下文里已经堆了七八万 token。这里面真正对最终决策有用的可能只有最开始的需求描述、筛选条件、还有最后几轮的判断中间那一大坨原始文档早就没用了但它们仍然占着窗口。更麻烦的是所谓的“迷失在中间”现象。模型对上下文开头和结尾的内容感知力最强中间部分很容易被忽略。几千行工具返回的 JSON 夹在历史中间模型要么扫一眼就略过要么被干扰最后给出的决策质量明显下降。上下文不是越大越好而是“有效信息密度”越高越好。1.2 不压缩的代价不只是“报错”这么简单如果上下文只是超限报错那问题反而好解决。真正麻烦的是还没到上限模型已经开始降智。我不知道你们有没有遇到过这种情况Agent 明明还在运行错误率却明显上升重复调用同一个工具或者绕来绕去就是不执行关键步骤。这就是上下文信噪比太低导致的。还有两个容易被忽略的代价成本和延迟。现在主流的 API 计费方式里输入 token 是要真金白银付钱的。一个任务跑两个小时假设有 10 万 token 的固定历史一直被重复发送那每多一步推理就多付一次这 10 万 token 的费用。延迟也一样——每次请求都要处理完整的历史首 token 延迟会随着上下文变长而逐渐上升长任务到后期会明显感觉“变慢”不只是模型思考慢是传输和预填充都在变慢。Compaction 的定位就在这里在上下文达到危险水位之前主动对历史做一次“提炼”把冗长的工具结果和重复的推理过程压缩成一段结构化摘要让模型继续带着最关键的信息往前跑。1.3 Checkpoint 解决的是“一切归零”的恐惧上下文压缩解决的是“模型记不住”Checkpoint 持久化解决的是“进程活不长”。Agent 任务往往不是几秒钟就能跑完的。一个复杂的调研任务、一个批处理的数据分析任务、一个需要多轮人工确认的流程跑几十分钟甚至几小时都很正常。而在这段时间里进程可能因为各种原因挂掉线上环境中被 OOM kill、网络抖动导致 API 连续超时、底层的 Worker 节点被重新调度甚至只是某人手滑重启了服务。如果没有持久化机制所有这些场景的结果都一样任务状态丢失下次启动从零开始。这个代价在短任务上还好在长任务上就是灾难。想象一下一个数据分析任务前 40 分钟已经把数据拉取、清洗、特征工程全做完了就剩最后一步建模结果进程崩了。重来一遍不仅浪费 40 分钟还可能要重新支付所有中间步骤的 API 费用和工具调用费用。Checkpoint 就是游戏里的存档点。定期把 Agent 的运行状态——对话历史、任务队列、中间变量、工具调用记录——全部写到持久化存储里。进程挂了不要紧重新拉起找到最近的存档点继续往下跑。1.4 两者为什么必须配合使用单独做压缩或者单独做持久化都有点偏科。只做压缩不持久化上下文是短了但进程一崩溃压缩后的摘要也一起没了。只做持久化不压缩你确实能把完整历史存下来但恢复之后还是要面对一个上下文爆炸的问题甚至可能因为历史太长根本无法恢复。所以两者是配套关系运行过程中定期压缩让上下文保持低水位压缩完成后立即打一次 checkpoint把提炼过的状态固化下来。这样每次存档的内容都是精炼过的恢复时不用重新读入大量无用历史直接带着摘要继续跑。DeepSeek-Harness 里对这两件事的整合逻辑本质上就是一条流水线执行 → 验证 → 压缩 → 存档 → 继续执行。2. 上下文压缩 Compaction不是“砍内容”是“换组织方式”2.1 先说清楚压缩到底在压什么很多第一次写压缩逻辑的人会犯一个错误把历史消息截断只留最后几轮。这种做法确实能快速降低 token 数但基本等于让 Agent 失忆。任务目标、关键约束、已经确认过的事实全都丢了后续根本没法做正确决策。正确的思路是压缩掉的应该是“可还原性低”的内容保留的应该是“决策依赖度高”的内容。什么意思呢工具返回的一整份 JSON 原始数据如果它只是中间产物后续决策仅仅依赖其中几个字段那这份 JSON 就可以被压缩成一个“事实列表”而用户最初的任务描述、系统的安全约束、Agent 自己已经做出的关键决策和未完成计划这些是模型每一步推理都必须看到的绝对不能丢。我习惯把需要压缩的内容分成三类可以丢弃的过程噪音重复的失败尝试、无关的日志、已经完成且不再引用的中间步骤细节。这些东西压缩时可以直接丢弃不进入摘要。可以摘录的原始数据工具返回的大块内容如果后续可能用到保留其中的关键字段或结论如果后续不会再用到直接不留。必须原样保留的决策上下文任务目标、用户偏好、系统规则、当前进度、尚未执行完的待办清单。这些内容即使已经出现在前面的对话里压缩后的摘要里也要有一份完整的“复议版本”。这里有个原则值得写下来压缩的目标不是让历史变短而是让历史里的“信息密度”变高。哪怕压缩后的摘要仍然有几千 token只要它是高密度的关键信息就比原来几万 token 的混杂堆更有效。2.2 主流压缩策略怎么选实际操作中压缩策略主要有这么几类各自适用场景不一样先说说摘要式压缩。这是目前最通用的一种方式调用一次 LLM让它阅读当前的历史消息输出一段结构化的摘要。优点是可以做到语义上的提炼缺点是多一次模型调用有延迟和费用。摘要模型可以比主模型小比如主模型用大参数模型压缩用一个小一号的模型就够。然后是抽取式压缩。不用 LLM规则化地从历史里抽取关键信息比如所有工具调用里的成功标记、错误码、返回结果里匹配特定 pattern 的字段。优点是快几乎零延迟缺点是理解力有限如果原始内容里没有显式的关键标记容易漏掉重要信息。还有结构化压缩。这是摘要方式的变体不要求 LLM 输出自由文本而是要求它把历史整理成 JSON比如{facts: [...], decisions: [...], pending_tasks: [...], obsolete: [...], compaction_strategy: full}。这种方式的最大好处是机器可读后续如果再叠加别的处理逻辑比如自动检索摘要里的某个字段会非常方便。最后一类比较少用但值得提的是滚窗压缩。它不是单次把全部历史压缩而是只保留最近 N 轮完整消息更早的全部并成一段摘要。这样实现简单但对 N 的选择比较敏感N 太小模型的短期记忆不够N 太大窗口一样会被占满。在实际项目里我比较推荐结构化摘要作为主策略因为它把“信息是否保留”的决策更多地从模型手里移交到了工程手里。模型只负责把历史朗读为结构化事实工程负责决定哪些事实进最终上下文。这比让模型自由发挥写一段“总结”要稳得多。2.3 触发时机别等窗口满了才动手压缩触发得太晚上下文已经逼近模型上限就算压缩也会因为历史太长导致压缩质量下降触发得太早频繁调用压缩模型浪费时间不说还可能把尚未完成的关键任务信息误伤。我建议设定两个水位线。第一个是告警水位比如上下文占用达到模型窗口的 60% 或 70%。到了这个水位启动压缩逻辑。第二个是危险水位80% 或者 90%。如果压缩还没来得及执行或者压缩失败至少要强制丢弃一些最低价值的内容比如最早的调试日志绝不能让请求真的超限。在 DeepSeek-Harness 的执行流程里我使用的是以 token 计数为基础、以事件为辅助的混合触发方式每一轮推理结束后统一次 token另外在工具调用返回超大结果时不等到下一轮结束就立即触发压缩因为超大的工具结果往往是上下文暴涨的元凶。token 计数这个细节不要省。不同模型的 tokenizer 不一样用字符长度估 token 数误差很大最好直接用模型对应的 tokenizer 来数。如果框架里没集成可以简单按“英文约 4 字符一个 token、中文约 1.5 到 2 字一个 token”的经验公式做估算但在告警水位附近要留出余量。2.4 压缩流程的执行要点一次完整的压缩我建议至少走这几步第一步是盘点。把当前消息列表拆成几个分区系统提示区、任务目标区、历史对话区、工具结果区、最近对话区。前两类无论如何都完整保留工具结果区是压缩的主要目标历史对话区里较早的部分也纳入压缩最近对话区保持原样。第二步是生成摘要。调用压缩模型时给它明确的指令格式要求输出结构化 JSON。一个实用的压缩提示词大概长这样你是信息压缩器。请把以下对话历史压缩为 JSON 对象包含 - summary: 一段 200 字以内的整体进展摘要 - facts: 已确认且后续仍需引用的事实列表 - decisions: Agent 已做出的关键决策及其理由 - pending: 尚未完成的步骤或待办事项 - discarded: 被丢弃的无价值内容描述 要求不要新增任何原文不存在的信息不要修改事实尽量保留可验证的细节。第三步是把摘要插入消息列表。插入位置应该在原始历史之前同时给摘要消息加一个特殊的role: system或者自定义标记比如compaction_marker让模型知道从这之后的内容是历史压缩包不是当前正在发生的对话。第四步是校验。压缩完成后先别急着继续跑。检查摘要里是否包含任务目标关键词、是否包含所有 pending 项、是否因为摘要过长而仍然超限。如果摘要质量不过关宁可降低压缩比例重新压也不要拿一个残缺摘要去糊弄主模型。这里有一个实操细节压缩后的摘要不要放在消息列表的末尾要放在历史开头。原因很简单模型对上下文开头的内容注意力最强把压缩摘要放在开头相当于给模型一个“先看重点”的线索。3. Checkpoint 持久化状态清单、序列化与恢复流程3.1 到底要保存哪些状态很多人写 checkpoint 的时候只想着“把 messages 存起来”。但真正跑起来就会发现光有 messages 并不足以恢复一个 Agent 任务。一个完整的 checkpoint 至少需要包含五类信息第一是任务元数据任务 ID、启动时间、最近更新时间、compaction 次数、当前阶段编号。这些信息在任务编排、监控、故障排查时都要用缺了任何一项后续都很难定位问题。第二是对话历史包括原始 messages 数组和已压缩的摘要。这里需要注意的是消息对象的 schema 必须稳定。每一条消息至少包含role、content、timestamp、step_id有工具调用的还要带tool_call_id。缺少时间戳和 step_id恢复时顺序一乱上下文就废了。第三是 Agent 的内部状态。不同框架的内部状态不一样可能是状态机里当前正处于哪个节点也可能是决策树里已经走过的分支。这部分必须和对话历史一起保存否则恢复后模型“失忆”内部的执行器也不知道自己该干吗。第四是待执行队列和进行中的工具调用。比如 Agent 已经发起了一个工具调用结果还没回来。checkpoint 里要记录这个调用是“已发出未返回”还是“已返回未处理”。这两者的恢复策略完全不同前者需要等待或者重试后者可以直接消费结果。第五是环境信息。包括当前工作目录、已经创建临时文件路径、依赖的会话 ID 等。很多 Agent 框架会调用本地环境或者外部系统这些环境侧的“副作用状态”不保存恢复后 Agent 就找不到自己之前留下的临时文件了。3.2 序列化与存储选型存储方案的选择直接影响 checkpoint 的可靠性和性能。我梳理一下常见的选型。首先是 JSON 文件存储。最简单直接把 checkpoint 对象 dump 成 JSON 写到一个指定目录。优点是可读性好、排查方便缺点是体积大、写盘慢。适合任务量不大、单机运行的场景。然后是 SQLite。把每一条消息、每一个状态字段拆成表结构写入。优点是有事务支持不容易写坏缺点是需要多做一层 schema 设计。适合需要频繁读写、担心写入中间态损坏的场景。还有 MessagePack 这类二进制序列化。体积比 JSON 小很多、解析快缺点是调试不直观。适合对性能要求高、checkpoint 体积较大的场景。最后是外部 KV 存储比如 Redis 或对象存储。优点是天然支持分布式场景多实例可以共享缺点是需要额外维护这份基础设施。如果 Agent 框架跑在集群里或者有跨节点容错需求这一步基本是必选项。我自己在 DeepSeek-Harness 这个项目里的建议是做一个可插拔的 Storage 接口本地开发用 JSON 文件、生产环境接 SQLite 或对象存储。不要刚起步就套一个复杂的数据库等真的有并发和持久化需求了再升级。但接口隔离这件事要一开始就做好不然后面改起来会很痛。3.3 保存时机事件驱动加定期快照checkpoint 保存太频繁性能扛不住保存太稀疏恢复时损失太大。怎么平衡我用的策略是“事件驱动 周期快照”。事件驱动指的是在某些关键节点强制保存工具调用完成之后、Agent 做出重大决策之后、上下文压缩完成之后。这些节点是任务状态最容易发生质变的时候也是“恢复后继续跑”需要的最低起点。举个例子Agent 刚执行完一个耗时很长的工具调用并拿到结果如果在这时候崩溃结果就丢了所以拿到结果后的第一件事就应该是保存。周期快照则是一个兜底不管有没有关键事件每运行 N 步比如 N20或者在固定时间间隔比如 60 秒保存一次。这样即使某些状态变更没有被事件驱动捕捉到也能保证整体进度不会丢失太多。还有一个细节压缩完成后必须立即保存。压缩本身是有损操作一旦压缩完但没保存就崩溃恢复时你是该用压缩前的完整历史还是压缩后的摘要都没有。所以压缩和保存绑定成同一步——先换组织方式再落地存档这种方式从根上保证恢复时一致性。写入动作本身要注意原子性。直接写目标文件不是一个好主意因为如果写入过程中进程崩溃文件可能处于半写状态。建议先写临时文件写完 fsync 落盘再用 rename 替换旧文件。这套“临时文件 rename”的操作在很多基础软件里都是标准做法成本极低安全性提升很多。3.4 恢复流程比保存更考验设计恢复流程的设计比保存更容易翻车。我见过一个项目checkpoint 保存的时候好好的恢复后 Agent 还是行为异常后来发现是恢复顺序有问题。一个清晰的恢复流程大概是这样的第一步是定位。根据传入的任务 ID 找到最近的 checkpoint 文件并解析为对象。如果最近的一份损坏自动回退到上一份。所以保存的时候建议保留最近 2 到 3 个轮转版本别每次都覆盖唯一文件。第二步是校验。检查 checkpoint 的 schema 版本号确认和当前代码兼容不兼容则报错停止绝不尝试硬恢复。校验消息列表连续完整。校验待执行队列里的工具调用 ID 是否在历史中有对应记录。第三步是重建上下文。把压缩摘要和最新的原始消息按顺序重新拼接成完整的 messages 数组。然后做一次 token 统计如果恢复后的上下文已经接近窗口上限立即先执行一次压缩再继续。第四步是恢复 Agent 状态。把内部状态机、待执行队列、工具调用进度全部加载回内存。第五步是继续执行。不要从头开始跑而是直接从最后的事件点恢复执行。这里特别要注意工具调用的幂等性如果某次工具调用在 checkpoint 之前已经成功执行但结果还没来得及记录这种窗口很难完全消除恢复后可能会重复执行。解决办法是给每次工具调用生成唯一 ID在执行器层做去重已经处理过的 ID 直接复用结果不真实执行。4. 实操记录一条带压缩与存档的执行主循环4.1 执行流程的骨架实现这一节直接给一个可参考的实现骨架演示如何把 Compaction 与 Checkpoint 嵌入 Agent 的主循环。这里用 Python 风格的伪代码核心逻辑可以直接搬到自己的框架里。class AgentRuntime: def __init__(self, storage, token_counter, max_context_tokens): self.storage storage self.token_counter token_counter self.max_context_tokens max_context_tokens self.alert_watermark int(max_context_tokens * 0.65) self.danger_watermark int(max_context_tokens * 0.85) def run(self, task_id, initial_messages): ckpt self.storage.load(task_id) if ckpt: history, agent_state, pending_queue self.restore(ckpt) else: history initial_messages agent_state {} pending_queue [] for step_index in range(agent_state.get(step, 0), MAX_STEPS): # 1. 执行一步推理 result self.llm_step(history, agent_state, pending_queue) # 2. 如果发起工具调用执行并记录结果 if result.tool_call: tool_result self.execute_tool(result.tool_call) history self.append_tool_result(history, result.tool_call, tool_result) # 工具完成后是关键事件立即存档 self.storage.save(task_id, self.build_checkpoint(...)) # 3. 检查是否需要压缩 current_tokens self.token_counter.count(history) if current_tokens self.alert_watermark: history self.compact_history(history) self.storage.save(task_id, self.build_checkpoint(...)) # 4. 周期性存档兜底 if step_index % 20 0: self.storage.save(task_id, self.build_checkpoint(...)) self.storage.save(task_id, self.build_checkpoint(...))这段主循环看起来很直白但几个细节不处理就会出问题。第二个检查点里的“压缩完成之后立即存档”是我踩过坑才加上去的。之前我的代码是先压缩、再继续执行、等下一个保存点才存档。结果有一次压缩完成了Agent 又调了一轮工具然后崩溃。恢复的时候拿到的还是压缩前的完整历史压缩白做了而且因为工具结果已经录入历史比压缩前更长了直接从告警水位变成了危险水位。4.2 压缩模块的调用细节压缩函数的实现藏了很多细节。一份好的摘要必须保持历史中决策链条的完整性。我在项目里是这样实现的def compact_history(history): protect_roles {system, task} preserved [m for m in history if m.role in protect_roles] compactable [m for m in history if m.role not in protect_roles] compact_prompt build_compact_prompt(compactable) summary call_compact_model(compact_prompt) new_history preserved [ { role: system, content: f[COMPACTION_MARKER] {summary}, msg_type: compaction_summary timestamp: now(), } ] return new_history注意一个问题被保留的 system 和 task 消息通常已经出现在历史开头了但如果 Agent 在运行过程中动态追加过约束条件比如用户中途补了一句“不要用这个接口”这条追加的约束并不会出现在最初的 system prompt 里如果不一起保护压缩后就会丢失。所以“protected”不能简单按角色判断还要把后续对话中标记为is_constraintTrue的消息也保留下来。我在框架里给消息对象加了一个is_constraint字段工具调用结果也被允许标记成约束比如“接口返回 401后续禁止使用该接口”。压缩时凡是带这个标记的一律不纳入压缩范围。4.3 一次完整的压缩与存档记录把上面的逻辑拼起来一次“压缩 存档”的流程是这样的先看上下文计数。假设窗口是 128K token告警水位设在 83K。某轮工具返回了一个 2 万 token 的 JSON计数直接跳到 90K。触发压缩。压缩选中的范围是 40 条历史中的 35 条工具返回的原始 JSON 和早期中间推理全部交给压缩模型处理。保护的部分是任务描述、新增约束、最近 2 轮的完整对话。压缩模型返回的结构化 JSON 被解析后组装成一条 1500 token 的摘要消息插入历史开头。消息列表从 90K 降到 20K 左右。然后立即调用 storage.save把任务 ID、消息列表、Agent 内部状态、压缩次数1写入 SQLite。写入用临时文件加 rename全程大约 80ms。之后 Agent 继续下一轮推理。这个流程走顺之后热点只有一个压缩模型本身的质量。摘要模型如果是小模型可能在“事实提炼”上不够精确把关键细节漏掉。我在实际项目里遇到的解决方案是做二次校验用规则检查摘要里是否包含所有 pending 项不包含就重压缩。这个规则检查非常快值得加上。5. 常见问题与排查实录来自一线的避坑清单5.1 压缩之后 Agent 明显“变笨了”这是最常见的反馈。特征是压缩前 Agent 决策清晰压缩后开始重复问同样的问题、忽略已经确认过的事实甚至把摘要里的旧信息当成当前状态来用。排查思路先把压缩前后的消息列表拉到一起对比看摘要里是否还包含这些要素——任务目标、关键事实、已做决策、待办事项。缺哪补哪。如果摘要信息都有但 Agent 还是变笨那问题可能出在摘要的位置上它是不是被插到了特别靠后的位置或者摘要消息的role被设置成了assistant让模型误以为这是某轮输出而不是“历史说明”。把role固定为system、msg_type标记为compaction_summary并加一个显式的说明语句比如“以下是此前的对话摘要不是真实消息仅用于参考”效果会好很多。另外检查一下是不是压缩频率太高。如果每两轮就压缩一次模型每次都面对一个“新格式”的旧历史本身就容易产生混乱。把告警水位调高一点减少压缩次数通常会改善。5.2 checkpoint 恢复后上下文错乱恢复后发现顺序不对、时间线混乱、摘要和真实历史混杂。大概率是消息对象没有统一的时间戳字段或者恢复时按文件中的存储顺序直接加载而没有按时间戳排序。我的建议是在写入消息时强制带上timestamp和step_id恢复时先按step_id排序再按timestamp校验。step_id比时间戳更可靠因为多个消息可能出现在同一毫秒内而step_id是在执行循环里递增生成的保证严格有序。还有一种情况恢复时把压缩摘要和原始消息混在了一起且没有保留压缩边界标记。新模型读到摘要消息和后续的真实消息无法分辨哪些是“之前发生的事”哪些是“现在正在发生的事”。解决办法就是上面提到的在摘要消息上用compaction_marker显式标出边界。5.3 同一个工具被重复执行了多次这个问题的根因不在 Compaction而在 checkpoint 的保存时机。如果工具调用已经发出、结果也已经返回但在这两件事之间发生了崩溃恢复后 Agent 将重新发送同一个工具调用。最稳妥的解法是工具调用幂等化。给每个工具调用生成一个唯一 IDUUID在框架层维护一张“已执行调用表”。工具执行前先查表如果 ID 已存在并带有结果直接返回结果不发真实请求。这张表本身也要写进 checkpoint否则恢复后同样没意义。另外建议把“工具执行”和“结果入库”做成一个事务性操作。如果结果无法一次性安全写入至少要先把“调用已发起但结果未回”的状态写进 checkpoint这样恢复后能明确知道该去“等结果”而不是“重新发起”。5.4 checkpoint 文件损坏与版本兼容问题崩溃时正在写 checkpoint文件只写了一半或者框架升级之后旧 checkpoint 的 schema 和新代码不匹配。这类问题一旦发生任务基本就找不回来了所以预防比补救更重要。预防手段有三个层面。第一是原子写前面已经提过写临时文件再 rename保证任何时刻目标文件都是完整的。第二是轮转版本保存latest.ckpt和last_2.ckpt两份每次写入都轮转恢复时最新文件失败就自动切到上一份。第三是启动时校验解析失败的 JSON 直接判定损坏不要做“尽力恢复”防止用半份数据把任务跑飞。版本兼容方面在 checkpoint 对象的根部加上schema_version字段从第一版就写上。以后改动消息结构的时候记得提供升级函数或者允许旧版本做保守恢复。不要指望一个 schema 永远不变整套机制运行三个月之后这点体会会非常深刻。5.5 压缩本身产生了不小的延迟压缩模型调用一次要 1 到 3 秒这在长任务里累积起来确实很可观。但这里要注意压缩通常不是每轮都触发真正需要压缩的场景大约在任务执行的 10% 到 20% 节点。所以延迟的绝对值并不大。如果还是很介意可以做三层优化。第一层是压缩模型降级。摘要任务对推理能力的要求低于主任务可以换用小参数模型延迟能降一半以上。第二层是异步压缩如果 Agent 当前正处于等待外部状态比如等待用户确认可以先返回一个“正在压缩”的中间状态压缩完成后继续执行。第三层是增量压缩不是每次都把全部历史丢给压缩模型而是只压缩“上次压缩之后新增的部分”再把新摘要和旧摘要合并。这样每次压缩的输入长度小很多速度快很多。注意合并摘要时旧摘要要原样保留不能再次交给模型改写否则丢失的风险会成倍增加。5.6 多实例并发写同一份 checkpoint把多个 Agent 实例跑在容器里做容错或者同一个任务在多个节点上同时执行容易出现两个进程写同一个任务目录互相覆盖。解决方案是让 checkpoint 的存储路径严格按任务 ID 隔离并且引入文件锁或数据库事务。一个任务在一个时刻只能有一个活跃执行者这是基本原则。如果确实需要多实例热备建议把 storage 换成支持原子性和锁的外部组件靠本地文件系统搞并发写迟早会撞车。最后再分享一个小技巧我自己在做这个项目的过程中有一个体会特别深Compaction 和 Checkpoint 这两套机制要放在一起设计和验证分开做一定会出现某种“时间窗口”问题。压缩完成之后必须存档工具调用完成之后必须存档这两条规则定死很多诡异的 bug 直接就不会出现。还有一个小建议把压缩和存档的日志打全。每条压缩记录保留压缩前 token 数、压缩后 token 数、压缩了哪些消息、丢弃了什么每条存档记录保留任务 ID、step_id、文件大小。任务跑挂了、Agent 变笨了这些日志就是你定位问题的第一份证据。别嫌日志多长任务排错全靠它们了。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
