Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,105 +0,0 @@
|
||||
# Rust `api-server` SSE 使用口径（2026-04-22）
|
||||
|
||||
日期：`2026-04-22`
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于冻结 `server-rs/crates/api-server` 的 SSE 实现口径。
|
||||
|
||||
本轮结论调整为：Rust `api-server` 不再维护自定义 `sse.rs` 基础设施，统一使用 Axum 内建的 `axum::response::sse::{Event, Sse}` 能力。
|
||||
|
||||
本轮目标只有三个：
|
||||
|
||||
1. 删除 `server-rs/crates/api-server/src/sse.rs` 自定义模块。
|
||||
2. 把现有 custom world message stream 切到 Axum 官方 SSE 类型。
|
||||
3. 保持现有业务事件协议与“一次性返回完整事件序列”的兼容语义不变。
|
||||
|
||||
本轮不做：
|
||||
|
||||
1. 不改前端消费协议。
|
||||
2. 不把 custom world message stream 当场改成真实逐段 token streaming。
|
||||
3. 不引入跨 crate 的共享 SSE runtime helper。
|
||||
4. 不抽象 `reply_delta / session / done / error` 等业务事件名。
|
||||
|
||||
## 2. 当前问题
|
||||
|
||||
上一轮曾在 `server-rs/crates/api-server/src/sse.rs` 中抽出自定义 SSE helper，用于统一响应头、事件编码、缓冲式输出和实时 writer。
|
||||
|
||||
继续保留这套自定义模块的问题是：
|
||||
|
||||
1. Axum 已经提供 `Sse<Event>`、`Event::json_data(...)` 和标准 SSE body 编码。
|
||||
2. 自定义文本编码需要自行维护换行、JSON 序列化、响应头等细节。
|
||||
3. 后续真流式接口如果继续沿用自定义 writer，会和 Axum 官方生态产生重复抽象。
|
||||
4. 当前项目已经以 Axum 作为 Rust HTTP 框架，优先使用框架内建能力更简单。
|
||||
|
||||
## 3. 统一实现口径
|
||||
|
||||
Rust `api-server` 的 SSE 路由统一使用：
|
||||
|
||||
```rust
|
||||
use axum::response::sse::{Event, Sse};
|
||||
```
|
||||
|
||||
有限事件序列使用：
|
||||
|
||||
```rust
|
||||
let stream = tokio_stream::iter(events);
|
||||
Sse::new(stream).into_response()
|
||||
```
|
||||
|
||||
实时流式接口后续直接使用：
|
||||
|
||||
```rust
|
||||
Sse::new(event_stream)
|
||||
```
|
||||
|
||||
如需保持长连接，可在真实长流接口中追加：
|
||||
|
||||
```rust
|
||||
.keep_alive(axum::response::sse::KeepAlive::default())
|
||||
```
|
||||
|
||||
## 4. 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. 通过 Axum `Sse` 返回完整事件序列。
|
||||
|
||||
本轮只替换传输层实现，不改变事件顺序、事件名和 payload 结构。
|
||||
|
||||
## 5. 响应头说明
|
||||
|
||||
Axum `Sse` 默认写入：
|
||||
|
||||
1. `Content-Type: text/event-stream`
|
||||
2. `Cache-Control: no-cache`
|
||||
|
||||
当前不再额外写入自定义 `X-Accel-Buffering: no` helper。
|
||||
|
||||
原因：
|
||||
|
||||
1. 本轮目标是移除项目自定义 SSE 模块，避免继续维护传输层封装。
|
||||
2. 当前 custom world stream 仍是短生命周期的兼容事件序列，不是长时间 token streaming。
|
||||
3. 如果未来某条真实长流接口需要反向代理禁用缓冲，应在该路由或统一 HTTP 中间件层显式评估，而不是恢复自定义 SSE 编码器。
|
||||
|
||||
## 6. 验收标准
|
||||
|
||||
当以下条件满足时，本轮视为完成：
|
||||
|
||||
1. `api-server/src/sse.rs` 已删除。
|
||||
2. `api-server/src/main.rs` 不再声明 `mod sse;`。
|
||||
3. `custom_world.rs` 不再依赖 `crate::sse::SseEventBuffer`。
|
||||
4. custom world message stream 使用 Axum `Sse<Event>` 构造响应。
|
||||
5. 为旧自定义 writer 引入的 `bytes`、`tokio::sync` feature 等依赖已清理。
|
||||
6. `cargo fmt -p api-server` 通过。
|
||||
7. `cargo check -p api-server` 通过。
|
||||
8. `npm run check:encoding` 通过。
|
||||
|
||||
## 7. 一句话结论
|
||||
|
||||
Rust `api-server` 的 SSE 能力以 Axum 内建 `Sse<Event>` 为唯一实现入口，不再保留项目自定义 `sse.rs` 模块；当前 custom world stream 只替换传输层，不改变业务协议。
|
||||
Reference in New Issue
Block a user