WebTraverse

面向单一 base URL 的外向树探索器，构建可回放的网页探索图（Replay Graph）。支持无 LLM 的快速探索，也支持细粒度阶段用 LLM 选择动作，发现更多 UI 状态。

主要特性

• 以 base URL 为起点的受限树搜索，避免全站爬取。
• DOM/AXTree 指纹去重，减少循环和重复页面。
• 交互元素抽取（click/type/nav）+ 可选 LLM 排序。
• 生成回放图、节点库与统计信息，便于训练与分析。
• 分阶段运行（base + fine_grained），输出独立落盘。

安装

cd /Users/hzy/Documents/codes/agent/WebTraverse
uv venv .venv
source .venv/bin/activate
uv sync

快速开始（单阶段）

uv run webtraverse-search \
  --base-url "http://52.15.66.76:7770/" \
  --driver http \
  --storage-state /Users/hzy/Documents/codes/test/.auth/shopping_state.json \
  --max-depth 2 --max-nodes 32 --per-page 5 \
  --dedup-mode both

分阶段运行（base + fine_grained）

1. 编辑 run_staged.yaml（示例已提供）。
2. 执行：

uv run webtraverse-search --config run_staged.yaml

支持覆写（不改 YAML）：

uv run webtraverse-search --config run_staged.yaml \
  --set run.base_url="http://52.15.66.76:7770/" \
  --set run.run_id="shopping_$(date +%Y%m%d_%H%M%S)" \
  --set run.driver.storage_state="/Users/hzy/Documents/codes/test/.auth/shopping_state.json"

输出目录结构（分阶段子目录）：

outputs/<run_id>/<stage_name>/
  outward_graph.json
  nodes.jsonl
  edges.jsonl
  node_library/
  stats.json
  selection.json
  prompts.jsonl

说明：

• base 阶段：无需 LLM，快速构图。
• fine_grained 阶段：以 AXTree 状态变化为新节点（URL 仅作聚合），动作由 LLM 选择。
• fine_grained 需要设置 OPENAI_API_KEY。

常用参数

• --driver：http / playwright / browsergym / scriptenv
• --max-depth / --max-nodes / --per-page
• --storage-state：复用登录态（Playwright storage_state JSON）
• --dedup-mode：dom / url / both / axtree
• --policy：heuristic / category-llm / llm_action

目录结构

• src/webtraverse/core/：核心数据结构、去重、图模型
• src/webtraverse/drivers/：浏览器/HTTP 驱动
• src/webtraverse/extractors/：交互元素抽取
• src/webtraverse/policy/：动作排序策略（含 LLM）
• src/webtraverse/pipeline/：探索流程与分阶段执行
• src/webtraverse/agents/：LLM 动作选择/页面任务标注
• src/webtraverse/prompts/：Prompt 模板与管理

备注

• BrowserGym 需本地环境准备，详见你的本地 BrowserGym 安装文档。
• 如需图可视化，可使用 src/webtraverse/scripts/visualize_graph.py 输出 HTML。