事件、持久化重放与索引进度¶

手册 · 架构 · 索引恢复

不同事件系统具有不同的持久化保证。从正在诊断的操作入手；进程本地通知不是持久的回合日志。

回合生命周期¶

应用服务通过共享的会话存储和运行时来协调准入与执行。每次执行都有一个回合级 StreamBus；事件必须先进入持久化/重放路径，之后适配器才能将其投递给消费者。浏览器断开本身并不能证明回合失败，也不能授权第二次执行。恢复过程必须区分仍然有效的租约与已丢失的工作进程，并保留终态。

在修改流式传输时，请测试重复提交、部分输出后的重连、终态事件后的重放、取消以及工作进程丢失等场景。应保留事件 ID/序列和现有投影规则，而不是把到达顺序或渲染后的文本视作持久化的事实来源。协议类型位于 core/stream.py；前端消费 web/contracts/ 下的契约。

单个工作进程可以使用内存协调器。超过一个后端工作进程则需要 Redis 协调，通过 system.backend_workers 和 integrations.turn_coordination 配置。设置校验器 会拒绝在内存协调器下配置多个工作进程，也会拒绝没有 URL 的 Redis。Redis 是协调/通知层，不能替代会话存储。deeptutor doctor runtime --format json 输出运行时诊断信息。

知识库进度¶

ProgressTracker 持久化快照，并通过注入的进度端口发出进度。API 安装 WebSocket/SSE 端口；领域代码不得导入 FastAPI 来报告进度。CLI/SDK 执行时即使没有浏览器广播器，也能持久化进度。

知识路由器暴露了进度 WebSocket 与任务日志 SSE 流。useKnowledgeProgress 将二者结合，跟踪预期任务，并对齐终态。在重连或应用快照时，请保留工作区范围与任务标识。日志和百分比估算只是观测结果，不能证明索引已经发布。

索引日志 记录源级的成功、失败和中断工作。完成状态必须与已持久化的发布状态一致；解析器处理完最后一批并不足以证明完成。重建不得用部分候选替换可查询版本。关于解析检查点和精确的源定位器，另请参阅源可视化。

调试顺序¶

1. 确定账号、工作区、会话/回合或 KB/任务 ID，以及时间窗口。
2. 先检查持久化状态，再检查协调器/工作进程和传输层。
3. 将浏览器的游标/任务标识与服务端的持久化状态进行对比。
4. 使用测试夹具复现断开的连接、旧快照和重复帧。不要通过手动覆盖成功字段来修复进度。
5. 重新打开后验证终态，而不仅仅是原始浏览器连接仍然存活时。

相关测试套件包括应用测试、协调测试、知识测试和知识进度 WebSocket 测试。