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

深入理解 dsh/第 05 章

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 的支持写进内核,而是写成了一层可卸载的适配器。 代价是:每个方言的差异都得有人显式写出来(比如那个换行)。

本章学习记录

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