platonai/dsh-browser4

🤖 Browser4

License: APACHE2

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

目录
- 🤖 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
├─ 想先看当前哪些元素可点击 / 可输入？→ snapshot -i --boxes
├─ 需要点击按钮、链接、复选框或菜单项？→ click
├─ 需要填写表单并替换已有文本？→ fill  ""
├─ 需要像真人一样继续输入，或者发送 Enter / Tab？→ type / press
├─ 需要从下拉框中选择值？→ select
├─ 需要悬停、拖拽、滚动，或直接使用鼠标？→ hover / drag / scroll / mouse*
├─ 需要在下一步前等待页面稳定？
│  ├─ 等元素出现？→ wait
│  ├─ 等文本出现？→ 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 ""
├─ 静态页面，获取某字段所有匹配项？→ htmlsnapshot get all text ""
├─ 静态页面，需要相关联的多字段（每个条目的标题+价格+链接）？
│  → 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  --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 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 库进行单机聚类（。
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，后续再查询状态和结果。

全局选项

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

| 标志 | 说明 |
|---|---|
| -h, --help [command\|category] | 显示顶层帮助、分类帮助或某个命令的详细帮助 |
| --help-json | 输出机器可读的命令参考 JSON |
| -v, --version | 打印 CLI 版本 |
| -s, --session  | 使用命名会话，而不是默认会话 |
| --server  | 覆盖 Browser4 服务端 URL |
| --timeout  | 覆盖当前命令的 HTTP 超时时间 |
| --proxy  | 安装 / 下载运行时使用的代理 |
| --json | 只输出机器可读 JSON |
| --pretty | 美化 JSON 输出 |
| -q, --quiet | 隐藏正常的人类可读输出 |
| -tip, --show-tip | 每条命令后在 stderr 输出相关提示 |

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

元素 ref 与 CSS 选择器

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

snapshot 与 htmlsnapshot

| 工具 | 适用场景 | 输入模型 | 输出模型 |
|---|---|---|---|
| snapshot | 点击、输入、查找可交互元素 | 实时可访问性树 | e15 这类 ref |
| htmlsnapshot | DOM 检查、CSS 提取、X-SQL | 已存储的 HTML 快照 | CSS 选择器和查询结果 |

LLM 配置

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

| 提供商 | 环境变量 |
|---|---|
| DeepSeek | DEEPSEEK_API_KEY |
| OpenRouter | OPENROUTER_API_KEY, OPENROUTER_MODEL_NAME, OPENROUTER_BASE_URL |
| Volcengine | VOLCENGINE_API_KEY, VOLCENGINE_MODEL_NAME, VOLCENGINE_BASE_URL |
| OpenAI-compatible | OPENAI_API_KEY, OPENAI_MODEL_NAME, OPENAI_BASE_URL |
| Aliyun Qwen | OPENAI_API_KEY, OPENAI_MODEL_NAME, OPENAI_BASE_URL |

export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx

完整命令参考

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

| 命令 | 说明 |
|---|---|
| open [url] | 打开浏览器会话，或重新连接已有会话。默认为无头模式。 支持 --headed（可视窗口）、--headless、--profile 、--profile-mode 、--interact-level 。 |
| attach | 通过 CDP 或 Browser4 扩展附加到现有浏览器。支持 --cdp  与远程 endpoint 选项。 |
| close | 关闭当前活动浏览器会话。 |
| list | 列出浏览器会话及其状态和下次打开行为。支持 --all。 |
| session-default  | 把一个命名会话设为默认未命名会话。 |
| close-all | 关闭所有会话，但不停止后端。 |
| kill-all | 强制停止后端以及 Browser4 管理的浏览器进程。 |
| stop | 优雅停止 Browser4 服务。 |
| status | 显示服务版本、端口和健康状态。 |
| doctor | 运行诊断：构建信息、LLM 状态、陈旧 daemon 清理、可选修复。支持 --verbose 与 --fix。 |
| doctor log [name] | 列出、查看、tail 或 grep 后端日志文件。支持 --tail、grep 风格参数，以及 doctor log  grep 。 |
| doctor metrics [filter] | 列出、过滤或 grep 后端指标。支持 doctor metrics grep 。 |
| delete-data | 删除会话数据。 |
| install | 安装 Browser4 运行时 bundle。支持 --tag  与 --force。 |
| upgrade | 升级 CLI / 运行时 bundle。支持 --tag  与 --force。 |
| uninstall | 删除全局安装和运行时数据。支持 -y、--yes、--dry-run。 |

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

导航

| 命令 | 说明 |
|---|---|
| goto  | 导航到 URL；如果需要会自动打开 / 重连会话。 |
| go-back | 在浏览器历史中后退。 |
| go-forward | 在浏览器历史中前进。 |
| reload | 刷新当前页面。 |

核心交互

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

| 命令 | 说明 |
|---|---|
| click  [button] | 点击元素。支持 --modifiers、--follow、--auto-dismiss-dialogs。 |
| dblclick  [button] | 双击元素。支持 --modifiers、--follow、--auto-dismiss-dialogs。 |
| hover  | 悬停到元素上。 |
| fill   | 清空并填写可编辑字段。支持 --submit、--verify。 |
| type  [ref] | 向当前焦点元素或指定目标元素输入文本。支持 --submit、--verify、--focus、--interactable-timeout。 |
| press  [ref] | 向当前焦点元素或指定目标元素发送按键。支持 --verify、--follow。 |
| select   | 选择下拉框值。支持 --verify。 |
| check  | 勾选复选框或单选框。 |
| uncheck  | 取消勾选复选框或单选框。 |
| drag   | 从一个元素拖放到另一个元素。 |
| wait [target] | 等待 selector/ref、时长、文本、URL 模式、页面加载状态或 JavaScript 表达式。支持 --timeout、--text、--url、--load、--fn。 |

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

键盘与鼠标

| 命令 | 说明 |
|---|---|
| keydown  | 按下并保持某个键。 |
| keyup  | 释放某个已按住的键。 |
| mousemove   | 把鼠标移动到页面 / 屏幕坐标。 |
| mousedown [button] | 按下鼠标按键。 |
| mouseup [button] | 释放鼠标按键。 |
| mousewheel   | 用滚轮 delta 进行滚动。 |
| scroll   | 按 up、down、left 或 right 滚动页面。 |

页面检查与实时提取

| 命令 | 说明 |
|---|---|
| snapshot | 捕获可访问性树快照。支持 --boxes、-i/--interactive、-u/--urls、-c/--compact、--no-compact、-d/--depth、-l/--limit、-s/--selector、--raw、--stdout、-vp/--viewport、--filename。 |
| snapshot grep  | 用 grep 风格参数搜索保存的 / 当前 snapshot YAML，例如 -i、-v、-c、-l、-F、-w、-A、-B、-C、--selector、--page、--page-size、--all。 |
| snapshot list | 列出保存的快照文件及其时间戳、大小。 |
| snapshot clean | 删除旧快照文件。支持 --dry-run。 |
| get   [name] | 从实时页面元素中提取 text、html、box、styles、property 或 attr。 |
| eval [expression] [ref] | 在页面或某元素上执行 JavaScript。支持 --file、--stdin、--base64、--await、--wait-selector、--json。 |
| console [min-level] | 列出浏览器控制台消息。支持 --clear。 |
| cdp  | 发送任意 Chrome DevTools Protocol 命令。支持 --json 。 |
| generate-locator  | 为 snapshot ref 或已有选择器生成最佳 CSS selector。 |
| resize   | 调整浏览器窗口尺寸。 |
| dialog-accept [prompt] | 接受 alert / confirm / prompt 对话框，并可填写 prompt 内容。 |
| dialog-dismiss | 关闭 alert / confirm / prompt 对话框。 |

get 支持的 mode：

| 模式 | 含义 | 示例 |
|---|---|---|
| text | 可见文本 | browser4-cli get text ".price" |
| html | inner HTML | browser4-cli get html "#main" |
| box | 边界框 | browser4-cli get box "#hero" |
| styles | 计算后的样式 | browser4-cli get styles e9 |
| property | DOM 属性值 | browser4-cli get property "input" value |
| attr | HTML attribute 值 | browser4-cli get attr "a" href |

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 结构化提取工作流的核心。

| 命令 | 说明 |
|---|---|
| htmlsnapshot | htmlsnapshot capture 的简写。 |
| htmlsnapshot capture | 捕获并存储静态 HTML 快照，同时返回页面和交互元素的元数据。 |
| htmlsnapshot get  [selector] [name] | 从已存储快照中提取第一个匹配项的 text、html 或 attr。 |
| htmlsnapshot get all  [selector] [name] | 从已存储快照中提取全部匹配值。支持 --offset 和 --limit。 |
| htmlsnapshot query [url] | 运行 X-SQL。支持 --sql 、--sql-stdin、--sql-base64、结果分页和提取导向输出选项。 |
| htmlsnapshot export | 把已存储 HTML 导出到文件。支持位置参数文件路径或 --file ，以及 --clean。 |
| htmlsnapshot summary | 生成压缩版 Web Page Summary Index（WPSI）。 |
| htmlsnapshot grep  | 用 grep 风格参数搜索已存储 HTML。 |
| htmlsnapshot inspect [selector] | 发现重复 DOM 模式和候选选择器。支持 --max、--depth、--stdin、--selector-base64。 |

重要规则：

- 需要 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

| 命令 | 说明 |
|---|---|
| screenshot [ref] | 对页面或元素截图。支持 --filename、--full-page、--viewport。 |
| pdf | 将当前页面保存为 PDF。支持 --filename。 |

标签页

| 命令 | 说明 |
|---|---|
| tab-list | 列出打开的标签页及其索引、标题、URL；配合 --json 可获得完整 GUID。 |
| tab-new [url] | 打开新标签页，可选同时导航到 URL。 |
| tab-close [index] | 按索引关闭标签页；支持 --guid 。 |
| tab-select  | 按索引切换标签页；支持 --guid 。 |

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

| 命令 | 说明 |
|---|---|
| state-save [filename] | 把 cookies 和 localStorage 保存为 JSON 文件。 |
| state-load  | 从 JSON 文件恢复 cookies 和 localStorage。 |
| cookie-list | 列出 cookies。支持 --domain、--path。 |
| cookie-get  | 按名称获取 cookie。 |
| cookie-set   | 设置 cookie。支持 --domain、--path、--expires、--httpOnly、--secure、--sameSite。 |
| cookie-delete  | 按名称删除 cookie。支持 --domain、--path。 |
| cookie-clear | 清空所有 cookies。 |
| localstorage-list | 列出 localStorage 项。 |
| localstorage-get  | 读取 localStorage 键。 |
| localstorage-set   | 设置 localStorage 键。 |
| localstorage-delete  | 删除 localStorage 键。 |
| localstorage-clear | 清空 localStorage。 |
| sessionstorage-list | 列出 sessionStorage 项。 |
| sessionstorage-get  | 读取 sessionStorage 键。 |
| sessionstorage-set   | 设置 sessionStorage 键。 |
| sessionstorage-delete  | 删除 sessionStorage 键。 |
| sessionstorage-clear | 清空 sessionStorage。 |
| webdb export  | 把 Browser4 web database 中的页面导出到本地目录。 |
| webdb normalize  | 把 URL 规范化为 web database key 格式。 |

AI 提取、chat 与自主 agent 任务

这些命令需要 LLM key。

| 命令 | 说明 |
|---|---|
| extract  | 从当前页面提取结构化数据。支持 --schema 、--filename、--raw、--stdout。 |
| summarize [instruction] | 总结当前页面内容。支持 --selector、--filename、--raw、--stdout。 |
| chat  | 发送纯 AI chat 请求，不自动追加浏览器上下文。 |
| chat-result  | 获取异步 chat 任务结果。 |
| agent run  | 提交一个自主浏览器任务，并立即获得任务 ID。 |
| agent status  | 查询运行中的任务状态。 |
| agent result  | 获取已完成任务的结果。 |
| agent list | 列出已跟踪的 agent 任务及其状态。 |

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 [command...] | 在一次调用中执行多条命令。支持 --bail 与从 stdin 读取命令数组的 --json。 |
| loop [task] | 周期性运行一个任务。支持 --name、-i/--interval、-n/--count、-t/--timeout、--shell、--list、--pause、--resume、--pause-all、--resume-all、--stop、--stop-all、--status、--history、--keep-state。 |

可用于 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 的别名使用。

| 命令 | 说明 |
|---|---|
| swarm create | 创建并行抓取会话。支持 --profile-mode、--max-open-tabs、--max-browser-contexts、--display-mode。 |
| swarm submit [url] | 提交 URL 或 X-SQL payload 作为作业。支持 --seed-file、--sql、--deadline、--expires、--refresh、--parse。 |
| swarm query  | 对一个或多个已加载页面提交 X-SQL 提取任务。支持 --sql、--seed-file、--deadline、--expires、--refresh。 |
| swarm status  | 查询 swarm 任务状态。 |
| swarm result  | 获取已完成的 swarm 任务结果。 |
| swarm list | 列出已跟踪的 swarm 任务。 |
| swarm close | 关闭 swarm 会话并释放浏览器资源。 |
| crawl [url] | 从 URL 或 seed file 开始抓取。支持 --seed-file、--sql、--sql-stdin、--sql-base64、--format、--output、-d/--depth、-ol/--out-link-selector、-olp/--out-link-pattern、-tl/--top-links、-a/--args、--refresh、--parse、--expires、-p/--priority、--page-load-timeout、--ignore-url-query、--no-norm、--readonly、-bg/--background。 |
| crawl status  | 查询 crawl 任务状态。 |
| crawl result  | 获取 crawl 结果。 |
| crawl cancel  | 取消运行中的 crawl 任务。 |
| crawl clear | 删除处于终态的 crawl 任务；支持扩展清理选项。 |
| crawl list | 列出已跟踪的 crawl 任务。 |

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 | 列出内置 skill 名称。 |
| skills list | 与 skills 等价。 |
| skills get  | 打印某个 skill 的 SKILL.md。支持 --full 与 --all。 |
| skills path [name] | 打印内置 skill 目录路径。 |
| skills unpack [dest] | 将内置 skill 文件解包到目录。 |

已安装运行时 skills

| 命令 | 说明 |
|---|---|
| skill-list | 列出已安装的后端 skill。 |
| skill-info  | 显示 skill 详细元数据。 |
| skill-install  | 从包含 SKILL.md 的目录安装一个 skill。支持 --overwrite。 |
| skill-uninstall  | 按 ID 删除 skill。 |
| skill-reload  | 从源目录重新加载 skill。 |

渐进式经验记忆

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

| 命令 | 说明 |
|---|---|
| experience save   | 保存任务执行轨迹。支持 --outcome、--intent、--task-type。 |
| experience query  | 查询某个 URL / 域名已知的选择器、阻塞因素和提示。支持 --intent。 |
| experience list | 列出已存储的经验条目。支持 --filter、--intent-filter、--page、--page-size。 |
| experience deep-learn   | 对已存储轨迹做更深入分析。支持 --force。 |

插件

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

| 命令 | 说明 |
|---|---|
| plugin list | 列出已安装插件。 |
| plugin info  | 显示插件详情。 |
| plugin install  | 从本地 JAR 文件安装插件。支持 --replace。 |
| plugin remove  | 删除插件。支持 -y、--yes。 |

高级 / 当前隐藏命令

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

| 命令 | 说明 |
|---|---|
| upload   | 向文件输入框上传一个或多个文件。 |
| act  | 实验性自然语言动作翻译器：把自然语言转换成浏览器命令并立即执行。 |

超时环境变量

| 变量 | 默认值 | 用途 |
|---|---:|---|
| BROWSER4_CLI_HTTP_TIMEOUT_SECS | 30 | 大多数命令 |
| BROWSER4_CLI_INPUT_TIMEOUT_SECS | 90 | type、fill 及其他较慢的输入流程 |
| BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS | 120 | goto、reload、go-back、go-forward |

export BROWSER4_CLI_INPUT_TIMEOUT_SECS=180
export BROWSER4_CLI_NAVIGATION_TIMEOUT_SECS=300

状态持久化

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

- 默认会话：~/.browser4/cli-state.json
- 命名会话：~/.browser4/sessions/.json
- loops：~/.browser4/loops/.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 --

或全局安装：
cd cli/browser4-cli && cargo install --path .

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

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

🎬 YouTube:
Watch the video

📺 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 工具名映射到浏览器自动化方法

📦 模块概览

| 模块 | 说明 |
|---|---|
| cli/browser4-cli | Rust CLI——快速、原生的浏览器自动化二进制 |
| skills/browser4-cli | AI 智能体 skill 定义（SKILL.md） |
| browser4-core | 核心引擎：会话、调度、DOM、浏览器控制 |
| browser4-dependencies | BOM 与依赖版本对齐 |
| browser4-tools | 运维工具与启动辅助 |
| browser4-agentic | AI agent、MCP 集成、skill 注册 |
| browser4-agent-tools | 高层 agent 工具：抓取、爬取、有状态页面交互 |
| browser4-rest | Spring Boot REST 层与命令端点 |
| browser4-apps/browser4-standalone | 产品打包——统一启动器（target/Browser4.jar） |
| examples/browser4-examples | 可运行示例与演示 |
| browser4-tests | E2E、集成与场景测试套件 |
| cdp-protocol | Chrome DevTools Protocol JSON 定义 |
| coworker/ | 内置 AI 协作助手 |

🧪 测试夹具服务器（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 站点。

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

把环境变量 PROXY_ROTATION_URL 设置为代理服务商提供的轮换 URL：

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

每次访问这个轮换 URL 时，它都应返回一个或多个新的代理 IP。
如果你需要这种 URL，请联系你的代理服务商。

许可证

Apache 2.0 License。详见 LICENSE。