内容
# 🚀 WebBrain Ultimate Edition (3合1)
欢迎来到 **WebBrain Ultimate Edition (3合1)** - 这是一款完整的、优化到极致的AI浏览器代理集成解决方案。该安装包将三个重要的组件合并到一个单独的发行目录中，它继承并发展了社区中高质量的开源代码。
---
## 📂 软件包结构
```text
3in1/
├── extension/ # 集成Tab Bar及3种界面交互的Chrome扩展程序
├── server/ # WebSocket MCP Server（已集成通过CDP上传文件，不包含node_modules）
└── scripts/ # 简洁的Node.js脚本，用于自动加载本地资源
```
---
## 🛠️ 快速安装与运行指南
### 步骤 1：安装Chrome扩展程序
1. 访问Chrome扩展程序管理页面：`chrome://extensions/`。
2. 在右上角启用 **开发者模式**。
3. 点击左上角的 **加载已解压的扩展程序**。
4. 选择目录：`3in1/extension`。
5. 打开WebBrain的侧边栏，开始使用。
### 步骤 2：为IDE/AI代理安装和配置MCP服务器
WebBrain服务器采用双重通信机制：
- **WebSocket (`ws://localhost:8545`)**: 直接连接到Chrome扩展程序并进行控制。
- **STDIO（标准输入/输出）**: 与IDE和AI代理（Antigravity、Claude Code、Codex、Cursor、Windsurf、Claude Desktop等）连接。
#### 1. 安装依赖：
在`server`目录下的终端中安装库：
```bash
cd 3in1/server
npm install
```
#### 2. 将MCP服务器添加到IDE/AI代理：
* **Antigravity / VS Code / Cursor / Windsurf / Codex / Claude Desktop**（使用JSON配置文件`mcp.json`或`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"webbrain": {
"command": "node",
"args": ["C:/path/to/3in1/server/index.js"]
}
}
}
```
*(用您机器上的`server`目录中`index.js`文件的绝对路径替换`C:/path/to/3in1/server/index.js`)*。
* **Claude Code (CLI)**：
在终端中直接运行命令以注册MCP服务器：
```bash
claude mcp add webbrain -- node C:/path/to/3in1/server/index.js
```
> 💡 **重要注意：** 当您添加了`mcpServers`配置或运行`claude mcp add`命令后，IDE/AI代理将**自动启动**MCP服务器（`node index.js`）在后台每次启动。因此，您**不需要**手动在终端中运行`npm start`命令，以免占用WebSocket端口`8545`（`EADDRINUSE`）。
* **手动启动（仅用于开发/调试，不通过IDE）**：
```bash
cd 3in1/server
npm start
```
*(仅在直接从终端测试而不声明IDE中的`mcpServers`文件时打开)*。
#### 3. 检查连接：
1. **浏览器端：** 返回扩展程序的侧边栏 → **MCP服务器**选项卡 → 显示 **CONNECTED** 状态（成功连接到WebSocket端口`ws://localhost:8545`）。
2. **IDE/代理端：** IDE将通过STDIO自动调用`node index.js`并识别`webbrain`的28个MCP工具（例如`get_accessibility_tree`、`click_ax`、`upload_file`等）。
### 步骤 3：运行Shopee爬虫并下载资源
1. 在侧边栏中选择 **Shopee爬虫**选项卡。
2. 粘贴需要爬取的Shopee产品链接列表。
3. 输入Gemini API密钥（或OpenAI端点）→ 点击 **开始爬取**。
4. 完成后，导出JSON结果文件（例如`shopee_scraped.json`）。打开终端并运行命令下载原始图像/视频：
```bash
node ../scripts/download-media.js "C:/path/to/your/shopee_scraped.json"
```
*图像CDN和介绍视频将自动保存在`3in1/downloads/`目录中，按产品名称分类。*
---
## 📋 各工具技术细节
该系统在3个独立的流程中并行运行，提供从原始上下文交互到深入系统干预的工具集：
### 1. AI浏览器代理流程（选项卡1 - WebBrain聊天）
作为与当前网页内容直接对话的聊天助手，通过推荐的操作：
* **与页面聊天：** 根据活动选项卡中显示的文本进行上下文分析并回答问题。
* **页面总结：** 快速总结长篇文档/研究论文的内容。
* **任务规划：** 根据用户的自然提示，草拟计划并自动执行基本操作。
### 2. 模型上下文协议流程（选项卡2 - WebSocket MCP服务器）
在`8545`端口发布 **28个系统工具** 到WebSocket服务器，供外部代理（例如Claude、Gemini、IDE）连接和远程控制浏览器。工具列表包括：
* **精确DOM交互组（可访问性树）：**
* `get_accessibility_tree`：读取当前页面的可访问性树，生成唯一的`ref_id`标识符。
* `click_ax`：使用`ref_id`精确点击DOM元素。
* `type_ax`：使用`ref_id`在输入字段中输入文本。
* `set_field`：快速填充文本并可选地按Enter键。
* `hover`：使用`ref_id`将鼠标悬停在元素上。
* `get_selection`：提取当前选定的文本。
* **导航和网络状态组：**
* `navigate`：重定向到特定URL。
* `new_tab`：创建新选项卡并将其分组到WebBrain。
* `go_back` / `go_forward`：在浏览历史中后退或前进。
* `wait_for_stable`：等待页面稳定并完成渲染。
* **窗口和界面操作组：**
* `resize_window`：调整Chrome窗口大小。
* `get_window_info`：获取当前窗口大小和选项卡列表。
* `screenshot`：捕获当前视口的截图。
* **文件管理和下载组：**
* `list_downloads`：搜索已下载文件历史记录。
* `download_files`：通过Chrome下载管理器从URL直接下载文件。
* `upload_file` *(特权CDP)*：使用`chrome.debugger` API将本地文件上传到网页。
* **备用DOM操作组（CSS选择器）：**
* `click` / `type_text`：使用CSS选择器或索引执行点击和输入操作。
* `wait_for_element`：等待元素出现。
* `get_interactive_elements`：扫描粗略交互元素及其索引。
* `extract_data`：提取结构化数据，如表格或链接。
* `read_page` / `read_page_source`：读取可见文本或获取`outerHTML`。
* **高级执行组：**
* `execute_js`：动态执行异步JavaScript代码。
### 3. Shopee爬虫流程（选项卡3 - Stealth爬虫）
运行具有结构化数据爬取的Shopee爬虫，集成生物启发机制以避免被封：
* **隐身人性化：** 自动模拟自然滚动和随机鼠标移动，以绕过检测算法。
* **AI数据解析：** 捕获屏幕截图并将原始文本发送到LLM（Gemini、DeepSeek）进行分析，返回标准JSON结构。
* **媒体链接提取：** 运行隔离的JavaScript代码以提取高质量图像CDN链接和产品视频链接。
---
## 🌟 Ultimate版独家改进
1. **闪烁边框效果：** 运行MCP任务时，选项卡周围的渐变紫色边框会连续闪烁，任务完成后熄灭。
2. **智能选项卡分组：** 当点击Shopee爬取时，新选项卡将创建在当前选项卡旁边。如果当前选项卡在选项卡组中，新爬取选项卡将自动加入该组。
3. **保持爬取选项卡：** 完成爬取后保持选项卡在最后一个产品页面，并将边框颜色更改为绿色表示成功。
4. **直观的中文解释：** 在侧边栏界面上集成28个MCP工具的解释。
---
## 💖 鸣谢与致敬
**WebBrain Ultimate Edition (3合1)** 项目基于社区的优秀贡献进行开发、定制和打包。我们深深感谢：
* **原始WebBrain项目：** 由 [webbrain-one](https://github.com/webbrain-one/webbrain) 开发 - 优秀的Chrome扩展AI代理平台。
* **作者的WebBrain MCP分支：** 由 [nqtruong136/webbrain](https://github.com/nqtruong136/webbrain) 存储和贡献 - 提供第一个WebSocket MCP服务器连接的基础。
*开源代码是创造力的桥梁，我们衷心感谢所有贡献者！*
