手册/第 05 章
五个机制:dsh 真正跑起来靠什么
前四章建立了「插件树 + turn 契约」。这一章拆开五个反复出现的机制——
你在 dsh 源码里见到的绝大多数 ctx.xxx 调用,都属于其中之一。
机制一:事件域决定「该用什么方式改」
三个域的边界不是按「模块」划的,是按事实的性质划的(architecture.md:71–73):
session/event 广播。判断标准只有一条:
这件事必须活过一次重启吗?是 → Session 事件。
agent/* 携带一个活着的 Agent:inbox、step、status、request、validation、
continuation。要观察或拦截在飞的工作,用它。
fs/*、tools/*、telemetry/*。
能在不 import 循环的前提下挂上策略或适配器。
机制二:waterfall 是「可被包裹的决策」
dsh 里有 4 组事件是 waterfall,全部集中在「请求发出前」这条线上
(architecture.md:106):agent/pre-step、
agent/request、llm/stream、以及三个 tools/*。
与之相对,agent/turn-stopping 是 serial 且无 next()。
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), { ...exec.agent ? { agent: exec.agent } : {}, turn, 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() })
这段不是教学示例,是仓库里 hooks-claude-code 插件的真实代码——它把 Claude Code 的
PreToolUse hook 映射到 dsh 的 waterfall 上。三种出口正好展示了 waterfall 的全部用法:
deny(短路拒绝)、ask(短路转人工)、next()(委托给下游,让后面的监听者
仍能 block 或替换)。它在注释里把这条规矩写明了:"Our hooks did not block. DELEGATE so a later
listener can still block/replace."
Cordis 的明确规定是:协作型监听者改共享对象再委托;拥有决策的监听者直接返回;只做标注的必须委托。
(docs/cordis-primer.md:33–35)这条规则如果违反,表现是「后面的插件静默失效」——
很难查,所以写插件时值得刻意检查。
机制三:seam 必须三角齐全
| seam | 定义在哪 | 换掉它会发生什么 |
|---|---|---|
ctx.llm | llm/src/index.ts:208(abstract class LlmAdapter)、:401(registerAdapter) | 换模型厂商,循环一行不改 |
ctx.tools | core/tools/src/index.ts:99(ToolsService) | 换工具注册表与执行调度 |
ctx.sessions | core/session/src/index.ts:525(Session)、:1064(SessionStore) | 换会话存储后端(含格式代际) |
ctx.fs | fs/fs/src/index.ts:87(abstract class FileSystem) | 文件访问指向别处(本地 / 远端沙箱) |
ctx.subprocess | subprocess/subprocess/src/index.ts:117(abstract class SubprocessRuntime) | 进程也在同一个新世界里跑 |
ctx.sandbox | sandbox/sandbox-policy/src/index.ts:134(SandboxPolicyService) | 换成另一套限制/审批策略 |
机制四:工具管线拿的是「原始批次」
一个容易忽略的设计:ctx.tools.execute() 接收的是原始批次与并发上限
(architecture.md:120),不是单次调用。意味着调度(并行几个、失败怎么收)属于 seam,
而不是散在循环里。
pre-execute 管准入(能不能跑);execute 管执行;
post-execute 管结果(要不要改写/审计)。三者都是 waterfall。
architecture.md:116),
所以模型下一轮看到的历史是完整可读的,而不是缺一条 toolResult。
机制五:执行世界是共享的
这条是 dsh 最容易被低估的设计。fs 与 subprocess 的 provider
共享同一个执行世界(architecture.md:138):
这就是为什么架构图里 sandbox / fs / subprocess 被画成一个合并节点: 它们不是三个可独立替换的能力,而是同一个「你在这里干活」的世界的三个面。
architecture.md:110)。而 AgentLoop 的 inbox 是持久投影,
所以没有活着的 Agent 时,也能看出还有哪些输入在排队。
architecture.md:106 · waterfall 清单 architecture.md:136 · seam 三角色 tools/src/pipeline.ts:200 · pre-execute