vibe-check

Vibium 浏览器自动化 — CLI 参考

vibium CLI 可从命令行自动化 Chrome（也可通过 --engine firefox 自动化 Firefox）。浏览器会在首次使用时自动启动（守护进程模式会让它在命令之间保持运行）。

vibium go <url> && vibium map && vibium click @e1 && vibium map

核心工作流

每次浏览器自动化都遵循以下模式：

1. 导航：vibium go <url>
2. 映射：vibium map（获取 @e1、@e2 等元素引用）
3. 交互：使用引用进行点击、填写、选择等操作，例如 vibium click @e1
4. 重新映射：导航或 DOM 发生变化后，使用 vibium map 获取最新引用

二进制文件解析

运行任何命令前，先解析一次 vibium 二进制文件路径：

1. 先尝试直接运行 vibium（通过 npm install -g vibium 全局安装时可用）
2. 回退到 ./clicker/bin/vibium（项目根目录中的开发环境）
3. 回退到 ./node_modules/.bin/vibium（本地 npm 安装）

运行 vibium --help（或已解析的路径）进行确认。后续所有命令都使用已解析的路径。

**Windows 提示：**路径中使用正斜杠（例如 ./clicker/bin/vibium.exe），并为包含空格的路径加引号。

命令串联

使用 && 串联命令，使其依次运行。遇到第一个错误时，命令串联会停止：

vibium go https://example.com && vibium map && vibium click @e3 && vibium diff map

**何时串联：**对于需要连续执行的步骤（导航 → 交互 → 验证），使用 &&。如果需要在步骤之间检查输出，则分别运行命令。

**何时不串联：**不要串联依赖解析上一步输出的命令（例如，读取映射输出后再决定要点击什么）。请分别运行这些命令，以便先分析结果。

命令

探索

• vibium map — 映射交互元素并生成 @ 引用（建议在交互前使用）
• vibium map --selector "nav" — 将映射范围限定为 CSS 子树中的元素
• vibium diff map — 比较当前映射与上一次映射（查看发生了哪些变化）

导航

• vibium go <url> — 前往页面
• vibium back — 返回上一页
• vibium forward — 前往下一页
• vibium reload — 重新加载当前页面
• vibium url — 打印当前 URL
• vibium title — 打印页面标题

读取内容

• vibium text — 获取页面上的所有文本
• vibium text "<selector>" — 获取指定元素的文本
• vibium html — 获取页面 HTML（使用 --outer 获取 outerHTML）
• vibium find "<selector>" — 查找元素并返回 @e1 引用（可通过 vibium click @e1 点击）
• vibium find "<selector>" --all — 查找所有匹配元素 → @e1、@e2、...（使用 --limit N 限制数量）
• vibium find text "Sign In" — 按文本内容查找元素 → @e1
• vibium find label "Email" — 按标签查找输入框 → @e1
• vibium find placeholder "Search" — 按占位符查找 → @e1
• vibium find testid "submit-btn" — 按 data-testid 查找 → @e1
• vibium find xpath "//div[@class]" — 按 XPath 查找 → @e1
• vibium find alt "Logo" — 按 alt 属性查找 → @e1
• vibium find title "Settings" — 按 title 属性查找 → @e1
• vibium find role <role> — 按 ARIA 角色查找元素 → @e1（使用 --name 按可访问名称筛选）
• vibium eval "<js>" — 运行 JavaScript 并打印结果（使用 --stdin 从标准输入读取）
• vibium count "<selector>" — 统计匹配元素的数量
• vibium screenshot -o file.png — 截取屏幕截图（使用 --full-page、--annotate）
• vibium a11y-tree — 获取无障碍树（使用 --everything 获取所有节点）

交互

• vibium click "<selector>" — 点击元素（也接受来自 map 的 @ref）
• vibium dblclick "<selector>" — 双击元素
• vibium type "<selector>" "<text>" — 在输入框中输入内容（追加到现有值）
• vibium fill "<selector>" "<text>" — 清空字段并输入新内容（替换现有值）
• vibium press <key> [selector] — 在元素或当前聚焦的元素上按键
• vibium focus "<selector>" — 聚焦元素
• vibium hover "<selector>" — 将鼠标悬停在元素上
• vibium scroll [direction] — 滚动页面（--amount N、--selector）
• vibium scroll into-view "<selector>" — 滚动页面使元素进入视野（居中）
• vibium keys "<combo>" — 按下按键（Enter、Control+a、Shift+Tab）
• vibium select "<selector>" "<value>" — 选择下拉选项
• vibium check "<selector>" — 勾选复选框或单选按钮（幂等）
• vibium uncheck "<selector>" — 取消勾选复选框（幂等）

鼠标操作

• vibium mouse click [x] [y] — 在指定坐标或当前位置点击（--button 0|1|2）
• vibium mouse move <x> <y> — 将鼠标移动到指定坐标
• vibium mouse down — 按下鼠标按钮（--button 0|1|2）
• vibium mouse up — 释放鼠标按钮（--button 0|1|2）
• vibium drag "<source>" "<target>" — 将一个元素拖动到另一个元素

元素状态

• vibium value "<selector>" — 获取 input/textarea/select 的值
• vibium attr "<selector>" "<attribute>" — 获取 HTML 属性值
• vibium is visible "<selector>" — 检查元素是否可见（true/false）
• vibium is enabled "<selector>" — 检查元素是否已启用（true/false）
• vibium is checked "<selector>" — 检查复选框或单选按钮是否已勾选（true/false）
• vibium is actionable "<selector>" — 检查元素是否可操作（true/false）

等待

• vibium wait "<selector>" — 等待元素（--state visible|hidden|attached、--timeout ms）
• vibium wait url "<pattern>" — 等待 URL 包含指定子字符串（--timeout ms）
• vibium wait load — 等待页面完全加载（--timeout ms）
• vibium wait text "<text>" — 等待页面上出现指定文本（--timeout ms）
• vibium wait fn "<expression>" — 等待 JS 表达式返回真值（--timeout ms）
• vibium sleep <ms> — 暂停执行（最长 30000ms）

捕获

• vibium screenshot -o file.png — 截取屏幕截图（--full-page、--annotate）
• vibium pdf -o file.pdf — 将页面保存为 PDF

对话框

• vibium dialog accept [text] — 接受对话框（可选填写提示文本）
• vibium dialog dismiss — 关闭对话框

模拟

• vibium viewport — 获取当前视口尺寸
• vibium viewport <width> <height> — 设置视口尺寸（使用 --dpr 设置设备像素比）
• vibium window — 获取操作系统浏览器窗口的尺寸和状态
• vibium window <width> <height> [x] [y] — 设置窗口尺寸和位置（--state）
• vibium media — 覆盖 CSS 媒体特征（--color-scheme、--reduced-motion、--forced-colors、--contrast、--media）
• vibium geolocation <lat> <lng> — 覆盖地理位置（--accuracy）
• vibium content "<html>" — 替换页面 HTML（使用 --stdin 从标准输入读取）

框架

• vibium frames — 列出页面上的所有 iframe
• vibium frame "<nameOrUrl>" — 按名称或 URL 子字符串查找框架

文件上传

• vibium upload "<selector>" <files...> — 为 input[type=file] 设置文件

录制

• vibium record start — 开始录制（--screenshots、--snapshots、--name、-o path — 默认文件名带时间戳，为 record-<date>.zip，因此重复运行不会覆盖已有文件）
• vibium record stop — 停止录制并保存 ZIP（-o path 可覆盖开始时指定的路径；输出会显示保存的文件名）

录制内容可以包含会话视频轨道（Firefox 154+、本地浏览器）。默认情况下，如果引擎支持视频录制，就会录制视频；否则会跳过，停止录制时会说明结果。传入 --video 可强制录制（在 Chrome 上会失败并显示说明性错误），传入 --video=false 可禁用录制，传入 --video-size 1280x720 / --video-fps 30 可覆盖视口默认值。视频会与跟踪文件一起放在录制 ZIP 中（video/<context>.webm）；它会录制开始时处于活动状态的页面，不会跟随标签页切换。远程浏览器连接会录制除视频之外的所有轨道；传入 --video-remote keep 仍会录制视频，并将文件保留在远程主机上（停止录制时的输出会显示该文件在远程主机上的路径）。

vibium record start --video -o run.zip
# ... actions ...
vibium record stop
# Saved run.zip (23 steps, 14s video)

Cookie

• vibium cookies — 列出所有 Cookie
• vibium cookies <name> <value> — 设置 Cookie
• vibium cookies clear — 清除所有 Cookie

存储状态

• vibium storage — 导出 Cookie、localStorage 和 sessionStorage（-o state.json）
• vibium storage restore <path> — 从 JSON 文件恢复状态

下载

• vibium download dir <path> — 设置下载目录

页面

• vibium pages — 列出已打开的页面
• vibium page new [url] — 打开新页面
• vibium page new --isolated [url] — 打开拥有独立 Cookie 和存储的页面
• vibium page switch <index|url> — 切换页面
• vibium page close [index|page id] — 关闭页面

调试

• vibium highlight "<selector>" — 以可视方式突出显示元素（3 秒）

会话

• vibium start — 启动本地浏览器会话
• vibium start <url> — 启动并连接到远程浏览器
• vibium stop — 停止浏览器会话
• vibium daemon start — 启动后台浏览器
• vibium daemon status — 检查是否正在运行
• vibium daemon stop — 停止守护进程
• vibium --session <name> <command> — 在隔离的守护进程和浏览器中运行命令

常见模式

基于引用的工作流（推荐用于 AI）

vibium go https://example.com
vibium map
vibium click @e1
vibium map  # re-map after interaction

验证操作是否成功

vibium map
vibium click @e3
vibium diff map  # see what changed

读取页面

vibium go https://example.com && vibium text

填写表单（端到端）

vibium go https://example.com/login
vibium map
# Look at map output to identify form fields
vibium fill @e1 "[email protected]"
vibium fill @e2 "secret"
vibium click @e3
vibium wait url "/dashboard"
vibium screenshot -o after-login.png

限定范围的映射（大型页面）

vibium map --selector "nav"        # Only map elements in <nav>
vibium map --selector "#sidebar"   # Only map elements in #sidebar
vibium map --selector "form"       # Only map form controls

语义查找（无需 CSS 选择器）

vibium find text "Sign In"             # → @e1 [button] "Sign In"
vibium find label "Email"              # → @e1 [input] placeholder="Email"
vibium click @e1                       # Click the found element
vibium find placeholder "Search..."    # → @e1 [input] placeholder="Search..."
vibium find testid "submit-btn"        # → @e1 [button] "Submit"
vibium find alt "Company logo"         # → @e1 [img] alt="Company logo"
vibium find title "Close"              # → @e1 [button] title="Close"
vibium find xpath "//a[@href='/about']"  # → @e1 [a] "About"

使用状态持久化进行身份验证

# Log in once and save state
vibium go https://app.example.com/login
vibium fill "input[name=email]" "[email protected]"
vibium fill "input[name=password]" "secret"
vibium click "button[type=submit]"
vibium wait url "/dashboard"
vibium storage -o auth.json

# Restore in a later session (skips login)
vibium storage restore auth.json
vibium go https://app.example.com/dashboard

提取结构化数据

vibium go https://example.com
vibium eval "JSON.stringify([...document.querySelectorAll('a')].map(a => ({text: a.textContent.trim(), href: a.href})))"

不渲染页面，检查其结构

vibium go https://example.com && vibium a11y-tree

远程浏览器

vibium start ws://remote-host:9515/session
vibium go https://example.com
vibium map
vibium stop

并发会话（隔离的浏览器）

# Two scripts on one host, each with its own daemon and browser
export VIBIUM_SESSION=checkout-tests
vibium go https://example.com/checkout
vibium daemon stop

# Or per command, to drive two browsers from one script
vibium --session buyer go https://shop.example.com
vibium --session seller go https://shop.example.com/admin

隔离页面（同一浏览器，不同的 Cookie 和存储）

# Lighter than a session: two logins in one browser, no second launch
vibium page new --isolated https://shop.example.com   # prints (page: <id>)
vibium page new --isolated https://shop.example.com
vibium page close <id>   # also removes the page's isolated context

多页面工作流

vibium page new https://docs.example.com
vibium text "h1"
vibium page switch 0

带注释的屏幕截图

vibium screenshot -o annotated.png --annotate

检查元素

vibium attr "a" "href"
vibium value "input[name=email]"
vibium is visible ".modal"

保存为 PDF

vibium go https://example.com && vibium pdf -o page.pdf

求值 / JavaScript

vibium eval 可用于执行 CLI 未直接覆盖的任何 DOM 查询或修改操作。

简单表达式 — 使用单引号：

vibium eval 'document.title'
vibium eval 'document.querySelectorAll("li").length'

复杂脚本 — 使用 --stdin 和 heredoc：

vibium eval --stdin <<'EOF'
const rows = [...document.querySelectorAll('table tbody tr')];
JSON.stringify(rows.map(r => {
  const cells = r.querySelectorAll('td');
  return { name: cells[0].textContent.trim(), price: cells[1].textContent.trim() };
}));
EOF

JSON 输出 — 使用 --json 获取机器可读的输出：

vibium eval --json 'JSON.stringify({url: location.href, title: document.title})'

重要提示： eval 会返回表达式结果。如果脚本没有返回值，结果将为 null。请务必确保最后一个表达式求值后得到所需的数据。

超时与等待

所有交互命令（click、fill、type 等）都会自动等待目标元素变为可操作状态。通常无需显式等待。

在以下情况使用显式等待：

• 等待导航： 点击跳转链接后，使用 vibium wait url "/dashboard"
• 等待内容： 提交表单后，使用 vibium wait text "Success" 等待确认信息
• 等待元素： 使用 vibium wait ".modal" 等待模态框出现
• 等待页面加载： 导航到加载较慢的页面后，使用 vibium wait load
• 等待 JS 条件： 使用 vibium wait fn "window.appReady === true" 等待应用初始化
• 固定延迟（最后手段）： 使用 vibium sleep 2000，仅在没有更好的信号时使用（最长 30s）

所有等待命令都接受 --timeout <ms>（默认值因命令而异）。

Ref 生命周期

页面发生变化时，Refs（@e1、@e2）会失效。以下操作后务必重新映射：

• 点击会跳转的链接或按钮
• 提交表单
• 动态内容加载（下拉菜单、模态框）

全局标志

标志	描述
--engine <name>	浏览器引擎：chrome（默认）或 firefox（环境变量：VIBIUM_ENGINE）
--channel <ch>	引擎发布渠道 — Firefox：release（默认）或 beta；Chrome：stable（默认）、beta、dev 或 canary（环境变量：VIBIUM_ENGINE_CHANNEL）
--headless	隐藏浏览器窗口
--json	以 JSON 格式输出
-v, --verbose	调试日志
--session <name>	用于并发使用的隔离守护进程和浏览器（环境变量：VIBIUM_SESSION）

提示

• 所有 click/type/hover/fill 操作都会自动等待元素变为可操作状态
• 所有选择器参数也接受 vibium map 返回的 @ref
• 交互前使用 vibium map 发现可交互元素
• 在大型页面上使用 vibium map --selector 减少干扰信息
• 使用 vibium fill 替换字段的值，使用 vibium type 在其后追加内容
• 使用 vibium find text / find label / find testid 按语义查找元素（比 CSS 选择器更可靠）
• 使用 vibium find role 按 ARIA 角色查找元素
• 使用 vibium a11y-tree 在不进行视觉渲染的情况下了解页面结构
• 使用 vibium text "<selector>" 读取特定部分
• 交互后使用 vibium diff map 查看发生了哪些变化
• 对于复杂的 DOM 查询，可使用 vibium eval 作为备用方案
• vibium check/vibium uncheck 具有幂等性 — 无需先检查状态即可安全调用
• 截图默认保存到当前目录（使用 -o 更改保存位置）
• 使用 vibium storage / vibium storage restore 在不同会话间保留身份验证信息
• 不使用 --session 时，同一主机上的所有命令共享一个守护进程和一个浏览器 — 并发运行时请设置 VIBIUM_SESSION