逐日AI微信小程序
30 天从前端工程师到 Agent 工程师
第 2 周 · D11🔒 锁定约 6 小时

run 状态机、输出流回传、按 runId 保序、SSE 等待者、30s 打断合并

给每次对话执行建一个 run 状态机,把 worker 产生的流式输出按 runId 保序回传给等待中的 SSE 连接,并处理 30 秒内的打断合并。

今日目标 0/3

登录后可以勾选并保存进度。

今日目标

  1. 能画出一个 run 从创建到完成的完整状态机(含失败、打断状态)
  2. 能实现按 runId 把 worker 的流式输出保序回传给等待中的 SSE 客户端
  3. 能实现 30 秒内的用户打断合并成同一次输入,而不是开两个 run

D10 把执行侧的顺序保住了,但用户那边还是「发出去就没声了」。今天把输出接回去,这条链路才算通。读完回来把上面三条勾掉。

小白版讲解

先把今天和 D7 的分界画清楚,因为整章都立在这条线上。D7 是同一个进程既生成又推送:模型吐一个字,同一个函数栈里立刻 res.write 一帧,生成和推送之间没有任何缝隙,所以那时候「顺序」根本不是问题——它天然就是对的。今天生成在 Worker、推送在 Gateway,中间隔着一条消息总线:字在一个进程里产生,连接挂在另一个进程上,中间那条总线不承诺你什么时候拿到、以什么顺序拿到。SSE 的服务端写法 D7 已经讲透了(四个响应头、: ping 心跳、连接断开处理),今天一行都不重讲,全部精力用在这条缝隙带来的四个新问题上:状态、顺序、多个订阅者、重连。

一次执行得有个身份:run 状态机

电台做一期节目:策划立项、进棚录制、开始播出、播完归档。任何时刻问「这期节目现在到哪一步了」,都有一个明确答案,而且这些步骤是单向的——播完了不可能退回去变成「正在录制」。

单进程时代你不需要这个东西。D7 那个 POST /chat 里,「执行到哪一步了」就是那个函数栈本身:函数在跑就是在跑,函数返回了就是结束了,函数抛异常了就是失败了。这份状态存在于进程内存里,没有名字,也不需要名字。

拆开之后它必须有名字,因为至少有三方要同时回答同一个问题:Gateway 要知道「这次执行还活着吗」才能决定挂不挂 SSE;Worker 要知道「这条消息是不是已经有人在做了」才能决定要不要执行;用户重新打开页面时,前端要知道「上一次问的问题还在生成吗」。三方不在同一个进程里,只能靠一张表对齐。这就是 D8 定的 runs 表,和它的六个状态:

TextText
       ┌──────────────────────────── 正常路径 ────────────────────────────┐
       │                                                                 │
  ┌─────────┐   投递被消费   ┌─────────┐  第一个片段  ┌───────────┐        ▼
  │ pending │ ────────────→ │ running │ ──────────→ │ streaming │ ───→ ┌──────┐
  └─────────┘               └─────────┘             └───────────┘      │ done │
       │                         │                        │            └──────┘
       │                         ▼                        ▼
       │                    ┌────────┐              ┌────────┐
       └──────────────────→ │ failed │              │ failed │   重试耗尽
                            └────────┘              └────────┘
       │                         │                        │
       └──────────────────→ ┌───────────┐ ←──────────────-─┘
                            │ cancelled │   被打断合并或用户取消
                            └───────────┘

四个正常状态一路向前,两个异常出口随时可以走:failed 是重试耗尽,cancelled 是被打断合并或用户主动取消。running 和 streaming 要分开,是因为它们对用户的含义完全不同:running 是「已经有 Worker 领走了,但还没有一个字」,streaming 是「第一个字已经出来了」。这条分界线就是首字延迟(time-to-first-token)的观测点,也是前端决定「继续转圈」还是「开始打字机效果」的依据。

状态机的价值不在于把这几个词列出来,而在于把不合法的转换写进代码里挡住:

state.js
// 转换表,不是一串 if:它能被读、能被测,也能直接贴进设计文档
const TRANSITIONS = {
  pending: ['running', 'cancelled', 'failed'],
  running: ['streaming', 'done', 'failed', 'cancelled'],
  streaming: ['done', 'failed', 'cancelled'],
  done: [], // 终态没有出边,这是整张表最值钱的一行
  failed: [],
  cancelled: [],
}
 
function transition(from, to) {
  if (!TRANSITIONS[from].includes(to)) {
    throw new Error(`非法状态转换:${from} → ${to}`)
  }
  return to
}

那句 throw 换来的是一类事故被挡在写入那一刻。分布式系统里「一个已经 done 的 run 又收到一个片段」是常态而不是意外——总线至少投递一次(D9),网络抖一下就会重放一条旧消息,慢半拍的 Worker 也可能在收尾之后又醒过来写一笔。没有这张表,那一笔会安静地写进库里,用户看到回复末尾莫名多出半句话,你查半天日志找不出是谁写的;有这张表,它当场抛错、当场进日志。

状态机真正的产出不是那几个词,是一条「凡是写状态都必须过这个函数」的纪律。 绕过它写一次 UPDATE runs SET status = 'done',这张表就退化成注释了。

那么第二个问题来了:Worker 在自己的进程里一个字一个字地生成,这些字要怎么按顺序回到 Gateway 上那条还挂着的连接?

登录并关联后阅读全文

请先登录网页,并在账户页关联微信小程序账号。关联后每天可免费阅读 1 篇;额外文章需在小程序看广告解锁。

小程序码

微信扫码打开「逐日AI」,进入相同课程和章节,选择看广告解锁,完成后刷新本页。

面试题库

  • 怎么设计一次 Agent 执行(run)的状态机?需要覆盖哪些异常状态?How would you design the state machine for one agent run, and which failure states must it cover?
    国内高频海外高频基础#state-machine#distributed-systems

    🔒 解锁本章后查看答题要点。

  • 多个客户端同时订阅同一次执行的流式输出,怎么保证每个客户端都收到完整且有序的内容?Several clients subscribe to the same run's streaming output at once. How do you guarantee each of them receives the full content in order?
    国内高频海外高频进阶#sse#ordering#fan-out

    🔒 解锁本章后查看答题要点。

  • 用户在 Agent 还没回复完的时候又发来一条消息,应该怎么处理?A user sends another message while the agent is still answering the previous one. How should the system handle it?
    国内高频海外高频进阶#interrupt-merge#state-machine#cost

    🔒 解锁本章后查看答题要点。

  • 流式接口的客户端断线重连后,怎么做到既不丢片段也不重复?After a streaming client reconnects, how do you deliver every missed chunk exactly once — no gaps, no duplicates?
    国内高频海外高频深入#sse#idempotency#reconnect

    🔒 解锁本章后查看答题要点。

评论