coding-proxy 0.2.4a4__tar.gz → 0.3.0__tar.gz

{coding_proxy-0.2.4a4 → coding_proxy-0.3.0}/CHANGELOG.md

@@ -4,7 +4,25 @@
 
 ## [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 异常;
+## [v0.3.0](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.3.0) — 2026-04-20
+
+> [!IMPORTANT]
+>
+> **🚀 OpenAI、Anthropic、Gemini 原生 API 进驻 Coding Proxy！**
+>
+> 服务对象不在局限 Claude Code，凡兼容 OpenAI、Anthropic、Gemini 三巨头 API 协议的客户端，出口 LLM 流量可统一收敛到 Coding Proxy。
+
+### ✨ 核心亮点
+
+- feat(native-api): 新增 `/api/{openai,gemini,anthropic}/**` 原生 LLM API 全量 catch-all 透传通道；
+- feat(dashboard): 新增实时 Web Dashboard 页面，聚合展示流量与用量统计;
+- feat(usage): `usage` 区分 Claude Code 场景（`'cc'`）与原生 API 场景（`'api'`）；
+- refactor(vendor-channels): 将供应商转换通道从目标专属重构为源→目标绑定模型;
+- docs(user-guide): 补充 POST /v1/messages 完整 API 参考文档;
+
+### 🔧 更多特性
+
+- feat(server): 默认监听端口 `8046` → `3392`，规范化 [Negentropy](https://github.com/ThreeFish-AI/negentropy) 体系端口；
 
 ## [v0.2.3](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.2.3) — 2026-04-16
 

{coding_proxy-0.2.4a4 → coding_proxy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-proxy
-Version: 0.2.4a4
+Version: 0.3.0
 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
@@ -57,13 +57,13 @@ When you're deeply immersed in your coding "zone" with **Claude Code** (or any A
 ## 🌟 Core Features
 
 <div align="center">
-    <img src="assets/dashboard-v0.2.3.png">
+    <img src="assets/dashboard-v0.2.4.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.
 
@@ -97,9 +97,9 @@ uv run coding-proxy start
 # INFO:     Started server process [1403]
 # INFO:     Waiting for application startup.
 # ...
-# INFO:     coding-proxy started: host=127.0.0.1 port=8046
+# INFO:     coding-proxy started: host=127.0.0.1 port=3392
 # INFO:     Application startup complete.
-# INFO:     Uvicorn running on http://127.0.0.1:8046 (Press CTRL+C to quit)
+# INFO:     Uvicorn running on http://127.0.0.1:3392 (Press CTRL+C to quit)
 ```
 
 ### 4. Seamless Claude Code Integration
@@ -107,7 +107,7 @@ uv run coding-proxy start
 Open a fresh terminal tab and route your traffic through coding-proxy before firing up Claude Code:
 
 ```bash
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8046
+export ANTHROPIC_BASE_URL=http://127.0.0.1:3392
 
 # Enjoy blissful, silky-smooth, and uninterrupted coding nirvana:
 claude
@@ -119,12 +119,13 @@ claude
 
 `coding-proxy` comes equipped with a badass suite of CLI tools to help you boss around your proxy state.
 
-| Command  | Description                                                                                                                                        | Example Usage                                 |
-| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
-| `start`  | **Fire up the proxy server.** Supports custom ports and configuration paths.                                                                       | `coding-proxy start -p 8080 -c ~/config.yaml` |
-| `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`                          |
+| 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.4a4 → coding_proxy-0.3.0}/README.md

@@ -30,13 +30,13 @@ When you're deeply immersed in your coding "zone" with **Claude Code** (or any A
 ## 🌟 Core Features
 
 <div align="center">
-    <img src="assets/dashboard-v0.2.3.png">
+    <img src="assets/dashboard-v0.2.4.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.
 
@@ -70,9 +70,9 @@ uv run coding-proxy start
 # INFO:     Started server process [1403]
 # INFO:     Waiting for application startup.
 # ...
-# INFO:     coding-proxy started: host=127.0.0.1 port=8046
+# INFO:     coding-proxy started: host=127.0.0.1 port=3392
 # INFO:     Application startup complete.
-# INFO:     Uvicorn running on http://127.0.0.1:8046 (Press CTRL+C to quit)
+# INFO:     Uvicorn running on http://127.0.0.1:3392 (Press CTRL+C to quit)
 ```
 
 ### 4. Seamless Claude Code Integration
@@ -80,7 +80,7 @@ uv run coding-proxy start
 Open a fresh terminal tab and route your traffic through coding-proxy before firing up Claude Code:
 
 ```bash
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8046
+export ANTHROPIC_BASE_URL=http://127.0.0.1:3392
 
 # Enjoy blissful, silky-smooth, and uninterrupted coding nirvana:
 claude
@@ -92,12 +92,13 @@ claude
 
 `coding-proxy` comes equipped with a badass suite of CLI tools to help you boss around your proxy state.
 
-| Command  | Description                                                                                                                                        | Example Usage                                 |
-| :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
-| `start`  | **Fire up the proxy server.** Supports custom ports and configuration paths.                                                                       | `coding-proxy start -p 8080 -c ~/config.yaml` |
-| `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`                          |
+| 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.3.0/docs/arch/config-reference.md

@@ -0,0 +1,310 @@
+# 配置字段参考
+
+> **路径约定**：本文档中模块路径均相对于 `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  | `3392`        | 监听端口 |
+
+### 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 日志建议迁移至新格式
+
+---
+
+## 10. native_api — 原生 API 透传配置
+
+> **定义位置**：[`native_api/config.py`](../../src/coding/proxy/native_api/config.py)
+>
+> **端点**：`/api/{openai,gemini,anthropic}/**` catch-all 透传通道；认证头由客户端自带，proxy 不保管凭据。
+
+### 10.1 NativeApiConfig 顶层字段
+
+| 字段          | 类型                   | 默认值                                 | 说明                                      |
+| ------------- | ---------------------- | -------------------------------------- | ----------------------------------------- |
+| `openai`      | `NativeProviderConfig` | 内置官方 URL，`enabled=true`           | OpenAI chat / responses / embeddings 等   |
+| `gemini`      | `NativeProviderConfig` | 内置官方 URL，`enabled=true`           | Gemini generateContent / embedContent 等  |
+| `anthropic`   | `NativeProviderConfig` | 内置官方 URL，`enabled=true`           | Anthropic messages / count_tokens / batches |
+
+### 10.2 NativeProviderConfig 字段
+
+| 字段                  | 类型 | 默认值              | 说明                                                                  |
+| --------------------- | ---- | ------------------- | --------------------------------------------------------------------- |
+| `enabled`             | bool | `true`              | 是否启用该 provider 的原生透传端点（默认启用，开箱即用）              |
+| `base_url`            | str  | 见下方内置默认      | 上游 API base_url（纯域名前缀，不含 `/v1`）                           |
+| `timeout_ms`          | int  | `300000`            | 单次请求超时（毫秒），LLM 大模型建议 ≥ 120s                           |
+| `connect_timeout_ms`  | int  | `15000`             | 连接建立超时（毫秒）                                                  |
+
+### 10.3 内置默认 `base_url`
+
+| Provider     | 内置默认                                              |
+| ------------ | ----------------------------------------------------- |
+| `openai`     | `https://api.openai.com`                              |
+| `gemini`     | `https://generativelanguage.googleapis.com`           |
+| `anthropic`  | `https://api.anthropic.com`                           |
+
+### 10.4 `base_url` 三级覆写优先级
+
+由 `NativeApiConfig._apply_env_overrides` `@model_validator(mode="after")` 注入：
+
+```text
+env var（运行时） > YAML 显式字段（部署时） > Pydantic 内置默认（兜底）
+```
+
+| 环境变量                     | 覆写目标                  |
+| ---------------------------- | ------------------------- |
+| `NATIVE_OPENAI_BASE_URL`     | `openai.base_url`         |
+| `NATIVE_GEMINI_BASE_URL`     | `gemini.base_url`         |
+| `NATIVE_ANTHROPIC_BASE_URL`  | `anthropic.base_url`      |
+
+空串或纯空白视作未设置，保留上一层值（避免"未设置 env → 空串覆盖内置默认"陷阱）。
+
+> `ANTHROPIC_BASE_URL`（client → proxy，Claude Code 使用）与 `NATIVE_ANTHROPIC_BASE_URL`（proxy → upstream，原生透传使用）方向正交，勿混用。参见 [用户指引 § 4.7 native_api](../user-guide.md#47-native_api--原生-api-透传)。