autobrowse

AutoBrowse — 自我改進的瀏覽器技能

透過反覆實驗建立可靠的瀏覽器自動化技能。內部代理瀏覽網站（evaluate.ts）。你——外部代理——讀取發生的事情並改進指令（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

# 也可以——自由解析：
/autobrowse https://flights.google.com/
/autobrowse book a flight on delta.com
/autobrowse fix the existing google-flights skill

--browser-trace（預設關閉，僅限遠端）：將每次迭代與同級的 browser-trace 技能配對——將內部代理包裝在 CDP 擷取中，以取得每個頁面的網路/主控台/頁面生命週期證據。隱含 --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 → 多任務模式（產生子代理）
• --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/ 內。這使內部代理的檔案寫入遠離 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
# 然後編輯 task.md 以描述 URL、輸入、步驟和預期的 JSON 輸出

位於 ${CLAUDE_SKILL_DIR} 的技能來源保持唯讀——訓練期間只寫入 CWD 中的 ./autobrowse/。畢業（最後一步）將單一檔案寫入 ~/.claude/skills/<task>/SKILL.md。

列出可用任務：

ls ./autobrowse/tasks/

步驟 3 — 多任務：產生平行子代理

如果執行多個任務，請使用 Agent 工具同時為每個任務產生一個子代理。每個子代理收到一個自包含的提示，為其任務執行完整的 autobrowse 循環：

"你正在為任務 <name> 執行 autobrowse 技能。工作區：<absolute-path-to-workspace>（例如 /path/to/project/autobrowse）。執行 <N> 次迭代：評估 → 讀取追蹤 → 改進 strategy.md → 重複。使用 --env <env>。將 --workspace <workspace> 傳遞給每次 evaluate.mjs 呼叫。如果父呼叫使用了 --browser-trace，你必須在每次迭代中使用 SKILL.md 循環的追蹤路徑區塊（預先建立 session、附加 bb-capture、將 --connect-url 傳遞給 evaluate.mjs、停止+二分、釋放）——不要回退到預設的單一命令路徑。完全遵循 autobrowse 循環指令。

畢業時，將技能安裝到 ~/.claude/skills/<task-name>/SKILL.md，並帶有正確的 agentskills frontmatter（name + description）。不要只是複製 strategy.md——撰寫一個自包含的技能。

最後，輸出結構化摘要，包含：任務名稱、最終執行的通過/失敗、累計總成本、完成的迭代數、每次迭代表格（迭代編號、回合數、成本、狀態、測試的假設），以及 2-3 條關鍵學習。"

平行產生所有子代理，等待全部完成，然後收集它們的摘要並撰寫會議報告。

對於單一任務，跳過此步驟，直接執行下面的循環。

---

循環（為每個任務執行此操作）

迭代開始

檢查 ./autobrowse/tasks/<task>/task.md 是否存在（如果不存在，則從模板建立骨架——請參閱步驟 2）。strategy.md 在第一次執行時由 harness 自動建立為空。

需求

• ANTHROPIC_API_KEY 必須在環境中（或在 CWD 的 .env 檔案中——evaluate.mjs 會自動載入）。如果缺少，harness 會列印明確的錯誤並退出；不要在其他路徑尋找金鑰。

執行內部代理

預設路徑（無 --browser-trace） — 單一命令，無編排：

node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse
# 或對於有機器人保護的網站：
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs --task <task-name> --workspace ./autobrowse --env remote

這會執行瀏覽器工作階段，並將完整追蹤寫入 ./autobrowse/traces/<task>/latest/。

追蹤路徑（--browser-trace，僅限遠端） — 外部 harness 預先建立 Browserbase session，附加 bb-capture 作為被動觀察者，並將 session 的 connectUrl 傳遞給 evaluate.mjs，使每次內部 browse 呼叫都使用 --cdp $connectUrl --session autobrowse-main（標準的 browser-trace 模式，為觀察者提供完整的 Network/Console 事件）。每次迭代執行此區塊一次，$N 設為從 1 開始的迭代編號：

# 預檢——如果 browser-trace 未與 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 設定——預先建立 keep-alive session 並取得其 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"   # 將 browser-trace 輸出放在 autobrowse 執行目錄內
export O11Y_RUN_ID="$RUN_ID"           # 告訴 browse CLI 將 descriptors.ndjson 寫入哪個執行目錄

# b. 附加 BROWSER-TRACE——被動觀察者；在背景執行
node ${CLAUDE_SKILL_DIR}/../browser-trace/scripts/bb-capture.mjs "$sid" "$RUN_ID" &
sleep 2

# c. 執行 AUTOBROWSE——connectUrl 旗標告訴 evaluate.mjs 將 --cdp/--session
#    注入每次內部 browse 呼叫。內部代理永遠不會看到 --remote。
node ${CLAUDE_SKILL_DIR}/scripts/evaluate.mjs \
  --task <task-name> --workspace ./autobrowse --env remote \
  --connect-url "$connect_url" --run-number "$N"

# d. 停止 + 二分 + 統一——順序很重要；二分需要 session 仍然存在，
#    而 unify-trace 將二分輸出與 autobrowse 的 trace.json 合併成單一
#    按時間排序的 NDJSON，外部代理每次迭代首先讀取。
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. 釋放
browse cloud sessions update "$sid" --status REQUEST_RELEASE

這會將內部代理追蹤寫入 ./autobrowse/traces/<task-name>/latest/，並將 CDP 二分寫入 ./autobrowse/traces/<task-name>/latest/.o11y/<run-id>/。追蹤的 browse CLI 也會為每個命令發出豐富的節點描述符到 .o11y/<run-id>/cdp/descriptors.ndjson（每個頁面驅動呼叫一個 JSON 物件：target tag/id/role/accessibleName/attributes/xpath/bounding-rect）。描述符檔案供下游 codegen 使用；它不是形成假設所必需的——讀取追蹤時跳過它。

讀取追蹤

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

摘要包含持續時間、成本、回合數、決策日誌和最終 JSON 輸出。

如果代理失敗或卡住，請深入查看：

• 讀取 ./autobrowse/traces/<task-name>/latest/trace.json — 搜尋失敗回合
• 使用 Read 工具讀取失敗點附近的螢幕截圖

當使用 --browser-trace 時——從 unified-events.jsonl 開始。 Harness 將代理的回合日誌和瀏覽器的 CDP 事件流合併成一個按時間排序的 NDJSON 串流，位於執行根目錄。單一檔案，來源標記（source: "agent" | "browser"），按牆鐘時間戳交錯。從上到下瀏覽；失敗原因通常是一兩行相鄰（代理發出命令 X，瀏覽器回應 Y）。

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

結構化檔案（trace.json、.o11y/<run-id>/cdp/*）也可供代理作為深入檢視，當統一串流指向你需要更多資訊的地方時：

需求	深入檢視檔案或命令
每個頁面的總計 + 時間（事件、網路計數、每個頁面的錯誤）	.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 中的特定事件（行號或時間戳）——或者如果你必須深入某個檔案，則命名深入檢視檔案。這使更新基於證據，而不是憑感覺。僅基於代理命令的假設可能會說「點擊沒有效」；基於統一串流，它可以說「unified-events.jsonl 的第 47 行：browse open 之後是 Network.responseReceived 狀態 403 在 /api/checkout 上——切換到 --verified --proxies。」

範例：

• "點擊下拉選單後，等待 1 秒——選項在可點擊前會動畫顯示"
• "直接導航到 /pay-invoice/——完全跳過登陸頁面"
• "使用 browse fill #field_3 value 而不是 browse type——此欄位在聚焦時會清除"
• "頁面在第 8 回合顯示 spinner——在快照前新增 browse wait timeout 2000"
• （使用 --browser-trace）"在 unified-events.jsonl 的第 47 行，browse open 後緊接著 3 個連續的 Network.responseReceived 事件在 /api/availability 上回傳 403——網站正在指紋辨識；下一次迭代需要 --verified --proxies。"

更新 strategy.md

編輯 ./autobrowse/tasks/<task-name>/strategy.md。保留所有有效的內容。修正特定的失敗。新增具體的啟發式。

好的策略具有：

• 快速路徑：直接 URL 或捷徑以跳過探索
• 逐步工作流程：確切的順序和時間註記
• 網站特定知識：選擇器 ID、表單欄位名稱、成功指標
• 失敗恢復：當 X 出錯時該怎麼做

判斷結果

讀取新的摘要。它通過了嗎？有明顯進展嗎？

• 通過或進展 → 保留，進行下一次迭代
• 沒有進展或退步 → 將 strategy.md 還原為先前版本，並嘗試不同的假設

產生可執行腳本（可選）

一旦任務收斂，你可以透過 scripts/codegen.mjs 在一個或多個框架中產生確定性、可執行的腳本。這是每個框架一次 LLM 呼叫，按內容雜湊快取，並可選擇對全新 session 驗證並在失敗時重寫。

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 session 執行產生的腳本；預設 --verify
--max-retries N	驗證失敗時重寫的上限；預設 2
--cache-only	快取未命中時報錯（適合 CI）
--force	清除快取
--dry-run	估計提示大小 + 成本；不呼叫 LLM
--run <id>	強制使用特定的 run-NNN（預設：最新通過的）

輸出是每個框架一行 JSON 到 stdout。如果任何選定框架的最終狀態為 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 句話描述此技能的作用和何時使用。包含觸發關鍵字。>
---

# <任務標題> — 瀏覽器技能

## 目的
<1-2 句話：這自動化了什麼以及為什麼存在。>

## 何時使用
<何時應該使用此技能。>

## Browse CLI 參考
內部代理使用 `browse` CLI。此任務的關鍵命令：
- `browse stop` — 終止現有 session（在切換到 remote 之前始終執行）
- `browse open <url> --remote` — 啟動全新的 Browserbase 雲端 session 並導航
- `browse open <url> --local` — 啟動乾淨的本機瀏覽器並導航
- `browse tab new <url>` — 在新分頁中開啟 URL
- `browse wait load` — 等待頁面完成載入
- `browse wait timeout <ms>` — 等待固定時間以處理 spinner 或動畫
- `browse wait selector "<selector>"` — 等待元素變為可見
- `browse get title` — 驗證你在正確的頁面上
- `browse get text body` — 提取所有可見文字（內容提取的首選）
- `browse snapshot` — 取得無障礙樹；每個節點都有 `[X-Y]` 格式的引用（例如 `[0-5]`、`[2-147]`）
- `browse click [X-Y]` — 按最新快照中的引用點擊元素（包含括號）

**永遠不要在 SKILL.md 中使用 `--session <name>` 旗標。** 命名 session 是平行執行的變通方法——它們會用基礎設施問題污染技能。技能必須在隔離環境中使用預設 session 運作。

## 工作流程

### 步驟 1 — 啟動 session
<依序的確切 browse 命令>

### 步驟 2 — 導航
<確切的 URL 和驗證步驟>

### 步驟 3 — 提取
<確切的提取命令>

### 步驟 4 — 輸出
<要輸出的 JSON，參考下面的 schema>

## 網站特定注意事項
<每次迭代中學到的每個艱苦啟發式的項目符號列表。這是技能的核心價值。>

## 失敗恢復
<當導航失敗、session 被污染或提取回傳垃圾時該怎麼做>

## 預期輸出
```json
<貼上 task.md 中確切的預期輸出 schema>

寫入 SKILL.md 後，確認它已安裝：
```bash
ls ~/.claude/skills/<task-name>/SKILL.md

該技能現在在 Claude Code 中可用為 /<task-name>。

---

最終報告（多任務模式）

所有子代理完成後，列印一個 markdown 表格：

任務	迭代	最終狀態	已畢業	成本
google-flights	5	✅ 通過	是	$0.42
amazon-add-to-cart	5	❌ 失敗	否	$1.20

然後將持久化的 session 報告寫入 ./autobrowse/reports/，以便在工作區內有執行的持久記錄：

mkdir -p ./autobrowse/reports

將檔案 ./autobrowse/reports/YYYY-MM-DD-HH-MM-<tasks>.md 寫入：

# AutoBrowse Session 報告
**日期：** <ISO 日期>
**任務：** <逗號分隔列表>
**環境：** remote|local
**總成本：** $X.XX

## 結果

| 任務 | 迭代 | 通過率 | 最終狀態 | 已畢業 | 成本 |
|------|-----------|-----------|--------------|-----------|------|
| ... | ... | X/5 | ✅/❌ | 是/否 | $X.XX |

## 每個任務的學習

### <task-name>
- **關鍵見解 1：** <代理學到了什麼>
- **關鍵見解 2：** <另一個啟發式>
- **已修正的失敗模式：** <什麼失敗以及如何解決>

## 迭代日誌

### <task-name>
| 迭代 | 回合 | 成本 | 狀態 | 測試的假設 |
|------|-------|------|--------|-------------------|
| 1 | 79 | $18.75 | ❌ 失敗 | 基線 |
| 2 | 9 | $0.26 | ✅ 通過 | session 污染修正 |
| ... | ... | ... | ... | ... |

---

規則

• 只編輯 strategy.md — 永遠不要碰 task.md（除非從模板建立）或 evaluate.mjs
• 留在工作區內 — 所有訓練寫入都到 ./autobrowse/，永遠不要到 ~/.claude/skills/autobrowse/。技能來源是唯讀的。
• 每次迭代一個假設 — 一次測試一個變更
• 建立在勝利之上 — 保留有效的內容，並添加
• 信任追蹤 — 內部代理確切顯示它看到和做了什麼
• 畢業到 ~/.claude/skills/ — 你寫入的唯一檔案是最終畢業的 SKILL.md
• 在二分之前不要釋放 — 在 --browser-trace 下，每次迭代結束時的順序是不可協商的：stop-capture → bisect-cdp → browse cloud sessions update REQUEST_RELEASE。二分依賴於 session 在追蹤停止時仍然存在。