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

深入理解 dsh/第 06 章

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(仍缺的护栏)

本章学习记录

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