Skip to content

Commit c0d9b92

Browse files
NikkeTryHardNikkeTryHard
authored
docs: comprehensive documentation update for v4.0.3 changes (#294)
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
1 parent d0f2efe commit c0d9b92

6 files changed

Lines changed: 181 additions & 58 deletions

‎docs/advanced-configuration.md‎

Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ UNIFIED_PROXY_CONFIG=
3030

3131
## 响应获取模式配置
3232

33-
### 模式1: 优先使用集成的流式代理 (默认推荐)
33+
### 模式 1: 优先使用集成的流式代理 (默认推荐)
3434

3535
**推荐使用 .env 配置方式**:
3636

@@ -56,7 +56,7 @@ python launch_camoufox.py --headless --server-port 2048 --stream-port 3120 --hel
5656

5757
在此模式下，主服务器会优先尝试通过端口 `3120` (或指定的 `--stream-port`) 上的集成流式代理获取响应。如果失败，则回退到 Playwright 页面交互。
5858

59-
### 模式2: 优先使用外部 Helper 服务 (禁用集成流式代理)
59+
### 模式 2: 优先使用外部 Helper 服务 (禁用集成流式代理)
6060

6161
```bash
6262
# 基本外部Helper模式，明确禁用代理
@@ -68,7 +68,7 @@ python launch_camoufox.py --headless --server-port 2048 --stream-port 0 --helper
6868

6969
在此模式下，主服务器会优先尝试通过 `--helper` 指定的端点获取响应 (需要有效的 `auth_profiles/active/*.json` 以提取 `SAPISID`)。如果失败，则回退到 Playwright 页面交互。
7070

71-
### 模式3: 仅使用 Playwright 页面交互 (禁用所有流式代理和 Helper)
71+
### 模式 3: 仅使用 Playwright 页面交互 (禁用所有流式代理和 Helper)
7272

7373
```bash
7474
# 纯Playwright模式，明确禁用代理
@@ -129,7 +129,7 @@ openssl rsa -in certs/ca.key -out certs/ca.key
129129

130130
项目根目录下的 `excluded_models.txt` 文件可用于从 `/v1/models` 端点返回的列表中排除特定的模型 ID。
131131

132-
每行一个模型ID，例如：
132+
每行一个模型 ID，例如：
133133

134134
```
135135
gemini-1.0-pro
@@ -195,14 +195,54 @@ ENABLE_URL_CONTEXT=true
195195
ONLY_COLLECT_CURRENT_USER_ATTACHMENTS=true
196196
```
197197

198+
### 前端构建控制
199+
200+
```env
201+
# 跳过启动时的前端资源构建检查 (适用于无 Node.js 环境或使用预构建资源)
202+
SKIP_FRONTEND_BUILD=true
203+
```
204+
205+
也可以通过命令行参数设置：
206+
207+
```bash
208+
python launch_camoufox.py --headless --skip-frontend-build
209+
```
210+
211+
## 模型能力配置
212+
213+
### config/model_capabilities.json
214+
215+
模型能力配置已外部化到 `config/model_capabilities.json` 文件。此配置定义了各模型的：
216+
217+
- **thinkingType**: 思考模式类型 (`none`, `level`, `budget`)
218+
- **supportsGoogleSearch**: 是否支持 Google Search 工具
219+
- **levels/budgetRange**: 思考等级或预算范围
220+
221+
**优势**：当 Google 发布新模型时，只需编辑 JSON 文件，无需修改代码。
222+
223+
示例结构：
224+
225+
```json
226+
{
227+
"categories": {
228+
"gemini3Flash": {
229+
"thinkingType": "level",
230+
"levels": ["minimal", "low", "medium", "high"],
231+
"supportsGoogleSearch": true
232+
}
233+
},
234+
"matchers": [{ "pattern": "gemini-3.*-flash", "category": "gemini3Flash" }]
235+
}
236+
```
237+
198238
## GUI 启动器高级功能
199239

200-
### 本地LLM模拟服务
240+
### 本地 LLM 模拟服务
201241

202-
GUI 集成了启动和管理一个本地LLM模拟服务的功能：
242+
GUI 集成了启动和管理一个本地 LLM 模拟服务的功能：
203243

204244
- **功能**: 监听 `11434` 端口，模拟部分 Ollama API 端点和 OpenAI 兼容的 `/v1/chat/completions` 端点
205-
- **启动**: 在 GUI 的"启动选项"区域，点击"启动本地LLM模拟服务"按钮
245+
- **启动**: 在 GUI 的"启动选项"区域，点击"启动本地 LLM 模拟服务"按钮
206246
- **依赖检测**: 启动前会自动检测 `localhost:2048` 端口是否可用
207247
- **用途**: 主要用于测试客户端与 Ollama 或 OpenAI 兼容 API 的对接
208248

@@ -214,6 +254,8 @@ GUI 提供端口进程管理功能：
214254
- 选择并尝试停止在指定端口上找到的进程
215255
- 手动输入 PID 终止进程
216256

257+
**安全机制**：进程终止功能会验证 PID 是否属于配置的端口（FastAPI、Camoufox、Stream Proxy），防止意外终止无关进程。
258+
217259
## 环境变量配置
218260

219261
### 代理配置

‎docs/architecture-guide.md‎

Lines changed: 59 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -118,25 +118,34 @@ AIstudioProxyAPI/
118118
**职责**: API 路由、认证、请求处理。
119119

120120
#### app.py - 应用入口
121+
121122
- FastAPI 应用创建和配置
122123
- 生命周期管理 (startup/shutdown)
123124
- 中间件配置 (API 密钥认证)
124125

125126
#### routers/ - API 路由
127+
126128
路由按职责拆分为独立模块:
127129

128-
| 模块 | 端点 | 职责 |
129-
|------|------|------|
130-
| `chat.py` | `/v1/chat/completions` | 聊天完成接口 |
131-
| `models.py` | `/v1/models` | 模型列表 |
132-
| `health.py` | `/health` | 健康检查 |
133-
| `queue.py` | `/v1/queue`, `/v1/cancel` | 队列管理 |
134-
| `api_keys.py` | `/api/keys*` | 密钥管理 |
135-
| `logs_ws.py` | `/ws/logs` | 实时日志流 |
136-
| `static.py` | `/`, `/webui.*` | 静态资源 |
137-
| `info.py` | `/api/info` | API 信息 |
130+
| 模块 | 端点 | 职责 |
131+
| ----------------------- | ------------------------- | ------------------ |
132+
| `chat.py` | `/v1/chat/completions` | 聊天完成接口 |
133+
| `models.py` | `/v1/models` | 模型列表 |
134+
| `model_capabilities.py` | `/api/model-capabilities` | 模型能力查询 |
135+
| `health.py` | `/health` | 健康检查 |
136+
| `queue.py` | `/v1/queue`, `/v1/cancel` | 队列管理 |
137+
| `api_keys.py` | `/api/keys*` | 密钥管理 |
138+
| `logs_ws.py` | `/ws/logs` | 实时日志流 |
139+
| `static.py` | `/`, `/assets/*` | React SPA 静态资源 |
140+
| `info.py` | `/api/info` | API 信息 |
141+
| `auth_files.py` | `/api/auth-files*` | 认证文件管理 |
142+
| `ports.py` | `/api/ports*` | 端口配置和进程管理 |
143+
| `proxy.py` | `/api/proxy*` | 代理配置管理 |
144+
| `server.py` | `/api/server*` | 服务器控制 |
145+
| `helper.py` | `/api/helper*` | Helper 服务配置 |
138146

139147
#### queue_worker.py - 队列工作器
148+
140149
- 异步请求队列处理 (FIFO)
141150
- 并发控制和资源管理
142151
- **分级错误恢复机制**:
@@ -148,19 +157,21 @@ AIstudioProxyAPI/
148157
**职责**: 浏览器控制、页面交互、脚本注入。
149158

150159
#### page_controller.py - 页面控制器
160+
151161
基于 Mixin 模式的聚合控制器，继承自 `page_controller_modules/` 子模块。
152162

153163
#### initialization/ - 初始化模块
154164

155-
| 模块 | 职责 |
156-
|------|------|
157-
| `core.py` | 浏览器上下文创建、导航、登录检测 |
158-
| `network.py` | 网络拦截、模型列表注入 |
159-
| `auth.py` | 认证状态保存/恢复 |
160-
| `scripts.py` | UserScript 脚本注入 |
161-
| `debug.py` | 调试监听器设置 |
165+
| 模块 | 职责 |
166+
| ------------ | -------------------------------- |
167+
| `core.py` | 浏览器上下文创建、导航、登录检测 |
168+
| `network.py` | 网络拦截、模型列表注入 |
169+
| `auth.py` | 认证状态保存/恢复 |
170+
| `scripts.py` | UserScript 脚本注入 |
171+
| `debug.py` | 调试监听器设置 |
162172

163173
#### script_manager.py - 脚本注入 v3.0
174+
164175
- Playwright 原生网络拦截
165176
- 油猴脚本解析和注入
166177
- 模型数据同步
@@ -177,11 +188,11 @@ AIstudioProxyAPI/
177188

178189
**职责**: 应用启动和进程管理。
179190

180-
| 模块 | 职责 |
181-
|------|------|
182-
| `runner.py` | 启动逻辑核心 |
183-
| `config.py` | 启动配置处理 |
184-
| `checks.py` | 环境与依赖检查 |
191+
| 模块 | 职责 |
192+
| ------------ | ----------------- |
193+
| `runner.py` | 启动逻辑核心 |
194+
| `config.py` | 启动配置处理 |
195+
| `checks.py` | 环境与依赖检查 |
185196
| `process.py` | Camoufox 进程管理 |
186197

187198
---
@@ -194,19 +205,21 @@ AIstudioProxyAPI/
194205
请求 → 第一层: 流式代理 → 第二层: Helper → 第三层: Playwright
195206
```
196207

197-
| 层级 | 类型 | 延迟 | 参数支持 | 适用场景 |
198-
|------|------|------|----------|----------|
199-
| **流式代理** | True Streaming | 最低 | 基础参数 | 生产环境 (推荐) |
200-
| **Helper** | 取决于实现 | 中等 | 取决于实现 | 特殊网络环境 |
201-
| **Playwright** | Pseudo-Streaming | 最高 | 所有参数 | 调试、参数测试 |
208+
| 层级 | 类型 | 延迟 | 参数支持 | 适用场景 |
209+
| -------------- | ---------------- | ---- | ---------- | --------------- |
210+
| **流式代理** | True Streaming | 最低 | 基础参数 | 生产环境 (推荐) |
211+
| **Helper** | 取决于实现 | 中等 | 取决于实现 | 特殊网络环境 |
212+
| **Playwright** | Pseudo-Streaming | 最高 | 所有参数 | 调试、参数测试 |
202213

203214
### 请求处理路径
204215

205216
**辅助流路径 (STREAM)**:
217+
206218
- 入口: `_handle_auxiliary_stream_response`
207219
- 从 `STREAM_QUEUE` 消费，产出 OpenAI 兼容 SSE
208220

209221
**Playwright 路径**:
222+
210223
- 入口: `_handle_playwright_response`
211224
- 通过 `PageController.get_response` 拉取文本，按块输出
212225

@@ -215,11 +228,13 @@ AIstudioProxyAPI/
215228
## 🔐 认证系统
216229

217230
### API 密钥管理
231+
218232
- **存储**: `auth_profiles/key.txt`
219233
- **验证**: Bearer Token 和 X-API-Key 双重支持
220234
- **管理**: Web UI 分级权限查看
221235

222236
### 浏览器认证
237+
223238
- **文件**: `auth_profiles/active/*.json`
224239
- **内容**: 浏览器会话和 Cookie
225240
- **更新**: 通过 `--debug` 模式重新获取
@@ -229,18 +244,23 @@ AIstudioProxyAPI/
229244
## 📊 配置管理
230245

231246
### 优先级
247+
232248
1. **命令行参数** (最高)
233249
2. **环境变量** (`.env` 文件)
234250
3. **默认值** (代码定义)
235251

236252
### config/ 模块
237253

238-
| 文件 | 职责 |
239-
|------|------|
240-
| `settings.py` | 环境变量加载和解析 |
241-
| `constants.py` | 系统常量定义 |
242-
| `timeouts.py` | 超时配置 |
243-
| `selectors.py` | CSS 选择器定义 |
254+
| 文件 | 职责 |
255+
| ------------------------- | ---------------------------------------------- |
256+
| `settings.py` | 环境变量加载和解析 |
257+
| `constants.py` | 系统常量定义 |
258+
| `timeouts.py` | 超时配置 |
259+
| `selectors.py` | CSS 选择器定义 |
260+
| `model_capabilities.json` | 模型能力配置（思考类型、Google Search 支持等） |
261+
262+
> **注意**: `model_capabilities.json` 是外部化的 JSON 配置文件，用于定义各模型的能力参数。
263+
> 当 Google 发布新模型时，只需编辑 JSON 文件，无需修改代码。
244264
245265
---
246266

@@ -263,12 +283,12 @@ AIstudioProxyAPI/
263283

264284
## 📈 开发工具
265285

266-
| 工具 | 用途 |
267-
|------|------|
268-
| **Poetry** | 依赖管理 |
269-
| **Pyright** | 类型检查 |
270-
| **Ruff** | 代码格式化和 Lint |
271-
| **pytest** | 测试框架 |
286+
| 工具 | 用途 |
287+
| ----------- | ----------------- |
288+
| **Poetry** | 依赖管理 |
289+
| **Pyright** | 类型检查 |
290+
| **Ruff** | 代码格式化和 Lint |
291+
| **pytest** | 测试框架 |
272292

273293
---
274294

‎docs/development-guide.md‎

Lines changed: 60 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,11 @@
88

99
- **Python**: ≥3.9, <4.0 (推荐 3.10+)
1010
- **Poetry**: 依赖管理工具
11+
- **Node.js**: ≥18 (用于前端开发，可选)
1112
- **Git**: 版本控制
1213

14+
> **提示**: 如果不进行前端开发，可以使用 `--skip-frontend-build` 或设置 `SKIP_FRONTEND_BUILD=1` 跳过前端构建。
15+
1316
### 快速开始
1417

1518
```bash
@@ -91,6 +94,51 @@ poetry run python script.py
9194

9295
---
9396

97+
## 🎨 前端开发 (React)
98+
99+
前端使用 React + Vite + TypeScript 构建。
100+
101+
### 开发模式
102+
103+
```bash
104+
cd static/frontend
105+
106+
# 安装依赖
107+
npm install
108+
109+
# 开发服务器 (热重载)
110+
npm run dev
111+
112+
# 构建生产版本
113+
npm run build
114+
115+
# 运行测试
116+
npm run test
117+
```
118+
119+
### 跳过前端构建
120+
121+
如果只进行后端开发，可以跳过前端构建：
122+
123+
```bash
124+
# 命令行方式
125+
python -m launcher.runner --skip-frontend-build
126+
127+
# 环境变量方式
128+
SKIP_FRONTEND_BUILD=1 python -m launcher.runner
129+
```
130+
131+
### 配置文件
132+
133+
| 文件 | 用途 |
134+
| ---------------------------------- | --------------- |
135+
| `static/frontend/package.json` | 依赖和脚本配置 |
136+
| `static/frontend/vite.config.ts` | Vite 构建配置 |
137+
| `static/frontend/tsconfig.json` | TypeScript 配置 |
138+
| `static/frontend/vitest.config.ts` | Vitest 测试配置 |
139+
140+
---
141+
94142
## 🔍 类型检查 (Pyright)
95143

96144
项目使用 Pyright 进行类型检查。
@@ -111,6 +159,7 @@ pyright --watch
111159
### 配置
112160

113161
`pyrightconfig.json`:
162+
114163
```json
115164
{
116165
"pythonVersion": "3.13",
@@ -182,12 +231,12 @@ git push origin feature-branch
182231

183232
### 命名规范
184233

185-
| 类型 | 规范 | 示例 |
186-
|------|------|------|
234+
| 类型 | 规范 | 示例 |
235+
| ------ | ------------ | ---------------------- |
187236
| 文件名 | `snake_case` | `request_processor.py` |
188-
| 类名 | `PascalCase` | `QueueManager` |
189-
| 函数名 | `snake_case` | `process_request` |
190-
| 常量 | `UPPER_CASE` | `DEFAULT_PORT` |
237+
| 类名 | `PascalCase` | `QueueManager` |
238+
| 函数名 | `snake_case` | `process_request` |
239+
| 常量 | `UPPER_CASE` | `DEFAULT_PORT` |
191240

192241
### 文档字符串
193242

@@ -219,12 +268,12 @@ def process_request(request: ChatRequest) -> ChatResponse:
219268

220269
### 错误码规范
221270

222-
| 错误码 | 场景 |
223-
|--------|------|
224-
| 499 | 客户端断开/取消 |
225-
| 502 | 上游/Playwright 失败 |
226-
| 503 | 服务不可用 |
227-
| 504 | 处理超时 |
271+
| 错误码 | 场景 |
272+
| ------ | -------------------- |
273+
| 499 | 客户端断开/取消 |
274+
| 502 | 上游/Playwright 失败 |
275+
| 503 | 服务不可用 |
276+
| 504 | 处理超时 |
228277

229278
---
230279

0 commit comments

Comments
 (0)