Genarrative/docs/technical/RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md

Rust api-server SSE 基础设施设计（2026-04-22）

日期：2026-04-22

1. 文档目的

这份文档用于冻结 server-rs/crates/api-server 内部的 SSE 基础设施抽取口径。

本轮目标只有两个：

1. 把当前散落在业务 handler 中的 text/event-stream 响应头与事件文本编码逻辑，收口为 api-server 可复用的 Rust 基础设施。
2. 在同一基础设施上补出“实时写事件”的 writer 版本，为后续真流式接口预留稳定入口。

本轮不做：

1. 不改前端消费协议
2. 不把 custom world message stream 当场改成真实逐段 token streaming
3. 不引入跨 crate 的共享 shared-contracts SSE runtime helper
4. 不同时重构 story / runtime / txt mode 的未来流式接口

2. 当前问题

当前 Rust 侧 SSE 能力只在一个地方手写：

1. server-rs/crates/api-server/src/custom_world.rs

当前实现存在以下问题：

1. append_sse_event(...) 与 build_event_stream_response(...) 直接写在业务文件里
2. SSE 响应头、事件编码规则没有统一入口
3. 后续如果再新增第二条 Rust SSE 路由，极容易复制一份近似实现
4. 业务层和传输层耦合在一起，不利于测试

3. 抽取边界

本轮只抽以下基础能力：

1. 标准 SSE 响应头构造
2. 单条事件编码
3. 缓冲式 SSE body builder
4. 实时写事件的 SSE writer
5. 一次性返回完整 SSE 文本的响应构造
6. 基于流 body 的实时 SSE 响应构造

本轮明确不抽：

1. reply_delta / session / done / error 这些业务事件名
2. 事件发送顺序
3. custom world session 的查询与回复文本推导
4. 业务错误到 SSE error 事件的映射策略

原因固定如下：

1. 这些内容属于业务协议，而不是通用传输设施
2. 当前不同链路未来很可能有不同事件集合
3. 先把传输层抽干净，后续真实流式能力才能稳定复用

4. 基础设施 API 口径

本轮在 server-rs/crates/api-server/src/sse.rs 提供：

1. SseEventBuffer
   • 面向当前最小兼容场景
   • 内部持有 String
   • 提供 push_json(event, payload) 与 into_response()
2. SseStreamWriter
   • 面向后续真流式场景
   • 内部持有实时写出的 channel sender
   • 提供 push_json(event, payload)
   • writer 被 drop 后，流自动结束
3. new_sse_stream()
   • 返回 (SseStreamWriter, Response)
   • 业务 handler 可先把 Response 返回，再异步持续推送事件
4. build_sse_response(body)
   • 统一写入标准 SSE 响应头
5. encode_sse_event(body, event, payload)
   • 只负责把事件编码为：

   event: xxx
   data: {...}
   
   

5. 标准响应头

所有通过本基础设施输出的 SSE 响应，统一包含：

1. Content-Type: text/event-stream; charset=utf-8
2. Cache-Control: no-cache
3. X-Accel-Buffering: no

当前不默认加入：

1. Connection: keep-alive

原因：

1. 当前 Rust axum 一次性 body 返回场景不依赖显式设置该头
2. 保持最小必要头集合，避免提前固化未来长连接策略

6. 与 custom world message stream 的关系

POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream 当前仍然保持 Stage 8 文档冻结的最小语义：

1. 业务层先完成 deterministic 写表
2. 读取最新 session snapshot
3. 组装 reply_delta
4. 组装 session
5. 组装 done
6. 一次性返回完整 SSE 文本

本轮变化只在于：

1. 事件编码和响应头不再手写在 custom_world.rs
2. 改由 sse.rs 基础设施承接
3. 同时补出实时 writer 版本，但当前不强制业务路由马上切换

7. 验收标准

当以下条件满足时，本轮视为完成：

1. api-server/src/sse.rs 已提供可复用 SSE helper
2. api-server/src/sse.rs 已同时提供缓冲式与实时写出式两种能力
3. custom_world.rs 不再内联维护 SSE 编码与响应头细节
4. cargo fmt -p api-server 通过
5. cargo check -p api-server 通过
6. npm run check:encoding 通过

8. 一句话结论

本轮把 Rust api-server 里的 SSE 能力收口为“双模式传输层基础设施”，同时提供缓冲式输出与实时写事件 writer，但不改当前业务事件协议，也不强制现有 custom world 路由立即切到真流式。