深入理解 dsh 全本 目录 学习手册全本
Full text

深入理解 dsh
单页全本

六章合订。适合 Ctrl+F 搜索与打印。

1.1

先分清四种「派发」,不是一种

读 dsh 的第一道坎就在这里。pi 那边的事件是「发了就发了」,dsh 这边的事件有四种不同语义, 而且一个 turn 的控制流就是这四种派发串起来的。

语义Cordis 原语谁能影响结果典型用途
emit ctx.emit 没人——纯通知 状态变化广播(agent/status)
serial ctx.serial 第一个 bail 的返回值 按序询问(agent/turn-stopping)
waterfall ctx.waterfall 每一个——链式包裹 默认实现可被插件替换(agent/pre-step)
并行 ctx.parallel 各自独立 互不依赖的观察者

最容易被忽略的是 waterfall 的「包裹」语义:它不是「谁最后返回听谁的」, 而是每个监听器都拿到一个 next(),调用它就继续往里走,不调用就截断整条链。

Around-middleware dispatch (Cordis `waterfall`). The declared event parameters already end with the `next` callback, so `rest` is exactly the event's arguments after the payload — the final element being the innermost `next` (the default the listener chain wraps).
环绕中间件式派发。事件参数本身就以 next 回调结尾,因此 rest 恰好是 payload 之后的全部参数——最后一个是最内层的 next,也就是监听链所包裹的那个默认行为。
— packages/core/agent/src/dispatch.ts:73-81

dispatch.ts:73-81(waterfall 契约)

1.2

入口:一个 Service,六个注入项

整个 agent 循环是一个 Cordis 服务。它能用到什么,写在 static inject 里—— 这是读 dsh 最省力的入手点,因为它等于一张依赖清单:

packages/core/agent-loop/src/index.ts:291-292
export class AgentLoop extends Service implements AgentFactory {
  static inject = ['agents', 'sessions', 'llm', 'tools', 'systemPrompt', 'sessionProjections']

六项正好对应一个 turn 需要的六件事:

注入项一个 turn 里它负责什么
agents把自己注册成 factory,供 ctx.agents 创建实例
sessions持久化事件日志 + 派生消息(第 3、6 章)
llm发请求、流式收 token
tools解析本步可见的工具集合(第 2 章)
systemPrompt按 scope 拼装系统提示
sessionProjections注册模型选择与收件箱的投影

注意初始化不在构造函数里,而在一个名为 [Service.init] 的计算属性方法里—— 这是 Cordis 的服务生命周期约定,等价于「所有依赖都就绪之后再跑」。

packages/core/agent-loop/src/index.ts:330-340
protected async [Service.init](): Promise<void> {
  const ctx = this.runtime.ctx
  const ownership = this.ownership
  // Agent projections remain readable until teardown finishes.
  ctx.effect(() => () => ownership.dispose(), 'agentLoop.transactions()')
  this.modelProjectionHandle = await ctx.sessionProjections.register(modelSelectionProjectionDefinition)
  this.inboxProjectionHandle = await ctx.sessionProjections.register(inboxProjectionDefinition)
  ctx.effect(() => ctx.agents.setFactory(this), 'agentLoop.setFactory()')
  ctx.systemPrompt.variable('provider', context => context.modelSelection?.provider ?? context.agent?.options.provider)
  ctx.systemPrompt.variable('model', context => context.modelSelection?.model ?? context.agent?.options.model)

ctx.effect(...) 出现两次——这是全篇反复出现的东西:凡是从 ctx 上申请的东西,都用 effect 登记销毁。 所以插件卸载时不需要手写清理,框架按 effect 逆序回收。

index.ts:291-292(inject)· :330-340(Service.init)

1.3

三层:kick → turn → step

dsh 的循环也是嵌套的,但分层方式和 pi 不一样:它把「驱动」和「轮次」和「步」分成三个不同职责。

层代码循环它管什么
L1 驱动 agent.ts:259 while (await this.turn()) {} 「还有没有下一轮」
L2 轮次 agent.ts:332 while (true) + break 这一轮里的若干 step
L3 步进 preStep() + step() 不是循环,是一次调用 一次模型请求 + 一批工具

最外层短得离谱,但它承担了一件事:把异常吞掉并把状态复位。

packages/core/agent-loop/src/agent.ts:262-275
private async kick(): Promise<void> {
  try {
    while (await this.turn()) {}
  } catch (_error) {
    // Reported failures and cancellation are contained at the driver boundary.
  } finally {
    if (this.phase.kind === 'running') {
      const { turn, wakeRequested } = this.phase
      this.setPhase({ kind: 'idle', lastTurn: turn })
      if (wakeRequested && this.inbox.hasPending) this.wakeDriver()
    }
  }
}

catch 是空的,这不是偷懒:错误已经在更内层被上报过了(agent/error 事件), 这里只负责「不要让一次失败把驱动永久卡在 running」。而 finally 里那个 wakeRequested 是另一种情形——运行期间有人敲门,但当时没法处理,于是记下来,收尾后再敲一次。

agent.ts:262-275(kick)

1.4

turn 本体:五处 append

轮次的骨架可以压成五行——每一行都是一个「持久化事件」(第 6 章会讲为什么这很重要):

packages/core/agent-loop/src/agent.ts:320-400(骨架)
const turn = phase.turn + 1
this.session.append('turn/start', { turn })          // ① 开轮
while (true) {
  const step = phase.step + 1
  const decision = await this.preStep(target, { turn, step })   // ② 准入
  if (decision.kind === 'reject') { turnEnds = { kind: 'blocked' }; return false }
  this.session.append('step/start', { turn, step })      // ③ 开步
  try {
    const stepEnd = await this.step(decision)                // ④ 模型 + 工具
    if (turnEnds === null || turnEnds.kind !== 'max-tokens') turnEnds = stepEnd
  } finally {
    stopRecovery()
    this.session.append('step/end', { turn, step })        // ⑤ 闭步
  }
  if (turnEnds && this.inbox.nextStep.length === 0) {
    await this.dispatch.serial('agent/turn-stopping', { turn, signal })
  }
  if (turnEnds && this.inbox.nextStep.length === 0) break
  target = 'next-step'
}

四处细节值得单独指出:

① turnEnds 是「粘性」的
代码里那句注释说得很直接:max-tokens is sticky: once any step hits the ceiling, later steps that complete normally must not downgrade the turn outcome. 一旦某步撞到输出上限,整轮就记 max-tokens——后面几步正常完成也不能把它降级。
② 空决策也要占住轮次边界
if (phase.step === 0 && decision.messages.length === 0) 时返回 false, 注释解释:消息被移除或决策改写为空,仍然拥有这一轮的起始边界,但不消耗一次模型调用。
③ turn-stopping 是 serial,不是 emit
因为它需要「按序询问,第一个说停就停」——这正是 serial 的语义。
④ 同一个条件判断了两次
turnEnds && inbox.nextStep.length === 0 在 serial 前后各出现一次。 不是冗余:serial 是异步的,期间可能有新输入进来;第二次判断才是「真的没活了」。

agent.ts:320-430(turn 全貌)

1.5

preStep:插件树的入口

这是本章的核心。preStep 做五件事,然后把「进入这一步」的决定权交给插件链:

packages/core/agent-loop/src/agent.ts:276-311
const claimed = this.inbox.claim(target, position.turn)          // ① 领走输入
const selection = this.model.current()                        // ② 当前模型
if (selection === undefined) throw new Error(`agent "${this.id}" has no provider/model…`)
const toolSet = await this.loopCtx.tools.resolve({ agent: this, modelSelection: selection, signal })   // ③ 工具准入
const assembly = await this.loopCtx.systemPrompt.assemble({ ...assembleContextFor(this, signal), modelSelection: selection, toolSet })  // ④ 拼提示
const decision = await this.dispatch.waterfall(
  'agent/pre-step', { messages: claimed, ...position, signal, modelSelection: selection },
  (): Promise<PreStepDecision> => {                            // ⑤ 默认实现(链的最内层)
    const sections = renderContextSections(assembly)
    const context = this.runtimeContext.project(joinContextSections(sections), sections)
    return Promise.resolve<PreStepDecision>({
      kind: 'enter',
      messages: context === undefined ? claimed : [...claimed, context],
    })
  },
)

这段代码的形状就是 dsh 的扩展模型:框架提供一个默认实现作为 next,插件通过 waterfall 决定要不要调到它、或者干脆返回别的。

插件返回值后果谁来用
不返回(调 next())走默认:进入这一步,消息加上上下文段绝大多数插件
{ kind: 'reject' }这一步不开,整轮标 blocked权限、配额、外部 hook 的 deny
{ kind: 'enter', messages: [...] }进入,但换掉消息注入上下文、改写用户输入
为什么 toolSet.dispose() 在 reject 分支里被显式调用: 工具准入是「本步有效」的快照(第 2 章),这一步不开就必须立刻释放。 代码里 reject 和 throw 两条路径都 dispose 了——唯独成功路径交给 step 之后的 finally。 这种「谁申请谁释放,且释放点要覆盖所有出口」的写法,比 try/finally 包的更精确。

agent.ts:276-311(preStep)· :300-308(dispose 出口)

1.6

为什么 emit 要自己实现一遍

这是全篇最能看出「作者被坑过」的一处。dsh 没有直接用 Cordis 的 emit,而是自己写了一个循环:

packages/core/agent/src/dispatch.ts:120-140
emit(name, payload) {
  // Cordis emit invokes callbacks through Array.map: one synchronous throw
  // starves later listeners, and returned promises are discarded. Agent
  // notifications are non-vetoing, so resolve the same filtered callback
  // set ourselves and contain both failure modes independently.
  const args: unknown[] = [carrier, name, fused(payload)]
  const callbacks = ctx.events.dispatch('emit', args)
  for (const callback of callbacks) {
    try {
      const returned: unknown = callback(...args)
      void Promise.resolve(returned).catch((error: unknown) => {
        ctx.logger.warn(`agent event "${name}" listener rejected: ${String(error)}`)
      })
    } catch (error: unknown) {
      ctx.logger.warn(`agent event "${name}" listener threw: ${String(error)}`)
    }
  }
},

两个独立的失败模式,各自被单独包住:

失败模式原生 emit 的后果这里的处理
监听器同步抛错 Array.map 中断 → 后面的监听器收不到事件 每个 callback 单独 try/catch,后续照常执行
监听器返回 rejected promise promise 被丢弃 → 变成 unhandled rejection Promise.resolve().catch() 记 warn

注释里那句 Agent notifications are non-vetoing 是关键定性:通知不能否决生命周期推进。 既然不能否决,那它就绝不该因为某个监听器写错而让整个 agent 停摆。

对照一下:需要「否决」的地方用 serial(第一个 bail 胜出), 需要「替换默认」的地方用 waterfall。三种语义各有各的失败策略—— 这正是第 1 章开头那张表的意义:选错派发语义,失败处理就没法写对。

dispatch.ts:120-140(自实现 emit)

1.7

把一次提问压成一条链

① 输入进收件箱 → wakeDriver()
如果驱动是 idle,开一个新 phase(running)并 kick();如果正在跑,只记 wakeRequested。
② kick() → while (await this.turn())
turn 返回 false 就停:被拒(blocked)、空决策(completed)、或正常完成。
③ turn(): append('turn/start') → 内层 while(true)
每一圈 = 一个 step。先 preStep 拿决策,再 append('step/start'),再 step(),finally 里 append('step/end')。
④ preStep() 的五件事
领输入 → 取模型 → tools.resolve() → systemPrompt.assemble() → dispatch.waterfall('agent/pre-step')。
⑤ waterfall 的默认实现 = 拼上下文档 → enter
插件可以在这之前返回 reject 或换掉 messages。
⑥ 收尾:agent/turn-stopping(serial)→ 再看一眼收件箱
没新活就 break,有新活就 target = 'next-step' 继续。

一句话总结:turn 是一条由 append 标点、由 waterfall 决定走向、由 serial 决定停不停的链。 后面五章都是这条链上某个环节的放大。

2.1

为什么工具必须先是一个注册表

在 pi 里,工具是四个函数的返回值——createReadOnlyToolDefinitions() 这样的东西, 静态、可枚举。在 dsh 里,工具是运行时可增删的分层集合,而且注册本身就是一个插件行为。

两者都合理,但代价完全不同。先看 dsh 要解决什么:

真实场景静态工具表做不到的地方
子 agent 有更少的工具 需要「按 scope 限制」,而不是复制一份新表
某个工具只在特定模型下可用 需要每步重新求值的准入条件,而不是加载时确定
插件热卸载 注册必须绑定到插件生命周期,卸载即撤销
部署方想禁掉某几个工具 限制必须能叠加(intersect),且不能改注册

这四条需求,正好对应 ToolsService 的四个机制:分层 / 准入 / effect 注册 / 限制。

index.ts:99-100(服务定义,inject = ['systemPrompt'])

2.2

view():遮蔽与限制是两件事

这是全章最容易读错的地方。view(scope) 返回一个 scope 能看到什么,它做了两轮处理, 语义完全不同:

packages/core/tools/src/index.ts:199-226
private view(scope?: ScopeKey): ToolView {
  const layers = this.layers.chainLayers(scope)
  const own = this.layers.peek(scope)
  const inherited = new Map(this.layers.global.tools.entries())
  for (const layer of layers) {
    if (layer === own) continue
    for (const [name, registration] of layer.tools.entries()) inherited.set(name, registration)
  }
  // 第一轮:继承来的(global + 祖先 scope),要过限制检查
  for (const [name, registration] of inherited) {
    if (layers.every(layer => layer.admits(name))) {
      visible.set(name, registration.definition)
    }
  }
  // 第二轮:自己 scope 注册的,无条件可见
  if (own !== undefined) {
    for (const [name, registration] of own.tools.entries()) {
      visible.set(name, registration.definition)
    }
  }
}
轮次成员受限吗为什么
继承 global + 所有祖先 scope 受:layers.every(admits) 限制是「部署方/父级对下级的约束」
自身 本 scope 注册的 不受 你给自己装的东西,不该被别人的过滤器删掉

遮蔽(shadowing)发生在第一轮的 inherited.set 上:近的覆盖远的(global 打底,祖先 scope 依次覆盖)。 而 own 被 continue 跳过、留到第二轮单独处理——否则自己就会被自己覆盖掉。

一个反直觉的推论:同一个名字的工具,可能在 A 处可见、在 B 处不可见,既不是 A 注册的也不是 B 注册的。 所以任何「工具存在吗」的判断都必须带 scope,get(name, scope) 的签名里 scope 不是可选项而是语义的一部分。

index.ts:199-226(view)· :239(get 带 scope)

2.3

注册就是一次 effect

register() 的返回值是一个 disposer,但它不是手写的清理函数——它来自 this.layers.effect(...):

packages/core/tools/src/index.ts:128-153
register(definition: ToolDefinition, options: ToolRegistrationOptions = {}): () => void {
  const name = definition.name
  const output = (definition as Partial<ToolDefinition>).output
  if (output === undefined || typeof output !== 'object'
    || typeof output.render !== 'function') {
    throw new TypeError(`tool "${name}" must declare output { schema, render, presentationMeta? }`)
  }
  assertSupportedJsonSchema(output.schema)
  if (name === RUN_CODE_NAME) {
    throw new Error(`tool name "${RUN_CODE_NAME}" is reserved for the PTC mode presentation transport…`)
  }
  return this.layers.effect(
    this.ctx,
    layer => layer.tools.insert(name, { definition, when: options.when }),
    { label: 'tools.register()' },
  )
}

三个设计点:

① 三个字段是硬要求:{ schema, render, presentationMeta? }
工具必须能渲染自己(render),不只是能执行。assertSupportedJsonSchema 还会拒绝「JSON Schema 里我们不支持的写法」—— 因为 schema 要发给模型,而不同 provider 支持度不一。
② run_code 被无条件保留
注释解释得极清楚:any agent may select a code mode for itself, so a name free to take under the deployment default would become a collision the moment a preset mounted. ——今天不冲突,不代表明天不冲突,所以现在就禁。
③ effect 让注册与插件 fiber 同生共死
插件卸载 → effect 回收 → 工具消失 → tools/change 事件 → 提示词与 schema 重新计算。 一条 effect 串起了「生命周期 → 可见性 → 提示词」。

index.ts:128-153(register)

2.4

resolve():每步一份快照 + 身份栅栏

可见性是一回事,这一步实际能用哪些是另一回事。后者由 resolve() 在 preStep 里求值(第 1 章 1.5):

packages/core/tools/src/index.ts:264-303
async resolve(context: ToolActivationContext): Promise<ResolvedToolSet> {
  const { agent, signal } = context
  signal.throwIfAborted()
  const view = this.view(agent)
  const admitted = new Map<string, ToolDefinition>()
  for (const [name, definition] of view.visible) {
    const registration = view.registrations.get(name)
    let enabled: boolean
    try {
      enabled = registration?.when === undefined || await registration.when(context)   // 条件注册
    } catch (cause: unknown) {
      signal.throwIfAborted()
      throw new ToolActivationError(name, cause)
    }
    if (enabled) admitted.set(name, definition)
  }
  let closed = false
  return Object.freeze({
    dispose: () => { closed = true },
    view: (scope) => {
      const visible = new Map()
      if (closed || scope !== agent) return visible
      const current = this.view(agent)
      for (const [name, definition] of admitted) {
        if (current.visible.get(name) === definition                        // 定义未换
          && current.registrations.get(name) === view.registrations.get(name)) {  // 注册未换
          visible.set(name, definition)
        }
      }
      return visible
    },
  })
}

这段里藏了两个非常精确的决定:

机制代码防的是什么
when 抛错 → 包装 throw new ToolActivationError(name, cause) 条件函数写错时,报错要能指向哪个工具,而不是一个光秃秃的 undefined 错误
双重身份比较 visible.get(name) === definition 且 registrations.get(name) === 快照时的 同名工具被换成了另一个对象(插件重装、热更新)时,旧快照必须失效
closed 闸门 if (closed || scope !== agent) return empty 已 dispose 的快照不允许再被查询
为什么是两个比较而不是一个:只比 definition 会漏掉「definition 对象复用了、但 registration 换了」的情形 (比如注册方偷偷换了 when 条件)。只比 registration 会漏掉「registration 没变、definition 被原地替换」。 两个都比,才叫「身份未变」。

index.ts:264-303(resolve + 身份栅栏)

2.5

一次工具调用的六个阶段

pipeline.ts 有 771 行,但它做的是一条固定流水线。压成六个阶段:

阶段做什么失败时关键点
① prepare 快照参数、冻结、分配关联 token 参数不可 JSON 化 → 立即 final-result 不可序列化的参数根本不进流水线
② pre-execute tools/pre-execute waterfall:策略 + 守卫 + 审批 拒绝 → final-result,不执行 这里是外部 hook 的 deny 落地处(第 5 章)
③ execute tool.execute(args, exec) 抛错 → toolErrorResult,变成模型可见的输入 错误不是异常,是数据
④ post-execute tools/execute 事件,可要求再跑一轮 — 允许「结果出来了但我还想改」
⑤ finalize finalizeContent:定义自己收尾 — 截断、附路径、加提示都在这
⑥ materialize 无损、冻结、发布给观察者 — Object.freeze 后的同一份给所有人

其中「先抓回调、再读参数」这一步单独值一提——因为参数可能带 getter:

packages/core/tools/src/pipeline.ts:147-158
// Capture callbacks before argument getters run; rejected calls retain finalization only when aborted.
const capturedFinalizer = visible?.finalizeContent?.bind(visible)
const capturedProjector = visible?.projectContent?.bind(visible)
const finalizerFor = (): ToolDefinition['finalizeContent'] | undefined =>
  rejected && !signal.aborted ? undefined : capturedFinalizer
try {
  const detached = snapshotJsonValue(exec.arguments)
  if (detached === undefined) {
    throw new TypeError('tool execution arguments must be losslessly JSON-serializable')
  }
  const execution: MutableToolRunContext = { ...base, arguments: deepFreeze(detached) }

rejected && !signal.aborted ? undefined : capturedFinalizer 这一行值得慢慢读:

情形保留 finalizer为什么
被策略拒绝,且未中断不保留压根没执行,没有产出可收尾
被策略拒绝,但已中断保留中断前可能已有部分输出,仍要按工具自己的方式收尾
正常进入执行保留—

pipeline.ts:147-158(prepare 快照)· :190-230(pre-execute)

2.6

执行器也是可换的

最后一个可插拔点:「怎么执行一批工具」本身是个服务。selectExecutor 按 scope 链就近查找:

packages/core/tools/src/index.ts:357-366
private selectExecutor(scope?: ScopeKey): ToolExecutor {
  let record: Registration | undefined
  for (const key of scopeChainOf(scope)) {
    record = this.scoped.get(key)
    if (record !== undefined) break
  }
  record ??= this.root
  const executor = record?.executor
  if (executor === undefined) throw new ToolExecutorUnavailableError()
  return executor
}

这就是为什么 ToolsService.Config 里那两个字段被写成 z.never()—— mode 和 maxParallelSubCalls 被移除了,改成「装一个 executor 插件」:

mode: z.never().description('Removed. Mount a native or PTC tool executor instead.')
mode:已移除。改为挂载一个 native 或 PTC 工具执行器。
— packages/core/tools/src/index.ts:101
z.never() 是一种「迁移 API」的写法:字段还在 schema 里,所以老配置文件会被读到并明确报错, 而不是被静默忽略。删字段会让用户拿到「配置没生效但不报错」这种最难查的 bug。

index.ts:357-366(selectExecutor)· :101-104(z.never 迁移)

2.7

四层过滤器,从粗到细

① 分层(register / effect)——谁能装工具
注册绑在插件 fiber 上;scoped 注册遮蔽 global;run_code 与同层重名直接抛错。
② 限制(restrict)——部署方/父级砍工具
allow / deny 在 scope 链上求交;只作用于继承来的,自己的注册豁免。
③ 准入(when + resolve)——这一步能不能用
每步重新求值;抛错包成 ToolActivationError;结果是一份冻结快照 + dispose。
④ 守卫(guard / pre-execute)——这一次调用能不能落地
单调拒绝(只说不),在 pre-execute 之后、dispatch 之前检查;外部 hook 的 deny 也从这里进。

四层各有各的粒度:装 / 砍 / 本步可用 / 本次可执行。 在 pi 里这四件事被压成一件事(函数返回数组),代价是「按 scope 变化」和「热卸载」做不到; dsh 把代价明确摊开成四层,代价是读代码必须先看 scope。

3.1

seq 就是数组下标,永不重编号

append-only 日志的第一条铁律,dsh 用一行代码就实现了:

packages/core/session/src/index.ts:817-835(略去 surfaceMetadata 快照段)
const dataSnapshot = snapshotJsonValue(data)
if (dataSnapshot === undefined) {
  throw new Error(`session event "${type}" carries non-JSON-serializable data`)
}
const event = deepFreeze({
  type,
  seq: SessionSeq(this.log.length),      // ← 就是这个
  time: Date.now(),
  data: dataSnapshot,
} as unknown as SessionEvent<T>)
validateSessionEventData(event, `session event "${type}" at seq ${event.seq}`)
this.commit(event as SessionEvent, entry)
return event

seq = log.length:序号不是计数器,是下标。这三行推论一路贯穿到压缩(第 4 章):

推论代码意义
取事件 = 数组下标访问 this.log[seq]! O(1),不需要 Map 索引
连续性可校验 event.seq !== expectedSeq → 抛错 日志缺一条立刻发现
序号永不复用 只 push,不 splice 任何 seq 永久指向同一事件

this.log[seq]! 那行注释写得很诚实:

Surface sequences are built from this.log — seq is always a valid index by construction. The non-null assertion expresses that invariant.
surface 序列由 this.log 构造——按构造法 seq 永远是合法下标。那个非空断言就是在表达这条不变式。
— packages/core/session/src/index.ts:1009-1010

index.ts:817-835(append 分配 seq)· :1009-1010(seq 即下标)

3.2

surface 只是一串指向日志的下标

模型看到的「对话历史」不是日志本身,而是日志的一个视图。这个视图的数据结构简单到只有三个字段:

packages/core/session/src/surface.ts:244-252
export interface SessionSurface {
  /** Current surface event sequences in model-visible order. */
  readonly nodes: readonly SessionSeq[]
  /** Monotonic count of committed positional replacements. */
  readonly replaceGeneration: number
  /** Monotonic count of committed replacements and plugin-owned message changes. */
  readonly contentGeneration: number
}

nodes 是一串 seq,顺序即模型可见顺序。它不存消息内容,内容永远回日志里取。 所以「改历史」不是改消息,而是改这串下标。

操作对 nodes 做什么代际变化
appendnodes.push(seq)无
replacenodes.splice(startIdx, count, newSeq)replaceGeneration++ 且 contentGeneration++
project不动 nodes,改派生的消息副本仅 contentGeneration++
packages/core/session/src/surface.ts:567-577
if (plan?.kind === 'append') {
  state.nodes.push(plan.seq)
} else if (plan?.kind === 'replace') {
  state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq)
  state.replaceGeneration += 1
  state.contentGeneration += 1
} else if (plan?.kind === 'project') {
  for (const [seq, message] of plan.messages) state.projectedMessages.set(seq, message)
  state.projections.add(plan.projection)
  state.contentGeneration += 1
}

surface.ts:244-252(SessionSurface)· :567-577(三种折叠)

3.3

为什么需要两个代际

这是本章最精妙的一处。replaceGeneration 和 contentGeneration 几乎总是同步增长, 但有一个操作只动后者:project。

问题该问哪个代际为什么
「历史被裁剪过吗?」 replaceGeneration 压缩改变了范围,token 账要重算
「派生消息还能用吗?」 contentGeneration 只要内容变了缓存就失效,不管变的是范围还是内容

所以 deriveMessages() 的缓存看的是 contentGeneration—— 它不关心「为什么变」,只关心「变没变」:

packages/core/session/src/index.ts:999-1019
deriveMessages(): Message[] {
  const surface = this.surface
  const nodes = surface.nodes
  const generation = surface.contentGeneration
  if (generation !== this.derivedGeneration) {
    this.derived = []          // 代际变了 → 整体重建
    this.derivedNodes = 0
    this.derivedGeneration = generation
  }
  for (const seq of nodes.slice(this.derivedNodes)) {   // 否则只追加尾部
    const msg = this.deriveEventMessage(this.log[seq]!)
    if (msg) this.derived.push(msg)
  }
  this.derivedNodes = nodes.length
  return [...this.derived]
}

两种路径,代价完全不同:

常见路径:append 之后
代际没变 → nodes.slice(derivedNodes) 只处理新增的尾部。 每次追加是 O(新增条数),不是 O(历史长度)。这是长会话能跑下去的物理原因。
稀有路径:replace / project 之后
代际变了 → derived = []、derivedNodes = 0,整个历史重新派生一遍。 压缩一次的代价是 O(整段历史),但因为压缩本来就少,这个交换是划算的。
为什么不用「增量修补」
replace 是把一段节点换成一个新节点,中间那些消息派生结果要一起丢。 增量修补需要精确知道「哪几条受影响」——而那正是 surface 已经知道的事,重算一遍更简单且不会错。
返回 [...this.derived] 而不是 this.derived:内部缓存数组不能交给外面, 否则调用方 push 一下就污染了缓存。消息对象本身是冻结共享的(策略是「不可变数据共享、容器复制」), 所以复制数组几乎不花钱。

index.ts:999-1019(deriveMessages 缓存)

3.4

replace 的边缘是「位置」,不是「序号大小」

这一节解释第 4 章那句让人困惑的话:「start 和 end 按 surface 位置命名,而不是数值 seq 顺序」。 原因就在这里——indexOf:

packages/core/session/src/surface.ts:418-430
const startIdx = state.nodes.indexOf(op.startSeq)
if (startIdx === -1) {
  // 不在 surface 上 → 抛错
}
const endIdx = state.nodes.indexOf(op.endSeq)

关键:边缘是通过在节点数组里「找位置」确定的,不是比较数字。
于是 splice(startIdx, endIdx - startIdx + 1, newSeq) 天然就是「按可见顺序切一段」。

情形nodes结果
纯 append [0,1,2,3,4] seq 单调递增,位置 = 序号大小
压缩掉 [1,2,3] [0,9,4] 非单调:9 在 4 前面
此时 indexOf(4) — 返回 2,而 4 > 9 也成立——数字大小完全失去意义

所以任何「从 seq A 到 seq B」的逻辑都不能写成 for (let s = A; s <= B; s++)。 这个坑不是理论上的——第 4 章的 compactRegion 文档特意写了这句话警告调用方。

surface.ts:418-430(indexOf 定位)· compaction:170-171(非单调警告)

3.5

replace 的四条校验

「能改历史」是危险能力。dsh 用四条校验把它的边界钉死,全部在追加之前完成:

校验规则防什么
引用必须更早 sourceEventSeqs 里每个 seq 都 < event.seq 不许引用未来事件(否则日志不可重放)
不许重复 duplicates → 抛错 同一事件不能被同一替换引用两次
必须覆盖全部被遮蔽节点 missing → 抛错(列出缺哪些) 不能「悄悄」删掉一个节点而不声明它被谁替代
system prompt 特殊 node 0 只能被 system/message 且长度恰为 1 的替换改写 系统提示不能被压缩顺手吃掉
packages/core/session/src/surface.ts:355-364
if (sources.size !== raw.length) {
  throw new Error('sourceEventSeqs must not contain duplicates')
}
if (nonEarlierSource !== undefined) {
  throw new Error(`sourceEventSeqs must reference earlier events: ${nonEarlierSource} >= current seq ${event.seq}`)
}
const missing = shadowedSeqs.filter(seq => !sources.has(seq))
if (missing.length > 0) {
  throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(', ')}`)
}
第三条是整个设计的关键:它把「删除」变成「替换 + 声明」。 你删掉的每一个节点,都必须在 sourceEventSeqs 里出现——于是任何一段历史的消失,都能被追溯到是谁替代了它。 这是 recovery.html 里那种「删了但没人知道」问题在数据结构层的答案。

surface.ts:355-364(四条校验)· :492-506(system head 特例)

3.6

这套设计的账单

公平地说代价。dsh 没有选 pi 那种「树 + 父指针 + 分支」,而选了「单链 + replace」, 换来了能力,也换了复杂度:

得到付出具体账单
改历史的唯一入口 每个消费者都要考虑非单调 「A 到 B 之间」必须按位置查,不能按数值遍历
缓存命中率高 两个代际要分清 用错代际 → 要么缓存过期不失效,要么白重建
日志永不可变 派生逻辑成了一条第四种路径 append / replace / project / 投影未加载 → 四种分支(见下)
seq 恒定可寻址 日志只增不减 磁盘增长靠上层切分,不靠日志自己回收

「第四种路径」指的是 planSurfaceEvent 里那个容易漏的分支—— 日志里出现了当前没加载插件的消息类型时,直接抛错而不是静默跳过:

session event "${event.type}" requires a message projection; load its owning plugin or supply its projection definition
「该事件需要消息投影;请加载它所属的插件,或提供投影定义」
— packages/core/session/src/surface.ts:529-531

一句话总结第 3 章:dsh 的「历史」有两种形态——永不改的日志(按 seq 寻址)和可改的视图(按位置寻址); 两个代际就是这两者之间的汇率。

surface.ts:529-531(缺投影即抛错)

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 的经济学」——先找免费的,再找便宜的,最后才花钱。

5.1

三层:协议 / 方言 / 桥

「兼容 Claude Code 的 hooks」听起来是一个适配器,dsh 把它拆成了三层,而且每层都可以单独测试:

包行数它知道什么 / 不知道什么
hook-protocol 约 780 知道「hook 有输入输出、有匹配器、要合并、要执行」;不知道 Claude Code 或 Codex 的任何细节
hooks-claude-code 488 知道 CC 的事件名与配置格式;不知道 dsh 的决策类型
hooks-codex — 同上的 Codex 方言

每条边的职责都写在模块注释的第一行,读起来像分工声明:

文件自述
merge.ts 把匹配到的多个 hook 折成一个最严格的结果
matcher.ts 决定哪个 hook 匹配这个事件
runner.ts 通过 ctx.shell 执行命令,复用它的凭据擦除、进程组取消、超时机制
codec.ts 解析 hook 的输出
runner.ts 那句「复用 ctx.shell 的…」是这层拆分的价值所在: 执行外部进程最危险的三件事(凭据泄漏、子进程逃逸、挂死)已经有人在 ctx.shell 里解决了, hook 层不需要重新发明。

merge.ts:1-6(自述)· runner.ts:1-5(复用 ctx.shell)

5.2

合并规则:最严格的赢

一个事件可能匹配多个 hook,它们的意见会冲突。dsh 用一套固定的优先级把冲突压平:

packages/experimental/hook-protocol/src/merge.ts:35-43
function rank(decision: HookOutput['decision']): number {
  switch (decision) {
    case 'deny': case 'block': return 3
    case 'ask': return 2
    case 'approve': case 'allow': return 1
    default: return 0 // no decision
  }
}

四条规则合起来是一个单调收紧的折叠:

规则结果为什么
权限取最严 deny > ask > allow 一个 hook 说不行,就真的不行——安静地放行是安全事故
block/deny 归一 两者都折到 deny CC 用 block,dsh 用 deny,语义相同
第一个 continue:false 粘住 stop = true 且保留其 stopReason 停止是终态,后面的 allow 不能把它取消
理由拼接而非覆盖 \n\n 连接所有阻塞理由 用户需要看到所有拒绝原因,不是一个
「context 和 systemMessage 按 hook 顺序累积」(不拼接)——注释特意点出这个不对称: 理由要合成一句话给用户看,上下文要保留成独立条目给模型用。 合并策略取决于「谁消费这个字段」,不是取决于字段类型。

merge.ts:35-43(rank)· :14-32(MergedHookOutcome)

5.3

翻译表:CC 事件 → dsh 决策

桥接层要支持的 CC 事件有七个(CLAUDE_EVENTS),但只有四个真正接进了控制流。 这个不对称本身就是信息:

CC 事件接到哪个 dsh 点能改变什么
PreToolUse tools/pre-execute waterfall 能拒绝(deny / ask / 放行)
PostToolUse tools/post-execute 能拦截并反馈(block + 文本回给模型)
UserPromptSubmit PreStepDecision 能改写/阻止用户输入进入这一步
Stop agent/turn-stopping 能强制继续(steer 一条消息)
SessionStart 启动钩子 只能观察(失败只 warn)
SubagentStart / SubagentStop 声明支持 取决于子 agent 插件是否装了
packages/experimental/hooks-claude-code/src/index.ts:243-249
ctx.on('tools/pre-execute', async (exec, next): Promise<PreToolDecision> => {
  const turn = lastTurn(ctx, exec.agent)
  const merged = await runPoint('PreToolUse', exec.name, preToolPayload(exec), { ..., signal: exec.signal })
  if (merged.decision === 'deny') return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' }
  if (merged.decision === 'ask') return { kind: 'ask', ...merged.reason !== undefined ? { reason: merged.reason } : {} }
  return next()      // ← 没意见就往下传,不吞掉
})

最后那行 return next() 是整个桥接层最重要的习惯:hook 没意见时必须把决定权传下去, 而不是返回一个「允许」。因为后面可能还有别的监听器(dsh 自己的守卫、另一个插件)。

config.ts:11-19(七个事件)· index.ts:243-249(PreToolUse 桥)

5.4

PostToolUse 为什么写成那样

这是我见过最讲究的一段桥接代码——它先调 next() 再把自己的上下文折上去:

packages/experimental/hooks-claude-code/src/index.ts:252-270
// Our hooks did not block. DELEGATE so a later listener can still block/replace,
// then fold our context onto its decision (a downstream block carries it too).
const downstream = await next()
if (!context) return downstream
if (downstream.kind === 'block') {
  return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }
}
return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) }

这个写法解决了 waterfall 里一个真实的两难:

写法后果问题
不调 next(),直接返回自己的 后面的监听器全部失效 hook 悄悄接管了本该属于 dsh 的决定
调了 next(),返回它的结果 自己的上下文丢失 hook 白跑了
调 next(),再把上下文折上去 两者都保留 —(这就是它做的)
两个 if 分支的返回值看起来一样(都 return {...downstream, additionalContexts: ...}), 第一个分支其实是冗余的——很可能原本打算对 block 做不同处理。 这类「保留了两条等价的路径」在成熟代码里通常是重构留下的痕迹,不影响正确性,但读的时候会卡一下。

index.ts:252-270(PostToolUse 委托)

5.5

Stop hook 能「不许停」——以及它承认的缺环

Stop 是权限最大的一个:它可以让 agent 不许结束这一轮。

packages/experimental/hooks-claude-code/src/index.ts:272-282
// A blocking Stop hook steers at the stopping boundary, which makes the
// machine observe pending input and run another step.
// TODO(stop-loop-guard): cap consecutive forced continuations; hooks must self-limit meanwhile.
ctx.on('agent/turn-stopping', async ({ agent, turn, signal }): Promise<void> => {
  const merged = await runPoint('Stop', '', stopPayload(agent), { agent, turn, signal })
  if (merged.decision === 'deny') {
    // A blocking Stop hook forces continuation.
    const text = merged.reason ?? 'continue: blocked by Stop hook'
    agent.steer(createUserMessage({ content: [{ type: 'text', text }], source: CONTEXT_SOURCE }))
  }
})

那行 TODO 值得单独放大看,因为它是本次分析里唯一一处「代码自己承认的缺环」:

TODO(stop-loop-guard): cap consecutive forced continuations; hooks must self-limit meanwhile.
TODO(停止循环护栏):限制连续强制继续的次数;在此之前,hook 必须自行约束。
— packages/experimental/hooks-claude-code/src/index.ts:274
这正好落在对比站 recovery.html 标注为「共同真空」的那一行上。 那一页说 pi 与 dsh 都没有「最大迭代轮数」;这里给出了 dsh 的准确状态—— 不是没有意识到,而是在源码里写了 TODO 并明确把责任推给 hook 作者。 这比「完全没想到」好,比「已经做了」差,属于已知未修。 同一个 recovery.html 的六条改造清单里第 3 条「可配迭代上限」,对 dsh 来说落点就是这行 TODO。

顺带一个连锁反应:Stop hook 说「不许停」时,agent 会 steer 一条消息, 于是收件箱非空 → 第 1 章 1.4 那个「turnEnds && inbox.nextStep.length === 0」判断不成立 → 再跑一步。 整条「hook → 控制流」的链路就是靠这一个收件箱条件接通的。

index.ts:272-282(Stop 桥 + TODO)

5.6

两个方言的差异,被压缩成一个 boolean

协议层有一处细节,把「抽象到底该多细」这个问题回答得很干脆:

Whether to append a trailing newline to the stdin payload (CC yes, Codex no).
是否给 stdin 的 payload 追加一个结尾换行(Claude Code 要,Codex 不要)。
— packages/experimental/hook-protocol/src/runner.ts:34

这是个真实存在的、无法回避的差异:某些 hook 脚本用 read 或 fgets 读 stdin, 没有换行就读不到最后一行。所以协议层把它变成 RunHookOptions.trailingNewline, 由方言层决定填什么。

差异归属哪层怎么表达
事件名方言层CLAUDE_EVENTS 常量
配置格式方言层config.ts 的解析器
stdin 结尾换行方言层trailingNewline: boolean
默认超时协议层DEFAULT_HOOK_TIMEOUT_MS = 600_000(10 分钟,两家一致)
合并规则协议层merge.ts(两家一致)
10 分钟默认超时只写了一次,注释还特意说明「这是 CC 和 Codex 在 hook 未配置 timeout 时都采用的值」。 把「两家偶然一致」固化成协议层的单一常量,而不是让两个方言各写一遍——这就是协议层存在的意义。

runner.ts:14-20(默认超时)· :34(trailingNewline)

5.7

这一层的三个可复用结论

① 协议层只放「两家都同意」的东西
合并规则、默认超时、执行方式 → 协议层;事件名、配置格式、换行 → 方言层。分歧越大,越要往下放。
② 合并策略是单调收紧,不是多数投票
安全相关的判断不能靠「多数同意」。一个 deny 就够否决全部 allow。
③ 借别人的命脉(ctx.shell),别自己造
凭据擦除、进程组取消、超时——这三件事自己做一定会漏。

一句话:hooks 兼容层是 dsh「一切皆插件」最实用的证明——它没有把 Claude Code 的支持写进内核,而是写成了一层可卸载的适配器。 代价是:每个方言的差异都得有人显式写出来(比如那个换行)。

6.1

在追加点失败,而不是在落盘时

第 3 章讲了 append 怎么分配 seq。它还有后半段——写进去之前要过一遍严格的 JSON 检查, 而且注释明确说了为什么:

One iterative pass reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. The event log is the durable source of truth, so a bad event fails at the append site rather than later during a backend flush.
一趟迭代就把每个嵌套值读取、校验、复制各一次,所以有状态的 getter 无法「校验时给一个值、存储时给另一个值」。事件日志是持久的真相来源,因此坏事件在追加点就失败,而不是拖到后端落盘时才失败。
— packages/core/session/src/index.ts:796-801

这条「不许通过的清单」写得很全:

被拒绝的值为什么它不能进日志
BigInt / function / symbol / undefined JSON.stringify 之后信息丢失,重放出来就不是原来的事件
NaN / Infinity / -0 序列化后变 null 或 0——悄悄改变数值
循环引用 无法序列化
稀疏数组 空洞在 JSON 里变 null
Map / Set / Date / 类实例 序列化成 {} 或字符串——看起来成功了,实际全丢了
最后一行是最阴的:JSON.stringify(new Map([[1,2]])) 得到 "{}",不报错。 等你在三天后恢复会话时才发现上下文空了。所以这里用的是「白名单式深拷贝」(snapshotJsonValue), 不是 JSON.parse(JSON.stringify(x))。

index.ts:796-801(fail at the append site)· :806-836(append 主体)

6.2

物理有效 ≠ 语义完整

这是第 6 章的核心分野。恢复会话时,持久层交回来的日志是物理有效的—— 每条都能解析、seq 连续、schema 对得上。但它可能语义上是断的:

日志尾部状态物理有效?语义完整?后果
turn/start 之后就没了 ✅ ❌ 轮次没结束 下一轮开始时就出现了嵌套 turn
有 assistant/message 带 tool-call,无 tool/result ✅ ❌ 配对不全 provider 直接 400(悬空调用)
step/start 无 step/end ✅ ❌ step 悬空 状态机进不去下一个 step

dsh 把这两件事分给两层做,而且写在了注释里:

Semantic crash repair is the agent layer's job: persistence hands back the physically valid log; an interrupted final turn receives synthetic closers (missing tool errors, step/end, turn/end) that are appended through the same handle as an ordinary batch.
语义层的崩溃修复是 agent 层的职责:持久层只交回物理有效的日志;被中断的最后一轮会收到合成的收尾事件(补齐的工具错误、step/end、turn/end),并且通过与普通批次完全相同的 handle 追加。
— packages/core/agent-loop/src/index.ts:793-797

「通过相同的 handle 追加」这句话很关键:修复不搞特殊通道。 收尾事件和正常事件在日志里长得一模一样、走同一条写入路径、接受同一套校验。 所以修复本身也是可重放的——如果有人崩溃在修复过程中,下次启动还能再修一次。

index.ts:793-804(语义修复归属)

6.3

两个错误码,因为事实有两种

收尾时最关键的一个区分:那个工具调用到底有没有开始执行? 这两种情形对模型意味着完全不同的下一步。

packages/core/session/src/repair.ts:14-19
/** Recovery code for an assistant tool request that never reached a recorded call start. */
export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED'

/** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
export const TOOL_OUTCOME_UNKNOWN = 'TOOL_OUTCOME_UNKNOWN'
错误码含义给模型的建议
TOOL_NOT_STARTED 助手请求了,但连「开始」都没记上 「如果仍然需要,就重试」——可以放心重试
TOOL_OUTCOME_UNKNOWN 「开始」记上了,但结果没落盘 「按工具语义判断:只读或幂等才能重试;可能有副作用就先核实外部状态或问用户。不要盲目重试」

判定依据就是 callSeq 存不存在——一个字段承载了整个区分:

packages/core/session/src/repair.ts:166-194
for (const [callId, { turn, step, callSeq }] of this.pendingCalls) {
  const started = callSeq !== undefined
  const message: ToolResultMessage = deepFreeze({
    id: brandString<MessageId>(`${this.cause.kind}-tool-result-${callId}-${seq}`),
    role: 'tool',
    toolCallId: callId,
    isError: true,
    source: { kind: 'tool', callId },
    content: [{ type: 'text', text: started ? text.started : text.notStarted }],
  })
  results.push({
    type: 'tool/result',
    seq: SessionSeq(seq++),
    time,
    data: {
      turn, step, message,
      error: started
        ? { name: 'ToolOutcomeUnknownError', code: TOOL_OUTCOME_UNKNOWN }
        : { name: 'ToolNotStartedError', code: TOOL_NOT_STARTED },
    },
    surfaceOp: 'append',
    ...started ? { sourceEventSeqs: [callSeq] } : {},
  })
}

三处细节,每一处都值得学:

① 消息 id 是确定性的
`${cause.kind}-tool-result-${callId}-${seq}`——不含随机数、不含时间戳。 崩溃两次跑两次修复,生成完全相同的 id,不会产生重复消息。
② sourceEventSeqs: [callSeq]
只有「确实开始过」的那条才带上——符合第 3 章「引用必须更早」的规则, 而且让这个合成结果指回它对应的那次真实调用。
③ 时间戳复用最后一条真实事件的时间
const time = last.time。注释说:reusing the last timestamp keeps them deterministic and never invents a "future" time. 合成事件不允许伪造「未来」时间。

repair.ts:14-19(两个错误码)· :166-194(生成结果)

6.4

给模型的文案,是按「能不能重试」写的

这是全篇最见功力的一段字符串。CLOSER_TEXT 不是「出错了」,而是一份重试决策指引:

packages/core/session/src/repair.ts:32-35
started: 'The tool call was interrupted after it was recorded, but no result was durably recorded. Its outcome is unknown. Decide whether to retry from the tool semantics: retry only if the operation is read-only or idempotent; if it may have side effects, first verify external state or ask the user. Do not retry blindly.'

把它拆成四个动作,每个都对应一个具体的判断:

句子它要求模型做什么
Its outcome is unknown.先承认不确定性,不要假设成功或失败
Decide from the tool semantics.把判断依据指向这个工具本身,不是泛指
only if read-only or idempotent给出可操作的判据(二分:安全 / 不安全)
first verify external state or ask the user给出两条兜底路径,其中一条是升级给人
Do not retry blindly.结尾是一个明确的禁令
两种 cause 有四段不同文案(interrupted / forked × started / notStarted)。 forked 那两段的措辞不是「被中断」而是「父会话可能在分叉点之后完成了它」—— 因为分叉场景下,那个调用很可能真的成功了,只是结果在另一条分支上。 同一个不确定性,两种成因,两套措辞。

repair.ts:32-41(四段文案)· :21-26(两种 cause)

6.5

修复是个纯状态机

ToolCallRecovery 的全部状态只有两个字段——待答调用表和最后一条事件。 它不存历史:

packages/core/session/src/repair.ts:106-149
private readonly pendingCalls = new Map<ToolCallId, { turn: number; step: number; callSeq?: SessionSeqType }>()

observe(event: SessionEvent): void {
  this.last = { seq: event.seq, time: event.time }
  switch (event.type) {
    case 'turn/start': case 'turn/end': case 'step/end':
      this.pendingCalls.clear()      // 边界到了 → 待答清零
      break
    case 'assistant/message':
      for (const block of event.data.message.content) {
        if (block.type === 'tool-call') this.pendingCalls.set(block.id, { turn, step })
      }
      break
    case 'tool/call': {
      const entry = this.pendingCalls.get(event.data.callId)
      if (entry) entry.callSeq = event.seq      // ← 记下「确实开始了」
      break
    }
    case 'tool/result': {
      const entry = this.pendingCalls.get(callId)
      if (event.surfaceOp === 'append' && entry?.turn === ... && entry?.step === ...) {
        this.pendingCalls.delete(callId)      // 有结果了 → 不再待答
      }
    }
  }
}

这个状态机的三个性质,让它可以在三种场景下复用:

性质意义
纯观察(不改 session) 可以订阅 session/event 边跑边看,不干扰主流程
只留待答身份,不留历史 内存 O(未答调用数),崩溃日志再长也不爆
turn / step 边界清零 上一个 step 的悬空调用不会污染下一个

三种用法,都真实存在于代码里:

① 崩溃恢复
interruptedTurnClosers(events) — 扫整个持久日志,补收尾
② 分叉种子
openTurnClosers(prefix, { kind: 'forked' }) — 分叉点落在未闭合轮次里
③ 活着的 step
第 1 章 1.4 那个 step() 的 catch 里就 new 了一个 ToolCallRecovery() 并订阅事件—— 工具批量执行中途抛错时,用它补齐悬空结果。同一套逻辑,三种时机。

repair.ts:106-149(observe 状态机)· agent.ts:358(活 step 也用它)

6.6

连只读查询都要修尾

session-query 的冷读有一个非常值得玩味的地方:它只读,但仍然会补收尾事件—— 补在返回给调用方的视图里,不写回日志。

packages/session-query/session-query/src/cold-read.ts:49-57
await handle.close()
const { events } = read
return {
  eventState: read.eventState,
  header: handle.header,
  inheritedEventCount: handle.inheritedEventCount,
  events: [...events, ...interruptedTurnClosers(events)],      // 视图里补,不改日志
}

为什么只读也要补?因为读的人会拿这份事件去做和线上一样的渲染。 如果尾部有一个悬空的 tool-call,UI 那边就得自己再处理一次「这条没有结果」—— 于是同一件事在两个地方各写一遍,迟早不一致。

这条设计原则可以单独拿出来用:让「读到的历史」和「活着的历史」形状一致, 消费方就不需要区分两种来源。代价是每次冷读都多跑一遍 O(n) 扫描——而这是值得的, 因为它把「不一致」从运行时随机出现变成了构建时不存在的可能。

cold-read.ts:49-57(只读也修尾)· fork.ts:29(分叉也用同一函数)

6.7

和 pi 对照:两种「树」,两种恢复

问题pidsh
历史结构 append-only 树(id/parentId,可分支) append-only 单链 + surface 替换
坏数据的防线 写入时校验 写入时严格 JSON 白名单 + 深冻结 + 校验(796-801)
崩溃后补什么 补配对的工具错误(合成) 补工具错误 + step/end + turn/end(完整收尾)
两种不确定性 未细分 两个错误码 + 两套文案
修复是否可重放 — 是(确定性 id + 复用时间戳 + 同一 handle)
只读视图 — 也修尾,保持形状一致

一句话:pi 的恢复是「给模型一个解释」,dsh 的恢复是「把日志修补成一台状态机能继续跑的形状」。 前者更轻,后者更彻底——因为 dsh 的日志要能同时喂给恢复会话、分叉、只读查询三条路径, 所以它必须是一个「不管从哪读都完整」的东西。

但仍然缺的那一块:这套机制处理的是「崩溃造成的不完整」,不是「模型原地打转」。 对比站 recovery.html 标为「共同真空」的三项——重复调用指纹、连续失败计数、最大迭代轮数—— 在 dsh 里最好的证据就是第 5 章那行 TODO(stop-loop-guard)。 能修好日志,不等于能修好行为。

repair.ts:53-98(openTurnClosers)· hooks-claude-code:274(仍缺的护栏)

《深入理解 dsh》六章合订 · 证据锚点固定 commit 22ddee3