06.1 API、模型与流式调用

关注源码

  • src/services/api/claude.ts
  • src/services/api/*
  • src/utils/model/model.ts

services/api 负责的不是单次 HTTP 请求

它要把运行时状态翻译为稳定的模型请求，涉及：

  • provider 选择
  • model alias 解析
  • betas/header/body 参数
  • prompt cache 相关 header
  • streaming 事件规范化
  • 错误与重试
  • usage/cost/telemetry

claude.ts 在做什么

这个文件会综合考虑：

  • 当前模型
  • provider
  • tools schema
  • system prompt
  • thinking config
  • task budget
  • prompt cache 策略
  • fast mode / effort / advisor / context management betas

然后发起 streaming request，并把结果重新映射成内部消息流。

为什么模型选择属于平台层

utils/model/model.ts 展示出模型选择不是简单 settings 读取，而是综合：

  • 订阅类型
  • provider
  • 1m context 可用性
  • 用户 override
  • plan mode 特判

因此模型选择实际上属于平台策略的一部分。

API 层和运行时层的分工

运行时层决定：

  • 本轮消息和工具是什么
  • 是否要继续、压缩、恢复

API 层决定：

  • 如何把这些内容编码成 provider 可接受的请求
  • 如何解释 provider 返回的 streaming 事件和 usage

这让 query loop 不需要了解太多具体 API 协议细节。

设计上的关键点

1. prompt cache 是 API 层一等约束

header、工具顺序、thinking 配置、context management 都会影响缓存命中，因此 API 层有大量 cache-aware 逻辑。

2. provider 适配被压在平台层

上层运行时尽量只关心“模型能力”，而不是第一方、Bedrock、Vertex 等差异。

3. streaming 事件是统一出口

无论底层 API 怎么流式返回，上层看到的都是统一 StreamEvent / message 语义。