Files

T

AskaEth 0c437a96f1 docs: 项目架构设计文档（中文）及使用指南

- architecture.md: 完整架构设计（技术栈、API、CLI、生命周期、测试策略）
- api.md: REST + WebSocket 接口文档
- cli.md: CLI 命令参考
- contributing.md: 开发规范与 JSON 转义要求
- quickstart.md: 快速开始指南
- llm-integration.md: 智能体集成指南
- examples.md: 8 个典型使用场景

2026-08-12 20:14:54 +08:00

3.9 KiB

Raw Blame History

在 LLM 智能体中集成 VisionL

本文档介绍如何让 LLM 通过工具调用使用 VisionL-CLI 操控浏览器。

原理

LLM 将 visionl 注册为一个系统命令/工具，在需要浏览网页时调用。所有命令输出结构化的 JSON，LLM 直接解析结果并决定下一步操作。

集成方式

方式一：Function Calling（推荐）

在 LLM 的 function/tool 定义中注册 VisionL 命令。大多数 LLM 平台（OpenAI、Claude、本地模型）都支持。

工具定义示例（OpenAI 格式）：

{
  "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"]
    }
  }
}

使用流程：

LLM 决策需要访问网页
LLM 生成 visionl page open <url> 调用
宿主程序在终端执行该命令，将 JSON 输出返回给 LLM
LLM 解析结果，继续决策（截图、点击、提取文本等）

方式二：MCP Server

可以封装一个 MCP（Model Context Protocol）Server，将 VisionL-CLI 包装为 MCP 工具：

// 伪代码示意
server.tool(
  "visionl",
  "通过 VisionL 浏览器操控网页",
  { command: z.string() },
  async ({ command }) => {
    const { stdout } = await exec(`visionl ${command}`);
    return JSON.parse(stdout);
  }
);

方式三：Agent 框架集成

与 LangChain、AutoGPT、CrewAI 等框架集成，注册为自定义工具。

LangChain 示例：

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 字段：

// 失败示例
{"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 应避免在不可信页面执行敏感操作（自动填写密码等）

3.9 KiB Raw Blame History Unescape Escape