Merge pull request #158 from CJackHwang/dev

更新文档以反映新功能和配置管理，增强脚本注入功能描述，优化用户指南和故障排除步骤

Author: CJackHwang

README.md

@@ -35,16 +35,18 @@ This project is generously sponsored by ZMTO. Visit their website: [https://zmto
 
 ## 主要特性
 
-*   **OpenAI 兼容 API**: 支持 `/v1/chat/completions` 端点，兼容现有的 OpenAI 客户端
-*   **流式和非流式响应**: 支持实时流式输出和传统的完整响应
-*   **模型切换**: 通过 API 请求中的 `model` 字段动态切换 AI Studio 中的模型
-*   **参数控制**: 支持 `temperature`, `max_output_tokens`, `top_p`, `stop` 等参数
-*   **反指纹检测**: 使用 Camoufox 降低被检测为自动化脚本的风险
-*   **多种响应获取方式**: 集成流式代理、外部 Helper 服务、Playwright 页面交互
-*   **脚本注入功能**: 支持油猴脚本动态挂载，与前端显示效果100%一致的模型增强 🆕
-*   **Web UI**: 内置现代化的测试界面，支持聊天、状态监控、安全的API密钥管理
-*   **图形界面启动器**: 提供 GUI 启动器，简化配置和管理
-*   **灵活的认证系统**: 支持可选的API密钥认证，兼容OpenAI标准的Bearer token
+*   **OpenAI 兼容 API**: 支持 `/v1/chat/completions` 端点，完全兼容 OpenAI 客户端
+*   **流式和非流式响应**: 支持实时流式输出和传统的完整响应模式
+*   **智能模型切换**: 通过 API 请求中的 `model` 字段动态切换 AI Studio 中的模型
+*   **完整参数控制**: 支持 `temperature`、`max_output_tokens`、`top_p`、`stop` 等所有主要参数
+*   **反指纹检测**: 使用 Camoufox 浏览器降低被检测为自动化脚本的风险
+*   **多层响应获取**: 集成流式代理、外部 Helper 服务、Playwright 页面交互的多重保障机制
+*   **脚本注入功能**: 支持油猴脚本动态挂载，实现与前端显示效果100%一致的模型增强 🆕
+*   **现代化 Web UI**: 内置测试界面，支持实时聊天、状态监控、API密钥管理
+*   **图形界面启动器**: 提供功能丰富的 GUI 启动器，简化配置和进程管理
+*   **灵活认证系统**: 支持可选的API密钥认证，完全兼容OpenAI标准的Bearer token格式
+*   **模块化架构**: 采用清晰的模块化设计，便于维护和扩展
+*   **统一配置管理**: 基于 `.env` 文件的统一配置方式，支持环境变量覆盖
 
 ## 系统架构
 
@@ -57,24 +59,28 @@ graph TD
     end
 
     subgraph "启动与配置 (Launch & Config)"
-        GUI_Launch["gui_launcher.py"]
-        CLI_Launch["launch_camoufox.py"]
+        GUI_Launch["gui_launcher.py (图形启动器)"]
+        CLI_Launch["launch_camoufox.py (命令行启动)"]
+        EnvConfig[".env (统一配置)"]
         KeyFile["key.txt (API Keys)"]
-        ConfigDir["config/ (Settings)"]
+        ConfigDir["config/ (配置模块)"]
     end
 
     subgraph "核心应用 (Core Application)"
-        FastAPI_App["api_utils/app.py (FastAPI App)"]
-        Routes["api_utils/routes.py"]
-        RequestProcessor["api_utils/request_processor.py"]
-        PageController["browser_utils/page_controller.py"]
-        ScriptManager["browser_utils/script_manager.py (Script Injection)"]
-        StreamProxy["stream/ (Proxy Server)"]
+        FastAPI_App["api_utils/app.py (FastAPI 应用)"]
+        Routes["api_utils/routes.py (路由处理)"]
+        RequestProcessor["api_utils/request_processor.py (请求处理)"]
+        AuthUtils["api_utils/auth_utils.py (认证管理)"]
+        PageController["browser_utils/page_controller.py (页面控制)"]
+        ScriptManager["browser_utils/script_manager.py (脚本注入)"]
+        ModelManager["browser_utils/model_management.py (模型管理)"]
+        StreamProxy["stream/ (流式代理服务器)"]
     end
 
     subgraph "外部依赖 (External Dependencies)"
-        CamoufoxInstance["Camoufox 浏览器 (Browser)"]
+        CamoufoxInstance["Camoufox 浏览器 (反指纹)"]
         AI_Studio["Google AI Studio"]
+        UserScript["油猴脚本 (可选)"]
     end
 
     User -- "运行 (Run)" --> GUI_Launch
@@ -88,15 +94,19 @@ graph TD
     API_Client -- "API 请求 (Request)" --> FastAPI_App
     WebUI -- "聊天请求 (Chat Request)" --> FastAPI_App
 
-    FastAPI_App -- "读取配置 (Reads Config)" --> ConfigDir
+    FastAPI_App -- "读取配置 (Reads Config)" --> EnvConfig
     FastAPI_App -- "使用路由 (Uses Routes)" --> Routes
-    FastAPI_App -- "验证密钥 (Validates Key)" --> KeyFile
+    AuthUtils -- "验证密钥 (Validates Key)" --> KeyFile
+    ConfigDir -- "提供设置 (Provides Settings)" --> EnvConfig
 
     Routes -- "处理请求 (Processes Request)" --> RequestProcessor
+    Routes -- "认证管理 (Auth Management)" --> AuthUtils
     RequestProcessor -- "控制浏览器 (Controls Browser)" --> PageController
     RequestProcessor -- "通过代理 (Uses Proxy)" --> StreamProxy
 
+    PageController -- "模型管理 (Model Management)" --> ModelManager
     PageController -- "脚本注入 (Script Injection)" --> ScriptManager
+    ScriptManager -- "加载脚本 (Loads Script)" --> UserScript
     ScriptManager -- "增强功能 (Enhances)" --> CamoufoxInstance
     PageController -- "自动化 (Automates)" --> CamoufoxInstance
     CamoufoxInstance -- "访问 (Accesses)" --> AI_Studio
@@ -165,8 +175,7 @@ python launch_camoufox.py --headless
 - [Web UI使用指南](docs/webui-guide.md) - Web界面功能说明
 - [故障排除指南](docs/troubleshooting.md) - 常见问题解决方案
 - [高级配置指南](docs/advanced-configuration.md) - 高级功能和配置选项
-- [脚本注入指南](docs/script_injection_guide.md) - 油猴脚本动态挂载功能使用指南 🆕
-- [脚本注入v2.0升级指南](docs/script_injection_v2_upgrade.md) - v2.0重大改进和升级说明 🔥
+- [脚本注入指南](docs/script_injection_guide.md) - 油猴脚本动态挂载功能使用指南 (v3.0) 🆕
 - [日志控制指南](docs/logging-control.md) - 日志系统配置和调试
 - [依赖版本说明](docs/dependency-versions.md) - Python版本要求和依赖兼容性详解
 

docker/README-Docker.md

@@ -1,19 +1,31 @@
-# Docker 部署教程 (AI Studio Proxy API)
+# Docker 部署指南 (AI Studio Proxy API)
 
 > 📁 **注意**: 所有 Docker 相关文件现在都位于 `docker/` 目录中，保持项目根目录的整洁。
 
-本文档提供了使用 Docker 构建和运行 AI Studio Proxy API 项目的详细步骤。
+本文档提供了使用 Docker 构建和运行 AI Studio Proxy API 项目的完整指南，包括最新的 `.env` 配置管理和脚本注入功能。
 
-**先决条件:**
-*   确保您的系统已正确安装并正在运行 Docker。您可以从 [Docker 官方网站](https://www.docker.com/get-started) 下载并安装 Docker Desktop (适用于 Windows 和 macOS) 或 Docker Engine (适用于 Linux)。
-*   项目代码已下载到本地。
-*   **重要**: 首次运行需要在主机上完成认证文件获取，Docker环境目前仅支持日常运行。
+## 概述
+
+Docker 部署提供了以下优势：
+- ✅ **环境隔离**: 容器化部署，避免环境冲突
+- ✅ **统一配置**: 基于 `.env` 文件的配置管理
+- ✅ **版本更新无忧**: `bash update.sh` 即可完成更新
+- ✅ **跨平台支持**: 支持 x86_64 和 ARM64 架构
+- ✅ **配置持久化**: 认证文件和日志持久化存储
+
+## 先决条件
+
+*   **Docker**: 确保您的系统已正确安装并正在运行 Docker。您可以从 [Docker 官方网站](https://www.docker.com/get-started) 下载并安装 Docker Desktop (适用于 Windows 和 macOS) 或 Docker Engine (适用于 Linux)。
+*   **项目代码**: 项目代码已下载到本地。
+*   **认证文件**: 首次运行需要在主机上完成认证文件获取，Docker环境目前仅支持日常运行。
+
+## Docker 环境规格
 
-**Docker 环境说明:**
 *   **基础镜像**: Python 3.10-slim-bookworm (稳定且轻量)
 *   **Python版本**: 3.10 (在容器内运行，与主机Python版本无关)
-*   **兼容性**: 支持 x86_64 和 ARM64 架构
+*   **架构支持**: x86_64 和 ARM64 (Apple Silicon)
 *   **依赖管理**: 容器内自动安装所有必需依赖
+*   **模块化设计**: 完全支持项目的模块化架构
 
 ## 1. 理解项目中的 Docker 相关文件
 
@@ -204,10 +216,10 @@ AUTO_CONFIRM_LOGIN=true
 AUTO_SAVE_AUTH=false
 AUTH_SAVE_TIMEOUT=30
 
-# 脚本注入配置
+# 脚本注入配置 (v3.0)
 ENABLE_SCRIPT_INJECTION=true
 USERSCRIPT_PATH=browser_utils/more_modles.js
-MODEL_CONFIG_PATH=browser_utils/model_configs.json
+# 注意：MODEL_CONFIG_PATH 已废弃，现在直接从油猴脚本解析模型数据
 
 # API 默认参数
 DEFAULT_TEMPERATURE=1.0
@@ -320,11 +332,17 @@ docker run -d \
 
 希望本教程能帮助您成功地通过 Docker 部署和运行 AI Studio Proxy API 项目！
 
-## 脚本注入配置 (新功能)
+## 脚本注入配置 (v3.0 新功能) 🆕
 
 ### 概述
 
-Docker 环境现在支持油猴脚本动态注入功能，可以增强 AI Studio 的模型列表。
+Docker 环境完全支持最新的脚本注入功能 v3.0，提供以下特性：
+
+- **🚀 Playwright 原生拦截**: 使用 Playwright 路由拦截，100% 可靠
+- **🔄 双重保障机制**: 网络拦截 + 脚本注入，确保万无一失
+- **📝 直接脚本解析**: 从油猴脚本中自动解析模型列表
+- **🔗 前后端同步**: 前端和后端使用相同的模型数据源
+- **⚙️ 零配置维护**: 无需手动维护模型配置文件
 
 ### 配置选项
 

docs/api-usage.md

@@ -1,6 +1,16 @@
 # API 使用指南
 
-代理服务器默认监听在 `http://127.0.0.1:2048`。端口可以在 [`launch_camoufox.py`](../launch_camoufox.py) 的 `--server-port` 参数或 [`gui_launcher.py`](../gui_launcher.py) 中修改。
+本指南详细介绍如何使用 AI Studio Proxy API 的各种功能和端点。
+
+## 服务器配置
+
+代理服务器默认监听在 `http://127.0.0.1:2048`。端口可以通过以下方式配置：
+
+- **环境变量**: 在 `.env` 文件中设置 `PORT=2048` 或 `DEFAULT_FASTAPI_PORT=2048`
+- **命令行参数**: 使用 `--server-port` 参数
+- **GUI 启动器**: 在图形界面中直接配置端口
+
+推荐使用 `.env` 文件进行配置管理，详见 [环境变量配置指南](environment-configuration.md)。
 
 ## API 密钥配置
 

docs/daily-usage.md

@@ -1,10 +1,25 @@
 # 日常运行指南
 
-完成首次认证设置后，推荐使用 [`gui_launcher.py`](../gui_launcher.py) 的无头模式或直接通过命令行运行 [`launch_camoufox.py --headless`](../launch_camoufox.py) 进行日常运行。
+本指南介绍如何在完成首次认证设置后进行日常运行。项目提供了多种启动方式，推荐使用基于 `.env` 配置文件的简化启动方式。
+
+## 概述
+
+完成首次认证设置后，您可以选择以下方式进行日常运行：
+
+- **图形界面启动**: 使用 [`gui_launcher.py`](../gui_launcher.py) 提供的现代化GUI界面
+- **命令行启动**: 直接使用 [`launch_camoufox.py`](../launch_camoufox.py) 命令行工具
+- **Docker部署**: 使用容器化部署方式
 
 ## ⭐ 简化启动方式（推荐）
 
-**现在有了 `.env` 配置文件，启动变得非常简单！**
+**基于 `.env` 配置文件的统一配置管理，启动变得极其简单！**
+
+### 配置优势
+
+- ✅ **一次配置，终身受益**: 配置好 `.env` 文件后，启动命令极其简洁
+- ✅ **版本更新无忧**: `git pull` 后无需重新配置，直接启动
+- ✅ **参数集中管理**: 所有配置项统一在 `.env` 文件中
+- ✅ **环境隔离**: 不同环境可使用不同的配置文件
 
 ### 基本启动（推荐）
 

docs/environment-configuration.md

@@ -1,15 +1,20 @@
 # 环境变量配置指南
 
-本文档介绍如何使用 `.env` 文件来配置 AI Studio Proxy API 项目，避免硬编码配置参数。
+本文档详细介绍如何使用 `.env` 文件来配置 AI Studio Proxy API 项目，实现统一的配置管理。
 
 ## 概述
 
-项目现在支持通过 `.env` 文件进行配置管理，这样可以：
+项目采用基于 `.env` 文件的现代化配置管理系统，提供以下优势：
 
-- 避免每次更新版本时重新修改配置参数
-- 保护敏感配置信息（`.env` 文件已被 `.gitignore` 忽略）
-- 方便不同环境的配置管理
-- 一个 `git pull` 就能完成版本更新
+### 主要优势
+
+- ✅ **版本更新无忧**: 一个 `git pull` 就完成更新，无需重新配置
+- ✅ **配置集中管理**: 所有配置项统一在 `.env` 文件中，清晰明了
+- ✅ **启动命令简化**: 无需复杂的命令行参数，一键启动
+- ✅ **安全性**: `.env` 文件已被 `.gitignore` 忽略，不会泄露敏感配置
+- ✅ **灵活性**: 支持不同环境的配置管理（开发、测试、生产）
+- ✅ **Docker 兼容**: Docker 和本地环境使用相同的配置方式
+- ✅ **模块化设计**: 配置项按功能分组，便于理解和维护
 
 ## 快速开始
 

docs/installation-guide.md

@@ -71,10 +71,13 @@ pip install -r requirements.txt
 - **FastAPI**: 使用 0.115.12 版本，最新稳定版本，支持 Python 3.8+
   - 包含新的参数模型功能和性能优化
   - 改进的类型提示和 OpenAPI 文档生成
-- **Pydantic**: 使用 2.7.1+ 版本范围，提供强大的数据验证
-- **Uvicorn**: 使用 0.29.0 版本，高性能 ASGI 服务器
-- **Playwright**: 最新版本，用于浏览器自动化
-- **Camoufox**: 反指纹检测浏览器，包含 geoip 数据
+  - 完全兼容 OpenAI API 标准
+- **Pydantic**: 使用 2.7.1+ 版本范围，提供强大的数据验证和类型安全
+- **Uvicorn**: 使用 0.29.0 版本，高性能 ASGI 服务器，支持异步处理
+- **Playwright**: 最新版本，用于浏览器自动化和页面交互
+- **Camoufox**: 反指纹检测浏览器，包含 geoip 数据，提供更好的隐蔽性
+- **WebSockets**: 12.0 版本，用于实时日志传输和状态监控
+- **aiohttp**: 3.9.5 版本，用于异步HTTP客户端操作
 
 ### 4. 下载 Camoufox 浏览器