run 状态机、输出流回传、按 runId 保序、SSE 等待者、30s 打断合并
给每次对话执行建一个 run 状态机,把 worker 产生的流式输出按 runId 保序回传给等待中的 SSE 连接,并处理 30 秒内的打断合并。
今日目标
- 能画出一个 run 从创建到完成的完整状态机(含失败、打断状态)
- 能实现按 runId 把 worker 的流式输出保序回传给等待中的 SSE 客户端
- 能实现 30 秒内的用户打断合并成同一次输入,而不是开两个 run
D10 把执行侧的顺序保住了,但用户那边还是「发出去就没声了」。今天把输出接回去,这条链路才算通。读完回来把上面三条勾掉。
小白版讲解
先把今天和 D7 的分界画清楚,因为整章都立在这条线上。D7 是同一个进程既生成又推送:模型吐一个字,同一个函数栈里立刻 res.write 一帧,生成和推送之间没有任何缝隙,所以那时候「顺序」根本不是问题——它天然就是对的。今天生成在 Worker、推送在 Gateway,中间隔着一条消息总线:字在一个进程里产生,连接挂在另一个进程上,中间那条总线不承诺你什么时候拿到、以什么顺序拿到。SSE 的服务端写法 D7 已经讲透了(四个响应头、: ping 心跳、连接断开处理),今天一行都不重讲,全部精力用在这条缝隙带来的四个新问题上:状态、顺序、多个订阅者、重连。
一次执行得有个身份:run 状态机
电台做一期节目:策划立项、进棚录制、开始播出、播完归档。任何时刻问「这期节目现在到哪一步了」,都有一个明确答案,而且这些步骤是单向的——播完了不可能退回去变成「正在录制」。
单进程时代你不需要这个东西。D7 那个 POST /chat 里,「执行到哪一步了」就是那个函数栈本身:函数在跑就是在跑,函数返回了就是结束了,函数抛异常了就是失败了。这份状态存在于进程内存里,没有名字,也不需要名字。
拆开之后它必须有名字,因为至少有三方要同时回答同一个问题:Gateway 要知道「这次执行还活着吗」才能决定挂不挂 SSE;Worker 要知道「这条消息是不是已经有人在做了」才能决定要不要执行;用户重新打开页面时,前端要知道「上一次问的问题还在生成吗」。三方不在同一个进程里,只能靠一张表对齐。这就是 D8 定的 runs 表,和它的六个状态:
┌──────────────────────────── 正常路径 ────────────────────────────┐
│ │
┌─────────┐ 投递被消费 ┌─────────┐ 第一个片段 ┌───────────┐ ▼
│ pending │ ────────────→ │ running │ ──────────→ │ streaming │ ───→ ┌──────┐
└─────────┘ └─────────┘ └───────────┘ │ done │
│ │ │ └──────┘
│ ▼ ▼
│ ┌────────┐ ┌────────┐
└──────────────────→ │ failed │ │ failed │ 重试耗尽
└────────┘ └────────┘
│ │ │
└──────────────────→ ┌───────────┐ ←──────────────-─┘
│ cancelled │ 被打断合并或用户取消
└───────────┘四个正常状态一路向前,两个异常出口随时可以走:failed 是重试耗尽,cancelled 是被打断合并或用户主动取消。running 和 streaming 要分开,是因为它们对用户的含义完全不同:running 是「已经有 Worker 领走了,但还没有一个字」,streaming 是「第一个字已经出来了」。这条分界线就是首字延迟(time-to-first-token)的观测点,也是前端决定「继续转圈」还是「开始打字机效果」的依据。
状态机的价值不在于把这几个词列出来,而在于把不合法的转换写进代码里挡住:
// 转换表,不是一串 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
}from enum import StrEnum
class RunStatus(StrEnum):
PENDING = "pending"
RUNNING = "running"
STREAMING = "streaming"
DONE = "done"
FAILED = "failed"
CANCELLED = "cancelled"
# frozenset 表达「这是一张不会被改的表」,比 list 更贴合语义
TRANSITIONS: dict[RunStatus, frozenset[RunStatus]] = {
RunStatus.PENDING: frozenset({RunStatus.RUNNING, RunStatus.CANCELLED, RunStatus.FAILED}),
RunStatus.RUNNING: frozenset({RunStatus.STREAMING, RunStatus.DONE, RunStatus.FAILED, RunStatus.CANCELLED}),
RunStatus.STREAMING: frozenset({RunStatus.DONE, RunStatus.FAILED, RunStatus.CANCELLED}),
RunStatus.DONE: frozenset(),
RunStatus.FAILED: frozenset(),
RunStatus.CANCELLED: frozenset(),
}
def transition(current: RunStatus, target: RunStatus) -> RunStatus:
if target not in TRANSITIONS[current]:
raise ValueError(f"非法状态转换:{current} → {target}")
return target// Java 里状态机的地道写法是把出边挂在枚举自己身上,用 EnumSet 存——
// 位图实现,查一次是常数时间,而且忘了给新状态配出边编译期就能发现
enum RunStatus {
PENDING, RUNNING, STREAMING, DONE, FAILED, CANCELLED;
Set<RunStatus> allowedNext() {
return switch (this) {
case PENDING -> EnumSet.of(RUNNING, CANCELLED, FAILED);
case RUNNING -> EnumSet.of(STREAMING, DONE, FAILED, CANCELLED);
case STREAMING -> EnumSet.of(DONE, FAILED, CANCELLED);
case DONE, FAILED, CANCELLED -> EnumSet.noneOf(RunStatus.class);
};
}
RunStatus to(RunStatus target) {
if (!allowedNext().contains(target)) {
throw new IllegalStateException("非法状态转换:" + this + " → " + target);
}
return target;
}
}// Swift 用穷尽 switch:以后往枚举里加一个状态,这个 switch 编译不过,
// 编译器会逼你回来补出边——四门语言里它对「漏写一个状态」的防护最强
// 出边表与 D8 那份完全一致(含 pending → failed)。区别只在方法:
// D8 给的是 canTransition(to:) -> Bool,今天升级成 transition(to:) throws——
// 状态机要真的挡住非法迁移,返回 Bool 太容易被调用方忽略掉
enum RunStatus: String, Codable {
case pending, running, streaming, done, failed, cancelled
var allowedNext: Set<RunStatus> {
switch self {
case .pending: [.running, .cancelled, .failed]
case .running: [.streaming, .done, .failed, .cancelled]
case .streaming: [.done, .failed, .cancelled]
case .done, .failed, .cancelled: []
}
}
func transition(to target: RunStatus) throws -> RunStatus {
guard allowedNext.contains(target) else {
throw RunError.illegalTransition(from: self, to: target)
}
return target
}
}那句 throw 换来的是一类事故被挡在写入那一刻。分布式系统里「一个已经 done 的 run 又收到一个片段」是常态而不是意外——总线至少投递一次(D9),网络抖一下就会重放一条旧消息,慢半拍的 Worker 也可能在收尾之后又醒过来写一笔。没有这张表,那一笔会安静地写进库里,用户看到回复末尾莫名多出半句话,你查半天日志找不出是谁写的;有这张表,它当场抛错、当场进日志。
状态机真正的产出不是那几个词,是一条「凡是写状态都必须过这个函数」的纪律。 绕过它写一次 UPDATE runs SET status = 'done',这张表就退化成注释了。
那么第二个问题来了:Worker 在自己的进程里一个字一个字地生成,这些字要怎么按顺序回到 Gateway 上那条还挂着的连接?
面试题库
怎么设计一次 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🔒 解锁本章后查看答题要点。
