🤖 Browser4

项目主页：github.com/platonai/Browser4 · 官网：browser4.io

English | 简体中文 | 中国镜像

目录

• 🤖 Browser4
  • 🌟 项目简介
    • ✨ 核心能力
  • 📦 安装
    • 检查并安装 DeepSeek Harness（DSH）
    • 安装 Browser4 插件（推荐）
    • 启动 DSH
    • 在 DSH 中使用 Browser4
    • 安装 browser4-cli（可选）
    • 免安装使用（可选）
  • 快速开始
  • 🧭 工具选择指南
    • 如何与页面交互
    • 如何提取数据
    • 如何批量处理页面
    • 如何把 HTML 转成电子表格——零 Token
  • 💡 面向人的 CLI 指南
    • 快速上手
    • 心智模型
    • 全局选项
    • 命令列表前需要理解的概念
    • 完整命令参考
    • 超时环境变量
    • 状态持久化
  • 🚀 从源码构建
  • 架构
  • 📦 模块概览
  • 🧪 测试夹具服务器（MockSite）
  • 🤝 支持与社区
  • 📜 文档
  • 🔧 代理配置
  • 许可证

🌟 项目简介

💖 Browser4：一个快速、智能、可扩展、适用于多种场景的智能体浏览器 💖

🌟 简介

💖 Browser4 — 面向 AI Agent 的新一代智能浏览器引擎，连接网页、数据与自动化任务。 💖

✨ 核心能力

• 🤖 Agent Browser — 为 AI Agent 提供自主浏览、网页操作和自动化执行能力。
• 🧠 ML 智能提取 — 通过机器学习理解网页结构，无需消耗 LLM Token，即可从复杂页面提取结构化数据。
• ⚡ 高性能架构 — 协程安全设计，支持单机每天 10 万～20 万复杂网页访问。
• 🧬 智能数据管线 — 融合 LLM、ML、X-SQL 与选择器，实现复杂网页的数据提取、清洗与经验复用。
• 📦 企业级自动化平台 — 支持大规模网页访问、CDP 原生控制、批处理、有状态浏览、插件扩展等能力。

📦 安装

1. 检查并安装 DeepSeek Harness（DSH）

先检查本地是否已经安装 DSH：

dsh --version

如果命令能够正常输出版本号，说明 DSH 已就绪，可直接进入下一步。如果提示找不到命令，请根据操作系统安装。

macOS

安装 Node.js 20 或更高版本，然后安装 DSH：

brew install node
npm install -g @deepseek-ai/dsh

Windows

在 PowerShell 中安装 Node.js LTS：

winget install OpenJS.NodeJS.LTS

安装完成后重新打开 PowerShell，再安装 DSH：

npm install -g @deepseek-ai/dsh

安装后再次运行 dsh --version，确认 DSH 可以正常使用。

2. 安装 Browser4 插件（推荐）

用一条命令把 dsh-browser4 作为 DSH 插件 bundle 安装——从 npm registry 或直接从 GitHub：

dsh plugin --profile web add dsh-browser4                  # npm registry
dsh plugin --profile web add github:platonai/dsh-browser4  # GitHub

安装包时会执行包内的安装脚本（scripts/install-browser4.mjs），它只做两件事：

1. 按照 browser4-cli SKILL 的安装流程 安装 browser4-cli（npm install -g browser4-cli → browser4-cli install；npm 不可用时回退到 SKILL.md 中的平台引导脚本）。
2. 用 browser4-cli skills unpack 把 SKILL 文件解压到 ~/.dsh/skills 和 ~/.agents/skills（尊重 $DSH_HOME / $DSH_AGENTS_HOME），让所有 DSH profile 与 preset 都能发现 browser4-cli、browser4-experience、browser4-plugin、scent-miner 四个技能。

此外，bundle 的 cordis.patch.yml 会注册 skill-provider 层，直接从已安装包的 skills/ 目录提供同样的技能。

解压到用户目录的是你本机 browser4-cli 二进制内嵌的版本。 browser4-cli skills unpack 读取的是 CLI 自身编译进去的技能文件，而不是本 npm 包里附带的那份。这是有意为之：智能体的使用说明永远与你机器上实际安装的 CLI 的命令集、选项和行为完全一致——无网络请求、无版本漂移；升级 browser4-cli 后只需再跑一次 browser4-cli skills unpack 即可刷新。

也支持更短的别名：dsh plugin --profile web add b4@github:platonai/dsh-browser4。

pnpm ≥ 10 默认拦截依赖构建脚本。 如果 add 因构建权限失败，把 pnpm 打印的包 key 原样复制到该 profile 的 pnpm-workspace.yaml（位于 $DSH_HOME/profiles/web/）并重新执行命令：

allowBuilds:
  dsh-browser4: true

从本地 checkout 安装（dsh plugin --profile web add ./dsh-browser4）只是链接包，不会执行生命周期脚本——请随后手动运行一次安装器：

node scripts/install-browser4.mjs

3. 启动 DSH

dsh web

4. 在 DSH 中使用 Browser4

启动 DSH 后，bundle 会自动加载 Skill Provider，模型可通过 skill({ name: "browser4-cli" }) 或 /browser4-cli 命令加载使用说明，无需任何额外配置。

之后只需用自然语言向智能体描述任务即可，智能体会通过 browser4-cli 命令（借助 Bash 工具）驱动浏览器完成操作，例如：

打开 https://browser4.io，找到安装指南，
并把整页截图保存到当前目录。

智能体在背后执行的典型流程：

browser4-cli open --headless https://browser4.io   # 打开会话（首次运行后端启动约需 10 秒）
browser4-cli snapshot -i --boxes                   # 检查页面并获取元素 ref
browser4-cli click e15                             # 使用 ref 进行交互
browser4-cli screenshot --full-page --filename page.png

安装 browser4-cli（可选）

插件安装器已经帮你装好了 browser4-cli，因此手动安装是可选的。仅当你想在 DSH 之外单独使用 browser4-cli，或者 AI 智能体在阅读 SKILL 后被要求自行安装时才需要。

通过 npm 全局安装 browser4-cli（需要 Node.js）：

npm install -g browser4-cli
browser4-cli install

或者用单条命令直接引导安装原生二进制：

Windows（PowerShell）：

irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex
browser4-cli install

Linux / macOS（bash）：

curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash
browser4-cli install

免安装使用（可选）

不需要安装插件。启动 DSH 后，让智能体阅读 SKILL 并自行安装：

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed), then run `browser4-cli skills unpack` into ~/.dsh/skills and ~/.agents/skills, for browser automation

智能体会按照 SKILL.md 的 Installation 章节安装 browser4-cli，并把同一套技能文件解压到 DSH 技能目录——效果与插件安装器一致。

快速开始

把下面这段说明粘贴给你喜欢的 AI 智能体（如 claude、codex、workbuddy 或 openclaw）并执行：

Read https://browser4.io/SKILL.md and install browser4-cli (if not installed) for browser automation to perform the following task:

1. go to amazon.com
2. search for pens to draw on whiteboards
3. compare the first 4 ones
4. write the result to a markdown file

🧭 工具选择指南

根据任务类型选择最合适的工具：

如何与页面交互

需要与页面交互？
├─ 需要打开或恢复浏览器会话？→ open [url] 或 goto <url>
├─ 想先看当前哪些元素可点击 / 可输入？→ snapshot -i --boxes
├─ 需要点击按钮、链接、复选框或菜单项？→ click <ref>
├─ 需要填写表单并替换已有文本？→ fill <ref> "<text>"
├─ 需要像真人一样继续输入，或者发送 Enter / Tab？→ type / press
├─ 需要从下拉框中选择值？→ select <ref> <value>
├─ 需要悬停、拖拽、滚动，或直接使用鼠标？→ hover / drag / scroll / mouse*
├─ 需要在下一步前等待页面稳定？
│  ├─ 等元素出现？→ wait <ref|selector>
│  ├─ 等文本出现？→ wait --text "..."
│  ├─ 等 URL 变化？→ wait --url "**/target"
│  └─ 等加载 / 网络请求完成？→ wait --load networkidle
├─ 需要确认动作之后页面发生了什么变化？→ snapshot、get 或 eval
└─ 需要高效重复很多 UI 步骤？→ batch "goto ..." "click ..." "fill ..."

典型交互流程：

browser4-cli goto https://example.com/login
browser4-cli snapshot -i --boxes
browser4-cli fill e3 "user@example.com"
browser4-cli fill e4 "secret" --submit
browser4-cli wait --load networkidle
browser4-cli snapshot -i

如何提取数据

需要从页面提取数据？
├─ 页面需要先点击、填写、滚动？→ snapshot + refs，再提取
├─ 静态页面，只取一个字段？→ htmlsnapshot get text "<selector>"
├─ 静态页面，获取某字段所有匹配项？→ htmlsnapshot get all text "<selector>"
├─ 静态页面，需要相关联的多字段（每个条目的标题+价格+链接）？
│  → htmlsnapshot query --sql @query.sql
├─ 需要处理实时 JS / 复杂 DOM 逻辑？→ eval --json
├─ 自然语言需求（“找到商品价格”）？→ extract（需要 LLM key）
└─ 大规模、多页面处理？→ crawl 或 swarm 搭配 --sql

如何批量处理页面

需要处理多页面？
├─ 单个列表页（搜索结果页）？→ htmlsnapshot query + DOM_LOAD_AND_SELECT
├─ 已知 URL 列表（在文件中）？→ crawl --seed-file urls.txt --depth 0 --sql @query.sql
├─ 从起始 URL 开始递归抓取？→ crawl <url> --out-link-selector "..." --depth N
├─ 需要并行执行（高吞吐）？→ swarm create → swarm query --seed-file ...
├─ 需要周期性监控（如每小时检查一次）？→ loop -- eval "..." -i 3600
└─ 只是脚本里处理少量 URL？
   → for url in ...; do browser4-cli goto "$url"; ... done

如何把 HTML 转成电子表格——零 Token

WebMiner 会对下载下来的 HTML 文件做机器学习聚类，生成结构化电子表格和交互式报告——不消耗 LLM token，全部本地运行。

已经有 HTML 文件，想要结构化数据，而且不想花 token？
├─ < 1,000 页（小中规模）？→ WebMiner Free（SMILE ML 引擎）
│  java -jar scent-miner.jar all ./pages/
│  → 交互式 HTML 报告 + Excel 电子表格，本地运行，零成本
├─ > 1,000 页（生产规模）？→ WebMiner Commercial（Apache Spark ML）
│  同样是 encode → cluster → views 流程，但可分布式扩展到多台机器
└─ 还需要先获取页面？
   ├─ 单页下载：browser4-cli htmlsnapshot export
   ├─ 批量下载：browser4-cli crawl --seed-file urls.txt --depth 0
   └─ 高吞吐：browser4-cli swarm create → swarm query --seed-file ...
       然后把 HTML 目录交给 WebMiner

Pipeline： encode（HTML → 特征向量 → CSV）→ cluster（KMeans，自动检测 K）→ views（HTML 报告 + Excel）。免费版使用 SMILE ML 库进行单机聚类（< 1,000 页）。需要 JDK 17+。安装说明见 web-miner。

💡 面向人的 CLI 指南

browser4-cli 不只是智能体后端，它本身也是一个适合人类直接使用的浏览器自动化命令行工具。你可以用它驱动真实浏览器、检查页面状态、提取结构化数据、运行 X-SQL、编排 crawl / swarm 任务、管理服务端插件与 skills，也可以把长任务交给内建的 AI 能力处理。

如果你想看嵌入给智能体使用的说明，请查看 skills/browser4-cli/SKILL.md。这一节是面向人的参考手册。

快速上手

# 打开浏览器会话（默认无头模式，添加 --headed 可显示窗口）
browser4-cli open https://browser4.io

# 或者显式打开可视浏览器：
browser4-cli open --headed https://browser4.io

# 检查页面并获取元素 ref
browser4-cli snapshot --boxes

# 使用 snapshot 输出中的 ref 进行交互
browser4-cli click e15
browser4-cli fill e16 "Browser4" --submit

# 从当前页面实时提取数据
browser4-cli get text "h1"

# 捕获静态 DOM 快照，用于重复提取
browser4-cli htmlsnapshot
browser4-cli htmlsnapshot get text "#main-content"
browser4-cli htmlsnapshot query --sql @query.sql

# 保存输出
browser4-cli screenshot --full-page --filename page.png
browser4-cli pdf --filename page.pdf

心智模型

1. 以会话为中心：命令默认作用于当前浏览器会话；需要隔离状态时使用 -s <name>。
2. 两种页面视图：snapshot 用于交互式工作，提供 e15 这样的元素 ref；htmlsnapshot 用于 DOM / X-SQL 提取，基于 CSS 选择器。
3. 交互式提取 vs 静态提取：页面需要先操作时用 click、fill、type、press、wait；需要结构化提取时优先用 htmlsnapshot query。
4. 同步命令 vs 异步任务：agent、swarm、crawl、异步 chat 一类命令会返回任务 ID，后续再查询状态和结果。

全局选项

这些标志可以放在任何命令之前。

命令列表前需要理解的概念

元素 ref 与 CSS 选择器

• snapshot 会返回可访问性树中的 ref，例如 e5、e12、e42
• 大多数交互命令同时接受 snapshot ref 和 CSS 选择器
• htmlsnapshot 系列命令使用 CSS 选择器，不使用可访问性 ref

snapshot 与 htmlsnapshot

LLM 配置

extract、summarize、chat、agent run 以及 X-SQL 的 llm_* 函数都需要 LLM 提供商的 API key。

export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

完整命令参考

会话生命周期与服务端管理

browser4-cli open --headed https://example.com
browser4-cli attach --cdp chrome
browser4-cli doctor --verbose
browser4-cli doctor log server.log --tail
browser4-cli doctor metrics grep request

导航

核心交互

除非另有说明，所有交互命令都接受 snapshot ref（如 e15）或 CSS 选择器。多数命令还支持 --no-snapshot，用于跳过动作执行后的自动可访问性快照。

wait --load 接受 domcontentloaded、load 和 networkidle。

browser4-cli click e8 --follow
browser4-cli fill e4 "john@example.com" --submit
browser4-cli type "Browser4" e7 --verify
browser4-cli wait --text "Success"
browser4-cli wait --load networkidle

键盘与鼠标

页面检查与实时提取

get 支持的 mode：

browser4-cli snapshot -i --boxes
browser4-cli snapshot grep -C 2 "button"
browser4-cli eval "document.title"
browser4-cli eval --file script.js --await
browser4-cli console warn
browser4-cli cdp Runtime.evaluate --json '{"expression":"document.title"}'

HTML 快照与 X-SQL 提取

htmlsnapshot 会捕获并存储原始 DOM 快照，是 Browser4 结构化提取工作流的核心。

重要规则：

• 需要 ref 和交互时用 snapshot
• 需要重复 DOM 提取时用 htmlsnapshot
• 推荐使用 htmlsnapshot query --sql @query.sql，避免 shell 转义问题
• 需要关联型列表提取时，优先使用 htmlsnapshot query，而不是多次 get all

browser4-cli htmlsnapshot
browser4-cli htmlsnapshot get text "#productTitle"
browser4-cli htmlsnapshot get all text ".result-title" --offset 10 --limit 5
browser4-cli htmlsnapshot inspect ".s-result-item" --depth 6 --max 20
browser4-cli htmlsnapshot export --file page.html --clean
browser4-cli htmlsnapshot query --sql @query.sql

深入了解 X-SQL 可参见 skills/browser4-cli/references/htmlsnapshot.md 与 skills/browser4-cli/references/x-sql-dom-load-select.md。

截图与 PDF

标签页

浏览器存储与本地页面数据

AI 提取、chat 与自主 agent 任务

这些命令需要 LLM key。

browser4-cli extract "product name, price, rating"
browser4-cli extract "contacts" --schema @schema.json
browser4-cli summarize --selector "#reviews"
browser4-cli agent run "Go to amazon.com, compare the first 3 keyboards, write a summary"
browser4-cli agent status agent-task-1

Batch 与 loop 自动化

可用于 batch 的命令：

goto  go-back  go-forward  reload  press  type  keydown  keyup
click  dblclick  hover  fill  select  check  uncheck  drag
mousemove  mousedown  mouseup  mousewheel  scroll  wait
get  eval  snapshot  screenshot  pdf  dialog-accept  dialog-dismiss
resize  tab-list  tab-new  tab-close  tab-select

browser4-cli batch --bail "goto https://example.com" "snapshot" "screenshot"
browser4-cli loop "load https://example.com and extract the title" -i 300 -n 10
browser4-cli loop --shell "curl -s https://api.example.com/health" -i 60
browser4-cli loop --list

用于规模化处理的 Swarm 与 Crawl

co 前缀可以作为 swarm 的别名使用。

browser4-cli swarm create --max-open-tabs 12 --display-mode HEADLESS
browser4-cli swarm query --seed-file urls.txt --sql @query.sql --refresh
browser4-cli crawl "https://example.com" --depth 2 --out-link-selector "a[href]"
browser4-cli crawl list

内置 skill 文件 与 已安装运行时 skill

Browser4 中有两套不同的 “skill” 表面：

1. skills ...：管理随 CLI 一起打包、嵌入式分发的 skill 文档。
2. skill-*：管理由后端暴露的、已安装运行时 skill。

CLI 内置 skills

已安装运行时 skills

渐进式经验记忆

这些命令作用于 Browser4 的学习型经验存储。

插件

插件是运行在服务端的 JAR 扩展，用于扩展 Browser4 能力。

高级 / 当前隐藏命令

这些命令实际存在于 CLI 中，但默认 public help 不会展示。

超时环境变量

export BROWSER4_CLI_INPUT_TIMEOUT_SECS=180
export BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS=300

状态持久化

除非显式覆盖，CLI 状态保存在 ~/.browser4 下：

• 默认会话：~/.browser4/cli-state.json
• 命名会话：~/.browser4/sessions/<name>.json
• loops：~/.browser4/loops/<name>.json

运行时 bundle 则单独保存在平台惯例的应用数据目录中，因此清理会话状态不会导致重新下载 Browser4 本体。

🚀 从源码构建

前置要求： Git、JDK 17+（推荐 21+）、Chrome/Chromium，以及 PowerShell 7（Linux/macOS 需要）。完整前置条件表、平台差异工具和 Chrome 自动探测路径请见 Build from Source。

1. 克隆仓库

   git clone https://github.com/platonai/Browser4.git
   cd Browser4
   

2. 配置你的 LLM API key

   编辑 application.properties 并添加 API key，或者通过环境变量配置。支持的提供商和变量名见上文 LLM 配置。

3. 构建项目

   ./mvnw -DskipTests
   

4. 构建并运行 CLI（源码方式）

   # 构建 Rust CLI（需要 Rust toolchain）
   cd cli/browser4-cli && cargo build --release
   
   # 或直接运行而不安装：
   cargo run --manifest-path cli/browser4-cli/Cargo.toml -- --help
   
   # 加上 --quiet 可隐藏 Cargo 构建状态输出：
   cargo run --quiet --manifest-path cli/browser4-cli/Cargo.toml -- <command>
   
   # 或全局安装：
   cd cli/browser4-cli && cargo install --path .
   

   Windows 上可在命令前加 chcp 65001 >nul &&，以获得正确的 UTF-8 输出。 完整平台说明请见 Build from Source。

   开发模式包装脚本（无需安装）： 仓库根目录提供自动按需构建的包装脚本。可使用 ./b4w.ps1 <command>（PowerShell）、./b4w.sh <command>（Git Bash / Linux / macOS）或 ./b4w.bat <command>（CMD），参数与已安装的 browser4-cli 完全一致。

🎬 YouTube:

📺 Bilibili: https://www.bilibili.com/video/BV1kM2rYrEFC

架构

browser4-cli (Rust) ──MCP over HTTP──▶ browser4-rest (Kotlin/Spring) ──▶ PulsarWebDriver (Kotlin/CDP)

• CLI（cli/browser4-cli）— 原生 Rust 二进制，通过 MCP tool call 与后端通信
• Backend（browser4-rest）— Spring Boot 服务，负责把 MCP 工具请求分发给浏览器驱动
• Browser driver（browser4-core/browser4-browser）— 对 Chrome DevTools Protocol 的封装
• Agent tools（browser4-agentic）— 把 MCP 工具名映射到浏览器自动化方法

📦 模块概览

🧪 测试夹具服务器（MockSite）

Browser4 自带一个轻量级 MockSite 服务器，用于提供静态 HTML 测试页和演示页。可在仓库根目录启动：

Windows： ./bin/test.ps1 mock-site -Dmock.site.port=18080 Linux/macOS： ./bin/test.sh mock-site -Dmock.site.port=18080

关键演示页面位于 http://localhost:18080/generated/。完整页面列表、环境变量、Python 回退方案和基于 Maven 的启动方式请见 MockSite。测试分类体系与标签系统请见 Test Taxonomy。

🤝 支持与社区

欢迎加入社区，获取支持、提出反馈并参与协作！

• GitHub Discussions：与开发者和用户交流
• Issue Tracker：报告 bug 或提出功能需求
• Social Media：关注项目动态和更新

欢迎贡献代码和文档！详情见 CONTRIBUTING.md。

📜 文档

完整文档位于仓库的 docs/ 目录，也可访问我们的 GitHub Pages 站点。

🔧 代理配置 - 解锁网站访问

export PROXY_ROTATION_URL=https://your-proxy-provider.com/rotation-endpoint

许可证

Apache 2.0 License。详见 LICENSE。