跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-05
课程目录 · 11 节

Agent 框架源码

第 8 节:压缩是可选能力,删的只是一条 surfaceOp

核对 2026-11-05 更新 1 次 引用 0 个来源

压缩不在循环里,是一个可插拔 seam,用 start/summary/end 三个事件构成一把锁。压掉的从来不是日志,而是一段 surface:摘要带着 surfaceOp 把区间替换掉,日志一条没少,所以压缩可撤销、可审计。

关键事实 · 3 条口径随行标注
压缩事件
compaction/start·summary·end三个,均只写日志不进 surface
surface 变更
唯一一条摘要承载在 user/message,带 surfaceOp replace
锁的语义
有 start 无 end 即可检测中途崩溃不会被伪装成成功

压缩不在循环里,是一个可插拔的 seam

多数框架把「上下文超了怎么办」写成循环里的一个 if 分支。dsh 把它做成了 seam:ctx.compaction 是接口,compaction-basic 是一个提供方,command-compact 是面向用户的消费方。压缩是可选能力,不属于 agent loop 主干,所以不用它的人一行成本都不付。

做成 seam 之后,持久化必须跟上——压缩这件事本身也要留痕,否则「为什么模型忘掉了前面」就无从查起。它向 SessionEventMap 合并了三个只写日志、不进 surface 的事件:

三个事件构成一把锁
事件 载荷要点 作用
compaction/start { turn },null 表示独立手动尝试 获取日志记录的锁
compaction/summary 摘要、被遮蔽区间与 seq 列表、token 估算、模型调用 envelope 记录压了什么、用什么模型压的
compaction/end { turn, error? } 释放锁,失败也记

锁的设计值得细看:start 先落盘,然后才做摘要生成、写 summary、写替换消息,最后才 end。先拿锁再干活,最后放锁——这样中途崩溃会留下「有 start 没 end」的可检测状态,而不是一个假装成功的 end。

还有个细节:未匹配的 start 会阻塞所有入口点,但如果它出现在较新的 session/end-seed 之前,就判定为上一个生命周期留下的陈旧证据,直接忽略。这类「状态有生命周期归属」的判断,是长跑系统必须有的。

压掉的到底是什么:一条 surfaceOp

压缩最容易做错的地方是「以为在删历史」。dsh 的做法把两件事分得很开:

仅追加日志(永不删)
  ├─ turn/start, user/message, assistant/message, tool/call, tool/result …
  ├─ compaction/start
  ├─ compaction/summary   ← 记录 shadowedRange / shadowedSeqs / token 数
  ├─ user/message         ← 摘要本体,带 surfaceOp { op:'replace', startSeq, endSeq }
  └─ compaction/end

模型看到的 surface(由日志投影)
  └─ 被 startSeq..endSeq 覆盖的那些事件 → 替换成一条摘要消息
       其余事件原样保留

关键在 surfaceOp。摘要本身承载在一条 user/message 上,这条消息带着「把 startSeq 到 endSeq 的 surface 替换掉」的指令。这是压缩唯一的 surface 变更——日志一条没少,只是投影时那段被折叠了。

这带来两个能力:压缩可撤销(去掉那条 surfaceOp 就回到压缩前),压缩可审计(shadowedSeqs 精确列出被遮蔽的事件序号,按 surface 顺序排列)。

注意 shadowedRange 是「位置跨度」而不是「数值区间」——start 和 end 两个 seq 标记边界,中间可能夹杂不属于该消息的其他事件。这个区分在实现里很容易写错,写成数值区间就会误删相邻事件。

spill:超长工具输出不截断,先存再给定位符

另一条与上下文相关的路径是工具输出太长。常见做法是截断加一句「已省略 N 行」,模型于是永远看不到后面。dsh 用 spill 存储:把完整文本原样存下来,返回不透明定位符加检索指引,模型需要时自己去取。

ctx.spillStore 只有一个服务操作 saveText:原样持久保存内容,返回定位符、后端提供的检索提示、精确字节数。请求里带三个字段,语义划分很清楚:owner 是存储命名空间(不是访问控制)、source 是生产者来源信息(同样绝非访问控制)、suggestedName 只是命名提示,后端会把它消毒成单一路径段。

三处都明确写「不是访问控制」,这本身就是一条警告:别把安全边界建在字符串字段上。看过太多系统拿 source: 'system' 当权限凭证。

三种处理超长上下文的方式,代价各不同
策略 信息损失 可追溯 适用
硬截断 永久丢失后半段 否 只用于纯装饰性输出
摘要压缩 细节被概括 是,日志保留原文事件 长会话的常规手段
spill 外置 不丢失,需要时再取 是,定位符可回查 工具输出、抓取正文、大日志

三者的组合顺序通常是:先把大块输出 spill 出去,剩下的历史仍超预算再做摘要压缩,硬截断只留给确实无关紧要的内容。dsh 把这三种都做成可选插件,装哪几个由部署决定,循环不知道它们存在。

下一节是实战:从零写一个插件,把工具、LLM 适配器、设置卡三件事走完。

变更记录

日期类型改了什么范围
新建 讲清「删的是 surface 不是日志」,并把三种超长策略做取舍对比 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型