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

深入理解 dsh/第 01 章

1.1

先分清四种「派发」,不是一种

读 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(),调用它就继续往里走,不调用就截断整条链。

Around-middleware dispatch (Cordis `waterfall`). The declared event parameters already end with the `next` callback, so `rest` is exactly the event's arguments after the payload — the final element being the innermost `next` (the default the listener chain wraps).
环绕中间件式派发。事件参数本身就以 next 回调结尾,因此 rest 恰好是 payload 之后的全部参数——最后一个是最内层的 next,也就是监听链所包裹的那个默认行为。
— packages/core/agent/src/dispatch.ts:73-81

dispatch.ts:73-81(waterfall 契约)

1.2

入口:一个 Service,六个注入项

整个 agent 循环是一个 Cordis 服务。它能用到什么,写在 static inject 里—— 这是读 dsh 最省力的入手点,因为它等于一张依赖清单:

packages/core/agent-loop/src/index.ts:291-292
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 的服务生命周期约定,等价于「所有依赖都就绪之后再跑」。

packages/core/agent-loop/src/index.ts:330-340
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)

1.3

三层:kick → turn → step

dsh 的循环也是嵌套的,但分层方式和 pi 不一样:它把「驱动」和「轮次」和「步」分成三个不同职责。

层代码循环它管什么
L1 驱动 agent.ts:259 while (await this.turn()) {} 「还有没有下一轮」
L2 轮次 agent.ts:332 while (true) + break 这一轮里的若干 step
L3 步进 preStep() + step() 不是循环,是一次调用 一次模型请求 + 一批工具

最外层短得离谱,但它承担了一件事:把异常吞掉并把状态复位。

packages/core/agent-loop/src/agent.ts:262-275
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)

1.4

turn 本体:五处 append

轮次的骨架可以压成五行——每一行都是一个「持久化事件」(第 6 章会讲为什么这很重要):

packages/core/agent-loop/src/agent.ts:320-400(骨架)
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 is sticky: once any step hits the ceiling, later steps that complete normally must not downgrade the turn outcome. 一旦某步撞到输出上限,整轮就记 max-tokens——后面几步正常完成也不能把它降级。
② 空决策也要占住轮次边界
if (phase.step === 0 && decision.messages.length === 0) 时返回 false, 注释解释:消息被移除或决策改写为空,仍然拥有这一轮的起始边界,但不消耗一次模型调用。
③ turn-stopping 是 serial,不是 emit
因为它需要「按序询问,第一个说停就停」——这正是 serial 的语义。
④ 同一个条件判断了两次
turnEnds && inbox.nextStep.length === 0 在 serial 前后各出现一次。 不是冗余:serial 是异步的,期间可能有新输入进来;第二次判断才是「真的没活了」。

agent.ts:320-430(turn 全貌)

1.5

preStep:插件树的入口

这是本章的核心。preStep 做五件事,然后把「进入这一步」的决定权交给插件链:

packages/core/agent-loop/src/agent.ts:276-311
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 出口)

1.6

为什么 emit 要自己实现一遍

这是全篇最能看出「作者被坑过」的一处。dsh 没有直接用 Cordis 的 emit,而是自己写了一个循环:

packages/core/agent/src/dispatch.ts:120-140
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)

1.7

把一次提问压成一条链

① 输入进收件箱 → wakeDriver()
如果驱动是 idle,开一个新 phase(running)并 kick();如果正在跑,只记 wakeRequested。
② kick() → while (await this.turn())
turn 返回 false 就停:被拒(blocked)、空决策(completed)、或正常完成。
③ turn(): append('turn/start') → 内层 while(true)
每一圈 = 一个 step。先 preStep 拿决策,再 append('step/start'),再 step(),finally 里 append('step/end')。
④ preStep() 的五件事
领输入 → 取模型 → tools.resolve() → systemPrompt.assemble() → dispatch.waterfall('agent/pre-step')。
⑤ waterfall 的默认实现 = 拼上下文档 → enter
插件可以在这之前返回 reject 或换掉 messages。
⑥ 收尾:agent/turn-stopping(serial)→ 再看一眼收件箱
没新活就 break,有新活就 target = 'next-step' 继续。

一句话总结:turn 是一条由 append 标点、由 waterfall 决定走向、由 serial 决定停不停的链。 后面五章都是这条链上某个环节的放大。

本章学习记录

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