深入理解 dsh/第 04 章
四个包,四个不同策略
pi 的压缩是一个文件(compaction.ts,约 1000 行)。dsh 把它拆成一个抽象引擎 + 四个实现,
而且这四个实现不是同一件事的四种写法——它们是四种完全不同的省 token 手段。
| 包 | 行数 | 用模型吗 | 手段 |
|---|---|---|---|
compaction |
195 | — | 抽象引擎:三个抽象方法 + 一个恢复事件 |
compaction-tool-result-pruner |
185 | 不用 | 把老工具结果截短,留标记 |
compaction-basic |
476 + 600 | 用 | 选一段历史 → 让模型总结 → 替换成一条 |
compaction-image-offload |
41 | 不用 | 图片换成占位符(由 provider 错误码触发) |
command-compact |
108 | — | /compact 斜杠命令 |
这个拆法的意义在于:「省 token」不是一个动作,而是一串按代价从低到高的动作。 免模型的先做,还不够再上模型——这正是 4.4 节要讲的顺序。
compaction/src/index.ts:119(抽象类)· tool-result-pruner:1-5(model-free)
抽象引擎只规定三件事
| 方法 | 谁调 | 契约要点 |
|---|---|---|
compactIfNeeded(agent, trigger, signal) |
每步之前自动 | trigger 是 'pressure' 或 'context-overflow';不需要压缩返回 null |
compactNow(agent, signal, commandId?) |
/compact 手动 |
空闲会话上跑;同步先开空闲任务再异步干活 |
compactRegion(start, end, agent, signal?) |
上面两个共用 | 强制把一个位置区间压成一条;边缘必须成对平衡 |
三个方法里最值得注意的是 compactNow 的文档,它把「并发安全」写成了一段时序:
compaction/start。这条持久标记就是压缩锁,直到某一次 compaction/end 为止。「锁」这个词在这里是字面意思:锁不是内存里的 mutex,而是日志里的一条记录。 进程崩了,锁还在——下次启动扫日志就知道「上次压缩没走完」。
compaction:147-152(compaction/start 即锁)
摘要失败可以「改输入再重试」
这是 dsh 压缩设计里最聪明的一个洞。接口声明了一个 waterfall 事件:
/** * Recover a failed summary request by synchronously recording a durable * change to its selected input. Return true only after making progress; * the provider re-derives and re-prices the selection before retrying. * Call next() when the failure cannot be recovered. */ 'compaction/summary-error'(payload: { session: Session; sourceEventSeqs: readonly SessionSeq[]; error: unknown; signal?: AbortSignal }, next: () => boolean): boolean
照这个契约,compaction-image-offload 就这么接进来的:当 provider 报 IMAGE_OFFLOAD_REQUIRED 时,
它不放弃,而是把最老的几张图换成占位符并记一条 durable 决策,然后返回 true 让上游重试。
| 失败类型 | 谁来处理 | 动作 |
|---|---|---|
| 图片太多 | compaction-image-offload |
换最老 N 张为占位符,持久记录,重试 |
| 工具结果太长 | compaction-tool-result-pruner |
截短并加标记,重试 |
| 其他 | 没人处理 → next() |
失败如实上报 |
onError 钩子做不到的,
因为 pi 的钩子不能保证「改了就记下来」。
compaction:94-106(summary-error 契约)· image-offload:1-8(实现者)
两段式:先免费剪裁,再花钱总结
compactIfNeeded 的真实流程,这是本章的核心:
if (measurement.totalTokens < spec.thresholdTokens) return null // ① 没过阈值,不管 // Once pressure qualifies, land the model-free pass before choosing a // summary range, then remeasure through the singleton replay fold. if (prune !== undefined) { prune.pruneSession(agent.session) // ② 先免费剪裁工具结果 measurement = meter.measure(agent.session, header) } if (measurement.totalTokens < spec.thresholdTokens) return null // ③ 剪完够了就到此为止 let result: CompactionResult | null = null for (let attempt = 0; attempt <= spec.compactionRetries; attempt += 1) { // ④ 不够才上模型 const range = selectCompactableRange(agent.session, measurement, spec.retainTokens) if (range === null) { /* 找不到安全区间 → 抛错或放弃 */ } result = await this.compactRegion(range.start, range.end, agent, signal) measurement = meter.measure(agent.session, header) // ⑤ 每次都重新测 if (measurement.totalTokens < spec.thresholdTokens) return result } throw new Error(`compaction still above threshold after ${spec.compactionRetries + 1} compaction attempts …`)
三个值钱的细节:
pruneSession 不调模型、不花钱、毫秒级。大量会话走到这一步就够了,
根本不会触发 LLM 总结。这个顺序不是优化,是设计。
measurement = meter.measure(...) 在循环体内。压缩一次没压够就再来一次,
但每次都用真实测量值判断——不靠估算。
compactionRetries 默认 1(即最多 2 次尝试),maxOverflowRetries 默认也是 1。
这直接回答了对比站 recovery.html 里那句「压缩失败熔断:都只是有上限」——dsh 这边是个有名字、可配的计数器,不是一个隐式标志。
basic:342-362(两段式)· config.ts:105-106(两个重试默认值)
切点:从后往前走,凑够尾预算,再对齐配对
阈值用比例表示,不写死 token 数——这是和 pi 最直观的差别(pi 是固定的 16384 / 20000):
| 常数 | 值 | 含义 |
|---|---|---|
DEFAULT_THRESHOLD_RATIO | 0.8 | 占用超过窗口 80% 才考虑压缩 |
DEFAULT_RETAIN_RATIO | 0.16 | 最近的 16% 窗口原文保留,不压 |
比例会自动乘上「该模型的 contextWindow」——所以换模型不需要改配置。然后选切点:
// ① 从末尾往前累加,凑够 retainTokens 就停 let accumulated = 0 let keepFromIdx = pricedNodes.length for (let index = pricedNodes.length - 1; index >= 0; index -= 1) { accumulated += pricedNodes[index]!.tokens keepFromIdx = index if (accumulated >= retainTokens) break } if (keepFromIdx <= firstIdx) return null // 尾巴就占满了 → 无可压 // ② 再往前挪,直到「切在这里不会劈开一对 tool-call/result」 while (keepFromIdx > firstIdx) { if (toolPairingBalancedBefore(session, surfaceNodes[keepFromIdx]!)) break keepFromIdx -= 1 } if (keepFromIdx <= firstIdx) return null // ③ 区间 = 保留尾之前的所有节点 const first = surfaceNodes[firstIdx]! const cutoff = surfaceNodes[keepFromIdx - 1]! return { start: first, end: cutoff }
和 pi 的 findCutPoint 对照着看最有意思——同一个直觉,不同的守卫:
| 维度 | pi findCutPoint | dsh selectCompactableRange |
|---|---|---|
| 方向 | 从末尾倒着走 | 从末尾倒着走(一致) |
| 预算口径 | 固定 token(16384) | 比例 × 窗口(0.16) |
| 配对守卫 | 内联判断 + shouldCompact |
toolPairingBalancedBefore(导出、可单测) |
| system 头 | 在别处处理 | 显式跳过 node 0 |
| 前置一致性校验 | 无 | surfaceNodes 必须与计价的 pricedNodes 逐项相等,否则抛错 |
surfaceNodes.some((seq, index) => seq !== pricedNodes[index]?.seq) ——
如果 token 计量用的 surface 和当前 session 的 surface 不是同一份,直接报错而不是切错地方。
这是第 3 章「两个代际」思想的延伸:凡是按位置计算的东西,都要先验证位置对齐。
region.ts:117-152(选切点)· config.ts:18-22(两个比例默认值)
「平衡」是怎么被强制的
compactRegion 自己不判断配对——它要求调用方保证,并在开工前复查:
if (!toolPairingBalancedBefore(session, nodes[startIdx]!)) { throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`) } if (!toolPairingBalancedAfter(session, nodes[endIdx]!)) { throw new Error(`compactRegion: end seq ${end} is not a balanced boundary (would split a step, or the step is still open)`) }
两条错误信息把两种「不平衡」区分开了,这是有意的:
| 边缘 | 危险 | 为什么 |
|---|---|---|
start |
劈开一对 tool-call / result | 模型会看到「调用了但没有结果」,provider 直接 400 |
end |
劈开一个 step,或 step 还没结束 | 留下半个 step,后续无法继续 |
注意 toolPairingBalancedBefore / toolPairingBalancedAfter 是从抽象包导出的公共函数:
对比一下 pi:pi 在 findCutPoint 里内联判断,还额外有 shouldCompact 与「工具调用护栏」(compaction.ts:742-748)。
两家都把这条规则当硬约束,但 dsh 把它做成了可复用的公共谓词。
region.ts:349-355(平衡校验)· compaction:18(导出谓词)
一键对照
| 问题 | pi | dsh |
|---|---|---|
| 压缩逻辑在哪 | 一个文件 | 抽象包 + 4 个实现包 |
| 阈值 | 固定 token | 比例 × 模型窗口 |
| 先剪裁再总结 | 无此分层 | 两段式(免费的先做) |
| 失败后重试 | 一次性标志 | 两个计数器(compactionRetries / maxOverflowRetries) |
| 摘要失败恢复 | 无 | compaction/summary-error waterfall,可改输入后重试 |
| 并发保护 | await this.abort() + 重入抛错 | durable 标记当锁(进程崩溃后仍有效) |
| 配对校验 | 内联 | 导出谓词 toolPairingBalanced* |
一句话:pi 把压缩写成一个算法,dsh 把它写成一门「省 token 的经济学」——先找免费的,再找便宜的,最后才花钱。