Merge pull request #201 from ThreeFish-AI/feature/1.x.x

v0.3.0

Author: ThreeFish-AI

CHANGELOG.md

@@ -4,9 +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 异常;
-- 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.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
 

README.md

@@ -70,17 +70,17 @@ 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
 
 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

docs/arch/config-reference.md

@@ -49,7 +49,7 @@ flowchart TD
 | 字段   | 类型 | 默认值        | 说明     |
 | ------ | ---- | ------------- | -------- |
 | `host` | str  | `"127.0.0.1"` | 监听地址 |
-| `port` | int  | `8046`        | 监听端口 |
+| `port` | int  | `3392`        | 监听端口 |
 
 ### 3.2 DatabaseConfig
 
@@ -257,3 +257,54 @@ tiers: [anthropic, copilot, zhipu]  # 显式优先级（可选）
 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-透传)。

docs/arch/testing.md

@@ -65,6 +65,7 @@
 | `test_convert_sse.py`              | Gemini SSE→Anthropic SSE 流适配（单/多 chunk、各 finishReason、边界情况） |
 | `test_copilot_convert_request.py`  | Anthropic→OpenAI 请求格式转换                                             |
 | `test_copilot_convert_response.py` | OpenAI→Anthropic 响应格式转换                                             |
+| `test_vendor_channels.py`          | 源→目标通道：zhipu/copilot 兼容性清洗、tool_use 配对、内容感知源推断      |
 
 ### 2.5 数据模型（model）
 
@@ -95,7 +96,6 @@
 | 测试文件                     | 覆盖范围                                                |
 | ---------------------------- | ------------------------------------------------------- |
 | `test_app_routes.py`         | FastAPI 路由端点测试                                    |
-| `test_request_normalizer.py` | 请求标准化：私有块清洗、tool_use_id 重写、fatal_reasons |
 | `test_cli_usage.py`          | CLI 用量查询命令                                        |
 | `test_banner.py`             | CLI Banner 显示                                         |
 | `test_logging_dual_write.py` | 日志双写机制                                            |

docs/framework.md

@@ -69,7 +69,6 @@ graph TD
         App["<code>app.py</code><br/>应用工厂 + lifespan"]
         Routes["<code>routes.py</code><br/>路由注册"]
         Factory["<code>factory.py</code><br/>Vendor/Tier 构建工厂"]
-        Normalizer["<code>request_normalizer.py</code><br/>请求标准化"]
         Dashboard["<code>dashboard.py</code><br/>状态面板"]
     end
 
@@ -179,15 +178,8 @@ graph TD
 ```mermaid
 flowchart TD
     Client["Client POST /v1/messages"] --> Server["server.routes.messages()"]
-
-    subgraph Normalize ["请求标准化"]
-        Body["body = await request.json()"]
-        Norm["normalize_anthropic_request(body)<br/>清洗私有块 + 重写 tool_use_id"]
-        Body --> Norm
-    end
-
-    Server --> Normalize
-    Norm --> RouteType{"stream?"}
+    Server --> Body["body = await request.json()"]
+    Body --> RouteType{"stream?"}
 
     RouteType -- "true" --> StreamRoute["route_stream()"]
     RouteType -- "false" --> MsgRoute["route_message()"]
@@ -401,7 +393,6 @@ flowchart TD
 | [`app.py`](../src/coding/proxy/server/app.py)                               | FastAPI 应用工厂 `create_app()` + `lifespan` 生命周期管理 |
 | [`factory.py`](../src/coding/proxy/server/factory.py)                       | Vendor/Tier 构建工厂 + 凭证解析                           |
 | [`routes.py`](../src/coding/proxy/server/routes.py)                         | 路由端点按职责分组注册                                    |
-| [`request_normalizer.py`](../src/coding/proxy/server/request_normalizer.py) | 入站请求标准化（清洗供应商私有块）                        |
 | [`responses.py`](../src/coding/proxy/server/responses.py)                   | 响应辅助工具（JSON error / stream error 构建）            |
 | [`dashboard.py`](../src/coding/proxy/server/dashboard.py)                   | 状态面板（Web Dashboard）                                 |
 

docs/guide/api-reference.md

@@ -31,7 +31,7 @@
 根路径连通性探针。Claude Code 在建立连接前发送 `HEAD /` 作为健康检查，代理返回 HTTP 200 空响应。
 
 ```bash
-curl -I http://127.0.0.1:8046/
+curl -I http://127.0.0.1:3392/
 # HTTP/1.1 200 OK
 ```
 
@@ -189,7 +189,7 @@ curl -I http://127.0.0.1:8046/
 Token 计数 API 透传。支持所有提供 Anthropic 兼容端点的供应商。
 
 ```bash
-curl -X POST http://127.0.0.1:8046/v1/messages/count_tokens \
+curl -X POST http://127.0.0.1:3392/v1/messages/count_tokens \
   -H "Content-Type: application/json" \
   -H "anthropic-version: 2023-06-01" \
   -d '{"model":"claude-sonnet-4-6","messages":[{"role":"user","content":"Hello"}]}'
@@ -206,7 +206,7 @@ curl -X POST http://127.0.0.1:8046/v1/messages/count_tokens \
 健康检查。
 
 ```bash
-curl http://127.0.0.1:8046/health
+curl http://127.0.0.1:3392/health
 # {"status":"ok"}
 ```
 
@@ -215,7 +215,7 @@ curl http://127.0.0.1:8046/health
 查询所有层级的熔断器、配额守卫、周级配额守卫、Rate Limit 及诊断信息。
 
 ```bash
-curl http://127.0.0.1:8046/api/status
+curl http://127.0.0.1:3392/api/status
 ```
 
 **返回示例**：
@@ -258,15 +258,15 @@ curl http://127.0.0.1:8046/api/status
 
 ```bash
 # 仅重置（向后兼容）
-curl -X POST http://127.0.0.1:8046/api/reset
+curl -X POST http://127.0.0.1:3392/api/reset
 
 # 重置 + 提升 anthropic 到最高优先级
-curl -X POST http://127.0.0.1:8046/api/reset \
+curl -X POST http://127.0.0.1:3392/api/reset \
   -H "Content-Type: application/json" \
   -d '{"vendors": ["anthropic"]}'
 
 # 重置 + 替换整条链路顺序
-curl -X POST http://127.0.0.1:8046/api/reset \
+curl -X POST http://127.0.0.1:3392/api/reset \
   -H "Content-Type: application/json" \
   -d '{"vendors": ["zhipu", "anthropic", "copilot"]}'
 ```
@@ -282,7 +282,7 @@ curl -X POST http://127.0.0.1:8046/api/reset \
 返回 Copilot 认证与交换链路的脱敏诊断信息。
 
 ```bash
-curl http://127.0.0.1:8046/api/copilot/diagnostics
+curl http://127.0.0.1:3392/api/copilot/diagnostics
 ```
 
 若 Copilot 供应商未启用，返回 404。
@@ -292,7 +292,7 @@ curl http://127.0.0.1:8046/api/copilot/diagnostics
 按需探测当前 Copilot 会话可见的模型列表。
 
 ```bash
-curl http://127.0.0.1:8046/api/copilot/models
+curl http://127.0.0.1:3392/api/copilot/models
 ```
 
 需要有效的 Copilot 凭证；凭证无效时返回 503。
@@ -302,15 +302,15 @@ curl http://127.0.0.1:8046/api/copilot/models
 查询运行时重认证状态。
 
 ```bash
-curl http://127.0.0.1:8046/api/reauth/status
+curl http://127.0.0.1:3392/api/reauth/status
 ```
 
 ## 10. POST /api/reauth/{provider}
 
 手动触发指定 provider 的运行时重认证。
 
 ```bash
-curl -X POST http://127.0.0.1:8046/api/reauth/github
+curl -X POST http://127.0.0.1:3392/api/reauth/github
 # HTTP/1.1 202 Accepted
 # {"status":"reauth requested"}
 ```
@@ -330,15 +330,15 @@ curl -X POST http://127.0.0.1:8046/api/reauth/github
 返回 Dashboard HTML 页面。
 
 ```bash
-curl http://127.0.0.1:8046/dashboard
+curl http://127.0.0.1:3392/dashboard
 ```
 
 ### 11.2 GET /api/dashboard/summary
 
 返回 Dashboard 汇总数据（今日 + 所选区间）。
 
 ```bash
-curl "http://127.0.0.1:8046/api/dashboard/summary?days=7"
+curl "http://127.0.0.1:3392/api/dashboard/summary?days=7"
 ```
 
 | 参数   | 类型 | 默认值 | 说明             |
@@ -352,7 +352,7 @@ curl "http://127.0.0.1:8046/api/dashboard/summary?days=7"
 返回按天分组的时序数据（用于图表绘制）。
 
 ```bash
-curl "http://127.0.0.1:8046/api/dashboard/timeline?days=30"
+curl "http://127.0.0.1:3392/api/dashboard/timeline?days=30"
 ```
 
 | 参数   | 类型 | 默认值 | 说明             |

docs/guide/cli-reference.md

@@ -39,7 +39,7 @@ coding-proxy start
 coding-proxy start -p 9000 -c ~/my-config.yaml
 
 # 自定义监听地址和端口
-coding-proxy start --host 0.0.0.0 --port 8046
+coding-proxy start --host 0.0.0.0 --port 3392
 ```
 
 > 若启用了 Copilot 或 Antigravity 供应商但未配置凭证，启动时会自动触发 OAuth 浏览器登录流程。
@@ -54,7 +54,7 @@ coding-proxy status [OPTIONS]
 
 | 参数     | 缩写 | 说明                      |
 | -------- | ---- | ------------------------- |
-| `--port` | `-p` | 代理服务端口（默认 8046） |
+| `--port` | `-p` | 代理服务端口（默认 3392） |
 
 **输出示例**：
 
@@ -143,7 +143,7 @@ coding-proxy reset [OPTIONS]
 
 | 参数       | 缩写 | 说明                                            |
 | ---------- | ---- | ----------------------------------------------- |
-| `--port`   | `-p` | 代理服务端口（默认 8046）                       |
+| `--port`   | `-p` | 代理服务端口（默认 3392）                       |
 | `--vendor` | `-v` | 提升/重排序 vendor 优先级（单个或逗号分隔多个） |
 
 **重排序语义**：
@@ -211,7 +211,7 @@ coding-proxy auth reauth PROVIDER [OPTIONS]
 | 参数       | 缩写 | 说明                                       |
 | ---------- | ---- | ------------------------------------------ |
 | `PROVIDER` | —    | provider 名称（必填）：`github` / `google` |
-| `--port`   | `-p` | 代理服务端口（默认 8046）                  |
+| `--port`   | `-p` | 代理服务端口（默认 3392）                  |
 
 **示例**：
 

docs/guide/dashboard.md

@@ -7,7 +7,7 @@ coding-proxy 内置 Web 可视化看板，提供流量、用量、故障转移
 启动代理后，浏览器访问：
 
 ```
-http://127.0.0.1:8046/dashboard
+http://127.0.0.1:3392/dashboard
 ```
 
 ## 功能概览

docs/guide/monitoring.md

@@ -67,17 +67,17 @@ coding-proxy usage --db /path/to/usage.db
 
 ```bash
 # 基础检查
-curl http://127.0.0.1:8046/health
+curl http://127.0.0.1:3392/health
 
 # 详细状态（所有层级的熔断器、配额守卫、Rate Limit、诊断信息）
-curl http://127.0.0.1:8046/api/status
+curl http://127.0.0.1:3392/api/status
 ```
 
 > 端点详情参见 [API 参考](./api-reference.md)。
 
 ## 4. Dashboard 监控
 
-浏览器访问 `http://127.0.0.1:8046/dashboard` 查看 Web 可视化看板。详见 [Dashboard 文档](./dashboard.md)。
+浏览器访问 `http://127.0.0.1:3392/dashboard` 查看 Web 可视化看板。详见 [Dashboard 文档](./dashboard.md)。
 
 ## 5. 数据库维护
 
@@ -138,7 +138,7 @@ coding-proxy reset -v anthropic
 coding-proxy auth reauth github
 
 # API
-curl -X POST http://127.0.0.1:8046/api/reauth/github
+curl -X POST http://127.0.0.1:3392/api/reauth/github
 ```
 
 重认证请求发出后（HTTP 202），在浏览器中完成授权即可，无需重启。
@@ -150,7 +150,7 @@ curl -X POST http://127.0.0.1:8046/api/reauth/github
 **端口占用**：
 
 ```bash
-lsof -i :8046
+lsof -i :3392
 coding-proxy start --port 8080
 ```
 
@@ -161,7 +161,7 @@ coding-proxy start --port 8080
 ### 8.2 Claude Code 无法连接代理
 
 1. 确认代理正在运行：`coding-proxy status`
-2. 确认环境变量：`echo $ANTHROPIC_BASE_URL`（应为 `http://127.0.0.1:8046`）
+2. 确认环境变量：`echo $ANTHROPIC_BASE_URL`（应为 `http://127.0.0.1:3392`）
 3. 确认端口一致
 
 ### 8.3 频繁触发故障转移
@@ -185,10 +185,10 @@ coding-proxy start --port 8080
 
 ```bash
 # 查看诊断信息
-curl http://127.0.0.1:8046/api/copilot/diagnostics
+curl http://127.0.0.1:3392/api/copilot/diagnostics
 
 # 探查可用模型
-curl http://127.0.0.1:8046/api/copilot/models
+curl http://127.0.0.1:3392/api/copilot/models
 
 # 重认证
 coding-proxy auth reauth github