# universal-web-api

**Repository Path**: underdogs/universal-web-api

## Basic Information

- **Project Name**: universal-web-api
- **Description**: No description available
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-13
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Universal Web API

📖 文档 • [English](./README.md) • [简体中文](./README.zh-CN.md)

> 当前文档对应版本：`v2.6.5`
>
> 💡 **一句话介绍**：将任何你常用的 AI 网站（ChatGPT, DeepSeek, Claude, Gemini 等）转换为标准的 OpenAI 兼容 API 接口，完全免费，支持本地部署。

## 📖 目录
1. [项目简介](#-项目简介)
2. [小白快速开始](#-小白快速开始)
3. [控制面板可视化导览](#-控制面板可视化导览)
4. [如何新增站点](#-如何新增站点)
5. [连接 API](#-连接-api)
6. [函数调用兼容说明](#-函数调用兼容说明)
7. [标签页池与预设系统](#-标签页池与预设系统)
8. [核心功能配置](#-核心功能配置)
9. [高级配置](#-高级配置)
10. [重要注意事项与已知限制](#-重要注意事项与已知限制)
11. [常见问题 (FAQ)](#-常见问题-faq)
12. [项目结构](#-项目结构)
13. [免责声明](#-免责声明)

---

## 💡 项目简介

这是一个基于 **浏览器自动化 (DrissionPage)** 技术的工具。它就像一个"机器人助理"，会在你的电脑上打开一个浏览器窗口，模仿人类的操作去和 AI 网页对话，然后把 AI 的回复通过标准 API 接口传回来给你。

**核心优势：**
* ✅ **0 成本**：直接利用网页版的免费对话额度。
* ✅ **数据安全**：账号在你自己本地登录，Cookie 不会上云，隐私完全掌握在自己手中。
* ✅ **高度智能**：内置 AI 语义分析引擎，不需要你去查网页源代码，只要告诉机器人"输入框在哪里"，它就能自己找到。
* ✅ **多标签并发**：支持同时打开多个标签页，自动调度，实现并行请求。
* ✅ **预设系统**：为同一站点创建多套配置方案（如对话、识图、代码），分配给不同标签页。

**已适配的站点：**

| 站点 | 地址 | 备注 |
|------|------|------|
| ChatGPT | chatgpt.com | 约 200k 单次最大发送长度 |
| DeepSeek | chat.deepseek.com | 思考模式下存在读取问题 |
| Gemini | gemini.google.com | 无会员约 30k，Pro 会员尚未发现上限 |
| Claude | claude.ai | 已支持站点级解析与适配 |
| Kimi | www.kimi.com | 当前文档按现有配置同步 |
| 通义千问 | chat.qwen.ai | 已支持 Qwen 页面适配 |
| Grok | grok.com | — |
| 豆包 | www.doubao.com | 已适配新版域名 |
| AI Studio | aistudio.google.com | — |
| Arena AI | arena.ai | IP 质量敏感，详见注意事项 |
> 对于未收录的网站，系统支持通过 AI 自动分析网页结构进行适配，详见「AI 元素识别」章节。

---

## 💬 交流群

如果遇到问题，可加 QQ 群 **1073037753** 交流反馈。

---

## 🚀 小白快速开始

### 1. 下载与安装

1. 下载 Release 中的压缩包。
2. 解压到一个 **没有中文路径** 的文件夹里（例如 `D:\AI_Tools\Universal-Web-API`）。
3. 确保你的电脑上安装了以下任一 Chromium 内核浏览器：
   - Google Chrome（推荐）
   - Microsoft Edge（Windows 10/11 自带）
   - Brave / Vivaldi / Opera

### 2. 启动与进入配置页面

1. 双击运行文件夹里的 **`start.bat`** 脚本。
   * 脚本会自动检测环境并安装必要的依赖，第一次运行可能需要一点时间，请耐心等待。
   * 脚本还会自动执行 DrissionPage 补丁（用于隐身模式优化）。
2. 当出现黑色命令行窗口（CMD）并停止滚动时，你会看到类似下面的提示：
   ```text
   Web UI 已启动，请访问: http://127.0.0.1:8199
   ```
3. **如何打开配置界面**：
   * 按住键盘上的 **Ctrl** 键，鼠标点击这个链接。
   * 或者手动复制 `http://127.0.0.1:8199` 到你的浏览器地址栏打开。

### 3. 登录账号

程序启动后，会自动弹出一个浏览器窗口（Chrome、Edge 或其他已检测到的 Chromium 内核浏览器）。

1. 在这个自动弹出的浏览器里，打开你要使用的 AI 网站。
2. **手动登录你的账号**。
   * **推荐登录**：登录后 API 也就拥有了你的账号权限（如 Plus 会员、历史记录等）。
   * **免登录**：如果该网站在未登录状态下允许对话，则无需登录即可直接调用。
3. 登录成功后，**不要关闭浏览器**，回到刚才打开的 Web UI 网页（8199 端口）开始配置。

> 💡 教程页现在不会再自动在脚本控制的浏览器中打开。你可以正常开着文档页查看说明；真正需要避免的是**你自己在受控浏览器里额外打开搜索页、资讯页或其他无关标签页**。

### 4. 第一次进入控制台先看哪里

第一次打开控制台时，建议先按这个顺序看：

1. **左上角服务状态**：确认浏览器是否已连接
2. **左侧站点列表**：确认你要用的站点是否已经收录
3. **站点配置页**：看选择器、工作流、流式配置是否已经存在
4. **标签页池**：确认当前网页标签有没有被系统识别
5. **日志页**：如果第一次测试失败，先看日志再改参数

![控制台总览](assets/tutorial-dashboard-overview.png)

---

## 🖥️ 控制面板可视化导览

控制面板不是一个“纯配置页”，而是整个项目的可视化中控台。理解每一页是干什么的，后面调试和新增站点会轻松很多。

### 左侧边栏

- 显示浏览器连接状态、认证状态、当前站点数量
- 支持搜索站点
- 支持新增站点、导入、导出
- 支持切换主标签页：站点、标签页、提取器、日志、设置

### 站点配置页

这是你最常待的地方，负责“这个网站到底怎么被程序操作”：

- **选择器**：输入框、发送按钮、结果容器在哪里
- **工作流**：先点哪里，再填哪里，再怎么等结果
- **图片提取**：网页里的生成图片怎么抓
- **响应检测**：什么时候算回复结束
- **文件粘贴**：长文本超限时是否改走文件上传
- **预设系统**：同一个站点拆成多套配置方案

### 标签页池

这是并发和多用途调用的核心：

- 能看到每个标签页的编号、状态、当前 URL
- 能复制指定标签页的专属接口
- 能给单个标签页切换不同预设
- 忙碌或异常时可以快速定位问题

### 提取器页

适合解决“网页明明有回复，但抓出来不对”的问题：

- 查看当前可用提取器
- 设置全局默认提取器
- 给站点绑定特定提取器
- 做验证标记，区分“只是绑定了”和“已经验证可用”

### 日志页

适合判断问题出在：

- 发送前
- 发送中
- 响应等待阶段
- 文本提取阶段
- 自动化命令阶段

### 设置页

适合改全局配置：

- **环境配置**：端口、认证、代理、AI 分析配置等，通常需要重启生效
- **浏览器常量**：元素查找超时、流式判定阈值等，通常即时生效
- **AI 元素识别**：定义辅助 AI 自动分析新站点时需要找哪些元素
- **更新白名单**：控制下次自动更新时，哪些文件或目录保持原样不被覆盖

---

## 🆕 如何新增站点

这部分是最容易卡人的地方。新增站点其实有两条路线：**AI 自动识别** 和 **手动配置**。

### 路线 A：让系统自动识别

适合页面结构比较标准，或者你想先快速跑通的时候。

**前置条件：**

1. 在控制面板 → 设置 → 环境配置中填好 `HELPER_API_KEY`、`HELPER_BASE_URL`、`HELPER_MODEL`
2. 在脚本控制的浏览器里打开目标站点
3. 确保停在真正可聊天的页面，而不是首页/欢迎页/登录页

**触发方式：**

当某个域名**不在 `config/sites.json` 中**时，第一次对该站点发起 API 请求，后端会：

1. 读取当前页面 HTML
2. 调用辅助 AI 分析页面结构
3. 自动生成 `selectors + workflow + 默认预设`
4. 保存到 `config/sites.json`

也就是说，**自动识别不是点“新增站点”按钮触发，而是未知域名第一次实际请求时触发。**

### 路线 B：手动新增并配置

适合以下情况：

- 你不想消耗辅助 AI token
- 网站结构比较怪，自动识别不准
- 你想完全自己掌控选择器和工作流

**操作步骤：**

1. 点击左下角的 **新增站点**
2. 输入域名，例如 `chat.example.com`
3. 进入该站点的 **主预设**
4. 先补最小必需选择器
5. 再补工作流
6. 用“测试选择器”逐个验证
7. 最后保存配置并实际调用一次 API

### 最小必填配置建议

#### 1. 选择器至少先配这三个

| Key | 作用 |
|-----|------|
| `input_box` | 聊天输入框 |
| `send_btn` | 发送按钮 |
| `result_container` | AI 回复容器 |

#### 2. 工作流先从最短链路开始

```json
[
  { "action": "CLICK", "target": "new_chat_btn", "optional": true, "value": null },
  { "action": "WAIT", "target": "", "optional": false, "value": 0.5 },
  { "action": "FILL_INPUT", "target": "input_box", "optional": false, "value": null },
  { "action": "CLICK", "target": "send_btn", "optional": true, "value": null },
  { "action": "KEY_PRESS", "target": "Enter", "optional": true, "value": null },
  { "action": "STREAM_WAIT", "target": "result_container", "optional": false, "value": null }
]
```

#### 3. 调试顺序建议

1. 先测 `input_box`
2. 再测 `send_btn`
3. 再测 `result_container`
4. 再跑整条工作流
5. 最后再去调流式阈值、提取器、图片提取、文件粘贴

### 新增站点时最实用的经验

- **不要一开始就堆很多步骤**，最容易把自己绕晕
- **不要先改全局浏览器常量**，优先把站点本身配通
- **自动识别完成后一定要人工校对**，特别是 `result_container`
- **如果网页回复已经出来，但 API 没结束**，优先检查流式配置而不是选择器

---

## 🔌 连接 API

本项目提供兼容 **OpenAI 格式**的接口，可以对接任何支持 OpenAI API 的客户端。

### 通用配置参数

| 配置项 | 填写内容 |
|--------|----------|
| **服务提供商** | 选择 `OpenAI`、`OpenAI 兼容` 或 `自定义` |
| **API 接口地址** | `http://127.0.0.1:8199/v1`（默认，自动分配标签页）|
| **API 密钥** | 任意填写即可（例如：`sk-any`）|
| **模型名称** | 任意填写（实际模型取决于你访问的网站）|

### 路由方式

| 路由 | 地址格式 | 说明 |
|------|----------|------|
| **默认路由** | `/v1/chat/completions` | 自动选择一个空闲标签页处理请求 |
| **指定标签页** | `/tab/{编号}/v1/chat/completions` | 使用特定编号的标签页（编号见控制面板的标签页池）|

> 部分客户端需要填写完整路径：`http://127.0.0.1:8199/v1/chat/completions`

### 调用示例

```bash
curl http://127.0.0.1:8199/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-any" \
  -d '{
    "model": "any",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'
```

### 关于 SillyTavern（酒馆）

> ⚠️ 酒馆的 API 测试功能可能出现 bug，**建议直接发送对话进行测试**，而非点击测试按钮。酒馆测试时发送的请求信息过短，特别是配合 AI Studio 时容易失败。

---

### 函数调用兼容说明

从 `v2.5.8` 开始，项目文档明确补充了对 **OpenAI 标准函数调用格式** 的兼容说明。你可以像对接普通 OpenAI 接口一样传入 `tools` / `tool_choice`，也兼容旧字段 `functions` / `function_call`。

但要特别注意：这不是官方原生的函数调用能力。本项目本质上仍然是把工具定义、工具历史和约束条件整理成网页端模型能理解的提示词，再依靠模型自己按要求输出结构化结果，后端再把它解析回 `tool_calls`。

这意味着它能用，但稳定性强依赖模型本身的“智力”和指令遵循能力：

- 模型越聪明、越擅长严格按格式输出，函数调用越稳定
- 模型较弱时，可能会出现函数名拼错、参数缺失、JSON 结构跑偏、输出混入解释文字等情况，最终导致后端无法解析
- 即使同一个站点，不同模型、不同提示词写法、不同工具数量，成功率也会有明显差异
- 整体体验通常仍然不如官方原生 Tool Calling API 稳定

如果你准备在客户端里开启函数调用，建议按下面的思路配置：

- 工具数量尽量少，先从 1 到 3 个开始
- 函数名尽量短、语义清晰，避免相似命名
- 参数 schema 尽量简单，优先扁平结构，少用深层嵌套
- 系统提示词和用户提示词不要过于冗长，避免把模型注意力冲散
- 如果经常出现“无法解析工具调用”，优先换更强的模型，而不是先继续堆规则

---

## 🗂️ 标签页池与预设系统

### 标签页池

标签页池是本项目的核心调度机制。脚本会自动扫描浏览器中打开的所有 AI 网站标签页，并为每个标签页分配一个**持久编号**。

**工作原理：**
1. 你在浏览器中打开一个或多个 AI 网站标签页
2. 脚本自动检测并将它们加入标签页池，分配编号（1, 2, 3...）
3. API 请求到达时，自动选择一个空闲的标签页来处理
4. 处理完成后，标签页被释放回池中，等待下一个请求

**在控制面板中管理：**
- 查看所有标签页的实时状态（空闲/忙碌/错误）
- 查看每个标签页的当前 URL 和请求计数
- 复制指定标签页的 API 端点地址
- 为标签页切换不同的预设配置

> 注意：`chrome://newtab` 等空白页不会被加入池，页面需加载完成后才会被识别。标签页编号在脚本运行期间保持不变，重启后会重新分配。

### 预设系统

预设系统允许你为同一个站点创建**多套独立的配置方案**，并将不同预设分配给不同的标签页。

**典型应用场景：**

| 标签页 | 预设名称 | 配置差异 |
|--------|----------|----------|
| 标签页 #1 | Pro 模型对话 | 完整工作流、较长超时、启用深度提取 |
| 标签页 #2 | 快速识图 | 简化工作流、启用图片提取、较短超时 |
| 标签页 #3 | 代码助手 | 启用文件粘贴、高阈值、启用网络拦截模式 |

**使用步骤：**
1. **创建预设**：在控制面板中选择站点 → 配置选项卡 → 点击「＋ 新建预设」
2. **分配预设**：切换到「标签页」选项卡 → 在标签页行中选择预设
3. **通过 API 调用**：使用 `/tab/{编号}/v1/chat/completions` 访问指定标签页

> 每个预设包含独立的选择器、工作流、流式配置、图片提取、文件粘贴等全套配置，互不影响。

---

## ⚙️ 核心功能配置

### 选择器配置 (Selectors)

每个站点需要定义一组 CSS 选择器，告诉程序去哪里输入、哪里点击：

| 选择器 | 必需 | 说明 |
|--------|------|------|
| `input_box` | ✅ | 聊天输入框 |
| `send_btn` | ✅ | 发送按钮 |
| `result_container` | ✅ | AI 回复内容的容器 |
| `new_chat_btn` | ❌ | 新建对话按钮 |

> 💡 你可以自定义更多选择器（如「临时对话按钮」），然后在工作流里添加对应的点击步骤。在控制面板的选择器配置项中点击「测试」按钮可以验证选择器是否生效。

### 工作流配置 (Workflow)

定义一系列动作的执行顺序：

```json
[
  { "action": "CLICK", "target": "new_chat_btn" },
  { "action": "WAIT", "value": 0.5 },
  { "action": "FILL_INPUT", "target": "input_box" },
  { "action": "CLICK", "target": "send_btn" },
  { "action": "STREAM_WAIT" }
]
```

| 动作类型 | 说明 |
|----------|------|
| `CLICK` | 点击元素（target 为选择器 key）|
| `FILL_INPUT` | 在输入框填入用户问题 |
| `WAIT` | 等待固定时间（value 为秒数）|
| `KEY_PRESS` | 模拟按键（如 Enter）|
| `STREAM_WAIT` | 等待响应完成 |

**对于小白用户**，大部分主流网站已经预设好了配置，通常只需要关注三个要素：

| 设置项 | 说明 | 示例 |
|--------|------|------|
| **Key (元素名)** | 给这个操作对象起个英文名 | `input_box` |
| **描述** | 用大白话描述这是什么，AI 会根据描述去网页里找 | `这是聊天的输入框` |
| **是否启用** | 勾选后机器人才会操作这一步 | `☑️` |

![工作流可视化](assets/workflow-visualization.png)

### 提取器配置 (Extractors)

提取器决定如何从网页 HTML 中解析出干净的 Markdown 文本：

- **默认模式**：自动提取 `result_container` 中的文本
- **深度模式 (deep_mode)**：针对复杂的 LaTeX 公式、代码块进行特殊处理（**推荐**）

> ⚠️ 目前只有深度模式经过深度优化，其他模式处于未完善状态。即使是深度模式，某些复杂代码块也可能无法正确处理，此时可切换为网络拦截模式。

### 响应检测配置

支持两种检测模式：

| 模式 | 是否流式 | 说明 |
|------|----------|------|
| **DOM 模式**（默认） | ✅ 流式 | 轮询检测页面 DOM 变化，实时输出内容 |
| **网络拦截模式** | ✅ 流式（按站点适配） | 拦截浏览器网络请求并解析增量响应，通常更快、更稳 |

**DOM 模式调优建议：**

| 场景 | 静默超时阈值 | 稳定判定次数 | 初始等待 |
|------|-------------|-------------|----------|
| 快速模型 (GPT-4o) | 3-5 秒 | 3-5 次 | 60 秒 |
| 慢速思考 (o1/Claude) | 10-15 秒 | 8-12 次 | 300 秒 |
| 代码生成 | 8-10 秒 | 6-8 次 | 180 秒 |
| 长文生成 | 12-15 秒 | 10 次 | 300 秒 |

> ⚠️ **关于网络拦截模式**：目前仅针对部分站点做了适配。如果某个站点默认没有开启网络拦截，**请谨慎手动开启**——可能无适配或会增加被检测风险。

### 图片提取配置

配置程序如何处理网页中生成的图片：

```json
{
  "enabled": true,
  "selector": "img",
  "container_selector": ".img-grid",
  "download_blobs": true,
  "mode": "all",
  "max_size_mb": 10
}
```

- **发送的图片**保存在根目录 `image/`
- **捕获的图片**保存在根目录 `download_images/`

### 文件粘贴

当发送的文本长度超过阈值时，系统会先把文本写入项目根目录下的临时 `.txt` 文件，再尝试把这个文件作为真实附件送进网页。它的目标不是单纯往输入框里塞文字，而是尽量走站点自己的上传通道，绕过长文本输入限制。

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 启用 | 站点预设决定 | 是否开启文件粘贴模式 |
| 阈值 | 默认 `50000` 字符 | 文本超过此值时触发，不同站点预设可单独覆盖 |
| 引导文本 | `完全专注于文件内容` | 文件挂载成功后自动追加到输入框里的提示语 |

当前实现的实际顺序大致是：

1. 创建临时 `.txt` 文件
2. 优先尝试站点配置里的 `file_input`
3. 再尝试页面上通用的 `input[type=file]`
4. 如果配置了 `upload_btn`，会先点上传按钮，再重新尝试上传入口
5. 如果配置了 `drop_zone`，会尝试走拖拽投递
6. 以上都不行时，最后才回退到 Windows 剪贴板文件粘贴
7. 检查页面上是否真的出现了“文件已挂载”的信号
8. 成功后再补一段 `hint_text`，确保模型会去读文件内容

这也意味着“文件粘贴”现在已经不只是老版本那种单纯的 `Ctrl+V` 文件剪贴板方案了，而是一个站点感知的上传流程。你如果要给新站点配长文本支持，除了 `file_paste.enabled` 以外，也要优先考虑这三个选择器：

- `upload_btn`
- `file_input`
- `drop_zone`

按当前默认预设，已经开启文件粘贴的站点有：`aistudio.google.com`、`chatgpt.com`、`chat.deepseek.com`、`www.doubao.com`、`chat.qwen.ai`。其余站点默认关闭，需要你自己确认网页是否真能收 `.txt` 文件后再开。

> ⚠️ 文件粘贴并不等于“任何站点都能稳定上传文件”。如果目标网页本身不接受附件，或者上传成功后页面没有真正挂载文件，系统会放弃文件粘贴并回退到普通文本输入。

### 自动化命令系统（自 2.5.6 起）

自动化命令是一个独立的“策略引擎”，用于在对话运行过程中自动执行恢复、分流、告警等动作。

#### 1) 触发器类型（最新）

| 触发器 | 说明 | 典型用途 |
|--------|------|----------|
| `request_count` | 对话次数达到阈值 | 每 N 轮清理环境 |
| `error_count` | 连续错误次数达到阈值 | 失败积累后重置 |
| `idle_timeout` | 标签页空闲超过指定秒数 | 自动回收异常标签页 |
| `page_check` | 页面出现指定文本 | 命中验证码/提示词时处理 |
| `command_triggered` | 某命令触发后再触发本命令 | 串联执行 |
| `command_result_match` | 匹配上一命令（或某步骤）返回值 | 条件分支 |
| `network_request_error` | 匹配网络请求 URL + 状态码 | 提前拦截 403/429/5xx |

#### 2) 动作类型（最新）

| 动作 | 说明 |
|------|------|
| `clear_cookies` / `refresh_page` / `new_chat` / `wait` / `run_js` | 基础恢复动作 |
| `execute_preset` / `execute_workflow` | 执行预设与工作流 |
| `navigate` | 跳转 URL |
| `switch_proxy` | 通过 Clash 切换代理 |
| `send_webhook` | 发送外部告警（钉钉/企微/Telegram/Server 酱） |
| `abort_task` | 立即中断当前任务（并可停止后续动作） |

#### 3) 条件分支（命令结果匹配）

`command_result_match` 支持 4 个核心字段：

| 字段 | 说明 |
|------|------|
| 监听命令（`command_id`） | 选择上游命令 |
| 目标步骤（`action_ref`） | 可选，不选则匹配命令最终返回值 |
| 匹配规则（`match_rule`） | `equals` / `contains` / `not_equals` |
| 期望值（`expected_value`） | 如 `CSS_FAILED` / `SUCCESS` |

实战建议：
- 探针命令先用 `run_js` 返回明确状态字符串（如 `CSS_FAILED`）。
- 分支命令用 `command_result_match` 接住结果，分别执行“重置策略”或“继续流程”。

#### 4) Webhook 告警

`send_webhook` 支持 `GET/POST`、自定义 Header、超时、失败策略，并支持模板变量：

`{{tab_index}}`、`{{domain}}`、`{{network_status}}`、`{{network_url}}`、`{{timestamp}}`

示例 payload：

```json
{"msg":"标签页 #{{tab_index}} 在 {{domain}} 命中 {{network_status}}，URL={{network_url}}"}
```

#### 5) 网络异常拦截（独立于 stream_mode）

从 `2.5.6` 开始，`network_request_error` 不再依赖站点必须启用 `stream_config.mode=network`：

- 即使站点在 DOM 模式，仍会启动“仅事件监听（event-only）”用于拦截异常状态码。
- 命中后可立即执行 `switch_proxy` / `refresh_page` / `send_webhook` / `abort_task`。
- 正则模式支持标准正则；若误填 `*/queue/join*` 这类通配写法，会自动兜底匹配。

#### 6) 推荐编排（防死锁）

1. 先建“网络异常拦截”命令：`URL 规则 + 状态码(403,429,500,502,503,504)`。  
2. 动作链建议：`switch_proxy -> wait(1~2s) -> refresh_page -> send_webhook(可选)`。  
3. 需要硬切断时追加 `abort_task`。  
4. 作用范围优先用“指定域名”，避免误伤其他站点。  
5. 最后在日志页观察 `[CMD]` 与 `NetworkMonitor` 日志，确认命中。

---

## 🔧 高级配置

### 隐身模式 (Stealth Mode)

开启后，脚本的所有操作会加入随机延迟和模拟人类特征，防止被网站识别为脚本。

| 行为 | 普通模式 | 隐身模式 |
|------|----------|----------|
| 鼠标点击 | 直接 CDP 命令 | 模拟真实鼠标按压（含 pressure、微移、释放偏移）|
| 鼠标移动 | 瞬间跳转 | 人类化曲线移动 |
| 空闲时 | 无动作 | 随机微漂移（模拟手部抖动）|
| 操作间隔 | 最小延迟 | 随机化延迟（0.1-0.3 秒）|

**使用建议：**
- **需要开启**：访问有 Cloudflare 防护的站点（如 arena.ai、chatgpt.com）
- **不需要开启**：访问无防护或低防护的站点（如 AI Studio、DeepSeek）
- 如果网站没有强制弹验证码，建议**不开启**以提高运行速度

> ⚠️ **高强度防御无法绕过**：对于 Cloudflare 盾等级调得非常高的网站（如 arena.ai），即使开启隐身模式也可能被拦截。arena.ai 在半小时内连续对话约 10 条几乎一定会触发人机验证，真人操作也同样如此。

**DrissionPage 补丁**：`start.bat` 会在依赖安装后自动执行补丁。也可以手动执行：
```bash
python patch_drissionpage.py          # 执行补丁
python patch_drissionpage.py --restore # 恢复原文件
```
> 每次升级 DrissionPage 后需要重新执行补丁。

### AI 元素识别

当你访问的站点不在已适配列表中时，系统可以调用 AI 自动分析网页结构，识别出输入框、发送按钮等关键元素。

**默认识别项：**

| 关键词 | 描述 | 必需 |
|--------|------|------|
| `input_box` | 用户输入文本的输入框 | ✅ |
| `send_btn` | 发送消息的按钮 | ✅ |
| `result_container` | AI 回复内容的容器 | ✅ |
| `new_chat_btn` | 新建对话的按钮 | ❌ |
| `message_wrapper` | 消息完整容器 | ❌ |
| `generating_indicator` | 生成中指示器 | ❌ |

**使用流程：**
1. 在控制面板 → 设置 → AI 分析配置中，填写你自己的 OpenAI 格式 API 地址和 Key
2. 在浏览器中打开未适配的网站，并停留在真正可聊天的页面
3. 第一次向该未知域名发起 API 请求时，系统会自动调用辅助 AI 分析网页（约消耗 **8000 tokens**）
4. 分析成功后，配置会自动写入 `config/sites.json`

> 如果你只使用已适配的站点，不需要关注此功能。你也可以跳过 AI 分析，手动配置选择器。


### 环境配置

在控制面板 → 设置 → 环境配置中修改，**需重启服务生效**。

| 分类 | 配置项 | 默认值 | 说明 |
|------|--------|--------|------|
| 服务 | 监听地址 | `127.0.0.1` | `0.0.0.0` 允许外部访问 |
| 服务 | 监听端口 | `8199` | HTTP 服务端口 |
| 服务 | 调试模式 | 开启 | 开启 API 文档 `/docs` |
| 认证 | 启用认证 | 关闭 | 是否要求 Bearer Token |
| 代理 | 代理地址 | — | 支持 `socks5://` 或 `http://` |
| 浏览器 | Chrome 调试端口 | `9222` | 浏览器远程调试端口 |

> 完整参数说明请查阅根目录下的 **[参数解释.md](./参数解释.md)** 文件。

### 浏览器常量

在控制面板 → 设置 → 浏览器常量中修改，**即时生效**。包括操作延迟、元素查找超时、响应检测参数等。**大部分情况下保持默认即可，无需修改。**

### 更新白名单

在控制面板 → 设置 → 更新白名单中修改。点击“保存”后会写入 `config/update_settings.json`，并在**下次自动更新**时生效。

- 它控制的是“更新时是否保留不变”，不是运行时启用/禁用开关。
- 勾选目录项（如 `config/`、`app/`、`static/`）时，会保留整个目录。
- `config/sites.json` 与 `config/commands.json` 在**未勾选**时，更新器会优先做合并：补入发布版新增内容，同时尽量保留本地已有站点、命令和状态；如果**勾选**，则整份文件保持本地版本不动。
- `config/update_settings.json` 会被更新器内部自动保留，无需手动勾选。

当前默认保留项：

- `config/sites.local.json`：保留站点默认预设覆盖
- `config/commands.local.json`：保留命令启用状态与分组覆盖
- `chrome_profile/`：保留浏览器登录态、Cookie 与用户目录
- `venv/`：保留 Python 虚拟环境
- `logs/`：保留日志目录
- `image/`：保留图片输出目录
- `updater.py`：保留更新脚本本体
- `.git/`：保留 Git 元数据
- `__pycache__/`：保留 Python 缓存目录
- `*.pyc`：保留 Python 编译缓存文件
- `backup_*/`：保留更新前备份目录

可勾选范围覆盖这些分类：`核心配置`、`本地覆盖`、`运行数据`、`后端代码`、`前端资源`、`脚本与文档`、`开发文件`。如果你只是想保留登录态和个人配置，通常保持默认勾选即可。

---

## ⚠️ 重要注意事项与已知限制

### 🛑 运行中请勿干扰浏览器

当工作流正在执行时：
* **禁止操作**：不要去点击网页上的任何按钮（特别是不要替脚本点击"发送"）
* **禁止切屏**：尽量不要切换浏览器的标签页或最小化窗口
* **禁止折叠**：不要手动缩小页面边框或折叠某些按钮
* **后果**：人为干预会导致脚本逻辑错乱，引发**脚本死锁 (Deadlock)** 或产生预期之外的行为
* **正确做法**：你可以静静地看着浏览器自动操作，不要动手。如果脚本卡死，请关闭 CMD 窗口，**重启 `start.bat`**

### 📉 特殊格式抓取限制

在使用提取器（DOM 模式）进行内容提取时存在一定局限性：
* **代码块、LaTeX 与超链接**：脚本**可能无法完整捕捉**，或者抓取结果出现格式错误
* 如果主要用于角色扮演等纯文本场景，DOM 模式完全够用
* 如果用于写代码，可切换为**网络拦截模式**（适配站点通常更稳，但仍需按站点配置）

### 📏 上下文长度限制

受限于网站输入框一次性所能容纳的字符上限，上下文不能太长，否则请求会直接失败。可以开启「文件粘贴」功能来绕过部分限制。

### 🌐 关于 arena.ai

该站点非常看重 IP 质量。**IP 好的可以一直对话，IP 不好的一次就会被拦截。** 建议谨慎使用网络监听相关功能（额外监听可能增加被检测概率）。

### 🐛 已知问题

- DeepSeek 思考模式下存在读取问题
- VSCode 中 **Codex** 插件不适配，原因未知
- DrissionPage 补丁需在每次升级后重新执行

---

## ❓ 常见问题 (FAQ)

### Q1: 运行 start.bat 后闪退，或者浏览器没有弹出来

程序会按以下优先级自动检测浏览器：Chrome → Edge → Brave → Vivaldi → Opera。如果都未找到，可以在 `.env` 文件中手动指定：
```
BROWSER_PATH=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
```

### Q2: 网页配置打不开 (http://127.0.0.1:8199 无法访问)

- 检查黑色的命令行窗口是否被关闭了？CMD 窗口必须一直开着
- 检查端口 8199 是否被其他软件占用

### Q3: 为什么发消息给 AI 后，一直显示"等待中"或超时？

1. **观察浏览器**：切到自动弹出的浏览器看一眼
   - 如果是网速慢，网页还没加载出来 → 请刷新网页
   - 如果是弹出了验证码 → 请手动帮机器人点一下验证码
2. **调整配置**：在工作流中适当增加"等待时间"
3. **检查干扰**：请确认你没有在脚本运行时手动点击过网页

### Q4: 使用时频繁失败怎么办？

请按以下顺序排查：
1. **人为干涉了工作流**：脚本执行过程中不能操作脚本控制的浏览器
2. **折叠边框**：必须将折叠元素全部展开（浏览器可以最小化但不能缩小边框）
3. **网站状态异常**：可能触发了人机验证、单次发送信息太长被拒绝、或内容包含违规信息
4. **网络问题**：网络波动或代理切换 IP 导致发送失败，可能引发脚本死锁，需要重启脚本或等待约 5 分钟
5. **多余标签页**：不要在脚本控制的浏览器里额外打开无关标签页（如搜索页、资讯页、普通网页）。教程页本身现在不会再自动占用受控浏览器标签。
6. **站点配置失效**：网站更新后选择器可能失效，可在 GitHub 提 Issue 或加群反馈

### Q5: 总是提示 "Context Too Long"

这取决于你登录的网页版账号权益。如果你用的是免费版 ChatGPT，上下文通常限制在 8k 左右。这是网站的限制，不是本软件的限制。

### Q6: 标签页池中看不到新打开的标签页？

- 新标签页的网页是否已经**加载完成**（空白页不会被识别）
- 等待 2-3 秒后点击「立即刷新」按钮
- 如果仍然看不到，重启脚本即可

### Q7: 控制面板的参数应该怎么调？

**大多数时候不需要调整**，所有参数都有经过优化的默认值，可以满足绝大多数使用场景。

### Q8: 这个项目有什么用？

- **免费额度利用**：将网页端免费额度转化为 OpenAI 格式的 API
- **调试上下文**：便捷查看前端如何构造上下文
- **多标签页 + 多预设**：同时开多个标签页实现多用途并行
- **长文本绕过**：通过文件粘贴功能绕过部分网站输入框的字符限制

---

## 📁 项目结构

```
📁 Universal-Web-API/
├── 📁 app/                  # 🐍 Python 后端核心代码库
│   ├── 📁 api/              # [接口层] HTTP 请求处理
│   ├── 📁 core/             # [核心层] 浏览器自动化与底层逻辑
│   │   ├── 📁 extractors/   # 提取策略（深度/DOM/混合/图片）
│   │   ├── 📁 parsers/      # 各站点专用内容解析器
│   │   └── 📁 workflow/     # 工作流执行引擎
│   ├── 📁 models/           # [数据模型层] Pydantic 数据结构
│   ├── 📁 services/         # [业务逻辑层] 配置引擎、请求调度
│   └── 📁 utils/            # [工具层] 剪贴板、图片处理等
├── 📁 config/               # 🔧 配置文件目录
│   ├── sites.json           # 站点数据库（URL、选择器、工作流）
│   ├── browser_config.json  # 浏览器启动配置
│   ├── extractors.json      # 提取器配置
│   └── image_presets.json   # 图片预设配置
├── 📁 static/               # 🎨 前端静态资源（Web UI 控制面板）
├── .env                     # 🔒 环境变量
├── main.py                  # ▶️ 程序主入口
├── start.bat                # 🚀 Windows 一键启动脚本
├── requirements.txt         # 📦 Python 依赖列表
└── 参数解释.md               # 📝 配置参数详细说明
```

## 依赖

**后端：**
- FastAPI - Web 框架
- uvicorn - ASGI 服务器
- DrissionPage - 浏览器自动化
- beautifulsoup4 - HTML 解析
- pydantic - 数据验证

**前端：**
- [Vue.js](https://vuejs.org/) - JavaScript 框架

---

## 后续开发

| 计划 | 状态 |
|------|------|
| 增加并发能力 | 🚧 进行中 |
| Cookie 模拟模式（低资源占用，无需浏览器） | 🚧 规划中 |
| Bug 修复 | 🔄 持续进行 |

### 两种模式规划

| 模式 | 适用场景 | 优势 | 劣势 | 状态 |
|------|---------|------|------|------|
| **浏览器自动化模式** | 防护严格的网站（ChatGPT、Claude、Grok 等） | 完全模拟真实用户、可绕过大部分检测 | 资源占用高、响应速度较慢 | ✅ **当前支持** |
| **Cookie 模拟模式** | 防护宽松的网站（部分开源 AI、本地部署等） | 资源占用低、响应速度快、无需浏览器 | 需分析请求结构、容易被检测 | 🚧 **规划中** |

---

## ⚖️ 免责声明

**请在使用本项目前仔细阅读以下声明**

### 使用目的

本项目 (Universal Web-to-API) 仅供**学习、研究和技术交流**使用，旨在探索浏览器自动化技术和 API 设计模式。

### 服务条款合规

1. **用户责任**：使用本项目访问任何第三方网站时，您必须遵守该网站的服务条款 (Terms of Service)、使用协议及相关法律法规。
2. **自动化限制**：许多网站明确禁止或限制自动化访问行为。使用本项目可能违反这些网站的服务条款，导致账号封禁、IP 封锁或法律诉讼风险。
3. **使用建议**：
   - 仅在目标网站明确允许自动化访问的情况下使用
   - 优先使用官方提供的 API（如有）
   - 控制请求频率，避免对服务器造成负担
   - 不要用于商业用途或大规模自动化

### 风险提示

- **账号风险**：目标网站可能检测并封禁您的账号
- **数据风险**：自动化过程中可能导致数据丢失或泄露
- **法律风险**：某些司法管辖区可能认定此类行为违法
- **安全风险**：第三方依赖库可能存在安全漏洞

### 隐私和数据

1. 本项目在本地运行，不会主动收集或上传您的任何数据
2. 您需自行确保辅助 AI API（如配置）的数据安全性
3. 请勿在生产环境或处理敏感数据时使用本项目

### 责任限制

本项目作者和贡献者**不对以下情况承担任何责任**：使用本项目导致的账号封禁、数据丢失等任何直接或间接损失；违反第三方服务条款产生的法律后果；因项目缺陷、错误或故障造成的任何损害。

本项目按"现状"(AS IS) 提供，**不提供任何明示或暗示的保证**。

### 开源协议

本项目采用 **AGPL-3.0 许可证**。允许修改和分发，但必须保持相同的开源协议。如果您修改本项目并通过网络提供服务，必须公开源代码。

### 特别提醒

- ⚠️ 切勿将本项目用于任何非法用途
- ⚠️ 切勿用于规避付费服务或侵犯知识产权
- ⚠️ 切勿对目标网站进行高频请求或恶意攻击
- ⚠️ 建议仅在测试环境中使用
- ⚠️ 商业使用前请咨询法律顾问

**使用本项目即表示您已阅读并理解本免责声明的全部内容，同意自行承担所有使用风险和后果。如果您不同意上述任何条款，请立即停止使用本项目。**