Vibium

面向AI智能体与人类的浏览器自动化工具。

Vibium为AI智能体提供了一个浏览器环境。只需安装vibium技能，您的智能体便可通过简单的命令行指令实现页面导航、表单填写、按钮点击以及截图等功能。同时，Vibium也支持作为MCP服务器使用，并提供了JS/TS、Python和Java客户端库。

初次使用？ 您可以快速上手：在JavaScript、Python或Java中，5分钟内即可完成从零到“Hello, World”的体验。

为什么选择Vibium？

• 原生支持AI。 以技能形式集成，您的智能体可立即掌握完整的浏览器自动化工具集。
• 零配置。 一次安装，浏览器自动下载，默认可见。
• 基于标准。 基于WebDriver BiDi构建，而非由大型企业控制的专有协议。
• 轻量级。 单个约10MB的二进制文件，无运行时依赖。
• 灵活易用。 可作为CLI技能、MCP服务器，或JS/Python/Java库使用。

---

智能体设置

npm install -g vibium
npx skills add https://github.com/VibiumDev/vibium --skill vibe-check

第一条命令会安装Vibium及其vibium二进制文件，并自动下载Chrome浏览器。第二条命令则将该技能安装到{project}/.agents/skills/vibium目录下。

skills是开放的智能体技能CLI工具，用于管理AI智能体技能的包管理器。无需全局安装，直接通过npx运行即可。

CLI快速参考

# 页面映射与交互（核心流程）
vibium go https://var.parts           # 导航至指定URL
vibium map                            # 映射可交互元素 → @e1, @e2, ...
vibium click @e1                      # 使用引用点击元素
vibium diff map                       # 查看页面变化

# 元素查找（语义化——无需CSS选择器）
vibium find text "Sign In"            # 根据可见文本查找
vibium find label "Email"             # 根据表单标签查找
vibium find placeholder "Search"      # 根据占位符查找
vibium find role button               # 根据ARIA角色查找

# 内容读取与捕获
vibium text                           # 获取页面全部文本
vibium screenshot -o page.png         # 截取屏幕截图
vibium screenshot --annotate -o a.png # 添加元素标注的截图
vibium pdf -o page.pdf                # 将页面保存为PDF
vibium eval "document.title"          # 执行JavaScript代码

# 等待操作
vibium wait ".modal"                  # 等待指定元素出现
vibium wait url "/dashboard"          # 等待URL跳转
vibium wait text "Success"            # 等待页面上出现特定文本

# 会话录制
vibium record start                   # 开始录制并保存截图
vibium record stop                    # 停止录制并保存为record.zip

# 表单与输入
vibium fill @e2 "hello@example.com"   # 使用引用填充输入框
vibium select @e3 "US"               # 选择下拉菜单选项
vibium check @e4                      # 勾选复选框
vibium press Enter                    # 按下回车键

完整命令列表请参见：SKILL.md

替代方案：MCP服务器（适用于结构化工具调用，而非CLI）：

claude mcp add vibium -- npx -y vibium mcp    # Claude Code
gemini mcp add vibium npx -y vibium mcp       # Gemini CLI

更多选项及故障排除，请参阅MCP设置指南。

---

各语言API

npm install vibium   # JavaScript/TypeScript
pip install vibium   # Python

Java（Gradle）：

implementation 'com.vibium:vibium:26.3.18'

Java（Maven）：

<dependency>
    <groupId>com.vibium</groupId>
    <artifactId>vibium</artifactId>
    <version>26.3.18</version>
</dependency>

上述命令会自动安装Vibium二进制文件并下载Chrome浏览器，无需手动配置浏览器环境。

JS/TS客户端

异步API：

import { browser } from 'vibium'

const bro = await browser.start()
const vibe = await bro.page()
await vibe.go('https://example.com')

const png = await vibe.screenshot()
await fs.writeFile('screenshot.png', png)

const link = await vibe.find('a')
await link.click()
await bro.stop()

同步API：

const { browser } = require('vibium/sync')
const fs = require('fs')

const bro = browser.start()
const vibe = bro.page()
vibe.go('https://example.com')

const png = vibe.screenshot()
fs.writeFileSync('screenshot.png', png)

const link = vibe.find('a')
link.click()
bro.stop()

Python客户端

# 异步
from vibium.async_api import browser

# 同步（默认）
from vibium import browser

异步API：

import asyncio
from vibium.async_api import browser

async def main():
    bro = await browser.start()
    vibe = await bro.page()
    await vibe.go("https://example.com")

    png = await vibe.screenshot()
    with open("screenshot.png", "wb") as f:
        f.write(png)

    link = await vibe.find("a")
    await link.click()
    await bro.stop()

asyncio.run(main())

同步API：

from vibium import browser

bro = browser.start()
vibe = bro.page()
vibe.go("https://example.com")

png = vibe.screenshot()
with open("screenshot.png", "wb") as f:
    f.write(png)

link = vibe.find("a")
link.click()
bro.stop()

Java客户端

var bro = Vibium.start();
var vibe = bro.page();
vibe.go("https://example.com");

var png = vibe.screenshot();
Files.write(Path.of("screenshot.png"), png);

var link = vibe.find("a");
link.click();
bro.stop();

---

架构

┌──────────────────────────────────────┐
│             大模型 / 代理              │
│  (Claude Code、Codex、Gemini 等)  │
└──────────────────────────────────────┘
       ▲                  ▲
       │ CLI（Bash）       │ MCP（stdio）
       ▼                  ▼
┌───────────────────────────────────┐
│          Vibium 二进制文件            │
│                                   │
│  ┌──────────────┐ ┌────────────┐  │
│  │ CLI 命令     │ │ MCP 服务器 │  │
│  └─────┬────────┘ └──────┬─────┘  │        ┌──────────────────┐
│        └───────▲─────────┘        │        │                  │
│                │                  │        │                  │
│         ┌──────▼───────┐          │  BiDi  │  Chrome 浏览器  │
│         │  BiDi 代理  │          │◄──────►│                  │
│         └──────────────┘          │        │                  │
└───────────────────────────────────┘        └──────────────────┘
          ▲
          │ WebSocket BiDi :9515
          ▼
┌──────────────────────────────────────┐
│          客户端库            │
│       (js/ts | python | java)        │
│                                      │
│  ┌─────────────────┐ ┌────────────┐  │
│  │   异步 API     │ │  同步 API  │  │
│  │ await vibe.go() │ │  vibe.go() │  │
│  └─────────────────┘ └────────────┘  │
└──────────────────────────────────────┘

---

平台支持

平台	架构	状态
Linux	x64	✅ 支持
macOS	x64（Intel）	✅ 支持
macOS	arm64（Apple Silicon）	✅ 支持
Windows	x64	✅ 支持

---

贡献

请参阅 CONTRIBUTING.md，了解开发环境搭建及贡献指南。

---

路线图

V1 专注于核心流程：通过 CLI、MCP 和客户端库控制浏览器。

更多计划中的功能，请参阅 ROADMAP.md：

• Cortex（记忆/导航层）
• Retina（录制扩展）
• 视频录制
• AI 驱动的定位器

---

许可证

Apache 2.0

Vibium 快速上手指南

Vibium 是一款专为 AI 智能体（Agent）和开发者设计的浏览器自动化工具。它支持通过 CLI、MCP 服务器或多种编程语言（JS/TS, Python, Java）控制浏览器，无需复杂配置即可实现页面导航、表单填写、截图等操作。

环境准备

系统要求：

• 操作系统：Linux (x64), macOS (Intel x64 / Apple Silicon arm64), Windows (x64)
• 网络：首次运行时需下载 Chrome 浏览器（约 10MB+），请确保网络通畅。
• 前置依赖：
  • 使用 CLI 或 JS/TS：需安装 Node.js (推荐 LTS 版本)
  • 使用 Python：需安装 Python 3.8+
  • 使用 Java：需安装 JDK 17+ 及构建工具 (Maven/Gradle)

注意：Vibium 会自动下载并管理 Chrome 浏览器，无需手动安装或配置 WebDriver。

安装步骤

方式一：全局安装 CLI（推荐用于快速测试）

通过 npm 全局安装 Vibium 二进制文件，并添加 Agent 技能包：

# 1. 安装 Vibium 核心二进制文件（自动下载 Chrome）
npm install -g vibium

# 2. 安装 Agent 技能包 (需要 npx 运行 skills 管理器)
npx skills add https://github.com/VibiumDev/vibium --skill vibe-check

方式二：作为项目依赖安装（用于代码开发）

JavaScript / TypeScript:

npm install vibium

Python:

pip install vibium
# 国内加速可选: pip install vibium -i https://pypi.tuna.tsinghua.edu.cn/simple

Java (Maven): 在 pom.xml 中添加：

<dependency>
    <groupId>com.vibium</groupId>
    <artifactId>vibium</artifactId>
    <version>26.3.18</version>
</dependency>

基本使用

1. CLI 命令行模式

最核心的工作流是：导航 -> 映射元素 -> 交互。

# 访问网页
vibium go https://var.parts

# 映射页面上的可交互元素（生成 @e1, @e2 等引用标识）
vibium map

# 基于语义查找元素（无需写 CSS 选择器）
vibium find text "Sign In"
vibium find label "Email"

# 执行操作
vibium click @e1                # 点击引用为 @e1 的元素
vibium fill @e2 "hello@test.com" # 填充表单
vibium screenshot -o page.png   # 截取屏幕

# 等待特定条件
vibium wait text "Success"      # 等待页面出现 "Success" 文本

2. 代码调用示例

JavaScript / TypeScript (异步)

import { browser } from 'vibium'
import fs from 'fs'

async function run() {
  // 启动浏览器
  const bro = await browser.start()
  const vibe = await bro.page()
  
  // 导航
  await vibe.go('https://example.com')
  
  // 截图
  const png = await vibe.screenshot()
  fs.writeFileSync('screenshot.png', png)
  
  // 查找并点击链接
  const link = await vibe.find('a')
  await link.click()
  
  await bro.stop()
}

run()

Python (同步)

from vibium import browser

# 启动浏览器
bro = browser.start()
vibe = bro.page()

# 导航
vibe.go("https://example.com")

# 截图
png = vibe.screenshot()
with open("screenshot.png", "wb") as f:
    f.write(png)

# 查找并点击
link = vibe.find("a")
link.click()

bro.stop()

Java

import com.vibium.Vibium;
import java.nio.file.Files;
import java.nio.file.Path;

public class Main {
    public static void main(String[] args) throws Exception {
        var bro = Vibium.start();
        var vibe = bro.page();
        
        vibe.go("https://example.com");
        
        var png = vibe.screenshot();
        Files.write(Path.of("screenshot.png"), png);
        
        var link = vibe.find("a");
        link.click();
        
        bro.stop();
    }
}

3. 集成 MCP 服务器 (适用于 Claude Code 等 AI 助手)

若需在 AI 对话中直接调用浏览器能力，可配置 MCP Server：

# 为 Claude Code 添加 Vibium 工具
claude mcp add vibium -- npx -y vibium mcp

配置完成后，AI 助手可直接执行“打开网页”、“截图”、“点击按钮”等自然语言指令。