错误处理与恢复

wesgine 的错误分类、认知韧性机制与 Cell 级故障策略。

错误分类

类别	可重试	示例
Provider 瞬时错误	✅	503、429、网络超时
认知内部错误	✅	LLM 返回格式异常
安全策略阻止	❌	guardrail_blocked
内容过滤	❌	content_filter_blocked
预算耗尽	❌	budget_exhausted
用户中断	❌	context_cancelled
崩溃	❌	panic_stop

认知韧性（Cognitive Resilience）

三层防御机制在 internal/cognitive/resilience/ 实现：

Retry（重试）

对可重试错误自动重试：

最大重试次数有上限
指数退避间隔
只对瞬时错误生效

Backoff（退避）

Provider 持续失败时的冷却机制：

标记 Provider 为不健康
冷却期间跳过该 Provider
冷却结束后恢复尝试
触发 fallback 到其他 Provider

ImageRecovery（图片恢复）

图片相关错误的专用恢复：

Vision 不支持时剥离图片重试
图片格式错误时转换格式
图片过大时压缩后重试

Cell 级故障策略

故障计数

Cell 跟踪连续故障次数：

字段	说明
`ConsecutiveFailures`	连续失败次数
`LastFailure`	最后失败时间
`FailureReason`	失败原因分类

熔断（Circuit Breaking）

连续故障超过阈值后：

Cell 标记为 Faulted
新请求被拒绝（429）
后台健康检查继续
恢复后自动解除

手动重置

hyp.Cells().ResetFaults(ctx, cellID)

清零故障计数，不重启 Cell。

FaultPolicyOverride

通过 CellSpec 覆盖默认故障策略：

CellSpec{
    FaultPolicyOverride: &FaultPolicy{
        MaxConsecutiveFailures: 10,  // 默认更严格
        CooldownSeconds:       300,
    },
}

错误 UI 展示

可重试错误

{
  "severity": null,
  "recoverable": false
}

→ 红色错误块 + 重试按钮

不可重试错误

{
  "severity": "info",
  "recoverable": false
}

→ 柔和提示 + 无重试按钮

静默错误

{
  "severity": "silent"
}

→ 不渲染（引擎自愈中）

用户中断的处理

context_cancelled / interrupted：

在 createDoneReasonMapper 中被压制
不渲染任何错误块
不显示重试按钮

余额 / 欠费错误

action: 'none'：

Chat 气泡只报错
不画「前往充值」按钮
结清入口在其他 UI 位置