autobrowse

AutoBrowse — 自我改进的浏览器技能

通过迭代实验构建可靠的浏览器自动化技能。内层 Agent 浏览网站（evaluate.ts）。你——外层 Agent——读取执行情况并改进指令（strategy.md）。重复此过程，直到稳定通过。

入口

调用方式灵活——显式标志和自由文本自然语言均可：

/autobrowse --task google-flights
/autobrowse --task google-flights --iterations 10 --env remote
/autobrowse --task google-flights --browser-trace
/autobrowse --tasks google-flights,amazon-add-to-cart
/autobrowse --all

# Also fine — parse freely:
/autobrowse https://flights.google.com/
/autobrowse book a flight on delta.com
/autobrowse fix the existing google-flights skill

--browser-trace（默认关闭，仅限远程）：每次迭代都会配合使用同级的 browser-trace 技能——通过 CDP 捕获封装内层 Agent，收集每个页面的网络、控制台和页面生命周期证据。隐含 --env remote；与 --env local 同时使用时会报错。需要同级的 browser-trace 技能位于 ${CLAUDE_SKILL_DIR}/../browser-trace/，并且需要设置 BROWSERBASE_API_KEY 环境变量。

如果用户提供的是 URL 或自由格式指令，而不是 --task <name>：

• 如果 ${WORKSPACE}/tasks/ 中有现成任务与该网站／意图明显匹配，则使用该任务。
• 否则，选一个简短的 kebab-case 名称，从 ${CLAUDE_SKILL_DIR}/references/example-task.md 创建 ${WORKSPACE}/tasks/<name>/task.md，根据用户提供的信息填写 URL／目标，然后继续。用一行告知用户所选名称。

---

运行方法

第 1 步——解析参数并了解情况

检查传入的内容：

• --task <name> → 单任务模式
• --tasks a,b,c 或 --all → 多任务模式（启动子 Agent）
• --iterations N → 执行多少轮评估 → 改进周期（默认值：5）
• --env local|remote → 浏览器环境（默认值：local；对于受机器人防护的网站，使用 remote）
• --browser-trace → 选择启用 browser-trace 集成（默认关闭）。隐含 --env remote。如果同时显式传入 --env local --browser-trace，则报错：browser-trace requires Browserbase; drop --env local or drop --browser-trace.

如果用户传入的是自由文本，则在继续前将其映射到上述选项之一。

第 2 步——设置工作区

所有训练产物（任务定义、策略迭代、跟踪记录、报告）都存放在当前工作目录中的工作区目录里，而不是 ~/.claude/skills/ 中。这样可以避免内层 Agent 将文件写入 Claude 的主目录，也能避开权限问题。

默认工作区：${CWD}/autobrowse/

mkdir -p ./autobrowse/tasks ./autobrowse/traces ./autobrowse/reports

如果任务目录（./autobrowse/tasks/<task>/task.md）尚不存在，则创建该目录：

mkdir -p ./autobrowse/tasks/<task>
cp ${CLAUDE_SKILL_DIR}/references/example-task.md ./autobrowse/tasks/<task>/task.md
# Then edit task.md to describe the URL, inputs, steps, and expected JSON output

${CLAUDE_SKILL_DIR} 中的技能源文件保持只读——训练期间只会写入 CWD 中的 ./autobrowse/。晋升（最后一步）时，会向 ~/.claude/skills/<task>/SKILL.md 写入一个文件。

列出可用任务：

ls ./autobrowse/tasks/

第 3 步 — 多任务：启动并行子 Agent

如果运行多个任务，请使用 Agent 工具同时为每个任务启动一个子 Agent。每个子 Agent 都会收到一条自包含的提示词，为其任务运行完整的 autobrowse 循环：

“你正在为任务 <name> 运行 autobrowse 技能。工作区：<absolute-path-to-workspace>（例如 /path/to/project/autobrowse）。运行 <N> 次迭代：评估 → 读取跟踪记录 → 改进 strategy.md → 重复。使用 --env <env>。每次调用 evaluate.mjs 时都传入 --workspace <workspace>。如果父调用使用了 --browser-trace，则每次迭代都必须使用 SKILL.md 循环中的跟踪路径代码块（预创建会话、附加 bb-capture、向 evaluate.mjs 传入 --connect-url、停止并进行二分、释放会话）——不要回退到默认的单命令路径。严格遵循 autobrowse 循环说明。

晋级时，将技能安装到 ~/.claude/skills/<task-name>/SKILL.md，并添加正确的 agentskills frontmatter（name + description）。不要只复制 strategy.md——请编写一份自包含的技能。

最后，输出结构化摘要，包含：任务名称、最终运行通过/失败、累计总成本、完成的迭代次数、每次迭代的表格（迭代编号、轮数、成本、状态、测试的假设）以及 2–3 条关键经验。”

并行启动所有子 Agent，等待它们全部完成，然后收集其摘要并撰写会话报告。

单个任务时，跳过此步骤，直接运行下方的循环。

---

循环（为每个任务运行）

迭代开始

检查 ./autobrowse/tasks/<task>/task.md 是否存在（如果不存在，则根据模板创建——参见第 2 步）。首次运行时，harness 会自动创建空的 strategy.md。

要求

• 环境中必须有 ANTHROPIC_API_KEY（或在当前工作目录的 .env 文件中——evaluate.mjs 会自动加载）。如果缺失，harness 会打印清晰的错误信息并退出；不要去其他路径寻找密钥。

运行内部 Agent

默认路径（不带 --browser-trace）——单条命令，无需编排：

node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse
# or for bot-protected sites:
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse --env remote

这会运行浏览器会话，并将完整跟踪记录写入 ./autobrowse/traces/<task>/latest/。

跟踪路径（--browser-trace，仅远程）——外层 harness 会预创建 Browserbase 会话，将 bb-capture 作为被动观察器附加，并将该会话的 connectUrl 传给 evaluate.mjs，以便每次内部 browse 调用都使用 --cdp $connectUrl --session autobrowse-main（这是规范的 browser-trace 模式，可为观察器提供完整的 Network/Console 事件）。每次迭代运行一次此代码块，并将 $N 设为从 1 开始的迭代编号：

# Preflight — fail fast if browser-trace isn't installed alongside autobrowse.
BT_DIR="${CLAUDE_SKILL_DIR}/../browser-trace"
if [ ! -f "$BT_DIR/scripts/bb-capture.mjs" ]; then
  echo "ERROR: --browser-trace requires the browser-trace skill at $BT_DIR." >&2
  echo "Install it by cloning github.com/browserbase/skills and copying skills/browser-trace/" >&2
  echo "into the same parent directory as autobrowse (e.g. ~/.claude/skills/browser-trace/)." >&2
  exit 1
fi

# a. SESSION SETUP — pre-create the keep-alive session and derive its connectUrl
sid=$(browse cloud sessions create --keep-alive --verified --proxies \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).id))")
connect_url=$(browse cloud sessions get "$sid" \
  | node -e "let s='';process.stdin.on('data',c=>s+=c).on('end',()=>process.stdout.write(JSON.parse(s).connectUrl))")

RUN_ID="run-$(printf '%03d' "$N")"
TRACE_ROOT="./autobrowse/traces/<task-name>/$RUN_ID"
mkdir -p "$TRACE_ROOT"
export O11Y_ROOT="$TRACE_ROOT/.o11y"   # park browser-trace output inside the autobrowse run dir
export O11Y_RUN_ID="$RUN_ID"           # tells the browse CLI which run dir to write descriptors.ndjson into

# b. ATTACH BROWSER-TRACE — passive observer; runs in background
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bb-capture.mjs "$sid" "$RUN_ID" &
sleep 2

# c. RUN AUTOBROWSE — connectUrl flag tells evaluate.mjs to inject --cdp/--session
#    into every inner browse call. The inner agent never sees --remote.
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs \
  --task <task-name> --workspace ./autobrowse --env remote \
  --connect-url "$connect_url" --run-number "$N"

# d. STOP + BISECT + UNIFY — order matters; bisect needs the session to still
#    exist, and unify-trace joins the bisect output with autobrowse's trace.json
#    into a single time-ordered NDJSON the outer agent reads first each iter.
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/stop-capture.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bisect-cdp.mjs "$RUN_ID"
node ${CLAUDE_SKILL_DIR}/scripts/unify-trace.mjs \
  --trace-dir "$TRACE_ROOT" \
  --o11y-dir "$O11Y_ROOT/$RUN_ID"

# e. RELEASE
browse cloud sessions update "$sid" --status REQUEST_RELEASE

这会将内部 Agent 的跟踪记录写入 ./autobrowse/traces/<task-name>/latest/，并将 CDP 二分结果写入 ./autobrowse/traces/<task-name>/latest/.o11y/<run-id>/。带跟踪功能的 browse CLI 还会将每条命令的丰富节点描述符输出到 .o11y/<run-id>/cdp/descriptors.ndjson（每次页面操作调用对应一个 JSON 对象：目标标签、ID、角色、可访问名称、属性、XPath 和边界矩形）。描述符文件会提供给下游代码生成使用；它不是形成假设所必需的——读取跟踪记录时可以跳过。

阅读 trace

cat ./autobrowse/traces/<task-name>/latest/summary.md

摘要包含耗时、成本、轮次、决策日志和最终 JSON 输出。

如果 Agent 失败或卡住了，请深入查看：

• 阅读 ./autobrowse/traces/<task-name>/latest/trace.json — 搜索失败轮次
• 使用 Read 工具查看失败点附近的截图

使用了 --browser-trace 时——从 unified-events.jsonl 开始。 运行框架会在运行根目录下，将 Agent 的轮次日志和浏览器的 CDP 事件流合并成按时间排序的 NDJSON 流。文件只有一个，并带有来源标记（source: "agent" | "browser"），按墙上时钟时间戳交错排列。从上到下快速浏览；失败原因通常就在相邻的一两行中（Agent 发出命令 X，浏览器返回 Y）。

cat ./autobrowse/traces/<task-name>/latest/unified-events.jsonl

结构化文件（trace.json、.o11y/<run-id>/cdp/*）也可供 Agent 深入查看，以便在统一流指出需要进一步调查的内容时使用：

需求	深入查看的文件或命令
每个页面的总计与时间信息（事件、网络计数、页面错误）	.o11y/<run-id>/cdp/summary.json
集中查看所有失败的网络请求	.o11y/<run-id>/cdp/network/failed.jsonl
完整的控制台异常负载（堆栈跟踪等）	.o11y/<run-id>/cdp/console/exceptions.jsonl
单个页面的切片（仅包含页面 N 上的事件）	.o11y/<run-id>/cdp/pages/<pid>/
特定轮次的完整推理文本 / 未截断的工具输出	trace.json（按 turn === N 筛选）
临时分组查询（例如，按主机统计、按页面统计错误）	O11Y_ROOT=./autobrowse/traces/<task-name>/latest/.o11y node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/query.mjs <run-id> <cmd>

统一流是默认选择；只有在需要分组查询、完整文本负载，或需要筛选统一流无法提供时，才深入查看结构化文件。

提出一个假设

找出出错的确切轮次。什么单一启发式方法可以避免这个问题？

使用 --browser-trace 时，假设必须引用 unified-events.jsonl 中的具体事件（行号或时间戳）——或者指出你深入查看过的文件。这样可以确保更新有证据支撑，而不是凭感觉。仅基于 Agent 命令的假设可能会说“点击没有生效”；基于统一流的假设则可以说“unified-events.jsonl 第 47 行：browse open 后，/api/checkout 的 Network.responseReceived 状态码为 403 — 改用 --verified --proxies。”

示例：

• “点击下拉菜单后，等待 1 秒 — 选项会先播放动画，然后才能点击”
• “直接导航到 /pay-invoice/ — 完全跳过落地页”
• “使用 browse fill #field_3 value，而不是 browse type — 这个字段会在获得焦点时清空”
• “第 8 轮时页面显示加载旋转图标 — 在快照前添加 browse wait timeout 2000”
• （使用 --browser-trace 时）“在 unified-events.jsonl 第 47 行中，browse open 后，/api/availability 上连续 3 个 Network.responseReceived 事件均返回 403 — 网站正在进行指纹识别；下一次迭代需要使用 --verified --proxies。”

更新 strategy.md

编辑 ./autobrowse/tasks/<task-name>/strategy.md。保留所有有效内容。修复具体问题，并添加明确的启发式方法。

好的策略包含：

• 快速路径：直接 URL 或快捷方式，跳过探索
• 逐步工作流：精确步骤顺序和时间说明
• 网站专属知识：选择器 ID、表单字段名称、成功标志
• 失败恢复：X 出错时的处理方法

判断结果

阅读新的摘要。是否通过？是否取得了明确进展？

• 通过或有进展 → 保留，进行下一次迭代
• 没有进展或出现退步 → 将 strategy.md 恢复到先前版本，并尝试其他假设

生成可运行脚本（可选）

任务收敛后，你可以通过 scripts/codegen.mjs，使用一个或多个框架生成确定性的可运行脚本。每个框架只调用一次 LLM，并按内容哈希缓存；还可以选择与新会话进行验证，并在失败时重写。

node ${CLAUDE_SKILL_DIR}/scripts/codegen.mjs \
  --task <name> \
  --workspace ./autobrowse \
  --frameworks playwright,stagehand \
  --verify

每个框架都会在 tasks/<name>/<framework>/ 下拥有自己的子目录，存放生成的脚本和自包含脚手架（package.json、tsconfig.json）。该目录可独立运行：cd tasks/<name>/playwright && npm install && npx tsx <name>.ts——运行时唯一的要求是 BROWSERBASE_API_KEY（Stagehand 目标还需要 ANTHROPIC_API_KEY）。

内置框架：playwright、stagehand。使用 --prompt-template <path> --frameworks custom 添加自定义框架（并提供自己的运行器，或传入 --no-verify）。

常用标志：

标志	用途
--frameworks a,b,...	逗号分隔；默认为 playwright
--verify / --no-verify	使用全新的 BB 会话运行生成的脚本；默认为 --verify
--max-retries N	验证失败时重写的次数上限；默认为 2
--cache-only	缓存未命中时出错（适用于 CI）
--force	清除缓存
--dry-run	估算提示词大小和成本；不调用 LLM
--run <id>	指定某个 run-NNN（默认：最新的通过项）

每个框架都会在 stdout 上输出一行 JSON。若任何选定框架的最终状态为 passed: false，则以非零状态码退出。

请参阅 references/playwright-cdp-bridge.md，了解生成的脚本所遵循的标准 connectOverCDP 模式。

所有迭代完成后——准备就绪时发布

如果任务在最近 3 次迭代中有至少 2 次通过，或已达到最大迭代次数，请将其安装为 Claude Code 技能。不要只复制 strategy.md——技能必须自包含，并且对从未接触过此代码库的人也有用。如果在达到最大迭代次数时仍未干净通过，请注明已知失败点，但仍需记录所有已学到的内容。

将内容写入 ~/.claude/skills/<task-name>/SKILL.md 进行安装：

mkdir -p ~/.claude/skills/<task-name>

SKILL.md 使用以下结构：

---
name: <task-name>
description: <1-2 sentences describing what this skill does and when to use it. Include trigger keywords.>
---

# <Task Title> — Browser Skill

## Purpose
<1-2 sentences: what this automates and why it exists.>

## When to Use
<When should someone reach for this skill.>

## Browse CLI Reference
The inner agent uses the `browse` CLI. Key commands for this task:
- `browse stop` — kill existing session (always run before switching to remote)
- `browse open <url> --remote` — start a fresh Browserbase cloud session and navigate
- `browse open <url> --local` — start a clean local browser and navigate
- `browse tab new <url>` — open URL in a new tab
- `browse wait load` — wait for page to finish loading
- `browse wait timeout <ms>` — wait a fixed amount of time for spinners or animations
- `browse wait selector "<selector>"` — wait for an element to become visible
- `browse get title` — verify you're on the right page
- `browse get text body` — extract all visible text (preferred for content extraction)
- `browse snapshot` — get accessibility tree; each node has a ref in `[X-Y]` format (e.g. `[0-5]`, `[2-147]`)
- `browse click [X-Y]` — click element by ref from the latest snapshot (include the brackets)

**Never use `--session <name>` flags in SKILL.md.** Named sessions are a parallel-run workaround — they contaminate skills with infrastructure concerns. Skills must work in isolation with the default session.

## Workflow

### Step 1 — Start session
<exact browse commands in order>

### Step 2 — Navigate
<exact URL and verification steps>

### Step 3 — Extract
<exact extraction commands>

### Step 4 — Output
<what JSON to emit, referencing the schema below>

## Site-Specific Gotchas
<Bullet list of every hard-won heuristic from the iterations. This is the core value of the skill.>

## Failure Recovery
<What to do when navigation fails, session is contaminated, or extraction returns garbage>

## Expected Output
```json
<paste the exact expected output schema from task.md>

After writing the SKILL.md, confirm it's installed:
```bash
ls ~/.claude/skills/<task-name>/SKILL.md

该技能现在可在 Claude Code 中通过 /<task-name> 使用。

---

最终报告（多任务模式）

所有子 Agent 完成后，打印一个 Markdown 表格：

任务	迭代次数	最终状态	已晋级	成本
google-flights	5	✅ pass	是	$0.42
amazon-add-to-cart	5	❌ fail	否	$1.20

然后将会话报告持久化到 ./autobrowse/reports/，以便在工作区中保留此次运行记录：

mkdir -p ./autobrowse/reports

创建文件 ./autobrowse/reports/YYYY-MM-DD-HH-MM-<tasks>.md，内容如下：

# AutoBrowse Session Report
**Date:** <ISO date>
**Tasks:** <comma-separated list>
**Environment:** remote|local
**Total cost:** $X.XX

## Results

| Task | Iterations | Pass Rate | Final Status | Graduated | Cost |
|------|-----------|-----------|--------------|-----------|------|
| ... | ... | X/5 | ✅/❌ | yes/no | $X.XX |

## Per-Task Learnings

### <task-name>
- **Key insight 1:** <what the agent learned>
- **Key insight 2:** <another heuristic>
- **Failure mode fixed:** <what was failing and how it was resolved>

## Iteration Log

### <task-name>
| Iter | Turns | Cost | Status | Hypothesis tested |
|------|-------|------|--------|-------------------|
| 1 | 79 | $18.75 | ❌ fail | baseline |
| 2 | 9 | $0.26 | ✅ pass | session contamination fix |
| ... | ... | ... | ... | ... |

---

规则

• 只编辑 strategy.md——绝不修改 task.md（除非从模板创建）或 evaluate.mjs
• 留在工作区内——所有训练内容都写入 ./autobrowse/，绝不写入 ~/.claude/skills/autobrowse/。技能源文件为只读。
• 每次迭代只验证一个假设——一次只测试一项更改
• 在成功的基础上继续——保留有效做法，并在此基础上改进
• 相信跟踪记录——内部 Agent 会准确展示其所见和所做
• 晋级到 ~/.claude/skills/——在那里只能写入最终晋级的 SKILL.md
• 二分定位前不要释放——在 --browser-trace 模式下，每次迭代结束时的操作顺序不可更改：stop-capture → bisect-cdp → browse cloud sessions update REQUEST_RELEASE。二分定位依赖跟踪停止时会话仍然存在。