好文集ChatGPT Plus¥119

敲下回车之后,DSH 是如何安全启动并维持单实例运转的?

文章目录

在上一篇(EP.01)中,我们顺着“先纵后横”的阅读路线,追踪了一条提示词如何从前端浏览器跨越本地进程边界,通过 Web RPC 定位到内存中的 ReactLoopAgent 实例,并叩响第一个公共入口 followup(input)

但在真实的运行环境中,Agent 的交互从来不是理想化的“你一句、我一句、等彻底结束了再发下一句”。只要把引擎放进并发与异步的真实工程场景里,立刻就会撞上三个极易引发状态错乱的核心边界问题:

文章配图

  1. 重复点火(并发重入):用户在前端连点两次发送,或者后台定时任务与用户输入在同一毫秒抵达,如果每次都直接启动一个新的推理循环,两个循环同时读写同一个 Session 上下文,状态瞬间就会撕裂;

  2. 忙碌期插队:引擎正在调工具、推理到一半,用户突然又发来一条纠偏指令(steer)或静默注入一段上下文(inject),此时该不该重新点火?

  3. 收尾间隙的竞态(最隐蔽的边界):用户刚点了“停止”按钮(旧任务正在取消收尾),或者后台正在跑上下文压缩(maintenance 维护态),就在旧任务即将彻底熄火的前一微秒,一条新消息敲门进来了——旧任务马上要停机,新任务又因为看到旧任务“还没彻底停稳”而退出了,谁来拉起这条新消息?


这一篇(EP.02),我们直接切入 packages/core/agent-loop/src/agent.ts,看 DSH 是如何通过 send() → wakeDriver() → kick() 三棒接力,用一套极度克制的三态状态机解决上述所有边界问题的。

第一棒 send():双队列分流、防御性改道与先落盘铁律

在 ReactLoopAgent 中,对外暴露的三个输入入口(followup、steer、inject)其实都是预设了不同路由参数的快捷别名,它们转身就把控制权交给了统一的路由中心 send():

文章配图

这段代码里藏着三个非常严谨的工程设计:

  • 双边界收件箱分流('next-turn' vs 'next-step'):收件箱(ReactLoopInbox)内部维护着两条有序队列。普通对话消息走 followup 进 'next-turn',等待当前完整回合结束后再开启新一轮对话;而运行中途的人工纠偏(steer)或系统注入(inject)进 'next-step',允许在当前回合的步骤(Step)边界中途插队生效。

  • 取消期防御性改道(wakingAfterAbort):设想一种极端情况——当前回合正处于被取消(aborted)的清理收尾阶段,此时刚好进来一条带 wakeup = true 的输入(例如 steer)。如果仍按原定计划放进 'next-step',正在退出的旧回合已经不会再跑下一步了,消息就会卡在错误的边界上。因此 send() 一旦检测到当前状态非 idle 且信号已中断,立刻强制将 resolvedTarget 改道至 'next-turn',并把 wakingAfterAbort = true 传递给下游。

  • 先持久化落盘,后点火唤醒:在调用 wakeDriver() 之前,this.inbox.splice() 会同步向 Session 追加一条不可变的 agent/inbox/spliced 事件并更新内存投影。这意味着 DSH 严格遵循 Event Sourcing 原则——任何计算还没开始之前,用户的意图就已经安全落盘了,哪怕下一毫秒进程崩溃,重启恢复时这条未消费的输入也不会丢失。

二、 第二棒 wakeDriver():四道关卡锁死单实例运行权

消息安全入库后,send() 拨动了引擎的点火继电器 wakeDriver()。它本身不执行任何推理循环,唯一的职责是作为单实例准入阀门,在四道关卡内安全地将状态机从 idle 翻转为 running:

// packages/core/agent-loop/src/agent.ts

private wakeDriver(wakeAfterAbort = false): void {
  // 关卡 1:实例生命周期检查
  if (this.lifetimeSignal.aborted) return

  // 关卡 2:状态互斥拦截与延迟唤醒标记(wakeRequested)
  if (this.phase.kind !== 'idle') {
    const reason = this.phase.abort.signal.reason as AgentCancelCause | undefined
    if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
      this.phase.wakeRequested = true
    }
    return
  }

  // 关卡 3:创建完工信号量,并同步抢占 'running' 状态
  const driver = Promise.withResolvers<void>()
  this.activityDone = driver.promise
  this.setPhase({
    kind: 'running',
    abort: new AbortController(),
    turn: this.phase.lastTurn,
    step: 0,
    wakeRequested: false,
  })

  // 关卡 4:绑定调用链归属身份,异步触发主循环
  this.loopCtx.agents.withInitiator(this, () => this.kick()).then(driver.resolve, driver.reject)
}

我们逐关拆解它的设计意图:

  1. 关卡 1(生命周期守卫):如果当前 Agent 实例已经触发全局销毁(lifetimeSignal.aborted),直接拒绝一切唤醒请求。

  2. 关卡 2(状态互斥 + wakeRequested 延迟唤醒标记):只要当前 this.phase.kind !== 'idle',就绝不允许启动第二个并行循环,直接 return 拦截。但拦截内部又细分为两种精妙分支:正常 running 中:直接退出。因为活着的 kick() 循环每跑完一个 Step 或 Turn,都会主动回头检查收件箱并认领新消息,无需重复打火。 maintenance 维护态或 wakeAfterAbort 取消收尾期:此时旧任务正在做清理收尾、即将熄火,新请求既不能自己点火(会冲突),又不能一走了之(会导致漏单)。于是它在当前阶段对象上记录 this.phase.wakeRequested = true(除非中断原因是永久销毁 disposed),留下一张“收工后请立即重启”的接力纸条后安心退出。

  3. 关卡 3(同步状态翻转与完成信号量):一旦确认处于 idle,立刻同步执行两件事:通过 ES2024 原生的 Promise.withResolvers<void>() 创建一对“承诺与钥匙”,把 driver.promise 挂到 this.activityDone 上,供外部调用 await agent.whenIdle() 时安静挂起等待(零轮询、零 CPU 占用),而把开锁钥匙 driver.resolve / driver.reject 留给主循环收尾; 调用 this.setPhase({ kind: 'running', ... }) 同步锁定运行权(后续任何微秒级并发请求都会立刻撞上关卡 2),为本轮分配独立的 AbortController 紧急刹车控制器、继承上一回合号 lastTurn 并将步数计数器 step 归零,同时对外发射 agent/status 事件——前端浏览器收到这个事件后,输入框右侧的“发送”按钮就会瞬间切换为“停止”按钮。

  4. 关卡 4(绑定调用链身份与异步启动):通过 Cordis 基于 AsyncLocalStorage 的 withInitiator(this, () => this.kick()),将当前 ReactLoopAgent 实例登记为整条异步执行链的发起者,使深层工具调用或派生子 Agent 随时能溯源当前归属。同时注意这里刻意没有写 await——主循环被丢进事件循环后台异步运转,wakeDriver() 同步返回,使得前端发消息的 Web RPC 接口能够毫秒级收到响应,而不必干等大模型生成结束。

第三棒 kick():主循环外壳与收尾接力闭环

被 wakeDriver() 在后台异步拉起的 this.kick(),构成了整个推理引擎最外层的循环外壳:

// packages/core/agent-loop/src/agent.ts

private async kick(): Promise<void> {
  try {
    // 只要 turn() 返回 true(说明收件箱里仍有待处理消息),就一轮接一轮地跑下去
    while (await this.turn()) {}
  } catch (_error) {
    // 兜底捕获未处理异常,确保单次循环异常不会击穿宿主 Node.js 进程
  } finally {
    if (this.phase.kind === 'running') {
      const { turn, wakeRequested } = this.phase
      // 1. 队列彻底清空:切回 'idle',记录最新回合号(前端“停止”按钮恢复为“发送”)
      this.setPhase({ kind: 'idle', lastTurn: turn })
      // 2. 兑现预约接力:若收尾期间有人打过 wakeRequested 标记且队列非空,立即重新点火
      if (wakeRequested && this.inbox.hasPending) this.wakeDriver()
    }
  }
}

看到 finally 块里的最后两行,前面 wakeDriver() 关卡 2 埋下的伏笔就彻底闭环了:

当收件箱所有消息都被消费完毕、turn() 返回 false 退出 while 循环后,程序必然进入 finally 块。它在把状态重置回 idle(并广播 agent/status 让前端恢复发送按钮)的同一瞬间,检查阶段对象上的 wakeRequested 标记——如果在刚才取消收尾的间隙恰好有新消息留过“接力纸条”,就由当前即将退出的旧循环在切回 idle 后亲手再拨动一次 this.wakeDriver(),无缝拉起新一轮运行,彻底消灭并发边界上的漏单假死。

紧接着,当 kick() 彻底返回结算时,挂在外部的 .then(driver.resolve, driver.reject) 自动触发,拨动 this.activityDone 信号灯,唤醒所有正在 await agent.whenIdle() 处等待的调用方。


下期预告(EP.03)

至此,DSH 引擎已经完成了从 idle 到 running 的安全点火,并稳定维持着单实例主循环的运转。

在下一期(EP.03)中,我们将正式钻进 while (await this.turn()) {} 的内部,拆解单个回合(Turn)与步骤(Step)的运转主干:看 turn() 如何开启持久化回合日志 turn/start,以及 preStep() 如何从收件箱中原子认领(Claim)我们的提示词、组装系统提示词(System Prompt)与可用工具列表,并走过插件拦截瀑布流。

全文完
查看原文

沿着这个主题继续读

从一篇文章,找到相关的教程、经验和阅读路径。

DeepSeek 与国产大模型DeepSeek、豆包、Kimi、Qwen、MiniMax 等国产大模型的实测、Agent 用法与本地部署。