断线恢复（resume） 产品与架构

它是什么

断线恢复（resume）指客户端断线后带进度指针重连、只补收未看事件的能力。它的前提是「Agent 的运行」与「客户端的连接」彻底解耦：断线不丢事件——Agent 照常运行、事件照常落存储，重连只是「从断点续读」。一句话记住产品语义：放弃连接 ≠ 放弃任务。产品形态参照 Claude Code 的 --resume 会话恢复；本教程把它做进了协议层，用 since 参数 + lastSeq 精确定位断点。

机制

协议侧只有两个改动：GET /events?since=N 只回放 seq > N 的增量；POST /chat 返回 lastSeq，客户端据此只订阅本轮新事件。缺省 since=0 等于全量回放，向后兼容旧客户端。为什么不用 SSE 自带的 Last-Event-ID？因为协议要同时服务 EventSource、fetch 流、curl 等任意 HTTP 客户端，进度语义必须走应用层而不是 SSE 传输层——传输层机制只作锦上添花。

边界与坑

断线恢复只恢复了「读」侧（事件流）；会话的「写」侧（消息历史）仍在服务端内存里——服务器重启一切蒸发，真正「进程死了恢复」需要第 10 章的持久层接管。另一个坑是重复投递：网络层可能重试、客户端可能把 since 传错（多记漏一条、少记重一条），所以服务端允许重复投递，客户端必须幂等消费（见第 16 章「常见坑」坑二）。

在本教程的位置

第 16 章实现从序号分配器、事件存储到重连续传协议的完整链路；第 17 章的前端把重放的事件喂给 reducer 恢复界面；真正的「取消/抢占」留到 ch17 前端打断与 ch18 权限层。