ZhaoShanGeng commited on
Commit
eab61c2
·
1 Parent(s): 4bf0fdd

docs: 更新文档和打包配置

Browse files

## README.md 更新
- 新增二进制文件部署章节(推荐方式)
- 下载链接和平台支持说明
- 配置文件准备指南
- Windows/Linux/macOS 运行方式
- systemd 服务配置示例
- 新增功能特性:签名透传控制、预编译二进制文件
- 更新配置说明:新增 useContextSystemPrompt 和 passSignatureToClient
- 更新轮询策略说明:默认改为 request_count
- 更新项目结构:新增模块文件说明

## API.md 更新
- 新增配置选项章节
- passSignatureToClient 配置说明
- useContextSystemPrompt 配置说明
- 更新 thinking_budget 默认值为 1024
- 更新 reasoning_effort 说明(low 为默认)
- 新增注意事项:默认轮询策略说明

## 打包配置更新
- scripts/build.js: 简化 public 目录复制逻辑
- scripts/build.js: 更新 pkg.assets 支持 js/ 和 assets/ 子目录
- package.json: 更新 pkg.assets 配置

Files changed (4) hide show
  1. API.md +51 -3
  2. README.md +129 -5
  3. package.json +4 -1
  4. scripts/build.js +8 -13
API.md CHANGED
@@ -162,7 +162,7 @@ curl http://localhost:8045/v1/chat/completions \
162
  | `top_p` | number | ❌ | Top P 参数,默认 1 |
163
  | `top_k` | number | ❌ | Top K 参数,默认 50 |
164
  | `max_tokens` | number | ❌ | 最大 token 数,默认 32000 |
165
- | `thinking_budget` | number | ❌ | 思考预算(仅对思考模型生效),可为 0 或 1024-32000,默认 16000(0 表示关闭思考预算限制) |
166
  | `reasoning_effort` | string | ❌ | 思维链强度(OpenAI 格式),可选值:`low`(1024)、`medium`(16000)、`high`(32000) |
167
  | `tools` | array | ❌ | 工具列表(Function Calling) |
168
 
@@ -246,8 +246,8 @@ curl http://localhost:8045/v1/chat/completions \
246
 
247
  | reasoning_effort | thinking_budget | 说明 |
248
  |-----------------|-----------------|------|
249
- | `low` | 1024 | 快速响应,适合简单问题 |
250
- | `medium` | 16000 | 平衡模式(默认) |
251
  | `high` | 32000 | 深度思考,适合复杂推理 |
252
 
253
  ### 使用 thinking_budget(直接数值)
@@ -505,6 +505,53 @@ for await (const chunk of stream) {
505
  }
506
  ```
507
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
508
  ## 注意事项
509
 
510
  1. 所有 `/v1/*` 请求必须携带有效的 API Key
@@ -515,3 +562,4 @@ for await (const chunk of stream) {
515
  6. 图片生成仅支持 `gemini-3-pro-image` 模型
516
  7. 模型列表会缓存 1 小时,可通过配置调整
517
  8. 思维链内容通过 `reasoning_content` 字段输出(兼容 DeepSeek 格式)
 
 
162
  | `top_p` | number | ❌ | Top P 参数,默认 1 |
163
  | `top_k` | number | ❌ | Top K 参数,默认 50 |
164
  | `max_tokens` | number | ❌ | 最大 token 数,默认 32000 |
165
+ | `thinking_budget` | number | ❌ | 思考预算(仅对思考模型生效),可为 0 或 1024-32000,默认 1024(0 表示关闭思考预算限制) |
166
  | `reasoning_effort` | string | ❌ | 思维链强度(OpenAI 格式),可选值:`low`(1024)、`medium`(16000)、`high`(32000) |
167
  | `tools` | array | ❌ | 工具列表(Function Calling) |
168
 
 
246
 
247
  | reasoning_effort | thinking_budget | 说明 |
248
  |-----------------|-----------------|------|
249
+ | `low` | 1024 | 快速响应,适合简单问题(默认) |
250
+ | `medium` | 16000 | 平衡模式 |
251
  | `high` | 32000 | 深度思考,适合复杂推理 |
252
 
253
  ### 使用 thinking_budget(直接数值)
 
505
  }
506
  ```
507
 
508
+ ## 配置选项
509
+
510
+ ### passSignatureToClient
511
+
512
+ 控制是否将 `thoughtSignature` 透传到客户端响应中。
513
+
514
+ 在 `config.json` 中配置:
515
+
516
+ ```json
517
+ {
518
+ "other": {
519
+ "passSignatureToClient": false
520
+ }
521
+ }
522
+ ```
523
+
524
+ - `false`(默认):不透传签名,响应中不包含 `thoughtSignature` 字段
525
+ - `true`:透传签名,响应中包含 `thoughtSignature` 字段
526
+
527
+ **启用透传后的响应示例**:
528
+
529
+ ```json
530
+ {
531
+ "choices": [{
532
+ "delta": {
533
+ "reasoning_content": "让我思考...",
534
+ "thoughtSignature": "RXFRRENrZ0lDaEFD..."
535
+ }
536
+ }]
537
+ }
538
+ ```
539
+
540
+ ### useContextSystemPrompt
541
+
542
+ 控制是否将请求中的 system 消息合并到 SystemInstruction。
543
+
544
+ ```json
545
+ {
546
+ "other": {
547
+ "useContextSystemPrompt": false
548
+ }
549
+ }
550
+ ```
551
+
552
+ - `false`(默认):仅使用全局 `SYSTEM_INSTRUCTION` 环境变量
553
+ - `true`:将请求开头连续的 system 消息与全局配置合并
554
+
555
  ## 注意事项
556
 
557
  1. 所有 `/v1/*` 请求必须携带有效的 API Key
 
562
  6. 图片生成仅支持 `gemini-3-pro-image` 模型
563
  7. 模型列表会缓存 1 小时,可通过配置调整
564
  8. 思维链内容通过 `reasoning_content` 字段输出(兼容 DeepSeek 格式)
565
+ 9. 默认轮询策略为 `request_count`,每 50 次请求切换 Token
README.md CHANGED
@@ -23,6 +23,8 @@
23
  - ✅ 隐私模式(自动隐藏敏感信息)
24
  - ✅ 内存优化(从 8+ 进程减少为 2 个进程,内存占用从 100MB+ 降为 50MB+)
25
  - ✅ 对象池复用(减少 50%+ 临时对象创建,降低 GC 频率)
 
 
26
 
27
  ## 环境要求
28
 
@@ -75,6 +77,114 @@ npm start
75
 
76
  服务将在 `http://localhost:8045` 启动。
77
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
78
  ## Docker 部署
79
 
80
  ### 使用 Docker Compose(推荐)
@@ -365,7 +475,9 @@ curl http://localhost:8045/v1/chat/completions \
365
  "other": {
366
  "timeout": 300000, // 请求超时时间(毫秒)
367
  "skipProjectIdFetch": false,// 跳过 ProjectId 获取,直接随机生成(仅 Pro 账号有效)
368
- "useNativeAxios": false // 使用原生 axios 而非 AntigravityRequester
 
 
369
  }
370
  }
371
  ```
@@ -375,8 +487,8 @@ curl http://localhost:8045/v1/chat/completions \
375
  | 策略 | 说明 |
376
  |------|------|
377
  | `round_robin` | 均衡负载:每次请求后切换到下一个 Token |
378
- | `quota_exhausted` | 额度耗尽才切换:持续使用当前 Token 直到额度用完 |
379
- | `request_count` | 自定义次数:每个 Token 使用指定次数后切换 |
380
 
381
  ### 2. .env(敏感配置)
382
 
@@ -425,10 +537,12 @@ npm run login
425
  │ └── refresh-tokens.js # Token 刷新脚本
426
  ├── src/
427
  │ ├── api/
428
- │ │ └── client.js # API 调用逻辑(含模型列表缓存)
 
429
  │ ├── auth/
430
  │ │ ├── jwt.js # JWT 认证
431
  │ │ ├── token_manager.js # Token 管理(含轮询策略)
 
432
  │ │ └── quota_manager.js # 额度缓存管理
433
  │ ├── routes/
434
  │ │ ├── admin.js # 管理接口路由
@@ -441,6 +555,7 @@ npm run login
441
  │ │ ├── config.js # 配置加载
442
  │ │ └── init-env.js # 环境变量初始化
443
  │ ├── constants/
 
444
  │ │ └── oauth.js # OAuth 常量
445
  │ ├── server/
446
  │ │ └── index.js # 主服务器(含内存管理和心跳)
@@ -448,10 +563,19 @@ npm run login
448
  │ │ ├── configReloader.js # 配置热重载
449
  │ │ ├── deepMerge.js # 深度合并工具
450
  │ │ ├── envParser.js # 环境变量解析
 
451
  │ │ ├── idGenerator.js # ID 生成器
452
  │ │ ├── imageStorage.js # 图片存储
453
  │ │ ├── logger.js # 日志模块
454
- │ │ └── utils.js # 工具函数
 
 
 
 
 
 
 
 
455
  │ └── AntigravityRequester.js # TLS 指纹请求器封装
456
  ├── test/
457
  │ ├── test-request.js # 请求测试
 
23
  - ✅ 隐私模式(自动隐藏敏感信息)
24
  - ✅ 内存优化(从 8+ 进程减少为 2 个进程,内存占用从 100MB+ 降为 50MB+)
25
  - ✅ 对象池复用(减少 50%+ 临时对象创建,降低 GC 频率)
26
+ - ✅ 签名透传控制(可配置是否将 thoughtSignature 透传到客户端)
27
+ - ✅ 预编译二进制文件(支持 Windows/Linux/Android,无需 Node.js 环境)
28
 
29
  ## 环境要求
30
 
 
77
 
78
  服务将在 `http://localhost:8045` 启动。
79
 
80
+ ## 二进制文件部署(推荐)
81
+
82
+ 无需安装 Node.js,直接下载预编译的二进制文件即可运行。
83
+
84
+ ### 下载二进制文件
85
+
86
+ 从 [GitHub Releases](https://github.com/ZhaoShanGeng/antigravity2api-nodejs/releases) 下载对应平台的二进制文件:
87
+
88
+ | 平台 | 文件名 |
89
+ |------|--------|
90
+ | Windows x64 | `antigravity2api-win-x64.exe` |
91
+ | Linux x64 | `antigravity2api-linux-x64` |
92
+ | Linux ARM64 | `antigravity2api-linux-arm64` |
93
+ | macOS x64 | `antigravity2api-macos-x64` |
94
+ | macOS ARM64 | `antigravity2api-macos-arm64` |
95
+
96
+ ### 准备配置文件
97
+
98
+ 将以下文件放在二进制文件同目录下:
99
+
100
+ ```
101
+ ├── antigravity2api-win-x64.exe # 二进制文件
102
+ ├── .env # 环境变量配置(必需)
103
+ ├── config.json # 基础配置(必需)
104
+ ├── public/ # 静态文件目录(必需)
105
+ │ ├── index.html
106
+ │ ├── style.css
107
+ │ ├── assets/
108
+ │ │ └── bg.jpg
109
+ │ └── js/
110
+ │ ├── auth.js
111
+ │ ├── config.js
112
+ │ ├── main.js
113
+ │ ├── quota.js
114
+ │ ├── tokens.js
115
+ │ ├── ui.js
116
+ │ └── utils.js
117
+ └── data/ # 数据目录(自动创建)
118
+ └── accounts.json
119
+ ```
120
+
121
+ ### 配置环境变量
122
+
123
+ 创建 `.env` 文件:
124
+
125
+ ```env
126
+ API_KEY=sk-your-api-key
127
+ ADMIN_USERNAME=admin
128
+ ADMIN_PASSWORD=admin123
129
+ JWT_SECRET=your-jwt-secret-key-change-this-in-production
130
+ # IMAGE_BASE_URL=http://your-domain.com
131
+ # PROXY=http://127.0.0.1:7890
132
+ ```
133
+
134
+ ### 运行
135
+
136
+ **Windows**:
137
+ ```bash
138
+ # 直接双击运行,或在命令行执行
139
+ antigravity2api-win-x64.exe
140
+ ```
141
+
142
+ **Linux/macOS**:
143
+ ```bash
144
+ # 添加执行权限
145
+ chmod +x antigravity2api-linux-x64
146
+
147
+ # 运行
148
+ ./antigravity2api-linux-x64
149
+ ```
150
+
151
+ ### 二进制部署说明
152
+
153
+ - **无需 Node.js**:二进制文件已包含 Node.js 运行时
154
+ - **配置文件**:`.env` 和 `config.json` 必须与二进制文件在同一目录
155
+ - **静态文件**:`public/` 目录必须与二进制文件在同一目录
156
+ - **数据持久化**:`data/` 目录会自动创建,用于存储 Token 数据
157
+ - **跨平台**:支持 Windows、Linux、macOS(x64 和 ARM64)
158
+
159
+ ### 作为系统服务运行(Linux)
160
+
161
+ 创建 systemd 服务文件 `/etc/systemd/system/antigravity2api.service`:
162
+
163
+ ```ini
164
+ [Unit]
165
+ Description=Antigravity2API Service
166
+ After=network.target
167
+
168
+ [Service]
169
+ Type=simple
170
+ User=www-data
171
+ WorkingDirectory=/opt/antigravity2api
172
+ ExecStart=/opt/antigravity2api/antigravity2api-linux-x64
173
+ Restart=always
174
+ RestartSec=10
175
+
176
+ [Install]
177
+ WantedBy=multi-user.target
178
+ ```
179
+
180
+ 启动服务:
181
+
182
+ ```bash
183
+ sudo systemctl daemon-reload
184
+ sudo systemctl enable antigravity2api
185
+ sudo systemctl start antigravity2api
186
+ ```
187
+
188
  ## Docker 部署
189
 
190
  ### 使用 Docker Compose(推荐)
 
475
  "other": {
476
  "timeout": 300000, // 请求超时时间(毫秒)
477
  "skipProjectIdFetch": false,// 跳过 ProjectId 获取,直接随机生成(仅 Pro 账号有效)
478
+ "useNativeAxios": false, // 使用原生 axios 而非 AntigravityRequester
479
+ "useContextSystemPrompt": false, // 是否将请求中的 system 消息合并到 SystemInstruction
480
+ "passSignatureToClient": false // 是否将 thoughtSignature 透传到客户端
481
  }
482
  }
483
  ```
 
487
  | 策略 | 说明 |
488
  |------|------|
489
  | `round_robin` | 均衡负载:每次请求后切换到下一个 Token |
490
+ | `quota_exhausted` | 额度耗尽才切换:持续使用当前 Token 直到额度用完(高性能优化) |
491
+ | `request_count` | 自定义次数:每个 Token 使用指定次数后切换(默认策略) |
492
 
493
  ### 2. .env(敏感配置)
494
 
 
537
  │ └── refresh-tokens.js # Token 刷新脚本
538
  ├── src/
539
  │ ├── api/
540
+ │ │ ├── client.js # API 调用逻辑(含模型列表缓存)
541
+ │ │ └── stream_parser.js # 流式响应解析(对象池优化)
542
  │ ├── auth/
543
  │ │ ├── jwt.js # JWT 认证
544
  │ │ ├── token_manager.js # Token 管理(含轮询策略)
545
+ │ │ ├── token_store.js # Token 文件存储(异步读写)
546
  │ │ └── quota_manager.js # 额度缓存管理
547
  │ ├── routes/
548
  │ │ ├── admin.js # 管理接口路由
 
555
  │ │ ├── config.js # 配置加载
556
  │ │ └── init-env.js # 环境变量初始化
557
  │ ├── constants/
558
+ │ │ ├── index.js # 应用常量定义
559
  │ │ └── oauth.js # OAuth 常量
560
  │ ├── server/
561
  │ │ └── index.js # 主服务器(含内存管理和心跳)
 
563
  │ │ ├── configReloader.js # 配置热重载
564
  │ │ ├── deepMerge.js # 深度合并工具
565
  │ │ ├── envParser.js # 环境变量解析
566
+ │ │ ├── errors.js # 统一错误处理
567
  │ │ ├── idGenerator.js # ID 生成器
568
  │ │ ├── imageStorage.js # 图片存储
569
  │ │ ├── logger.js # 日志模块
570
+ │ │ ├── memoryManager.js # 智能内存管理
571
+ │ │ ├── openai_generation.js # 生成配置
572
+ │ │ ├── openai_mapping.js # 请求体构建
573
+ │ │ ├── openai_messages.js # 消息格式转换
574
+ │ │ ├── openai_signatures.js # 签名常量
575
+ │ │ ├── openai_system.js # 系统指令提取
576
+ │ │ ├── openai_tools.js # 工具格式转换
577
+ │ │ ├── paths.js # 路径工具(支持 pkg 打包)
578
+ │ │ └── utils.js # 工具函数(重导出)
579
  │ └── AntigravityRequester.js # TLS 指纹请求器封装
580
  ├── test/
581
  │ ├── test-request.js # 请求测试
package.json CHANGED
@@ -47,7 +47,10 @@
47
  "scripts/**/*.js"
48
  ],
49
  "assets": [
50
- "public/**/*",
 
 
 
51
  "src/bin/**/*",
52
  ".env.example",
53
  "config.json"
 
47
  "scripts/**/*.js"
48
  ],
49
  "assets": [
50
+ "public/*.html",
51
+ "public/*.css",
52
+ "public/js/**/*",
53
+ "public/assets/**/*",
54
  "src/bin/**/*",
55
  ".env.example",
56
  "config.json"
scripts/build.js CHANGED
@@ -98,8 +98,9 @@ const pkgJson = {
98
  pkg: {
99
  assets: [
100
  toSlash(path.join(rootDir, 'public', '*.html')),
101
- toSlash(path.join(rootDir, 'public', '*.js')),
102
  toSlash(path.join(rootDir, 'public', '*.css')),
 
 
103
  toSlash(path.join(rootDir, 'src', 'bin', '*'))
104
  ]
105
  }
@@ -189,18 +190,12 @@ try {
189
  if (fs.existsSync(publicDestDir)) {
190
  fs.rmSync(publicDestDir, { recursive: true, force: true });
191
  }
192
- fs.mkdirSync(publicDestDir, { recursive: true });
193
- const publicFiles = fs.readdirSync(publicSrcDir);
194
- for (const file of publicFiles) {
195
- if (file === 'images') continue; // 跳过 images 目录
196
- const srcPath = path.join(publicSrcDir, file);
197
- const destPath = path.join(publicDestDir, file);
198
- const stat = fs.statSync(srcPath);
199
- if (stat.isFile()) {
200
- fs.copyFileSync(srcPath, destPath);
201
- } else if (stat.isDirectory()) {
202
- fs.cpSync(srcPath, destPath, { recursive: true });
203
- }
204
  }
205
  console.log(' ✓ Copied public directory');
206
  }
 
98
  pkg: {
99
  assets: [
100
  toSlash(path.join(rootDir, 'public', '*.html')),
 
101
  toSlash(path.join(rootDir, 'public', '*.css')),
102
+ toSlash(path.join(rootDir, 'public', 'js', '*.js')),
103
+ toSlash(path.join(rootDir, 'public', 'assets', '*')),
104
  toSlash(path.join(rootDir, 'src', 'bin', '*'))
105
  ]
106
  }
 
190
  if (fs.existsSync(publicDestDir)) {
191
  fs.rmSync(publicDestDir, { recursive: true, force: true });
192
  }
193
+ // 直接全复制 public 目录
194
+ fs.cpSync(publicSrcDir, publicDestDir, { recursive: true });
195
+ // 删除 images 目录(运行时生成,不需要打包)
196
+ const imagesDir = path.join(publicDestDir, 'images');
197
+ if (fs.existsSync(imagesDir)) {
198
+ fs.rmSync(imagesDir, { recursive: true, force: true });
 
 
 
 
 
 
199
  }
200
  console.log(' ✓ Copied public directory');
201
  }