深入理解 dsh/第 01 章
先分清四种「派发」,不是一种
读 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 决定停不停的链。
后面五章都是这条链上某个环节的放大。