Index 11: Error Recovery — 重试 / fallback / token 升级

[INFO] Retrying chat after rate_limit_error (attempt 1/3, delay=500ms)
[INFO] Retrying chat after rate_limit_error (attempt 2/3, delay=1000ms)
[Agent] 好的，我来看看这个文件...

AgentLoop.run()
  → llmProvider.chat(messages, options, tools)     ← 唯一的外部依赖
      → AnthropicProvider
          → HTTP POST api.anthropic.com/v1/messages

} catch (e: Exception) {
    logger.error(e) { "API call failed" }
    ChatResponse(
        content = "Error: ${e.message}",
        stopReason = StopReason.ERROR
    )
}

StopReason.ERROR, StopReason.STOP_SEQUENCE -> {
    if (response.content.isNotBlank()) {
        messagesHistory.add(Message(Role.ASSISTANT, response.content))
    }
    return response.content   // ← 终止整个 turn，返回错误文本
}

                    ┌─────────────────────────────────────────┐
                    │           AnthropicProvider             │
                    │   (吞异常 → ERROR + 结构化 LlmError)      │
                    └──────────────────┬──────────────────────┘
                                       │ delegate
                    ┌──────────────────▼──────────────────────┐
                    │        ErrorRecoveryManager             │
                    │   (实现 LLMProvider 的透明包装器)         │
                    │                                        │
                    │  ┌────────────────────────────────────┐ │
                    │  │ MAX_TOKENS → TokenEscalation        │ │
                    │  │ ERROR 瞬时 → RetryStrategy 退避重试  │ │
                    │  │ ERROR 永久 → ModelFallback 换模型    │ │
                    │  │ delegate 抛异常 → CancellationException│
                    │  │   重抛 / 其他归一 network_error      │ │
                    │  └────────────────────────────────────┘ │
                    └──────────────────┬──────────────────────┘
                                       │ 实现 LLMProvider
              ┌────────────────────────┼────────────────────────┐
              │                        │                        │
         AgentLoop              SubagentFactory           Memory/Compactor
       (主循环，无感知)          (子智能体隔离)           (摘要/提取)

                        ErrorClassifier ← LlmError(type, message)
                        （瞬时 / 永久 分类）

data class LlmError(
    val type: String,     // "rate_limit_error" / "api_error" / "authentication_error" / "network_error" ...
    val message: String
)

data class ChatResponse(
    val content: String,
    val stopReason: StopReason,
    val toolCalls: List<ToolCall> = emptyList(),
    val error: LlmError? = null   // s11: 非空表示本次调用失败
)

// 网络兜底
} catch (e: Exception) {
    ChatResponse(
        content = "Error: ${e.message}",
        stopReason = StopReason.ERROR,
        error = LlmError(type = ERROR_TYPE_NETWORK, message = e.message ?: "Unknown error")
    )
}

// API 错误响应——透传服务端 type
if (anthropicError != null) {
    return ChatResponse(
        content = "API Error: ${anthropicError.message}",
        stopReason = StopReason.ERROR,
        error = LlmError(type = anthropicError.type, message = anthropicError.message)
    )
}

enum class ErrorCategory { TRANSIENT, PERMANENT }

object ErrorClassifier {
    fun classify(error: LlmError): ErrorCategory {
        val type = error.type.lowercase()
        if (TRANSIENT_TYPES.any { type.contains(it) }) return ErrorCategory.TRANSIENT
        if (PERMANENT_TYPES.any { type.contains(it) }) return ErrorCategory.PERMANENT
        return ErrorCategory.TRANSIENT   // 未知 type 兜底按瞬时——重试比放弃安全
    }

    private val TRANSIENT_TYPES = listOf(
        "network_error", "rate_limit_error", "api_error", "overloaded_error", "timeout"
    )
    private val PERMANENT_TYPES = listOf(
        "authentication_error", "invalid_request_error", "not_found_error", "permission_error"
    )
}

class RetryStrategy(
    val maxAttempts: Int = 3,       // 总尝试次数（含首次）
    val baseDelayMs: Long = 500,    // 首次失败后的退避基准
    val backoffFactor: Double = 2.0 // 每次失败延迟翻倍
) {
    fun shouldRetry(attempt: Int): Boolean = attempt + 1 < maxAttempts

    fun delayMs(attempt: Int): Long =
        (baseDelayMs * Math.pow(backoffFactor, attempt.toDouble())).toLong().coerceAtLeast(0)
}

class ModelFallback(val fallbackModels: List<String> = emptyList()) {
    fun chainFrom(primaryModel: String): List<String> =
        (listOf(primaryModel) + fallbackModels).distinct()   // 主模型在前 + 去重
}

class TokenEscalation(
    val maxEscalations: Int = 1,     // 最多升级几次
    val factor: Double = 2.0,        // 每次 maxTokens * factor
    val ceiling: Int = 32_768        // 硬上限
) {
    fun escalatedMaxTokens(current: Int, escalation: Int): Int? {
        if (escalation > maxEscalations) return null
        val escalated = (current * Math.pow(factor, escalation.toDouble())).toInt()
        return if (escalated > ceiling) null else escalated   // 超 ceiling 放弃升级
    }
}

class ErrorRecoveryManager(
    private val delegate: LLMProvider,
    private val retryStrategy: RetryStrategy = RetryStrategy(),
    private val modelFallback: ModelFallback = ModelFallback(),
    private val tokenEscalation: TokenEscalation = TokenEscalation()
) : LLMProvider {
    private val logger = KotlinLogging.logger {}

    override suspend fun chat(
        messages: List<Message>,
        options: ChatOptions,
        tools: List<JsonObject>,
        toolResults: List<ToolResult>
    ): ChatResponse {
        val models = modelFallback.chainFrom(options.model)

        for (model in models) {
            val attemptOptions = options.copy(model = model)
            var attempt = 0

            while (true) {
                var response = safeChat(messages, attemptOptions, tools, toolResults)

                // MAX_TOKENS：先尝试 token 升级；升级耗尽返回最后（最完整）的截断响应
                if (response.stopReason == StopReason.MAX_TOKENS) {
                    val escalated = escalateIfNeeded(messages, attemptOptions, tools, toolResults, response)
                    if (escalated.stopReason == StopReason.MAX_TOKENS) {
                        return escalated   // 升级耗尽 → 交还 AgentLoop 走 s08 压缩
                    }
                    response = escalated   // 升级后成功或 ERROR，走下方统一处理
                }

                // 成功（END_TURN / TOOL_USE / STOP_SEQUENCE）直接返回
                if (response.stopReason != StopReason.ERROR) {
                    return response
                }

                // ERROR：判断瞬时 / 永久
                val error = response.error ?: LlmError(UNKNOWN_ERROR_TYPE, response.content)
                val category = ErrorClassifier.classify(error)

                if (category == ErrorCategory.TRANSIENT && retryStrategy.shouldRetry(attempt)) {
                    val delayMs = retryStrategy.delayMs(attempt)
                    logger.info {
                        "Retrying chat after ${error.type} (attempt ${attempt + 1}/${retryStrategy.maxAttempts}, delay=${delayMs}ms)"
                    }
                    delay(delayMs)
                    attempt++
                    continue
                }

                // 永久错误或重试耗尽：尝试下一个模型
                if (model != models.last()) {
                    logger.warn { "Chat failed with ${error.type}, falling back to next model" }
                    break
                }

                // 全部模型失败，返回最后的 ERROR
                logger.error { "All models failed, last error: ${error.type}: ${error.message}" }
                return response
            }
        }

        error("unreachable: model chain is never empty")
    }
}

    private suspend fun safeChat(...): ChatResponse = try {
        delegate.chat(...)
    } catch (e: CancellationException) {
        throw e   // 结构化并发：取消必须传播
    } catch (e: Exception) {
        logger.warn(e) { "LLM chat threw, treating as network error" }
        ChatResponse(
            content = "Error: ${e.message}",
            stopReason = StopReason.ERROR,
            error = LlmError(NETWORK_ERROR_TYPE, e.message ?: "Unknown error")
        )
    }

    private suspend fun escalateIfNeeded(...): ChatResponse {
        var lastMaxTokens = original
        var escalation = 1
        while (true) {
            val newMaxTokens = tokenEscalation.escalatedMaxTokens(options.maxTokens, escalation)
                ?: return lastMaxTokens   // 升级不可用/耗尽 → 返回最后（最完整）的截断响应
            logger.info { "MAX_TOKENS, escalating maxTokens ${options.maxTokens} → $newMaxTokens (escalation $escalation)" }
            val response = safeChat(messages, options.copy(maxTokens = newMaxTokens), tools, toolResults)
            if (response.stopReason == StopReason.MAX_TOKENS) {
                lastMaxTokens = response
                escalation++
                continue
            }
            return response   // 升级后成功或 ERROR（ERROR 由主循环处理）
        }
    }

s11 token 升级：maxTokens 1000 → 2000（输出预算不足）
  ├─ 升级后成功 → 完成
  └─ 升级耗尽仍 MAX_TOKENS → 返回截断响应
      → AgentLoop 触发 s08 压缩（上下文过长）
      → 压缩后重试

// s11: 错误恢复层——透明包装，主循环/子智能体/压缩器/记忆提取全部自动获得
// 瞬时重试 + 模型 fallback + MAX_TOKENS token 升级能力
val resilientProvider = ErrorRecoveryManager(
    delegate = llmProvider,
    retryStrategy = RetryStrategy(),
    modelFallback = ModelFallback(),   // MVP 默认空 fallback，机制就绪
    tokenEscalation = TokenEscalation()
)

用户："重构 UserService"
AgentLoop.run()
  → resilientProvider.chat(...)
      → delegate.chat → ERROR(rate_limit_error)
      → ErrorClassifier: TRANSIENT
      → RetryStrategy.shouldRetry(0) = true → delay(500ms)
      → delegate.chat → ERROR(rate_limit_error)
      → RetryStrategy.shouldRetry(1) = true → delay(1000ms)
      → delegate.chat → END_TURN("好的，让我先看一下...")
  → AgentLoop 正常继续
[INFO] Retrying chat after rate_limit_error (attempt 1/3, delay=500ms)
[INFO] Retrying chat after rate_limit_error (attempt 2/3, delay=1000ms)

  → delegate.chat → ERROR(authentication_error)
  → ErrorClassifier: PERMANENT
  → 不重试 → ModelFallback: 下一个模型
  → delegate.chat(模型=claude-opus-4-8) → END_TURN
[WARN] Chat failed with authentication_error, falling back to next model

  → delegate.chat → MAX_TOKENS("partial")
  → TokenEscalation: maxTokens 1000 → 2000
  → delegate.chat(maxTokens=2000) → END_TURN("full")
[INFO] MAX_TOKENS, escalating maxTokens 1000 → 2000 (escalation 1)

  → delegate.chat → ERROR(api_error)  × 3
  → 重试耗尽 → 返回最后的 ERROR
  → AgentLoop 按既有逻辑兜底（追加错误内容并返回）
[ERROR] All models failed, last error: api_error: Internal server error

class ScriptedProvider(private val responses: MutableList<ChatResponse>) : LLMProvider {
    val callOptions = mutableListOf<ChatOptions>()
    override suspend fun chat(messages, options, tools, toolResults): ChatResponse {
        callOptions.add(options)
        return if (responses.isNotEmpty()) responses.removeAt(0) else error("No more scripted responses")
    }
}