coding-proxy 0.2.4a3__tar.gz → 0.2.4a5__tar.gz

{coding_proxy-0.2.4a3 → coding_proxy-0.2.4a5}/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 ## [Unreleased]
 
+- fix(request-normalizer): 重设计 zhipu→anthropic 跨供应商 tool_use/tool_result 配对修复——以单遍自包含 `enforce_anthropic_tool_pairing` 替代原有多步串联管线（剥离→重定位→孤儿修复），消除步骤间隐式依赖导致的孤儿 tool_use 漏修问题，彻底根治 `tool_use ids were found without tool_result blocks` 400 异常;
+- refactor(vendor-channels): 将供应商转换通道从「目标 vendor 专属」重构为「源→目标绑定」模型——注册表键从 `target_vendor` 改为 `(source, target)` 二元组，通道函数从 `prepare_for_X` 重命名为 `prepare_X_to_Y`，触发逻辑从 `_needs_vendor_channel` 替换为 `_determine_source_vendor`（基于请求内 `failed_tier_name` 和会话历史推断源 vendor），未注册的转换对（如 anthropic→zhipu）不触发任何通道;
+- feat(vendor-channels): 新增 zhipu→anthropic、zhipu→copilot、copilot→zhipu 三条源→目标绑定转换通道，在跨供应商故障转移时自动清理源 vendor 产物（thinking 块、cache_control 字段、thinking 参数、tool_use/tool_result 配对），消除 `likely format incompatibility (400 + tool_results)` 错误;
+
 ## [v0.2.3](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.2.3) — 2026-04-16
 
 - feat(dashboard): 新增实时 Web Dashboard 页面，聚合展示流量与用量统计;

{coding_proxy-0.2.4a3 → coding_proxy-0.2.4a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-proxy
-Version: 0.2.4a3
+Version: 0.2.4a5
 Summary: A High-Availability, Transparent, and Smart Multi-Vendor Proxy for Claude Code. Support Claude Plans, GitHub Copilot, Google Antigravity, ZAI/GLM, MiniMax, Qwen, Xiaomi, Kimi, Doubao...
 Project-URL: Source Code, https://github.com/ThreeFish-AI/coding-proxy
 Project-URL: User Guide, https://github.com/ThreeFish-AI/coding-proxy/blob/master/docs/user-guide.md
@@ -60,10 +60,10 @@ When you're deeply immersed in your coding "zone" with **Claude Code** (or any A
     <img src="assets/dashboard-v0.2.3.png">
 </div>
 
-- **⛓️ N-tier Chained Failover**: Autonomous descending sequence, supporting Claude's official plans, as well as Coding Plans from GitHub Copilot, Z AI, MiniMax, Alibaba Qwen, Xiaomi, Kimi, Doubao, etc.
+- **⛓️ N-tier Chained Failover**: Autonomous descending sequence, supporting Claude's official plans, as well as Coding Plans from GitHub Copilot, Google Antigravity, Z AI, MiniMax, Alibaba Qwen, Xiaomi, Kimi, Doubao, etc.
 - **🛡️ Smart Resilience & Quota Guardians**: Every single vendor node comes fully armed with an independent **Circuit Breaker** and **Quota Guard** to proactively dodge avalanches without breaking a sweat.
 - **👻 Phantom-like Transparency**: **100% transparent** to the client! No code tweaks required. Overwrite `ANTHROPIC_BASE_URL` with a single line, and you're good to go.
-- **🔄 Universal Alchemy (Formats & Models)**: Native support for two-way request/streaming (SSE) translations between Anthropic ←→ Gemini. Plus, auto/DIY model name mapping (e.g., effortlessly morphing `claude-*` into `glm-*`).
+- **🔄 Universal Alchemy (Formats & Models)**: Native support for two-way request/streaming (SSE) translations between Anthropic ←→ Gemini and Anthropic ←→ OpenAI. Plus, auto/DIY model name mapping (e.g., effortlessly morphing `claude-*` into `glm-*`).
 - **📊 Extreme Observability**: Built-in, zero-BS local monitoring powered by a `SQLite WAL`. The CLI provides a one-click detailed Token usage dashboard (`coding-proxy usage`).
 - **⚡ Featherweight Standalone Deployment**: A fully asynchronous architecture (`FastAPI` + `httpx`). Zero dependency on Redis, message queues, or other heavy machinery—absolutely no extra baggage for your dev rig.
 
@@ -122,6 +122,7 @@ claude
 | Command  | Description                                                                                                                                        | Example Usage                                 |
 | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
 | `start`  | **Fire up the proxy server.** Supports custom ports and configuration paths.                                                                       | `coding-proxy start -p 8080 -c ~/config.yaml` |
+| `auth`   | **Manage OAuth credentials.** Sub-commands: `login` (browser OAuth), `status` (token validity), `reauth` (re-authenticate), `logout` (clear tokens). | `coding-proxy auth login -p github`           |
 | `status` | **Check proxy health.** Shows circuit breaker states (OPEN/CLOSED) and quota status across all tiers.                                              | `coding-proxy status`                         |
 | `usage`  | **Token Stats Dashboard.** Stalks every single token consumed, failovers triggered, and latency across day/vendor/model dimensions.                | `coding-proxy usage -d 7 -v anthropic`        |
 | `reset`  | **The emergency flush button.** Force-reset all circuit breakers and quotas instantly when you've confirmed the main vendor is back from the dead. | `coding-proxy reset`                          |
@@ -153,29 +154,29 @@ graph RL
         subgraph NTier["N-tier"]
             direction TB
 
-            subgraph Tier0 ["Tier 0: Anthropic"]
+            subgraph Tier0 ["Tier 0: Zhipu"]
                 direction RL
-                G0{"CB / Quota"}:::gateway -- "✅ Pass" --> API0(("Anthropic API")):::api
+                G0{"CB / Quota"}:::gateway -- "✅ Pass" --> API0(("GLM API")):::api
             end
 
-            subgraph Tier1 ["Tier 1: GitHub Copilot"]
+            subgraph Tier1 ["Tier 1: Anthropic"]
                 direction RL
-                G1{"CB / Quota"}:::gateway -- "✅ Pass" --> API1(("Copilot API")):::api
+                G1{"CB / Quota"}:::gateway -- "✅ Pass" --> API1(("Anthropic API")):::api
             end
 
-            subgraph Tier2 ["Tier 2: Google Antigravity"]
+            subgraph Tier2 ["Tier 2: GitHub Copilot"]
                 direction RL
-                G2{"CB / Quota"}:::gateway -- "✅ Pass" --> API2(("Gemini API")):::api
+                G2{"CB / Quota"}:::gateway -- "✅ Pass" --> API2(("Copilot API")):::api
             end
 
-            subgraph TierN ["Tier N: Zhipu"]
+            subgraph Tier3 ["Tier 3: Google Antigravity"]
                 direction RL
-                APIN(("GLM API")):::fallback
+                API3(("Gemini API")):::fallback
             end
 
             Tier0 -. "❌ Blocked / API Error" .-> Tier1
             Tier1 -. "❌ Blocked / API Error" .-> Tier2
-            Tier2 -. "🆘 Safety Net Downgrade" .-> TierN
+            Tier2 -. "🆘 Safety Net Downgrade" .-> Tier3
         end
 
     end

{coding_proxy-0.2.4a3 → coding_proxy-0.2.4a5}/README.md

@@ -33,10 +33,10 @@ When you're deeply immersed in your coding "zone" with **Claude Code** (or any A
     <img src="assets/dashboard-v0.2.3.png">
 </div>
 
-- **⛓️ N-tier Chained Failover**: Autonomous descending sequence, supporting Claude's official plans, as well as Coding Plans from GitHub Copilot, Z AI, MiniMax, Alibaba Qwen, Xiaomi, Kimi, Doubao, etc.
+- **⛓️ N-tier Chained Failover**: Autonomous descending sequence, supporting Claude's official plans, as well as Coding Plans from GitHub Copilot, Google Antigravity, Z AI, MiniMax, Alibaba Qwen, Xiaomi, Kimi, Doubao, etc.
 - **🛡️ Smart Resilience & Quota Guardians**: Every single vendor node comes fully armed with an independent **Circuit Breaker** and **Quota Guard** to proactively dodge avalanches without breaking a sweat.
 - **👻 Phantom-like Transparency**: **100% transparent** to the client! No code tweaks required. Overwrite `ANTHROPIC_BASE_URL` with a single line, and you're good to go.
-- **🔄 Universal Alchemy (Formats & Models)**: Native support for two-way request/streaming (SSE) translations between Anthropic ←→ Gemini. Plus, auto/DIY model name mapping (e.g., effortlessly morphing `claude-*` into `glm-*`).
+- **🔄 Universal Alchemy (Formats & Models)**: Native support for two-way request/streaming (SSE) translations between Anthropic ←→ Gemini and Anthropic ←→ OpenAI. Plus, auto/DIY model name mapping (e.g., effortlessly morphing `claude-*` into `glm-*`).
 - **📊 Extreme Observability**: Built-in, zero-BS local monitoring powered by a `SQLite WAL`. The CLI provides a one-click detailed Token usage dashboard (`coding-proxy usage`).
 - **⚡ Featherweight Standalone Deployment**: A fully asynchronous architecture (`FastAPI` + `httpx`). Zero dependency on Redis, message queues, or other heavy machinery—absolutely no extra baggage for your dev rig.
 
@@ -95,6 +95,7 @@ claude
 | Command  | Description                                                                                                                                        | Example Usage                                 |
 | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
 | `start`  | **Fire up the proxy server.** Supports custom ports and configuration paths.                                                                       | `coding-proxy start -p 8080 -c ~/config.yaml` |
+| `auth`   | **Manage OAuth credentials.** Sub-commands: `login` (browser OAuth), `status` (token validity), `reauth` (re-authenticate), `logout` (clear tokens). | `coding-proxy auth login -p github`           |
 | `status` | **Check proxy health.** Shows circuit breaker states (OPEN/CLOSED) and quota status across all tiers.                                              | `coding-proxy status`                         |
 | `usage`  | **Token Stats Dashboard.** Stalks every single token consumed, failovers triggered, and latency across day/vendor/model dimensions.                | `coding-proxy usage -d 7 -v anthropic`        |
 | `reset`  | **The emergency flush button.** Force-reset all circuit breakers and quotas instantly when you've confirmed the main vendor is back from the dead. | `coding-proxy reset`                          |
@@ -126,29 +127,29 @@ graph RL
         subgraph NTier["N-tier"]
             direction TB
 
-            subgraph Tier0 ["Tier 0: Anthropic"]
+            subgraph Tier0 ["Tier 0: Zhipu"]
                 direction RL
-                G0{"CB / Quota"}:::gateway -- "✅ Pass" --> API0(("Anthropic API")):::api
+                G0{"CB / Quota"}:::gateway -- "✅ Pass" --> API0(("GLM API")):::api
             end
 
-            subgraph Tier1 ["Tier 1: GitHub Copilot"]
+            subgraph Tier1 ["Tier 1: Anthropic"]
                 direction RL
-                G1{"CB / Quota"}:::gateway -- "✅ Pass" --> API1(("Copilot API")):::api
+                G1{"CB / Quota"}:::gateway -- "✅ Pass" --> API1(("Anthropic API")):::api
             end
 
-            subgraph Tier2 ["Tier 2: Google Antigravity"]
+            subgraph Tier2 ["Tier 2: GitHub Copilot"]
                 direction RL
-                G2{"CB / Quota"}:::gateway -- "✅ Pass" --> API2(("Gemini API")):::api
+                G2{"CB / Quota"}:::gateway -- "✅ Pass" --> API2(("Copilot API")):::api
             end
 
-            subgraph TierN ["Tier N: Zhipu"]
+            subgraph Tier3 ["Tier 3: Google Antigravity"]
                 direction RL
-                APIN(("GLM API")):::fallback
+                API3(("Gemini API")):::fallback
             end
 
             Tier0 -. "❌ Blocked / API Error" .-> Tier1
             Tier1 -. "❌ Blocked / API Error" .-> Tier2
-            Tier2 -. "🆘 Safety Net Downgrade" .-> TierN
+            Tier2 -. "🆘 Safety Net Downgrade" .-> Tier3
         end
 
     end

coding_proxy-0.2.4a5/docs/arch/config-reference.md

@@ -0,0 +1,259 @@
+# 配置字段参考
+
+> **路径约定**：本文档中模块路径均相对于 `src/coding/proxy/`。
+>
+> **定位**：本文档是所有配置参数的**规范来源（Single Source of Truth）**。设计模式章节和模块详情中引用参数默认值时，统一链接至此。
+
+[TOC]
+
+---
+
+## 1. 配置模块结构
+
+配置模型已从单体 `schema.py` 正交拆分为 5 个子模块：
+
+| 子模块          | 文件                                                                    | 核心类型                                                                                                                                               |
+| --------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **server**      | [`config/server.py`](../../src/coding/proxy/config/server.py)           | `ServerConfig`, `DatabaseConfig`, `LoggingConfig`                                                                                                      |
+| **vendors**     | [`config/vendors.py`](../../src/coding/proxy/config/vendors.py)         | `AnthropicConfig`, `CopilotConfig`, `AntigravityConfig`, `ZhipuConfig`, `MinimaxConfig`, `KimiConfig`, `DoubaoConfig`, `XiaomiConfig`, `AlibabaConfig` |
+| **resiliency**  | [`config/resiliency.py`](../../src/coding/proxy/config/resiliency.py)   | `CircuitBreakerConfig`, `RetryConfig`, `FailoverConfig`, `QuotaGuardConfig`                                                                            |
+| **routing**     | [`config/routing.py`](../../src/coding/proxy/config/routing.py)         | `VendorType`, `VendorConfig`, `ModelMappingRule`, `ModelPricingEntry`                                                                                  |
+| **auth_schema** | [`config/auth_schema.py`](../../src/coding/proxy/config/auth_schema.py) | `AuthConfig`                                                                                                                                           |
+
+`config/schema.py` 作为聚合入口点 re-export 所有符号，并保留 `ProxyConfig` 顶层模型及旧格式迁移逻辑。
+
+---
+
+## 2. 配置搜索优先级
+
+[`config/loader.py`](../../src/coding/proxy/config/loader.py) 按以下顺序搜索配置文件：
+
+```mermaid
+flowchart TD
+    A["CLI --config 参数<br/>（显式指定）"] -->|"未指定"| B["./config.yaml<br/>（项目根目录）"]
+    B -->|"不存在"| C["~/.coding-proxy/config.yaml<br/>（用户目录）"]
+    C -->|"不存在"| D["Pydantic 默认值"]
+
+    style A fill:#1a5276,color:#fff
+    style D fill:#7b241c,color:#fff
+```
+
+**环境变量展开**：语法 `${VARIABLE_NAME}`，递归处理 dict/list/str，未定义变量保留原文。
+
+---
+
+## 3. 服务器配置
+
+### 3.1 ServerConfig
+
+| 字段   | 类型 | 默认值        | 说明     |
+| ------ | ---- | ------------- | -------- |
+| `host` | str  | `"127.0.0.1"` | 监听地址 |
+| `port` | int  | `8046`        | 监听端口 |
+
+### 3.2 DatabaseConfig
+
+| 字段                       | 类型 | 默认值                        | 说明                  |
+| -------------------------- | ---- | ----------------------------- | --------------------- |
+| `path`                     | str  | `"~/.coding-proxy/usage.db"`  | SQLite 数据库文件路径 |
+| `compat_state_path`        | str  | `"~/.coding-proxy/compat.db"` | 兼容性会话存储路径    |
+| `compat_state_ttl_seconds` | int  | `86400`                       | 兼容性会话 TTL（秒）  |
+
+### 3.3 LoggingConfig
+
+| 字段           | 类型        | 默认值    | 说明                                     |
+| -------------- | ----------- | --------- | ---------------------------------------- |
+| `level`        | str         | `"INFO"`  | 控制台日志级别                           |
+| `file`         | str \| null | `null`    | 文件日志路径（`null` 时输出到控制台）    |
+| `max_bytes`    | int         | `5242880` | 单个日志文件最大字节数（5 MB），触发轮转 |
+| `backup_count` | int         | `5`       | 保留的已压缩备份文件数                   |
+
+### 3.4 AuthConfig
+
+| 字段               | 类型 | 默认值 | 说明                                 |
+| ------------------ | ---- | ------ | ------------------------------------ |
+| `token_store_path` | str  | `""`   | Token Store 文件路径（空则使用默认） |
+
+---
+
+## 4. VendorConfig 通用字段
+
+| 字段         | 类型 | 默认值   | 说明                                                                                                                 |
+| ------------ | ---- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `vendor`     | enum | --       | 供应商类型：`anthropic` / `copilot` / `antigravity` / `zhipu` / `minimax` / `kimi` / `doubao` / `xiaomi` / `alibaba` |
+| `enabled`    | bool | `true`   | 是否启用                                                                                                             |
+| `base_url`   | str  | `""`     | API 基础 URL（留空使用各供应商默认值）                                                                               |
+| `timeout_ms` | int  | `300000` | 请求超时（毫秒）                                                                                                     |
+
+---
+
+## 5. VendorConfig 弹性字段
+
+| 字段                 | 类型           | 默认值               | 说明                        |
+| -------------------- | -------------- | -------------------- | --------------------------- |
+| `circuit_breaker`    | config \| None | `None`               | 熔断器配置（None = 终端层） |
+| `retry`              | config         | `RetryConfig()`      | 重试策略配置                |
+| `quota_guard`        | config         | `QuotaGuardConfig()` | 日度配额守卫配置            |
+| `weekly_quota_guard` | config         | `QuotaGuardConfig()` | 周度配额守卫配置            |
+
+<a id="elastic-params"></a>
+
+### 5.1 CircuitBreakerConfig — 熔断器参数
+
+> **设计语义**：参见 [设计模式 -- Circuit Breaker](./design-patterns.md#circuit-breaker)
+
+| 字段                       | 类型 | 默认值 | 说明                              |
+| -------------------------- | ---- | ------ | --------------------------------- |
+| `failure_threshold`        | int  | `3`    | 触发 OPEN 的连续失败次数          |
+| `recovery_timeout_seconds` | int  | `300`  | OPEN → HALF_OPEN 等待秒数         |
+| `success_threshold`        | int  | `2`    | HALF_OPEN → CLOSED 所需连续成功数 |
+| `max_recovery_seconds`     | int  | `3600` | 指数退避最大恢复时间（秒）        |
+
+### 5.2 QuotaGuardConfig — 配额守卫参数
+
+> **设计语义**：参见 [设计模式 -- QuotaGuard State Machine](./design-patterns.md#quota-guard)
+
+| 字段                     | 类型  | 默认值  | 说明                                 |
+| ------------------------ | ----- | ------- | ------------------------------------ |
+| `enabled`                | bool  | `false` | 是否启用配额守卫                     |
+| `token_budget`           | int   | `0`     | 滑动窗口内的 Token 预算上限          |
+| `window_hours`           | float | `5.0`   | 滑动窗口大小（小时）                 |
+| `threshold_percent`      | float | `99.0`  | 触发 QUOTA_EXCEEDED 的用量百分比阈值 |
+| `probe_interval_seconds` | int   | `300`   | QUOTA_EXCEEDED 状态下探测间隔（秒）  |
+
+### 5.3 RetryConfig — 重试策略参数
+
+> **设计语义**：参见 [设计模式 -- Retry with Full Jitter](./design-patterns.md#retry)
+
+| 字段                 | 类型  | 默认值 | 说明             |
+| -------------------- | ----- | ------ | ---------------- |
+| `max_retries`        | int   | `2`    | 最大重试次数     |
+| `initial_delay_ms`   | int   | `500`  | 初始延迟（毫秒） |
+| `max_delay_ms`       | int   | `5000` | 最大延迟（毫秒） |
+| `backoff_multiplier` | float | `2.0`  | 退避倍数         |
+| `jitter`             | bool  | `true` | 是否启用抖动     |
+
+### 5.4 FailoverConfig — 故障转移参数
+
+> **设计语义**：参见 [请求生命周期 -- 故障转移判定](../framework.md#fault-overhead)
+
+| 字段                     | 类型      | 默认值                                                                             |
+| ------------------------ | --------- | ---------------------------------------------------------------------------------- |
+| `status_codes`           | list[int] | `[429, 403, 503, 500, 529]`                                                        |
+| `error_types`            | list[str] | `["rate_limit_error", "overloaded_error", "api_error"]`                            |
+| `error_message_patterns` | list[str] | `["quota", "limit exceeded", "usage cap", "capacity", "internal network failure"]` |
+
+---
+
+## 6. 供应商专属字段
+
+### 6.1 Copilot 专属字段
+
+| 字段                       | 类型 | 默认值          | 说明                                               |
+| -------------------------- | ---- | --------------- | -------------------------------------------------- |
+| `github_token`             | str  | `""`            | GitHub OAuth token / PAT（支持 `${ENV_VAR}`）      |
+| `account_type`             | str  | `"individual"`  | 账号类型：`individual` / `business` / `enterprise` |
+| `token_url`                | str  | `"https://..."` | Token 交换端点                                     |
+| `models_cache_ttl_seconds` | int  | `300`           | 模型列表缓存 TTL                                   |
+
+### 6.2 Antigravity 专属字段
+
+| 字段             | 类型 | 默认值                              | 说明                        |
+| ---------------- | ---- | ----------------------------------- | --------------------------- |
+| `client_id`      | str  | `""`                                | Google OAuth2 Client ID     |
+| `client_secret`  | str  | `""`                                | Google OAuth2 Client Secret |
+| `refresh_token`  | str  | `""`                                | Google OAuth2 Refresh Token |
+| `model_endpoint` | str  | `"models/claude-sonnet-4-20250514"` | Gemini 模型端点路径         |
+
+### 6.3 原生 Anthropic 兼容供应商共用字段
+
+适用于 `zhipu` / `minimax` / `kimi` / `doubao` / `xiaomi` / `alibaba`。
+
+| 字段      | 类型 | 默认值 | 说明                         |
+| --------- | ---- | ------ | ---------------------------- |
+| `api_key` | str  | `""`   | API Key（支持 `${ENV_VAR}`） |
+
+---
+
+## 7. 模型映射规则
+
+### 7.1 ModelMappingRule 字段
+
+| 字段       | 类型      | 说明                                       |
+| ---------- | --------- | ------------------------------------------ |
+| `pattern`  | str       | 匹配模式（精确/通配符/正则）               |
+| `target`   | str       | 目标模型名称                               |
+| `is_regex` | bool      | 是否为正则表达式（默认 `false`）           |
+| `vendors`  | list[str] | 规则作用域（留空应用于所有原生兼容供应商） |
+
+### 7.2 ModelPricingEntry 字段
+
+| 字段                        | 类型  | 说明                                               |
+| --------------------------- | ----- | -------------------------------------------------- |
+| `vendor`                    | str   | 供应商名称                                         |
+| `model`                     | str   | 实际模型名                                         |
+| `input_cost_per_mtok`       | float | 输入 Token 单价（$/百万 token，支持 `$`/`¥` 前缀） |
+| `output_cost_per_mtok`      | float | 输出 Token 单价                                    |
+| `cache_write_cost_per_mtok` | float | 缓存创建 Token 单价                                |
+| `cache_read_cost_per_mtok`  | float | 缓存读取 Token 单价                                |
+
+---
+
+## 8. tiers — 显式优先级
+
+| 字段    | 类型                     | 说明                                       |
+| ------- | ------------------------ | ------------------------------------------ |
+| `tiers` | list[VendorType] \| None | 降级链路优先级（None 时回退 vendors 顺序） |
+
+---
+
+## 9. vendors 列表格式（推荐）
+
+推荐使用 `vendors` 列表格式，每个 vendor 自包含其弹性配置：
+
+```yaml
+vendors:
+  - vendor: anthropic
+    enabled: true
+    base_url: https://api.anthropic.com
+    timeout_ms: 300000
+    circuit_breaker:
+      failure_threshold: 3
+      recovery_timeout_seconds: 300
+    quota_guard:
+      enabled: false
+    weekly_quota_guard:
+      enabled: false
+
+  - vendor: copilot
+    enabled: false
+    github_token: "${GITHUB_TOKEN}"
+    account_type: individual
+    circuit_breaker:
+      failure_threshold: 3
+    quota_guard:
+      enabled: true
+      token_budget: 3000000
+      window_hours: 4.0
+
+  - vendor: zhipu
+    enabled: true
+    api_key: "${ZHIPU_API_KEY}"
+    # 无 circuit_breaker -> 终端层
+
+  - vendor: minimax
+    enabled: false
+    api_key: "${MINIMAX_API_KEY}"
+
+tiers: [anthropic, copilot, zhipu]  # 显式优先级（可选）
+```
+
+### Legacy Flat 格式（向后兼容）
+
+旧的 flat 格式字段（`primary`/`copilot`/`antigravity`/`fallback`/`circuit_breaker`/`*_quota_guard`）仍受支持，通过 `ProxyConfig._migrate_legacy_fields()` 自动迁移为 vendors 列表格式。
+
+迁移规则：
+1. `anthropic` 字段名 → `primary`
+2. `zhipu` 字段名 → `fallback`
+3. 若无 `vendors` 字段，从 legacy flat 字段自动生成 vendors 列表
+4. 迁移时发出 INFO 日志建议迁移至新格式

coding_proxy-0.2.4a5/docs/arch/convert.md

@@ -0,0 +1,101 @@
+# 格式转换模块（convert/）
+
+> **路径约定**：本文档中模块路径均相对于 `src/coding/proxy/`。
+>
+> **定位**：从 `framework.md` 提取，详述 Anthropic ↔ Gemini ↔ OpenAI 三向格式转换。
+
+[TOC]
+
+---
+
+## 1. 模块总览
+
+[`convert/`](../../src/coding/proxy/convert/) 模块提供独立的纯函数适配器层，支持三向格式转换：
+
+| 转换方向                   | 模块                                                                                      | 说明               |
+| -------------------------- | ----------------------------------------------------------------------------------------- | ------------------ |
+| Anthropic → Gemini         | [`convert/anthropic_to_gemini.py`](../../src/coding/proxy/convert/anthropic_to_gemini.py) | 请求格式转换       |
+| Gemini → Anthropic         | [`convert/gemini_to_anthropic.py`](../../src/coding/proxy/convert/gemini_to_anthropic.py) | 响应格式转换       |
+| Gemini SSE → Anthropic SSE | [`convert/gemini_sse_adapter.py`](../../src/coding/proxy/convert/gemini_sse_adapter.py)   | 流式事件重构       |
+| Anthropic → OpenAI         | [`convert/anthropic_to_openai.py`](../../src/coding/proxy/convert/anthropic_to_openai.py) | Copilot 请求适配   |
+| OpenAI → Anthropic         | [`convert/openai_to_anthropic.py`](../../src/coding/proxy/convert/openai_to_anthropic.py) | Copilot 响应逆适配 |
+
+---
+
+## 2. 请求转换（Anthropic → Gemini）
+
+**应用位置**：[`convert/anthropic_to_gemini.py`](../../src/coding/proxy/convert/anthropic_to_gemini.py) -- `convert_request()`
+
+**转换映射**：
+
+| Anthropic 字段                    | Gemini 字段                        | 说明                                             |
+| --------------------------------- | ---------------------------------- | ------------------------------------------------ |
+| `system`（str \| list）           | `systemInstruction.parts[].text`   | 支持字符串和文本块列表两种格式                   |
+| `messages[]`                      | `contents[]`                       | 角色映射：`assistant` → `model`，`user` → `user` |
+| `content`（text）                 | `parts[].text`                     | 文本内容块                                       |
+| `content`（image）                | `parts[].inlineData`               | Base64 数据 + MIME 类型                          |
+| `content`（tool_use）             | `parts[].functionCall`             | `name` + `input` → `args`                        |
+| `content`（tool_result）          | `parts[].functionResponse`         | `tool_use_id` → `name`，`content` → `result`     |
+| `max_tokens`                      | `generationConfig.maxOutputTokens` |                                                  |
+| `temperature` / `top_p` / `top_k` | `generationConfig.*`               | 参数名驼峰转换                                   |
+| `stop_sequences`                  | `generationConfig.stopSequences`   |                                                  |
+
+**不支持的字段**（静默剥离并记录 WARNING）：`tools`、`tool_choice`、`metadata`、`extended_thinking`、`thinking`
+
+---
+
+## 3. 响应转换（Gemini → Anthropic）
+
+**应用位置**：[`convert/gemini_to_anthropic.py`](../../src/coding/proxy/convert/gemini_to_anthropic.py) -- `convert_response()` / `extract_usage()`
+
+**finishReason 映射**：
+
+| Gemini                            | Anthropic    |
+| --------------------------------- | ------------ |
+| `STOP`                            | `end_turn`   |
+| `MAX_TOKENS`                      | `max_tokens` |
+| `SAFETY` / `RECITATION` / `OTHER` | `end_turn`   |
+
+**Parts 转换**：
+- `text` → `{"type": "text", "text": "..."}`
+- `functionCall` → `{"type": "tool_use", "id": "toolu_...", "name": "...", "input": {...}}`
+
+**Usage 提取**：
+- `usageMetadata.promptTokenCount` → `input_tokens`
+- `usageMetadata.candidatesTokenCount` → `output_tokens`
+- 缓存字段填 0（Gemini 不直接暴露缓存信息）
+
+---
+
+## 4. SSE 流适配
+
+**应用位置**：[`convert/gemini_sse_adapter.py`](../../src/coding/proxy/convert/gemini_sse_adapter.py) -- `adapt_sse_stream()`
+
+将 Gemini SSE 流重构为 Anthropic 消息生命周期事件序列：
+
+```mermaid
+flowchart LR
+    Input["Gemini SSE chunks"] --> MS["message_start<br/>← 首次收到内容时发出"]
+    MS --> CBS["content_block_start<br/>← 内容块开始"]
+    CBS --> CBD["content_block_delta*<br/>← 增量文本"]
+    CBD --> CBS2["content_block_stop<br/>← 内容块结束"]
+    CBS2 --> MD["message_delta<br/>← stop_reason + output_tokens"]
+    MD --> MSP["message_stop<br/>← 消息结束"]
+
+    style Input fill:#1a5276,color:#fff
+    style MSP fill:#196f3d,color:#fff
+```
+
+**边界情况处理**：
+- 空 parts 后跟有 text 的 chunk → 延迟发出 `message_start` + `content_block_start`
+- 流结束但未收到 `finishReason` → 补发默认 `message_delta`（`stop_reason: "end_turn"`）+ `message_stop`
+
+---
+
+## 5. OpenAI 格式转换
+
+**应用位置**：
+- [`convert/anthropic_to_openai.py`](../../src/coding/proxy/convert/anthropic_to_openai.py) -- Anthropic → OpenAI Chat Completions 请求格式
+- [`convert/openai_to_anthropic.py`](../../src/coding/proxy/convert/openai_to_anthropic.py) -- OpenAI Chat Completions → Anthropic 响应格式
+
+专为 CopilotVendor 适配，处理 Anthropic Messages API 与 OpenAI Chat Completions API 之间的双向格式差异（角色映射、工具格式、usage 字段名等）。