docs: 优化文档

2026-06-16 21:03:59 +08:00 · 2025-12-07 01:21:54 +08:00
parent 878142a6b6
commit 31f2035f03
1 changed files with 65 additions and 60 deletions
@@ -1,71 +1,70 @@
 # LMArenaImagenAutomator
+![Image](https://github.com/user-attachments/assets/0a887137-64c3-4919-8ab6-b5cf23e5f751)

 ## 📝 项目简介

-LMArenaImagenAutomator 是一个基于 Playwright + Camoufox 的自动化图像生成工具，通过模拟人类操作与 LMArena、Gemini 等网站交互提供图像生成服务到OpenAI格式的接口。(未来可能支持更多支持免费生图的网站)
+LMArenaImagenAutomator 是一个基于 Playwright + Camoufox 的自动化图像生成工具，通过模拟人类操作与 LMArena、Gemini 等网站交互提供图像生成服务到OpenAI格式的接口。

 当前支持的网站：
  - LMArena
  - Gemini Enterprise Business
  - Nano Banana Free
+  - 未来可能支持更多网站...

 ### ✨ 主要特性

- 💁‍♂️ **拟人操作**：模拟人类鼠标移动轨迹和抖动行为
- 🤖 **智能输入**：模拟人类打字速度和错误纠正行为
+- 🤖 **拟人操作**：模拟人类打字行为和鼠标移动行为
 - 🖼️ **多图支持**：最多支持同时上传 10 张参考图片
 - 📊 **队列管理**：支持任务队列，防止请求过载或超时
 - 🌐 **代理支持**：支持 HTTP 和 SOCKS5 代理配置
 - 🎭 **特征伪装**：尽量伪装成非自动程序控制的浏览器
 - 🔗 **流式保活**：复用标准接口的流式模式发送心跳包

-![Image](https://github.com/user-attachments/assets/81170a77-e377-4b47-a2a4-009878142a28)
-
 ---

 ## 🚀 快速开始

 ### 系统要求

- **Node.js**: 20.0.0 或更高版本 (ABI 115+)
- **操作系统**: Windows、Linux 或 MacOS
- **浏览器**: Camoufox (经过反检测处理的FireFox浏览器)
+- **Node.js**: v20.0.0 或更高版本 (需 ABI 115+)
+- **操作系统**: Windows / Linux / macOS
+- **运行环境**: Camoufox (基于 Firefox 的反指纹检测浏览器)
+
 > **开发环境参考**
-> - Node.js v22.20.0 ( Windows 10 )
-> - Node.js v20.19.0 ( Debian 12 )
+> - Windows 10: Node.js v22.20.0
+> - Debian 12: Node.js v20.19.0

 ### 安装步骤

-1. **克隆项目** 或下载解压项目文件
+1. **获取项目**
+   克隆代码仓库或下载源码解压。

-2. **配置文件**
-  复制配置文件模板进行配置文件的修改
-   ```
+2. **准备配置**
+   复制配置文件模板：
+   ```bash
   cp config.example.yaml config.yaml
   ```

 3. **安装依赖**
   ```bash
-   # 安装 NPM 基本依赖
+   # 安装基础依赖
   pnpm install

-   # 安装所需额外依赖
-   # 自动下载安装所需的浏览器和NPM预编译文件
-   # 若网络无法连接 GitHub，请提前在配置文件中设置可用代理
+   # 初始化环境 (下载浏览器及预编译文件)
+   # ⚠️ 若无法连接 GitHub，请先在 config.yaml 中配置代理
   npm run init
   ```

-4. **启动程序**
+4. **启动服务**
   ```bash
+   # 登录模式 (首次使用推荐，用于手动登录)
+   npm start -- -login
+
   # 标准模式
   npm start
-
-   # 登录模式 (用于手动登录，该模式会自动禁用自动化和无头模式)
-   npm start -- -login
   ```

-5. **测试程序 (可选)**
-   用于快速测试服务器接口
+5. **接口测试 (可选)**
   ```bash
   npm test
   ```
@@ -73,19 +72,13 @@ LMArenaImagenAutomator 是一个基于 Playwright + Camoufox 的自动化图像

 ## 📖 使用方法

-### ⚠️ 首次使用重要指引
+### ⚠️ 首次使用必读

-#### 1. 启动与登录
- **关闭无头模式**：首次启动务必关闭无头模式。推荐使用 **登录模式**。（Linux 命令行用户请参阅文档结尾）
- **手动登录**：网页加载完毕后，请手动完成账号登录。
-
-#### 2. 验证流程
- **触发验证**：在输入框输入任意内容并发送，触发服务条款及 CloudFlare Turnstile 验证。
- **完成验证**：点击验证码并通过（可能包含 reCAPTCHA），同意条款后再次点击发送确保流程通畅。
-
-#### 3. 运行建议
- **模式选择**：完成上述初始化后，可切换至无头模式运行。
- **最佳实践**：为降低风控概率，**强烈建议**保持非无头模式运行。
+1. **首次启动**：请使用 `npm start -- -login` 进入登录模式（关闭无头模式）。
+2. **完成初始化**：
+   - 手动登录账号。
+   - 在输入框发送任意消息，触发并完成 CloudFlare/reCAPTCHA 验证及服务条款同意。
+3. **运行建议**：初始化完成后可切换回标准模式，但为降低风控，**强烈建议长期保持非无头模式运行**。


 ### 接口使用说明
@@ -93,7 +86,10 @@ LMArenaImagenAutomator 是一个基于 Playwright + Camoufox 的自动化图像
 #### 1. OpenAI 兼容接口

 > [!WARNING]
-> 由于模拟真实浏览器操作，每次只能处理一个任务，其余任务将进入队列等待。为避免客户端超时影响体验，若当前任务数已达3个，后续请求将直接返回错误。因此，强烈推荐开启流式保活，该模式下服务器会向客户端发送保活注释或者心跳包以确保连接持续活跃。
+> **并发限制与流式保活建议**
+> 本项目通过模拟真实浏览器操作实现，**必须串行处理任务**，并发请求将进入队列。为防止排队过久导致客户端超时，当积压任务达到 3 个时将拒绝新请求。
+> 
+> **💡 强烈建议开启流式模式**：服务器将发送保活心跳包，有效避免因排队等待造成的连接超时。

 **请求端点**
 ```
@@ -172,17 +168,18 @@ data: [DONE]
 ```
 </details>

-> **关于 `model` 参数**：
-> - **必填**：必须填写支持的模型名称，否则将使用目标网站的默认模型
-> - **查看可用模型**：
->   - 方式 1：访问 `/v1/models` 接口查询
->   - 方式 2：直接查看 `lib/backend/models.js` 文件
-> - **示例模型**：`gemini-3-pro-image-preview`、`seedream-4-high-res-fal`、`dall-e-3` 等
+#### 参数说明

-> **关于流式保活的心跳模式**：
-> - 主要分为两种方式，可自行在配置文档中根据所需切换
->   - comment模式: 发送 :keepalive 注释。不污染数据，绝大多数 SDK 支持，不会影响接口标准
->   - content模式: 在 choices[0].delta.content = "" 中发送空字符串（仅当你使用的客户端非常特殊，必须收到 data JSON 包才重置超时时使用）
+| 参数 | 说明 |
+| :--- | :--- |
+| **model** | **必填**。指定使用的模型名称（如 `gemini-3-pro-image-preview`）。<br>可通过 `/v1/models` 接口或查看 `lib/backend/models.js` 获取完整列表。 |
+| **stream** | **推荐开启**。流式响应包含心跳保活机制，防止生成耗时过长导致连接超时。 |
+
+> **💡 关于流式保活（Heartbeat）**
+>
+> 为防止长连接超时，系统提供两种保活模式（可在配置中切换）：
+> 1. **Comment 模式（默认/推荐）**：发送 `:keepalive` 注释。符合 SSE 标准，兼容性最好。
+> 2. **Content 模式**：发送空内容的 data 包。仅用于必须收到 JSON 数据才重置超时的特殊客户端。

 #### 2. 获取可用模型列表

@@ -223,11 +220,16 @@ curl -X GET http://127.0.0.1:3000/v1/models \

 </details>

-#### 3. 带图片的请求说明
+#### 3. 多模态请求 (图生图/图生文)

-**支持格式**：PNG、JPEG、GIF、WebP  
-**最大数量**：5 张图片  
-**数据格式**：Base64 编码
+**功能说明**：支持在消息中附带图片进行对话或生成。
+
+| 限制项 | 说明 |
+| :--- | :--- |
+| **支持格式** | PNG, JPEG, GIF, WebP |
+| **数量限制** | 最大为10，但根据不同网站有不同出入 |
+| **数据格式** | 必须使用 Base64 Data URL 格式 (如 `data:image/jpeg;base64,...`) |
+| **自动转换** | 为保证兼容性与传输速度，服务器会自动将所有图片转换为 JPG 格式 |

 <details>
 <summary>📄 查看API请求示例</summary>
@@ -334,15 +336,16 @@ curl -X GET http://127.0.0.1:3000/v1/models \

 ---

-## 📊 设备配置
-| 资源 | 最低配置 | 推荐配置 |
-|------|---------|---------|
-| CPU | 1核 | 2核及以上 |
-| 内存 | 1GB | 2GB 及以上 |
+## 📊 设备配置参考

-经测试，本项目可在以下环境中运行：
- Oracle 免费机（有些卡顿，勉强能用）：1C1G 配置，基于 Debian 12 系统。
- 阿里云轻量应用服务器（开发测试所用）：2C2G 配置，基于 Debian 11 系统。
+| 资源 | 最低配置 | 推荐配置 | 
+| :--- | :--- | :--- | 
+| **CPU** | 1 核 | 2 核及以上 | 
+| **内存** | 1 GB | 2 GB 及以上 | 
+
+**实测环境表现**：
+- **Oracle 免费机** (1C1G, Debian 12)：资源紧张，偶有卡顿，仅供尝鲜或轻度使用。
+- **阿里云轻量云** (2C2G, Debian 11)：运行流畅稳定，为本项目开发测试基准环境。

 ## 📄 许可证和免责声明

@@ -357,7 +360,9 @@ curl -X GET http://127.0.0.1:3000/v1/models \

 查看完整的版本历史和更新内容，请访问 [CHANGELOG.md](CHANGELOG.md)。

-迁移前的 Puppeteer 版本已在分支中保留，但不影响使用的情况下不会再进行更新和修复！
+## 🕰️ 历史版本说明
+
+本项目已从 Puppeteer 迁移至 Camoufox，以应对日益复杂的反机器人检测机制。基于 Puppeteer 的旧版本代码已归档至 `puppeteer-edition` 分支，仅作留存，**不再提供更新与维护**。

 ---