docs: update user-facing docs with real test results from baidu.com verification
This commit is contained in:
+131
-77
@@ -1,138 +1,192 @@
|
||||
# 在 LLM 智能体中集成 VisionL
|
||||
|
||||
> 本文档介绍如何让 LLM 通过工具调用使用 VisionL-CLI 操控浏览器。
|
||||
> 让 LLM 通过 HTTP API 工具调用操控 VisionL 浏览器。
|
||||
|
||||
## 原理
|
||||
|
||||
LLM 将 `visionl` 注册为一个系统命令/工具，在需要浏览网页时调用。
|
||||
所有命令输出结构化的 JSON，LLM 直接解析结果并决定下一步操作。
|
||||
VisionL daemon 提供完整的 REST API。LLM 将 API 调用注册为工具/函数（Function Calling），
|
||||
在需要浏览网页时生成对应的 HTTP 请求。所有接口返回结构化 JSON，LLM 直接解析。
|
||||
|
||||
## API 总览
|
||||
|
||||
| 方法 | 端点 | 功能 |
|
||||
|------|------|------|
|
||||
| POST | `/pages` | 打开页面 |
|
||||
| GET | `/pages` | 列出所有页面 |
|
||||
| GET | `/pages/:id` | 页面详情 |
|
||||
| DELETE | `/pages/:id` | 关闭页面 |
|
||||
| POST | `/pages/:id/navigate` | 跳转 |
|
||||
| POST | `/pages/:id/click` | 点击元素 |
|
||||
| POST | `/pages/:id/type` | 输入文本 |
|
||||
| POST | `/pages/:id/scroll` | 滚动 |
|
||||
| POST | `/pages/:id/eval` | 执行 JS |
|
||||
| POST | `/pages/:id/wait` | 等待 |
|
||||
| GET | `/pages/:id/screenshot` | 截图（base64） |
|
||||
| GET | `/pages/:id/text` | 纯文本 |
|
||||
| GET | `/pages/:id/html` | HTML 源码 |
|
||||
| GET | `/pages/:id/cookies` | Cookie 列表 |
|
||||
| POST | `/pages/:id/cookies` | 设置 Cookie |
|
||||
| DELETE | `/pages/:id/cookies/:name` | 删除 Cookie |
|
||||
| GET | `/pages/:id/console` | 控制台日志 |
|
||||
| GET | `/pages/:id/network` | 网络请求日志 |
|
||||
| GET | `/profiles` | 指纹配置列表 |
|
||||
|
||||
完整文档见 [API 文档](../development/api.md)。
|
||||
|
||||
## 集成方式
|
||||
|
||||
### 方式一：Function Calling（推荐）
|
||||
|
||||
在 LLM 的 function/tool 定义中注册 VisionL 命令。大多数 LLM 平台（OpenAI、Claude、本地模型）都支持。
|
||||
|
||||
**工具定义示例（OpenAI 格式）：**
|
||||
注册 `visionl_api` 工具，LLM 直接生成 HTTP 请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "visionl",
|
||||
"description": "通过 VisionL 浏览器操控网页。子命令: page open|list|info|kill|kill-all, click, type, scroll, navigate, eval, wait, screenshot, text, html, daemon start|stop|status, raw",
|
||||
"name": "visionl_api",
|
||||
"description": "通过 VisionL 浏览器操控网页。支持打开页面、点击、输入、截图、提取文本、执行JS、管理Cookie、查看网络请求等。",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"command": {
|
||||
"method": {
|
||||
"type": "string",
|
||||
"description": "完整 visionl 命令，例如 'page open https://example.com'"
|
||||
"enum": ["GET", "POST", "DELETE"],
|
||||
"description": "HTTP 方法"
|
||||
},
|
||||
"path": {
|
||||
"type": "string",
|
||||
"description": "API 路径，如 /pages、/pages/baidu/text"
|
||||
},
|
||||
"body": {
|
||||
"type": "object",
|
||||
"description": "请求体（仅 POST 需要）"
|
||||
}
|
||||
},
|
||||
"required": ["command"]
|
||||
"required": ["method", "path"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**使用流程：**
|
||||
### 使用流程
|
||||
|
||||
1. LLM 决策需要访问网页
|
||||
2. LLM 生成 `visionl page open <url>` 调用
|
||||
3. 宿主程序在终端执行该命令，将 JSON 输出返回给 LLM
|
||||
4. LLM 解析结果，继续决策（截图、点击、提取文本等）
|
||||
2. LLM 调用 `visionl_api`：`POST /pages` 打开 baidu.com
|
||||
3. 宿主程序执行 HTTP 请求，将 JSON 结果返回 LLM
|
||||
4. LLM 解析结果，获得页面 ID `p_xxx`
|
||||
5. LLM 继续：`GET /pages/p_xxx/text` 读取内容
|
||||
6. 或：`POST /pages/p_xxx/click` 点击搜索
|
||||
|
||||
### 方式二：MCP Server
|
||||
### 方式二：多工具注册
|
||||
|
||||
可以封装一个 MCP（Model Context Protocol）Server，将 VisionL-CLI 包装为 MCP 工具：
|
||||
将每个操作注册为独立工具（更细粒度）：
|
||||
|
||||
```typescript
|
||||
// 伪代码示意
|
||||
server.tool(
|
||||
"visionl",
|
||||
"通过 VisionL 浏览器操控网页",
|
||||
{ command: z.string() },
|
||||
async ({ command }) => {
|
||||
const { stdout } = await exec(`visionl ${command}`);
|
||||
return JSON.parse(stdout);
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "visionl_open",
|
||||
"description": "打开网页",
|
||||
"parameters": {
|
||||
"url": { "type": "string" },
|
||||
"alias": { "type": "string" }
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "visionl_text",
|
||||
"description": "获取页面文本内容",
|
||||
"parameters": {
|
||||
"page_id": { "type": "string" }
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "visionl_click",
|
||||
"description": "点击页面元素",
|
||||
"parameters": {
|
||||
"page_id": { "type": "string" },
|
||||
"selector": { "type": "string" }
|
||||
}
|
||||
}
|
||||
);
|
||||
]
|
||||
```
|
||||
|
||||
### 方式三：Agent 框架集成
|
||||
|
||||
与 LangChain、AutoGPT、CrewAI 等框架集成，注册为自定义工具。
|
||||
|
||||
**LangChain 示例：**
|
||||
### 方式三：LangChain 集成
|
||||
|
||||
```python
|
||||
from langchain.tools import Tool
|
||||
import subprocess, json
|
||||
from langchain.tools import BaseTool
|
||||
import requests
|
||||
|
||||
def visionl_tool(command: str) -> str:
|
||||
result = subprocess.run(
|
||||
["visionl", *command.split()],
|
||||
capture_output=True, text=True
|
||||
)
|
||||
return result.stdout
|
||||
class VisionLTool(BaseTool):
|
||||
name = "visionl"
|
||||
description = "浏览器操控工具。API 基础 URL: http://127.0.0.1:9527"
|
||||
|
||||
visionl = Tool(
|
||||
name="visionl",
|
||||
description="浏览器操控工具。命令示例：page open <url>, click <id> <sel>, text <id>",
|
||||
func=visionl_tool,
|
||||
)
|
||||
def _run(self, method: str, path: str, body: dict = None) -> str:
|
||||
url = f"http://127.0.0.1:9527{path}"
|
||||
resp = requests.request(method, url, json=body)
|
||||
return resp.text
|
||||
```
|
||||
|
||||
## LLM Prompt 建议
|
||||
|
||||
在系统 prompt 中添加以下指引：
|
||||
## LLM 系统提示词建议
|
||||
|
||||
```
|
||||
你可以使用 visionl 命令操控浏览器：
|
||||
你可以使用 visionl_api 工具操控浏览器：
|
||||
|
||||
1. visionl page open <url> [--alias <name>] — 打开页面
|
||||
2. visionl page list — 列出所有页面
|
||||
3. visionl text <id|alias> — 获取页面文本
|
||||
4. visionl screenshot <id|alias> — 截图（返回 base64）
|
||||
5. visionl click <id|alias> <selector> — 点击元素
|
||||
6. visionl type <id|alias> <selector> <text> — 输入文本
|
||||
7. visionl page kill <id|alias> — 关闭页面
|
||||
打开页面: POST /pages {"url":"...","alias":"..."}
|
||||
页面文本: GET /pages/{id}/text
|
||||
页面截图: GET /pages/{id}/screenshot (返回 base64)
|
||||
点击元素: POST /pages/{id}/click {"selector":"#id"}
|
||||
输入文本: POST /pages/{id}/type {"selector":"#id","text":"..."}
|
||||
执行 JS: POST /pages/{id}/eval {"code":"..."}
|
||||
滚动页面: POST /pages/{id}/scroll {"deltaY":300}
|
||||
等待加载: POST /pages/{id}/wait {"ms":2000}
|
||||
查看Cookie: GET /pages/{id}/cookies
|
||||
网络日志: GET /pages/{id}/network
|
||||
关闭页面: DELETE /pages/{id}
|
||||
|
||||
所有命令返回 JSON。解析 ok 字段判断成功/失败。
|
||||
使用 --alias 给页面起别名方便后续引用。
|
||||
所有接口返回 {"ok":true,"data":{...}} 或 {"ok":false,"error":{...}}。
|
||||
打开页面后记录返回的 page_id，后续操作使用该 id。
|
||||
页面在被显式 kill 之前永远存活，可跨多轮对话复用。
|
||||
```
|
||||
|
||||
## 多页面管理
|
||||
## 多页面并行管理
|
||||
|
||||
LLM 可以同时打开多个页面，通过别名区分：
|
||||
LLM 同时打开多个页面，通过别名区分：
|
||||
|
||||
```
|
||||
LLM: visionl page open https://docs.python.org --alias py
|
||||
LLM: visionl page open https://developer.mozilla.org --alias mdn
|
||||
LLM: visionl text py # 读 Python 文档
|
||||
LLM: visionl text mdn # 读 MDN 文档
|
||||
LLM: POST /pages {"url":"https://docs.python.org","alias":"py"}
|
||||
→ {"ok":true,"data":{"id":"p_aaa",...}}
|
||||
|
||||
LLM: POST /pages {"url":"https://developer.mozilla.org","alias":"mdn"}
|
||||
→ {"ok":true,"data":{"id":"p_bbb",...}}
|
||||
|
||||
LLM: GET /pages/py/text # 读 Python 文档
|
||||
LLM: GET /pages/mdn/text # 读 MDN 文档
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
LLM 应检查返回的 `ok` 字段：
|
||||
|
||||
```json
|
||||
// 失败示例
|
||||
{"ok":false,"error":{"code":"PAGE_NOT_FOUND","message":"页面 py 不存在"}}
|
||||
```
|
||||
|
||||
常见错误及处理：
|
||||
常见错误码及处理：
|
||||
|
||||
| 错误码 | 处理建议 |
|
||||
|--------|---------|
|
||||
| `PAGE_NOT_FOUND` | 页面可能已被关闭，重新打开 |
|
||||
| `DAEMON_UNREACHABLE` | 等待几秒重试（自动拉起正在启动） |
|
||||
| `TIMEOUT` | 页面加载慢，重试或增加等待时间 |
|
||||
| `ALIAS_EXISTS` | 换一个别名或直接用 page ID |
|
||||
| 错误码 | HTTP | 处理建议 |
|
||||
|--------|------|---------|
|
||||
| `PAGE_NOT_FOUND` | 404 | 页面已关闭，重新打开 |
|
||||
| `DAEMON_UNREACHABLE` | 502 | 启动 daemon 或稍后重试 |
|
||||
| `TIMEOUT` | 408 | 页面加载慢，重试或增加等待 |
|
||||
| `ALIAS_EXISTS` | 409 | 换别名或直接用 page_id |
|
||||
|
||||
## 安全注意事项
|
||||
## 反检测能力
|
||||
|
||||
- VisionL daemon 仅监听 127.0.0.1，外部不可访问
|
||||
- 执行的 JS 代码在页面沙箱内运行，无法逃逸到宿主机
|
||||
- LLM 应避免在不可信页面执行敏感操作（自动填写密码等）
|
||||
VisionL 内置多层反检测，使自动化访问尽可能不被简单人机验证拦截：
|
||||
|
||||
- `navigator.webdriver` → `false`
|
||||
- 真实 Chrome User-Agent 和请求头
|
||||
- Canvas/WebGL/Audio 指纹加噪
|
||||
- 屏幕分辨率和视口合理性
|
||||
- 权限状态模拟
|
||||
- 3 套指纹模版可切换
|
||||
|
||||
详见 [反检测设计文档](../development/anti-detection.md)。
|
||||
|
||||
Reference in New Issue
Block a user