Agent 框架源码
第 8 节:压缩是可选能力,删的只是一条 surfaceOp
压缩不在循环里,是一个可插拔 seam,用 start/summary/end 三个事件构成一把锁。压掉的从来不是日志,而是一段 surface:摘要带着 surfaceOp 把区间替换掉,日志一条没少,所以压缩可撤销、可审计。
- 压缩事件
- 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 不是日志」,并把三种超长策略做取舍对比 | 全页 |