extract rust sse infrastructure

docs/technical/RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md

@@ -6,14 +6,15 @@
 
 这份文档用于冻结 `server-rs/crates/api-server` 内部的 SSE 基础设施抽取口径。
 
-本轮目标只有一个：
+本轮目标只有两个：
 
 1. 把当前散落在业务 handler 中的 `text/event-stream` 响应头与事件文本编码逻辑，收口为 `api-server` 可复用的 Rust 基础设施。
+2. 在同一基础设施上补出“实时写事件”的 writer 版本，为后续真流式接口预留稳定入口。
 
 本轮不做：
 
 1. 不改前端消费协议
-2. 不把 custom world message stream 改成真实逐段 token streaming
+2. 不把 custom world message stream 当场改成真实逐段 token streaming
 3. 不引入跨 crate 的共享 `shared-contracts` SSE runtime helper
 4. 不同时重构 story / runtime / txt mode 的未来流式接口
 
@@ -37,7 +38,9 @@
 1. 标准 SSE 响应头构造
 2. 单条事件编码
 3. 缓冲式 SSE body builder
-4. 一次性返回完整 SSE 文本的响应构造
+4. 实时写事件的 SSE writer
+5. 一次性返回完整 SSE 文本的响应构造
+6. 基于流 body 的实时 SSE 响应构造
 
 本轮明确不抽：
 
@@ -60,9 +63,17 @@
    - 面向当前最小兼容场景
    - 内部持有 `String`
    - 提供 `push_json(event, payload)` 与 `into_response()`
-2. `build_sse_response(body)`
+2. `SseStreamWriter`
+   - 面向后续真流式场景
+   - 内部持有实时写出的 channel sender
+   - 提供 `push_json(event, payload)`
+   - writer 被 drop 后，流自动结束
+3. `new_sse_stream()`
+   - 返回 `(SseStreamWriter, Response)`
+   - 业务 handler 可先把 `Response` 返回，再异步持续推送事件
+4. `build_sse_response(body)`
    - 统一写入标准 SSE 响应头
-3. `encode_sse_event(body, event, payload)`
+5. `encode_sse_event(body, event, payload)`
    - 只负责把事件编码为：
    ```text
    event: xxx
@@ -89,7 +100,7 @@
 
 ## 6. 与 custom world message stream 的关系
 
-`POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream` 仍然保持 Stage 8 文档冻结的最小语义：
+`POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream` 当前仍然保持 Stage 8 文档冻结的最小语义：
 
 1. 业务层先完成 deterministic 写表
 2. 读取最新 session snapshot
@@ -102,17 +113,19 @@
 
 1. 事件编码和响应头不再手写在 `custom_world.rs`
 2. 改由 `sse.rs` 基础设施承接
+3. 同时补出实时 writer 版本，但当前不强制业务路由马上切换
 
 ## 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` 通过
+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 能力收口为“最小传输层基础设施”，统一事件编码与响应头，但不改业务事件协议和当前 custom world 的同步伪流式语义。
+本轮把 Rust `api-server` 里的 SSE 能力收口为“双模式传输层基础设施”，同时提供缓冲式输出与实时写事件 writer，但不改当前业务事件协议，也不强制现有 custom world 路由立即切到真流式。