服务层全景

// services/api/client.ts:88-316
export async function getAnthropicClient({...}): Promise<Anthropic> {
  if (isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK)) {
    const { AnthropicBedrock } = await import('@anthropic-ai/bedrock-sdk')
    return new AnthropicBedrock(bedrockArgs)
  }
  if (isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX)) {
    const { AnthropicVertex } = await import('@anthropic-ai/vertex-sdk')
    return new AnthropicVertex(vertexArgs)
  }
  return new Anthropic(defaultArgs) // 原生 SDK
}

// services/api/withRetry.ts — 核心重试循环
async function* withRetry(fn, options) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const stream = await fn(retryContext)
      for await (const event of stream) {
        // 处理流式事件，yield 中间状态
      }
      return finalMessage
    } catch (error) {
      if (!shouldRetry(error)) throw new CannotRetryError(...)
      yield systemMessage  // 通知上层"正在重试"
      await delay(getRetryDelay(attempt))
      retryContext = adjustForRetry(error) // 调整参数
    }
  }
}

// services/api/promptCacheBreakDetection.ts:247
export function recordPromptState(snapshot: PromptStateSnapshot): void {
  // 记录: system hash, tool hash, model, betas
  const prev = previousStates.get(trackingKey)
  if (prev && prev.systemHash !== newSystemHash) {
    // 检测到 system prompt 变化 → 记录 diff
    pendingChanges.system = { prev, curr: snapshot }
  }
}

// L437 — 响应验证
export async function checkResponseForCacheBreak(...) {
  if (cacheReadTokens === 0 && shouldHaveCached) {
    // 缓存断裂！生成 diff 并上报
    await writeCacheBreakDiff(prevContent, newContent)
  }
}

// 多租户 API 客户端工厂 — 借鉴 CC 的 5 后端自动检测
function getLLMClient(tenant: Tenant): LLMClient {
  const config = tenant.llmConfig

  switch (config.provider) {
    case "openai":
      return createOpenAIClient({ apiKey: config.apiKey, model: config.model })

    case "anthropic":
      return createAnthropicClient({ apiKey: config.apiKey })

    case "azure":
      return createAzureClient({
        endpoint: config.azureEndpoint,
        deploymentName: config.deploymentName,
        apiKey: config.apiKey
      })

    case "local":
      // 租户自建模型 — Ollama/vLLM 等
      return createLocalClient({ baseUrl: config.localEndpoint })

    default:
      // 默认用平台提供的 LLM
      return createPlatformClient()
  }
}

// 透明切换 — 调用方不感知后端差异
async function queryAgent(tenant: Tenant, messages: Message[]) {
  const client = getLLMClient(tenant)  // 根据租户自动选后端
  return client.chat({ messages, tools: getToolsForTenant(tenant) })
}

// Fail-open 服务编排 — 借鉴 CC 的 failOpen<T> 包装器
async function failOpen<T>(
  fn: () => Promise<T>,
  fallback: T,
  context: string
): Promise<T> {
  try {
    return await fn()
  } catch (error) {
    logger.warn(`${context} failed, using fallback`, { error: error.message })
    return fallback
  }
}

// 客服服务编排 — 核心 + 辅助分离
async function handleCustomerQuery(tenant: Tenant, query: string) {
  // 核心服务：直接 await，失败就报错
  const intent = await analyzeIntent(getLLMClient(tenant), query)
  const knowledge = await queryKnowledgeBase(tenant.kbConfig, intent)

  // 辅助服务：fail-open 包装，失败不影响核心流程
  const translatedQuery = await failOpen(
    () => translate(query, "zh", "en"),     // 翻译服务
    query,                                   // 失败就用原文
    "translation service"
  )

  const speechText = await failOpen(
    () => speechToText(queryAudioBuffer),    // 语音转文字
    "[语音转文字服务不可用]",
    "speech-to-text service"
  )

  // 组装结果返回给坐席面板
  return { intent, knowledge, translatedQuery, speechText }
}

// 成本追踪 — 借鉴 CC 的 telemetry.track() 模式
class TenantCostTracker {
  private costs = new Map<string, TenantCost>()  // tenantId → 成本

  // 每次 LLM 调用后记录 — fail-open 包装，不影响主流程
  recordUsage(tenantId: string, usage: {
    provider: string
    model: string
    inputTokens: number
    outputTokens: number
    latencyMs: number
  }) {
    const cost = this.calculateCost(usage.provider, usage.model, usage)
    const current = this.costs.get(tenantId) ?? { totalCost: 0, calls: 0 }
    this.costs.set(tenantId, {
      totalCost: current.totalCost + cost,
      calls: current.calls + 1
    })
  }

  // 按租户出账单
  getBilling(tenantId: string, period: string): BillingReport {
    return { tenantId, period, ...this.costs.get(tenantId) }
  }
}

// 服务健康检查 + 降级策略
class ServiceHealthMonitor {
  private health = new Map<string, "healthy"|"degraded"|"down">()

  async checkAll() {
    // 核心服务：down 时返回错误，坐席面板显示"系统维护中"
    this.health.set("llm", await this.checkEndpoint(config.llmEndpoint))
    this.health.set("order_system", await this.checkEndpoint(config.orderEndpoint))

    // 辅助服务：down 时标记为 degraded，不影响整体状态
    this.health.set("translation", await this.checkEndpoint(config.translateEndpoint))
  }

  getStatus(): ServiceStatus {
    const coreDown = ["llm","order_system"].some(k => this.health.get(k) === "down")
    return coreDown ? "down" : "healthy"   // 只看核心服务
  }
}