feat: checkpoint m5 and bootstrap m6 asset flow

docs/technical/RUST_API_SERVER_SSE_INFRASTRUCTURE_DESIGN_2026-04-22.md

@@ -0,0 +1,118 @@
+# 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)`
+   - 只负责把事件编码为：
+   ```text
+   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 的同步伪流式语义。