# https://github.com/tangle-network/browser-agent-driver 项目说明书 生成时间：2026-06-20 23:06:18 UTC ## 目录 - [项目概述与系统架构](#page-overview) - [核心功能与CLI/SDK](#page-features) - [AI模型集成与决策引擎](#page-ai) - [评测基准、设计审计与扩展生态](#page-eval) ## 项目概述与系统架构 ### 相关页面 相关主题：[核心功能与CLI/SDK](#page-features), [AI模型集成与决策引擎](#page-ai)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) - [package.json](https://github.com/tangle-network/browser-agent-driver/blob/main/package.json) - [src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts) - [src/cli/commands/showcase.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/showcase.ts) - [src/brain/tasks/goal-verification.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/goal-verification.ts) - [src/brain/tasks/link-scout.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/link-scout.ts) - [src/brain/tasks/design-audit.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/design-audit.ts) - [src/brain/tasks/knowledge.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/knowledge.ts) - [src/brain/tasks/evaluate.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/evaluate.ts) - [src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts) - [bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) - [bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md)
# 项目概述与系统架构 ## 项目定位与核心目标 `tangle-network/browser-agent-driver` 是一个通用型智能体浏览器自动化框架（npm 包 `@tangle-network/browser-agent-driver`，CLI 命令为 `bad`），旨在让自动化代理在任意网站上完成真实的用户任务，包括搜索、信息抽取、表单填写、价格对比、复杂 UI 导航等场景 [README.md:1-5]()。 该项目在基准测试中表现突出：在 WebVoyager 的 590 个任务、15 个站点测试集上达到 **91.3% 成功率，单任务平均成本仅 $0.09**，默认模型为 `gpt-5.4` [README.md:7-9]()。除 WebVoyager 外，还在竞争性基准、WebbBench-50 等测试中保持了高水准表现 [README.md:9-11]()。 主要使用方式包括： - **CLI 安装**：通过 `install.sh` 一键脚本或 npm 全局包安装 `bad` 命令，并自动下载 Chromium（需要 Node.js 20+）[README.md:35-50]()。 - **SDK 集成**：作为库依赖（`pnpm add @tangle-network/browser-agent-driver`）嵌入其他项目 [README.md:54-56]()。 - **GitHub Action**：以设计审计动作的形式直接接入 CI/CD 流程 [README.md:115-130]()。 ## 核心特性矩阵 下表总结了项目在 README 中强调的核心能力维度： | 能力 | 说明 | 资料来源 | |------|------|----------| | Vision + DOM Hybrid | 同时使用视觉截图与可访问性树作为 LLM 输入 | [README.md:17-19]() | | Stealth & Anti-Bot | 内置反爬检测规避 | [README.md:20-22]() | | CAPTCHA Solving | 验证码自动求解 | [README.md:23-25]() | | Parallel Tab Execution | 多标签并行执行 | [README.md:26-28]() | | Multi-Model Orchestration | 规划者/执行者/验证者/监督者四角色模型分工 | [README.md:29-35](), [README.md:80-88]() | | Design Audit | 视觉驱动的设计质量审计 + 闭环修复 | [README.md:90-100]() | | Wallet & DeFi Testing | 内置 MetaMask 集成 | [README.md:102-108]() | 在多模型编排方面，默认配置示例为 `planner`、`executor`、`verifier`、`supervisor` 各自指定不同模型：规划者需要顶级推理能力，执行者只需要"廉价且能跟随指令"的模型，验证者输出结构化 yes/no，监督者负责策略性恢复 [README.md:80-88]()。 ## 系统架构与模块组成 系统整体可分为四个层次：**CLI 入口层**、**Brain 决策引擎**、**执行与沙箱层**、**基准测试与评估层**。下面是整体架构图： ```mermaid flowchart TB User[用户 / CI] CLI[CLI 入口 bad
run / snapshot / design-audit / showcase] Brain[Brain 决策引擎
多模型编排] Tasks{Brain 任务模块} Sandbox[执行与沙箱层
Playwright + sandbox-backend] Bench[基准测试套件
WebVoyager / WebBench / 竞争对比] User --> CLI CLI --> Brain Brain --> Tasks Tasks --> Goal[goal-verification] Tasks --> Link[link-scout] Tasks --> Design[design-audit] Tasks --> Eval[evaluate] Tasks --> Know[knowledge] Brain --> Sandbox Sandbox -->|Claude Code / Codex| Models[LLM 提供方] CLI -.-> Bench Bench --> Brain ``` **CLI 入口层**：`bad run` 负责运行任务，并在结束时按照 `json`、`markdown`、`html`、`junit` 等多种格式生成报告，还支持 Webhook 流式推送最终事件（`run-completed`、`suite-complete`）[src/cli/commands/run.ts:1-50]()。`bad snapshot` 提供无 LLM 的 DOM 转储，用于 CI 流水线 [README.md:75-78]()。`bad showcase` 则允许执行脚本并以截图/视频形式记录浏览器会话 [src/cli/commands/showcase.ts:1-40]()。 **Brain 决策引擎**：通过"委托 + 宿主接口（host-interface）"模式将各类决策任务拆分为独立文件，每个任务定义一个 `BrainXxxHost` 接口，由 `Brain` 实现，从而在编译期保证宿主面完整 [src/brain/tasks/goal-verification.ts:18-30](), [src/brain/tasks/link-scout.ts:18-30](), [src/brain/tasks/design-audit.ts:22-35](), [src/brain/tasks/evaluate.ts:18-30](), [src/brain/tasks/knowledge.ts:14-22]()。这种模式既减小了单个模块体积，又让 `Brain` 类保持瘦委托器（thin delegator）的清晰结构。 **执行与沙箱层**：浏览器执行基于 Playwright，并提供 `sandbox-backend` 作为 LLM 提供方适配层，可根据模型名自动识别 Claude Code、Codex 等后端（例如 `^(claude|sonnet|opus|haiku)` 映射到 `claude-code`，`^(gpt|o[134]|codex)` 映射到 `codex`）[src/providers/sandbox-backend.ts:1-30]()]。 ## 基准测试与性能评估 项目对基准场景做了严格的分层管理，避免网络噪声污染核心可靠性指标 [bench/scenarios/README.md:11-31]()： | 轨道 | 用途 | CI 是否必需 | |------|------|-------------| | `local-deterministic` | 受控夹具，用于回归与速度分析 | 是 | | `staging-auth` | 自有 staging/类生产环境端到端测试 | 否 | | `public-web` | 稳定公网页面的研究/导航/抓取 | 否 | | `webbench` | 来自 Halluminate WebBench 的外部任务，用于跨代理对比 | 否 | | `restricted-manual` | 高摩擦/政策敏感任务（验证码、反爬、法律风险）| 仅人工 | 在竞争性对比方面，README 与 `bench/competitive/README.md` 列出了主要竞品：**browser-use**（最接近的代理框架竞品）、**Stagehand**（Browserbase 的 TypeScript 代理，主打"最少 LLM 调用"）、**Skyvern**（带缓存的工作流型代理）以及原生 Computer Use 模型（OAI 与 Anthropic，作为能力天花板）[bench/competitive/README.md:9-15]()。 基准执行支持多复现（≥3 复现次数才能形成可信结论）与配置驱动的 A/B 实验，例如： ```bash npm run ab:experiment -- --spec ./bench/scenarios/specs/supervisor-ab-webbench.json \ --memory --memory-isolation per-run \ --prompt-file ./bench/scenarios/prompts/baseline-system.txt \ --out ./agent-results/ab-exp-prompts ``` [bench/scenarios/README.md:50-70]() 同时维护三套 benchmark 配置档：`default`（均衡默认）、`webbench`（快速低噪声）、`webvoyager`（证据丰富），可分别通过 `--profile benchmark-webbench` / `--profile benchmark-webvoyager` 启用 [bench/scenarios/README.md:42-46]()。 ## 部署与生态集成 框架提供了与 CI 深度集成的 GitHub Action，可在 PR 中自动发布设计审计的"Top Fixes by ROI"清单并可选择性在评分低于阈值时阻断合并 [README.md:115-130]()。`Session Viewer`（`bad view `）用于回放历史运行 [README.md:130-135]()。模型发现（agent discovery）方面，项目维护了一个 well-known 清单（`https://tangle.tools/.well-known/tangle-browser-agent.json`），让智能体在生成集成代码前能先读取产品清单 [README.md:42-50]()。 总体而言，`browser-agent-driver` 通过**多模型编排 + Vision/DOM 混合决策 + Playwright 沙箱执行 + 多轨道基准体系**的组合，在生产级浏览器自动化任务上以极低的单任务成本提供了接近上限的成功率，是研究型与生产型浏览器智能体都可借鉴的开源实现。 ## See Also - `CLI 参考` - `Brain 决策引擎与任务委托` - `多模型编排与模型路由` - `基准测试与竞争对比框架` - `GitHub Action 集成` --- ## 核心功能与CLI/SDK ### 相关页面 相关主题：[项目概述与系统架构](#page-overview), [AI模型集成与决策引擎](#page-ai)
相关源码文件 以下源码文件用于生成本页说明： - [src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts) - [src/cli/commands/preview.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/preview.ts) - [src/cli/commands/showcase.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/showcase.ts) - [src/cli/version.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/version.ts) - [README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) - [package.json](https://github.com/tangle-network/browser-agent-driver/blob/main/package.json) - [bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) - [bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md) - [src/brain/tasks/goal-verification.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/goal-verification.ts) - [src/brain/tasks/link-scout.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/link-scout.ts) - [src/brain/tasks/evaluate.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/evaluate.ts) - [src/brain/tasks/knowledge.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/knowledge.ts) - [src/brain/tasks/design-audit.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/design-audit.ts) - [src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts)
# 核心功能与 CLI / SDK ## 一、定位与适用范围 `browser-agent-driver`（CLI 命令为 `bad`）是面向真实网站的通用型 Agentic 浏览器自动化工具，宣称在 WebVoyager 基准上达到 91.3% 的通过率、单任务成本约 $0.09，默认模型为 `gpt-5.4`。项目同时提供 CLI（推荐安装方式）与 TypeScript SDK（`@tangle-network/browser-agent-driver`）两套入口，Agent 既可以通过命令行提交目标，也可以作为库函数嵌入到测试框架或自定义编排中（[README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md)）。CLI 适合快速实验与 CI 触发，SDK 适合在 Node 20+ 环境中做精细控制，例如接入 Steel 云浏览器或 Playwright 本地驱动。 ## 二、安装与发现 CLI 提供两种安装路径：脚本一键安装 `curl -fsSL https://raw.githubusercontent.com/tangle-network/browser-agent-driver/main/scripts/install.sh | sh` 或 npm 全局安装 `npm install -g @tangle-network/browser-agent-driver` 并配合 `npx playwright install chromium`（[README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md)）。SDK 安装为 `pnpm add @tangle-network/browser-agent-driver` 与 `pnpm add -D playwright`。安装完成后，CLI 通过 `bad --help`、`bad run --help`、`bad snapshot --help` 等子命令查看能力；版本号从 `package.json` 读取并用于遥测与启动横幅，文件路径相对编译产物 `dist/cli/version.js`，读取失败时回落到 `0.0.0`（[src/cli/version.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/version.ts)）。 为了让外部 Agent 正确发现能力，项目声明了产品清单（manifest）`https://tangle.tools/.well-known/tangle-browser-agent.json`，CLI 二进制固定为 `bad`，npm 包固定为 `@tangle-network/browser-agent-driver`，并明确指出非作用域的 `bad` 包与本项目无关，避免误装（[README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md)）。 ## 三、CLI 命令一览 ### 3.1 `bad run` — 目标驱动执行 `run` 是核心入口，接收 `--goal`、`--url`、模型与 Provider、可选 `--max-steps`、`--json`、`--reporters` 等参数。执行结束后支持四种 Reporter：`json`、`markdown`、`html`、`junit`，并按需写入 `reportDir/report.{ext}`，其中 `markdown` 会启用 `includeTurns` 复盘完整轮次（[src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts)）。Reporter 生成采用 best-effort 策略，单个格式失败不会中断整体退出；启用 `--json` 时，结果也会直接输出到 stdout（[src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts)）。 关闭路径经过精心排序：`renderer.destroy()` → `detachInterrupt()`（先退出 stdin raw 模式）→ `webhookStreamer.close()`（确保 `run-completed` / `suite-complete` 事件投递）→ `singleDriver.close()` → 钱包自动审批器停止 → `persistentContext.close()` → `browser.close()`，从而避免日志竞争或事件丢失（[src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts)）。 ### 3.2 `bad preview` — 计划预览 `preview` 子命令无需真正启动浏览器执行，只需传入 `--goal` 与 `--url` 即可生成执行计划，常用于调试 Prompt 或预算步骤（[src/cli/commands/preview.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/preview.ts)）。缺失必填参数会通过 `cliError` 打印 usage 并退出码 1；自定义错误类型 `PreviewError` 被捕获后单独处理，其他异常向上抛出。返回值 `result.plan` 决定退出码：成功为 0，否则 1。 ### 3.3 `bad showcase` — 视觉采集 `showcase` 用于采集页面截图、裁剪、高亮指定区域，支持自定义 `viewport`、`colorScheme`、`scale`、输出 `sink`（目录/文件）以及可选 `headless` 模式（[src/cli/commands/showcase.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/showcase.ts)）。`qualityThreshold` 与 `storageState` 让用户复用登录态并对采集结果做最小质量门槛过滤，常用于设计稿复刻、营销站点抓图与回归视觉对比。 ## 四、SDK 与 Driver 抽象 SDK 暴露 `BrowserAgent` 工厂，核心数据流为 `Driver → Brain → PageState → Action`；Driver 接口将浏览器层抽象掉，使得本地 Playwright、Steel 云浏览器、未来其他实现都可即插即用（[README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md)）。典型用法： ```typescript const driver = new PlaywrightDriver(page); const agent = new BrowserAgent({ driver, config }); ``` 或在反爬/CAPTCHA 场景接入 Steel： ```typescript const driver = await SteelDriver.create({ apiKey: process.env.STEEL_API_KEY, sessionOptions: { useProxy: true, solveCaptcha: true }, }); ``` Brain 内部进一步拆出多个细粒度任务：目标完成度核验（`verifyGoalCompletionImpl` 可独立指定 verifier 模型、并在自适应路由下回退到 nav 模型）（[src/brain/tasks/goal-verification.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/goal-verification.ts)）、链接候选排序（`recommendLinkCandidateImpl` 仅取 Top-5 节省 2–8k token）（[src/brain/tasks/link-scout.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/link-scout.ts)）、质量评分（`evaluateImpl`）（[src/brain/tasks/evaluate.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/evaluate.ts)）、知识抽取（`extractKnowledgeImpl` 把轨迹固化为 timing/selector/pattern/quirk 四类事实，供下次同类任务加速）（[src/brain/tasks/knowledge.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/knowledge.ts)）、以及设计审计（`auditDesignImpl` 输出评分与 `DesignFinding[]`）（[src/brain/tasks/design-audit.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/design-audit.ts)）。所有 Brain 任务通过 host-interface 模式与 Brain 解耦，`implements BrainXxxHost` 在编译期确保字段完整。 模型路由方面，项目支持 `sandbox-backend`，可基于模型名前缀推断后端（`claude*` → `claude-code`、`gpt/o*/codex*` → `codex`），未配置 `SANDBOX_BACKEND_TYPE` 时抛错（[src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts)）。请求头使用 Bearer Token 鉴权，并会将多模态消息统一扁平化为文本 transcript，便于在沙箱后端回放或调试。 ## 五、Benchmark / Scenario 工作流 `package.json` 内置的 npm scripts 覆盖了基准、评分板、几何提示演化、遥测聚合等多个工作流（[package.json](https://github.com/tangle-network/browser-agent-driver/blob/main/package.json)）。Scenario 套件采用 SWE-bench 风格的 5 条赛道划分： | 赛道 | 用途 | CI 必要性 | | --- | --- | --- | | `local-deterministic` | 全可控 fixture，回归与速度画像 | 必需 | | `staging-auth` | 自有 staging/prod-like 应用真实流 | 推荐 | | `public-web` | 稳定公网页面，研究/抓取 | 非必需（互联网漂移） | | `webbench` | 外部 Halluminate WebBench 衍生任务 | 非必需 | | `restricted-manual` | 高摩擦/合规敏感流（验证码、反爬、电话验证） | 禁止无人值守 | 任务类别覆盖 `navigation`、`form-completion`、`product-usage`、`research`、`scraping`、`auth`、`blocker-recovery` 七类，区分通用能力与风控场景（[bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md)）。 Benchmark Profile 提供 `default`（均衡）、`webbench`（快速低噪）、`webvoyager`（证据丰富）三档，可在 CLI 中通过 `--profile` 指定（[bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md)）。A/B 实验通过 `npm run ab:experiment` 驱动，支持重复次数、并发、prompt 变体、记忆隔离（`--memory --memory-isolation per-run`）以及 spec 驱动模式（例如 `supervisor-ab-webbench.json`）（[bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md)）。 竞品对比基准（`bench/competitive`）覆盖 `browser-use`、`Stagehand`、`Skyvern`、OpenAI / Anthropic Computer Use 等，以"最少 LLM 调用次数"等代理指标校准自身速度/成功率/单任务成本（[bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md)）。当前 README 标注状态为：spec 已完成、各 framework adapter 仅 `bad` 与 `browser-use` 处于可运行状态。 ## 六、典型执行流（架构图） ```mermaid flowchart LR U[User / CI] -- bad run goal/url --> CLI[CLI 入口] CLI --> Driver{Driver 实现} Driver -- Playwright 本地 --> Browser1[Chromium] Driver -- Steel 云 --> Browser2[Steel Browser] CLI --> Brain[Brain 决策引擎] Brain --> GoalVerify[目标核验] Brain --> LinkScout[链接侦察] Brain --> Eval[质量评估] Brain --> Knowledge[知识抽取] Brain --> DesignAudit[设计审计] Brain -- Action --> Driver Driver --> Reporter[json/md/html/junit] Reporter --> Out[report.* + stdout] ``` ## 七、常见失败模式 - **版本读取失败**：CLI 启动横幅使用 `0.0.0`，多出现在打包路径错位时，需检查 `package.json` 是否在 dist 同级（[src/cli/version.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts)）。 - **Sandbox 后端推断失败**：当 `--sandbox-backend-type` 未指定且模型名前缀不在 `claude|sonnet|opus|haiku|gpt|o[134]|codex` 时会抛错（[src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts)）。 - **Reporter 写入失败**：单个格式异常被吞掉，需检查磁盘权限与 `reportDir` 是否可写（[src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts)）。 - **`bad preview` 缺参数**：必须同时提供 `--goal` 与 `--url`，否则 `cliError` 退出码 1（[src/cli/commands/preview.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/preview.ts)）。 ## See Also - [README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) — 总览、安装与基准数据 - [bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) — Scenario 赛道与 A/B 实验 - [bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md) — 竞品对比基准 - [src/brain/tasks/*](https://github.com/tangle-network/browser-agent-driver/tree/main/src/brain/tasks) — Brain 决策任务族 --- ## AI模型集成与决策引擎 ### 相关页面 相关主题：[项目概述与系统架构](#page-overview), [核心功能与CLI/SDK](#page-features)
相关源码文件 以下源码文件用于生成本页说明： - [src/brain/tasks/goal-verification.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/goal-verification.ts) - [src/brain/tasks/link-scout.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/link-scout.ts) - [src/brain/tasks/knowledge.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/knowledge.ts) - [src/brain/tasks/design-audit.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/design-audit.ts) - [src/brain/tasks/evaluate.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/evaluate.ts) - [src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts) - [src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts) - [src/cli/commands/showcase.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/showcase.ts)
# AI模型集成与决策引擎 ## 概述 `browser-agent-driver` 的"决策引擎"由 `src/brain/` 下的 Brain 模块承担，负责把 LLM 推理、视觉理解、动作解析、目标验证与轨迹总结串联成一个 agent 循环。Brain 并非超大单体类，而是采用 **委托 + 宿主接口（delegate + host-interface）** 模式：每个具体子任务被拆分到独立模块（如 `goal-verification.ts`、`link-scout.ts`、`knowledge.ts`、`design-audit.ts`、`evaluate.ts`），Brain 仅保留瘦委托方法，所有状态访问通过 `implements BrainXxxHost` 接口在编译期被严格校验。资料来源：[src/brain/tasks/goal-verification.ts:1-15]() 决策引擎当前承担五类典型任务： - **目标完成验证（goal-verification）**：校验 agent 自报结果是否与页面真实状态一致。 - **链接推荐（link-scout）**：在确定性候选链接中选出下一步最佳链接。 - **知识抽取（knowledge）**：把已完成的轨迹压缩成可复用的 timing / selector / pattern / quirk 事实。 - **设计审计（design-audit）**：基于视觉模型分析布局、排版、对比度与 UX。 - **质量评估（evaluate）**：对当前页面给出 1–10 分的结构化评分与改进建议。 ## 委托模式与宿主接口 每个任务模块都导出一个 `xxxImpl(self: BrainXxxHost, …)` 函数；宿主接口精确声明该任务读取的 Brain 字段（如 `provider`、`modelName`、`navProvider`、`navModelName`、`scoutUseVision`、`buildUserContent`、`generate`）。Brain 在类上 `implements` 这些接口，使任何缺失或类型错误的字段在 `tsc` 阶段就暴露，而非运行时崩溃。资料来源：[src/brain/tasks/link-scout.ts:17-30]() `generate` 漏斗被统一为固定签名： ```typescript generate( system: string | SystemModelMessage[], messages: ModelMessage[], selection?: ModelSelection, maxOutputTokens?: number, ): Promise; ``` 任务模块因此只关心提示词构造与结果解析，不必重复处理 provider 切换、超时与 token 统计。资料来源：[src/brain/tasks/knowledge.ts:10-15]() ## 多模型路由与视觉通道 Brain 允许为不同子任务绑定独立的 provider / 模型，以权衡成本与质量。以 `verifyGoalCompletionImpl` 为例，校验模型按三级回退选择：显式 `verifierProvider` → 自适应路由下的 `navProvider` / `navModelName` → 主 `provider`。这种回退既允许用户"花钱用更强的验证器"，又能在自适应模式下免费复用导航模型。资料来源：[src/brain/tasks/goal-verification.ts:40-46]() `recommendLinkCandidateImpl` 更激进：它只取前 5 个候选链接而非完整快照（节省 2–8k token），并允许配置独立的 `scoutProvider` / `scoutModelName`；当 LLM 输出解析失败时，回退到确定性 top-candidate，保证进度不会卡死。资料来源：[src/brain/tasks/link-scout.ts:55-65]() 视觉内容通过统一的 `buildUserContent(text, screenshot?, forceVision?)` 注入：当 `useVision` 或 `forceVision` 为真时，截图作为图像部分与文本一同下发。`evaluateImpl` 与 `auditDesignImpl` 在评估场景中总是强制开启视觉通道，确保评分基于真实视觉证据。资料来源：[src/brain/tasks/evaluate.ts:35-40]() ## 任务执行流（架构图） ```mermaid flowchart LR A[PageState + Goal] --> B{Brain 决策循环} B -->|链接选择| C[link-scout] B -->|动作规划| D[action-parse] B -->|目标判定| E[goal-verification] B -->|设计/质量评估| F[design-audit / evaluate] C --> G[Scout Provider/Model] E --> H[Verifier Provider/Model] F --> I[Vision-capable Model] G --> J[下一步动作] H --> K{是否达成目标?} I --> L[结构化报告/分数] K -->|否| B K -->|是| M[knowledge 抽取] M --> N[可复用事实入库] ``` ## 沙盒后端与执行边界 CLI 在调用 Brain 时可通过 `sandbox-backend` 把 `ModelMessage` 转写为可读转录文本，并附上最近的用户文件附件，再发送到沙盒执行环境。它按模型名启发式判断后端类型（`claude*` / `sonnet` / `opus` / `haiku` → `claude-code`，`gpt*` / `o1-4` / `codex*` → `codex`），若无法推断则要求显式 `SANDBOX_BACKEND_TYPE` 环境变量或 CLI 参数。资料来源：[src/providers/sandbox-backend.ts:21-32]() 执行收尾时，`run` 命令会把同一结果按 `json` / `markdown` / `html` / `junit` 四种格式写入 `reportDir`，markdown 格式额外携带 turn 级别的明细；流式 webhook 在退出前会 flush `run-completed` / `suite-complete` 事件，避免下游消费方丢失尾部信号。资料来源：[src/cli/commands/run.ts:36-58]() 另一条对外入口是 `bad showcase`，它把 Brain 的能力以无 LLM 的确定性截图方式暴露给前端演示管线，便于把决策引擎与展示层解耦。资料来源：[src/cli/commands/showcase.ts:13-30]() ## 常见失败模式 - **解析失败**：所有任务模块对 LLM 输出都使用同一解析范式 —— 先 `trim()`，再去掉 Markdown 三反引号，再 `JSON.parse`；失败时返回保守默认值（如 `evaluate` 给 5 分、`knowledge` 返回空数组），因此单次解析错误不会让 agent 循环崩溃。资料来源：[src/brain/tasks/knowledge.ts:50-70]() - **模型推断失败**：当模型名无法匹配任何启发式规则时，`sandbox-backend` 会立即抛错而非静默回退，提醒调用方显式声明。资料来源：[src/providers/sandbox-backend.ts:24-32]() - **目标与实际状态不符**：`goal-verification` 通过比对 agent 自报结果与 `PageState`（URL、Title、元素快照）来判定，必要时叠加 `siteBoundaryNote` 提示一/三方边界。资料来源：[src/brain/tasks/goal-verification.ts:22-35]() ## See Also - [项目总览（README）](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) - [Brain 任务目录源码](https://github.com/tangle-network/browser-agent-driver/tree/main/src/brain/tasks) - [基准与场景说明](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) - [竞品对比说明](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md) --- ## 评测基准、设计审计与扩展生态 ### 相关页面 相关主题：[项目概述与系统架构](#page-overview), [核心功能与CLI/SDK](#page-features)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) - [package.json](https://github.com/tangle-network/browser-agent-driver/blob/main/package.json) - [bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) - [bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md) - [src/brain/tasks/design-audit.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/design-audit.ts) - [src/brain/tasks/evaluate.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/evaluate.ts) - [src/brain/tasks/goal-verification.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/goal-verification.ts) - [src/brain/tasks/link-scout.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/link-scout.ts) - [src/brain/tasks/knowledge.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/brain/tasks/knowledge.ts) - [src/providers/sandbox-backend.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/providers/sandbox-backend.ts) - [src/cli/commands/run.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/run.ts) - [src/cli/commands/showcase.ts](https://github.com/tangle-network/browser-agent-driver/blob/main/src/cli/commands/showcase.ts)
# 评测基准、设计审计与扩展生态 本仓库并非仅提供一套智能体浏览器自动化能力，而是围绕该核心能力构建了完整的「评测—审计—扩展」三层生态：底层的 Benchmark Suite 用于量化能力边界，中层的 Design Audit 与 Goal Verification 用于在轨迹末端进行结构化评估，顶层的 CLI、Showcase 与 Sandbox Backend 则把上述能力封装成可被外部代理调用的产物。 ## 一、场景化评测基准体系 `bench/scenarios/README.md` 将评测划分为五条独立轨道（tracks），以避免 flaky 互联网任务污染核心可靠性指标： | 轨道 | 用途 | CI 必需性 | |------|------|----------| | `local-deterministic` | 受控 fixture 上的回归与速度分析 | 是 | | `staging-auth` | 自有 staging 环境的端到端质量与拦截恢复 | 否（需 seeded users） | | `public-web` | 公开站点的研究/导航/抓取基线 | 否（互联网漂移风险） | | `webbench` | Halluminate WebBench 衍生任务 | 否 | | `restricted-manual` | 高摩擦或 ToS 敏感流程（验证码、反爬） | 否（人机协同） | 每个任务被进一步归入推荐类别：`navigation`、`form-completion`、`product-usage`、`research`、`scraping`、`auth`、`blocker-recovery`。执行入口在 `package.json` 中以脚本形式暴露，例如 `bench:tier1:gate`、`bench:tier2:repeat`、`baseline:track`，并可通过 `--benchmark-profile webbench` 切换为低噪声快速模式，或 `--profile benchmark-webvoyager` 切到证据丰富模式。资料来源：[bench/scenarios/README.md:1-60]()、[package.json:1-80]()。 ## 二、设计审计与质量评估 设计审计是 Brain 决策引擎内置的「闭环改进」能力。`auditDesignImpl` 接收 `PageState` 与目标（goal），使用 `DESIGN_AUDIT_PROMPT` 作为系统提示词，要求视觉模型（vision model）分析布局、排版、间距、对比度与 UX 体验，并返回结构化 `DesignFinding` 列表（含 category、severity，可选 ROI/patch 透传）。资料来源：[src/brain/tasks/design-audit.ts:1-50]()。 与之并行的是 `evaluateImpl`（通用质量评分）与 `verifyGoalCompletionImpl`（任务成功判定）。后者构造的 `textContent` 会同时附加「当前页面 URL、Title、预算化的元素快照」，并依据 `verifierProvider` 与 `adaptiveModelRouting` 选择校验模型，以避免错用昂贵模型做简单的 yes/no 判断。`recommendLinkCandidateImpl` 则限制输入仅为 top-5 候选与上下文，可节省 2-8k token。资料来源：[src/brain/tasks/evaluate.ts:1-30]()、[src/brain/tasks/goal-verification.ts:1-40]()、[src/brain/tasks/link-scout.ts:1-30]()。 `README.md` 表明 `bad design-audit` 命令既可单页审计，也支持 `--pages N` 多页爬取并自动合并系统级问题，输出按 `(impact * blast / effort)` 计算的「Top Fixes by ROI」；结合 `--evolve claude-code --project-dir ~/my-app` 可直接把发现派发给编码代理进入修复闭环。资料来源：[README.md:1-120]()。 ## 三、竞争框架对比与报告输出 `bench/competitive/README.md` 把 `browser-use`（最接近的 LangChain 风对手）、`Stagehand`（Browserbase 的 TS 代理，主打「最少 LLM 调用」）、`Skyvern`（带缓存的工作流代理）以及 Computer Use（OAI + Anthropic 基模原生浏览器能力）列为对照对象，并提出五项关键学习问题（是否在表单填充、提取、冷启动、成本、成功率上落后）。`ab:experiment` 脚本支持置信区间、并发与记忆隔离，对应脚本入口在 `package.json` 中以 `npm run ab:experiment --` 暴露。资料来源：[bench/competitive/README.md:1-50]()、[package.json:1-40]()。 `src/cli/commands/run.ts` 的 reporter 块把一次运行结果并行落盘为 JSON / Markdown / HTML / JUnit 四种格式（`report.json`、`report.md`、`report.html`、`report.xml`），其中 Markdown 形态额外保留回合轨迹（`includeTurns: true`），便于直接贴入 PR 或评审系统。资料来源：[src/cli/commands/run.ts:1-40]()。 ## 四、扩展生态：沙箱后端与 Showcase `src/providers/sandbox-backend.ts` 通过模型名前缀推断后端类型（`claude/sonnet/opus/haiku` → `claude-code`，`gpt/o1/o3/o4/codex` → `codex`），未命中时强制要求显式 `SANDBOX_BACKEND_TYPE`，并把 `ModelMessage` 序列化成纯文本 transcript，把图片附件占位为 `[Image attachment: ]`，以便沙箱代理在不接收原生多模态输入时仍能复现上下文。资料来源：[src/providers/sandbox-backend.ts:1-40]()。 `runShowcaseCommand` 则把浏览器驱动当作可视化渲染器使用：支持自定义 viewport、colorScheme、scale、storageState，并以 `--quality` 阈值控制产物校验；这使得该能力既可服务对外营销页截图，也可接入设计审计管线。资料来源：[src/cli/commands/showcase.ts:1-30]()。 ## See Also - 快速开始与 CLI 参考：[README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/README.md) - 场景轨道与策略：[bench/scenarios/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/scenarios/README.md) - 竞争基线设计：[bench/competitive/README.md](https://github.com/tangle-network/browser-agent-driver/blob/main/bench/competitive/README.md) --- --- ## Doramagic 踩坑日志 项目：tangle-network/browser-agent-driver 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/tangle-network/browser-agent-driver | host_targets=claude, chatgpt ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/tangle-network/browser-agent-driver | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/tangle-network/browser-agent-driver | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/tangle-network/browser-agent-driver | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/tangle-network/browser-agent-driver | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/tangle-network/browser-agent-driver | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/tangle-network/browser-agent-driver | release_recency=unknown