# CC-Switch API 转换层详细分析报告

## 1. 项目概述

**CC-Switch** 是一个基于 **Tauri (Rust 后端 + Web 前端)** 的桌面应用，用于管理多个大模型编程工具（Claude Code、Codex CLI、Gemini CLI 等）的配置切换。其核心功能之一是**本地 HTTP 代理服务器**，在客户端与上游 LLM API 之间充当协议翻译层，使仅支持特定 API 格式的客户端（如 Claude Code 只支持 Anthropic Messages API）能通过代理访问不同协议的后端服务。

### 核心能力

- 将 **Anthropic Messages API** 请求/响应转换为 **OpenAI Chat Completions**、**OpenAI Responses API**、**Google Gemini Native** 等格式
- 支持**流式 (SSE)** 和**非流式**两种模式的实时协议翻译
- 内置故障转移、熔断器、Thinking 自修复、Copilot 请求优化等企业级特性
- 支持 GitHub Copilot、ChatGPT Plus/Pro (Codex OAuth) 等动态 Token 认证的供应商

### 与同类项目的核心差异

CC-Switch 是唯一的**桌面端**代理工具（非服务端部署），面向个人开发者场景。其协议转换是**单方向锚定**的——以 Anthropic Messages API 为唯一"客户端协议"，向多种上游协议转换。相比 One-API / New-API 的多协议互转、LiteLLM 的 OpenAI-centric 统一格式，CC-Switch 的转换矩阵更聚焦但深度更大（如 Gemini Shadow Store、Copilot Optimizer 等属于独有的复杂机制）。

---

## 2. 技术架构总览

```
┌─────────────────────────────────────────────────────────────────┐
│                    CC-Switch Tauri 桌面应用                       │
├─────────────────────────────────────────────────────────────────┤
│  Web 前端 (React)  │          Rust 后端 (Tauri)                  │
│                    │  ┌──────────────────────────────────────┐   │
│  - 供应商管理      │  │       proxy/ 模块 (Axum HTTP Server)  │   │
│  - 配置切换        │  │                                      │   │
│  - 用量展示        │  │  ┌──────────┐   ┌────────────────┐   │   │
│                    │  │  │ server.rs│──▶│  handlers.rs   │   │   │
│                    │  │  │ (路由层)  │   │  (请求分发器)   │   │   │
│                    │  │  └──────────┘   └───────┬────────┘   │   │
│                    │  │                         │             │   │
│                    │  │  ┌──────────────────────▼─────────┐   │   │
│                    │  │  │       forwarder.rs (转发器)      │   │   │
│                    │  │  │  - 供应商选择 / 故障转移         │   │   │
│                    │  │  │  - 请求体预处理 / 参数过滤       │   │   │
│                    │  │  │  - Thinking 自修复 / Copilot优化  │   │   │
│                    │  │  └──────────────┬─────────────────┘   │   │
│                    │  │                 │                     │   │
│                    │  │  ┌──────────────▼─────────────────┐   │   │
│                    │  │  │     providers/ (适配器层)        │   │   │
│                    │  │  │                                 │   │   │
│                    │  │  │  ┌─────────┐  ┌──────────────┐  │   │   │
│                    │  │  │  │adapter.rs│  │   claude.rs  │  │   │   │
│                    │  │  │  │(Trait定义)│  │ (Claude适配器)│  │   │   │
│                    │  │  │  └─────────┘  ├──────────────┤  │   │   │
│                    │  │  │               │   codex.rs    │  │   │   │
│                    │  │  │               ├──────────────┤  │   │   │
│                    │  │  │               │   gemini.rs   │  │   │   │
│                    │  │  │               └──────────────┘  │   │   │
│                    │  │  └─────────────────────────────────┘   │   │
│                    │  │                                        │   │
│                    │  │  ┌─────────────────────────────────┐   │   │
│                    │  │  │   转换层 (transform/ 模块)        │   │   │
│                    │  │  │                                 │   │   │
│                    │  │  │  transform.rs         (→Chat)   │   │   │
│                    │  │  │  transform_responses.rs (→Resp)  │   │   │
│                    │  │  │  transform_gemini.rs    (→Gemini)│   │   │
│                    │  │  └─────────────────────────────────┘   │   │
│                    │  │                                        │   │
│                    │  │  ┌─────────────────────────────────┐   │   │
│                    │  │  │   流式转换层 (streaming/ 模块)     │   │   │
│                    │  │  │                                 │   │   │
│                    │  │  │  streaming.rs          (Chat)   │   │   │
│                    │  │  │  streaming_responses.rs (Resp)   │   │   │
│                    │  │  │  streaming_gemini.rs    (Gemini) │   │   │
│                    │  │  └─────────────────────────────────┘   │   │
│                    │  │                                        │   │
│                    │  │  ┌─────────────────────────────────┐   │   │
│                    │  │  │   辅助模块                        │   │   │
│                    │  │  │  gemini_shadow.rs  (状态回放)     │   │   │
│                    │  │  │  gemini_schema.rs  (Schema转换)   │   │   │
│                    │  │  │  copilot_optimizer.rs (Copilot优化)│   │   │
│                    │  │  │  thinking_rectifier.rs (Thinking修复)│   │
│                    │  │  │  thinking_budget_rectifier.rs     │   │   │
│                    │  │  │  cache_injector.rs (缓存注入)     │   │   │
│                    │  │  │  body_filter.rs   (私有参数过滤)   │   │   │
│                    │  │  │  model_mapper.rs  (模型名映射)     │   │   │
│                    │  │  │  gemini_url.rs    (Gemini URL构建)│   │   │
│                    │  │  └─────────────────────────────────┘   │   │
│                    │  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

**源文件规模**：`proxy/` 目录共 53 个源文件，其中核心转换层 6 个文件合计约 7,700 行，辅助模块 7 个文件合计约 4,000 行，转发器和处理器合计约 3,700 行。

---

## 3. 路由层 (server.rs)

**文件**: `src-tauri/src/proxy/server.rs` (354 行)

代理服务器基于 **Axum** 框架构建，使用手动 hyper HTTP/1.1 accept loop（通过 TCP `peek()` 捕获原始请求头大小写，存入 `OriginalHeaderCases` 扩展供转发器使用）。

### 路由表

| 路由路径 | 处理器 | 协议 |
|---------|--------|------|
| `/v1/messages`, `/claude/v1/messages` | `handle_messages` | Claude (Anthropic Messages API) |
| `/chat/completions`, `/v1/chat/completions`, `/v1/v1/chat/completions`, `/codex/v1/chat/completions` | `handle_chat_completions` | OpenAI Chat Completions |
| `/responses`, `/v1/responses`, `/v1/v1/responses`, `/codex/v1/responses` | `handle_responses` | OpenAI Responses API |
| `/responses/compact`, `/v1/responses/compact`, `/v1/v1/responses/compact`, `/codex/v1/responses/compact` | `handle_responses_compact` | Responses Compact (Codex CLI 远程压缩透传) |
| `/v1beta/*path`, `/gemini/v1beta/*path` | `handle_gemini` | Gemini (Google AI API) |
| `/health` | `health_check` | 健康检查 |
| `/status` | `get_status` | 状态查询 |

**关键设计细节**:
- **多前缀兼容**: 裸路径 (`/v1/...`) 和带供应商前缀 (`/claude/`, `/codex/`, `/gemini/`) 均支持，兼容不同客户端的 `base_url` 配置
- **双前缀容错**: `/v1/v1/...` 路由处理客户端双重前缀的配置错误
- **无前缀路由**: `/chat/completions` 和 `/responses` 不带 `/v1/`，适配 Codex CLI 的特定 base_url 配置
- **请求体限制**: `DefaultBodyLimit::max(200MB)`，支撑大体积上下文和图片请求

---

## 4. 适配器层 (Adapter Pattern)

### 4.1 ProviderAdapter Trait

**文件**: `src-tauri/src/proxy/providers/adapter.rs` (50 行)

所有供应商适配器都实现统一的 `ProviderAdapter` trait：

```rust
pub trait ProviderAdapter: Send + Sync {
    fn name(&self) -> &'static str;
    fn extract_base_url(&self, provider: &Provider) -> Result<String, ProxyError>;
    fn extract_auth(&self, provider: &Provider) -> Option<AuthInfo>;
    fn build_url(&self, base_url: &str, endpoint: &str) -> String;
    fn get_auth_headers(&self, auth: &AuthInfo) -> Vec<(HeaderName, HeaderValue)>;
    fn needs_transform(&self, _provider: &Provider) -> bool;         // 默认 false
    fn transform_request(&self, body: Value, provider: &Provider) -> Result<Value, ProxyError>;  // 默认透传
    fn transform_response(&self, body: Value) -> Result<Value, ProxyError>;  // 默认透传
}
```

其中 `needs_transform()`、`transform_request()`、`transform_response()` 提供默认实现（透传），供应商适配器仅需覆写需要的方法。

### 4.2 供应商类型枚举 (ProviderType)

**文件**: `src-tauri/src/proxy/providers/mod.rs` (515 行)

系统定义 8 种供应商类型，决定认证和请求处理逻辑：

| ProviderType | 说明 | 认证策略 | 是否需要转换 |
|---|---|---|---|
| `Claude` | Anthropic 官方 API | Anthropic (`x-api-key`) | 视 api_format 决定 |
| `ClaudeAuth` | Claude 中转服务 (仅 Bearer) | ClaudeAuth | 视 api_format 决定 |
| `Codex` | OpenAI Codex | Bearer | 否 |
| `Gemini` | Google Gemini API (API Key) | Google (`x-goog-api-key`) | 否 |
| `GeminiCli` | Gemini CLI (OAuth) | GoogleOAuth | 否 |
| `OpenRouter` | OpenRouter 中转 | Bearer | 否 (已支持原生) |
| `GitHubCopilot` | GitHub Copilot | GitHubCopilot (动态 Token) | **是** → OpenAI Chat/Responses |
| `CodexOAuth` | ChatGPT Plus/Pro 反代 | CodexOAuth (动态 Token) | **是** → OpenAI Responses |

**适配器工厂** `get_adapter_for_provider_type()` 的映射逻辑：
- `Claude`, `ClaudeAuth`, `OpenRouter`, `GitHubCopilot`, `CodexOAuth` → `ClaudeAdapter`
- `Codex` → `CodexAdapter`
- `Gemini`, `GeminiCli` → `GeminiAdapter`

### 4.3 API 格式识别

**文件**: `src-tauri/src/proxy/providers/claude.rs` (1313 行)

Claude 适配器通过 `get_claude_api_format()` 函数识别需要使用的 API 格式，优先级为：

1. **Codex OAuth 强制**: `meta.provider_type == "codex_oauth"` → `openai_responses`
2. **meta.apiFormat (SSOT)**: `meta.api_format` 字段 → `openai_chat` / `openai_responses` / `gemini_native`
3. **settings_config.api_format**: 旧版兼容
4. **openrouter_compat_mode**: 旧版 OpenRouter 兼容开关 → `openai_chat`
5. **默认**: `anthropic` (直接透传)

### 4.4 认证策略

**文件**: `src-tauri/src/proxy/providers/auth.rs` (259 行)

7 种认证策略覆盖所有上游服务：

| 策略 | Header 注入 |
|------|-----------|
| `Anthropic` | `x-api-key: <key>` + `anthropic-version: 2023-06-01` (版本由转发器注入) |
| `ClaudeAuth` | `Authorization: Bearer <key>` (无 `x-api-key`) |
| `Bearer` | `Authorization: Bearer <key>` |
| `Google` | `x-goog-api-key: <key>` |
| `GoogleOAuth` | `Authorization: Bearer <token>` + `x-goog-client: GeminiCLI/1.0` |
| `GitHubCopilot` | `Authorization: Bearer <token>` + 多个 Copilot 专有 Header (`openai-intent`, `x-initiator`, `x-interaction-type`, `x-request-id`, `x-agent-task-id` 等约 10 个) |
| `CodexOAuth` | `Authorization: Bearer <token>` + `originator: cc-switch` + `chatgpt-account-id` |

**动态认证机制**: GitHub Copilot 和 Codex OAuth 的 Token 是动态获取的，通过 `CopilotAuthManager` 和 `CodexOAuthAuth` 分别管理 Token 的刷新和多账户绑定（通过 `meta.authBinding` 实现供应商到账户的映射）。

---

## 5. 转换层详解 — 核心协议转换

### 5.1 Anthropic ↔ OpenAI Chat Completions

**文件**: `src-tauri/src/proxy/providers/transform.rs` (1193 行)

#### 请求转换: `anthropic_to_openai(body) → Value`

将 Anthropic Messages API 请求转换为 OpenAI Chat Completions 请求。

**字段映射**:

| Anthropic 字段 | OpenAI 字段 | 说明 |
|---|---|---|
| `system` (string) | `messages[0].role = "system"` | System prompt 提升为 system role message |
| `system` (array) | `messages[0].role = "system"` (合并) | 多个 system message 合并，冲突的 `cache_control` 被丢弃 |
| `messages` | `messages` | 按角色转换内容格式 |
| `max_tokens` | `max_tokens` / `max_completion_tokens` | o-series 模型使用 `max_completion_tokens` |
| `temperature` | `temperature` | 直接透传 |
| `top_p` | `top_p` | 直接透传 |
| `stop_sequences` | `stop` | 直接透传 |
| `tools[].input_schema` | `tools[].function.parameters` | Schema 格式转换，过滤 `BatchTool`，移除 `format: "uri"` |
| `tool_choice` | `tool_choice` | 直接透传 |
| `thinking` + `output_config.effort` | `reasoning_effort` | 仅对支持推理的模型注入 (o-series, GPT-5+) |

**消息内容转换**:
- `text` → `{type: "text", text: "..."}`
- `image` → `{type: "image_url", image_url: {url: "data:...;base64,..."}}` (data URI)
- `tool_use` → `tool_calls[{id, type: "function", function: {name, arguments}}]`
- `tool_result` → `{role: "tool", tool_call_id: "...", content: "..."}` (独立 tool role 消息)
- `thinking` → 丢弃

**推理强度 (reasoning_effort) 映射规则**:

| Anthropic thinking 配置 | OpenAI reasoning_effort |
|---|---|
| `type: "adaptive"` | `"xhigh"` |
| `type: "enabled"` + budget < 4000 | `"low"` |
| `type: "enabled"` + budget 4000-15999 | `"medium"` |
| `type: "enabled"` + budget >= 16000 | `"high"` |
| `type: "enabled"` + 无 budget | `"high"` |
| `output_config.effort: "max"` | `"xhigh"` |

**特殊处理**:
- 多个 system message 自动合并，冲突的 `cache_control` 被丢弃
- 支持 `cache_control` 在 system message、text block、tool 上的透传
- `clean_schema()` 清理 JSON Schema 中 OpenAI 不支持的 `format: "uri"` 等字段

#### 响应转换: `openai_to_anthropic(body) → Value`

| OpenAI 字段 | Anthropic 字段 |
|---|---|
| `choices[0].message.content` | `content[{type: "text"}]` |
| `choices[0].message.tool_calls` | `content[{type: "tool_use", id, name, input}]` |
| `choices[0].message.function_call` | `content[{type: "tool_use"}]` (旧格式兼容) |
| `choices[0].message.refusal` | `content[{type: "text", text: refusal}]` |
| `choices[0].finish_reason` | `stop_reason` (stop→end_turn, length→max_tokens, tool_calls→tool_use) |
| `usage.prompt_tokens` | `usage.input_tokens` |
| `usage.completion_tokens` | `usage.output_tokens` |
| `usage.prompt_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` |

---

### 5.2 Anthropic ↔ OpenAI Responses API

**文件**: `src-tauri/src/proxy/providers/transform_responses.rs` (1329 行)

Responses API 是 OpenAI 2025 年推出的新一代 API，采用扁平化的 input/output 结构。

#### 请求转换: `anthropic_to_responses(body, cache_key, is_codex_oauth) → Value`

| Anthropic 字段 | Responses API 字段 | 说明 |
|---|---|---|
| `system` | `instructions` | System prompt 转为 instructions 字段 |
| `messages` | `input` | 消息数组转为扁平化的 input items |
| `max_tokens` | `max_output_tokens` | 统一使用 max_output_tokens |
| `tools[].input_schema` | `tools[].parameters` | Schema 格式转换，移除 `cache_control` |
| `tool_choice.type = "any"` | `tool_choice = "required"` | 映射工具选择策略 |
| `tool_choice.type = "tool"` | `tool_choice = {type: "function", name}` | 强制指定工具 |
| `thinking` | `reasoning.effort` | 推理强度映射 |

**消息结构转换核心差异** — 消息从"嵌套在 role message 中"变为"独立 top-level item"：
- `tool_use` 从 assistant message 中**提升**为独立的 `function_call` item:
  ```json
  // Anthropic
  {"role": "assistant", "content": [{"type": "tool_use", "id": "call_1", ...}]}
  // Responses API
  {"type": "function_call", "call_id": "call_1", ...}
  ```
- `tool_result` 从 user message 中**提升**为独立的 `function_call_output` item:
  ```json
  // Anthropic
  {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_1", ...}]}
  // Responses API
  {"type": "function_call_output", "call_id": "call_1", ...}
  ```
- 文本类型区分: user 的 text → `input_text`, assistant 的 text → `output_text`

**Codex OAuth (ChatGPT Plus/Pro 反代) 特殊协议约束**:

当 `is_codex_oauth = true` 时，需满足 ChatGPT 后端的协议限制：
- `store: false` — 不允许服务端持久化
- `include: ["reasoning.encrypted_content"]` — 保持多轮 reasoning 上下文（ChatGPT 后端通过加密 reasoning blob 维持推理状态）
- 删除 `max_output_tokens`、`temperature`、`top_p` (ChatGPT 后端不支持这些参数)
- 兜底注入 `instructions`("")、`tools`([])、`parallel_tool_calls`(false) 默认值
- 强制 `stream: true` (CC-Switch SSE 解析层只支持流式)

#### 响应转换: `responses_to_anthropic(body) → Value`

| Responses API 字段 | Anthropic 字段 |
|---|---|
| `output[type="message"].content[type="output_text"]` | `content[{type: "text"}]` |
| `output[type="function_call"]` | `content[{type: "tool_use", id: call_id, name, input}]` |
| `output[type="reasoning"].summary` | `content[{type: "thinking", thinking: ...}]` |
| `output[type="message"].content[type="refusal"]` | `content[{type: "text"}]` |
| `status = "completed"` (无 tool_use) | `stop_reason: "end_turn"` |
| `status = "completed"` (有 function_call) | `stop_reason: "tool_use"` |
| `status = "incomplete"` (reason: max_output_tokens) | `stop_reason: "max_tokens"` |
| `usage.input_tokens` | `usage.input_tokens` |
| `usage.input_tokens_details.cached_tokens` | `usage.cache_read_input_tokens` |

---

### 5.3 Anthropic ↔ Google Gemini Native

**文件**: `src-tauri/src/proxy/providers/transform_gemini.rs` (2152 行)

将 Anthropic Messages 请求转换为 Gemini `generateContent` 格式。这是三个转换中最复杂的，涉及有状态管理。

#### 请求转换: `anthropic_to_gemini_with_shadow(body, shadow_store, provider_id, session_id) → Value`

| Anthropic 字段 | Gemini 字段 | 说明 |
|---|---|---|
| `system` | `systemInstruction.parts[{text}]` | System prompt 转为 systemInstruction |
| `messages` | `contents[{role, parts}]` | role: assistant→model, 其他→user |
| `max_tokens` | `generationConfig.maxOutputTokens` | |
| `temperature` | `generationConfig.temperature` | |
| `top_p` | `generationConfig.topP` | |
| `stop_sequences` | `generationConfig.stopSequences` | |
| `tools[].input_schema` | `tools[].functionDeclarations[]` | 转为 Gemini FunctionDeclaration |
| `tool_choice` | `toolConfig.functionCallingConfig` | auto→AUTO, none→NONE, any→ANY, tool→ANY+allowedFunctionNames |

**消息内容转换**:
- `text` → `{text: "..."}`
- `image` (base64) → `{inlineData: {mimeType, data}}`
- `document` (base64) → `{inlineData: {mimeType, data}}`
- `tool_use` → `{functionCall: {name, args, id}}` (仅 assistant)
- `tool_result` → `{functionResponse: {name, response, id}}` (通过 id→name 映射解析)
- `thinking` / `redacted_thinking` → 丢弃

#### Shadow Store (状态回放机制)

**文件**: `src-tauri/src/proxy/providers/gemini_shadow.rs` (389 行)

Gemini 的 `thoughtSignature` 和 `functionCall.id` 是有状态的，需要跨轮次保留。CC-Switch 实现了 `GeminiShadowStore` 来解决此问题：

- **存储结构**: 以 `(provider_id, session_id)` 为键，存储 `GeminiAssistantTurn`（包含 assistant_content + tool_calls 及 thoughtSignature）
- **容量限制**: 默认 200 个 session，每 session 64 轮对话，超出后 LRU 淘汰最旧 session
- **回放机制**: 在后续请求中，将存储的 shadow turn（包含 thoughtSignature 和原始 Gemini 格式内容）替换到对应 assistant 消息的位置，确保多轮对话的 `functionResponse` 和 `thoughtSignature` 能正确传递
- **线程安全**: 使用 `std::sync::RwLock`（非 tokio async lock），因为 shadow store 操作很快

#### 工具参数修正 (Tool Call Rectification)

Gemini 模型有时会将工具调用的参数结构"展平"或混淆（如将 `{skill: "git-commit"}` 发为 `{name: "git-commit"}`）。系统通过 `AnthropicToolSchemaHints` 机制：
1. 从请求中的 `tools[].input_schema` 提取预期参数结构
2. 在响应中检测并修正参数名映射 (如 `name` → `skill`)
3. 处理 `parameters` 嵌套展平问题
4. 通过 `rectify_tool_call_parts()` 实现类型强制转换（如 string `"123"` → integer `123`）

#### 合成 ID 机制

Gemini 2.x 并行调用常省略 `functionCall.id`。系统处理：
- `synthesize_tool_call_id()` 生成 `gemini_synth_<uuid>` 格式的合成 ID，在 Anthropic 侧使用
- **不会**转发回 Gemini（在构建 Gemini 请求时被过滤）
- 流式场景支持 "synth → real id upgrade"：当后续 chunk 携带真实 ID 时替换合成 ID

#### Gemini Schema 构建

**文件**: `src-tauri/src/proxy/providers/gemini_schema.rs` (338 行)

工具定义的 Schema 转换使用双通道策略：
- **`parameters` 通道**: 使用受限的 Gemini Schema 格式（去掉 `$ref`, `$defs`, `additionalProperties`, `oneOf`, `allOf`, `const`, `not`, `if/then/else` 等不支持的关键字）
- **`parametersJsonSchema` 通道**: 使用完整 JSON Schema 格式（当 Schema 包含 Gemini 不支持的关键字时自动升级）
- `build_gemini_function_parameters()` 自动根据 Schema 复杂度选择通道

#### 响应转换: `gemini_to_anthropic_with_shadow_and_hints(body, ...) → Value`

| Gemini 字段 | Anthropic 字段 |
|---|---|
| `candidates[0].content.parts[{text}]` | `content[{type: "text"}]` |
| `candidates[0].content.parts[{functionCall}]` | `content[{type: "tool_use", id, name, input}]` |
| `candidates[0].content.parts[{thought: true}]` | 丢弃 (Gemini thinking) |
| `candidates[0].finishReason = "STOP"` | `stop_reason: "end_turn"` / `"tool_use"` |
| `candidates[0].finishReason = "MAX_TOKENS"` | `stop_reason: "max_tokens"` |
| `candidates[0].finishReason = "SAFETY"` 等 | `stop_reason: "refusal"` |
| `promptFeedback.blockReason` | `stop_reason: "refusal"` + 错误文本 |
| `usageMetadata.promptTokenCount` | `usage.input_tokens` |
| `usageMetadata.cachedContentTokenCount` | `usage.cache_read_input_tokens` |

---

## 6. 流式转换层

### 6.1 OpenAI Chat Completions SSE → Anthropic SSE

**文件**: `src-tauri/src/proxy/providers/streaming.rs` (821 行)

**转换状态机**:

```
OpenAI SSE chunk ──▶ 状态解析 ──▶ Anthropic SSE event
                                    │
    choices[0].delta.content ──────▶ content_block_start (type: "text")
                                    content_block_delta (type: "text_delta")
                                    content_block_stop
                                    
    choices[0].delta.reasoning ────▶ content_block_start (type: "thinking")
                                    content_block_delta (type: "thinking_delta")
                                    content_block_stop
                                    
    choices[0].delta.tool_calls ───▶ content_block_start (type: "tool_use")
                                    content_block_delta (type: "input_json_delta")
                                    content_block_stop
                                    
    choices[0].finish_reason ──────▶ message_delta (stop_reason)
    [DONE] ───────────────────────▶ message_stop
```

**特殊处理**:
- **UTF-8 安全**: 处理 TCP 分包导致的 UTF-8 多字节字符截断，使用 `utf8_remainder` 缓冲区确保不会产生 U+FFFD 替换字符
- **Copilot 无限空白 Bug 检测**: 跟踪连续空白字符数，超过 20 个时强制中止 tool call 流（Copilot 有时会无限输出空白字符的已知 Bug）
- **延迟工具调用**: 处理 `id/name` 在 `arguments` 之后到达的乱序情况

### 6.2 OpenAI Responses API SSE → Anthropic SSE

**文件**: `src-tauri/src/proxy/providers/streaming_responses.rs` (1070 行)

Responses API 使用**命名事件** (named events) 的生命周期模型，与 Chat Completions 的 delta chunk 模型完全不同。

**事件映射**:

| Responses API SSE Event | Anthropic SSE Event |
|---|---|
| `response.created` | `message_start` |
| `response.content_part.added` (output_text) | `content_block_start(type:text)` |
| `response.output_text.delta` | `content_block_delta(text_delta)` |
| `response.refusal.delta` | `content_block_delta(text_delta)` |
| `response.output_text.done` | `content_block_stop` |
| `response.output_item.added` (function_call) | `content_block_start(type:tool_use)` |
| `response.function_call_arguments.delta` | `content_block_delta(input_json_delta)` |
| `response.function_call_arguments.done` | `content_block_stop` |
| `response.reasoning.delta` | `content_block_start(type:thinking)` + `content_block_delta(thinking_delta)` |
| `response.reasoning.done` | `content_block_stop` |
| `response.completed` | `message_delta` (stop_reason + usage) + `message_stop` |

**状态管理**: 维护 `content_part_key` (item_id + content_index 复合键)、`index_by_key` (content part → Anthropic index 映射)、`tool_index_by_item_id` (item_id → index 映射)、`open_indices` (未关闭的 block 索引集合)。

### 6.3 Gemini SSE → Anthropic SSE

**文件**: `src-tauri/src/proxy/providers/streaming_gemini.rs` (1054 行)

Gemini 的 `streamGenerateContent?alt=sse` 每个 chunk 都是完整的 `GenerateContentResponse`，需要增量合并。

**核心机制**:
- **累积快照模型**: 每个 SSE chunk 包含完整的 candidates，系统通过比较 `functionCall.name` 和位置匹配来去重和合并跨 chunk 的工具调用
- **工具调用 ID 去重合并**: `merge_tool_call_snapshots()` 处理跨 chunk 的工具调用累积（支持合成 ID → 真实 ID 升级）
- **Shadow Store 记录**: 在流结束时记录 assistant turn 到 shadow store（包括 `thoughtSignature`）
- **Tool Call Rectification**: 流式场景下同样应用工具参数修正
- **thoughtSignature 提取**: 从 text parts 中提取 `thoughtSignature` 用于后续回放

---

## 7. 请求处理流程

### 7.1 主处理链

以 Claude Code → CC-Switch → 上游 API 为例的完整流程：

```
Claude Code 发送 Anthropic Messages API 请求
         │
         ▼
[server.rs] 路由匹配 → /v1/messages → handle_messages()
         │
         ▼
[handlers.rs] handle_messages():
  1. 解析请求体
  2. 创建 RequestContext (识别 AppType::Claude, 提取 session_id)
  3. 调用 forwarder.forward_with_retry()
         │
         ▼
[forwarder.rs] RequestForwarder.forward_with_retry():
  遍历供应商列表（故障转移队列）:
  1. 检查熔断器状态
  2. forward() 内部处理:
     a. get_adapter(AppType::Claude) → ClaudeAdapter
     b. 提取 base_url，应用 model_mapper 映射模型名
     c. 规范化 thinking 类型
     d. 确定端点路径（Copilot 动态端点 / 格式化重写）
     e. Copilot Optimizer: 分类请求、清理孤立 tool_result、合并 tool_result、热身降级、确定性 ID
     f. 解析 API 格式: get_claude_api_format()
     g. 如需转换: transform_claude_request_for_api_format()
        - openai_chat → anthropic_to_openai()
        - openai_responses → anthropic_to_responses()
        - gemini_native → anthropic_to_gemini_with_shadow()
     h. body_filter: 过滤 `_` 前缀的私有参数
     i. 获取动态认证 Token (Copilot/CodexOAuth)
     j. 构建有序 HeaderMap
     k. 发送请求 (hyper for HTTP/CONNECT proxy, reqwest for SOCKS5 proxy)
  3. 成功: 记录结果、更新状态、触发 UI 切换
  4. 失败: 检查 thinking_rectifier / thinking_budget_rectifier，各自最多触发一次修复后重试
         │
         ▼
[handlers.rs] 响应处理:
  if needs_transform:
    流式: 根据格式选择:
      - openai_responses → create_anthropic_sse_stream_from_responses()
      - gemini_native → create_anthropic_sse_stream_from_gemini()
      - 其他 → create_anthropic_sse_stream()
    非流式: 读取完整响应，应用:
      - responses_to_anthropic()
      - gemini_to_anthropic_with_shadow_and_hints()
      - openai_to_anthropic()
  else:
    透传响应
```

### 7.2 Copilot Optimizer

**文件**: `src-tauri/src/proxy/copilot_optimizer.rs` (1251 行)

专用于 GitHub Copilot 的请求优化系统，在转发器内部对请求进行预处理：

| 优化策略 | 说明 |
|---------|------|
| **请求分类** | 识别 initiator (user/agent)、热身请求、压缩请求、子代理请求 |
| **孤立 tool_result 清理** | 清理无对应 tool_use 的 tool_result（Claude Code 偶尔产生） |
| **tool_result 合并** | 将多个 tool_result 合并为一个，减少 Copilot 高级计费 |
| **热身降级** | 检测到热身请求时降级为小模型，节省成本 |
| **确定性请求 ID** | 基于 session 生成确定性 `x-request-id` 和 `x-interaction-id`，提高 Copilot 稳定性 |
| **子代理头修改** | 子代理请求时修改 `x-initiator`、`x-interaction-type` 为 agent |

### 7.3 Thinking 自修复机制

**文件**: `src-tauri/src/proxy/thinking_rectifier.rs` (609 行), `thinking_budget_rectifier.rs` (307 行)

两个独立的自修复 rectifier，在 Anthropic API 返回特定错误时自动修复并重试：

| Rectifier | 触发条件 | 修复动作 | 触发次数限制 |
|-----------|---------|---------|------------|
| **Signature Rectifier** | Anthropic API 报告 thinking signature 无效 | 移除 `thinking`/`redacted_thinking` blocks 和 `signature` 字段 | 每请求 1 次 |
| **Budget Rectifier** | Anthropic API 报告 thinking budget 错误 | 调整 `thinking.budget_tokens` | 每请求 1 次 |

修复后通过 `release_permit_neutral()` 释放熔断器的 HalfOpen 探测槽位，不影响健康统计。

### 7.4 其他辅助机制

| 模块 | 文件 | 行数 | 说明 |
|------|------|------|------|
| **私有参数过滤** | `body_filter.rs` | 261 | 过滤 `_` 前缀的参数，允许客户端传递控制参数而不发送到上游 |
| **缓存注入** | `cache_injector.rs` | 329 | 为 Bedrock 等支持 prompt 缓存的供应商注入缓存控制标记 |
| **Thinking 优化** | `thinking_optimizer.rs` | 230 | Bedrock 场景下的 thinking 参数优化 |
| **模型名映射** | `model_mapper.rs` | 312 | 将客户端请求的模型名映射为上游实际模型名 |
| **Gemini URL** | `gemini_url.rs` | 583 | 处理 Gemini API 的复杂 URL 构建逻辑 |
| **SSE 基础** | `sse.rs` | 294 | SSE 事件解析和生成的基础工具 |

---

## 8. 熔断器与故障转移

### 8.1 熔断器

**文件**: `src-tauri/src/proxy/circuit_breaker.rs` (482 行)

三态熔断器保护上游服务：

| 参数 | 默认值 |
|------|-------|
| `failure_threshold` | 4 (连续失败次数) |
| `success_threshold` | 2 (连续成功次数) |
| `timeout_seconds` | 60 (Open 状态持续时间) |
| `error_rate_threshold` | 0.6 (错误率阈值) |
| `min_requests` | 10 (最小请求数) |

**状态转换**: Closed (正常) → Open (熔断) → HalfOpen (探测，最多 1 个并发探测请求) → Closed/Open

### 8.2 供应商路由

**文件**: `src-tauri/src/proxy/provider_router.rs` (512 行)

- 故障转移关闭时：仅使用当前供应商
- 故障转移开启时：返回按优先级排列的故障转移队列，跳过熔断中的供应商

---

## 9. 支持的协议转换矩阵

```
                    ┌──────────────────────────────────────────────┐
                    │              CC-Switch 代理                    │
                    │                                              │
                    │  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
 Claude Code ──────▶│  │ Claude   │  │ Codex    │  │ Gemini   │   │
 (Anthropic        │  │ Handler  │  │ Handler  │  │ Handler  │   │
  Messages API)    │  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
                    │       │             │              │         │
                    │  ┌────▼─────────────▼──────────────▼─────┐  │
                    │  │          Forwarder (转发器)              │  │
                    │  │  - 供应商选择 / 故障转移 / Copilot优化   │  │
                    │  │  - Thinking自修复 / 参数过滤             │  │
                    │  └────────────────┬───────────────────────┘  │
                    │                   │                          │
                    │       ┌───────────┼───────────┐              │
                    │       ▼           ▼           ▼              │
                    │  ┌─────────┐ ┌─────────┐ ┌──────────┐      │
                    │  │OpenAI   │ │OpenAI   │ │  Gemini  │      │
                    │  │Chat     │ │Responses│ │  Native  │      │
                    │  │Complet. │ │API      │ │          │      │
                    │  └────┬────┘ └────┬────┘ └────┬─────┘      │
                    │       │           │           │             │
                    └───────┼───────────┼───────────┼─────────────┘
                            ▼           ▼           ▼
                    ┌───────────┐ ┌──────────┐ ┌──────────────┐
                    │OpenAI/    │ │ChatGPT/  │ │ Google AI    │
                    │OpenRouter/│ │OpenAI/   │ │ Gemini API   │
                    │Copilot    │ │Codex OAuth│ │              │
                    └───────────┘ └──────────┘ └──────────────┘
```

### 转换路径汇总

| 转换路径 | 请求转换 | 响应转换 | 流式转换 | 使用场景 |
|---------|---------|---------|---------|---------|
| Anthropic → OpenAI Chat | `anthropic_to_openai()` | `openai_to_anthropic()` | `streaming.rs` | GitHub Copilot, OpenRouter (旧版) |
| Anthropic → OpenAI Responses | `anthropic_to_responses()` | `responses_to_anthropic()` | `streaming_responses.rs` | Codex OAuth (ChatGPT Plus/Pro) |
| Anthropic → Gemini | `anthropic_to_gemini_with_shadow()` | `gemini_to_anthropic_with_shadow_and_hints()` | `streaming_gemini.rs` | Gemini 模型直连 |
| Anthropic → Anthropic (透传) | 直接转发 | 直接转发 | 直接转发 | Anthropic 官方, OpenRouter (新版) |

---

## 10. 文件索引

### 核心转换文件

| 文件路径 | 功能 | 代码行数 |
|---------|------|---------|
| `src-tauri/src/proxy/providers/transform.rs` | Anthropic ↔ OpenAI Chat Completions 转换 | 1193 |
| `src-tauri/src/proxy/providers/transform_responses.rs` | Anthropic ↔ OpenAI Responses API 转换 | 1329 |
| `src-tauri/src/proxy/providers/transform_gemini.rs` | Anthropic ↔ Gemini Native 转换 | 2152 |
| `src-tauri/src/proxy/providers/streaming.rs` | OpenAI Chat SSE → Anthropic SSE 流式转换 | 821 |
| `src-tauri/src/proxy/providers/streaming_responses.rs` | Responses SSE → Anthropic SSE 流式转换 | 1070 |
| `src-tauri/src/proxy/providers/streaming_gemini.rs` | Gemini SSE → Anthropic SSE 流式转换 | 1054 |

### 适配器与认证

| 文件路径 | 功能 | 代码行数 |
|---------|------|---------|
| `src-tauri/src/proxy/providers/adapter.rs` | ProviderAdapter trait 定义 | 50 |
| `src-tauri/src/proxy/providers/auth.rs` | AuthInfo / AuthStrategy 认证类型定义 | 259 |
| `src-tauri/src/proxy/providers/claude.rs` | Claude 适配器 (API 格式检测, URL 构建, 认证) | 1313 |
| `src-tauri/src/proxy/providers/codex.rs` | Codex 适配器 | 305 |
| `src-tauri/src/proxy/providers/gemini.rs` | Gemini 适配器 | 442 |
| `src-tauri/src/proxy/providers/mod.rs` | ProviderType 枚举, get_adapter() 工厂函数 | 515 |
| `src-tauri/src/proxy/providers/copilot_auth.rs` | Copilot 动态 Token 管理 | 1820 |
| `src-tauri/src/proxy/providers/codex_oauth_auth.rs` | Codex OAuth 动态 Token 管理 | 1132 |
| `src-tauri/src/proxy/providers/gemini_shadow.rs` | Gemini Shadow Store (状态回放) | 389 |
| `src-tauri/src/proxy/providers/gemini_schema.rs` | Gemini Schema 构建 (双通道策略) | 338 |

### 请求处理链

| 文件路径 | 功能 | 代码行数 |
|---------|------|---------|
| `src-tauri/src/proxy/server.rs` | Axum HTTP 服务器, 路由注册 | 354 |
| `src-tauri/src/proxy/handlers.rs` | 请求处理器 (分发 + Claude 格式转换入口) | 643 |
| `src-tauri/src/proxy/forwarder.rs` | 请求转发器 (供应商选择, 故障转移, 请求预处理) | 2169 |
| `src-tauri/src/proxy/copilot_optimizer.rs` | Copilot 请求优化 | 1251 |
| `src-tauri/src/proxy/thinking_rectifier.rs` | Thinking Signature 自修复 | 609 |
| `src-tauri/src/proxy/thinking_budget_rectifier.rs` | Thinking Budget 自修复 | 307 |
| `src-tauri/src/proxy/thinking_optimizer.rs` | Bedrock Thinking 优化 | 230 |
| `src-tauri/src/proxy/cache_injector.rs` | Prompt 缓存注入 | 329 |
| `src-tauri/src/proxy/body_filter.rs` | 私有参数过滤 (`_` 前缀) | 261 |
| `src-tauri/src/proxy/model_mapper.rs` | 模型名映射 | 312 |
| `src-tauri/src/proxy/gemini_url.rs` | Gemini URL 构建 | 583 |
| `src-tauri/src/proxy/sse.rs` | SSE 基础工具 | 294 |
| `src-tauri/src/proxy/provider_router.rs` | 供应商路由 (故障转移队列) | 512 |
| `src-tauri/src/proxy/circuit_breaker.rs` | 熔断器实现 | 482 |
| `src-tauri/src/proxy/handler_context.rs` | RequestContext 构建 | 246 |
| `src-tauri/src/proxy/response_processor.rs` | 响应处理 (透传/日志/usage) | 915 |
| `src-tauri/src/proxy/session.rs` | 会话管理 | 565 |
| `src-tauri/src/proxy/hyper_client.rs` | Hyper HTTP 客户端 | 626 |
| `src-tauri/src/proxy/http_client.rs` | Reqwest HTTP 客户端 (SOCKS5) | 392 |
| `src-tauri/src/proxy/error.rs` | 错误类型定义 | 177 |
| `src-tauri/src/proxy/error_mapper.rs` | 错误映射 | 99 |

---

## 11. 关键设计特点

### 11.1 单方向锚定转换

所有转换以 Anthropic Messages API 为锚点，仅实现 Anthropic ↔ X 的双向转换。客户端协议只有一种（Anthropic Messages API），上游协议有三种（OpenAI Chat、OpenAI Responses、Gemini Native）加一种透传（Anthropic 直连）。

### 11.2 流式 + 非流式双轨支持

每种协议转换都同时实现了非流式 (JSON-to-JSON) 和流式 (SSE 事件逐事件翻译，基于 `async_stream` 异步流)。

### 11.3 有状态转换 (Gemini Shadow Store)

Gemini 的 `thoughtSignature` 是有状态的，系统通过 Shadow Store 在内存中记录每轮 assistant 的原始 Gemini 响应，在后续请求中回放。这是 CC-Switch 独有的复杂机制。

### 11.4 自修复能力 (Thinking Rectifiers)

两个独立 rectifier 在 API 错误时自动修复请求并重试，大幅提高了对 Anthropic API thinking 功能变更的容错能力。

### 11.5 Copilot 深度适配

Copilot Optimizer 针对性地解决了 Copilot 的多个实际问题（无限空白 Bug、请求不稳定、高级计费优化等），是与供应商深度绑定的典型案例。

### 11.6 请求头大小写保留

通过手动 hyper accept loop + TCP `peek()` 捕获原始请求头大小写，转发给上游时保持一致（部分上游 API 对 header 大小写敏感）。

### 11.7 代理协议支持

支持 HTTP/CONNECT 和 SOCKS5 两种代理协议，分别使用 hyper 和 reqwest 客户端。

### 11.8 UTF-8 安全

流式转换中处理 TCP 分包导致的 UTF-8 多字节字符截断，使用 `utf8_remainder` 缓冲区确保不会产生 U+FFFD 替换字符。