john
08feae8bef
落地 H5 Session 架构 Patch 1–5（Broker 收口、Router decision、SSE taxonomy、goosed 边界检查）， 并新增可选 MEMIND_RUN_STREAM_REPLAY run 事件回放与 H5 假交付 guard；修复 Finish 先于 agent-run gate 导致 UI 永久 loading 的竞态，接入 verify:h5-session-patches 回归脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
62 lines
2.0 KiB
Markdown
62 lines
2.0 KiB
Markdown
# Patch 4b：Run SSE Replay（进行中，禁止合并 main / 上 103）
|
||
|
||
> **状态：代码 + 单测已完成（2026-07-06）；Finish 竞态见 [h5-finish-before-run-gate-20260706.md](./h5-finish-before-run-gate-20260706.md)。禁止 merge main / 上 103。**
|
||
|
||
## 目标
|
||
|
||
解决 H5 run SSE 重连丢状态问题：
|
||
|
||
- 使用已有 `h5_agent_run_events.id` 作为 SSE `id:` cursor
|
||
- 客户端 `Last-Event-ID` 重连后从 DB 补发 missed events
|
||
- 状态变更时写入 `run_snapshot` 事件，保证 sessionId 回填可回放
|
||
|
||
## 开关
|
||
|
||
```bash
|
||
# 服务端（默认 0 = 旧 poll-only 行为）
|
||
MEMIND_RUN_STREAM_REPLAY=1
|
||
|
||
# 本地验证
|
||
MEMIND_RUN_STREAM_REPLAY=1 pnpm dev
|
||
```
|
||
|
||
客户端 `subscribeAgentRunEvents` 已支持 `Last-Event-ID` + 断线重连（与 session stream 一致）。
|
||
|
||
## 改动文件
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `agent-run-stream.mjs` | replay 纯函数、flag |
|
||
| `agent-run-gateway.mjs` | `listRunEventsForUser`、`appendRunSnapshot` |
|
||
| `agent-run-routes.mjs` | replay 模式 SSE handler |
|
||
| `src/api/client.ts` | run SSE Last-Event-ID + 重连 |
|
||
| `agent-run-stream.test.mjs` | 单测 |
|
||
| `agent-run-routes.test.mjs` | replay SSE handler 用例 |
|
||
| `agent-run-gateway.test.mjs` | replay cursor / cursorMiss / run_snapshot 用例 |
|
||
|
||
## 2026-07-06 补充
|
||
|
||
- 修复 `listRunEventsForUser` 误返回 `cursorMiss: false`（ stale `Last-Event-ID` 无法触发全量补发）
|
||
- gateway 新增 3 项 replay 单测（51 pass 合计）
|
||
|
||
## 本地测试清单（合并/发布前必跑）
|
||
|
||
```bash
|
||
npm run verify:h5-session-patches
|
||
# 或分项：
|
||
node --test agent-run-stream.test.mjs agent-run-routes.test.mjs agent-run-gateway.test.mjs
|
||
npm run verify:goosed-proxy-boundary
|
||
```
|
||
|
||
手工：
|
||
|
||
1. `MEMIND_RUN_STREAM_REPLAY=1 pnpm dev`
|
||
2. 发起 agent run，DevTools 观察 `/agent/runs/:id/events` 含 `id:` 行
|
||
3. 模拟断网/刷新，确认重连后仍能收到 `sessionId` 与 terminal `succeeded`
|
||
|
||
## 与 Patch 4a 关系
|
||
|
||
- Patch 4a：taxonomy shadow（已完成）
|
||
- Patch 4b：run replay（本文件）
|
||
- Session stream replay 仍为后续项，不在 4b 范围
|