browser-trace

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browser Trace

浏览器追踪

Attach a second, read-only CDP client to a browser session that is already being driven by your main automation. The trace records the full DevTools firehose to NDJSON, polls for screenshots and DOM dumps in parallel, and slices everything into a directory tree that bash tools can search.

This skill does not drive pages — it only listens. Pair it with the

browser

skill,

bb

, Stagehand, Playwright, or anything else that speaks CDP.

为已由主自动化程序驱动的浏览器会话附加一个只读的第二个CDP客户端。该追踪工具会将完整的DevTools事件流记录为NDJSON格式，同时并行轮询截图和DOM转储，并将所有内容切片为bash工具可搜索的目录树。

该技能不会驱动页面——它仅进行监听。可与

browser

技能、

bb

、Stagehand、Playwright或任何支持CDP的工具配合使用。

When to use

使用场景

The user wants to debug a browser-automation run (failing form, missing element, hung navigation, JS exception).
The user has a running automation and wants to attach a trace mid-flight without restarting it.
The user wants to split a CDP firehose into network / console / DOM / page buckets.
The user wants screenshots + DOM snapshots over time, joined to CDP events by timestamp.

If the user just wants to drive the browser, use the

browser

skill instead.

用户需要调试浏览器自动化运行任务（表单提交失败、元素缺失、导航挂起、JS异常）。
用户正在运行自动化任务，希望在不重启的情况下中途附加追踪工具。
用户希望将CDP事件流分割为网络/控制台/DOM/页面存储桶。
用户希望按时间戳关联CDP事件与随时间生成的截图+DOM快照。

如果用户仅需驱动浏览器，请改用

browser

技能。

Setup check

环境检查

bash

node --version                                  # require Node 18+
which browse || npm install -g @browserbasehq/browse-cli@alpha
which bb     || npm install -g @browserbasehq/cli   # only needed for Browserbase remote
which jq     || true                                # optional — used only for ad-hoc querying

Verify

browse cdp

exists (it ships in 0.5.0-alpha-a4ca430+):

bash

browse --help | grep -q "^\s*cdp " || echo "browse cdp not in this version — install @alpha"

bash

node --version                                  # 要求 Node 18+
which browse || npm install -g @browserbasehq/browse-cli@alpha
which bb     || npm install -g @browserbasehq/cli   # 仅Browserbase远程服务需要
which jq     || true                                # 可选 — 仅用于临时查询

验证

browse cdp

命令存在（该命令从0.5.0-alpha-a4ca430版本开始提供）：

bash

browse --help | grep -q "^\s*cdp " || echo "当前版本无browse cdp命令 — 请安装@alpha版本"

How it works

工作原理

Every Chrome DevTools target accepts multiple concurrent CDP clients. Your main automation is one client; this skill adds a second one that only enables observation domains (Network, Console, Runtime, Log, Page) and never sends action commands.

The tracer has three pieces:

Firehose:
```
browse cdp <target>
```
streams every CDP event as one JSON object per line to
```
cdp/raw.ndjson
```
.
Sampler: a polling loop calls
```
browse --ws <target> screenshot
```
and
```
browse --ws <target> get html body
```
on an interval (default 2s).
```
--ws
```
is one-shot and bypasses the daemon, so it doesn't fight the main automation.
Bisector: after the run,
```
bisect-cdp.mjs
```
walks
```
raw.ndjson
```
once, slices it into per-bucket JSONL files keyed by CDP method, and additionally bisects per page using top-level
```
Page.frameNavigated
```
events as boundaries.

每个Chrome DevTools目标都支持多个并发CDP客户端。主自动化程序是一个客户端；该技能会添加第二个客户端，仅启用观察域（Network、Console、Runtime、Log、Page），且从不发送操作命令。

追踪工具包含三个部分：

事件流（Firehose）：
```
browse cdp <target>
```
将每个CDP事件以单行JSON对象的形式流式传输到
```
cdp/raw.ndjson
```
。
采样器（Sampler）：轮询循环会按指定间隔（默认2秒）调用
```
browse --ws <target> screenshot
```
和
```
browse --ws <target> get html body
```
。
```
--ws
```
为一次性调用，会绕过守护进程，因此不会干扰主自动化程序。
分割器（Bisector）：运行结束后，
```
bisect-cdp.mjs
```
会遍历
```
raw.ndjson
```
一次，将其切片为按CDP方法分类的每个存储桶对应的JSONL文件，并额外以顶级
```
Page.frameNavigated
```
事件为边界按页面进行分割。

Quickstart

快速入门

Local Chrome

本地Chrome

bash

undefined

bash

undefined

1. Launch Chrome with a debugger port (any user-data-dir keeps it isolated).

1. 启动带调试端口的Chrome（使用独立的user-data-dir保证隔离）。

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
--remote-debugging-port=9222
--user-data-dir=/tmp/chrome-o11y
about:blank &

2. Start the tracer.

2. 启动追踪工具。

node scripts/start-capture.mjs 9222 my-run

3. Run your main automation against port 9222.

3. 针对端口9222运行主自动化程序。

browse env local 9222 browse open https://example.com

...whatever the run does...

...执行自动化操作...

4. Stop and bisect.

4. 停止追踪并分割数据。

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run

undefined

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run

undefined

Browserbase remote

Browserbase远程服务

Two helpers wrap the platform-side bookkeeping:

bb-capture.mjs

creates or attaches to a session and starts the tracer;

bb-finalize.mjs

pulls platform artifacts (final session metadata, server logs, downloads) into the run dir at the end.

Browserbase ends a session as soon as its last CDP client disconnects. Always create with
--keep-alive
and attach an automation client before (or together with) the tracer.
bb-capture.mjs --new
does this for you.

bash

export BROWSERBASE_API_KEY=...

两个辅助脚本封装了平台端的管理工作：

bb-capture.mjs

用于创建或附加到会话并启动追踪；

bb-finalize.mjs

在运行结束时将平台工件（最终会话元数据、服务器日志、下载文件）拉取到运行目录中。

一旦最后一个CDP客户端断开连接，Browserbase就会结束会话。请始终使用
--keep-alive
创建会话，并在（或同时）启动追踪工具之前附加自动化客户端。
bb-capture.mjs --new
会自动完成此操作。

bash

export BROWSERBASE_API_KEY=...

1. Create a keep-alive session AND start the tracer in one step.

1. 一步完成创建保活会话并启动追踪工具。

Prints the session id, connectUrl prefix, and a live debugger URL you

输出会话ID、connectUrl前缀以及可在浏览器中打开的实时调试URL，

can open in a browser to watch the run interactively.

用于交互式观察运行过程。

node scripts/bb-capture.mjs --new my-run

2. Drive automation. bb-capture stamped the session id into the manifest.

2. 执行自动化操作。bb-capture已将会话ID标记到manifest中。

SID=$(jq -r .browserbase.session_id .o11y/my-run/manifest.json) browse --connect "$SID" open https://example.com browse --connect "$SID" open https://news.ycombinator.com

3. Stop the tracer, bisect, then pull platform artifacts and release.

3. 停止追踪、分割数据，然后拉取平台工件并释放会话。

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run node scripts/bb-finalize.mjs my-run --release


Attaching to a session that's *already running* (e.g. one your production worker created) — `bb-capture.mjs` accepts a session id instead of `--new`:

```bash

node scripts/stop-capture.mjs my-run node scripts/bisect-cdp.mjs my-run node scripts/bb-finalize.mjs my-run --release


附加到**已在运行**的会话（例如生产工作进程创建的会话）——`bb-capture.mjs`接受会话ID作为参数，而非`--new`：

```bash

Pick a running session (filter client-side; bb sessions list has no --status flag)

选择一个正在运行的会话（客户端过滤；bb sessions list无--status参数）

bb sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs <session-id> mid-flight-debug

bb sessions list | jq -r '.[] | select(.status == "RUNNING") | .id'

node scripts/bb-capture.mjs <session-id> mid-flight-debug

...tracer runs alongside the existing automation client; no disruption...

...追踪工具与现有自动化客户端并行运行；无干扰...

node scripts/stop-capture.mjs mid-flight-debug node scripts/bisect-cdp.mjs mid-flight-debug node scripts/bb-finalize.mjs mid-flight-debug # without --release: leave the session running

undefined

node scripts/stop-capture.mjs mid-flight-debug node scripts/bisect-cdp.mjs mid-flight-debug node scripts/bb-finalize.mjs mid-flight-debug # 不带--release：保持会话运行

undefined

What you get from the Browserbase platform

从Browserbase平台获取的内容

bb-capture.mjs

adds a

browserbase

block to

manifest.json

(session id, project, region, started_at, expires_at, debugger URL).

bb-finalize.mjs

writes:

```
<run>/browserbase/session.json
```
— final
```
bb sessions get
```
snapshot (proxyBytes, status, ended_at, viewport, …)
```
<run>/browserbase/logs.json
```
—
```
bb sessions logs
```
output. Often empty. The CDP firehose in
```
cdp/raw.ndjson
```
is the source of truth; this is a side channel.
```
<run>/browserbase/downloads.zip
```
— files the session downloaded, if any (the script discards the empty 22-byte zip you get when there are none)

bb sessions recording

(rrweb session replay) is deprecated and isn't fetched. Use the screenshots + DOM dumps in

screenshots/

and

dom/

for visual ground truth.

The live

debugger_url

in the manifest opens an interactive Chrome DevTools view served by Browserbase — handy for watching a long-running automation while the tracer captures the firehose to disk.

bb-capture.mjs

会在

manifest.json

中添加

browserbase

模块：会话ID、项目、区域、启动时间、过期时间、调试URL。

bb-finalize.mjs

会写入：

```
<run>/browserbase/session.json
```
— 最终的
```
bb sessions get
```
快照（proxyBytes、状态、结束时间、视口等）
```
<run>/browserbase/logs.json
```
—
```
bb sessions logs
```
的输出。通常为空。
```
cdp/raw.ndjson
```
中的CDP事件流是可信数据源；此为辅助渠道。
```
<run>/browserbase/downloads.zip
```
— 会话下载的文件（如果有的话；脚本会丢弃无文件时生成的22字节空压缩包）

bb sessions recording

（rrweb会话重放）已废弃，不会被拉取。请使用

screenshots/

和

dom/

中的截图+DOM转储作为可视化依据。

manifest中的实时

debugger_url

会打开由Browserbase提供的交互式Chrome DevTools视图——在追踪工具将事件流捕获到磁盘时，可方便地观察长时间运行的自动化任务。

Filesystem layout

文件系统结构

.o11y/<run-id>/
  manifest.json                 run metadata: target, domains, started_at, stopped_at
  index.jsonl                   one line per sample: {ts, screenshot, dom, url}
  cdp/
    raw.ndjson                  full CDP firehose (one JSON object per line)
    summary.json                {sessionId, duration, totalEvents, pages[]} — see shape below
    network/{requests,responses,finished,failed,websocket}.jsonl   session-wide buckets (always written)
    console/{logs,exceptions}.jsonl
    runtime/all.jsonl
    log/entries.jsonl
    page/{navigations,lifecycle,frames,dialogs,all}.jsonl
    dom/all.jsonl                                                  (only if O11Y_DOMAINS includes DOM)
    target/{attached,detached}.jsonl
    pages/                      per-page slices, indexed by top-level frameNavigated boundaries
      000/                      first concrete page
        url.txt                 the URL for this page
        summary.json            this page's domains/network/timing block (same shape as a pages[] entry)
        raw.jsonl               firehose scoped to this page
        network/, console/, page/, runtime/, log/, target/, dom/    same buckets, only non-empty files
  screenshots/<iso-ts>.png      one PNG per sample interval
  dom/<iso-ts>.html             one HTML dump per sample interval
  browserbase/                  added by bb-finalize.mjs (Browserbase runs only)
    session.json                final `bb sessions get` snapshot (proxyBytes, status, ended_at, …)
    logs.json                   `bb sessions logs` output (often [])
    downloads.zip               `bb sessions downloads get` output (only if the session downloaded files)

When a run was started via

bb-capture.mjs

manifest.json

also carries a top-level

browserbase

block:

session_id

project_id

region

started_at

expires_at

keep_alive

debugger_url

.o11y/<run-id>/
  manifest.json                 运行元数据：目标、域、启动时间、停止时间
  index.jsonl                   每个采样的单行记录：{ts, screenshot, dom, url}
  cdp/
    raw.ndjson                  完整CDP事件流（每行一个JSON对象）
    summary.json                {sessionId, duration, totalEvents, pages[]} — 结构见下文
    network/{requests,responses,finished,failed,websocket}.jsonl   会话级存储桶（始终生成）
    console/{logs,exceptions}.jsonl
    runtime/all.jsonl
    log/entries.jsonl
    page/{navigations,lifecycle,frames,dialogs,all}.jsonl
    dom/all.jsonl                                                  （仅当O11Y_DOMAINS包含DOM时生成）
    target/{attached,detached}.jsonl
    pages/                      按顶级frameNavigated事件边界分割的每页切片
      000/                      第一个具体页面
        url.txt                 该页面的URL
        summary.json            该页面的域/网络/计时模块（结构与pages[]条目一致）
        raw.jsonl               该页面的事件流
        network/, console/, page/, runtime/, log/, target/, dom/    相同存储桶，仅生成非空文件
  screenshots/<iso-ts>.png      每个采样间隔生成一张PNG截图
  dom/<iso-ts>.html             每个采样间隔生成一份HTML转储
  browserbase/                  仅Browserbase运行时由bb-finalize.mjs添加
    session.json                最终的`bb sessions get`快照（proxyBytes、状态、结束时间等）
    logs.json                   `bb sessions logs`的输出（通常为[]）
    downloads.zip               `bb sessions downloads get`的输出（仅当会话有下载文件时生成）

当通过

bb-capture.mjs

启动运行时，

manifest.json

还包含顶级

browserbase

模块：

session_id

、

project_id

、

region

、

started_at

、

expires_at

、

keep_alive

、

debugger_url

。

Summary shape

摘要结构

cdp/summary.json

is the entry point for any analysis: it has session-level totals and a

pages[]

array indexed by top-level

Page.frameNavigated

. Per-page entries are emitted in navigation order (page 0 = first concrete URL).

json

{
  "sessionId": "45f28023-…",
  "duration": { "startMs": 1777312533000, "endMs": 1777312609000, "totalMs": 76000 },
  "totalEvents": 420,
  "pages": [
    {
      "pageId": 0,
      "url": "https://example.com/",
      "startMs": 1777312533000, "endMs": 1777312538886, "durationMs": 5886,
      "eventCount": 60,
      "domains": {
        "Network": { "count": 18, "errors": 1 },
        "Console": { "count": 2 },
        "Page":    { "count": 24 },
        "Runtime": { "count": 13 }
      },
      "network": { "requests": 4, "failed": 1, "byType": { "Document": 2, "Script": 1, "Other": 1 } }
    }
  ]
}

startMs

endMs

durationMs

are wall-clock ms, derived from

manifest.started_at

plus the offset of each event's CDP monotonic timestamp.

domains[*]

only includes

errors

warnings

keys when non-zero.

cdp/summary.json

是所有分析的入口：它包含会话级统计数据和按顶级

Page.frameNavigated

索引的

pages[]

数组。每页条目按导航顺序输出（页面0 = 第一个具体URL）。

json

{
  "sessionId": "45f28023-…",
  "duration": { "startMs": 1777312533000, "endMs": 1777312609000, "totalMs": 76000 },
  "totalEvents": 420,
  "pages": [
    {
      "pageId": 0,
      "url": "https://example.com/",
      "startMs": 1777312533000, "endMs": 1777312538886, "durationMs": 5886,
      "eventCount": 60,
      "domains": {
        "Network": { "count": 18, "errors": 1 },
        "Console": { "count": 2 },
        "Page":    { "count": 24 },
        "Runtime": { "count": 13 }
      },
      "network": { "requests": 4, "failed": 1, "byType": { "Document": 2, "Script": 1, "Other": 1 } }
    }
  ]
}

startMs

endMs

durationMs

为墙上时钟毫秒数，由

manifest.started_at

加上每个事件的CDP单调时间戳偏移量得出。仅当

errors

warnings

非零时，

domains[*]

才会包含这些键。

Drilling in with

query.mjs

使用

query.mjs

深入查询

For interactive exploration, use

scripts/query.mjs <run-id> <command>

instead of remembering paths:

bash

node scripts/query.mjs my-run list                    # one-line table of pages
node scripts/query.mjs my-run page 1                  # full summary for page 1
node scripts/query.mjs my-run page 1 network/failed   # cat failed.jsonl for page 1
node scripts/query.mjs my-run errors                  # all errors across pages, attributed by pid
node scripts/query.mjs my-run errors 2                # errors from page 2 only
node scripts/query.mjs my-run hosts                   # top hosts by request count
node scripts/query.mjs my-run host api.example.com    # all requests/responses for a host
node scripts/query.mjs my-run summary                 # full summary.json

Behind the scenes it just reads

cdp/summary.json

and the

cdp/pages/<pid>/

tree — feel free to bypass it with raw

jq

rg

once you know the shape.

对于交互式探索，使用

scripts/query.mjs <run-id> <command>

代替手动记忆路径：

bash

node scripts/query.mjs my-run list                    # 页面单行表格
node scripts/query.mjs my-run page 1                  # 页面1的完整摘要
node scripts/query.mjs my-run page 1 network/failed   # 页面1的failed.jsonl内容
node scripts/query.mjs my-run errors                  # 所有页面的错误信息，按pid归类
node scripts/query.mjs my-run errors 2                # 仅页面2的错误信息
node scripts/query.mjs my-run hosts                   # 请求量排名靠前的主机
node scripts/query.mjs my-run host api.example.com    # 某主机的所有请求/响应
node scripts/query.mjs my-run summary                 # 完整的summary.json内容

该脚本实际上只是读取

cdp/summary.json

和

cdp/pages/<pid>/

目录结构——熟悉结构后，可直接使用

jq

rg

绕过它。

Top traversal recipes

常用遍历命令示例

bash

undefined

bash

undefined

All failed network requests (use jq -c to keep it line-delimited)

所有失败的网络请求（使用jq -c保持行分隔格式）

jq -c '.params' .o11y/<run>/cdp/network/failed.jsonl

Find requests to a specific host

查找特定主机的请求

jq -c 'select(.params.request.url | test("api\.example\.com"))'
.o11y/<run>/cdp/network/requests.jsonl

4xx/5xx responses

4xx/5xx响应

jq -c 'select(.params.response.status >= 400) | {status: .params.response.status, url: .params.response.url}'
.o11y/<run>/cdp/network/responses.jsonl

Console errors only

仅控制台错误

jq -c 'select(.params.type == "error")' .o11y/<run>/cdp/console/logs.jsonl

Sequence of URLs visited

访问过的URL序列

jq -r '.params.frame.url' .o11y/<run>/cdp/page/navigations.jsonl

Find the screenshot taken closest to a timestamp (e.g., when an exception fired)

查找最接近指定时间戳的截图（例如异常发生时）

ls .o11y/<run>/screenshots/ | sort | awk -v t=20260427T1714123NZ ' $0 >= t { print; exit }'


See **REFERENCE.md** for the full jq recipe library and a method-by-method bisect map. See **EXAMPLES.md** for end-to-end debug scenarios.

ls .o11y/<run>/screenshots/ | sort | awk -v t=20260427T1714123NZ ' $0 >= t { print; exit }'


完整的jq命令库和按方法分割的映射请查看**REFERENCE.md**。端到端调试场景请查看**EXAMPLES.md**。

Best practices

最佳实践

Use
bb-capture.mjs
on Browserbase: it enforces
```
--keep-alive
```
, fetches the connectUrl, captures the debugger URL, and stamps the manifest. Doing it manually invites mistakes.
Don't
--release
a session you don't own:
```
bb-finalize.mjs --release
```
is for sessions you created with
```
--new
```
. When attaching to a production session via
```
bb-capture.mjs <session-id>
```
, run
```
bb-finalize.mjs
```
without
```
--release
```
so the original automation keeps running.
Order matters for remote: on Browserbase, attach the main automation client before (or together with) the tracer, and create the session with
```
--keep-alive
```
. Otherwise the session ends as soon as the tracer's WS closes.
Don't poll faster than ~1s: each sample opens a one-shot CDP connection and screenshots Chrome. 2s is a good default.
Pick domains deliberately: defaults (
```
Network Console Runtime Log Page
```
) cover most debugging. Add
```
DOM
```
for DOM-tree mutations (very noisy) via
```
O11Y_DOMAINS="$O11Y_DOMAINS DOM"
```
.
Use
--connect <session-id>
for the automation client on remote, not a fresh
```
browse env remote
```
(which would create a new session each time).
Always run
stop-capture.mjs
, even after a crash, so background processes don't linger and the manifest gets
```
stopped_at
```
.
Bisect once per run:
```
bisect-cdp.mjs
```
is idempotent — it overwrites the per-bucket files from
```
raw.ndjson
```
each time.

在Browserbase上使用
bb-capture.mjs
：它会强制启用
```
--keep-alive
```
、获取connectUrl、捕获调试URL并标记manifest。手动操作容易出错。
不要释放不属于你的会话：
```
bb-finalize.mjs --release
```
仅适用于你用
```
--new
```
创建的会话。通过
```
bb-capture.mjs <session-id>
```
附加到生产会话时，请不带
```
--release
```
运行
```
bb-finalize.mjs
```
，以便原自动化程序继续运行。
远程服务的顺序很重要：在Browserbase上，先附加主自动化客户端（或同时）再启动追踪工具，并使用
```
--keep-alive
```
创建会话。否则，一旦追踪工具的WS连接关闭，会话就会结束。
轮询间隔不要小于1秒：每个采样都会打开一次性CDP连接并截取Chrome截图。2秒是合适的默认值。
谨慎选择域：默认值（Network Console Runtime Log Page）覆盖大多数调试场景。如需DOM树变更追踪（非常嘈杂），可通过
```
O11Y_DOMAINS="$O11Y_DOMAINS DOM"
```
添加
```
DOM
```
域。
远程服务的自动化客户端请使用
--connect <session-id>
，而非新的
```
browse env remote
```
（后者每次都会创建新会话）。
始终运行
stop-capture.mjs
：即使崩溃后也要运行，避免后台进程残留，并为manifest添加
```
stopped_at
```
字段。
每次运行仅分割一次：
```
bisect-cdp.mjs
```
具有幂等性——每次运行都会从
```
raw.ndjson
```
覆盖每个存储桶的文件。

Troubleshooting

故障排除

browse cdp exited immediately
: usually means the target is unreachable (wrong port) or the Browserbase session has already ended. For remote, verify with
```
bb sessions get <id>
```
— if
```
status
```
is
```
COMPLETED
```
, recreate with
```
--keep-alive
```
and attach automation first.
Empty
raw.ndjson
even though processes are running: confirm a CDP client is actually driving the page. The tracer only emits events that the browser generates, so an idle browser produces ~5 lines of attach/discover messages and nothing else.
Screenshots all look identical: check
```
index.jsonl
```
— if
```
url
```
doesn't change, the page hasn't navigated yet. The polling loop runs independently of the main automation's pace.
Browserbase session ends mid-run: it likely hit
```
--timeout
```
. Recreate with a higher timeout (
```
BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...
```
) or remove the timeout flag.
bb-capture.mjs <id>
says "not RUNNING": the session you tried to attach to ended. List candidates with
```
bb sessions list | jq '.[] | select(.status == "RUNNING")'
```
and try again.
browserbase/logs.json
is empty
[]
: expected —
```
bb sessions logs
```
is sparse in practice. The CDP firehose in
```
cdp/raw.ndjson
```
is the source of truth.
Where's the session recording (rrweb)?:
```
bb sessions recording
```
is deprecated; this skill doesn't fetch it. Use the screenshot stream in
```
screenshots/
```
and DOM dumps in
```
dom/
```
.

For full reference, see REFERENCE.md. For example debug runs, see EXAMPLES.md.

browse cdp
立即退出：通常意味着目标不可达（端口错误）或Browserbase会话已结束。对于远程服务，使用
```
bb sessions get <id>
```
验证——如果
```
status
```
为
```
COMPLETED
```
，请使用
```
--keep-alive
```
重新创建并先附加自动化客户端。
进程运行但
raw.ndjson
为空：确认CDP客户端确实在驱动页面。追踪工具仅会输出浏览器生成的事件，因此空闲浏览器仅会生成约5行附加/发现消息，无其他内容。
所有截图看起来都一样：检查
```
index.jsonl
```
——如果
```
url
```
未变化，说明页面尚未导航。轮询循环独立于主自动化程序的节奏运行。
Browserbase会话中途结束：可能是触发了
```
--timeout
```
。请使用更高的超时时间重新创建（
```
BB_SESSION_TIMEOUT=1800 node scripts/bb-capture.mjs --new ...
```
）或移除超时标志。
bb-capture.mjs <id>
提示"not RUNNING"：你尝试附加的会话已结束。使用
```
bb sessions list | jq '.[] | select(.status == "RUNNING")'
```
列出候选会话并重试。
browserbase/logs.json
为空
[]
：属于正常情况——
```
bb sessions logs
```
在实际中很少有内容。
```
cdp/raw.ndjson
```
中的CDP事件流是可信数据源。
会话重放（rrweb）在哪里？：
```
bb sessions recording
```
已废弃；本技能不会拉取它。请使用
```
screenshots/
```
中的截图流和
```
dom/
```
中的DOM转储。

完整参考文档请查看REFERENCE.md。示例调试运行请查看EXAMPLES.md。

browser-trace

Original

Translation

Browser Trace

浏览器追踪

When to use

使用场景

Setup check

环境检查

How it works

工作原理

Quickstart

快速入门

Local Chrome

本地Chrome

1. Launch Chrome with a debugger port (any user-data-dir keeps it isolated).

1. 启动带调试端口的Chrome（使用独立的user-data-dir保证隔离）。

2. Start the tracer.

2. 启动追踪工具。

3. Run your main automation against port 9222.

3. 针对端口9222运行主自动化程序。

...whatever the run does...

...执行自动化操作...

4. Stop and bisect.

4. 停止追踪并分割数据。

Browserbase remote

Browserbase远程服务

1. Create a keep-alive session AND start the tracer in one step.

1. 一步完成创建保活会话并启动追踪工具。

Prints the session id, connectUrl prefix, and a live debugger URL you

输出会话ID、connectUrl前缀以及可在浏览器中打开的实时调试URL，

can open in a browser to watch the run interactively.

用于交互式观察运行过程。

2. Drive automation. bb-capture stamped the session id into the manifest.

2. 执行自动化操作。bb-capture已将会话ID标记到manifest中。

3. Stop the tracer, bisect, then pull platform artifacts and release.

3. 停止追踪、分割数据，然后拉取平台工件并释放会话。

Pick a running session (filter client-side; bb sessions list has no --status flag)

选择一个正在运行的会话（客户端过滤；bb sessions list无--status参数）

...tracer runs alongside the existing automation client; no disruption...

...追踪工具与现有自动化客户端并行运行；无干扰...

What you get from the Browserbase platform

从Browserbase平台获取的内容

Filesystem layout

文件系统结构

Summary shape

摘要结构

Drilling in with query.mjs

使用query.mjs深入查询

Top traversal recipes

常用遍历命令示例

All failed network requests (use jq -c to keep it line-delimited)

所有失败的网络请求（使用jq -c保持行分隔格式）

Find requests to a specific host

查找特定主机的请求

4xx/5xx responses

4xx/5xx响应

Console errors only

仅控制台错误

Sequence of URLs visited

访问过的URL序列

Find the screenshot taken closest to a timestamp (e.g., when an exception fired)

查找最接近指定时间戳的截图（例如异常发生时）

Best practices

最佳实践

Troubleshooting

故障排除

Drilling in with
`query.mjs`

使用
`query.mjs`
深入查询