错误恢复机制

wesclaw 的 AI 引擎内置了多层错误恢复机制，确保 Run 异常终止时能最大程度保全上下文和工作进度。

Run 终止的常见原因

CycleDetector（死循环检测）

当 AI 陷入重复操作时，CycleDetector 会介入：

检测指标

• IdenticalCall：完全相同的工具调用（相同工具 + 相同参数 + 相同结果）达到阈值
• ActionStreak：写入类工具（edit/write/exec）连续调用达到阈值
• ExplorationStreak：读取类工具（read/grep/search）连续调用达到阈值

两阶段恢复

1. 自愈：首次触发时，注入系统纠正消息，重置计数器，给 AI 第二次机会
2. HITL 升级：第二次触发时，询问用户"怎么办"。超时 60 秒后自动终止并保存进度

参数变化识别

CycleDetector 支持"进度感知"——如果相同工具的参数在变化（例如编辑不同文件），streak 计数减半，避免误判正常的批量操作。

ErrorStreakDetector（伪进展检测）

当 AI 的工具调用连续报错但仍在"尝试"时，这是一种伪进展——看起来在工作，实际没有推进。

• 检测连续错误的工具调用
• 触发 HITL 询问用户是否继续
• 超时后终止 Run

HITL 超时处理

当引擎需要用户决策（CycleDetector 升级、ErrorStreak 确认等）但用户未响应时：

• 默认等待 60 秒
• 超时后自动终止 Run
• 终止时保存当前进度（Plan 标记为 terminated，SessionState 仍然结算）

上下文压缩失败的 Fallback

CognitiveSettlement（认知结算）失败时的恢复链：

1. 重试：最多重试 3 次
2. MechanicalFallback：放弃 LLM 结算，改用确定性方式提取关键信息
   • 从即将丢弃的消息中提取工具调用证据（ExtractToolEvidence）
   • 将证据注入固定系统消息（Pinned message）
   • 确保关键操作结果不会因压缩而丢失
3. 降级标记：标记 degraded=true 并记录降级原因

Run 生命周期与 SSE 解耦

Run 生命周期始终与传输层（SSE 连接）解耦：

• SSE 断开不会取消 Run——Run 在后端继续执行
• 重新连接后可以通过事件重放（GET /runs/{runID}/events?from_seq=N）恢复
• 取消 Run 的唯一途径是用户主动中断

Provider 瞬时错误

当模型调用遇到瞬时错误（503 / 429 等）：

• 引擎的 SequentialFallbackResolver 会自动 fallback 到备选 Provider
• WES 模型 JWT 过期后，自动 fallback 到 BYOK Provider
• 这类错误的重试按钮在界面上会显示

不可重试的错误

以下错误重试同样输入只会得到同样结果，界面不显示重试按钮：

• guardrail_blocked：治理策略阻止
• content_filter_blocked：内容过滤阻止
• budget_exhausted：预算耗尽
• memory_limit_exceeded：记忆限制

这些错误会以柔和提示（而非红色错误块）展示，引导你"换一种表述"或"开新对话"。

相关文档

• Run 生命周期 → run-lifecycle.md
• Plan 系统使用 → plan-usage.md
• HITL 审批 → hitl-approval.md
• 故障排除 → troubleshooting.md