OpenClaw Studio 流式可靠性原理Outbox 模式 SSE 重放如何实现事件零丢失【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studioOpenClaw Studio 是一个干净的 OpenClaw Web 控制台dashboard负责连接 Gateway、管理 Agents 并加速交付。它的实时聊天流之所以稳定靠的正是Outbox 模式 SSE 重放这套事件零丢失机制所有事件先落库拿到单调递增编号再按编号回放给浏览器断线重连时从上次读到的编号继续投递不丢一条。实时流最大的难题事件为什么会丢在 Web 端做实时流streaming应用时丢事件通常来自三个场景断线重连网络抖动、服务重启浏览器重新订阅时中间那几条事件去哪了重放与实时事件交叠一边回放历史、一边又进来新事件容易出现缝隙漏条或重复投递多份。历史与实时衔接先加载历史窗口再接实时流两边边界没对齐就会跳变。OpenClaw Studio 的官方流式文档 docs/pi-chat-streaming.md 明确回答了这三点带Last-Event-ID重连则从该 id 向前重放全新连接则重放 outbox 头部的最近窗口重放与实时订阅显式排序避免缝隙和重复的终态副作用。总体架构服务器独占连接浏览器只读订阅整个控制平面control plane的边界非常清晰浏览器只访问领域 API/api/runtime/*、/api/intents/*和一条 SSE 流Studio 服务器是上游 OpenClaw Gateway WebSocket 的唯一持有者浏览器从不直连网关。浏览器 --(SSE /api/runtime/stream)-- Studio 服务器 --(WebSocket)-- OpenClaw Gateway这个设计本身就把浏览器直连断线丢事件的可能性砍掉了一半——连接的生命周期、重连退避都由服务器掌控。网关适配器使用指数退避1s 起、1.7 倍递增、封顶 15s自动重连见 src/lib/controlplane/openclaw-adapter.ts并为每次连接生成connectionEpoch以区分不同连接世代的事件。第一支柱Outbox 模式——每个事件先落库、拿编号所谓Outbox 模式事件不即发即忘而是先写入一张带自增主键的outbox表拿到全局单调递增的id之后才对外投递。核心实现在 src/lib/controlplane/projection-store.tsoutbox表用INTEGER PRIMARY KEY AUTOINCREMENT分配 id建表语句SQLite WAL 模式保证写入可靠每张事件票都有唯一event key由事件类型、seq、connectionEpoch、时间戳等推导见 src/lib/controlplane/outbox.ts存入processed_events表重复事件命中已存在的 key 时直接返回原 outbox 行、不再插入——这就是去重靠编号、幂等靠 key。每个网关事件进入时的完整链路src/lib/controlplane/runtime.ts网关帧 → 领域事件gateway.event/runtime.statusapplyDomainEvent()单事务落库去重 → 写投影 → 插 outbox 行返回带id的 entry同步通知所有 SSE 订阅者从此事件发生过这件事就有了持久化事实依据而不仅仅是一条内存推送。第二支柱SSE 重放——断线后从编号继续投递SSEServer-Sent Events天然支持Last-Event-ID浏览器每次收到事件帧会记住id:重连时自动带回。Studio 的流端点 src/app/api/runtime/stream/route.ts 在此基础上做了三件事双通道取编号同时解析Last-Event-ID请求头和lastEventId查询参数parseLastEventIdFromRequest兼容标准 EventSource 和自定义重连。两种重放策略启动逻辑带编号重连 → 从lastSeenId重放到 outbox 头部每批上限 2000 条全新连接 → 重放最近 2000 条尾部窗口保证首屏就有上下文。startup 缓冲消除缝隙重放期间新到的实时事件先进startupLiveBuffer重放结束后按 id 排序补发emitEntry跳过所有id lastDeliveredId的条目src/app/api/runtime/stream/route.ts。重放、实时、历史三条路径共用同一编号空间缝隙靠排序消除重复靠只投递更大 id消除。另外每 15 秒发一帧: heartbeat注释帧防止中间代理掐断空闲长连接。浏览器侧把读到哪了写进断点服务端再可靠也要客户端如实汇报进度。浏览器端 src/features/agents/state/useRuntimeEventStream.ts 的策略是双保险每收到一条事件就解析lastEventId只接受单调递增的编号并写入sessionStorageopenclaw.runtime.lastEventId:前缀重连时把断点拼进?lastEventId即便 EventSource 自带的头没生效服务端也能续上。这样刷新页面 / 短暂断网 / 切换 Agent后流都是从精确断点恢复而不是从头再来。历史回填与实时流走同一条管线打开会话时历史消息由 src/app/api/runtime/agents/[agentId]/history/route.ts 提供支持limit/beforeOutboxId游标分页返回hasMore等续读元数据。关键细节是浏览器把历史条目通过和实时流完全相同的事件管线处理并按 outbox id 去重。也就是说历史和实时不存在两套渲染逻辑编号空间统一天然无缝拼接。网关不可用时的优雅降级即使上游彻底断连这套机制也有兜底见 docs/pi-chat-streaming.md 的 Freshness 一节所有运行时读操作都会附带新鲜度元数据freshnessUI 能明确知道这是快照还是实时基于 outbox 投影的数据仍可渲染写操作则快速失败并返回确定性的GATEWAY_UNAVAILABLE错误而不是无限挂起。小结四步看懂零丢失编号事件先写 outbox拿自增 id持久化事实去重event key 保证同一事件只入库一次幂等重放SSE 按Last-Event-ID续投新连接补最近窗口startup 缓冲保证重放/实时无缝无重断点浏览器持久化 lastEventId历史与实时共用一条去重管线。对使用者而言这些机制是透明的你只会看到 Agent 的回复稳定地流式出现、刷新后上下文不丢。如果你想动手验证或二次开发建议按顺序阅读 src/lib/controlplane/outbox.ts、src/lib/controlplane/projection-store.ts 和 src/app/api/runtime/stream/route.ts 这三个文件即可完整还原整条可靠性链路。【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw Studio 流式可靠性原理：Outbox 模式 + SSE 重放如何实现事件零丢失
OpenClaw Studio 流式可靠性原理Outbox 模式 SSE 重放如何实现事件零丢失【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studioOpenClaw Studio 是一个干净的 OpenClaw Web 控制台dashboard负责连接 Gateway、管理 Agents 并加速交付。它的实时聊天流之所以稳定靠的正是Outbox 模式 SSE 重放这套事件零丢失机制所有事件先落库拿到单调递增编号再按编号回放给浏览器断线重连时从上次读到的编号继续投递不丢一条。实时流最大的难题事件为什么会丢在 Web 端做实时流streaming应用时丢事件通常来自三个场景断线重连网络抖动、服务重启浏览器重新订阅时中间那几条事件去哪了重放与实时事件交叠一边回放历史、一边又进来新事件容易出现缝隙漏条或重复投递多份。历史与实时衔接先加载历史窗口再接实时流两边边界没对齐就会跳变。OpenClaw Studio 的官方流式文档 docs/pi-chat-streaming.md 明确回答了这三点带Last-Event-ID重连则从该 id 向前重放全新连接则重放 outbox 头部的最近窗口重放与实时订阅显式排序避免缝隙和重复的终态副作用。总体架构服务器独占连接浏览器只读订阅整个控制平面control plane的边界非常清晰浏览器只访问领域 API/api/runtime/*、/api/intents/*和一条 SSE 流Studio 服务器是上游 OpenClaw Gateway WebSocket 的唯一持有者浏览器从不直连网关。浏览器 --(SSE /api/runtime/stream)-- Studio 服务器 --(WebSocket)-- OpenClaw Gateway这个设计本身就把浏览器直连断线丢事件的可能性砍掉了一半——连接的生命周期、重连退避都由服务器掌控。网关适配器使用指数退避1s 起、1.7 倍递增、封顶 15s自动重连见 src/lib/controlplane/openclaw-adapter.ts并为每次连接生成connectionEpoch以区分不同连接世代的事件。第一支柱Outbox 模式——每个事件先落库、拿编号所谓Outbox 模式事件不即发即忘而是先写入一张带自增主键的outbox表拿到全局单调递增的id之后才对外投递。核心实现在 src/lib/controlplane/projection-store.tsoutbox表用INTEGER PRIMARY KEY AUTOINCREMENT分配 id建表语句SQLite WAL 模式保证写入可靠每张事件票都有唯一event key由事件类型、seq、connectionEpoch、时间戳等推导见 src/lib/controlplane/outbox.ts存入processed_events表重复事件命中已存在的 key 时直接返回原 outbox 行、不再插入——这就是去重靠编号、幂等靠 key。每个网关事件进入时的完整链路src/lib/controlplane/runtime.ts网关帧 → 领域事件gateway.event/runtime.statusapplyDomainEvent()单事务落库去重 → 写投影 → 插 outbox 行返回带id的 entry同步通知所有 SSE 订阅者从此事件发生过这件事就有了持久化事实依据而不仅仅是一条内存推送。第二支柱SSE 重放——断线后从编号继续投递SSEServer-Sent Events天然支持Last-Event-ID浏览器每次收到事件帧会记住id:重连时自动带回。Studio 的流端点 src/app/api/runtime/stream/route.ts 在此基础上做了三件事双通道取编号同时解析Last-Event-ID请求头和lastEventId查询参数parseLastEventIdFromRequest兼容标准 EventSource 和自定义重连。两种重放策略启动逻辑带编号重连 → 从lastSeenId重放到 outbox 头部每批上限 2000 条全新连接 → 重放最近 2000 条尾部窗口保证首屏就有上下文。startup 缓冲消除缝隙重放期间新到的实时事件先进startupLiveBuffer重放结束后按 id 排序补发emitEntry跳过所有id lastDeliveredId的条目src/app/api/runtime/stream/route.ts。重放、实时、历史三条路径共用同一编号空间缝隙靠排序消除重复靠只投递更大 id消除。另外每 15 秒发一帧: heartbeat注释帧防止中间代理掐断空闲长连接。浏览器侧把读到哪了写进断点服务端再可靠也要客户端如实汇报进度。浏览器端 src/features/agents/state/useRuntimeEventStream.ts 的策略是双保险每收到一条事件就解析lastEventId只接受单调递增的编号并写入sessionStorageopenclaw.runtime.lastEventId:前缀重连时把断点拼进?lastEventId即便 EventSource 自带的头没生效服务端也能续上。这样刷新页面 / 短暂断网 / 切换 Agent后流都是从精确断点恢复而不是从头再来。历史回填与实时流走同一条管线打开会话时历史消息由 src/app/api/runtime/agents/[agentId]/history/route.ts 提供支持limit/beforeOutboxId游标分页返回hasMore等续读元数据。关键细节是浏览器把历史条目通过和实时流完全相同的事件管线处理并按 outbox id 去重。也就是说历史和实时不存在两套渲染逻辑编号空间统一天然无缝拼接。网关不可用时的优雅降级即使上游彻底断连这套机制也有兜底见 docs/pi-chat-streaming.md 的 Freshness 一节所有运行时读操作都会附带新鲜度元数据freshnessUI 能明确知道这是快照还是实时基于 outbox 投影的数据仍可渲染写操作则快速失败并返回确定性的GATEWAY_UNAVAILABLE错误而不是无限挂起。小结四步看懂零丢失编号事件先写 outbox拿自增 id持久化事实去重event key 保证同一事件只入库一次幂等重放SSE 按Last-Event-ID续投新连接补最近窗口startup 缓冲保证重放/实时无缝无重断点浏览器持久化 lastEventId历史与实时共用一条去重管线。对使用者而言这些机制是透明的你只会看到 Agent 的回复稳定地流式出现、刷新后上下文不丢。如果你想动手验证或二次开发建议按顺序阅读 src/lib/controlplane/outbox.ts、src/lib/controlplane/projection-store.ts 和 src/app/api/runtime/stream/route.ts 这三个文件即可完整还原整条可靠性链路。【免费下载链接】openclaw-studioA clean web dashboard for OpenClaw. Connect your Gateway, manage agents, and ship faster. ⭐️ Star if you like it!项目地址: https://gitcode.com/gh_mirrors/op/openclaw-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考