深入理解 dsh
单页全本
六章合订。适合 Ctrl+F 搜索与打印。
先分清四种「派发」,不是一种
读 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(),调用它就继续往里走,不调用就截断整条链。
next 回调结尾,因此 rest 恰好是 payload 之后的全部参数——最后一个是最内层的 next,也就是监听链所包裹的那个默认行为。dispatch.ts:73-81(waterfall 契约)
入口:一个 Service,六个注入项
整个 agent 循环是一个 Cordis 服务。它能用到什么,写在 static inject 里——
这是读 dsh 最省力的入手点,因为它等于一张依赖清单:
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 的服务生命周期约定,等价于「所有依赖都就绪之后再跑」。
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)
三层:kick → turn → step
dsh 的循环也是嵌套的,但分层方式和 pi 不一样:它把「驱动」和「轮次」和「步」分成三个不同职责。
| 层 | 代码 | 循环 | 它管什么 |
|---|---|---|---|
| L1 驱动 | agent.ts:259 |
while (await this.turn()) {} |
「还有没有下一轮」 |
| L2 轮次 | agent.ts:332 |
while (true) + break |
这一轮里的若干 step |
| L3 步进 | preStep() + step() |
不是循环,是一次调用 | 一次模型请求 + 一批工具 |
最外层短得离谱,但它承担了一件事:把异常吞掉并把状态复位。
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)
turn 本体:五处 append
轮次的骨架可以压成五行——每一行都是一个「持久化事件」(第 6 章会讲为什么这很重要):
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——后面几步正常完成也不能把它降级。
if (phase.step === 0 && decision.messages.length === 0) 时返回 false,
注释解释:消息被移除或决策改写为空,仍然拥有这一轮的起始边界,但不消耗一次模型调用。
turn-stopping 是 serial,不是 emitturnEnds && inbox.nextStep.length === 0 在 serial 前后各出现一次。
不是冗余:serial 是异步的,期间可能有新输入进来;第二次判断才是「真的没活了」。
agent.ts:320-430(turn 全貌)
preStep:插件树的入口
这是本章的核心。preStep 做五件事,然后把「进入这一步」的决定权交给插件链:
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 出口)
为什么 emit 要自己实现一遍
这是全篇最能看出「作者被坑过」的一处。dsh 没有直接用 Cordis 的 emit,而是自己写了一个循环:
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)
把一次提问压成一条链
wakeDriver()running)并 kick();如果正在跑,只记 wakeRequested。kick() → while (await this.turn())false 就停:被拒(blocked)、空决策(completed)、或正常完成。turn(): append('turn/start') → 内层 while(true)preStep 拿决策,再 append('step/start'),再 step(),finally 里 append('step/end')。preStep() 的五件事tools.resolve() → systemPrompt.assemble() → dispatch.waterfall('agent/pre-step')。enterreject 或换掉 messages。agent/turn-stopping(serial)→ 再看一眼收件箱break,有新活就 target = 'next-step' 继续。
一句话总结:turn 是一条由 append 标点、由 waterfall 决定走向、由 serial 决定停不停的链。
后面五章都是这条链上某个环节的放大。
为什么工具必须先是一个注册表
在 pi 里,工具是四个函数的返回值——createReadOnlyToolDefinitions() 这样的东西,
静态、可枚举。在 dsh 里,工具是运行时可增删的分层集合,而且注册本身就是一个插件行为。
两者都合理,但代价完全不同。先看 dsh 要解决什么:
| 真实场景 | 静态工具表做不到的地方 |
|---|---|
| 子 agent 有更少的工具 | 需要「按 scope 限制」,而不是复制一份新表 |
| 某个工具只在特定模型下可用 | 需要每步重新求值的准入条件,而不是加载时确定 |
| 插件热卸载 | 注册必须绑定到插件生命周期,卸载即撤销 |
| 部署方想禁掉某几个工具 | 限制必须能叠加(intersect),且不能改注册 |
这四条需求,正好对应 ToolsService 的四个机制:分层 / 准入 / effect 注册 / 限制。
index.ts:99-100(服务定义,inject = ['systemPrompt'])
view():遮蔽与限制是两件事
这是全章最容易读错的地方。view(scope) 返回一个 scope 能看到什么,它做了两轮处理,
语义完全不同:
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 跳过、留到第二轮单独处理——否则自己就会被自己覆盖掉。
get(name, scope) 的签名里 scope 不是可选项而是语义的一部分。
index.ts:199-226(view)· :239(get 带 scope)
注册就是一次 effect
register() 的返回值是一个 disposer,但它不是手写的清理函数——它来自 this.layers.effect(...):
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 被无条件保留effect 让注册与插件 fiber 同生共死tools/change 事件 → 提示词与 schema 重新计算。
一条 effect 串起了「生命周期 → 可见性 → 提示词」。
index.ts:128-153(register)
resolve():每步一份快照 + 身份栅栏
可见性是一回事,这一步实际能用哪些是另一回事。后者由 resolve() 在 preStep 里求值(第 1 章 1.5):
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 + 身份栅栏)
一次工具调用的六个阶段
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:
// 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)
执行器也是可换的
最后一个可插拔点:「怎么执行一批工具」本身是个服务。selectExecutor 按 scope 链就近查找:
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:已移除。改为挂载一个 native 或 PTC 工具执行器。z.never() 是一种「迁移 API」的写法:字段还在 schema 里,所以老配置文件会被读到并明确报错,
而不是被静默忽略。删字段会让用户拿到「配置没生效但不报错」这种最难查的 bug。
index.ts:357-366(selectExecutor)· :101-104(z.never 迁移)
四层过滤器,从粗到细
run_code 与同层重名直接抛错。allow / deny 在 scope 链上求交;只作用于继承来的,自己的注册豁免。ToolActivationError;结果是一份冻结快照 + dispose。deny 也从这里进。四层各有各的粒度:装 / 砍 / 本步可用 / 本次可执行。 在 pi 里这四件事被压成一件事(函数返回数组),代价是「按 scope 变化」和「热卸载」做不到; dsh 把代价明确摊开成四层,代价是读代码必须先看 scope。
seq 就是数组下标,永不重编号
append-only 日志的第一条铁律,dsh 用一行代码就实现了:
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]! 那行注释写得很诚实:
this.log 构造——按构造法 seq 永远是合法下标。那个非空断言就是在表达这条不变式。index.ts:817-835(append 分配 seq)· :1009-1010(seq 即下标)
surface 只是一串指向日志的下标
模型看到的「对话历史」不是日志本身,而是日志的一个视图。这个视图的数据结构简单到只有三个字段:
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 做什么 | 代际变化 |
|---|---|---|
append | nodes.push(seq) | 无 |
replace | nodes.splice(startIdx, count, newSeq) | replaceGeneration++ 且 contentGeneration++ |
project | 不动 nodes,改派生的消息副本 | 仅 contentGeneration++ |
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(三种折叠)
为什么需要两个代际
这是本章最精妙的一处。replaceGeneration 和 contentGeneration 几乎总是同步增长,
但有一个操作只动后者:project。
| 问题 | 该问哪个代际 | 为什么 |
|---|---|---|
| 「历史被裁剪过吗?」 | replaceGeneration |
压缩改变了范围,token 账要重算 |
| 「派生消息还能用吗?」 | contentGeneration |
只要内容变了缓存就失效,不管变的是范围还是内容 |
所以 deriveMessages() 的缓存看的是 contentGeneration——
它不关心「为什么变」,只关心「变没变」:
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 缓存)
replace 的边缘是「位置」,不是「序号大小」
这一节解释第 4 章那句让人困惑的话:「start 和 end 按 surface 位置命名,而不是数值 seq 顺序」。
原因就在这里——indexOf:
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(非单调警告)
replace 的四条校验
「能改历史」是危险能力。dsh 用四条校验把它的边界钉死,全部在追加之前完成:
| 校验 | 规则 | 防什么 |
|---|---|---|
| 引用必须更早 | sourceEventSeqs 里每个 seq 都 < event.seq |
不许引用未来事件(否则日志不可重放) |
| 不许重复 | duplicates → 抛错 |
同一事件不能被同一替换引用两次 |
| 必须覆盖全部被遮蔽节点 | missing → 抛错(列出缺哪些) |
不能「悄悄」删掉一个节点而不声明它被谁替代 |
| system prompt 特殊 | node 0 只能被 system/message 且长度恰为 1 的替换改写 |
系统提示不能被压缩顺手吃掉 |
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 特例)
这套设计的账单
公平地说代价。dsh 没有选 pi 那种「树 + 父指针 + 分支」,而选了「单链 + replace」, 换来了能力,也换了复杂度:
| 得到 | 付出 | 具体账单 |
|---|---|---|
| 改历史的唯一入口 | 每个消费者都要考虑非单调 | 「A 到 B 之间」必须按位置查,不能按数值遍历 |
| 缓存命中率高 | 两个代际要分清 | 用错代际 → 要么缓存过期不失效,要么白重建 |
| 日志永不可变 | 派生逻辑成了一条第四种路径 | append / replace / project / 投影未加载 → 四种分支(见下) |
seq 恒定可寻址 |
日志只增不减 | 磁盘增长靠上层切分,不靠日志自己回收 |
「第四种路径」指的是 planSurfaceEvent 里那个容易漏的分支——
日志里出现了当前没加载插件的消息类型时,直接抛错而不是静默跳过:
一句话总结第 3 章:dsh 的「历史」有两种形态——永不改的日志(按 seq 寻址)和可改的视图(按位置寻址); 两个代际就是这两者之间的汇率。
surface.ts:529-531(缺投影即抛错)
四个包,四个不同策略
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 的经济学」——先找免费的,再找便宜的,最后才花钱。
三层:协议 / 方言 / 桥
「兼容 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)
合并规则:最严格的赢
一个事件可能匹配多个 hook,它们的意见会冲突。dsh 用一套固定的优先级把冲突压平:
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 连接所有阻塞理由 |
用户需要看到所有拒绝原因,不是一个 |
merge.ts:35-43(rank)· :14-32(MergedHookOutcome)
翻译表: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 插件是否装了 |
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 桥)
PostToolUse 为什么写成那样
这是我见过最讲究的一段桥接代码——它先调 next() 再把自己的上下文折上去:
// 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 委托)
Stop hook 能「不许停」——以及它承认的缺环
Stop 是权限最大的一个:它可以让 agent 不许结束这一轮。
// 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 值得单独放大看,因为它是本次分析里唯一一处「代码自己承认的缺环」:
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)
两个方言的差异,被压缩成一个 boolean
协议层有一处细节,把「抽象到底该多细」这个问题回答得很干脆:
这是个真实存在的、无法回避的差异:某些 hook 脚本用 read 或 fgets 读 stdin,
没有换行就读不到最后一行。所以协议层把它变成 RunHookOptions.trailingNewline,
由方言层决定填什么。
| 差异 | 归属哪层 | 怎么表达 |
|---|---|---|
| 事件名 | 方言层 | CLAUDE_EVENTS 常量 |
| 配置格式 | 方言层 | config.ts 的解析器 |
| stdin 结尾换行 | 方言层 | trailingNewline: boolean |
| 默认超时 | 协议层 | DEFAULT_HOOK_TIMEOUT_MS = 600_000(10 分钟,两家一致) |
| 合并规则 | 协议层 | merge.ts(两家一致) |
runner.ts:14-20(默认超时)· :34(trailingNewline)
这一层的三个可复用结论
deny 就够否决全部 allow。ctx.shell),别自己造一句话:hooks 兼容层是 dsh「一切皆插件」最实用的证明——它没有把 Claude Code 的支持写进内核,而是写成了一层可卸载的适配器。 代价是:每个方言的差异都得有人显式写出来(比如那个换行)。
在追加点失败,而不是在落盘时
第 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(仍缺的护栏)
22ddee3