CC Switch 调用链与实现边界

调研对象：https://github.com/farion1231/cc-switch

核心判断：CC Switch 的价值在于把 Claude Code、Codex、Gemini CLI 的模型调用入口接到本地代理，再由本地代理决定真实上游。

一句话：

它不是配置编辑器，而是本地模型请求网关。

它解决什么问题

更准确地说，Claude Code、Codex、Gemini CLI 是客户端入口，不是模型边界。它们默认读取自己的配置、鉴权和协议入口；如果不接管，用户想让这些 CLI 使用官方模型之外的社区中转、OpenAI-compatible 或其他兼容格式服务，就要分别修改 JSON、TOML、.env、base_url、token 和模型名。

README 里的“50+ 供应商预设”“通用供应商”“本地代理热切换”说的就是这件事：把固定客户端入口变成可切换的 Provider 入口。真实上游不必是客户端默认绑定的官方模型，只要能被适配成 Anthropic、OpenAI Chat/Responses 或 Gemini Native 这类格式，就可以接进来。

CC Switch 的做法更直接：

继续使用原来的 CLI
-> 改写 CLI 会读取的 live config
-> 让请求先进入 127.0.0.1:<cc-switch-port>
-> CC Switch 决定真实 Provider、模型和协议

它不改变用户工作台，只改变模型请求路径。

完整调用链

用户在 Claude Code / Codex / Gemini CLI 发起请求
  -> 客户端读取自己的 live config
  -> base_url 已被改成 CC Switch 本地代理
  -> 本地代理按 path 识别协议和客户端类型
  -> 读取当前 Provider 配置
  -> 做模型名映射
  -> 必要时做协议转换
  -> 注入真实 API Key
  -> 请求真实上游模型服务
  -> 将响应转换回客户端期望格式
  -> 记录 usage、cost、latency、error

核心伪代码：

handle(request):
  app = detect_by_path(request.path)
  provider = load_current_provider(app)
  upstream_request = transform(request, provider.api_format)
  upstream_request.headers = inject_auth(provider.api_key)
  upstream_response = forward(upstream_request, provider.base_url)
  return transform_back(upstream_response, app)

三类配置

CC Switch 不是只有“原来接什么、现在接什么”两份配置，而是三类状态。

原始配置

Claude Code / Codex 原本的配置。主要用于备份、恢复和迁移，不是运行时路由的核心。

live config 投影

写给外部客户端看的配置。接管后通常变成：

base_url = http://127.0.0.1:<cc-switch-port>
api_key  = PROXY_MANAGED

它只负责把客户端请求导到本地代理。

Provider 配置

CC Switch 内部真正使用的出站配置：

provider.base_url
provider.api_key
provider.api_format
model_mapping
failover_queue

真实上游是谁，由这一层决定。

请求进入后怎么处理

本地代理主要按路径识别协议：

/v1/messages              -> Anthropic Messages，Claude 类请求
/v1/chat/completions      -> OpenAI Chat Completions
/v1/responses             -> OpenAI Responses，Codex 主路径
/v1/responses/compact     -> Codex compact
/v1/models                -> 模型列表或连通性检查
/v1beta/*, /gemini/v1*    -> Gemini Native

进入代理后，主流程很常规：

• 识别客户端和入站协议。
• 找到当前启用的 Provider。
• 将客户端请求模型映射到上游模型。
• 按 Provider 的 api_format 转换请求。
• 重建 header，注入真实 key。
• 发往上游。
• 把上游响应转回客户端可读格式。
• 记录用量和错误。

协议转换难点

协议转换不是这个项目的原创点，但它是主要工程成本。

• 消息结构不等价：Anthropic 的 content blocks、OpenAI 的 messages、Responses 的 input/output、Gemini 的 contents/parts 不能纯字段替换。
• Tool call 容易断：tool_call_id、function result、并发工具调用需要保持映射，否则下一轮无法对齐。
• Streaming 是事件转换：Anthropic、OpenAI Chat、Responses、Gemini 的 SSE 事件顺序和字段不同。
• Reasoning 字段不统一：thinking、reasoning、reasoning_content、thoughtSignature 的展示和回传规则不同。
• Usage 口径不统一：各家 token、cache、streaming usage 的返回方式不同，成本统计只能做兼容归一。

所以它不是“没有难点”，而是没有理论难点，难在协议兼容矩阵。

PROXY_MANAGED

接管后，真实 key 不再写在 Claude Code / Codex 的配置里。但客户端配置通常仍需要一个 key 字段，否则可能本地校验失败。

PROXY_MANAGED 是占位 key：

客户端看到：有 key，可以继续请求本地代理
CC Switch 看到：这是占位符，不拿它请求上游
真实上游看到：代理注入 Provider 的真实 key

这不是高级设计，只是必要的兼容和密钥边界处理。

Provider 切换

切换 Provider 时，理想路径不是再改客户端 endpoint。

Claude Code / Codex -> 127.0.0.1:<cc-switch-port> -> Provider A
切换后
Claude Code / Codex -> 127.0.0.1:<cc-switch-port> -> Provider B

客户端入口保持本地代理不变，真实上游在 CC Switch 内部变化。这样后续请求可以无感切换；已经开始的 streaming 请求不应被理解为能中途无缝换模型。

故障转移和用量记录

这部分也是常规网关能力，但落地时要处理边界：

• 5xx、超时可以 retry 或 failover。
• 4xx 通常不应污染 Provider 健康度。
• streaming 已经吐出内容后，不能随意重试，否则可能重复输出。
• usage 有时在 JSON 响应里，有时在 SSE 尾部，有时上游不给。
• cost 和 latency 要按最终实际使用的 Provider 记录。

实现难点与脆弱点

• 依赖外部客户端的 live config 结构。Claude Code / Codex 改配置格式，接管逻辑就要跟着改。
• Provider 越多，协议 adapter 和回归矩阵越大。
• Tool call、streaming、reasoning、usage 是最容易出兼容问题的四类能力。
• 排障链路变长：失败可能来自客户端配置、本地代理、协议转换、Provider、网络或真实上游。
• 它提升的是可控性，不是上游质量。坏 Provider 仍然坏，只是能被绕开、记录和熔断。

借鉴价值

值得学的是完整调用链，而不是把常规网关能力包装成新概念。

• 客户端入口是否能被稳定接管？
• 原始配置、live config、Provider 配置是否分清？
• 真实 key 是否只留在控制面内部？
• 请求是否始终经过代理，以便统计、failover 和转换？
• 协议转换是否从最窄链路开始，而不是一开始做全协议互转？
• streaming 失败后是否有明确处理策略？
• usage 不完整时是否有 fallback 和标注？

最值得保留的判断：

CC Switch 的价值不是“设计很新”，而是把常规代理、配置接管、协议转换、密钥隔离和用量记录拼成了一个可用的本地 AI CLI 控制面。

GitHub 参考

• 项目 README：https://github.com/farion1231/cc-switch/blob/main/README_ZH.md
• 代理接管与 live config 写入：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/services/proxy.rs
• 本地代理路由：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/server.rs#L291-L360
• Claude 请求处理：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/handlers.rs#L186-L246
• Provider 选择与故障转移：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/forwarder.rs#L393-L521
• 模型映射与协议转换入口：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/forwarder.rs#L1093-L1381
• 鉴权替换与 Header 重建：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/forwarder.rs#L1415-L1810
• Claude API 格式识别：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/providers/claude.rs
• Anthropic 到 OpenAI 转换：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/providers/transform.rs#L114-L220
• 响应与 usage 处理：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/proxy/response_processor.rs#L284-L383
• SQLite 状态表：https://github.com/farion1231/cc-switch/blob/main/src-tauri/src/database/schema.rs#L24-L137