深入理解 dsh/第 05 章
三层:协议 / 方言 / 桥
「兼容 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 的支持写进内核,而是写成了一层可卸载的适配器。 代价是:每个方言的差异都得有人显式写出来(比如那个换行)。