AskaEth
0c437a96f1
- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略） - api.md: REST + WebSocket 接口文档 - cli.md: CLI 命令参考 - contributing.md: 开发规范与 JSON 转义要求 - quickstart.md: 快速开始指南 - llm-integration.md: 智能体集成指南 - examples.md: 8 个典型使用场景
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# 在 LLM 智能体中集成 VisionL
|
||
|
||
> 本文档介绍如何让 LLM 通过工具调用使用 VisionL-CLI 操控浏览器。
|
||
|
||
## 原理
|
||
|
||
LLM 将 `visionl` 注册为一个系统命令/工具，在需要浏览网页时调用。
|
||
所有命令输出结构化的 JSON，LLM 直接解析结果并决定下一步操作。
|
||
|
||
## 集成方式
|
||
|
||
### 方式一：Function Calling（推荐）
|
||
|
||
在 LLM 的 function/tool 定义中注册 VisionL 命令。大多数 LLM 平台（OpenAI、Claude、本地模型）都支持。
|
||
|
||
**工具定义示例（OpenAI 格式）：**
|
||
|
||
```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",
|
||
"parameters": {
|
||
"type": "object",
|
||
"properties": {
|
||
"command": {
|
||
"type": "string",
|
||
"description": "完整 visionl 命令，例如 'page open https://example.com'"
|
||
}
|
||
},
|
||
"required": ["command"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**使用流程：**
|
||
|
||
1. LLM 决策需要访问网页
|
||
2. LLM 生成 `visionl page open <url>` 调用
|
||
3. 宿主程序在终端执行该命令，将 JSON 输出返回给 LLM
|
||
4. LLM 解析结果，继续决策（截图、点击、提取文本等）
|
||
|
||
### 方式二：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);
|
||
}
|
||
);
|
||
```
|
||
|
||
### 方式三：Agent 框架集成
|
||
|
||
与 LangChain、AutoGPT、CrewAI 等框架集成，注册为自定义工具。
|
||
|
||
**LangChain 示例：**
|
||
|
||
```python
|
||
from langchain.tools import Tool
|
||
import subprocess, json
|
||
|
||
def visionl_tool(command: str) -> str:
|
||
result = subprocess.run(
|
||
["visionl", *command.split()],
|
||
capture_output=True, text=True
|
||
)
|
||
return result.stdout
|
||
|
||
visionl = Tool(
|
||
name="visionl",
|
||
description="浏览器操控工具。命令示例：page open <url>, click <id> <sel>, text <id>",
|
||
func=visionl_tool,
|
||
)
|
||
```
|
||
|
||
## LLM Prompt 建议
|
||
|
||
在系统 prompt 中添加以下指引：
|
||
|
||
```
|
||
你可以使用 visionl 命令操控浏览器：
|
||
|
||
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> — 关闭页面
|
||
|
||
所有命令返回 JSON。解析 ok 字段判断成功/失败。
|
||
使用 --alias 给页面起别名方便后续引用。
|
||
```
|
||
|
||
## 多页面管理
|
||
|
||
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 应检查返回的 `ok` 字段：
|
||
|
||
```json
|
||
// 失败示例
|
||
{"ok":false,"error":{"code":"PAGE_NOT_FOUND","message":"页面 py 不存在"}}
|
||
```
|
||
|
||
常见错误及处理：
|
||
|
||
| 错误码 | 处理建议 |
|
||
|--------|---------|
|
||
| `PAGE_NOT_FOUND` | 页面可能已被关闭，重新打开 |
|
||
| `DAEMON_UNREACHABLE` | 等待几秒重试（自动拉起正在启动） |
|
||
| `TIMEOUT` | 页面加载慢，重试或增加等待时间 |
|
||
| `ALIAS_EXISTS` | 换一个别名或直接用 page ID |
|
||
|
||
## 安全注意事项
|
||
|
||
- VisionL daemon 仅监听 127.0.0.1，外部不可访问
|
||
- 执行的 JS 代码在页面沙箱内运行，无法逃逸到宿主机
|
||
- LLM 应避免在不可信页面执行敏感操作（自动填写密码等）
|