API 服务：认证、限流与 Anthropic API 客户端

Claude Code 的 API 服务层是整个系统的核心通信枢纽，负责与 Anthropic API 及第三方云服务商（AWS Bedrock、Google Vertex AI、Azure Foundry）的安全交互。该层实现了多层次认证机制、智能限流管理、统一客户端抽象以及健壮的错误处理与重试策略，为上层 QueryEngine 提供稳定可靠的 LLM 通信能力。

架构概览

API 服务层采用分层架构设计，将认证、客户端创建、请求构建、响应处理和限流管理解耦为独立模块。这种设计支持多提供商的无缝切换，同时保持核心业务逻辑的一致性。

graph TB
    subgraph "API 服务层架构"
        QueryEngine[QueryEngine 查询引擎] --> ClaudeAPI[Claude API 服务<br/>services/api/claude.ts]
        
        ClaudeAPI --> ClientFactory[客户端工厂<br/>services/api/client.ts]
        ClaudeAPI --> WithRetry[重试逻辑<br/>services/api/withRetry.ts]
        ClaudeAPI --> ErrorHandler[错误处理器<br/>services/api/errors.ts]
        
        ClientFactory --> AuthSystem[认证系统<br/>utils/auth.ts]
        ClientFactory --> AnthropicSDK[Anthropic SDK]
        ClientFactory --> BedrockSDK[AWS Bedrock SDK]
        ClientFactory --> VertexSDK[Vertex AI SDK]
        ClientFactory --> FoundrySDK[Azure Foundry SDK]
        
        AuthSystem --> OAuth[OAuth 客户端<br/>services/oauth/client.ts]
        AuthSystem --> APIKey[API Key 管理]
        AuthSystem --> Keychain[macOS Keychain]
        AuthSystem --> FileDescriptor[文件描述符传递]
        
        ClaudeAPI --> RateLimiter[限流管理器<br/>services/claudeAiLimits.ts]
        RateLimiter --> HeaderParser[响应头解析]
        RateLimiter --> WarningSystem[预警系统]
        RateLimiter --> OverageManager[超限额度管理]
        
        WithRetry --> TransientHandler[瞬态错误处理]
        WithRetry --> BackoffStrategy[退避策略]
        WithRetry --> CooldownManager[冷却期管理]
    end
    
    style QueryEngine fill:#e1f5ff
    style ClaudeAPI fill:#fff4e6
    style ClientFactory fill:#f3e5f5
    style AuthSystem fill:#e8f5e9
    style RateLimiter fill:#fce4ec

Sources: services/api/claude.ts, services/api/client.ts, utils/auth.ts

认证系统

认证系统是 API 服务的安全基石，实现了多源认证、优先级调度和自动刷新机制。系统支持 OAuth 2.0、静态 API Key、动态密钥助手和第三方云服务商认证，通过智能优先级决策确保在复杂环境中选择正确的认证方式。

认证源优先级

认证系统按以下优先级查找可用凭据（从高到低）：

关键决策逻辑：isAnthropicAuthEnabled() 函数决定是否启用第一方认证，该函数会检查是否使用第三方服务或外部认证源，并返回相应的布尔值。这确保了在混合认证环境中的正确行为，避免代理场景下的认证冲突。

Sources: utils/auth.ts

OAuth 2.0 认证流程

OAuth 客户端实现了标准的 Authorization Code Flow with PKCE（Proof Key for Code Exchange），支持浏览器自动化登录和手动授权码输入两种模式。

sequenceDiagram
    participant User as 用户
    participant CLI as CLI 入口
    participant OAuth as OAuth 客户端
    participant Browser as 浏览器
    participant AuthServer as 认证服务器
    participant TokenStore as Token 存储
    
    CLI->>OAuth: /login 命令
    OAuth->>OAuth: 生成 code_verifier & code_challenge
    OAuth->>OAuth: 生成 state 参数
    OAuth->>Browser: 打开授权 URL (PKCE)
    Browser->>AuthServer: 用户登录 & 授权
    AuthServer->>Browser: 重定向到 localhost/callback?code=xxx
    Browser->>OAuth: 回调请求携带 authorization_code
    OAuth->>AuthServer: 交换 code 获取 tokens
    AuthServer->>OAuth: access_token + refresh_token
    OAuth->>TokenStore: 持久化到 ~/.claude/oauth-tokens.json
    OAuth->>CLI: 认证成功
    
    Note over OAuth,AuthServer: 后续请求自动附加 Authorization: Bearer {access_token}
    
    rect rgb(255, 240, 240)
        Note over OAuth,AuthServer: Token 过期时自动刷新
        OAuth->>AuthServer: refresh_token 刷新请求
        AuthServer->>OAuth: 新 access_token
        OAuth->>TokenStore: 更新存储
    end

OAuth Token 结构：

interface OAuthTokens {
  accessToken: string        // 访问令牌（短期有效）
  refreshToken: string       // 刷新令牌（长期有效）
  expiresAt: number         // 过期时间戳（毫秒）
  scopes: string[]          // 授权范围
}

自动刷新机制：checkAndRefreshOAuthTokenIfNeeded() 在每次创建 API 客户端前检查 token 有效性，如果剩余有效期少于 5 分钟则自动刷新。刷新失败时清除本地 token 并提示重新登录。

Sources: services/oauth/client.ts, utils/auth.ts

API Key Helper 机制

API Key Helper 是企业级动态密钥管理的解决方案，允许通过外部命令或脚本动态获取 API Key，支持密钥轮换、短期凭证和集中式密钥管理。

配置方式：

// ~/.claude/settings.json
{
  "apiKeyHelper": "/path/to/key-helper-script.sh"
}

Helper 脚本规范：

• 输入：无（通过环境变量或标准输入传递上下文）
• 输出：标准输出返回 API Key 字符串
• 退出码：0 表示成功，非 0 表示失败
• 超时：默认 30 秒，可通过 CLAUDE_CODE_API_KEY_HELPER_TIMEOUT_MS 配置

缓存与刷新：系统实现了双层缓存策略以平衡性能和安全：

1. 热缓存：TTL 默认 5 分钟，期间直接返回缓存值
2. 后台刷新：过期后立即返回旧值，同时启动异步刷新
3. 冷启动：首次调用阻塞等待，避免竞态条件

Epoch 机制：使用 epoch 计数器防止过期数据污染新缓存。当调用 clearApiKeyHelperCache() 时，epoch 递增，所有进行中的异步操作在完成时检查 epoch，如果已变更则放弃写入。

Sources: utils/auth.ts

第三方云服务商认证

系统支持 AWS Bedrock、Google Vertex AI 和 Azure Foundry 三大云服务商，通过环境变量切换提供商，并自动处理各平台的认证差异。

AWS Bedrock 认证流程：

1. 检查 AWS_BEARER_TOKEN_BEDROCK 环境变量（Bearer Token 认证）
2. 如果未配置，调用 AWS SDK 的默认凭证链（环境变量 → ~/.aws/credentials → EC2 IAM 角色）
3. 通过 refreshAndGetAwsCredentials() 缓存凭证并支持自动刷新
4. 可选配置 ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION 为 Haiku 模型指定不同区域

Vertex AI 认证流程：

1. 调用 google-auth-library 的 GoogleAuth 类
2. 按优先级查找：GOOGLE_APPLICATION_CREDENTIALS → ADC 文件 → gcloud 配置 → GCE 元数据服务器
3. 通过 refreshGcpCredentialsIfNeeded() 处理凭证刷新
4. 区域配置优先级：模型特定环境变量 → CLOUD_ML_REGION → 默认区域

Azure Foundry 认证流程：

1. 检查 ANTHROPIC_FOUNDRY_API_KEY 环境变量（API Key 认证）
2. 如果未配置，使用 DefaultAzureCredential（支持环境变量、Managed Identity、Azure CLI 等）
3. 通过 getBearerTokenProvider() 获取 OAuth token 提供者
4. 配置 ANTHROPIC_FOUNDRY_RESOURCE 或 ANTHROPIC_FOUNDRY_BASE_URL 指定服务端点

Sources: services/api/client.ts

API 客户端工厂

getAnthropicClient() 是创建 API 客户端的统一入口，根据运行环境、认证状态和配置参数动态选择提供商并构建客户端实例。工厂函数实现了延迟加载、依赖注入和配置合并等设计模式。

客户端创建流程

flowchart TD
    Start[getAnthropicClient 调用] --> CheckAuth{检查认证状态}
    
    CheckAuth -->|OAuth| RefreshToken[刷新 OAuth Token]
    CheckAuth -->|API Key| ConfigureHeaders[配置 API Key Headers]
    CheckAuth -->|Bedrock| LoadBedrockSDK[加载 Bedrock SDK]
    CheckAuth -->|Vertex| LoadVertexSDK[加载 Vertex SDK]
    CheckAuth -->|Foundry| LoadFoundrySDK[加载 Foundry SDK]
    
    RefreshToken --> ConfigureHeaders
    ConfigureHeaders --> MergeConfig[合并配置参数]
    
    LoadBedrockSDK --> GetAWSCreds[获取 AWS 凭证]
    GetAWSCreds --> BedrockClient[创建 Bedrock 客户端]
    
    LoadVertexSDK --> GetGCPCreds[获取 GCP 凭证]
    GetGCPCreds --> VertexClient[创建 Vertex 客户端]
    
    LoadFoundrySDK --> GetAzureCreds[获取 Azure 凭证]
    GetAzureCreds --> FoundryClient[创建 Foundry 客户端]
    
    MergeConfig --> FirstPartyClient[创建第一方 Anthropic 客户端]
    
    BedrockClient --> ReturnClient[返回客户端实例]
    VertexClient --> ReturnClient
    FoundryClient --> ReturnClient
    FirstPartyClient --> ReturnClient
    
    ReturnClient --> End[供 claude.ts 使用]
    
    style Start fill:#e1f5ff
    style CheckAuth fill:#fff9c4
    style ReturnClient fill:#c8e6c9
    style End fill:#e1f5ff

核心配置参数：

• maxRetries：重试次数（默认由 withRetry 逻辑控制）
• timeout：请求超时时间（默认 600 秒，可通过 API_TIMEOUT_MS 配置）
• fetch：自定义 fetch 实现（用于测试和代理）
• fetchOptions：代理和 SSL 配置（通过 getProxyFetchOptions() 获取）

自定义 Headers 注入：

• 基础 Headers：x-app: cli、User-Agent、X-Claude-Code-Session-Id
• 容器标识：x-claude-remote-container-id（远程容器环境）
• 会话标识：x-claude-remote-session-id（远程会话环境）
• SDK 消费者：x-client-app（SDK 集成标识）
• 额外保护：x-anthropic-additional-protection（安全增强标志）
• 自定义 Headers：通过 ANTHROPIC_CUSTOM_HEADERS 环境变量注入

Sources: services/api/client.ts

代理与网络配置

系统通过 getProxyFetchOptions() 统一处理代理配置，支持 HTTP/HTTPS 代理、SSL 证书验证和自定义 CA 证书。

代理配置优先级：

1. ANTHROPIC_PROXY_URL 环境变量
2. HTTPS_PROXY / https_proxy 环境变量
3. HTTP_PROXY / http_proxy 环境变量
4. 系统代理设置（仅 macOS）

SSL 配置：

• NODE_TLS_REJECT_UNAUTHORIZED=0：禁用证书验证（仅用于测试）
• SSL_CERT_FILE / SSL_CERT_DIR：自定义 CA 证书路径
• REQUESTS_CA_BUNDLE：Python 兼容的 CA bundle 路径

Sources: services/api/client.ts

Claude API 服务

services/api/claude.ts 是与 Anthropic API 交互的核心模块，负责消息构建、流式处理、Beta 特性管理和成本追踪。该文件超过 3400 行代码，是整个代码库中最复杂的模块之一。

消息流式处理架构

Claude API 服务采用 Generator 模式处理流式响应，支持增量更新、错误恢复和中止控制。

sequenceDiagram
    participant QueryEngine as QueryEngine
    participant ClaudeAPI as Claude API 服务
    participant Client as Anthropic 客户端
    participant API as Anthropic API
    
    QueryEngine->>ClaudeAPI: streamCompletion()
    ClaudeAPI->>ClaudeAPI: 构建请求参数<br/>messages + tools + betas
    ClaudeAPI->>Client: client.beta.messages.stream()
    Client->>API: HTTP POST (streaming)
    
    loop 流式事件
        API->>Client: SSE 事件
        Client->>ClaudeAPI: yield BetaRawMessageStreamEvent
        ClaudeAPI->>ClaudeAPI: 处理事件类型
        
        alt message_start
            ClaudeAPI->>ClaudeAPI: 初始化消息对象
        else content_block_delta
            ClaudeAPI->>ClaudeAPI: 增量更新内容
        else message_delta
            ClaudeAPI->>ClaudeAPI: 更新 usage 统计
        else message_stop
            ClaudeAPI->>ClaudeAPI: 标记消息完成
        end
        
        ClaudeAPI->>QueryEngine: yield StreamEvent
    end
    
    ClaudeAPI->>ClaudeAPI: 提取限流 Headers
    ClaudeAPI->>ClaudeAPI: 计算请求成本
    ClaudeAPI->>QueryEngine: 返回完整 AssistantMessage
    
    rect rgb(255, 235, 238)
        Note over ClaudeAPI,API: 错误处理
        API->>Client: 4xx/5xx 错误
        Client->>ClaudeAPI: 抛出 APIError
        ClaudeAPI->>ClaudeAPI: 错误转换
        ClaudeAPI->>QueryEngine: yield SystemAPIErrorMessage
    end

流式事件类型：

type StreamEvent =
  | { type: 'content_block_delta'; delta: string; index: number }
  | { type: 'message_start'; message: BetaMessage }
  | { type: 'message_delta'; usage: BetaMessageDeltaUsage }
  | { type: 'message_stop' }
  | { type: 'error'; error: APIError }

Sources: services/api/claude.ts

请求参数构建

Claude API 服务需要处理复杂的请求参数，包括消息格式化、工具定义、Beta 特性和缓存控制。

核心参数结构：

interface BetaMessageStreamParams {
  model: string                           // 模型标识符
  messages: MessageParam[]                // 对话历史
  max_tokens: number                      // 最大输出 tokens
  system: SystemPrompt[]                  // 系统提示词数组
  tools?: BetaToolUnion[]                 // 工具定义
  tool_choice?: BetaToolChoiceAuto | BetaToolChoiceTool
  betas: string[]                         // Beta 特性标志
  metadata?: { user_id: string }          // 用户标识
  stream_options?: { prompt_cache_break: boolean }
  
  // 扩展参数（通过 extraBodyParams）
  anthropic_internal?: Record<string, unknown>  // 内部实验特性
}

Beta 特性管理：

• Prompt Caching：prompt-caching-2024-07-31（自动缓存系统提示和工具定义）
• Extended Thinking：max-tokens-3-5-sonnet-2024-07-15（支持深度思考模式）
• Structured Outputs：structured-outputs-2024-08-28（JSON Schema 约束输出）
• Tool Search：tool-search-2024-12-04（动态工具发现）
• Context Management：context-management-2025-01-01（上下文压缩）
• Fast Mode：fast-mode-2025-02-19（快速响应模式）
• Effort Control：effort-2025-02-28（计算投入控制）

Beta 合并逻辑：getMergedBetas() 函数合并模型默认 betas、全局 betas 和请求特定 betas，并通过 shouldIncludeFirstPartyOnlyBetas() 过滤掉第三方提供商不支持的特性。

Sources: services/api/claude.ts

Prompt Cache 优化

Prompt Caching 是降低成本和延迟的关键特性，Claude Code 实现了智能缓存策略，根据查询源和用户类型动态选择 TTL。

缓存策略决策树：

flowchart TD
    Start[请求到达] --> CheckEligibility{检查缓存资格}
    
    CheckEligibility -->|用户类型=ant| Use1Hour[使用 1 小时 TTL]
    CheckEligibility -->|Claude AI 订阅者| CheckOverage{是否使用超限额度?}
    CheckEligibility -->|其他用户| Use5Minutes[使用 5 分钟 TTL]
    
    CheckOverage -->|是| Use5Minutes
    CheckOverage -->|否| CheckAllowlist{查询源在白名单?}
    
    CheckAllowlist -->|是| Use1Hour
    CheckAllowlist -->|否| Use5Minutes
    
    Use1Hour --> SetCacheControl[设置 cache_control: {type: 'ephemeral', ttl: 1h}]
    Use5Minutes --> SetCacheControl5[设置 cache_control: {type: 'ephemeral'}]
    
    SetCacheControl --> AttachToMessage[附加到系统提示/工具/消息]
    SetCacheControl5 --> AttachToMessage
    
    AttachToMessage --> SendRequest[发送请求到 API]
    
    SendRequest --> DetectBreak{检测缓存断裂?}
    DetectBreak -->|是| InvalidateCache[清除客户端缓存]
    DetectBreak -->|否| UpdateMetrics[更新缓存命中率]
    
    style Use1Hour fill:#c8e6c9
    style Use5Minutes fill:#fff9c4
    style DetectBreak fill:#ffccbc

缓存断裂检测：checkResponseForCacheBreak() 监控 API 返回的 anthropic-ratelimit-cache-break header，如果检测到缓存断裂（例如组织 ID 变更），则清除本地缓存状态并重置会话。

Session Stability：缓存资格和允许列表在会话开始时锁定（latch），防止会话中途的配置变更导致缓存 TTL 混乱，这避免了每次 flip 浪费约 20K tokens 的服务器端缓存。

Sources: services/api/claude.ts

限流 Header 解析

API 响应包含丰富的限流信息，Claude Code 通过解析这些 headers 实现了实时状态监控和预警。

限流 Headers 映射表：

预警系统：getHeaderBasedEarlyWarning() 函数检测 surpassed-threshold header，当用户使用量超过预设阈值时触发早期警告，帮助用户提前规划使用。

Sources: services/claudeAiLimits.ts

限流管理系统

限流管理系统是 Claude AI 订阅用户的核心特性，实现了配额监控、超限额度管理和多窗口预警。系统通过解析 API 响应 headers 维护全局限流状态，并通过事件监听器通知 UI 层更新。

限流状态模型

interface ClaudeAILimits {
  status: QuotaStatus                      // 'allowed' | 'allowed_warning' | 'rejected'
  unifiedRateLimitFallbackAvailable: boolean  // 是否可回退到 Sonnet
  resetsAt?: number                        // 重置时间戳（秒）
  rateLimitType?: RateLimitType            // 限流类型
  utilization?: number                     // 使用率 (0-1)
  overageStatus?: QuotaStatus              // 超限额度状态
  overageResetsAt?: number                 // 超限额度重置时间
  overageDisabledReason?: OverageDisabledReason  // 超限额度禁用原因
  isUsingOverage?: boolean                 // 是否正在使用超限额度
  surpassedThreshold?: number              // 超过的阈值序号
}

限流类型：

• five_hour：5 小时会话限制（短窗口）
• seven_day：7 天周限制（标准窗口）
• seven_day_opus：7 天 Opus 专属限制（高成本模型）
• seven_day_sonnet：7 天 Sonnet 专属限制
• overage：超限额度限制（付费扩展）

Sources: services/claudeAiLimits.ts

预警配置

系统实现了时间相对预警策略，当用户使用配额的速度快于时间窗口进度时触发警告，避免在窗口末期耗尽配额。

预警配置表：

计算逻辑：computeTimeProgress() 函数计算当前时间在窗口中的进度，timePct = (now - windowStart) / windowSeconds，如果 utilization > threshold 且 timePct < threshold，则触发预警。

Sources: services/claudeAiLimits.ts

超限额度管理

超限额度是 Team/Enterprise 用户的付费扩展机制，允许在订阅配额耗尽后继续使用服务，系统会自动检测超限额度状态并切换。

超限额度禁用原因：

自动切换逻辑：当 status === 'rejected' 但 overageStatus === 'allowed' 时，系统自动设置 isUsingOverage = true，并在 UI 中显示超限额度使用提示。

Sources: services/claudeAiLimits.ts

限流消息生成

rateLimitMessages.ts 模块是限流相关消息的单一真实来源，根据限流状态生成用户友好的错误和警告消息。

消息类型：

type RateLimitMessage = {
  message: string
  severity: 'error' | 'warning'
}

消息生成逻辑：

1. 优先检查超限额度：如果 isUsingOverage === true 且 overageStatus === 'allowed_warning'，返回超限额度接近上限警告
2. 错误状态：如果 status === 'rejected'，返回配额耗尽错误消息
3. 警告状态：如果 status === 'allowed_warning' 且 utilization >= 0.7，返回早期预警消息
4. 过滤误报：如果 utilization < 0.7，忽略 allowed_warning 状态（避免周重置后的误报警告）
5. Team/Enterprise 特殊处理：如果用户启用了超限额度，不显示即将耗尽的警告（会自动切换）

错误消息前缀（用于 UI 组件识别）：

• "You've hit your"：配额耗尽
• "You've used"：使用量预警
• "You're now using extra usage"：切换到超限额度
• "You're close to"：接近上限
• "You're out of extra usage"：超限额度耗尽

Sources: services/rateLimitMessages.ts

错误处理与重试策略

withRetry.ts 实现了智能重试机制，根据错误类型、查询源和环境配置动态调整重试策略，平衡用户体验和系统负载。

重试分类体系

graph TB
    Error[API 错误] --> Transient{瞬态错误?}
    
    Transient -->|529 Overloaded| CapacityCheck{前台查询?}
    Transient -->|429 Rate Limit| RateLimitHandler[限流处理器]
    Transient -->|Connection Reset| ConnectionRetry[连接重试]
    Transient -->|Timeout| TimeoutRetry[超时重试]
    
    CapacityCheck -->|是| CapacityRetry[容量重试<br/>最多 3 次]
    CapacityCheck -->|否| FastFail[快速失败]
    
    RateLimitHandler --> CheckOverage{有超限额度?}
    CheckOverage -->|是| UseOverage[切换超限额度]
    CheckOverage -->|否| ShowError[显示错误消息]
    
    CapacityRetry --> Backoff[指数退避<br/>BASE_DELAY_MS × 2^attempt]
    ConnectionRetry --> Backoff
    TimeoutRetry --> Backoff
    
    Backoff --> Retry[重试请求]
    Retry --> Success{成功?}
    Success -->|是| Return[返回结果]
    Success -->|否| CheckMaxRetries{达到最大重试?}
    
    CheckMaxRetries -->|否| Backoff
    CheckMaxRetries -->|是| CannotRetry[抛出 CannotRetryError]
    
    FastFail --> CannotRetry
    ShowError --> CannotRetry
    UseOverage --> Retry
    
    style Error fill:#ffccbc
    style CapacityCheck fill:#fff9c4
    style Backoff fill:#c8e6c9
    style CannotRetry fill:#ef9a9a

前台查询源（允许 529 重试）：

• repl_main_thread：REPL 主线程交互
• sdk：SDK 调用
• agent:*：代理任务
• compact：上下文压缩
• hook_*：Hook 代理
• auto_mode：自动模式分类器
• bash_classifier：Bash 命令分类器（仅限 Ant 内部）

后台查询源（快速失败）：

• summary：会话摘要
• title：会话标题
• suggestion：建议生成
• classifier：非安全关键分类器

Sources: services/api/withRetry.ts

指数退避策略

重试机制使用指数退避加抖动算法，避免惊群效应并减少对过载服务的冲击。

退避公式：

delay = min(BASE_DELAY_MS × 2^attempt + random_jitter, max_backoff_ms)

参数配置：

• BASE_DELAY_MS = 500：基础延迟 500 毫秒
• DEFAULT_MAX_RETRIES = 10：默认最大重试 10 次
• MAX_529_RETRIES = 3：529 错误最多重试 3 次
• PERSISTENT_MAX_BACKOFF_MS = 300,000（5 分钟）：持久重试最大退避
• PERSISTENT_RESET_CAP_MS = 21,600,000（6 小时）：持久重试重置上限

持久重试模式（仅限 Ant 内部）：CLAUDE_CODE_UNATTENDED_RETRY=true 启用无限制重试，适用于无人值守的长期任务，每 30 秒发送心跳消息保持会话活跃。

Sources: services/api/withRetry.ts

错误类型与处理

errors.ts 模块定义了所有 API 错误类型及其处理逻辑，实现了错误分类、用户消息转换和自动恢复建议。

错误类型分类表：

Prompt Too Long 错误解析：

function parsePromptTooLongTokenCounts(rawMessage: string): {
  actualTokens: number | undefined
  limitTokens: number | undefined
}

使用正则表达式 /prompt is too long[^0-9]*(\d+)\s*tokens?\s*>\s*(\d+)/i 提取实际 token 数和限制，帮助用户理解超限程度。

Sources: services/api/errors.ts

错误恢复策略

系统为每种错误类型实现了自动恢复策略，尽量减少用户干预。

自动恢复流程：

1. 401 Unauthorized：

   • 清除 OAuth token 缓存
   • 清除 API key helper 缓存
   • 清除 AWS/GCP 凭证缓存
   • 尝试刷新 OAuth token
   • 如果刷新失败，提示 /login

2. 429 Rate Limit：

   • 解析限流 headers
   • 检查超限额度可用性
   • 如果有超限额度，自动切换
   • 如果 Opus 受限，建议回退到 Sonnet
   • 显示剩余时间和使用率

3. 529 Overloaded：

   • 判断查询源是否为前台
   • 如果是前台，执行指数退避重试（最多 3 次）
   • 如果是后台，快速失败以避免级联过载
   • 记录重试日志用于容量规划

4. Connection Errors：

   • 检测错误类型（ECONNRESET、EPIPE、ETIMEDOUT）
   • 如果是瞬态错误，重试
   • 如果是代理问题，尝试直连
   • 如果持续失败，禁用 keep-alive

Sources: services/api/withRetry.ts

相关页面

• 整体架构：从 CLI 入口到 QueryEngine：了解 API 服务层在整体架构中的位置
• 查询引擎：QueryEngine 对话生命周期管理：API 服务的调用者
• 配置管理：settings、环境变量与迁移系统：认证和环境配置
• 日志系统：诊断追踪与错误处理：错误日志和诊断
• MCP 服务：服务器连接、资源管理与协议实现：另一种 API 集成方式