Merge pull request #284 from NikkeTryHard/main

feat: Logging overhaul, UI selector robustness, and thinking mode support

Author: NikkeTryHard

.env.example

@@ -1,210 +1,180 @@
-# AI Studio Proxy API 配置文件示例
+# AI Studio Proxy API Configuration Template
 # 复制此文件为 .env 并根据需要修改配置
+# Copy this file to .env and modify as needed
 
 # =============================================================================
-# 服务端口配置
+# 1. 服务端口配置 (Server Port Configuration)
 # =============================================================================
 
-# FastAPI 服务端口
+# FastAPI 主服务端口
+# The port where the main OpenAI-compatible API will listen.
 PORT=2048
 
-# GUI 启动器默认端口配置
+# GUI 启动器默认端口配置 (Launcher Defaults)
+# 这些值仅用于启动器显示的默认建议，实际运行端口由上面的 PORT 决定。
 DEFAULT_FASTAPI_PORT=2048
 DEFAULT_CAMOUFOX_PORT=9222
 
-# Camoufox WebSocket 端点捕获超时（秒）
-ENDPOINT_CAPTURE_TIMEOUT=45
-
-# 流式代理服务配置
-STREAM_PORT=3120
-# 设置为 0 禁用流式代理服务
-
 # =============================================================================
-# 代理配置
+# 2. 认证配置 (Authentication Configuration)
 # =============================================================================
 
-# HTTP/HTTPS 代理设置
-# HTTP_PROXY=http://127.0.0.1:7890
-# HTTPS_PROXY=http://127.0.0.1:7890
-
-# 统一代理配置 (优先级高于 HTTP_PROXY/HTTPS_PROXY)
-UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
+# 自动保存认证信息 (Auto Save Auth)
+# 设置为 true 以在每次成功登录后自动保存认证状态 (cookies/localStorage)，无需人工确认。
+# 强烈建议在 headless 模式下开启，以便长期运行。
+# Default: false
+AUTO_SAVE_AUTH=false
 
-# 代理绕过列表 (用分号分隔)
-# NO_PROXY=localhost;127.0.0.1;*.local
+# 认证保存超时时间 (seconds)
+# 在 debug 模式下等待用户输入保存文件名的超时时间。超时后将使用默认文件名。
+# Default: 30
+AUTH_SAVE_TIMEOUT=30
 
 # =============================================================================
-# 日志配置
+# 3. 浏览与启动配置 (Browser & Model Configuration)
 # =============================================================================
 
-# 服务器日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
-SERVER_LOG_LEVEL=INFO
+# 启动模式 (Launch Mode)
+# 选项 (Options):
+# - normal: 标准模式，同 debug。
+# - debug: 显示浏览器窗口，允许交互。适合初次设置和调试。
+# - headless: 无头模式，无浏览器窗口。适合服务器部署。需先保存认证文件。
+# - virtual_display: (仅 Linux) 使用 Xvfb 虚拟显示。比纯 headless 更稳定被识别。
+# - direct_debug_no_browser: 不启动浏览器，仅用于调试 API 逻辑。
+LAUNCH_MODE=normal
 
-# 是否重定向 print 输出到日志
-SERVER_REDIRECT_PRINT=false
+# Camoufox WebSocket 端点 (仅高级用户)
+# 如果您想连接到现有的外部 Camoufox/Chrome 实例。
+# CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222
 
-# 启用调试日志
-DEBUG_LOGS_ENABLED=false
+# 快速启动 (Direct Launch)
+# 设置为 true 跳过启动器的交互式选择菜单，直接使用 .env 配置启动。
+DIRECT_LAUNCH=false
 
-# 启用跟踪日志
-TRACE_LOGS_ENABLED=false
+# 仅收集当前用户消息中的附件
+# 设置为 true 则只处理当前请求中的附件，忽略历史消息中的附件（节省带宽）。
+ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=false
 
 # =============================================================================
-# 认证配置
+# 4. 代理配置 (Proxy Configuration)
 # =============================================================================
 
-# 自动保存认证信息
-AUTO_SAVE_AUTH=false
-
-# 认证保存超时时间 (秒)
-AUTH_SAVE_TIMEOUT=30
+# 统一代理配置 (Unified Proxy)
+# 推荐使用此设置。它会同时配置 HTTP_PROXY, HTTPS_PROXY 以及浏览器内部代理。
+# 支持 http:// 和 socks5:// 协议。
+UNIFIED_PROXY_CONFIG=http://127.0.0.1:7890
 
-# 自动确认登录
-AUTO_CONFIRM_LOGIN=true
+# 传统代理设置 (Legacy Proxy Settings)
+# 仅在未设置 UNIFIED_PROXY_CONFIG 时生效。
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
 
-# 仅收集当前用户消息中的附件（true/false）
-ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=false
+# 代理绕过列表
+# NO_PROXY=localhost,127.0.0.1,::1
 
 # =============================================================================
-# 浏览器配置
+# 5. 日志与调试 (Logging & Debugging)
 # =============================================================================
 
-# Camoufox WebSocket 端点
-# CAMOUFOX_WS_ENDPOINT=ws://127.0.0.1:9222
+# 服务器日志级别
+# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+SERVER_LOG_LEVEL=INFO
 
-# 启动模式 (normal, headless, virtual_display, direct_debug_no_browser)
-LAUNCH_MODE=normal
+# 打印重定向
+# 设置为 true 将 server.py 的所有 print 输出重定向到日志文件。
+# 生产环境建议开启，调试时建议关闭以在控制台查看实时输出。
+SERVER_REDIRECT_PRINT=false
 
-# 快速启动
-DIRECT_LAUNCH=false
+# 扩展日志开关
+# 启用详细的调试日志 (可能会包含敏感信息)
+DEBUG_LOGS_ENABLED=false
+# 启用极详细的追踪日志 (会产生大量日志)
+TRACE_LOGS_ENABLED=false
+
+# JSON 结构化日志 (Structured JSON Logging)
+# 设置为 true 以输出 JSON 格式日志，适用于 ELK/Datadog 等日志聚合工具。
+# Default: false
+JSON_LOGS=false
+
+# 日志文件轮换配置 (Log Rotation Configuration)
+# 单个日志文件最大字节数 (默认 10MB)
+LOG_FILE_MAX_BYTES=10485760
+# 保留的日志备份文件数量 (默认 5 个)
+LOG_FILE_BACKUP_COUNT=5
 
 # =============================================================================
-# API 默认参数配置
+# 6. API 默认参数 (API Defaults)
 # =============================================================================
+# 当 API 请求未明确指定参数时使用的默认值。
 
-# 默认温度值 (0.0-2.0)
+# 采样温度 (越高越随机)
 DEFAULT_TEMPERATURE=1.0
-
-# 默认最大输出令牌数
+# 最大输出 Token 数
 DEFAULT_MAX_OUTPUT_TOKENS=65536
-
-# 默认 Top-P 值 (0.0-1.0)
+# Top-P 采样 (核采样)
 DEFAULT_TOP_P=0.95
-
-# 默认停止序列 (JSON 数组格式)
+# 停止序列 (JSON 数组格式)
 DEFAULT_STOP_SEQUENCES=["用户:"]
 
-# 是否在处理请求时自动打开并使用 "URL Context" 功能,此工具功能详情可参考:https://ai.google.dev/gemini-api/docs/url-context
-ENABLE_URL_CONTEXT=false
+# 思考模型配置 (Thinking Models)
+# 适用于 gemini-2.0-flash-thinking 等支持思考过程的模型
 
-# 是否默认启用 "指定思考预算" 功能 (true/false),不启用时模型一般将自行决定思考预算
-# 当 API 请求中未提供 reasoning_effort 参数时将使用此值。
+# 是否默认启用 "Thinking Budget"
 ENABLE_THINKING_BUDGET=false
 
-# "指定思考预算量" 的默认值 (token)
-# 当 API 请求中未提供 reasoning_effort 参数时，将使用此值。
+# 默认思考预算 (Token count)
 DEFAULT_THINKING_BUDGET=8192
 
-# "指定思考等级" 的默认值 (high/low)
-# 仅适用于 gemini-3-pro-preview 等使用思考等级的模型。
-# 当 API 请求中未提供 reasoning_effort 参数时，将使用此值。
+# 默认思考等级 (Thinking Level)
+# Options: high, low (仅特定模型支持)
 DEFAULT_THINKING_LEVEL=high
 
-# 是否默认启用 "Google Search" 功能 (true/false)
-# 当 API 请求中未提供 tools 参数时，将使用此设置作为 Google Search 的默认开关状态。
+# 工具配置
+# 是否默认启用 Google Search
 ENABLE_GOOGLE_SEARCH=false
+# 是否默认启用 URL Context 分析
+ENABLE_URL_CONTEXT=false
 
 # =============================================================================
-# 超时配置 (毫秒)
+# 7. 高级超时配置 (Advanced Timeouts)
 # =============================================================================
+# 单位均为毫秒 (ms)，除非另有说明。仅供高级调优，一般无需修改。
 
-# 响应完成总超时时间
+# 响应总超时 (5分钟)
 RESPONSE_COMPLETION_TIMEOUT=300000
 
-# 初始等待时间
-INITIAL_WAIT_MS_BEFORE_POLLING=500
-
 # 轮询间隔
 POLLING_INTERVAL=300
 POLLING_INTERVAL_STREAM=180
 
-# 静默超时
+# 静默超时 (60秒无响应则断开)
 SILENCE_TIMEOUT_MS=60000
 
-# 页面操作超时
-POST_SPINNER_CHECK_DELAY_MS=500
-FINAL_STATE_CHECK_TIMEOUT_MS=1500
-POST_COMPLETION_BUFFER=700
-
-# 清理聊天相关超时
-CLEAR_CHAT_VERIFY_TIMEOUT_MS=5000
-CLEAR_CHAT_VERIFY_INTERVAL_MS=2000
-
-# 点击和剪贴板操作超时
+# 页面交互超时
 CLICK_TIMEOUT_MS=3000
-CLIPBOARD_READ_TIMEOUT_MS=3000
-
-# 元素等待超时
 WAIT_FOR_ELEMENT_TIMEOUT_MS=10000
 
-# 流相关配置
-PSEUDO_STREAM_DELAY=0.01
-
 # =============================================================================
-# GUI 启动器配置
+# 8. 其他系统配置 (Misc System Config)
 # =============================================================================
 
-# GUI 默认代理地址
-GUI_DEFAULT_PROXY_ADDRESS=http://127.0.0.1:7890
-
-# GUI 默认流式代理端口
-GUI_DEFAULT_STREAM_PORT=3120
-
-# GUI 默认 Helper 端点
-GUI_DEFAULT_HELPER_ENDPOINT=
-
-# =============================================================================
-# 脚本注入配置
-# =============================================================================
+# 流式代理服务端口 (Stream Proxy)
+# 用于处理流式响应的内部代理服务。设置为 0 可禁用（不推荐）。
+STREAM_PORT=3120
 
-# 是否启用油猴脚本注入功能
+# 脚本注入 (Userscript Injection)
+# 允许加载自定义 JavaScript 以扩展页面功能（如加载额外模型列表）。
 ENABLE_SCRIPT_INJECTION=false
-
-# 油猴脚本文件路径（相对于项目根目录）
-# 模型数据直接从此脚本文件中解析，无需额外配置文件
 USERSCRIPT_PATH=browser_utils/more_models.js
 
-# =============================================================================
-# 其他配置
-# =============================================================================
+# Camoufox WebSocket 捕获超时 (秒)
+ENDPOINT_CAPTURE_TIMEOUT=45
 
-# 模型名称
+# 模型配置
 MODEL_NAME=AI-Studio_Proxy_API
-
-# 聊天完成 ID 前缀
 CHAT_COMPLETION_ID_PREFIX=chatcmpl-
-
-# 默认回退模型 ID
-DEFAULT_FALLBACK_MODEL_ID=no model list
-
-# 排除模型文件名
-EXCLUDED_MODELS_FILENAME=excluded_models.txt
-
-# AI Studio URL 模式
 AI_STUDIO_URL_PATTERN=aistudio.google.com/
 
-# 模型端点 URL 包含字符串
-MODELS_ENDPOINT_URL_CONTAINS=MakerSuiteService/ListModels
-
-# 用户输入标记符
-USER_INPUT_START_MARKER_SERVER=__USER_INPUT_START__
-USER_INPUT_END_MARKER_SERVER=__USER_INPUT_END__
-
-# =============================================================================
-# 流状态配置
-# =============================================================================
-
-# 流超时日志状态配置
-STREAM_MAX_INITIAL_ERRORS=3
-STREAM_WARNING_INTERVAL_AFTER_SUPPRESS=60.0
-STREAM_SUPPRESS_DURATION_AFTER_INITIAL_BURST=400.0
+# 排除模型列表文件 (相对于项目根目录)
+# 此文件中列出的模型将不会在 /v1/models 端点中返回
+EXCLUDED_MODELS_FILENAME=excluded_models.txt

api_utils/app.py

@@ -172,6 +172,19 @@ async def _shutdown_resources() -> None:
 
     if state.STREAM_PROCESS:
         state.STREAM_PROCESS.terminate()
+        # Wait for process to terminate with timeout to avoid atexit hang
+        state.STREAM_PROCESS.join(timeout=3)
+        if state.STREAM_PROCESS.is_alive():
+            logger.warning("STREAM proxy did not terminate, killing...")
+            state.STREAM_PROCESS.kill()
+            state.STREAM_PROCESS.join(timeout=1)
+        # Close the queue to prevent resource leaks
+        if state.STREAM_QUEUE:
+            try:
+                state.STREAM_QUEUE.close()
+                state.STREAM_QUEUE.join_thread()
+            except Exception:
+                pass
         logger.info("STREAM proxy terminated.")
 
     if state.worker_task and not state.worker_task.done():

api_utils/queue_worker.py

@@ -13,11 +13,10 @@
 from fastapi.responses import JSONResponse, StreamingResponse
 from playwright.async_api import Locator
 
+from api_utils.context_types import QueueItem
 from logging_utils import set_request_id, set_source
 from models import ChatCompletionRequest
 
-from api_utils.context_types import QueueItem
-
 from .error_utils import (
     client_cancelled,
     client_disconnected,