# @browserbasehq/browse-cli 中文文档

规范地址：https://npmcn.com/package/%40browserbasehq/browse-cli/

版本：0\.6\.1
npm 元数据更新时间：2026-08-31T16:40:55.525Z
中文译文更新时间：2026-11-09T22:07:02.816Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40browserbasehq/browse-cli
原文对照：https://npmcn.com/package/%40browserbasehq/browse-cli/?lang=original
项目主页：https://github.com/browserbase/stagehand/tree/main/packages/cli#readme
源码仓库：https://github.com/browserbase/stagehand

弃用说明：The Browserbase CLI is now published as 'browse'\. Please migrate by running: npm uninstall -g @browserbasehq/browse-cli && npm install -g browse

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.9 MB，20 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：7 个
- 首次发布：2026-01-26T20:39:54.064Z
- 最新版本发布：2026-06-03T21:33:39.233Z
- 近 30 天下载量：1710（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：78（近 12 个月 78 个）

## 中文简介

在 Stagehand 上建立的 AI 代理器的浏览器自动化 CLI

## 安装

```sh
npm install @browserbasehq/browse-cli
```

也可以使用：`pnpm add @browserbasehq/browse-cli`、`yarn add @browserbasehq/browse-cli`、`bun add @browserbasehq/browse-cli`

## README

# 浏览 CLI

AI代理的浏览器自动化CLI. 建造在 [阶段手](https://github.com/browserbase/stagehand),提供原始浏览器控制而无需LLM集成.

## 安装

```bash
npm install -g @browserbasehq/browse-cli
```

需要安装在系统中的铬/铬.

## 快速启动

```bash
# Navigate to a URL (auto-starts browser daemon)
browse open https://example.com

# Take a snapshot to get element refs
browse snapshot -c

# Click an element by ref
browse click @0-5

# Type text
browse type "Hello, world!"

# Take a screenshot
browse screenshot ./page.png

# Stop the browser
browse stop
```

## 如何运作

浏览使用守护进程架构进行快速,状态的交互:

1.  **第一个命令** 自动启动 Chrome 浏览器守护进程
2.  **随后的命令** 重用同一浏览器会话
3.  **国家持续存在** 命令之间 (cookies, refs等)
4.  **多会** 支持通过 `--session` 或者说 `BROWSE_SESSION` 环境 var

### 自愈会

CLI会自动从陈旧的会话中恢复. 如果守护进程或克罗姆崩溃:

1.  检测失败
2.  清理陈旧的进程和文件
3.  重新启动守护进程
4.  重试命令

特工不需要处理恢复 - 命令"只是工作".

## 图标

### 导航

```bash
browse open <url> [--wait load|domcontentloaded|networkidle] [-t|--timeout ms]
browse reload
browse back
browse forward
```

这个 `--timeout` 旗 (默认: 3000ms) 控制等待页面负载状态的时间 。 对慢装页面使用较长的超时 :

```bash
browse open https://slow-site.com --timeout 60000
```

### 单击动作

```bash
browse click <ref> [-b left|right|middle] [-c count]  # Click by ref (e.g., @0-5)
browse click_xy <x> <y> [--button] [--xpath]          # Click at coordinates
```

### 协调行动

```bash
browse hover <x> <y> [--xpath]
browse scroll <x> <y> <deltaX> <deltaY> [--xpath]
browse drag <fromX> <fromY> <toX> <toY> [--steps n] [--xpath]
```

### 键盘

```bash
browse type <text> [-d delay] [--mistakes]
browse press <key>  # e.g., Enter, Tab, Cmd+A
```

### 表单

```bash
browse fill <selector> <value> [--no-press-enter]
browse select <selector> <values...>
browse highlight <selector> [-d duration]
```

### 页面信息

```bash
browse get url
browse get title
browse get text <selector>
browse get html <selector>
browse get value <selector>
browse get box <selector>  # Returns center coordinates

browse snapshot [-c|--compact]  # Accessibility tree with refs
browse screenshot [path] [-f|--full-page] [-t png|jpeg]
```

### 等待时

```bash
browse wait load [state]
browse wait selector <selector> [-t timeout] [-s visible|hidden|attached|detached]
browse wait timeout <ms>
```

### 多标签

```bash
browse pages          # List all tabs
browse newpage [url]  # Open new tab
browse tab_switch <n> # Switch to tab by index
browse tab_close [n]  # Close tab (default: last)
```

### 网络抓取

抓取 HTTP 请求到文件系统检查 :

```bash
browse network on     # Start capturing requests
browse network off    # Stop capturing
browse network path   # Get capture directory path
browse network clear  # Clear captured requests
```

抓取的请求被保存为目录 :

```
/tmp/browse-default-network/
  001-GET-api.github.com-repos/
    request.json      # method, url, headers, body
    response.json     # status, headers, body, duration
```

### 守护进程控制

```bash
browse start          # Explicitly start daemon
browse stop [--force] # Stop daemon
browse status         # Check daemon status
browse env [target]   # Show or switch environment: local | remote
```

### 环境切换( 本地对远程)

当代理机应该保持相同的指令流时使用环境切换,但是 浏览器运行时间需要更改 :

-   `local` 在您的机器上运行 Chrome( 最适合本地调试/ dev 循环)
-   `remote` 运行浏览器会话(最适合反机器人硬化和云运行)

```bash
# Show active environment (if running) and desired environment for next start
browse env

# Switch current session to Browserbase (restarts daemon if needed)
browse env remote

# Switch back to local Chrome (clean isolated browser by default)
browse env local
```

#### 本地浏览器策略

默认, `browse env local` 发射一个干净的孤立本地浏览器. 使用 `browse env local --auto-connect` 选择重用已运行的 启用远程调试的 Chrome 。 如果找不到可调试的 Chrome, 它 回到发射一个孤立的浏览器.

```bash
# Use a clean isolated browser (default)
browse env local

# Auto-discover local Chrome, fallback to isolated
browse env local --auto-connect

# Attach to a specific CDP target (port or URL)
browse env local 9222
browse env local ws://localhost:9222/devtools/browser/...
```

自动发现检查 :

1.  `DevToolsActivePort` 众所周知的克罗姆/克罗姆/布拉夫用户数据目录中的文档
2.  常见调试端口( 9222, 9229)

让你的克洛姆可以发现:

1.  打开 `chrome://inspect/#remote-debugging`
2.  检查框 **浏览器实例 Allow 远程调试**

更多信息,请参见 [Chrome DevTools 文档](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)。 。 。 .

使用 `browse status` 找出解决了哪些战略:

```bash
browse status
# {"running":true,"session":"default","mode":"local","localStrategy":"isolated","localSource":"isolated"}
```

#### 一般行为

-   环境范围为每 `--session`
-   `browse env <target>` 持续覆盖并重新启动守护进程
-   `browse stop` 清除覆盖, 所以下一个开始会回到基于 env- var 的自动检测
-   自动检测默认为 :
    -   `remote` 何时 `BROWSERBASE_API_KEY` 设定
    -   `local` 否则

## 全球选项

| 选项 | 说明 |
| --- | --- |
| `--session <name>` | 多个浏览器的会话名称( 默认: “ 默认 ” ) |
| `--headless` | 在无头模式下运行 Chrome |
| `--headed` | 用可见窗口运行 Chrome( 默认) |
| `--ws <url|port>` | 一发 CDP 连接( 通过守护进程) |
| `--json` | 输出为 JSON |

## 环境变量

| 变量 | 说明 |
| --- | --- |
| `BROWSE_SESSION` | 默认会话名称( 以 `--session`(中文(简体) ) |
| `BROWSERBASE_API_KEY` | 浏览器库 API 密钥( 需要 `browse env remote`(中文(简体) ) |

## 元素参考文献

运行后 `browse snapshot`,您可以通过他们的参考ID参考元素:

```bash
# Get snapshot with refs
browse snapshot -c

# Output includes refs like [0-5], [1-2], etc.
# RootWebArea "Example" url="https://example.com"
#   [0-0] link "Home"
#   [0-1] link "About"
#   [0-2] button "Sign In"

# Click using ref (multiple formats supported)
browse click @0-2       # @ prefix
browse click 0-2        # Plain ref
browse click ref=0-2    # Explicit prefix
```

完整的快照产出包括绘图:

-   **ưμ㼯A**: 跨框架 XPath 选择器
-   **缩写**: 可用时快速 CSS 选择器
-   **uRL地图**: 从链接提取的 URL

## 多个会话

同时运行多个浏览器实例 :

```bash
# Terminal 1
BROWSE_SESSION=session1 browse open https://google.com

# Terminal 2
BROWSE_SESSION=session2 browse open https://github.com

# Or use --session flag
browse --session work open https://slack.com
browse --session personal open https://twitter.com
```

## 直接 CDP 连接

选择使用已存在的 Chrome 实例 :

让你的克洛姆可以发现:

1.  打开 `chrome://inspect/#remote-debugging`
2.  检查框 **浏览器实例 Allow 远程调试**
3.  启用自动连接后重新运行 CLI .

更多信息,请参见 [Chrome DevTools 文档](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)。 。 。 .

```bash
# Auto-discover Chrome with remote debugging enabled
browse env local --auto-connect
browse open https://example.com

# Or target a specific port / WebSocket URL
browse env local 9222
browse --ws ws://localhost:9222/devtools/browser/... open https://example.com
```

## 优化 AI 工作流程

1.  **导航** 转到目标页面(浏览器自动启动)
2.  **抓图** 获取可访问性树 :
3.  **点击/填充** 直接使用参考文献(例如, `@0-5`(中文(简体) )
4.  **重新拍摄** 在核实状态变化的行动之后
5.  **停下来** 完成时

```bash
browse open https://example.com
browse snapshot -c
# [0-5] textbox: Search
# [0-8] button: Submit
browse fill @0-5 "my query"
browse click @0-8
browse snapshot -c  # Verify result
browse stop
```

## 解决问题

### 找不到颜色

CLI使用你的系统Chrome/Chrome. 未找到的 :

```bash
# macOS - Install Chrome or set path
export CHROME_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome

# Linux - Install chromium
sudo apt install chromium-browser
```

### Stale 守护进程

如果守护进程失去响应:

```bash
browse stop --force
```

### 套接字权限被拒绝

```bash
# Clean up stale socket files
rm /tmp/browse-*.sock /tmp/browse-*.pid
```

## 平台支持

-   macOS (英特尔和苹果硅)
-   Linux (x64和arm64) (英语)

Windows支持需要WSL或TCP socket执行.

## 发展

```bash
# Clone and setup (in monorepo)
cd packages/cli
pnpm install         # Install dependencies first!
pnpm run build       # Build the CLI

# Run without building (for development)
pnpm run dev -- <command>

# Or with tsx directly
npx tsx src/index.ts <command>

# Run linting and formatting
pnpm run lint
pnpm run format
```

## 许可证

麻省理工学院 - 看 [自由主义](https://npmcn.com/package/%40browserbasehq/browse-cli/LICENSE)

## 相关

-   [阶段手](https://github.com/browserbase/stagehand) - AI网页浏览器自动化框架
-   [浏览器库](https://browserbase.com/) - 云浏览器基础设施

## 常见问题

### @browserbasehq/browse-cli 是什么？

在 Stagehand 上建立的 AI 代理器的浏览器自动化 CLI注意：该包已被作者标记为弃用——The Browserbase CLI is now published as 'browse'\. Please migrate by running: npm uninstall -g @browserbasehq/browse-cli && npm install -g browse

### 如何安装 @browserbasehq/browse-cli？

在项目目录运行 npm install @browserbasehq/browse-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 browse，可以用 npx browse 直接运行。

### @browserbasehq/browse-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/browserbasehq\_\_browse-cli 是否存在。

### @browserbasehq/browse-cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @browserbasehq/browse-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @browserbasehq/browse-cli 可以商用吗？

@browserbasehq/browse-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @browserbasehq/browse-cli 的下载量有多少？

根据 npm 官方下载统计，@browserbasehq/browse-cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,710 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @browserbasehq/browse-cli 还在维护吗？

最新版本 0\.6\.1 发布于 2026/06/04（5 个月前）；至今共发布 78 个版本，其中过去 12 个月发布了 78 个；首次发布于 2026/01/27。作者已将其标记为弃用，新项目建议寻找替代方案。