深入理解 dsh/第 06 章
在追加点失败,而不是在落盘时
第 3 章讲了 append 怎么分配 seq。它还有后半段——写进去之前要过一遍严格的 JSON 检查,
而且注释明确说了为什么:
这条「不许通过的清单」写得很全:
| 被拒绝的值 | 为什么它不能进日志 |
|---|---|
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 章的核心分野。恢复会话时,持久层交回来的日志是物理有效的—— 每条都能解析、seq 连续、schema 对得上。但它可能语义上是断的:
| 日志尾部状态 | 物理有效? | 语义完整? | 后果 |
|---|---|---|---|
turn/start 之后就没了 |
✅ | ❌ 轮次没结束 | 下一轮开始时就出现了嵌套 turn |
有 assistant/message 带 tool-call,无 tool/result |
✅ | ❌ 配对不全 | provider 直接 400(悬空调用) |
step/start 无 step/end |
✅ | ❌ step 悬空 | 状态机进不去下一个 step |
dsh 把这两件事分给两层做,而且写在了注释里:
step/end、turn/end),并且通过与普通批次完全相同的 handle 追加。「通过相同的 handle 追加」这句话很关键:修复不搞特殊通道。 收尾事件和正常事件在日志里长得一模一样、走同一条写入路径、接受同一套校验。 所以修复本身也是可重放的——如果有人崩溃在修复过程中,下次启动还能再修一次。
index.ts:793-804(语义修复归属)
两个错误码,因为事实有两种
收尾时最关键的一个区分:那个工具调用到底有没有开始执行? 这两种情形对模型意味着完全不同的下一步。
/** 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 存不存在——一个字段承载了整个区分:
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] } : {}, }) }
三处细节,每一处都值得学:
`${cause.kind}-tool-result-${callId}-${seq}`——不含随机数、不含时间戳。
崩溃两次跑两次修复,生成完全相同的 id,不会产生重复消息。
sourceEventSeqs: [callSeq]const time = last.time。注释说:reusing the last timestamp keeps them deterministic and never invents a "future" time.
合成事件不允许伪造「未来」时间。
repair.ts:14-19(两个错误码)· :166-194(生成结果)
给模型的文案,是按「能不能重试」写的
这是全篇最见功力的一段字符串。CLOSER_TEXT 不是「出错了」,而是一份重试决策指引:
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. | 结尾是一个明确的禁令 |
interrupted / forked × started / notStarted)。
forked 那两段的措辞不是「被中断」而是「父会话可能在分叉点之后完成了它」——
因为分叉场景下,那个调用很可能真的成功了,只是结果在另一条分支上。
同一个不确定性,两种成因,两套措辞。
repair.ts:32-41(四段文案)· :21-26(两种 cause)
修复是个纯状态机
ToolCallRecovery 的全部状态只有两个字段——待答调用表和最后一条事件。
它不存历史:
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() 的 catch 里就 new 了一个 ToolCallRecovery() 并订阅事件——
工具批量执行中途抛错时,用它补齐悬空结果。同一套逻辑,三种时机。
repair.ts:106-149(observe 状态机)· agent.ts:358(活 step 也用它)
连只读查询都要修尾
session-query 的冷读有一个非常值得玩味的地方:它只读,但仍然会补收尾事件——
补在返回给调用方的视图里,不写回日志。
await handle.close() const { events } = read return { eventState: read.eventState, header: handle.header, inheritedEventCount: handle.inheritedEventCount, events: [...events, ...interruptedTurnClosers(events)], // 视图里补,不改日志 }
为什么只读也要补?因为读的人会拿这份事件去做和线上一样的渲染。 如果尾部有一个悬空的 tool-call,UI 那边就得自己再处理一次「这条没有结果」—— 于是同一件事在两个地方各写一遍,迟早不一致。
cold-read.ts:49-57(只读也修尾)· fork.ts:29(分叉也用同一函数)
和 pi 对照:两种「树」,两种恢复
| 问题 | pi | dsh |
|---|---|---|
| 历史结构 | 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(仍缺的护栏)