深入理解 dsh 04 / 06 目录 单页全本 学习手册 对比站

深入理解 dsh/第 04 章

4.1

四个包,四个不同策略

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)

4.2

抽象引擎只规定三件事

方法谁调契约要点
compactIfNeeded(agent, trigger, signal) 每步之前自动 trigger 是 'pressure' 或 'context-overflow';不需要压缩返回 null
compactNow(agent, signal, commandId?) /compact 手动 空闲会话上跑;同步先开空闲任务再异步干活
compactRegion(start, end, agent, signal?) 上面两个共用 强制把一个位置区间压成一条;边缘必须成对平衡

三个方法里最值得注意的是 compactNow 的文档,它把「并发安全」写成了一段时序:

Implementations synchronously start an idle task before any asynchronous work, select a useful range without writing on a no-op, then append a standalone `compaction/start` before summarization. That durable marker is the compaction lock until one `compaction/end` attempt.
实现必须在任何异步工作之前同步地起一个空闲任务;无实际需要时不写日志直接返回;然后在摘要之前追加一条独立的 compaction/start。这条持久标记就是压缩锁,直到某一次 compaction/end 为止。
— packages/compaction/compaction/src/index.ts:147-152

「锁」这个词在这里是字面意思:锁不是内存里的 mutex,而是日志里的一条记录。 进程崩了,锁还在——下次启动扫日志就知道「上次压缩没走完」。

compaction:147-152(compaction/start 即锁)

4.3

摘要失败可以「改输入再重试」

这是 dsh 压缩设计里最聪明的一个洞。接口声明了一个 waterfall 事件:

packages/compaction/compaction/src/index.ts:94-106
/**
 * 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() 失败如实上报
为什么是 waterfall 而不是 try/catch 重试:因为恢复手段需要改输入,而改输入必须持久化(否则重试时又变回去)。 waterfall 给了插件「在失败点上写一条 durable 事件」的权利——这是 pi 那边 onError 钩子做不到的, 因为 pi 的钩子不能保证「改了就记下来」。

compaction:94-106(summary-error 契约)· image-offload:1-8(实现者)

4.4

两段式:先免费剪裁,再花钱总结

compactIfNeeded 的真实流程,这是本章的核心:

packages/compaction/compaction-basic/src/index.ts:342-362
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(两个重试默认值)

4.5

切点:从后往前走,凑够尾预算,再对齐配对

阈值用比例表示,不写死 token 数——这是和 pi 最直观的差别(pi 是固定的 16384 / 20000):

常数值含义
DEFAULT_THRESHOLD_RATIO0.8占用超过窗口 80% 才考虑压缩
DEFAULT_RETAIN_RATIO0.16最近的 16% 窗口原文保留,不压

比例会自动乘上「该模型的 contextWindow」——所以换模型不需要改配置。然后选切点:

packages/compaction/compaction-basic/src/region.ts:131-152
// ① 从末尾往前累加,凑够 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 findCutPointdsh 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(两个比例默认值)

4.6

「平衡」是怎么被强制的

compactRegion 自己不判断配对——它要求调用方保证,并在开工前复查:

packages/compaction/compaction-basic/src/region.ts:349-355
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 是从抽象包导出的公共函数:

export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
配对判定被单独导出——因为它是接口的一部分,任何实现压缩的后端都必须用同一套判定。
— packages/compaction/compaction/src/index.ts:18

对比一下 pi:pi 在 findCutPoint 里内联判断,还额外有 shouldCompact 与「工具调用护栏」(compaction.ts:742-748)。 两家都把这条规则当硬约束,但 dsh 把它做成了可复用的公共谓词。

region.ts:349-355(平衡校验)· compaction:18(导出谓词)

4.7

一键对照

问题pidsh
压缩逻辑在哪一个文件抽象包 + 4 个实现包
阈值固定 token比例 × 模型窗口
先剪裁再总结无此分层两段式(免费的先做)
失败后重试一次性标志两个计数器(compactionRetries / maxOverflowRetries)
摘要失败恢复无compaction/summary-error waterfall,可改输入后重试
并发保护await this.abort() + 重入抛错durable 标记当锁(进程崩溃后仍有效)
配对校验内联导出谓词 toolPairingBalanced*

一句话:pi 把压缩写成一个算法,dsh 把它写成一门「省 token 的经济学」——先找免费的,再找便宜的,最后才花钱。

本章学习记录

记录仅保存在当前浏览器。