智能体浏览器引擎platonai/Browser4

🤖 Browser4

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

🌟 项目简介

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

✨ 核心能力

* 🤖 Agent Browser — 通过 Rust CLI、MCP 与 Agent 后端，让 AI Agent 和人类都能驱动真实浏览器：导航、点击、填写、快照、批处理与循环。
* 🧬 零 Token 提取 — 用 X-SQL + CSS 选择器从实时页面或存储的 HTML 快照中确定性提取；WebMiner 机器学习聚类把 HTML 语料整理成电子表格与报告视图，全程不消耗 LLM Token。
* 🧠 混合智能 — 融合 LLM 提取、ML 聚类、X-SQL 与渐进式经验库，复用已习得的选择器与障碍处理经验。
* ⚡ 高性能架构 — 协程安全、CDP 原生，面向单机每天 10 万～20 万复杂网页访问设计，可经 swarm/crawl 横向扩展。
* 📦 企业级自动化平台 — 大规模爬取（swarm/crawl）、批处理/循环任务、有状态会话、插件、运行时 skills、浏览器扩展与 MCP-over-HTTP。
* 🛠️ 编程 Agent 内核 — 50+ 个 coding. 工具（沙箱 shell/文件系统、脚手架、校验、自开发），让 Agent 既能构建 Browser4 工件，也能开发 Browser4 本身。

快速开始

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

Read https://browser4.io/SKILL.md, install or upgrade browser4-cli for browser automation, perform the following task:

1. Open the browser in headed mode (open --headed) so the window is visible — this is a human-facing demo
2. go to amazon.com
3. search for pens to draw on whiteboards
4. compare the first 4 ones
5. write the result to a markdown file

DeepSeek Harness 集成

https://github.com/platonai/dsh-browser4

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

🧭 工具选择指南

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

如何与页面交互

需要与页面交互？
├─ 需要打开或恢复浏览器会话？→ 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 ..."

页面内容嵌在  中（支付表单、编辑器、小组件）时，使用内置的 frame 切换：frames 列出 frame 树，frame "" 把后续元素命令的作用域切到该 iframe（同源 iframe 完整支持），frame main 回到主文档——无需手写 contentDocument eval。

典型交互流程：

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
iframe 较多的页面：
browser4-cli frame "#pay-frame"
browser4-cli fill "#card-number" "4111 1111 1111 1111"
browser4-cli frame main

如何提取数据

需要从页面提取数据？
├─ 页面需要先点击、填写、滚动？→ 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 -i 3600 -- eval "..."
└─ 只是脚本里处理少量 URL？
→ for url in ...; do browser4-cli goto "$url"; ... done

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

WebMiner 会对下载下来的 HTML 文件做机器学习聚类，生成结构化电子表格和交互式报告——不消耗 LLM token，全部本地运行。 webminer 是 Browser4 CLI 的一等公民：browser4-cli webminer install + browser4-cli webminer all  即可跑完整流程，无需 PowerShell。

已经有 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 。注意： SYSTEM_DEFAULT 已废弃，Chrome ≥ 143 不支持——复用系统浏览器状态请用 attach + state-save/state-load（见 browser-state-import.md）。 |
| attach | 通过 CDP 或 Browser4 扩展附加到现有浏览器。支持 --cdp  与远程 endpoint 选项。成功附加后 CLI 会打印实际连接的浏览器（Connected browser: … / Attached to … at …），当实际浏览器与请求的 channel 不符（如请求 msedge 却连到 Chrome）时会输出 ⚠ 告警——请在驱动会话前核对。 |
| close | 关闭当前活动浏览器会话。 |
| list | 列出浏览器会话及其状态和下次打开行为。Connection 列优先显示后端上报的真实浏览器，并在 channel 冲突时标注（如 requested msedge · actual Google Chrome）。支持 --all。 |
| session-default  | 把一个命名会话设为默认未命名会话。 |
| close-all | 关闭所有会话，但不停止后端。 |
| kill-all | 强制停止后端以及 Browser4 管理的浏览器进程。 |
| stop | 优雅停止 Browser4 服务。 |
| status | 显示服务版本、端口、健康状态，以及 Web 状态面板地址（http://:8182/status）。存在活动会话时还会打印当前会话小节：Name / Session ID / Status / Connection / Next open。 |
| doctor | 运行诊断：构建信息、LLM 状态、陈旧 daemon 清理、可选修复。支持 --verbose 与 --fix。 |
| doctor log [name] | 列出、查看、tail 或 grep 后端日志文件。支持 --tail、grep 风格参数，以及 doctor log  grep 。 |
| doctor metrics [filter] | 列出、过滤或 grep 后端指标。支持 doctor metrics grep 。 |
| doctor status [--section ] [--verbose] | 在终端分层显示状态面板聚合报告：默认显示概要层，--verbose 显示完整明细，--section 钻取单个报告（health、build、runtime、llm、sessions、pulsar-sessions、swarm、url-pool、browsers、drivers、privacy、plugins、skills、metrics、logs），--json 输出机器可读 JSON。 |
| 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
browser4-cli doctor status --section skills --verbose

Web 状态面板： 在浏览器打开 http://127.0.0.1:8182/status 即可查看实时仪表盘
（健康状态、版本、JVM/运行时、LLM 配置、会话、Pulsar 会话——SDK 身份、上下文与主循环
状态、swarm——swarm 会话及任务汇总、URL 池——按优先级缓存的排队/实时/延迟数量、
浏览器与打开的标签页——每个会话的浏览器/驱动绑定与标签页数量，可点击按需加载实时标签页
明细，数据来自 GET /api/system/tabs——驱动池、插件（加载/启用状态与 SDK 兼容性）、
指标、日志文件；自动刷新，可用 ?refresh= 调整间隔）。面板数据来自聚合端点
GET /api/system/status；原有单个端点（/api/system/health、/api/system/build、
/api/doctor/llm-status、/api/doctor/metrics、/api/doctor/log-files、/api/plugins、
/api/skills）继续可用。browser4-cli plugin-list 也会报告每个已安装插件的加载/启用状态与
SDK 版本；同样的报告也可以在终端中通过 browser4-cli doctor status 分层查看。

页面截图： 打开 http://127.0.0.1:8182/pages.html 可以网格形式查看所有会话中打开的网页。
每个会话的活动页自动截图（点击截图可重新截取）；非活动页显示占位图，点击后截取展示；
SWARM 会话的所有页面仅显示占位图。截图采用异步加载——后端在后台截取（截取中返回
202 Accepted + Retry-After，完成后返回缓存的 image/png），面板不会阻塞等待截图。
由 GET /api/pages 与 GET /api/pages/{sessionId}/{guid}/screenshot.png 提供数据
（?refresh=1 强制重新截取）。

导航

| 命令 | 说明 |
|---|---|
| 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，以及 --method auto\|chars\|exec（需同时给目标 ref：auto 默认——短文本逐字符输入，长文本/多行文本对 textarea/contenteditable 通过一次 execCommand('insertText') 批量插入；chars 强制逐字符；exec 强制批量插入）。 |
| press  [ref] | 向当前焦点元素或指定目标元素发送按键。支持 --verify、--follow。 |
| select   | 选择下拉框值。支持 --verify。 |
| check  | 勾选复选框或单选框。 |
| uncheck  | 取消勾选复选框或单选框。 |
| drag   | 从一个元素拖放到另一个元素。 |
| wait [target] | 等待 selector/ref、时长、文本、URL 模式、页面加载状态或 JavaScript 表达式。支持 --timeout、--text、--url、--load、--fn。 |
| upload   [file...] | 把本地文件上传到页面的文件输入框。目标必须是 （其他元素会报错）；文件路径须能被浏览器进程读取——本地模式下即本机，且空文件/不存在的文件会被拒绝并提示；远程后端时路径在后端主机上解析。支持 --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

键盘与鼠标

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

页面检查与实时提取

| 命令 | 说明 |
|---|---|
| snapshot | 捕获可访问性树快照。支持 --boxes/--no-boxes、-i/--interactive、-u/--urls、-c/--compact、--no-compact、-d/--depth、-l/--limit、-s/--selector、--raw、--stdout、-vp/--viewport、--filename。--stdout/--raw 输出默认按 2000 行/页截断分页——截断时若 stdout 是管道会追加一行 # … output truncated: showing N of M lines … 提示，完整 footer 走 stderr；需要完整树请用 --all 或 --page-size 0，超大页面建议用 -v N/--depth/--selector/--no-boxes 约束。 |
| 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。 |
| htmlsnapshot readability [url] | 用 Readability 式启发式算法一步提取正文——无需 LLM、零 token。支持 --text-only 与分页。 |

重要规则：

- 需要 ref 和交互时用 snapshot
- 需要重复 DOM 提取时用 htmlsnapshot
- 推荐使用 htmlsnapshot query --sql @query.sql，避免 shell 转义问题
- 需要关联型列表提取时，优先使用 htmlsnapshot query，而不是多次 get all
- 需要一步提取正文（无需手写选择器）时，用 htmlsnapshot readability

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
browser4-cli htmlsnapshot readability --text-only --all

深入了解 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。支持 --wait（阻塞等待结果）和 --wait-timeout （默认 600）。 |
| 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

网络检查、HAR 录制与请求路由

查看页面实际加载了哪些网络请求（XHR/fetch、状态码、请求头、响应体），
录制可被 Chrome DevTools 导入的 HAR 1.2 归档，并对匹配的请求做路由
（mock 响应或中止）。完整指南见
skills/browser4-cli/references/network.md。

| 命令 | 说明 |
|---|---|
| network requests | 列出已跟踪的请求。支持 --filter、--type、--method、--status（200、2xx、400-499）、--clear。 |
| network request  | 单个请求的完整详情：请求/响应头、时序与响应体（按需拉取）。 |
| network har start [--content ] | 开始 HAR 录制。内容模式：none、text 或 all（二进制 base64）。 |
| network har stop [path] | 停止录制并输出 HAR JSON；给出路径时写入 .har 文件。 |
| network route  --body \|--abort | 拦截匹配的请求（mock 响应或让其失败），基于 CDP Fetch。支持 --content-type、--resource-type。 |
| network unroute [pattern] | 移除路由；不带 pattern 时完全关闭拦截。 |

browser4-cli network requests --filter api --status 2xx
browser4-cli network har start --content text
browser4-cli network har stop ./capture.har
browser4-cli network route "/api/users" --body '{"users":[]}' --content-type application/json

用于规模化处理的 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（规范任务类型，含 publish_post），以及 --facts ——把复盘式知识（selectors / interaction_hints / known_blockers / anti_patterns，camelCase 或 snake_case 键均可）合并进 (domain, intent) 的 facts 条目；当该条目为 VERIFIED（不可变）时合并会被拒绝。 |
| 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 不会展示。

| 命令 | 说明 |
|---|---|
| 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 25+（Eclipse Temurin）、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 工具名映射到浏览器自动化方法
- 编程内核（browser4-coding）— 轻依赖 agent 工具箱（沙箱 shell/文件系统、脚手架、校验、自身开发工具），见下文

📦 模块概览

| 模块 | 说明 |
|---|---|
| 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-coding | 编程内核——沙箱 shell/fs、工件脚手架与校验、自身开发工具（47 个 coding. 工具） |
| 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 协作助手 |

🧩 编程内核（browser4-coding）

browser4-coding 是轻依赖的编程内核：让 AI agent 既能创建 Browser4 工件，也能开发 Browser4 自身。它独立于 browser4-agentic 与 pulsar-common（仅依赖 SLF4J + Jackson + 协程），可供非 agent 宿主复用；重后端（LSP 服务器、kotlin-compiler-embeddable）仅在运行时探测，默认不加载不下载。

coding 域共 47 个工具，分四组：

| 分组 | 数量 | 要点 |
|---|---|---|
| Shell 与文件系统 | 28 | 沙箱 coding.shell（命令白名单）、快照编辑原语 + revert、diff（Myers/Patience）、仓库治理保护（coding.protect） |
| 工件创作与校验 | 6 | scaffold（plugin/skill/js/script）、scaffoldFlow（多文件开发流）、scaffoldFromExample（反陈旧活模板，目录模式 + 词干派生改名）、validate（含 repo-consistency） |
| 自身开发 | 7 | mvnBuild（结构化诊断）、ktSymbols/ktReferences/ktInheritance（零依赖 Kotlin 分析）、impact + moduleGraph（实时 pom 图谱）、devTask（AGENTS.md 流程 + 执行）、trapCheck（CDP 陷阱） |
| LSP | 4 | 按需 diagnostics/symbols/references（ts/js/py/rs，服务器缺失时优雅降级） |

通用能力 vs 项目专用：内核按"机制 vs 数据"分层——diff、沙箱、LSP 客户端、Kotlin 分析、Maven 通道与 pom 图谱扫描均为通用可移植；脚手架、校验器、ModuleMap、CdpTrapCheck 与治理默认清单编码了 Browser4 约定，复用到其他项目时需重写这一层。

- 工具全量参考与工作流：skills/browser4-coding/SKILL.md
- 开发 Browser4 自身：skills/browser4-dev/SKILL.md
- 四类工件对照示例（真实实现 vs 脚手架输出）：docs-dev/copilot/examples/
- 评估总结（P1–P7）：docs-dev/copilot/browser4-programming-support-eval.md

🧪 测试夹具服务器（MockSite）

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

Windows（pwsh —— PowerShell 7+）： ./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。

友链

omdsh-dev/dsh-data-agent - DSH Data Agent · 用对话分析数据
* ccch1mneyyy/dsh-TUI - DSH TUI · 一个美观且实用的 Claude Code 风格 TUI 插件