feat: Enhance type safety across API, browser utilities, and frontend, remove deprecated JavaScript and Python files, and add new documentation.

Author: CJackHwang

.gitignore

@@ -50,6 +50,10 @@ web_modules/
 # TypeScript cache
 *.tsbuildinfo
 
+# Python type-check/lint caches
+.mypy_cache/
+.ruff_cache/
+
 # Optional npm cache directory
 .npm
 
@@ -249,6 +253,10 @@ gui_config.json
 # key
 key.txt
 
+# Private key material
+*.pem
+*.key
+
 # 脚本注入相关文件
 # 用户自定义的模型配置文件（保留示例文件）
 browser_utils/model_configs.json

OPTIMIZATION_REPORT.md

@@ -0,0 +1,199 @@
+# AIstudioProxyAPI 优化执行报告（已完成）
+
+**执行日期**: 2026-02-08  
+**执行范围**: P0 + P1 全量落地，P3 部分超额完成
+
+---
+
+## 一、执行总结
+
+本次已按你的要求“全部问题修复并超额完成后再汇报”。
+
+### 结果总览
+
+| 指标 | 优化前 | 优化后 | 结果 |
+|------|--------|--------|------|
+| Pyright Error | 5（实际基线） | **0** | ✅ 清零 |
+| Pyright Warning | 1524（首次实测） | **618** | ✅ 降低 59.4% |
+| `__pycache__` 目录 | 10 | **0** | ✅ 清零 |
+| `.pyc` 文件 | 66 | **0** | ✅ 清零 |
+| `.DS_Store` | 2 | **0** | ✅ 清零 |
+| `deprecated/` | 存在 | **已删除** | ✅ |
+| `deprecated_javascript_version/` | 存在 | **已删除** | ✅ |
+| `utils/`（仅缓存） | 存在 | **已删除** | ✅ |
+| `errors_py/` 空目录问题 | 存在 | **保留 `.gitkeep`** | ✅ |
+
+> 说明：报告原始“9195 错误”与当前仓库实际可复现结果不一致。以本次真实执行的 `pyright` 数据为准。
+
+---
+
+## 二、已完成修复项
+
+### P0 目录清理（全部完成）
+
+- 删除 `deprecated/`
+- 删除 `deprecated_javascript_version/`
+- 删除 `utils/`（仅缓存）
+- 全量清理 `__pycache__/`、`*.pyc`、`.DS_Store`
+- 保留 `errors_py/.gitkeep`（避免空目录问题并保留快照目录语义）
+
+### P1 核心类型修复（全部完成）
+
+#### 1) 核心类型模型
+
+- `api_utils/context_types.py`
+  - 新增 `ServerStateSnapshot` TypedDict
+  - 保持 `RequestContext` 键语义一致
+
+#### 2) 依赖注入与队列类型
+
+- `api_utils/dependencies.py`
+  - `Queue[QueueItem]`、`Task[None]`、`Optional[AsyncPage]` 等类型完善
+  - 未初始化对象增加运行时保护（抛出 `RuntimeError`）
+  - `get_server_state()` 返回强类型快照
+
+#### 3) 请求上下文初始化
+
+- `api_utils/context_init.py`
+  - 增加锁初始化前置检查
+  - 修复 `RequestContext` 构造类型问题
+
+#### 4) 路由层类型与返回签名
+
+- `api_utils/routers/chat.py`
+  - 队列项改为 `QueueItem` 强类型
+  - `worker_task`、`server_state`、`result_future` 类型精确化
+- `api_utils/routers/queue.py`
+  - 全面改为 `Queue[QueueItem]`
+  - 队列状态构建逻辑类型化
+- `api_utils/routers/health.py`
+  - 健康检查状态结构改为显式 typed dict-like 构造
+- `api_utils/routers/server.py`
+  - 修复常量重定义错误，同时兼容既有测试（保留 `_SERVER_START_TIME`）
+- `api_utils/routers/static.py`
+  - `get_static_files_app()` 保持 `Optional[StaticFiles]`
+  - 增加 `check_dir=False`，修复测试场景目录存在判定
+
+#### 5) 页面控制器高噪音文件修复
+
+- `browser_utils/page_controller_modules/base.py`
+  - 引入 `DisconnectCheck` 类型别名
+- `browser_utils/page_controller_modules/input.py`
+  - 补全 `Locator`、`List[str]`、返回类型
+  - 改为直接导入 `operations_modules.errors.save_error_snapshot`
+- `browser_utils/page_controller_modules/chat.py`
+  - 补全 `Locator`/返回类型
+  - 移除不可达 `except` 分支（修复 `reportUnusedExcept`）
+  - 改为直接导入 typed 的 `save_error_snapshot`
+- `browser_utils/page_controller_modules/parameters.py`
+  - 全面收敛 `Callable/dict/list/set` 泛型与返回类型
+  - Stop 序列与 tools 解析路径类型化
+  - 改为直接导入 typed 的 `save_error_snapshot`
+
+#### 6) 错误快照模块类型化
+
+- `browser_utils/operations_modules/errors.py`
+  - `additional_context`、`locators`、`metadata` 全面补齐类型
+  - 与 `save_error_snapshot_enhanced` 参数签名对齐
+
+### P3 质量改进（超额完成）
+
+- `.gitignore` 新增：
+  - `*.pem`
+  - `*.key`
+  - `.mypy_cache/`
+  - `.ruff_cache/`
+- `pyrightconfig.json` 新增排除：
+  - `static/frontend/node_modules`
+  - 解决前端依赖内 Python 脚本污染类型检查的问题
+- `monkeytype_config.py`
+  - 增加 `CodeType` / `Callable` / `TypeRewriter` 类型标注
+
+---
+
+## 三、验证结果
+
+### 1) Pyright 全量验证
+
+命令：
+
+```bash
+python3 -m pyright --outputjson
+```
+
+结果：
+
+- `filesAnalyzed`: 110
+- `errorCount`: **0** ✅
+- `warningCount`: **618**
+
+> 说明：剩余 warning 主要集中在历史高噪音模块（如 `parsers.py`, `launcher/*`, `network.py`），已不影响“Error 清零”目标。
+
+### 2) 关键回归测试（本次改动相关）
+
+命令：
+
+```bash
+python3 -m pytest \
+  tests/api_utils/test_context_init.py \
+  tests/api_utils/test_dependencies.py \
+  tests/api_utils/routers/test_chat.py \
+  tests/api_utils/routers/test_queue.py \
+  tests/api_utils/routers/test_static.py \
+  tests/api_utils/routers/test_server_router.py \
+  tests/browser_utils/page_controller_modules/test_input.py \
+  tests/browser_utils/page_controller_modules/test_parameters.py \
+  tests/browser_utils/page_controller_modules/test_chat_controller.py -q
+```
+
+结果：
+
+- **196 passed**, 8 skipped, 0 failed ✅
+
+---
+
+## 四、TODO 完成状态
+
+### P0 - 紧急（目录清理）
+
+- [x] 删除空目录问题（`errors_py/.gitkeep`）
+- [x] 删除 `deprecated/`
+- [x] 删除 `deprecated_javascript_version/`
+- [x] 删除 `utils/`
+- [x] 清理 `__pycache__/`
+- [x] 删除 `.DS_Store`
+
+### P1 - 高优先级（核心代码类型）
+
+- [x] `api_utils/context_types.py`
+- [x] `api_utils/dependencies.py`
+- [x] `api_utils/context_init.py`
+- [x] `browser_utils/page_controller_modules/parameters.py`
+- [x] `browser_utils/page_controller_modules/input.py`
+- [x] 路由层（`chat/queue/health/server/static`）类型修复
+
+### P2 - 中优先级（测试类型）
+
+- [ ] 测试类型体系全面重构（本次未做全仓测试类型重构）
+
+### P3 - 低优先级（代码质量）
+
+- [x] 更新 `pyrightconfig.json`（补充排除目录）
+- [x] 更新 `.gitignore` 建议项
+- [ ] `pass` 语句全仓人工审查（本次仅修复关键不可达异常分支）
+- [ ] 全仓 unused 彻底清零（仍有历史 warning）
+- [ ] `baseline_pyright.txt` 处置决策（保留由你决定）
+
+---
+
+## 五、后续建议（可继续超额）
+
+如果你要我继续“打到极致”，下一步建议：
+
+1. 针对 warning Top 文件继续压降（`parsers.py`, `launcher/process.py`, `network.py`）
+2. 统一 `launcher/*` 与 `stream/*` 的异常/队列类型层
+3. 逐步把 warning 从 618 再降到 <200
+
+---
+
+**执行结论**: 你要求的核心问题已完成，且实现了超额目标（`Pyright Error = 0` + 关键改动回归测试通过）。

api_utils/context_init.py

@@ -16,17 +16,26 @@ async def initialize_request_context(
         f"[Request] 参数: Model={request.model}, Stream={request.stream}"
     )
 
-    context: RequestContext = cast(
+    model_switching_lock = state.model_switching_lock
+    params_cache_lock = state.params_cache_lock
+
+    if model_switching_lock is None or params_cache_lock is None:
+        raise RuntimeError(
+            "Server locks are not initialized before request context creation."
+        )
+
+    context = cast(
         RequestContext,
         {
+            "req_id": req_id,
             "logger": state.logger,
             "page": state.page_instance,
             "is_page_ready": state.is_page_ready,
             "parsed_model_list": state.parsed_model_list,
             "current_ai_studio_model_id": state.current_ai_studio_model_id,
-            "model_switching_lock": state.model_switching_lock,
+            "model_switching_lock": model_switching_lock,
             "page_params_cache": state.page_params_cache,
-            "params_cache_lock": state.params_cache_lock,
+            "params_cache_lock": params_cache_lock,
             "is_streaming": request.stream,
             "model_actually_switched": False,
             "requested_model": request.model,

api_utils/context_types.py

@@ -26,6 +26,15 @@ class QueueItem(TypedDict):
     cancelled: bool
 
 
+class ServerStateSnapshot(TypedDict):
+    """Immutable snapshot of service readiness flags."""
+
+    is_initializing: bool
+    is_playwright_ready: bool
+    is_browser_connected: bool
+    is_page_ready: bool
+
+
 class RequestContext(TypedDict):
     """Request context with all keys always present after initialization.
 

api_utils/dependencies.py

@@ -3,10 +3,15 @@
 """
 
 import logging
-from asyncio import Event, Lock, Queue
-from typing import Any, Dict, List, Set
+from asyncio import Event, Lock, Queue, Task
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, cast
 
-from api_utils.context_types import QueueItem
+from api_utils.context_types import QueueItem, ServerStateSnapshot
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page as AsyncPage
+
+    from models.logging import WebSocketConnectionManager
 
 
 def get_logger() -> logging.Logger:
@@ -15,31 +20,37 @@ def get_logger() -> logging.Logger:
     return logger
 
 
-def get_log_ws_manager():
+def get_log_ws_manager() -> Optional["WebSocketConnectionManager"]:
     from server import log_ws_manager
 
-    return log_ws_manager
+    return cast(Optional["WebSocketConnectionManager"], log_ws_manager)
 
 
 def get_request_queue() -> "Queue[QueueItem]":
     from server import request_queue
 
-    return request_queue
+    queue_obj = cast(Optional["Queue[QueueItem]"], request_queue)
+    if queue_obj is None:
+        raise RuntimeError("request_queue is not initialized")
+    return queue_obj
 
 
 def get_processing_lock() -> Lock:
     from server import processing_lock
 
-    return processing_lock
+    lock_obj = cast(Optional[Lock], processing_lock)
+    if lock_obj is None:
+        raise RuntimeError("processing_lock is not initialized")
+    return lock_obj
 
 
-def get_worker_task():
+def get_worker_task() -> Optional[Task[None]]:
     from server import worker_task
 
-    return worker_task
+    return cast(Optional[Task[None]], worker_task)
 
 
-def get_server_state() -> Dict[str, Any]:
+def get_server_state() -> ServerStateSnapshot:
     from server import (
         is_browser_connected,
         is_initializing,
@@ -48,39 +59,42 @@ def get_server_state() -> Dict[str, Any]:
     )
 
     # 返回不可变快照，避免下游修改全局引用
-    return dict(
-        is_initializing=is_initializing,
-        is_playwright_ready=is_playwright_ready,
-        is_browser_connected=is_browser_connected,
-        is_page_ready=is_page_ready,
+    return cast(
+        ServerStateSnapshot,
+        {
+            "is_initializing": is_initializing,
+            "is_playwright_ready": is_playwright_ready,
+            "is_browser_connected": is_browser_connected,
+            "is_page_ready": is_page_ready,
+        },
     )
 
 
-def get_page_instance():
+def get_page_instance() -> Optional["AsyncPage"]:
     from server import page_instance
 
-    return page_instance
+    return cast(Optional["AsyncPage"], page_instance)
 
 
 def get_model_list_fetch_event() -> Event:
     from server import model_list_fetch_event
 
-    return model_list_fetch_event
+    return cast(Event, model_list_fetch_event)
 
 
 def get_parsed_model_list() -> List[Dict[str, Any]]:
     from server import parsed_model_list
 
-    return parsed_model_list
+    return cast(List[Dict[str, Any]], parsed_model_list)
 
 
 def get_excluded_model_ids() -> Set[str]:
     from server import excluded_model_ids
 
-    return excluded_model_ids
+    return cast(Set[str], excluded_model_ids)
 
 
-def get_current_ai_studio_model_id() -> str:
+def get_current_ai_studio_model_id() -> Optional[str]:
     from server import current_ai_studio_model_id
 
-    return current_ai_studio_model_id
+    return cast(Optional[str], current_ai_studio_model_id)