API 客户端

概述

Claude Code 的 API 客户端负责将对话消息发送到 Claude API 并处理流式响应。核心实现在 services/api/claude.ts 中。

Source: src/services/api/claude.ts

核心函数

queryModelWithStreaming()

Source: src/services/api/claude.ts:753-781

这是主查询循环 (query.ts) 调用的 API 函数：

export async function* queryModelWithStreaming({
  messages,
  systemPrompt,
  thinkingConfig,
  tools,
  signal,
  options,
}: {
  messages: Message[]
  systemPrompt: SystemPrompt
  thinkingConfig: ThinkingConfig
  tools: Tools
  signal: AbortSignal
  options: Options
}): AsyncGenerator<
  StreamEvent | AssistantMessage | SystemAPIErrorMessage,
  void
> {
  return yield* withStreamingVCR(messages, async function* () {
    yield* queryModel(messages, systemPrompt, thinkingConfig, tools, signal, options);
  });
}

关键点：

• Generator 函数 — 逐步产出流式事件
• VCR 包装 — withStreamingVCR() 用于测试录制/回放
• 委托给 queryModel() — 实际的 API 调用逻辑

queryModel() — 内部实现

构建请求参数并调用 Anthropic SDK：

请求参数构建

API 请求包含以下核心字段：

字段	来源	说明
model	options.model	模型 ID (如 claude-sonnet-4-20250514)
system	systemPrompt	系统提示词数组
messages	messages	对话历史
tools	tools	工具定义列表
max_tokens	计算得出	最大输出 token 数
stream	true	始终使用流式传输
betas	根据功能	启用的 Beta 功能

流式事件类型

API 返回的 BetaRawMessageStreamEvent 包含多种事件类型：

事件类型	说明
message_start	消息开始
content_block_start	内容块开始（文本/工具调用）
content_block_delta	内容块增量更新
content_block_stop	内容块结束
message_delta	消息级别更新（stop_reason 等）
message_stop	消息结束

executeNonStreamingRequest()

Source: src/services/api/claude.ts:819-917

非流式请求函数，用于降级场景和辅助查询（如 autocompact、classifier）：

export async function* executeNonStreamingRequest(
  clientOptions,
  retryOptions,
  paramsFromContext,
  onAttempt,
  captureRequest,
): AsyncGenerator<SystemAPIErrorMessage, BetaMessage>

重试与降级

withRetry 机制

API 调用内置重试逻辑：

模型降级

当主模型失败时，可以降级到 fallbackModel：

// query.ts 中的降级处理
catch (error) {
  if (error instanceof FallbackTriggeredError) {
    // 切换到降级模型
    // 清除孤立消息和工具结果
    // 使用新模型重试
  }
}

下一步

• 多供应商支持 — Anthropic、Bedrock、Vertex、Azure 的适配
• 流式响应处理 — 流式事件的处理链路