ZenLink
Zen浏览器和Firefox的浏览器自动化桥 通过简单的HTTP API控制浏览器。
作为Chrome MCP的快速、有效的替代品而构建。与任何可以发出HTTP请求的AI助手、自动化工具或脚本配合使用。
为什么选择ZenLink?
AI桌面助手(Claude、ChatGPT、Copilot等)通常需要与浏览器交互 填写表格、阅读页面、截图、浏览网站。大多数解决方案要么只有Chrome,要么有缺陷,要么需要复杂的设置。
ZenLink是一个轻量级的HTTP网桥 任何可以调用的 curl 或 fetch 完全控制Zen浏览器或Firefox。无特殊SDK,无专有协议 仅限于本地主机上的REST端点。
运作原理```
Any AI Assistant / Script / Tool
|
| HTTP request (e.g. POST http://localhost:8765/api/click)
v
ZenLink Bridge Server (Python, localhost:8765)
|
| WebSocket relay (ws://localhost:8766)
v
ZenLink Browser Extension
|
| browser.tabs API + content scripts
v
Web Page DOM click, type, read, screenshot, etc.
**核心思想:** 您的AI助手具有shell访问权限(终端、PowerShell、bash)。它向ZenLink的本地服务器发送HTTP请求。服务器通过WebSocket将命令中继到浏览器扩展。扩展程序在实际的浏览器选项卡中执行它们并返回结果。
### 示例:人工智能助手如何填写登录表单
1. **你说:** “登录example.com上的我的帐户”
1. **AI运行:** `curl -X POST localhost:8765/api/navigate -d '{"url":"https://example.com/login"}'`
1. **AI运行:** `curl -X POST localhost:8765/api/fill -d '{"selector":"#email","value":"me@example.com"}'`
1. **AI运行:** `curl -X POST localhost:8765/api/fill -d '{"selector":"#password","value":"secret"}'`
1. **AI运行:** `curl -X POST localhost:8765/api/click -d '{"selector":"#submit"}'`
1. **浏览器:** 导航、填写字段、单击提交 您已登录。
或者与 **批处理端点** (一个请求,多个命令):```json
POST http://localhost:8765/api/batch
{
"commands": [
{"action": "navigate", "url": "https://example.com/login"},
{"action": "sleep", "ms": 2000},
{"action": "fill", "selector": "#email", "value": "me@example.com"},
{"action": "fill", "selector": "#password", "value": "secret"},
{"action": "click", "selector": "#submit"}
]
}
谁可以使用这个?
| 工具 | 它如何调用ZenLink |
|---|---|
| 克劳德桌面版 (通过MCP外壳) | Invoke-RestMethod http://localhost:8765/api/... |
| ChatGPT (通过代码解释器/操作) | 对localhost的HTTP请求 |
| 任何具有终端访问权限的AI | curl, wget, requests, fetch |
| Python脚本 | requests.post("http://localhost:8765/api/click", json={...}) |
| Node.js | fetch("http://localhost:8765/api/...") |
| Bash脚本 | curl -s localhost:8765/api/page-text |
| PowerShell | Invoke-RestMethod localhost:8765/api/status |
如果它可以发出HTTP请求,它就可以控制你的浏览器。
快速开始
1.安装Python依赖项```bash
pip install websockets
### 2.在Zen浏览器(或Firefox)中加载扩展
1. 打开 `about:debugging#/runtime/this-firefox`
1. 点击 **加载临时加载项。。。**
1. 选择 `manifest.json` 从该文件夹
### 3.启动桥梁```bash
python native/bridge.py
或者双击 start-bridge.bat
4.验证```bash
curl http://localhost:8765/api/status
{"status": "running", "extension_connected": true}
## API 参考
### 读取操作(GET)
|端点|描述|
|----------|-------------|
| `/api/status` |桥接+扩展连接状态|
| `/api/tabs` |列出所有打开的选项卡|
| `/api/page-info` |URL、标题、尺寸、滚动位置|
| `/api/page-text` |从页面中提取可读文本|
| `/api/dom` |可访问性树|
| `/api/forms` |所有带有标签和值的表单字段|
| `/api/screenshot` |捕获视口(保存PNG,返回路径)|
### 动作操作(POST)
|端点|正文|描述|
|----------|------|-------------|
| `/api/navigate` | `{"url": "...", "expectTitle": "..."}` |加载URL(重定向检测的可选标题检查)|
| `/api/new-tab` | `{"url": "..."}` |在新选项卡中打开URL|
| `/api/close-tab` | `{"tabId": 123}` |按ID关闭选项卡|
| `/api/switch-tab` | `{"tabId": 123}` |聚焦选项卡|
| `/api/click` | `{"selector": "..."}` 或 `{"coords": {"x":0,"y":0}}` |点击元素|
| `/api/type` | `{"selector": "...", "text": "...", "clear": true}` |输入|
| `/api/fill` | `{"selector": "...", "value": "..."}` |设置表单字段值|
| `/api/scroll` | `{"direction": "down", "amount": 1}` |滚动页面(`amount` =视口高度,默认值1)|
| `/api/hover` | `{"selector": "..."}` |将鼠标悬停在元素上|
| `/api/find` | `{"query": "login button"}` |按描述查找元素|
| `/api/js` | `{"code": "document.title"}` |执行JavaScript(50KB结果限制,返回 `truncated: true` 如果超过)|
| `/api/highlight` | `{"selector": "..."}` |元素上的视觉叠加|
| `/api/clear-highlight` | _(无)_ |删除所有高光覆盖|
| `/api/page-text-by-tab-id` | `{"tabId": 123}` |从特定选项卡中提取文本(不仅仅是活动选项卡)|
| `/api/wait-for-element` | `{"selector": "...", "timeout": 10000}` |轮询直到元素出现在DOM中|
| `/api/wait-for-result` | `{"code": "...", "timeout": 15000}` |轮询JS表达式,直到它返回非空|
| `/api/batch` | `{"commands": [...], "stopOnWarning": true}` |运行多个命令(如果设置了标志,则在警告/错误时停止)|
### 批处理命令
在单个请求中发送多个命令 比单个呼叫快得多:```json
POST http://localhost:8765/api/batch
{
"commands": [
{"action": "navigate", "url": "https://example.com"},
{"action": "sleep", "ms": 2000},
{"action": "fill", "selector": "#email", "value": "test@example.com"},
{"action": "fill", "selector": "#password", "value": "secret"},
{"action": "click", "selector": "#submit"},
{"action": "pageInfo"}
]
}
可用的批处理操作: navigate, newTab, closeTab, switchTab, click, type, fill, scroll, hover, find, js, pageInfo, pageText, pageTextByTabId, screenshot, tabs, forms, dom, highlight, waitForElement, waitForResult, sleep, parallel
stopOnWarning:设置为 true 如果任何命令返回 warning (例如。 expectTitle 重定向不匹配)或 error。停止结果将包括 _stopped: true.
expectTitle 导航:通行证 "expectTitle": "keyword" 检查加载的页面标题。如果标题不包含关键字(不区分大小写),则结果包括 warning 和 redirected: true --可用于捕获静默URL重定向。
parallel:同时运行多个命令序列。每个序列按顺序运行其命令,但所有序列同时执行。针对活动选项卡的命令(如 navigate) 必须 包括明确的 tabId 以避免比赛条件。```json
{
"action": "parallel",
"sequences": [
[
{"action": "pageText", "tabId": 1},
{"action": "screenshot"}
],
[
{"action": "forms", "tabId": 2}
]
]
}
### 元素定位
针对元素的多种方法:
- **CSS选择器**: `#id`, `.class`, `input[name=email]`
- **元件位号**: `r0`, `r5` 返回由 `/api/find` 和 `/api/dom`
- **坐标**: `{"coords": {"x": 100, "y": 200}}`
## 用法示例
### python```python
import requests
# Navigate and fill a form
requests.post("http://localhost:8765/api/navigate", json={"url": "https://example.com"})
requests.post("http://localhost:8765/api/fill", json={"selector": "#search", "value": "hello"})
requests.post("http://localhost:8765/api/click", json={"selector": "#submit"})
# Read page content
text = requests.get("http://localhost:8765/api/page-text").json()
PowerShell(克劳德桌面/MCP)```powershell
Invoke-RestMethod http://localhost:8765/api/navigate -Method Post -Body '{"url":"https://example.com"}' -ContentType "application/json"
Invoke-RestMethod http://localhost:8765/api/page-text
### 卷曲```bash
curl -X POST http://localhost:8765/api/navigate -H "Content-Type: application/json" -d '{"url":"https://example.com"}'
curl http://localhost:8765/api/page-text
JavaScript/Node.js```javascript
await fetch("http://localhost:8765/api/navigate", {
method: "POST",
headers: {"Content-Type": "application/json"},
body: JSON.stringify({url: "https://example.com"})
});
const {title} = await (await fetch("http://localhost:8765/api/page-info")).json();
```
特性
- 全页面控制 导航、单击、键入、滚动、悬停、填写表单
- 智能元素查找 自然语言查询、CSS选择器、坐标或引用ID
- 选项卡管理 打开、关闭、切换、列出选项卡
- 截图 将视口捕获为PNG
- JavaScript执行 在页面上下文中运行任意JS(带有截断标志的50KB结果上限)
- 批处理命令 一个请求中包含多个命令
stopOnWarning早期流产 - 等待图元
waitForElement和waitForResult轮询,直到DOM/数据准备就绪 - 重定向检测
expectTitle在导航时捕获静默URL重定向 - 影子DOM支持 自动穿透现代web组件的开放阴影根
- 自动重新连接 网桥重启后,扩展以指数回退方式重新连接
- 内容脚本版本控制 更新的脚本自动注入,无需页面刷新
已知限制
- 扩展作为临时插件加载(浏览器重启后需要重新加载)
about:浏览器内部页面无法控制/api/type不支持content可编辑元素(使用/api/js相反)- 闭式阴影DOM表单需要
/api/js用于值设置 - 本地主机端点上没有身份验证(仅供本地使用)
安全说明
ZenLink公开了对localhost的完全浏览器控制,无需身份验证。这是为个人、本地使用而设计的。如果需要通过网络公开它,请先添加基于令牌的身份验证。
起源
出于对Chrome MCP被破坏的沮丧而构建。最初创建的目的是通过Zen browser为Claude Desktop浏览器提供自动化功能,但可以与任何可以发出HTTP请求的工具一起使用。
许可证
MIT 你想用它做什么就做什么。
