api-key-manager 3.0.1__tar.gz → 4.0.0__tar.gz

{api_key_manager-3.0.1 → api_key_manager-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: api-key-manager
-Version: 3.0.1
+Version: 4.0.0
 Summary: Batch manage API keys for 45+ AI providers with CLI and Web interfaces
 Author: Townrain
 License: MIT
@@ -25,6 +25,7 @@ Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.32.0
 Requires-Dist: python-multipart>=0.0.9
 Requires-Dist: cryptography>=42.0.0
+Requires-Dist: jinja2>=3.0.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
@@ -42,6 +43,8 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 - **能力测试** - 测试 Token 上限和并发能力
 - **模型筛选** - 按类型筛选模型（推理/视觉/联网/免费/嵌入/重排/工具）
 - **智能检测** - 前缀匹配 + 模式匹配 + 错误签名匹配，三级提供商自动识别
+- **自动发现** - 新增服务商只需创建 Python 文件，自动注册
+- **可扩展架构** - 支持 YAML 配置自定义服务商，Web API 管理
 - **Web 界面** - 赛博朋克风格的管理界面
 - **代理支持** - 支持 HTTP/SOCKS 代理
 - **加密存储** - AES-256-GCM 加密存储 API 密钥，随机盐值
@@ -118,6 +121,64 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 | Kimi Coding | 编程版 |
 | Infini Coding | 编程版 |
 
+## 添加自定义服务商
+
+### 方式一：Python 文件（推荐）
+
+创建 `key_manager/providers/my_llm.py`：
+
+```python
+from .base import ProviderBase
+
+
+class MyLlmProvider(ProviderBase):
+    name = "my-llm"
+    base_url = "https://api.my-llm.com/v1"
+    check_endpoint = "/models"
+    check_model = "my-model"
+    display_name = "My LLM"
+    key_prefixes = ["myllm-"]
+    error_signatures = ["my-llm", "invalid api key"]
+    website_url = "https://my-llm.com"
+    docs_url = "https://docs.my-llm.com"
+
+    def build_headers(self, key: str) -> dict:
+        return {"Authorization": f"Bearer {key}"}
+```
+
+重启服务即可自动发现。
+
+### 方式二：YAML 配置
+
+在 `config.yaml` 中添加：
+
+```yaml
+providers:
+  custom:
+    - name: "my-llm"
+      base_url: "https://api.my-llm.com/v1"
+      check_endpoint: "/models"
+      check_model: "my-model"
+      display_name: "My LLM"
+      key_prefixes: ["myllm-"]
+      auth_type: bearer
+```
+
+### 方式三：Web API
+
+```bash
+# 添加服务商
+curl -X POST http://localhost:18001/api/providers \
+  -H "Content-Type: application/json" \
+  -d '{"name":"my-llm","base_url":"https://api.my-llm.com/v1","check_endpoint":"/models"}'
+
+# 列出所有服务商
+curl http://localhost:18001/api/providers
+
+# 删除服务商
+curl -X DELETE http://localhost:18001/api/providers/my-llm
+```
+
 ## 快速开始
 
 ### 安装
@@ -221,133 +282,246 @@ set KEY_MANAGER_API_KEY=your-api-key
 
 系统采用**全并发探测**策略，自动识别 45+ 个 AI 服务商的 API 密钥。
 
-#### 检测流程
+### 检测流程（重要！）
 
 ```
-1. 模式匹配 - 检查唯一前缀（如 sk-proj- → OpenAI，AIza → Google）
+1. 前缀匹配 - 检查唯一前缀（如 sk-proj- → OpenAI，AIza → Google）
 2. 格式匹配 - 检查特殊格式（如智谱的 {id}.{secret} 格式）
-3. 全并发探测 - 同时向所有服务商发送请求（40+ 服务商 × 5 模型 = 200+ 请求）
+3. 全并发探测 - 同时向所有服务商发送请求
 4. 签名匹配 - 如果无200响应，通过错误响应体签名识别服务商
 ```
 
-#### 全并发探测逻辑
+### ⚠️ 关键概念：/v1/models vs /chat/completions
 
-当密钥无法通过前缀或格式识别时，系统会：
+**这两个端点的作用完全不同，不能混用！**
 
-1. 从 Cherry Studio 同步的模型列表中获取每个服务商的前5个模型
-2. 并发向所有服务商发送请求（每个服务商尝试5个模型）
-3. 第一个返回200的服务商立即胜出
-4. 如果所有请求都失败，通过签名匹配识别
+| 端点 | 作用 | 返回200的含义 |
+|------|------|--------------|
+| `/v1/models` | 获取模型列表 | 只表示可以获取模型列表，**不能**判断密钥是否有效 |
+| `/chat/completions` | 调用模型 | 表示密钥对该提供商有效，**这才是判断提供商的依据** |
+
+**常见错误：**
+- ❌ 用 `/v1/models` 返回200来判断提供商 → 错误！
+- ✅ 用 `/chat/completions` 返回200来判断提供商 → 正确！
+
+### 检测流程详解
+
+#### Step 1: 前缀匹配
+
+检查密钥是否匹配唯一前缀：
 
 ```python
-# 检测流程示例
-async def detect_provider(client, key):
-    # Step 1: 模式匹配
-    pattern_match = detect_by_pattern(key)  # 如 sk-proj- → OpenAI
-    if pattern_match:
-        return pattern_match
-    
-    # Step 2: 格式匹配
-    format_candidates = detect_by_format(key)  # 如 {id}.{secret} → 智谱/Z.AI
-    if format_candidates:
-        return format_candidates[0]
-    
-    # Step 3: 全并发探测
-    tasks = []
-    for name, provider in PROVIDERS.items():
-        models = PROVIDER_MODELS.get(name, [])[:5]
-        for model in models:
-            tasks.append(try_model(name, model))
-    
-    # 第一个返回200的胜出
-    for coro in asyncio.as_completed(tasks):
-        name, valid, body = await coro
-        if valid:
-            return name
-    
-    # Step 4: 签名匹配
-    return match_by_signature(error_bodies)
+# 唯一前缀 → 直接返回
+"sk-proj-" → OpenAI
+"sk-ant-api03-" → Anthropic
+"AIza" → Google
+"ms-" → ModelScope
+
+# 共享前缀 → 需要进一步探测
+"sk-" → 20+ 提供商（DeepSeek, OpenAI, 等）
 ```
 
-### 特殊密钥格式支持
+#### Step 2: 格式匹配
 
-#### 智谱/Z.AI 密钥格式
-
-智谱和 Z.AI 使用 `{id}.{secret}` 格式的密钥（非 `sk-` 开头）：
+检查密钥是否匹配特殊格式：
 
 ```python
-# 示例密钥格式
+# 智谱/Z.AI 格式：{id}.{secret}
 50bcde33b8774aa8a2cc1bd6d39444ae.ifriyNWRLStzpLEs
-
-# 正则表达式匹配
-ZHIPU_KEY_PATTERN = re.compile(r'^[a-zA-Z0-9]{20,50}\.[a-zA-Z0-9]{10,50}$')
+→ 返回 ["zhipu", "zai"]
 ```
 
-这种格式的密钥会被自动识别为智谱或 Z.AI（两者共享相同的 GLM 模型）。
+#### Step 3: 全并发探测（核心逻辑）
 
-### 错误签名匹配
+**重要：这一步用 `/chat/completions` 验证，不是 `/v1/models`！**
 
-当所有并发请求都失败时，系统通过错误响应体中的关键词识别服务商：
+```python
+async def detect_provider(client, key):
+    # Step 3.1: 获取所有提供商的模型列表（/v1/models）
+    # 这一步只是为了获取模型列表，不能判断提供商
+    models = {}
+    for name, provider in PROVIDERS.items():
+        resp = await client.get(f"{provider.base_url}/v1/models")
+        if resp.status_code == 200:
+            models[name] = extract_models(resp.json())
+    
+    # Step 3.2: 并发测试所有（提供商，模型）对的 /chat/completions
+    # 这一步才是判断提供商的依据！
+    tasks = []
+    for name, model_list in models.items():
+        for model in model_list:
+            tasks.append(try_chat_completion(name, model))
+    
+    # 第一个返回200的提供商胜出
+    for coro in asyncio.as_completed(tasks):
+        name, valid, status_code = await coro
+        if valid:  # /chat/completions 返回200
+            return name
+```
+
+#### Step 4: 签名匹配
+
+如果所有 `/chat/completions` 都失败，通过错误响应体识别提供商：
 
 ```python
+# 错误签名匹配
 UNIQUE_SIGNATURES = {
-    # 国内服务商
     "dashscope": ["model-studio", "modelstudio", "apikey-error"],
-    "tencent-hunyuan": ["hunyuan", "console.cloud.tencent.com"],
-    "baichuan": ["baichuan-ai.com", "platform.baichuan-ai.com"],
-    "minimax": ["authorized_error", "login fail"],
-    "yi": ["illegal apikey"],
-    "kimi": ["invalid_authentication_error"],
-    "siliconflow": ["api key is invalid"],
-    "stepfun": ["incorrect api key provided", "invalid_api_key"],
-    "doubao": ["authenticationerror"],
-    "infini": ["请使用正确的api key进行请求"],
-    "zhipu": ["令牌已过期或验证不正确"],
-    "mimo": ["invalid api key", "please provide valid api key"],
-    # 国外服务商
-    "deepseek": ["authentication fails"],
     "anthropic": ["request not allowed", "anthropic", "x-api-key"],
-    "openrouter": ["missing authentication header"],
-    "mistral": ["mistral", "la plateforme"],
-    "replicate": ["unauthenticated", "you did not pass a valid authentication token"],
-    "huggingface": ["huggingface", "hf_"],
-    "fireworks": ["fireworks", "accounts/fireworks"],
-    "perplexity": ["perplexity"],
-    "grok": ["console.x.ai"],
     "openai": ["platform.openai.com"],
-    "google": ["generativelanguage"],
-    "groq": ["groq"],
+    # ... 更多签名
 }
-```
-
-#### 签名匹配算法
-
-```python
-def score_provider(provider_name, error_body, status_code):
-    body = error_body.lower()
-    score = 0
-    weight = 100  # 每个匹配的签名加100分
-    
-    for sig in UNIQUE_SIGNATURES.get(provider_name, []):
-        if sig.lower() in body:
-            score += weight
-    
-    return score
 
 # 匹配阈值：至少2个签名匹配（200分）才返回结果
 if best_score >= 200:
     return best_name
 ```
 
+### 免费模型的重要性
+
+**某些提供商（如 OpenCode Zen）提供免费模型，这些模型对检测非常重要！**
+
+```python
+# OpenCode Zen 的模型列表：
+# - claude-fable-5 (付费)
+# - deepseek-v4-flash-free (免费) ✅
+# - mimo-v2.5-free (免费) ✅
+# - ...
+
+# 如果密钥只对免费模型有效：
+# - /chat/completions + claude-fable-5 → 401 (付费模型，无权限)
+# - /chat/completions + deepseek-v4-flash-free → 200 (免费模型，有权限) ✅
+```
+
+**检测逻辑会并发测试所有模型，包括免费模型。只要有一个模型返回200，提供商就会被正确识别。**
+
 ### 检测优先级
 
-| 优先级 | 方法 | 说明 |
-|--------|------|------|
-| 1 | 模式匹配 | 唯一前缀，如 `sk-proj-` → OpenAI |
-| 2 | 格式匹配 | 特殊格式，如 `{id}.{secret}` → 智谱 |
-| 3 | 全并发探测 | 第一个返回200的服务商胜出 |
-| 4 | 签名匹配 | 通过错误响应体识别，需至少2个签名匹配 |
+| 优先级 | 方法 | 端点 | 说明 |
+|--------|------|------|------|
+| 1 | 前缀匹配 | - | 唯一前缀，如 `sk-proj-` → OpenAI |
+| 2 | 格式匹配 | - | 特殊格式，如 `{id}.{secret}` → 智谱 |
+| 3 | 全并发探测 | `/chat/completions` | 第一个返回200的提供商胜出 |
+| 4 | 签名匹配 | - | 通过错误响应体识别，需至少2个签名匹配 |
+
+### 常见问题
+
+#### Q: 为什么我的密钥被错误识别为其他提供商？
+
+**A: 可能是因为：**
+1. 密钥使用共享前缀（如 `sk-`），需要通过 `/chat/completions` 验证
+2. 密钥只对免费模型有效，但检测逻辑没有测试免费模型
+3. 提供商的 `/v1/models` 返回200，但 `/chat/completions` 返回401
+
+#### Q: 为什么 `/v1/models` 返回200，但检测失败？
+
+**A: 因为 `/v1/models` 返回200不能判断提供商！**
+- `/v1/models` 只表示可以获取模型列表
+- `/chat/completions` 返回200才能判断提供商
+
+#### Q: 如何确保检测正确？
+
+**A: 确保以下几点：**
+1. 密钥对至少一个模型有调用权限（包括免费模型）
+2. 提供商的 `/chat/completions` 端点正常工作
+3. 密钥没有过期或被撤销
+
+### 检测流程图
 
+```
+输入: API Key
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 1: 前缀匹配                                            │
+│   - 唯一前缀 → 直接返回（如 sk-proj- → OpenAI）              │
+│   - 共享前缀 → 继续下一步                                    │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 2: 格式匹配                                            │
+│   - 智谱格式 {id}.{secret} → 返回 ["zhipu", "zai"]          │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 3: 全并发探测（用 /chat/completions 验证）               │
+│                                                             │
+│   3.1 获取所有提供商的模型列表（/v1/models）                  │
+│       - 这一步只是为了获取模型，不能判断提供商                 │
+│                                                             │
+│   3.2 并发测试所有（提供商，模型）对的 /chat/completions       │
+│       - 第一个返回200的提供商胜出                             │
+│       - 包括免费模型和付费模型                                │
+└─────────────────────────────────────────────────────────────┘
+     │
+     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Step 4: 签名匹配（如果 /chat/completions 都失败）             │
+│   - 通过错误响应体中的关键词识别提供商                        │
+│   - 需要至少2个签名匹配（200分）才返回结果                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 代码实现
+
+检测逻辑在 `key_manager/detector.py` 中实现：
+
+```python
+async def detect_provider(client, key: str, suspected_provider: str = None) -> str:
+    """Detect provider by concurrently probing ALL providers with multiple models.
+    
+    Strategy:
+    1. If suspected_provider given, try it first
+    2. If key matches unique pattern, try that provider
+    3. Otherwise, concurrently probe ALL providers with their top 5 models
+    4. First provider returning 200 wins
+    """
+    # Step 1: If suspected provider, try it first
+    if suspected_provider:
+        provider_name = suspected_provider.lower()
+        if provider_name in PROVIDERS:
+            return provider_name
+    
+    # Step 2: Try format matching (e.g., Zhipu's {id}.{secret})
+    format_candidates = detect_by_format(key)
+    if format_candidates:
+        for name in format_candidates:
+            if name in PROVIDERS:
+                return name
+    
+    # Step 3: Try prefix matching
+    prefix_candidates = detect_by_prefix(key)
+    if prefix_candidates:
+        if len(prefix_candidates) == 1:
+            return prefix_candidates[0]
+        # If multiple candidates, continue to Step 4
+    
+    # Step 4: Concurrently probe ALL providers
+    # First, get models from all providers concurrently
+    model_tasks = [get_provider_models(name, provider) for name, provider in PROVIDERS.items()]
+    model_results = await asyncio.gather(*model_tasks)
+    
+    # Build tasks: (provider_name, model) pairs
+    tasks = []
+    for name, models, is_valid in model_results:
+        if models:
+            for model in models:
+                tasks.append((name, model))
+    
+    # Concurrently check all (provider, model) pairs
+    all_tasks = [try_model(name, model) for name, model in tasks]
+    
+    # First provider returning 200 wins
+    for coro in asyncio.as_completed(all_tasks):
+        name, valid, body, status_code = await coro
+        if valid:
+            return name
+    
+    # Step 5: Signature matching
+    return match_by_signature(error_bodies)
+```
 
 ## 错误信息简化
 
@@ -445,7 +619,20 @@ key/
 ├── key_manager/                    # 核心包
 │   ├── __init__.py                 # 包导出
 │   ├── cli.py                      # CLI 入口
-│   ├── web.py                      # FastAPI 应用
+│   ├── web/                        # Web 模块 (v4.0.0 重构)
+│   │   ├── __init__.py             # 包导出
+│   │   ├── _app.py                 # FastAPI 应用入口
+│   │   ├── middleware.py           # 中间件和错误处理器
+│   │   ├── progress.py             # ProgressTracker和SSE辅助
+│   │   └── routes/                 # 路由模块
+│   │       ├── keys.py             # 密钥管理路由
+│   │       ├── check.py            # 验证路由
+│   │       ├── test.py             # 测试路由
+│   │       ├── balance.py          # 余额查询路由
+│   │       ├── models.py           # 模型路由
+│   │       ├── providers.py        # 提供商路由
+│   │       ├── stats.py            # 统计路由
+│   │       └── misc.py             # 杂项路由
 │   ├── config.py                   # 配置加载
 │   ├── storage.py                  # AES-256-GCM 加密存储
 │   ├── errors.py                   # 结构化错误码
@@ -467,7 +654,48 @@ key/
 │       ├── openai.py               # OpenAI
 │       ├── anthropic.py            # Anthropic
 │       └── ...                     # 更多提供商
+├── static/                         # 前端静态资源 (v4.0.0 重构)
+│   ├── css/
+│   │   ├── tokens.css              # CSS 变量
+│   │   ├── base.css                # 基础样式
+│   │   ├── components.css          # 组件入口 (@import)
+│   │   ├── components/             # 独立组件样式
+│   │   │   ├── button.css          # 按钮
+│   │   │   ├── form.css            # 表单控件
+│   │   │   ├── card.css            # 卡片、操作区
+│   │   │   ├── table.css           # 表格、徽章、分页
+│   │   │   ├── stat.css            # 统计卡片
+│   │   │   ├── nav.css             # 导航标签
+│   │   │   └── overlay.css         # 进度、Toast、日志
+│   │   ├── modals.css              # 模态框样式
+│   │   └── animations.css          # 动画
+│   └── js/
+│       ├── state.js                # 全局状态
+│       ├── utils.js                # 工具函数
+│       ├── api/                    # API 模块
+│       │   ├── client.js           # 通用 fetch 逻辑
+│       │   ├── index.js            # 重新导出
+│       │   ├── stats.js            # 统计 API
+│       │   ├── keys.js             # 密钥 API
+│       │   ├── check.js            # 验证 API
+│       │   ├── test.js             # 测试 API
+│       │   ├── balance.js          # 余额 API
+│       │   ├── models.js           # 模型 API
+│       │   ├── providers.js        # 提供商 API
+│       │   └── misc.js             # 杂项 API
+│       ├── toast.js                # Toast 通知
+│       ├── progress.js             # 进度覆盖层
+│       ├── confirm.js              # 确认模态框
+│       ├── keys-table.js           # 表格渲染
+│       ├── providers.js            # 提供商网格
+│       ├── batch.js                # 批量结果
+│       ├── modals.js               # 模态框
+│       ├── model-detect.js         # 模型检测
+│       └── init.js                 # 入口点
+├── templates/
+│   └── index.html                  # Web UI 入口 (467行)
 ├── tests/                          # 测试套件
+│   ├── conftest.py                 # 共享 fixtures 和帮助函数
 │   ├── test_detector.py            # 提供商检测测试
 │   ├── test_parser.py              # 解析器测试
 │   ├── test_validator.py           # 验证器测试
@@ -478,7 +706,9 @@ key/
 │   ├── test_errors.py              # 错误系统测试
 │   ├── test_i18n.py                # 国际化测试
 │   ├── test_e2e.py                 # 端到端测试
-│   └── test_webhook.py             # Webhook 测试
+│   ├── test_webhook.py             # Webhook 测试
+│   ├── test_bug_fixes.py           # Bug 修复回归测试
+│   └── test_provider_refactoring.py # 提供商重构测试
 ├── sdk/                            # SDK
 │   ├── python/                     # Python SDK
 │   └── typescript/                 # TypeScript SDK
@@ -609,24 +839,26 @@ python -m pytest tests/ --cov=key_manager --cov-report=term-missing
 
 | 模块 | 测试文件 | 测试数 |
 |------|---------|--------|
-| 提供商检测 | `test_detector.py` | 54 |
-| 密钥解析 | `test_parser.py` | 12 |
-| 验证器 | `test_validator.py` | 5 |
+| 提供商检测 | `test_detector.py` | 44 |
+| 密钥解析 | `test_parser.py` | 24 |
+| 验证器 | `test_validator.py` | 13 |
 | 检查器 | `test_checker.py` | 4 |
 | 提供商合约 | `test_providers.py` | 220 |
-| 安全回归 | `test_security.py` | 12 |
+| 安全回归 | `test_security.py` | 21 |
 | 加密存储 | `test_storage.py` | 26 |
 | 错误系统 | `test_errors.py` | 28 |
 | 国际化 | `test_i18n.py` | 37 |
-| 端到端 | `test_e2e.py` | 17 |
+| 端到端 | `test_e2e.py` | 18 |
 | Webhook | `test_webhook.py` | 35 |
 | OpenAPI | `test_openapi.py` | 26 |
 | 代理检测 | `test_proxy.py` | 19 |
 | 日志系统 | `test_logger.py` | 21 |
 | 能力测试 | `test_tester.py` | 11 |
 | 核心门面 | `test_core.py` | 22 |
+| Bug 修复 | `test_bug_fixes.py` | 15 |
+| 提供商重构 | `test_provider_refactoring.py` | 32 |
 
-**总测试数**: 583+ | **覆盖率**: 88%
+**总测试数**: 728+ | **覆盖率**: 80%
 ## SDK 使用
 
 ### Python SDK
@@ -642,10 +874,10 @@ from key_manager_sdk import KeyManagerClient
 client = KeyManagerClient(base_url="http://localhost:18001")
 
 # 获取密钥列表
-keys = client.get_keys()
+keys = client.keys()
 
 # 验证单个密钥
-result = client.check_single_key(key="sk-xxx", provider="openai")
+result = client.check_single(key="sk-xxx", provider="openai")
 ```
 
 ### TypeScript SDK
@@ -661,10 +893,10 @@ npm install @api-key-manager/sdk
 const client = new KeyManagerClient({ baseUrl: 'http://localhost:18001' });
 
 // 获取密钥列表
-const keys = await client.getKeys();
+const keys = await client.keys();
 
 // 验证单个密钥
-const result = await client.checkSingleKey({ key: 'sk-xxx', provider: 'openai' });
+const result = await client.checkSingle({ key: 'sk-xxx', provider: 'openai' });
 ```
 
 ## 依赖
@@ -717,6 +949,94 @@ const result = await client.checkSingleKey({ key: 'sk-xxx', provider: 'openai' }
 ## 更新日志
 
 
+### v4.0.0 (2026-06-21)
+
+- **前端模块化重构**: 将单体 `index.html` (4725行) 重构为模块化结构:
+  - CSS 拆分: 5个主题文件 + 7个组件文件
+    - `tokens.css` — CSS 变量
+    - `base.css` — 基础样式、布局、响应式
+    - `components.css` — 组件入口 (@import)
+    - `components/` — 7个独立组件 (button, form, card, table, stat, nav, overlay)
+    - `modals.css` — 模态框样式
+    - `animations.css` — 动画和过渡
+  - JS 模块化: 12个ES模块
+    - `state.js` — 全局状态管理
+    - `utils.js` — 纯工具函数
+    - `api/` — 9个API模块 (client, stats, keys, check, test, balance, models, providers, misc)
+    - UI模块: toast, progress, confirm, keys-table, providers, batch, modals, model-detect
+    - `init.js` — 入口点和事件绑定
+  - `index.html` 精简至 467行
+- **API模块拆分**: 按后端路由结构拆分前端API模块:
+  - `api/client.js` — 通用fetch逻辑 (safeFetch)
+  - `api/index.js` — 重新导出所有函数
+  - 每个路由模块对应独立文件
+- **静态文件服务**: 添加 `StaticFiles` 中间件
+- **错误处理增强**: loadKeys/loadStats 添加 try-catch 错误处理
+- **ES模块修复**: 修复 State 对象只读绑定问题
+
+- **Web模块重构**: 将单体 `web.py` (2094行) 重构为模块化包结构:
+  - `web/_app.py` — 应用入口 (239行)
+  - `web/middleware.py` — 中间件和错误处理器
+  - `web/progress.py` — ProgressTracker和SSE辅助
+  - `web/routes/` — 8个路由模块 (keys, check, test, balance, models, providers, stats, misc)
+- **测试套件重构**:
+  - 合并补充测试文件 (test_parser_supplement, test_validator_supplement, test_ssrf_supplement)
+  - 删除重复测试文件 (test_web_fixes)
+  - 修复 mock 路径以匹配新的 web 模块结构
+  - 提取共享 fixtures 和帮助函数到 conftest.py
+  - 移除冗余 @pytest.mark.asyncio 装饰器
+  - 修复速率限制中间件的测试隔离问题
+- **代码去重**: 消除 `api_check_single` 中的重复模型检查逻辑
+- **调试系统清理**: 移除 `sys.path.insert` hack，使用干净的可选导入模式
+- **重复路由修复**: 合并重复的 `GET /api/providers` 路由
+- **日志显示修复**: 修复日志显示为 `[object Object]` 的问题
+- **可扩展性**: 在 `routes/__init__.py` 中添加新路由、中间件和错误处理器的扩展指南
+
+- **提供商系统重构**:
+  - 删除 `check_model` 属性，改为先从 API 获取模型列表再测试
+  - 删除所有提供商中的冗余方法（build_headers, get_models, test_token_limit, test_concurrency, _probe, check_real）
+  - 标准提供商从 ~77 行减少到 ~5-8 行
+  - 总共减少 ~2,400 行冗余代码
+  - 添加 `chat_endpoint` 属性，自动从 `check_endpoint` 推导 chat completions 端点
+
+- **检测逻辑修复**:
+  - 修复检测逻辑不再因为 `/v1/models` 返回 200 就立即返回提供商
+  - `/v1/models` 只用于获取模型列表，不能判断提供商
+  - `/chat/completions` 返回 200 才能判断提供商
+  - 添加前缀匹配逻辑，支持共享前缀（如 `sk-`）的提供商检测
+  - 免费模型对检测非常重要，检测逻辑会测试所有模型包括免费模型
+
+- **文档更新**:
+  - 更新 README.md 的"提供商智能检测"部分，添加详细的检测流程说明
+  - 更新 docs/DEVELOPMENT.md 的"检测系统"部分
+  - 更新 docs/PROVIDER_REFACTORING_PLAN.md，添加"检测逻辑详解"部分
+  - 在 detector.py 中添加详细注释，说明 `/v1/models` 和 `/chat/completions` 的区别
+
+- **Bug 修复与改进**:
+  - 修复 SDK 文档方法名与实际不符（`get_keys()` → `keys()` 等）
+  - 修复删除密钥时报错 "No passphrase found"，新增自动生成加密密钥功能
+  - 修复签名验证报告端点 404 错误，改为动态生成报告
+  - 修复添加自定义服务商按钮缺失，新增前端 UI
+### v3.2.0 (2026-06-19)
+
+- **模型检测按模型测试**: 支持在模型检测模态框中直接测试Token限制和并发能力
+- **提供商管理UI**: 添加前端UI用于添加/管理自定义提供商
+- **移除check_model**: 从ProviderBase中移除check_model属性，提供商必须从API获取模型
+- **并发测试API改进**: 改进错误处理，提供详细错误信息
+- **提供商Token测试修复**: 修复提供商使用错误模型或错误API端点的问题
+- **余额API修复**: 修复支持余额查询的服务商的余额检测
+
+
+### v3.1.0 (2026-06-19)
+
+- **提供商自动发现**: 使用pkgutil自动发现替代47个显式导入
+- **提供商元数据属性**: 所有提供商声明display_name、key_prefixes等类属性
+- **默认实现**: test_token_limit、test_concurrency等方法现在是具体方法
+- **YAML配置支持**: 可在config.yaml中定义自定义提供商
+- **提供商Web API**: 添加/api/providers CRUD端点
+- **代码精简**: 39个标准提供商从~100行减少到~15行
+
+
 ### v3.0.0 (2026-06-15)
 
 - **精确匹配修复**: 能力检测从子串匹配改为 ^$ 锚定精确匹配，修复 o1 误匹配 o1-mini 等问题