远程浏览器 CLI

远程浏览器 CLI 是 Sa2web MCP 项目自带的命令行客户端。它会通过 stdio 启动同一套 MCP Server，并把命令转换为 sa2_* 或 browser_* 工具调用。适合人工测试、自动化脚本和连通性检查。

项目已开源到 sa2web/sa2web-mcp，并以 @sa2web/mcp 发布到 npm。全局安装后会提供三个入口：

• sa2：推荐使用的 CLI 命令。
• sa2-browser：兼容别名，等价于 sa2。
• sa2-mcp：供 MCP 客户端调用的 stdio server 入口。

准备 CLI

全局安装 npm 包：

npm install @sa2web/mcp -g
npx playwright install --with-deps

然后验证 CLI：

sa2 help
sa2-browser help

sa2-mcp 应由 MCP 客户端通过 stdio 启动，通常不需要手动运行。

如果需要源码开发，请克隆仓库并构建：

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

# 开发时运行 TypeScript 源码
npm run cli -- help

# 运行编译后的文件
node dist/cli.js help

# npm link 或 npm install -g . 后使用 bin 入口
sa2 help
sa2-browser help

CLI 启动的子 MCP Server 会继承当前进程环境变量。至少需要配置 SA2_LOGIN_URL：

export SA2_LOGIN_URL='https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...'
sa2 targets

如需严格校验 HTTPS 证书，可把 SA2_IGNORE_HTTPS_ERRORS 设为 false；该变量默认 true，表示忽略目标站点或远程浏览器页面的 HTTPS 证书错误。

密钥安全

登录 URL 通常包含 clientSecret。不要把真实 URL 留在 shell 历史、纳入版本管理的脚本或 CI 日志中。生产环境应使用受保护的环境变量或密钥管理。

单条命令与持久 shell

每次直接运行 sa2 <command> 都会启动并关闭一个独立的 MCP Server。因此，需要页面状态的命令必须传入 --url、--target-id 或其它目标选择参数。

需要在同一个浏览器会话里连续操作时，请使用 sa2 shell。repl 是别名。该 shell 中的 snapshot refs 可被后续命令继续使用：

sa2> open https://example.com
sa2> snapshot
sa2> click --ref e3
sa2> type --selector '#email' --text hello@example.com
sa2> press Enter
sa2> wait --url-includes dashboard
sa2> screenshot --output page.png
sa2> exit

使用 exit 或 quit 退出。当页面命令没有传目标，且当前会话还没有打开页面时，CLI 会先打开 SA2_LOGIN_URL。

命令参考

命令	用途	常用参数
help	显示帮助	--help、-h 也可用
shell / repl	启动持久会话	exit 或 quit 退出
targets	列出代理和已保存目标	无
open	打开公网或已保存目标	--url、--target-id、--type、--id、--name、--surf、--wait-until
workspace / saas / inner	已保存目标快捷命令	ID 或名称
snapshot	返回语义快照和 refs	--filter <css> 加目标参数
text	提取可见文本	--selector <css> 加目标参数
click	点击元素或坐标	--ref、--selector、--role、--name、文本、--x、--y
type	填充或输入文本	必填 --text；定位参数、--press-enter、--append
paste	粘贴文本、HTML、RTF 或文件	--text、--html、--rtf、可重复 --path、定位参数
press	按键	位置参数 key 或 --key
wait	等待时间、文本、元素或 URL	--ms、--text、--selector、--url-includes
scroll	滚动页面或元素	方向、--amount、--mode、定位参数、--x、--y
device / toggle-device	列出设备预设或切换桌面/移动端模拟	list、预设名、--enabled、方向、尺寸、DPR、触摸、UA、--reload
screenshot	保存 PNG 文件	--output、--full-page 加目标参数
back / forward / reload	控制导航	无
close	关闭浏览器会话	无
tool	直接调用任意 MCP 工具	工具名和 --json 对象

启动 CLI 时可以用 --headless true 或 --headless false 覆盖本进程的 SA2_HEADLESS。持久会话需要在启动时指定，例如 sa2 shell --headless true；进入 shell 后再修改不会重启浏览器。

打开目标

公网 URL：

sa2 open https://example.com
sa2 open --url https://example.com --surf direct
sa2 open cloud https://example.com --wait-until domcontentloaded

已保存目标：

sa2 targets
sa2 open --target-id workspace:123
sa2 open workspace 123
sa2 workspace 123
sa2 saas GitHub
sa2 inner 7
sa2 open --type saas --name GitHub

优先使用 targets 返回的稳定 targetId。名称匹配不区分大小写，但 ID 可以避免歧义。

读取与交互

下面这些命令如果省略目标参数，会假设你已经在持久 shell 中打开了页面。作为单条命令运行时，请加上 --url 或 --target-id。

sa2 snapshot --url https://example.com
sa2 snapshot --url https://example.com --filter 'main article'
sa2 text --url https://example.com --selector 'main'

使用 snapshot 中可操作的 ref=eN。id=tN 和 context=[tN] 是 snapshot 文本引用，不是 refs，也不是 CSS selectors。

sa2 click --ref e3
sa2 click --selector 'button[type=submit]'
sa2 click --role button --name Save
sa2 click 'Learn more'
sa2 click --x 420 --y 260

sa2 type --selector '#email' --text hello@example.com
sa2 type --ref e5 --text 'new value' --press-enter
sa2 type --selector textarea --text 'more text' --append

sa2 press Enter
sa2 wait --ms 1000
sa2 wait --text Ready
sa2 wait --selector '.result'
sa2 wait --url-includes dashboard

单条命令使用 --ref 时，CLI 会先获取一次 snapshot，以便 Server 解析该 ref。在持久 shell 中，会复用最新 snapshot refs。

粘贴与滚动

sa2 paste --selector '[contenteditable]' --html '<b>Hello</b>'
sa2 paste --selector '.paste-zone' --path image.png
sa2 paste --selector 'input[type=file]' --path a.png --path b.pdf

sa2 scroll down --amount 800
sa2 scroll top
sa2 scroll --ref e8 --mode intoView
sa2 scroll --mode to --x 0 --y 1200

切换设备

sa2 device list
sa2 device ls
sa2 device 'Pixel 7'
sa2 device 'iPhone 13' --orientation landscape --reload
sa2 device --preset 'iPad Mini' --width 1024 --height 768
sa2 device --enabled true --device-scale-factor 3 --has-touch true
sa2 device Desktop

toggle-device 是 device 的别名。位置参数预设名、--device 或 --preset 会映射到 MCP 的 device 参数。其它映射包括：--device-scale-factor 对应 deviceScaleFactor，--has-touch 对应 hasTouch，--user-agent 对应 userAgent。可按需使用 --orientation portrait|landscape 和 --reload。

设备切换需要已有页面会话。建议先在 sa2 shell 中打开目标，再切换设备；这样可以保留 Cookie 和登录状态。每次切换后都应重新获取 snapshot。sa2 device Desktop 会恢复桌面模式。

截图

sa2 screenshot --url https://example.com --output page.png
sa2 screenshot --output full.png --full-page

默认截图文件名是 screenshot.png。重复传入 --path 会生成文件列表。

调用原始 MCP 工具

tool 命令用于调用没有 CLI 快捷命令的 MCP 工具。--json 必须是 JSON 对象：

sa2 tool browser_resize --json '{"width":1280,"height":720}'
sa2 tool browser_handle_dialog --json '{"accept":true}'
sa2 tool browser_hover --json '{"selector":".menu"}'

在 Bash 或 zsh 中请用单引号包住 JSON；PowerShell 的转义规则不同。发布、提交、删除、购买、授权、转账或发送消息之前，必须获得用户明确确认。

参数规则

• 支持 --key value 和 --key=value。
• 不带值的 flag（如 --press-enter）表示 true；布尔值也可显式传 true 或 false。
• --no-<key> 会把该选项设为 false。
• 可重复参数（如 --path）会变成数组。
• Shell 模式支持单引号、双引号和反斜杠转义。

排障

现象	解决方法
Unknown command	运行 sa2 help 并检查命令名
dist/server.js 缺失	重新安装 @sa2web/mcp；如果使用源码 checkout，则运行 npm run build
SA2_LOGIN_URL is not configured	在当前终端导出该变量，或通过运行环境注入
单条命令中的 ref 指向了错误页面	使用 sa2 shell，或给命令传入 --url / --target-id
找不到目标	运行 sa2 targets，使用其 targetId，并检查账号权限
找不到元素	重新获取 snapshot，使用最新 ref=eN 或真实 CSS selector
截图无法保存	检查 --output 目录的写入权限