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 基础设施。

本轮不做：

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 文本的响应构造

本轮明确不抽：

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. build_sse_response(body)
   • 统一写入标准 SSE 响应头
3. 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 基础设施承接

7. 验收标准

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

1. api-server/src/sse.rs 已提供可复用 SSE helper
2. custom_world.rs 不再内联维护 SSE 编码与响应头细节
3. cargo fmt -p api-server 通过
4. cargo check -p api-server 通过
5. npm run check:encoding 通过

8. 一句话结论

本轮把 Rust api-server 里的 SSE 能力收口为“最小传输层基础设施”，统一事件编码与响应头，但不改业务事件协议和当前 custom world 的同步伪流式语义。