docs: verify and fix documentation accuracy against codebase (#295)

* docs: comprehensive documentation update for v4.0.3 changes

Updated files:
- advanced-configuration.md: Add SKIP_FRONTEND_BUILD, model_capabilities.json section, port kill security note
- architecture-guide.md: Add model_capabilities.json and all new routers
- development-guide.md: Add Node.js prereq, frontend dev section with npm commands
- env-variables-reference.md: Add SKIP_FRONTEND_BUILD variable
- environment-configuration.md: Add SKIP_FRONTEND_BUILD to startup config
- installation-guide.md: Update Node.js requirement for frontend development

* docs: update and refine various documentation files for improved clarity

Author: NikkeTryHard

README.md

@@ -15,17 +15,16 @@
 - **智能模型切换**: 动态切换 AI Studio 模型，完整参数控制
 - **反指纹检测**: Camoufox 浏览器降低被检测风险
 - **现代化 Web UI**: 内置测试界面、状态监控、API 密钥管理
-- **图形界面启动器**: GUI 启动器简化配置和进程管理
 - **脚本注入 v3.0**: Playwright 原生网络拦截，支持油猴脚本动态挂载
 
 ## 系统要求
 
-| 组件 | 要求 | 推荐 |
-|------|------|------|
-| **Python** | ≥3.9, <4.0 | 3.10+ 或 3.11+ |
-| **依赖管理** | Poetry | 最新版本 |
-| **内存** | ≥2GB | ≥4GB |
-| **网络** | 稳定互联网 | 可配置代理 |
+| 组件         | 要求       | 推荐           |
+| ------------ | ---------- | -------------- |
+| **Python**   | ≥3.9, <4.0 | 3.10+ 或 3.11+ |
+| **依赖管理** | Poetry     | 最新版本       |
+| **内存**     | ≥2GB       | ≥4GB           |
+| **网络**     | 稳定互联网 | 可配置代理     |
 
 ---
 
@@ -81,7 +80,6 @@ graph TD
     end
 
     subgraph "启动与配置"
-        GUI_Launch["gui_launcher.py"]
         CLI_Launch["launch_camoufox.py"]
         EnvConfig[".env 配置"]
     end
@@ -97,7 +95,7 @@ graph TD
         AI_Studio["Google AI Studio"]
     end
 
-    User --> GUI_Launch & CLI_Launch
+    User --> CLI_Launch
     API_Client & WebUI --> FastAPI_App
     FastAPI_App --> PageController & StreamProxy
     PageController --> CamoufoxInstance --> AI_Studio
@@ -108,12 +106,11 @@ graph TD
 
 ## 运行模式
 
-| 命令 | 说明 | 场景 |
-|------|------|------|
-| `python gui_launcher.py` | GUI 启动器 | 新手、可视化配置 |
-| `python launch_camoufox.py --headless` | 无头模式 | 日常使用、服务器 |
-| `python launch_camoufox.py --debug` | 调试模式 | 首次认证、故障排查 |
-| `python launch_camoufox.py --virtual-display` | 虚拟显示 | Linux 无 GUI 环境 |
+| 命令                                          | 说明     | 场景               |
+| --------------------------------------------- | -------- | ------------------ |
+| `python launch_camoufox.py --headless`        | 无头模式 | 日常使用、服务器   |
+| `python launch_camoufox.py --debug`           | 调试模式 | 首次认证、故障排查 |
+| `python launch_camoufox.py --virtual-display` | 虚拟显示 | Linux 无 GUI 环境  |
 
 ---
 
@@ -128,12 +125,12 @@ nano .env
 
 ### 核心配置
 
-| 配置 | 默认值 | 说明 |
-|------|--------|------|
-| `PORT` | 2048 | FastAPI 服务端口 |
-| `STREAM_PORT` | 3120 | 流式代理端口 (0 禁用) |
-| `UNIFIED_PROXY_CONFIG` | - | HTTP/HTTPS 代理 |
-| `SERVER_LOG_LEVEL` | INFO | 日志级别 |
+| 配置                   | 默认值 | 说明                  |
+| ---------------------- | ------ | --------------------- |
+| `PORT`                 | 2048   | FastAPI 服务端口      |
+| `STREAM_PORT`          | 3120   | 流式代理端口 (0 禁用) |
+| `UNIFIED_PROXY_CONFIG` | -      | HTTP/HTTPS 代理       |
+| `SERVER_LOG_LEVEL`     | INFO   | 日志级别              |
 
 > **详细配置**: [环境变量完整参考](docs/env-variables-reference.md)
 
@@ -160,26 +157,30 @@ bash update.sh
 ## 📚 文档
 
 ### 快速上手
+
 - **[快速开始指南](docs/quick-start-guide.md)** - 15 分钟快速部署 🎯
 - [安装指南](docs/installation-guide.md) - 详细安装步骤
 - [认证设置指南](docs/authentication-setup.md) - 首次认证设置
 - [日常运行指南](docs/daily-usage.md) - 日常使用
 
 ### 功能使用
+
 - [API 使用指南](docs/api-usage.md) - API 端点和配置
 - **[OpenAI 兼容性说明](docs/openai-compatibility.md)** - 与 OpenAI API 差异 🔄
 - [客户端集成示例](docs/client-examples.md) - 代码示例 💻
 - [Web UI 使用指南](docs/webui-guide.md) - Web 界面功能
 - [脚本注入指南](docs/script_injection_guide.md) - 油猴脚本功能 (v3.0)
 
 ### 高级配置
+
 - [环境变量配置指南](docs/environment-configuration.md) - 配置管理 ⭐
 - [环境变量完整参考](docs/env-variables-reference.md) - 所有配置项 📋
 - [流式处理模式详解](docs/streaming-modes.md) - 三层响应机制
 - [高级配置指南](docs/advanced-configuration.md) - 高级功能
 - [故障排除指南](docs/troubleshooting.md) - 问题解决
 
 ### 开发相关
+
 - [项目架构指南](docs/architecture-guide.md) - 模块化架构
 - [开发者指南](docs/development-guide.md) - Poetry、Pyright 工作流
 

docs/architecture-guide.md

@@ -21,13 +21,19 @@ AIstudioProxyAPI/
 │   ├── app.py                 # 应用入口和生命周期管理
 │   ├── routers/               # API 路由（按职责拆分）
 │   │   ├── api_keys.py        # /api/keys* 密钥管理
+│   │   ├── auth_files.py      # /api/auth-files* 认证文件管理
 │   │   ├── chat.py            # /v1/chat/completions
 │   │   ├── health.py          # /health 健康检查
+│   │   ├── helper.py          # /api/helper* Helper 服务配置
 │   │   ├── info.py            # /api/info 信息端点
 │   │   ├── logs_ws.py         # /ws/logs WebSocket 日志
+│   │   ├── model_capabilities.py  # /api/model-capabilities
 │   │   ├── models.py          # /v1/models 模型列表
+│   │   ├── ports.py           # /api/ports* 端口配置
+│   │   ├── proxy.py           # /api/proxy* 代理配置
 │   │   ├── queue.py           # /v1/queue, /v1/cancel
-│   │   └── static.py          # /, /webui.css, /webui.js
+│   │   ├── server.py          # /api/server* 服务器控制
+│   │   └── static.py          # /, /assets/* React SPA
 │   ├── request_processor.py   # 请求处理核心逻辑
 │   ├── queue_worker.py        # 异步队列工作器
 │   ├── response_generators.py # SSE 响应生成器
@@ -41,10 +47,13 @@ AIstudioProxyAPI/
 │   ├── sse.py                 # SSE 流式响应处理
 │   ├── utils.py               # 通用工具函数
 │   └── utils_ext/             # 扩展工具模块
-│       ├── attachments.py     # 附件处理
-│       ├── formatting.py      # 格式化工具
+│       ├── files.py           # 文件/附件处理
+│       ├── helper.py          # Helper 服务工具
 │       ├── prompts.py         # 提示词处理
-│       ├── streaming.py       # 流式处理工具
+│       ├── stream.py          # 流式处理工具
+│       ├── string_utils.py    # 字符串工具
+│       ├── tokens.py          # Token 计算
+│       ├── tools_execution.py # 工具执行
 │       └── validation.py      # 请求验证
 │
 ├── browser_utils/              # 浏览器自动化模块
@@ -67,7 +76,7 @@ AIstudioProxyAPI/
 │   │   ├── interactions.py    # 页面交互
 │   │   └── errors.py          # 错误处理
 │   ├── model_management.py    # 模型管理
-│   ├── script_manager.py      # 脚本注入管理 (v3.0)
+│   ├── operations.py          # 操作聚合入口
 │   ├── debug_utils.py         # 调试工具
 │   ├── thinking_normalizer.py # 思考过程标准化
 │   └── more_models.js         # 油猴脚本模板
@@ -76,7 +85,9 @@ AIstudioProxyAPI/
 │   ├── settings.py            # 主要设置和环境变量
 │   ├── constants.py           # 系统常量定义
 │   ├── timeouts.py            # 超时配置
-│   └── selectors.py           # CSS 选择器定义
+│   ├── selectors.py           # CSS 选择器定义
+│   ├── selector_utils.py      # 选择器工具函数
+│   └── model_capabilities.json # 模型能力配置
 │
 ├── models/                     # 数据模型定义
 │   ├── chat.py                # 聊天相关模型
@@ -96,6 +107,8 @@ AIstudioProxyAPI/
 │   ├── config.py              # 启动配置处理
 │   ├── checks.py              # 环境与依赖检查
 │   ├── process.py             # Camoufox 进程管理
+│   ├── frontend_build.py      # 前端构建检查
+│   ├── internal.py            # 内部工具
 │   ├── logging_setup.py       # 日志配置
 │   └── utils.py               # 启动器工具
 │
@@ -104,8 +117,9 @@ AIstudioProxyAPI/
 │   └── grid_logger.py         # 网格日志器
 │
 ├── server.py                   # 应用入口点
-├── gui_launcher.py             # GUI 启动器
-├── launch_camoufox.py          # 命令行启动器
+├── launch_camoufox.py          # 命令行启动器（主入口）
+├── deprecated/                 # 已废弃的模块
+│   └── gui_launcher.py         # [已废弃] GUI 启动器
 └── pyproject.toml              # Poetry 配置
 ```
 
@@ -170,11 +184,13 @@ AIstudioProxyAPI/
 | `scripts.py` | UserScript 脚本注入              |
 | `debug.py`   | 调试监听器设置                   |
 
-#### script_manager.py - 脚本注入 v3.0
+#### 脚本注入机制
 
-- Playwright 原生网络拦截
-- 油猴脚本解析和注入
-- 模型数据同步
+脚本注入通过 `initialization/network.py` 实现：
+
+- Playwright 原生路由拦截 `/api/models`
+- 从油猴脚本 (`more_models.js`) 解析模型数据
+- 模型数据自动同步到页面
 
 ### 3. stream/ - 流式代理服务
 
@@ -257,6 +273,7 @@ AIstudioProxyAPI/
 | `constants.py`            | 系统常量定义                                   |
 | `timeouts.py`             | 超时配置                                       |
 | `selectors.py`            | CSS 选择器定义                                 |
+| `selector_utils.py`       | 选择器工具函数                                 |
 | `model_capabilities.json` | 模型能力配置（思考类型、Google Search 支持等） |
 
 > **注意**: `model_capabilities.json` 是外部化的 JSON 配置文件，用于定义各模型的能力参数。

docs/authentication-setup.md

@@ -1,6 +1,6 @@
 # 首次运行与认证设置指南
 
-为了避免每次启动都手动登录 AI Studio，你需要先通过 [`launch_camoufox.py --debug`](../launch_camoufox.py) 模式或 [`gui_launcher.py`](../gui_launcher.py) 的有头模式运行一次来生成认证文件。
+为了避免每次启动都手动登录 AI Studio，你需要先通过 [`launch_camoufox.py --debug`](../launch_camoufox.py) 模式运行一次来生成认证文件。
 
 ## 认证文件的重要性
 
@@ -61,9 +61,14 @@ python launch_camoufox.py --debug --server-port 2048 --stream-port 0 --helper ''
 6.  **激活文件**: **将 `auth_profiles/saved/` 下新生成的 `.json` 文件移动到 `auth_profiles/active/` 目录。** 确保 `active` 目录下只有一个 `.json` 文件。
 7.  可以按 `Ctrl+C` 停止 `--debug` 模式的运行。
 
-## 方法二：通过 GUI 启动有头模式 (推荐)
+## 方法二：通过 GUI 启动有头模式 (已废弃)
 
-1.  运行 `python gui_launcher.py`。
+> [!WARNING]
+> GUI 启动器 (`gui_launcher.py`) 已移至 `deprecated/` 目录。请使用上面的命令行方式。
+
+以下步骤仅供参考，不再推荐使用：
+
+1.  运行 `python deprecated/gui_launcher.py`。
 2.  在 "认证文件管理" 区域，点击 **"管理认证文件"** 按钮。
 3.  在弹出的窗口中，点击 **"创建新认证文件"** 按钮。
 4.  输入想要保存的文件名（例如 `account1`），点击确定。
@@ -83,7 +88,7 @@ python launch_camoufox.py --debug --server-port 2048 --stream-port 0 --helper ''
 **认证文件会过期!** Google 的登录状态不是永久有效的。当无头模式启动失败并报告认证错误或重定向到登录页时，意味着 `active` 目录下的认证文件已失效。你需要：
 
 1. 删除 `active` 目录下的旧文件。
-2. 重新执行上面的 **【通过命令行运行 Debug 模式】** 或 **【通过 GUI 启动有头模式】** 步骤，生成新的认证文件。
+2. 重新执行上面的 **【通过命令行运行 Debug 模式】** 步骤，生成新的认证文件。
 3. 将新生成的 `.json` 文件再次移动到 `active` 目录下。
 
 ## 重要提示

docs/daily-usage.md

@@ -6,7 +6,6 @@
 
 完成首次认证设置后，您可以选择以下方式进行日常运行：
 
-- **图形界面启动**: 使用 [`gui_launcher.py`](../gui_launcher.py) 提供的现代化 GUI 界面 (支持一键创建认证)
 - **命令行启动**: 直接使用 [`launch_camoufox.py`](../launch_camoufox.py) 命令行工具
 - **Docker 部署**: 使用容器化部署方式
 
@@ -24,9 +23,6 @@
 ### 基本启动（推荐）
 
 ```bash
-# 图形界面启动（推荐新手）
-python gui_launcher.py
-
 # 命令行启动（推荐日常使用）
 python launch_camoufox.py --headless
 
@@ -36,8 +32,6 @@ python launch_camoufox.py --debug
 
 **就这么简单！** 所有配置都在 `.env` 文件中预设好了，无需复杂的命令行参数。
 
-> **💡 提示**: 如果您是首次使用，强烈推荐使用 **图形界面启动 (`gui_launcher.py`)**。它提供了一个向导式的"创建新认证文件"功能，可以自动处理登录和文件保存，比命令行更直观。
-
 ## 启动器说明
 
 ### 关于 `--virtual-display` (Linux 虚拟显示无头模式)
@@ -152,35 +146,23 @@ python launch_camoufox.py --headless --stream-port 0 --helper ''
 
 在此模式下，主服务器将仅通过 Playwright 与 AI Studio 页面交互 (模拟点击"编辑"或"复制"按钮) 来获取响应。这是传统的后备方法。
 
-## 使用图形界面启动器
-
-项目提供了一个基于 Tkinter 的图形用户界面 (GUI) 启动器：[`gui_launcher.py`](../gui_launcher.py)。
+## 图形界面启动器 (已废弃)
 
-### 启动 GUI
+> [!WARNING]
+> GUI 启动器 (`gui_launcher.py`) 已移至 `deprecated/` 目录。推荐使用命令行方式 `python launch_camoufox.py`。
 
-```bash
-python gui_launcher.py
-```
+项目曾提供一个基于 Tkinter 的图形用户界面 (GUI) 启动器，但现已废弃。
 
-### GUI 功能
+该工具的功能可通过以下命令行改写实现：
 
-- **服务端口配置**: 指定 FastAPI 服务器监听的端口号 (默认为 2048)。
-- **端口进程管理**: 查询和停止指定端口上的进程。
-- **认证文件管理**:
-  - **创建新认证**: 引导式流程，打开浏览器登录并自动保存 Cookie 到文件。
-  - **切换认证**: 在多个已保存的认证文件（Profile）之间快速切换。
-- **启动选项**:
-  1. **启动有头模式 (Debug, 交互式)**: 对应 `python launch_camoufox.py --debug`
-  2. **启动无头模式 (后台独立运行)**: 对应 `python launch_camoufox.py --headless`
-- **本地 LLM 模拟服务**: 启动和管理本地 LLM 模拟服务 (基于 [`llm.py`](../llm.py))
-- **状态与日志**: 显示服务状态和实时日志
+- **有头模式**: `python launch_camoufox.py --debug`
+- **无头模式**: `python launch_camoufox.py --headless`
 
 ### 使用建议
 
-- **首次运行**: 点击"管理认证文件" -> "创建新认证文件"，跟随指引完成登录。
-- **日常后台运行**: 确保认证文件已激活，然后点击"启动无头模式"。
-- **故障排查**: 使用"启动有头模式"观察浏览器行为。
-- 需要详细日志或调试：直接使用命令行 [`launch_camoufox.py`](../launch_camoufox.py)
+- **首次运行**: 使用 `python launch_camoufox.py --debug` 并手动完成登录
+- **日常后台运行**: `python launch_camoufox.py --headless`
+- **故障排查**: 使用 `--debug` 模式观察浏览器行为
 
 ## 重要注意事项
 

docs/env-variables-reference.md

@@ -147,6 +147,30 @@
 - **示例**: `TRACE_LOGS_ENABLED=true`
 - **说明**: 启用最详细的跟踪级别日志，用于深度调试
 
+### JSON_LOGS
+
+- **用途**: 启用 JSON 结构化日志
+- **类型**: 布尔值
+- **默认值**: `false`
+- **示例**: `JSON_LOGS=true`
+- **说明**: 启用后以 JSON 格式输出日志，适用于 ELK/Datadog 等日志聚合工具
+
+### LOG_FILE_MAX_BYTES
+
+- **用途**: 单个日志文件最大字节数
+- **类型**: 整数
+- **默认值**: `10485760` (10MB)
+- **示例**: `LOG_FILE_MAX_BYTES=20971520`
+- **说明**: 日志文件达到此大小后会自动轮换
+
+### LOG_FILE_BACKUP_COUNT
+
+- **用途**: 保留的日志备份文件数量
+- **类型**: 整数
+- **默认值**: `5`
+- **示例**: `LOG_FILE_BACKUP_COUNT=10`
+- **说明**: 轮换时保留的备份日志文件数量
+
 ---
 
 ## 认证配置
@@ -270,14 +294,23 @@
 - **示例**: `DEFAULT_THINKING_BUDGET=16384`
 - **说明**: 当 API 请求未提供 `reasoning_effort` 参数时使用此值
 
-### DEFAULT_THINKING_LEVEL
+### DEFAULT_THINKING_LEVEL_PRO
 
-- **用途**: 默认思考等级
+- **用途**: Gemini Pro 模型的默认思考等级
 - **类型**: 字符串
 - **默认值**: `high`
 - **可选值**: `high`, `low`
-- **示例**: `DEFAULT_THINKING_LEVEL=low`
-- **说明**: 仅适用于 gemini-3-pro-preview 等使用思考等级的模型。当 API 请求中未提供 `reasoning_effort` 参数时使用此值
+- **示例**: `DEFAULT_THINKING_LEVEL_PRO=low`
+- **说明**: 适用于 gemini-3-pro-preview 等 Pro 模型。当 API 请求中未提供 `reasoning_effort` 参数时使用此值
+
+### DEFAULT_THINKING_LEVEL_FLASH
+
+- **用途**: Gemini Flash 模型的默认思考等级
+- **类型**: 字符串
+- **默认值**: `high`
+- **可选值**: `high`, `medium`, `low`, `minimal`
+- **示例**: `DEFAULT_THINKING_LEVEL_FLASH=medium`
+- **说明**: 适用于 gemini-3-flash-preview 等 Flash 模型。当 API 请求中未提供 `reasoning_effort` 参数时使用此值
 
 ### ENABLE_GOOGLE_SEARCH
 
@@ -419,6 +452,9 @@
 
 ## GUI 启动器配置
 
+> [!WARNING]
+> GUI 启动器 (`gui_launcher.py`) 已移至 `deprecated/` 目录。以下配置仅供参考。
+
 ### GUI_DEFAULT_PROXY_ADDRESS
 
 - **用途**: GUI 启动器的默认代理地址