Agent Session 恢复与容错策略
Agent Session 恢复与容错策略
学习目标
- 掌握 6 种恢复场景的处理策略
- 理解双回退系统（model-fallback + runtime-fallback）
- 识别恢复过程中的状态不一致陷阱
前置知识
本章涉及 Session 恢复的通用原理，建议先阅读：
下文假设你已理解恢复场景分类和恢复架构模式，直接聚焦 Oh-My-OpenAgent 的具体实现。
项目实践
恢复场景与对应模块
Oh-My-OpenAgent 为每种常见失败场景提供了独立的恢复模块：
| 恢复场景 | 模块位置 | 策略 |
|---|---|---|
| 上下文窗口超限 | src/features/anthropic-context-window-limit-recovery/ | 智能压缩 + 降级到 fallback 模型 |
| 编辑错误 | src/features/edit-error-recovery/ | 重建 tool state，跳过无效 tool-part |
| 上下文窗口监控 | src/hooks/context-window-monitor.ts | 提前预警，主动触发压缩 |
| Todo 保持 | src/hooks/compaction-todo-preserver/ | 压缩时保留 Todo 状态 |
| 空任务响应 | src/hooks/empty-task-response-detector.ts | 检测空响应并重新提示 |
上下文窗口恢复
当 Anthropic API 返回 context window exceeded 错误时：
- 检测：通过错误消息模式匹配识别上下文超限
- 压缩：触发 compaction，将历史消息摘要化
- 保留关键状态：通过
compaction-todo-preserverHook 保留 Todo 列表 - 重试：使用压缩后的上下文重新发送请求
- 降级：如果压缩后仍超限，切换到上下文窗口更大的 fallback 模型
双回退系统
Oh-My-OpenAgent 使用两个独立的回退系统：
- model-fallback（主动）：在调用前根据 provider 健康状态选择模型链
- runtime-fallback（被动）：在运行时失败后按
fallback_models数组重试
src/shared/model-suggestion-retry.ts（24KB+）实现了复杂的回退逻辑，包括：
- 按错误类型分类回退策略（限流 vs 认证失败 vs 网络错误）
- model-scoped cooldown：同一提供商的不同模型可独立冷却
- 冷却原因识别：不仅限于 429，还包括提供商特定的限流消息
Edit Error Recovery
位于 src/features/edit-error-recovery/，处理编辑工具的失败：
- 检测编辑工具返回的错误
- 重建可恢复的工具状态
- 跳过无法恢复的 tool-part ID
- 向 Agent 提供清晰的错误提示，指导重新尝试
Context Window Monitor
位于 src/hooks/context-window-monitor.ts，主动监控上下文使用：
- 在上下文使用率达到阈值时发出警告
- 触发预emptive compaction（在超限之前）
- 避免等到 API 返回错误才处理
问题与规避
恢复过程中的状态不一致
问题：恢复操作可能引入新的状态不一致，例如跳过 tool-part 后后续消息引用了被跳过的部分。
规避：恢复后验证消息历史完整性，只跳过真正不可恢复的部分。
压缩导致关键信息丢失
问题：智能压缩可能丢弃后续推理所需的关键上下文。
规避：
- 保留最近的对话（时间局部性）
- 保留工具调用的关键输出
- Todo 状态通过专门的 Hook 保留
设计取舍
透明恢复 vs 显式通知
| 方案 | 优势 | 代价 |
|---|---|---|
| 透明恢复 | 用户无感知、工作流不中断 | 用户不知道发生了恢复，可能无法理解某些行为 |
| 显式通知 | 用户了解系统状态 | 频繁通知造成信息噪音 |
Oh-My-OpenAgent 的选择：透明恢复为主，仅在恢复失败时通知用户。日常恢复对用户透明。