browseros

使用 BrowserOS 进行浏览器自动化

通过 browseros-cli 控制真正的 Chromium 浏览器。通过 Bash 运行命令。使用 --json 获取结构化输出，使用 -p <pageId> 指定目标标签页。

不适用场景

• 在没有显示器的 CI/CD 中进行无头抓取——请改用 Playwright 或 Puppeteer。
• curl/wget 足以胜任的静态页面获取任务。

安全默认做法

• 默认先执行只读操作：snap、text、links、pages、ss。
• 除非没有更简单的命令可用，否则避免使用 eval。
• 仅将屏幕截图/PDF 保存到用户指定的路径或工作区路径。
• 操作完成后关闭标签页：browseros-cli close <pageId>。

设置

# Check if CLI is available
browseros-cli --version

# If not installed:
npm install -g browseros-cli

# If BrowserOS app is not installed:
browseros-cli install

# If BrowserOS is not running:
browseros-cli launch

# Configure connection:
browseros-cli init --auto

# Verify:
browseros-cli health

核心工作流：snap → act → re-snap

每次交互都遵循此循环：

1. 打开页面 → 获取页面 ID。
2. 快照 → 获取元素 ID，例如 [10] textbox "Email"、[15] button "Submit"。
3. 按 ID 操作元素（fill 10 "text"、click 15）。
4. 执行任何点击、导航或表单提交后，都要重新获取快照——DOM 更新后 ID 会改变。

重要规则：

• open <url> = 新建标签页。nav <url> = 在当前标签页中导航。
• 导航后绝不要重复使用元素 ID——务必重新执行 snap。
• 使用 text 提取内容，使用 snap 进行交互，使用 ss 进行视觉验证。

browseros-cli open https://example.com/login    # → Page ID: 5
browseros-cli snap -p 5                          # → [10] textbox "Email", [11] textbox "Password", [15] button "Sign In"
browseros-cli fill 10 "[email protected]"
browseros-cli fill 11 "password123"
browseros-cli click 15
browseros-cli snap -p 5                          # Re-snap! IDs have changed after submit
browseros-cli text -p 5                          # Read result page
browseros-cli close 5                            # Clean up

命令速查

类别	主要命令
导航	open <url>、open --hidden、nav <url>、back、forward、reload、pages、active、close [id]
查看	snap、snap -e、text、text --selector <css>、text --links、text --viewport、links、ss -o <path>、ss --full、eval "<js>"、dom、dom-search "<q>"、wait --text "<txt>"
输入	click <id>、click --double、fill <id> "text"、clear <id>、key Enter、hover <id>、focus <id>、check <id>、uncheck <id>、select <id> "val"、scroll down [amt]、drag <id> --to <id>、upload <id> <file>、dialog accept/dismiss
导出	pdf <path>、download <id> <dir>
资源	window list/create/close/activate、bookmark list/search/create/remove/update/move、history recent/search/delete、group list/create/update/ungroup/close

完整标志和选项：参阅 references/cli-commands.md，或运行 browseros-cli <command> --help。

常见模式

提取数据

browseros-cli open https://example.com/data
browseros-cli text                         # full page as markdown
browseros-cli text --selector "table"      # scoped to element
browseros-cli text --links                 # include hyperlinks

多标签页研究

browseros-cli open https://site-a.com      # → Page ID: 1
browseros-cli open https://site-b.com      # → Page ID: 2
browseros-cli text -p 1                    # extract from first
browseros-cli text -p 2                    # extract from second
browseros-cli close 1 && browseros-cli close 2

Web 应用测试

browseros-cli open http://localhost:3000
browseros-cli snap                         # get interactive elements
browseros-cli ss -o test-state.png         # visual snapshot
browseros-cli eval "document.querySelectorAll('.error').length"

常见错误

错误	修正方法
使用 CSS 选择器（fill --selector "input[type=email]"）	务必先执行 snap，然后使用元素 ID（fill 10 "text"）
点击或导航后重复使用元素 ID	DOM 更改会使 ID 失效——重新执行 snap
使用 eval 提取文本	改用 text 或 text --selector——消耗的 token 更少，且输出结构化
忘记关闭标签页	操作完成后务必执行 close <pageId>，以避免资源泄漏
想新开标签页时使用 nav	nav 会替换当前标签页。新开标签页请使用 open
想留在当前标签页时使用 open	open 会新建标签页。若要在当前标签页中导航，请使用 nav
为提取内容而截屏	使用 text 提取内容——截图会消耗 token，且需要视觉能力
使用 dialog --accept（标志语法）	正确语法为 dialog accept 或 dialog dismiss（位置参数）

深入文档

参考资料	说明
references/cli-commands.md	包含所有标志的完整命令参考

链接

• BrowserOS
• CLI 源代码
• MCP 设置指南
• Skills 仓库