结论先行:上下文窗口是 Agent 最刚性的资源,管理思路要像管内存一样:预算制、分级淘汰、关键状态换出到磁盘。核心三板斧是——工具输出截断(truncate)、历史轮次压缩(compact)、状态外置(externalize)。三者配合,长任务才能跑得完、跑得稳。
上下文是怎么被撑爆的
三种膨胀来源,危害排序如下:
工具输出最凶。一次 cat 一个大文件、一次全量 grep、一次返回几千条日志的接口调用,就能吃掉几十 k token。更麻烦的是这些内容后续轮次不再有用,却永久占据历史——模型看过一眼的东西,harness 默认会替它记到任务结束,哪怕那份内容只在第 3 轮有用、任务要跑 40 轮。
历史轮次次之。agentic loop 每轮都追加消息,30 轮的任务历史本身就可能超过窗口。而且每轮请求都重发全部历史,这直接体现在账单上——上下文管理同时也是成本管理。历史膨胀有个隐蔽的复合效应:早期的错误尝试(读错文件、跑挂的命令)如果一直留在历史里,模型后续还可能被它们带偏方向,重复已经证明失败的路径。所以清理历史不只是省 token,也是在纠正模型的"记忆"。
系统提示与说明书最稳定但也最占底座。system prompt、AGENTS.md、工具 schema 加起来轻松上万 token,这部分没法省,只能控制其他部分。它的特点是每轮都在,所以任何"往里加一句"的冲动都要克制:加的是常驻成本,乘上任务轮数和任务数之后是真实的账单数字。
截断:第一道闸门
工具结果进入上下文前,harness 必须做截断。先看错误写法:
# 错误写法:无脑掐头,只保留前 N 字符
def truncate_tool_output(text: str, limit: int = 10_000) -> str:
return text[:limit] # 堆栈、报错行几乎总在尾部,恰好全被切掉
问题在于工具输出的价值分布极不均匀:报错行、堆栈、总结段通常在尾部,头部往往只是重复的表头或前置内容。只保头的截断会把模型最需要的证据切掉,模型随后会再发起一次全量读取——截断不仅没省,反而多付一轮。原则是保头保尾、中间采样、失败信息完整保留:
# 正确写法:保头保尾,中间省略,并告诉模型如何拿全文
def truncate_tool_output(text: str, limit: int = 10_000) -> str:
if len(text) <= limit:
return text
head, tail = text[:limit // 3], text[-limit // 3:]
omitted = len(text) - len(head) - len(tail)
return f"{head}\n...[截断 {omitted} 字符,需要全文请用 offset 分段读取]...\n{tail}"
比无脑截断更好的做法是让工具自身支持分页参数(offset/limit、行号范围),把"读多大"的决定权交给模型,harness 只兜底。截断提示里那句"如何拿全文"很重要:它把一次硬失败转化成模型可执行的下一步动作。
压缩:临近上限时的整备
当 token 占用逼近预算(常见阈值是 80%~90%),触发 compaction:把较老的历史轮次交给模型做一次结构化摘要——当前任务、已完成步骤、关键结论、待办事项——然后用摘要替换原始历史,新对话从摘要继续。
压缩的关键不是摘要写多漂亮,而是淘汰顺序:
# 上下文预算配置(示意)
context:
max_tokens: 200000
compact_threshold: 0.85
eviction_order: # 先丢的排前面
- old_tool_outputs # 老的工具输出:几乎总是安全
- old_turns # 老轮次:摘要化后替换
- summarized_history # 已摘要的再压缩:合并压缩
pinned: # 永不丢弃
- system_prompt
- agents_md
- active_task_list
工具输出最安全(磁盘上有源文件,丢了可以重读);中间探索过程次之(失败的尝试方向,留一行结论即可);任务目标、用户明确给过的约束、当前进行中的状态必须钉住。压缩本身是一次 LLM 调用,用便宜模型做即可,摘要质量的要求是"结构完整"而不是"文笔流畅"。还有一个容易忽略的细节:压缩后上下文的前缀变了,缓存全部失效,所以压缩触发时机本身也值得优化——能靠外置避免的压缩就别靠压缩硬扛。
外置:把上下文当 cache 而不是主存
最有效的策略其实是换思路:上下文窗口不是存储,是工作内存。持久状态放磁盘——任务清单写进 markdown 文件、关键决策记录进笔记、大结果落盘后上下文里只留文件路径和一行摘要。模型需要时自己重读。
这样压缩导致的细节损失就不致命了:摘要丢掉的内容,磁盘上都有。同时还有个附带收益——状态在文件里意味着跨会话可恢复,token 计费上文件内容只在重读时付费。外置的粒度也有讲究:不是把所有东西都丢到磁盘就完事,上下文里要保留"有哪些文件存在、各自装着什么"的一行索引,否则模型不知道该去重读什么——外置做得好是"主存换磁盘",做得差是"把书扔了还烧了目录"。外置还有一层组织价值:任务清单落盘后,人类随时可以打开看进度、直接改两笔再让 Agent 继续,人和 Agent 围绕同一个事实源协作,这比任何"进度面板"都直接。
三种策略不是互斥的,配套关系如下:
| 策略 | 触发时机 | 保留什么 | 丢弃什么 | 主要风险 |
|---|---|---|---|---|
| 截断 truncate | 每次工具输出入上下文前 | 头尾关键段、报错与堆栈 | 中间低密度内容 | 切掉尾部证据(需保尾规避) |
| 压缩 compact | 占用超阈值(如 85%) | 结构化摘要、钉住项 | 老工具输出、中间探索 | 细节丢失、缓存失效 |
| 外置 externalize | 任务设计阶段就确定 | 磁盘上的全文与清单 | 上下文里的冗余副本 | 模型忘记重读(需清单兜底) |
落地建议与衡量指标
先做截断(一天就能上,立竿见影),再做 compaction 阈值触发(注意压缩本身是一次 LLM 调用,要选便宜模型),最后把状态外置作为任务设计规范推广。衡量指标用"任务完成时上下文峰值占用"和"压缩次数",而不是单看窗口利用率——能靠外置解决的就别靠压缩硬扛。上线后每周看两个曲线:单任务平均压缩次数上升说明任务设计在退化(状态没外置,全靠窗口硬装),截断后紧跟全量重读的次数上升说明截断阈值定低了或分页参数没暴露好。
实战场景
一个典型的翻车与修复过程:团队的长任务(跨模块重构)跑到第 20 轮左右频繁报"超出上下文窗口"。第一反应是上调窗口配置,但窗口加了一倍问题依旧——回放 trace 发现,第 4 轮一次全量 grep 返回了几万行结果,此后每一轮都被原样重发,账单和窗口一起被这份再也没用过的内容拖死。修复分三步:给搜索类工具加行数上限和分页参数(截断);把任务清单和已确认的重构决策写进仓库里的 markdown 文件,上下文只留路径(外置);占用超 85% 时用便宜模型对老轮次做结构化摘要(压缩)。改完同一个任务能稳定跑完,中途压缩从每任务数次降到零或一次(定性观察;token 开销的下降幅度与任务形态相关,此处不给出统一数字)。这个案例的教训是:窗口不够的第一反应不该是"买更大的窗口",而是"查谁在浪费"。
检查清单
- 所有工具输出入上下文前过截断,保头保尾,报错信息完整
- 截断提示里写明模型拿回全文的路径(分页参数或文件位置)
- 搜索类、读取类工具暴露 offset/limit 参数,把"读多大"交给模型
- 占用超阈值触发压缩,淘汰顺序明确:先老工具输出,再老轮次
- 任务目标、用户约束、进行中状态在压缩中钉住,永不淘汰
- 任务清单与关键决策落盘,上下文只留路径与摘要
- 监控压缩次数与峰值占用,上升趋势先查任务设计而不是加窗口
- 压缩用便宜模型执行,摘要只求结构完整