api-key-manager 2.2.0__tar.gz → 3.0.0__tar.gz

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: api-key-manager
-Version: 2.2.0
-Summary: Batch manage API keys for 44+ AI providers with CLI and Web interfaces
+Version: 3.0.0
+Summary: Batch manage API keys for 45+ AI providers with CLI and Web interfaces
 Author: Townrain
 License: MIT
 Project-URL: Homepage, https://github.com/Townrain/API-Key-Manager
@@ -45,7 +45,7 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 - **Web 界面** - 赛博朋克风格的管理界面
 - **代理支持** - 支持 HTTP/SOCKS 代理
 - **加密存储** - AES-256-GCM 加密存储 API 密钥，随机盐值
-- **安全防护** - 路径遍历防护、SSRF 防护、时序安全认证
+- **安全防护** - 路径遍历防护、SSRF 防护（含 IPv6）、时序安全认证、强制认证、CORS 配置
 - **API 文档** - Swagger UI 和 Redoc 自动文档
 - **国际化** - 支持中英文错误信息
 - **SDK 支持** - Python 和 TypeScript 客户端库
@@ -197,11 +197,13 @@ python web.py
 ### 安全防护
 
 - **路径遍历防护** - 导入端点验证路径在允许目录内
-- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP，已接入 `check/single` 和 `balance` 端点
+- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP（含 IPv6），DNS 重绑定防护
 - **时序安全认证** - 使用 `hmac.compare_digest()` 防止时序攻击
-- **认证警告** - 未配置 API Key 时启动警告
+- **强制认证** - 未配置 API Key 时自动生成随机密钥，拒绝未认证请求
 - **密钥掩码** - API 响应中只返回 `key_masked`，不暴露完整密钥
-- **Webhook 安全** - Webhook 端点使用正确的 API 方法，防止运行时错误
+- **CORS 配置** - 跨域资源共享安全配置
+- **Webhook 安全** - 使用 `secrets.token_hex` 生成不可预测的 webhook ID
+- **存储安全** - 密钥文件权限加固 (0o600)，AES-256-GCM 加密，PBKDF2 600,000 次迭代
 
 ### API 认证
 
@@ -718,6 +720,45 @@ const result = await client.checkSingleKey({ key: 'sk-xxx', provider: 'openai' }
 
 ## 更新日志
 
+
+### v3.0.0 (2026-06-15)
+
+- **安全修复**: 移除 API 响应中的明文密钥，只返回 key_masked
+- **安全修复**: 强制认证，无配置时自动生成随机 API Key
+- **安全修复**: 使用 hmac.compare_digest 防止时序攻击
+- **安全修复**: 添加 CORS 中间件配置
+- **性能优化**: PBKDF2 密钥缓存，迭代次数提升至 600,000 (OWASP 推荐)
+- **性能优化**: 速率限制器添加 TTL 驱逐，防止内存泄漏
+- **可靠性**: 修复 checker.py 合并逻辑错误
+- **可靠性**: 替换所有裸 except 为 except Exception
+- **可靠性**: 添加配置验证和错误处理
+- **可靠性**: 添加 /healthz 健康检查端点
+- **可靠性**: 修复 datetime.utcnow() 废弃警告
+- **SSRF 防护**: 添加 IPv6 私有范围和 DNS 重绑定防护
+- **Webhook 安全**: 使用 secrets.token_hex 替代 MD5 生成 webhook ID
+- **存储安全**: 密钥文件权限加固 (0o600)
+- **前端**: 模型检测列表添加自定义滚轮条样式
+- **前端**: 修复模型类型下拉窗口被弹窗裁剪的问题
+- **精确匹配修复**: 能力检测从子串匹配改为 ^$ 锚定精确匹配
+- **API Bug 修复**: 修复 /api/stats/chart 运行时崩溃
+- **测试补充**: 新增 8 个端点的测试，覆盖率 91.47%
+
+### v2.2.2 (2026-06-14)
+
+- **模型检测二级窗口**: 新增模型检测弹窗，支持搜索、类型筛选、全选、批量检测
+- **模型类型图标**: 显示模型能力图标（视觉/推理/联网/工具/嵌入/重排/免费）
+- **模型能力数据更新**: 从 Cherry Studio 同步最新模型能力数据（3184 条记录）
+- **检测逻辑优化**: DeepSeek 欠费密钥正确识别，不再误判为其他服务商
+- **指定模型检测**: 自动检测服务商时也支持指定模型检测
+
+### v2.2.1 (2026-06-14)
+
+- **检测逻辑修复**: 自动识别后必须调用 check() 验证 key 有效性
+- **签名匹配修复**: 状态码不再硬编码 401，使用实际状态码
+- **不可靠服务商**: ppio、nvidia、modelscope 不参与加分
+- **模型选择器**: 新增模型下拉框，支持选择具体模型检测
+- **Cherry Studio 同步**: 修复 ownedBy 映射（alibaba→dashscope 等）
+- **测试补充**: 新增 test_parser_supplement、test_ssrf_supplement、test_validator_supplement
 ### v2.2.0 (2026-06-14)
 
 - **检测逻辑重构**: 添加三步检测逻辑（/v1/models → 并发测试）

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/README.md

@@ -12,7 +12,7 @@
 - **Web 界面** - 赛博朋克风格的管理界面
 - **代理支持** - 支持 HTTP/SOCKS 代理
 - **加密存储** - AES-256-GCM 加密存储 API 密钥，随机盐值
-- **安全防护** - 路径遍历防护、SSRF 防护、时序安全认证
+- **安全防护** - 路径遍历防护、SSRF 防护（含 IPv6）、时序安全认证、强制认证、CORS 配置
 - **API 文档** - Swagger UI 和 Redoc 自动文档
 - **国际化** - 支持中英文错误信息
 - **SDK 支持** - Python 和 TypeScript 客户端库
@@ -164,11 +164,13 @@ python web.py
 ### 安全防护
 
 - **路径遍历防护** - 导入端点验证路径在允许目录内
-- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP，已接入 `check/single` 和 `balance` 端点
+- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP（含 IPv6），DNS 重绑定防护
 - **时序安全认证** - 使用 `hmac.compare_digest()` 防止时序攻击
-- **认证警告** - 未配置 API Key 时启动警告
+- **强制认证** - 未配置 API Key 时自动生成随机密钥，拒绝未认证请求
 - **密钥掩码** - API 响应中只返回 `key_masked`，不暴露完整密钥
-- **Webhook 安全** - Webhook 端点使用正确的 API 方法，防止运行时错误
+- **CORS 配置** - 跨域资源共享安全配置
+- **Webhook 安全** - 使用 `secrets.token_hex` 生成不可预测的 webhook ID
+- **存储安全** - 密钥文件权限加固 (0o600)，AES-256-GCM 加密，PBKDF2 600,000 次迭代
 
 ### API 认证
 
@@ -685,6 +687,45 @@ const result = await client.checkSingleKey({ key: 'sk-xxx', provider: 'openai' }
 
 ## 更新日志
 
+
+### v3.0.0 (2026-06-15)
+
+- **安全修复**: 移除 API 响应中的明文密钥，只返回 key_masked
+- **安全修复**: 强制认证，无配置时自动生成随机 API Key
+- **安全修复**: 使用 hmac.compare_digest 防止时序攻击
+- **安全修复**: 添加 CORS 中间件配置
+- **性能优化**: PBKDF2 密钥缓存，迭代次数提升至 600,000 (OWASP 推荐)
+- **性能优化**: 速率限制器添加 TTL 驱逐，防止内存泄漏
+- **可靠性**: 修复 checker.py 合并逻辑错误
+- **可靠性**: 替换所有裸 except 为 except Exception
+- **可靠性**: 添加配置验证和错误处理
+- **可靠性**: 添加 /healthz 健康检查端点
+- **可靠性**: 修复 datetime.utcnow() 废弃警告
+- **SSRF 防护**: 添加 IPv6 私有范围和 DNS 重绑定防护
+- **Webhook 安全**: 使用 secrets.token_hex 替代 MD5 生成 webhook ID
+- **存储安全**: 密钥文件权限加固 (0o600)
+- **前端**: 模型检测列表添加自定义滚轮条样式
+- **前端**: 修复模型类型下拉窗口被弹窗裁剪的问题
+- **精确匹配修复**: 能力检测从子串匹配改为 ^$ 锚定精确匹配
+- **API Bug 修复**: 修复 /api/stats/chart 运行时崩溃
+- **测试补充**: 新增 8 个端点的测试，覆盖率 91.47%
+
+### v2.2.2 (2026-06-14)
+
+- **模型检测二级窗口**: 新增模型检测弹窗，支持搜索、类型筛选、全选、批量检测
+- **模型类型图标**: 显示模型能力图标（视觉/推理/联网/工具/嵌入/重排/免费）
+- **模型能力数据更新**: 从 Cherry Studio 同步最新模型能力数据（3184 条记录）
+- **检测逻辑优化**: DeepSeek 欠费密钥正确识别，不再误判为其他服务商
+- **指定模型检测**: 自动检测服务商时也支持指定模型检测
+
+### v2.2.1 (2026-06-14)
+
+- **检测逻辑修复**: 自动识别后必须调用 check() 验证 key 有效性
+- **签名匹配修复**: 状态码不再硬编码 401，使用实际状态码
+- **不可靠服务商**: ppio、nvidia、modelscope 不参与加分
+- **模型选择器**: 新增模型下拉框，支持选择具体模型检测
+- **Cherry Studio 同步**: 修复 ownedBy 映射（alibaba→dashscope 等）
+- **测试补充**: 新增 test_parser_supplement、test_ssrf_supplement、test_validator_supplement
 ### v2.2.0 (2026-06-14)
 
 - **检测逻辑重构**: 添加三步检测逻辑（/v1/models → 并发测试）

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/api_key_manager.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: api-key-manager
-Version: 2.2.0
-Summary: Batch manage API keys for 44+ AI providers with CLI and Web interfaces
+Version: 3.0.0
+Summary: Batch manage API keys for 45+ AI providers with CLI and Web interfaces
 Author: Townrain
 License: MIT
 Project-URL: Homepage, https://github.com/Townrain/API-Key-Manager
@@ -45,7 +45,7 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 - **Web 界面** - 赛博朋克风格的管理界面
 - **代理支持** - 支持 HTTP/SOCKS 代理
 - **加密存储** - AES-256-GCM 加密存储 API 密钥，随机盐值
-- **安全防护** - 路径遍历防护、SSRF 防护、时序安全认证
+- **安全防护** - 路径遍历防护、SSRF 防护（含 IPv6）、时序安全认证、强制认证、CORS 配置
 - **API 文档** - Swagger UI 和 Redoc 自动文档
 - **国际化** - 支持中英文错误信息
 - **SDK 支持** - Python 和 TypeScript 客户端库
@@ -197,11 +197,13 @@ python web.py
 ### 安全防护
 
 - **路径遍历防护** - 导入端点验证路径在允许目录内
-- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP，已接入 `check/single` 和 `balance` 端点
+- **SSRF 防护** - `custom_base_url` 验证域名白名单，阻止私有 IP（含 IPv6），DNS 重绑定防护
 - **时序安全认证** - 使用 `hmac.compare_digest()` 防止时序攻击
-- **认证警告** - 未配置 API Key 时启动警告
+- **强制认证** - 未配置 API Key 时自动生成随机密钥，拒绝未认证请求
 - **密钥掩码** - API 响应中只返回 `key_masked`，不暴露完整密钥
-- **Webhook 安全** - Webhook 端点使用正确的 API 方法，防止运行时错误
+- **CORS 配置** - 跨域资源共享安全配置
+- **Webhook 安全** - 使用 `secrets.token_hex` 生成不可预测的 webhook ID
+- **存储安全** - 密钥文件权限加固 (0o600)，AES-256-GCM 加密，PBKDF2 600,000 次迭代
 
 ### API 认证
 
@@ -718,6 +720,45 @@ const result = await client.checkSingleKey({ key: 'sk-xxx', provider: 'openai' }
 
 ## 更新日志
 
+
+### v3.0.0 (2026-06-15)
+
+- **安全修复**: 移除 API 响应中的明文密钥，只返回 key_masked
+- **安全修复**: 强制认证，无配置时自动生成随机 API Key
+- **安全修复**: 使用 hmac.compare_digest 防止时序攻击
+- **安全修复**: 添加 CORS 中间件配置
+- **性能优化**: PBKDF2 密钥缓存，迭代次数提升至 600,000 (OWASP 推荐)
+- **性能优化**: 速率限制器添加 TTL 驱逐，防止内存泄漏
+- **可靠性**: 修复 checker.py 合并逻辑错误
+- **可靠性**: 替换所有裸 except 为 except Exception
+- **可靠性**: 添加配置验证和错误处理
+- **可靠性**: 添加 /healthz 健康检查端点
+- **可靠性**: 修复 datetime.utcnow() 废弃警告
+- **SSRF 防护**: 添加 IPv6 私有范围和 DNS 重绑定防护
+- **Webhook 安全**: 使用 secrets.token_hex 替代 MD5 生成 webhook ID
+- **存储安全**: 密钥文件权限加固 (0o600)
+- **前端**: 模型检测列表添加自定义滚轮条样式
+- **前端**: 修复模型类型下拉窗口被弹窗裁剪的问题
+- **精确匹配修复**: 能力检测从子串匹配改为 ^$ 锚定精确匹配
+- **API Bug 修复**: 修复 /api/stats/chart 运行时崩溃
+- **测试补充**: 新增 8 个端点的测试，覆盖率 91.47%
+
+### v2.2.2 (2026-06-14)
+
+- **模型检测二级窗口**: 新增模型检测弹窗，支持搜索、类型筛选、全选、批量检测
+- **模型类型图标**: 显示模型能力图标（视觉/推理/联网/工具/嵌入/重排/免费）
+- **模型能力数据更新**: 从 Cherry Studio 同步最新模型能力数据（3184 条记录）
+- **检测逻辑优化**: DeepSeek 欠费密钥正确识别，不再误判为其他服务商
+- **指定模型检测**: 自动检测服务商时也支持指定模型检测
+
+### v2.2.1 (2026-06-14)
+
+- **检测逻辑修复**: 自动识别后必须调用 check() 验证 key 有效性
+- **签名匹配修复**: 状态码不再硬编码 401，使用实际状态码
+- **不可靠服务商**: ppio、nvidia、modelscope 不参与加分
+- **模型选择器**: 新增模型下拉框，支持选择具体模型检测
+- **Cherry Studio 同步**: 修复 ownedBy 映射（alibaba→dashscope 等）
+- **测试补充**: 新增 test_parser_supplement、test_ssrf_supplement、test_validator_supplement
 ### v2.2.0 (2026-06-14)
 
 - **检测逻辑重构**: 添加三步检测逻辑（/v1/models → 并发测试）

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/api_key_manager.egg-info/SOURCES.txt

@@ -89,12 +89,15 @@ tests/test_i18n.py
 tests/test_logger.py
 tests/test_openapi.py
 tests/test_parser.py
+tests/test_parser_supplement.py
 tests/test_provider_detection.py
 tests/test_providers.py
 tests/test_proxy.py
 tests/test_security.py
+tests/test_ssrf_supplement.py
 tests/test_storage.py
 tests/test_tester.py
 tests/test_validator.py
+tests/test_validator_supplement.py
 tests/test_web_fixes.py
 tests/test_webhook.py

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/key_manager/__init__.py

@@ -1,4 +1,4 @@
-"""Key Manager - Batch API key management for 44+ AI providers."""
+"""Key Manager - Batch API key management for 45+ AI providers."""
 from key_manager.core import KeyManager
 from key_manager.providers import PROVIDERS, get_display_name
 from key_manager.errors import KeyManagerError, ErrorCode
@@ -13,5 +13,5 @@ __all__ = [
     "KeyStore",
 ]
 
-__version__ = "2.2.0"
+__version__ = "3.0.0"
 

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/key_manager/api_models.py

@@ -71,6 +71,7 @@ class KeyListResponse(BaseModel):
 
 
 class KeyExportItem(BaseModel):
+    key_masked: str = Field(..., description="Masked key for display")
     provider: str = Field(..., description="Provider identifier")
     max_tokens: int | None = Field(None, description="Maximum token limit")
     max_concurrency: int | None = Field(None, description="Maximum concurrency limit")
@@ -111,11 +112,12 @@ class ImportResponse(BaseModel):
 class CheckSingleRequest(BaseModel):
     key: str = Field(..., min_length=1, description="API key to check")
     provider: str = Field("", description="Provider name (auto-detected if empty)")
+    model: str | None = Field(None, description="Specific model to test (tests all if empty)")
     custom_base_url: str | None = Field(None, description="Override provider base URL")
 
     model_config = {
         "json_schema_extra": {
-            "examples": [{"key": "sk-abc123", "provider": "openai"}]
+            "examples": [{"key": "sk-abc123", "provider": "openai", "model": "gpt-4o"}]
         }
     }
 
@@ -296,23 +298,26 @@ class StatsResponse(BaseModel):
     total: int = Field(0, description="Total key count")
 
 
-class StatsChartProviderEntry(BaseModel):
-    total: int = Field(0, description="Total keys for this provider")
-    valid: int = Field(0, description="Valid keys")
-    invalid: int = Field(0, description="Invalid keys")
-    error: int = Field(0, description="Errored keys")
-
-
 class StatsChartStatuses(BaseModel):
     valid: int = Field(0, description="Total valid keys")
     invalid: int = Field(0, description="Total invalid keys")
     error: int = Field(0, description="Total errored keys")
     unknown: int = Field(0, description="Total unknown-status keys")
 
+class StatsChartProviderEntry(BaseModel):
+    provider: str = Field(..., description="Provider identifier")
+    display_name: str = Field("", description="Human-readable provider name")
+    total: int = Field(0, description="Total keys for this provider")
+    valid: int = Field(0, description="Valid keys")
+    invalid: int = Field(0, description="Invalid keys")
+    error: int = Field(0, description="Errored keys")
+    statuses: StatsChartStatuses = Field(
+        default_factory=StatsChartStatuses, description="Status breakdown"
+    )
 
 class StatsChartResponse(BaseModel):
-    providers: dict[str, StatsChartProviderEntry] = Field(
-        default_factory=dict, description="Per-provider breakdown for charts"
+    providers: list[StatsChartProviderEntry] = Field(
+        default_factory=list, description="Per-provider breakdown for charts"
     )
     statuses: StatsChartStatuses = Field(
         default_factory=StatsChartStatuses, description="Global status counts"

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/key_manager/checker.py

@@ -1,14 +1,11 @@
 import asyncio
-import json
 from datetime import datetime
-from pathlib import Path
 
 import httpx
 
 from .providers import PROVIDERS
 from .validator import validate_keys
 
-
 async def run_check(keys_file: str = "./data/keys.json",
                     results_file: str = "./data/check_results.json",
                     logs_dir: str = "./data/logs",
@@ -16,14 +13,16 @@ async def run_check(keys_file: str = "./data/keys.json",
                     timeout: int = 30,
                     proxy: str = None,
                     retry_failed: bool = True,
-                    retry_count: int = 2) -> dict:
+                    retry_count: int = 2,
+                    config: dict = None) -> dict:
     results = await validate_keys(
         keys_file=keys_file,
         results_file=results_file,
         logs_dir=logs_dir,
         concurrency=concurrency,
         timeout=timeout,
-        proxy=proxy
+        proxy=proxy,
+        config=config
     )
 
     # Retry failed keys
@@ -40,12 +39,18 @@ async def run_check(keys_file: str = "./data/keys.json",
                 concurrency=concurrency,
                 timeout=timeout,
                 proxy=proxy,
-                status_filter="error"
+                status_filter="error",
+                config=config
             )
 
-            # Merge results
+            # Recompute summary from details to avoid double-counting
+            # The retry only re-checks error keys, so we need to update the summary
+            # based on what changed
+            results["summary"]["error"]["count"] = retry_results["summary"]["error"]["count"]
+            results["summary"]["error"]["keys"] = retry_results["summary"]["error"]["keys"]
             results["summary"]["valid"]["count"] += retry_results["summary"]["valid"]["count"]
+            results["summary"]["valid"]["keys"].extend(retry_results["summary"]["valid"]["keys"])
             results["summary"]["invalid"]["count"] += retry_results["summary"]["invalid"]["count"]
-            results["summary"]["error"]["count"] = retry_results["summary"]["error"]["count"]
+            results["summary"]["invalid"]["keys"].extend(retry_results["summary"]["invalid"]["keys"])
 
     return results

{api_key_manager-2.2.0 → api_key_manager-3.0.0}/key_manager/cli.py

@@ -2,7 +2,7 @@ import argparse
 import asyncio
 import json
 import sys
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 from rich.console import Console
@@ -153,7 +153,7 @@ def cmd_report(args, config):
         return
 
     days = args.days or 7
-    cutoff = datetime.utcnow() - timedelta(days=days)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
 
     stats = {}
     for key, info in data["keys"].items():

api_key_manager-3.0.0/key_manager/config.py

@@ -0,0 +1,103 @@
+import copy
+import logging
+import yaml
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONFIG = {
+    "scan": {
+        "directories": ["./data/input"],
+        "recursive": True,
+    },
+    "check": {
+        "interval_hours": 6,
+        "timeout_seconds": 30,
+        "concurrency": 100,
+        "retry_failed": True,
+        "retry_count": 2,
+    },
+    "test": {
+        "token_test": True,
+        "token_auto_detect": True,
+        "token_steps": [1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288, 1048576],
+        "token_max_manual": None,
+        "concurrency_test": True,
+        "concurrency_steps": [1, 5, 10, 20, 50, 100],
+        "concurrency_timeout_seconds": 120,
+    },
+    "storage": {
+        "keys_file": "./data/keys.json",
+        "check_results_file": "./data/check_results.json",
+        "test_results_file": "./data/test_results.json",
+        "logs_dir": "./data/logs",
+    },
+    "auth": {
+        "api_key": "",
+    },
+    "rate_limit": {
+        "requests_per_minute": 60,
+    },
+}
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def _validate_config(config: dict) -> dict:
+    """Validate config values and warn about unknown keys."""
+    valid_keys = set(DEFAULT_CONFIG.keys())
+    unknown_keys = set(config.keys()) - valid_keys
+    if unknown_keys:
+        logger.warning(f"Unknown config keys (ignored): {unknown_keys}")
+
+    # Validate numeric values
+    check_config = config.get("check", {})
+    if check_config.get("concurrency", 100) < 1:
+        logger.warning("check.concurrency must be >= 1, using default")
+        check_config["concurrency"] = 100
+    if check_config.get("timeout_seconds", 30) < 1:
+        logger.warning("check.timeout_seconds must be >= 1, using default")
+        check_config["timeout_seconds"] = 30
+
+    rate_limit = config.get("rate_limit", {})
+    if rate_limit.get("requests_per_minute", 60) < 0:
+        logger.warning("rate_limit.requests_per_minute must be >= 0, using default")
+        rate_limit["requests_per_minute"] = 60
+
+    return config
+
+
+def load_config(path: str = "config.yaml") -> dict:
+    config_path = Path(path)
+    if config_path.exists():
+        try:
+            with open(config_path, "r", encoding="utf-8") as f:
+                user_config = yaml.safe_load(f) or {}
+            if not isinstance(user_config, dict):
+                logger.warning(f"Config file {path} is not a dict, using defaults")
+                return copy.deepcopy(DEFAULT_CONFIG)
+            config = _deep_merge(DEFAULT_CONFIG, user_config)
+            return _validate_config(config)
+        except yaml.YAMLError as e:
+            logger.error(f"Failed to parse config file {path}: {e}")
+            return copy.deepcopy(DEFAULT_CONFIG)
+        except Exception as e:
+            logger.error(f"Failed to load config file {path}: {e}")
+            return copy.deepcopy(DEFAULT_CONFIG)
+    return copy.deepcopy(DEFAULT_CONFIG)
+
+
+def save_config(config: dict, path: str = "config.yaml"):
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
+    except Exception as e:
+        logger.error(f"Failed to save config file {path}: {e}")