browser-cli

浏览器 DOM 自动化命令行工具，通过 Chrome 扩展实现浏览器控制。

架构

┌─────────────┐      HTTP       ┌─────────────────┐    WebSocket    ┌──────────────────┐
│ browser-cli │ ──────────────> │  Daemon Server  │ <────────────── │ Chrome Extension │
│   (CLI)     │   Port 19223    │  (Node.js)      │   Port 19222    │   (Browser)      │
└─────────────┘                 └─────────────────┘                 └──────────────────┘

• CLI: 命令行工具，发送命令到守护进程
• Daemon Server: 后台服务，桥接 CLI 和浏览器扩展
• Chrome Extension: 在浏览器中执行实际的 DOM 操作

安装

1. 安装 CLI 工具

# 全局安装（推荐）
npm install -g browser-use-cli

# 或作为项目依赖安装
npm install browser-use-cli

安装后可使用以下命令（两者等价）：

browser-cli --help
browser-use --help

2. 安装 Chrome 扩展

# 安装扩展文件到 ~/.browser-use-cli/chrome-extension
browser-cli extension install

1. 打开 Chrome 浏览器，访问 chrome://extensions/
2. 开启右上角的「开发者模式」
3. 点击「加载已解压的扩展程序」
4. 选择扩展目录：~/.browser-use-cli/chrome-extension/
5. 确保扩展已启用

快速开始

# 1. 启动守护进程
browser-cli server start

# 2. 检查状态（确认扩展已连接）
browser-cli server status

# 3. 导航到网页
browser-cli navigate https://example.com

# 4. 获取页面 DOM 快照
browser-cli snapshot

# 5. 与元素交互
browser-cli click @e1

如果你没有全局安装，也可以用 npx：

npx -p browser-use-cli browser-cli server status

命令参考

全局选项

| 选项 | 说明 | 默认值 | |------|------|--------| | -t, --timeout <ms> | 命令超时时间（毫秒） | 30000 | | -V, --version | 显示版本号 | - | | -h, --help | 显示帮助信息 | - |

服务器管理

| 命令 | 说明 | |------|------| | server start | 启动守护进程（后台运行） | | server start -f | 前台启动（用于调试） | | server stop | 停止守护进程 | | server status | 检查守护进程状态和扩展连接 | | server restart | 重启守护进程 |

扩展管理

| 命令 | 说明 | |------|------| | extension install | 安装扩展文件（已存在则跳过） | | extension install --force | 强制覆盖重装扩展文件 | | extension path | 查看扩展安装目录与打包源目录 |

页面导航

| 命令 | 说明 | |------|------| | navigate <url> | 导航到指定 URL | | back | 后退 | | forward | 前进 | | reload | 刷新页面 | | wait --ms <毫秒> | 等待指定时间 | | wait --text <文本> | 等待文本出现 | | wait --selector <选择器> | 等待元素出现 |

wait 命令至少需要一个条件：--ms、--text 或 --selector。

标签页管理

| 命令 | 说明 | |------|------| | tabs | 列出所有标签页 | | tab <index> | 切换到指定标签页（从 0 开始） | | new-tab [url] | 打开新标签页 | | close-tab [index] | 关闭标签页（不指定则关闭当前） |

DOM 快照

| 命令 | 说明 | |------|------| | snapshot | 捕获页面 DOM 快照 | | snapshot --no-interactive | 包含非交互节点 | | snapshot --no-compact | 保留结构节点（不压缩） | | snapshot --depth <n> | 限制快照树深度（默认 6） | | snapshot --selector <css> | 仅快照指定区域 | | snapshot --max-refs <n> | 限制 ref 数量（默认 80） | | snapshot --max-chars <n> | 限制快照字符数（默认 12000） | | snapshot --cursor | 额外包含 cursor-interactive 元素 | | snapshot --full-page | 关闭视口过滤，包含离屏节点 |

元素交互

| 命令 | 说明 | |------|------| | click <ref> | 点击元素 | | dblclick <ref> | 双击元素 | | hover <ref> | 悬停在元素上 | | focus <ref> | 聚焦元素 | | fill <ref> <text> | 清空并填充输入框 | | type <ref> <text> | 向元素输入文本（追加） | | input-text <ref> <text> | 富文本输入（键盘模拟） | | shadow-input <text> | Shadow DOM 输入（Gemini/Notion） | | select <ref> <value> | 从下拉框选择选项 | | check <ref> | 勾选复选框 | | uncheck <ref> | 取消勾选复选框 | | drag <source> <target> | 拖拽元素 | | upload <ref> | 触发文件上传 |

shadow-input 常用参数：

• --selector <css> 指定输入框选择器
• --clear 输入前清空
• --submit 输入后提交
• --submit-mode <auto|enter|ctrl-enter> 提交策略（默认 auto）
• --retry <n> 定位失败时重试次数（默认 2）

键盘操作

| 命令 | 说明 | |------|------| | press <key> | 按键（支持组合键） | | keydown <key> | 按下键 | | keyup <key> | 释放键 |

支持的按键示例：

• 单键：Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown
• 组合键：Control+a, Control+c, Control+v, Shift+Tab, Alt+F4

滚动

| 命令 | 说明 | |------|------| | scroll <direction> | 滚动页面（up/down/left/right） | | scroll <direction> --amount <px> | 指定滚动像素数（默认 500） | | scroll-into-view <ref> | 将元素滚动到可视区域 |

信息获取

| 命令 | 说明 | |------|------| | get-title | 获取页面标题 | | get-url | 获取当前 URL | | get-text <ref> | 获取元素文本内容 | | get-value <ref> | 获取输入框的值 | | get-html <ref> | 获取元素内部 HTML | | get-html <ref> --outer | 获取元素外部 HTML | | get-attr <ref> <attr> | 获取元素属性值 | | get-count <selector> | 统计匹配选择器的元素数量 | | get-box <ref> | 获取元素边界框坐标 | | is-visible <ref> | 检查元素是否可见 |

元素引用

<ref> 参数支持两种格式：

1. 快照引用：使用 snapshot 命令输出的元素 ID，如 @e1, e2, e3
2. CSS 选择器：直接使用 CSS 选择器，如 #submit-btn, .nav-link, input[name="email"]

# 使用快照引用
browser-cli snapshot          # 获取快照，查看元素 ID
browser-cli click @e5         # 点击 ID 为 e5 的元素（也支持 e5）

# 使用 CSS 选择器
browser-cli click "#login-btn"
browser-cli fill "input[type='email']" "[email protected]"

输出格式

所有命令输出 JSON 格式，便于脚本解析：

成功：

{"success": true, "data": {"title": "Example Domain"}}

失败：

{"success": false, "error": "Element not found"}

新版 snapshot 会在 data.stats 中返回体积统计： chars、rawChars、tokens、interactive、truncated、truncatedByChars、omitted。

对于机票/商品列表页，建议优先限定区域快照：
browser-cli snapshot --selector ".m-airfly-lst" --full-page --max-chars 8000

使用示例

自动登录

# 启动服务
browser-cli server start

# 打开登录页
browser-cli navigate https://example.com/login

# 等待页面加载
browser-cli wait --selector "#username"

# 填写表单
browser-cli fill "#username" "myuser"
browser-cli fill "#password" "mypassword"

# 点击登录
browser-cli click "#login-btn"

# 等待跳转
browser-cli wait --text "Welcome"

数据抓取

# 获取页面快照
browser-cli snapshot > page.json

# 获取特定元素文本
browser-cli get-text ".product-title"

# 获取所有链接数量
browser-cli get-count "a[href]"

# 获取元素属性
browser-cli get-attr ".product-image" "src"

表单自动化

# 填写文本输入
browser-cli fill "#name" "张三"
browser-cli fill "#email" "[email protected]"

# 选择下拉框
browser-cli select "#country" "CN"

# 勾选复选框
browser-cli check "#agree-terms"

# 提交表单
browser-cli press Enter
# 或
browser-cli click "#submit"

页面滚动

# 向下滚动 500 像素（默认）
browser-cli scroll down

# 向下滚动 2000 像素
browser-cli scroll down --amount 2000

# 将特定元素滚动到视图中
browser-cli scroll-into-view "#footer"

多标签页操作

# 列出所有标签页
browser-cli tabs

# 打开新标签页
browser-cli new-tab https://google.com

# 切换到第一个标签页
browser-cli tab 0

# 关闭当前标签页
browser-cli close-tab

故障排除

守护进程无法启动

# 检查端口是否被占用
lsof -i :19222
lsof -i :19223

# 强制停止并重启
browser-cli server stop
browser-cli server start

扩展未连接

1. 确认 Chrome 扩展已安装并启用
2. 检查扩展是否显示「已连接」状态
3. 尝试重新加载扩展
4. 查看扩展的 Service Worker 控制台日志

# 检查详细状态
browser-cli server status

命令超时

# 增加超时时间
browser-cli -t 60000 snapshot

# 或等待页面加载完成后再执行
browser-cli wait --ms 3000
browser-cli snapshot

元素找不到

1. 先执行 snapshot 确认元素存在
2. 检查元素是否在 iframe 中（当前不支持跨 iframe）
3. 确认元素是否可见（使用 is-visible 检查）
4. 尝试使用 wait --selector 等待元素出现

开发

# 监听模式编译
npm run dev

# 前台运行守护进程（查看日志）
browser-cli server start -f

# 清理编译产物
npm run clean

发布

# 发布前演练（不会真正发布）
npm run release -- --dry-run --skip-mirror-check

# 正式发布到 npm 官方源（脚本会自动检查登录态/版本冲突）
npm run release

可选参数：

• --tag beta 发布到自定义 tag
• --skip-mirror-check 跳过 npmmirror 同步检查
• NPM_OTP=123456 npm run release 传入一次性验证码（如果账号策略要求）

端口说明

| 端口 | 用途 | |------|------| | 19222 | WebSocket 服务器（Chrome 扩展连接） | | 19223 | HTTP 服务器（CLI 命令连接） |

许可证

MIT