Skip to content

Commit 3bf8d13

Browse files
Mag1cFallMag1cFall
committed
Update docs
1 parent 83e6ad0 commit 3bf8d13

File tree

1 file changed

+232
-0
lines changed

1 file changed

+232
-0
lines changed

‎docs/project-structure.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# AIStudio2API 源码结构文档
2+
3+
## 项目概览
4+
5+
AIStudio2API 是一个高性能代理服务，将 Google AI Studio 网页界面转换为 OpenAI 兼容格式 API。
6+
7+
---
8+
9+
## 根目录文件
10+
11+
| 文件 | 描述 |
12+
|------|------|
13+
| `README.md` | 项目中文文档 |
14+
| `README_en.md` | 项目英文文档 |
15+
| `pyproject.toml` | Python 项目配置和依赖声明 |
16+
| `pyrightconfig.json` | Pyright 类型检查配置 |
17+
| `setup.bat` | Windows 一键安装脚本 |
18+
| `setup.sh` | Linux/macOS 一键安装脚本 |
19+
| `start_webui.bat` | WebUI 模式启动脚本 |
20+
| `start_cmd.bat` | 命令行模式启动脚本 |
21+
| `.env.example` | 环境变量示例文件 |
22+
| `.gitignore` | Git 忽略规则 |
23+
| `uv.lock` | uv 依赖锁定文件 |
24+
25+
---
26+
27+
## src/ - 核心源码目录
28+
29+
### 入口文件
30+
31+
| 文件 | 描述 |
32+
|------|------|
33+
| `app_launcher.py` | **图形界面启动器**。启动 WebUI 管理服务 (端口9000)，自动打开浏览器 Dashboard |
34+
| `launch_camoufox.py` | **命令行启动器**。核心启动脚本，处理 Camoufox 浏览器启动、认证管理、代理配置、流式代理等 |
35+
| `server.py` | **主服务器**。定义全局状态变量，创建 FastAPI 应用实例，挂载静态资源 |
36+
| `manager.py` | **WebUI 管理器**。处理 Dashboard API、服务启停、认证文件管理、多 Worker 管理 |
37+
| `gateway.py` | **多 Worker 网关**。负载均衡代理，将请求分发到多个 Worker 实例 |
38+
39+
---
40+
41+
### api/ - API 处理模块
42+
43+
| 文件 | 描述 |
44+
|------|------|
45+
| `__init__.py` | 模块导出定义 |
46+
| `app.py` | FastAPI 应用工厂，配置 lifespan、路由、CORS |
47+
| `routes.py` | **路由定义**。定义所有 API 端点：`/v1/chat/completions`, `/generate-speech`, `/generate-image`, `/generate-video`, `/nano/generate` 等 |
48+
| `request_processor.py` | **请求处理核心**。处理聊天请求的完整生命周期：上下文初始化、模型切换、参数设置、响应处理、流式生成 |
49+
| `queue_worker.py` | **队列工作器**。异步处理请求队列，管理请求排队和执行 |
50+
| `dependencies.py` | FastAPI 依赖注入定义 |
51+
| `utils.py` | 工具函数：消息预处理、Base64 提取、SSE 生成、重试计算 |
52+
| `abort_detector.py` | 客户端中断检测器 |
53+
| `auth_utils.py` | API Key 验证工具 |
54+
55+
---
56+
57+
### browser/ - 浏览器自动化模块
58+
59+
| 文件 | 描述 |
60+
|------|------|
61+
| `__init__.py` | 模块导出定义 |
62+
| `initialization.py` | **浏览器初始化**。Playwright 连接、页面创建、事件监听、脚本注入 |
63+
| `page_controller.py` | **页面控制器**。核心 UI 自动化类：参数设置、系统指令、思考模式、图片上传、提交、响应获取 |
64+
| `operations.py` | **通用操作函数**。点击、重试、断开检查、响应获取、错误快照、模型列表解析 |
65+
| `model_management.py` | **模型管理**。模型切换、UI 状态验证、排除模型加载 |
66+
| `script_manager.py` | 油猴脚本管理，用于模型注入 |
67+
| `thinking_normalizer.py` | 思考参数解析和规范化 |
68+
| `more_models.js` | 油猴脚本，注入额外模型到 AI Studio |
69+
70+
---
71+
72+
### config/ - 配置管理
73+
74+
| 文件 | 描述 |
75+
|------|------|
76+
| `__init__.py` | 导出所有配置常量 |
77+
| `constants.py` | 全局常量定义 |
78+
| `settings.py` | 环境变量设置 |
79+
| `timeouts.py` | 超时配置 |
80+
| `selectors.py` | **主选择器**。AI Studio 核心页面元素 CSS/XPath 选择器 |
81+
| `tts_selectors.py` | TTS 页面选择器 |
82+
| `imagen_selectors.py` | Imagen 页面选择器 |
83+
| `veo_selectors.py` | Veo 页面选择器 |
84+
| `nano_selectors.py` | Nano Banana 页面选择器 |
85+
86+
---
87+
88+
### tts/ - TTS 语音生成模块
89+
90+
| 文件 | 描述 |
91+
|------|------|
92+
| `__init__.py` | 模块导出 |
93+
| `models.py` | TTS 数据模型定义 |
94+
| `tts_controller.py` | **TTS 控制器**。语音模式切换、说话人配置、文本输入、音频生成等待 |
95+
| `tts_processor.py` | TTS 请求处理，调用控制器完成生成 |
96+
97+
---
98+
99+
### media/ - 媒体生成模块
100+
101+
| 文件 | 描述 |
102+
|------|------|
103+
| `__init__.py` | 模块导出 |
104+
| `models.py` | 媒体生成数据模型 |
105+
| `imagen_controller.py` | **Imagen 控制器**。图片生成参数设置、提示输入、生成等待、图片提取 |
106+
| `veo_controller.py` | **Veo 控制器**。视频生成参数设置、提示输入、参考图上传、视频等待和提取 |
107+
| `nano_controller.py` | **Nano Banana 控制器**。Gemini 图片生成、参考图上传、结果提取 |
108+
| `media_processor.py` | 媒体请求处理，调用对应控制器 |
109+
110+
---
111+
112+
### proxy/ - 流式代理模块
113+
114+
| 文件 | 描述 |
115+
|------|------|
116+
| `__init__.py` | 模块导出 |
117+
| `server.py` | HTTPS 代理服务器实现 |
118+
| `connection.py` | 连接管理和流量拦截 |
119+
| `handler.py` | 请求处理器 |
120+
| `runner.py` | 代理启动器 |
121+
122+
---
123+
124+
### worker/ - 多 Worker 管理模块
125+
126+
| 文件 | 描述 |
127+
|------|------|
128+
| `__init__.py` | 模块导出 |
129+
| `models.py` | Worker 数据模型 |
130+
| `pool.py` | **Worker 池管理**。多账号 Worker 创建、状态管理、速率限制追踪 |
131+
132+
---
133+
134+
### logger/ - 日志模块
135+
136+
| 文件 | 描述 |
137+
|------|------|
138+
| `__init__.py` | 模块导出 |
139+
| `config.py` | 日志配置，支持文件和 WebSocket 输出 |
140+
141+
---
142+
143+
### static/ - 静态资源
144+
145+
| 文件 | 描述 |
146+
|------|------|
147+
| `dashboard.html` | **WebUI Dashboard**。Vue 3 单文件应用，服务管理、日志查看、聊天测试、配置管理 |
148+
| `i18n.js` | 国际化翻译文件，支持中/英/日/繁体等 |
149+
| `icons.js` | SVG 图标定义 |
150+
151+
---
152+
153+
## llm/ - Ollama 兼容层
154+
155+
| 文件 | 描述 |
156+
|------|------|
157+
| `llm.py` | Ollama 格式 API 兼容层，转发请求到主服务 |
158+
159+
---
160+
161+
## camoufox/ - Camoufox 脚本
162+
163+
| 文件 | 描述 |
164+
|------|------|
165+
| `fetch_camoufox_data.py` | Camoufox 数据获取脚本 |
166+
| `update_browserforge_data.py` | BrowserForge 数据更新脚本 |
167+
168+
---
169+
170+
## docker/ - Docker 配置
171+
172+
| 文件 | 描述 |
173+
|------|------|
174+
| `Dockerfile` | Docker 镜像构建文件 |
175+
| `docker-compose.yml` | Docker Compose 编排文件 |
176+
| `supervisord.conf` | Supervisord 进程管理配置 |
177+
| `.dockerignore` | Docker 构建忽略规则 |
178+
179+
---
180+
181+
## docs/ - 详细文档
182+
183+
| 文件 | 描述 |
184+
|------|------|
185+
| `installation-guide.md` | 安装指南 |
186+
| `authentication-setup.md` | 认证设置说明 |
187+
| `api-usage.md` | API 使用指南 |
188+
| `tts-guide.md` | TTS 语音生成指南 |
189+
| `media-generation-guide.md` | 媒体生成指南 |
190+
| `multi-worker-guide.md` | 多 Worker 模式说明 |
191+
| `docker-deployment.md` | Docker 部署指南 |
192+
| `development-guide.md` | 开发指南 |
193+
| `dependency-versions.md` | 依赖版本说明 |
194+
| `reverse-engineering-internals.md` | 逆向工程内部文档 |
195+
| `client-stop-mechanisms-analysis.md` | 客户端中断机制分析 |
196+
197+
---
198+
199+
## data/ - 运行时数据目录
200+
201+
| 目录/文件 | 描述 |
202+
|----------|------|
203+
| `auth_profiles/` | 认证文件存储目录 |
204+
| `certs/` | HTTPS 证书存储 |
205+
| `key.txt` | API Key 存储 |
206+
| `gui_config.json` | WebUI 配置 |
207+
208+
---
209+
210+
## 核心数据流
211+
212+
```mermaid
213+
graph TD
214+
A[客户端请求] --> B[gateway.py / server.py]
215+
B --> C[routes.py 路由分发]
216+
C --> D{请求类型}
217+
D -->|Chat| E[queue_worker.py]
218+
D -->|TTS| F[tts_processor.py]
219+
D -->|Image| G[media_processor.py]
220+
D -->|Video| H[media_processor.py]
221+
E --> I[request_processor.py]
222+
I --> J[page_controller.py]
223+
J --> K[AI Studio Browser]
224+
F --> L[tts_controller.py]
225+
L --> K
226+
G --> M[imagen_controller.py / nano_controller.py]
227+
M --> K
228+
H --> N[veo_controller.py]
229+
N --> K
230+
K --> O[响应提取]
231+
O --> P[流式/非流式返回]
232+
```

0 commit comments

Comments
 (0)