dsh-browser4

---

English | 简体中文 | 中国镜像

目录

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

🌟 项目简介

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

🌟 简介

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

✨ 核心能力

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

快速开始

把下面这段说明粘贴给你喜欢的 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. 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

🧭 工具选择指南

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

如何与页面交互

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

---

📦 安装

手动安装是可选的，因为 AI 智能体在阅读 SKILL 后通常可以自行完成安装。

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

npm install -g browser4-cli
browser4-cli install

或者用单条命令直接引导安装原生二进制。脚本随后会自动安装 Browser4 后端（运行时包）——全新机器执行 browser4-cli install，已安装后端则执行 browser4-cli upgrade 升级到最新版（可用 --skip-backend 跳过此步骤）：

Windows（PowerShell）：

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

Linux / macOS（bash）：

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

💡 面向人的 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.jpg
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，后续再查询状态和结果。

全局选项

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

标志	说明
-h, --help [command|category]	显示顶层帮助、分类帮助或某个命令的详细帮助
--help-json	输出机器可读的命令参考 JSON
-v, --version	打印 CLI 版本
-s, --session <name>	使用命名会话，而不是默认会话
--server <url>	覆盖 Browser4 服务端 URL
--timeout <seconds>	覆盖当前命令的 HTTP 超时时间
--proxy <url>	安装 / 下载运行时使用的代理
--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 <path>、--profile-mode <DEFAULT|SYSTEM_DEFAULT|SEQUENTIAL|TEMPORARY>、--interact-level <FASTEST|FAST|DEFAULT>。
attach	通过 CDP 或 Browser4 扩展附加到现有浏览器。支持 --cdp <url|port|channel> 与远程 endpoint 选项。
close	关闭当前活动浏览器会话。
list	列出浏览器会话及其状态和下次打开行为。支持 --all。
session-default <name>	把一个命名会话设为默认未命名会话。
close-all	关闭所有会话，但不停止后端。
kill-all	强制停止后端以及 Browser4 管理的浏览器进程。
stop	优雅停止 Browser4 服务。
status	显示服务版本、端口和健康状态。
doctor	运行诊断：构建信息、LLM 状态、陈旧 daemon 清理、可选修复。支持 --verbose 与 --fix。
doctor log [name]	列出、查看、tail 或 grep 后端日志文件。支持 --tail、grep 风格参数，以及 doctor log <name> grep <pattern>。
doctor metrics [filter]	列出、过滤或 grep 后端指标。支持 doctor metrics grep <pattern>。
delete-data	删除会话数据。
install	安装 Browser4 运行时 bundle。支持 --tag <version> 与 --force。
upgrade	升级 CLI / 运行时 bundle。支持 --tag <version> 与 --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>	导航到 URL；如果需要会自动打开 / 重连会话。
go-back	在浏览器历史中后退。
go-forward	在浏览器历史中前进。
reload	刷新当前页面。

核心交互

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

命令	说明
click <ref> [button]	点击元素。支持 --modifiers、--follow、--auto-dismiss-dialogs。
dblclick <ref> [button]	双击元素。支持 --modifiers、--follow、--auto-dismiss-dialogs。
hover <ref>	悬停到元素上。
fill <ref> <text>	清空并填写可编辑字段。支持 --submit、--verify。
type <text> [ref]	向当前焦点元素或指定目标元素输入文本。支持 --submit、--verify、--focus、--interactable-timeout。
press <key> [ref]	向当前焦点元素或指定目标元素发送按键。支持 --verify、--follow。
select <ref> <value>	选择下拉框值。支持 --verify。
check <ref>	勾选复选框或单选框。
uncheck <ref>	取消勾选复选框或单选框。
drag <startRef> <endRef>	从一个元素拖放到另一个元素。
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 <key>	按下并保持某个键。
keyup <key>	释放某个已按住的键。
mousemove <x> <y>	把鼠标移动到页面 / 屏幕坐标。
mousedown [button]	按下鼠标按键。
mouseup [button]	释放鼠标按键。
mousewheel <dx> <dy>	用滚轮 delta 进行滚动。
scroll <direction> <pixels>	按 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 <pattern>	用 grep 风格参数搜索保存的 / 当前 snapshot YAML，例如 -i、-v、-c、-l、-F、-w、-A、-B、-C、--selector、--page、--page-size、--all。
snapshot list	列出保存的快照文件及其时间戳、大小。
snapshot clean	删除旧快照文件。支持 --dry-run。
get <mode> <selector> [name]	从实时页面元素中提取 text、html、box、styles、property 或 attr。
eval [expression] [ref]	在页面或某元素上执行 JavaScript。支持 --file、--stdin、--base64、--await、--wait-selector、--json。
console [min-level]	列出浏览器控制台消息。支持 --clear。
cdp <method>	发送任意 Chrome DevTools Protocol 命令。支持 --json <params>。
generate-locator <ref>	为 snapshot ref 或已有选择器生成最佳 CSS selector。
resize <width> <height>	调整浏览器窗口尺寸。
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 <field> [selector] [name]	从已存储快照中提取第一个匹配项的 text、html 或 attr。
htmlsnapshot get all <field> [selector] [name]	从已存储快照中提取全部匹配值。支持 --offset 和 --limit。
htmlsnapshot query [url]	运行 X-SQL。支持 --sql <query|@file>、--sql-stdin、--sql-base64、结果分页和提取导向输出选项。
htmlsnapshot export	把已存储 HTML 导出到文件。支持位置参数文件路径或 --file <path>，以及 --clean。
htmlsnapshot summary	生成压缩版 Web Page Summary Index（WPSI）。
htmlsnapshot grep <pattern>	用 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 <guid>。
tab-select <index>	按索引切换标签页；支持 --guid <guid>。

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

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

AI 提取、chat 与自主 agent 任务

这些命令需要 LLM key。

命令	说明
extract <instruction>	从当前页面提取结构化数据。支持 --schema <json|@file>、--filename、--raw、--stdout。
summarize [instruction]	总结当前页面内容。支持 --selector、--filename、--raw、--stdout。
chat <message>	发送纯 AI chat 请求，不自动追加浏览器上下文。
chat-result <id>	获取异步 chat 任务结果。
agent run <task>	提交一个自主浏览器任务，并立即获得任务 ID。
agent status <id>	查询运行中的任务状态。
agent result <id>	获取已完成任务的结果。
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 <url>	对一个或多个已加载页面提交 X-SQL 提取任务。支持 --sql、--seed-file、--deadline、--expires、--refresh。
swarm status <id>	查询 swarm 任务状态。
swarm result <id>	获取已完成的 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 <id>	查询 crawl 任务状态。
crawl result <id>	获取 crawl 结果。
crawl cancel <id>	取消运行中的 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 <name>	打印某个 skill 的 SKILL.md。支持 --full 与 --all。
skills path [name]	打印内置 skill 目录路径。
skills unpack [dest]	将内置 skill 文件解包到目录。

已安装运行时 skills

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

渐进式经验记忆

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

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

插件

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

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

高级 / 当前隐藏命令

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

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

超时环境变量

变量	默认值	用途
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/<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 工具名映射到浏览器自动化方法

📦 模块概览

模块	说明
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。