内容
<p align="center">
<a href="https://browxai.com"><img src="brand/browxai-glass-aurora-1024.png" width="116" alt="browxai" /></a>
</p>
<h1 align="center">browxai</h1>
<p align="center"><strong>为智能代理打造的浏览器。</strong><br/>
<a href="https://browxai.com">browxai.com</a> · <a href="brand/">品牌资源</a></p>
**为您的AI代理提供一个真正的浏览器，让它可以导航、读取和执行操作 — 通过模型上下文协议或键入TypeScript SDK。**
browxai是一个为智能代理而设计的浏览器控制服务器，而不是为人类程序员设计的。任何MCP客户端（Claude Code、Codex、Pi等）或单个TypeScript脚本都可以指向它，您的代理将获得一组紧凑、安全的工具 — 导航、查找、点击、填充、读取、截图 — 返回小型结构化结果而不是原始DOM转储。它适用于任何模型，驱动五种浏览器引擎，并在您打开之前保持危险权限关闭。
## 您的代理可以做什么
- **驱动实时网页应用。** 让编码代理`navigate`到一个页面，`find`一个控件，通过自然语言查询，`fill`表单，`click`并通过结构化的`ActionResult`验证结果 — 而无需在完整的DOM转储上烧掉令牌。
- **在身份验证会话中工作。** 打开一个`persistent`或`attached`（自带浏览器）会话，以便代理在真实的登录配置文件中操作，并可以自动化需要现有cookie的多步骤流程。
- **从脚本中提取结构化数据。** 从一个自治的TypeScript文件：`createBrowxai()` → `navigate()` → `extract({ schema })` → `close()`，与MCP路径具有相同的安全防护。
- **运行跨引擎检查。** 在Chromium、Firefox、WebKit、真正的Android Chrome或真正的Safari上驱动相同的工具表面 — 按会话选择引擎并在不仅仅是Chromium的情况下验证流程。
- **在CI中运行而不会卡住。** 在管道中启动服务器无头；每个调用都有一个硬性防卡死截止日期，因此卡住的页面永远不会挂起运行。
- **共享一个浏览器跨代理。** 运行`browxai serve --socket`并将多个SDK客户端附加到一个长期运行的服务器（一个Chromium） — 例如，一个协调代理加上一个帮助脚本。
## 为什么选择browxai
- **模型无关** — 与任何MCP客户端（Claude、Codex等）合作；不锁定在一个模型上。
- **引擎无关** — 相同的工具驱动Chromium / Firefox / WebKit / Android Chrome / Safari，每个引擎都有适合它的协议（CDP、WebDriver BiDi、safaridriver）。使用`--engine` / `BROWX_ENGINE`选择；默认为Chromium。
- **令牌高效** — `snapshot()`返回一个紧凑的可访问性树，带有稳定的元素引用，而不是DOM转储；结果有范围、分页和预算。
- **默认安全** — 功能受限的工具、源允许/阻止列表、确认钩子和每个调用的硬性截止日期。危险的表面（任意JS、完整响应体、OS剪贴板、网络模拟、附加到您的真实Chrome）关闭，直到您选择启用。
- **拥有完整的会话生命周期** — 受管理的配置文件、BYOB附件和身份验证、头部或无头会话 — 而不是包装其他人的自动化API。
## 稳定性
browxai遵循semver。公共工具表面 — 工具名称、文档化的输入/输出形状、`ActionResult`形状和默认功能集 — 已冻结并受semver管辖，因此您可以自由采用并固定您的版本。任何在默认情况下关闭的功能背后的内容都是明确的实验性内容，不受稳定性保证的保护。参见[稳定性与semver](https://browxai.com/reference/tool-reference/#stability-and-semver)策略。
## 安装
```bash
npm install -g browxai
npx playwright-core install chromium # 一次性，~150 MB
```
将其连接到MCP客户端（stdio传输）— 例如，在`.mcp.json`中：
```jsonc
{
"mcpServers": {
"browxai": { "command": "browxai" },
},
}
```
就这样 — 您的代理现在有一个浏览器。有关每个测试框架的直接设置，请参见下面的[测试框架设置](#测试框架设置)。
## SDK（编程接口）
要编写单个TypeScript脚本并独立运行它，browxai提供了一个键入的SDK。相同的工具注册表、相同的功能门控、相同的出口卫生 — 不同的传输。
```ts
import { createBrowxai } from "browxai";
const browxai = await createBrowxai(); // 进程内，单个脚本
await browxai.navigate({ url: "https://example.com" });
const { data } = await browxai.extract({
schema: { title: "string" },
});
await browxai.close();
```
三种传输：
- **进程内**（默认）— 单个Node进程；SDK在进程内驱动服务器。`close()`关闭嵌入式服务器。
- **stdio子进程**（`transport: "stdio-child"`）— 将`browxai`二进制文件作为子进程启动，并通过stdio进行MCP通信。`close()`结束子进程。
- **套接字附件**（`endpoint: "unix:///tmp/foo.sock"`）— 连接到一个长期运行的`browxai serve --socket /tmp/foo.sock`进程。多个客户端可以附加到一个服务器（例如，一个父代理和一个子脚本共享一个Chromium）。`close()`仅结束本地连接。
与MCP路径上的相同安全防护适用。扩大安全姿态的工具（`eval_js`、`network_body`、`register_secret`、`upload_file`等）**默认关闭**，只有在`createBrowxai({ capabilities })`中命名了其功能时才会出现。通过`client.callTool("eval_js", …)`调用非公开工具甚至在连接建立之前也会失败，并返回`BROWXAI_SDK_NOT_EXPOSED`错误。
## 测试框架设置
常用代理测试框架的即用设置 — MCP服务器注册加上一个可移植的“良好驱动browxai”代理技能 — 位于 **[`harness/`](harness/)**： [Claude Code](harness/adapters/claude-code/)、 [Codex](harness/adapters/codex/)、 [Pi](harness/adapters/pi/)。
## 接口
- **`snapshot`** — 紧凑的可访问性树 + DOM遍历通道；每个节点获取一个稳定的 `[ref=eN]`。
- **`find`** — 自然语言查询 → 排名候选定位器，带有 `selectorHint`、`stability`、可见矩形 `bbox` 和 `actionable` 判决。
- **操作工具** (`click` / `fill` / `navigate` / `select` / `wait_for` / …) — 每个返回一个结构化的 `ActionResult`：导航内容、结构变化、控制台/网络切片和操作后元素探测。
- **读取工具** — `text_search`、`inspect`、`console_read`、`network_read`、`ws_read`、`screenshot`.
- **会话** — 隔离的每个会话上下文（自己的cookie jar / 引用）；`persistent`、`incognito` 或 `attached`（自带）模式；MCP驱动的配置。
- **功能** — `read`、`navigation`、`action`、`human` 默认开启；`eval`、`network-body`、`clipboard`、`file-io`、`byob-attach`、`secrets`、`extensions` 等是显式开启。
完整的工具参考、安全模型和稳定性政策在 **[文档站点](https://browxai.com/)** 上。
## 为贡献者提供的说明
```bash
corepack enable && pnpm install
pnpm install-browser # 为playwright-core安装Chromium
pnpm typecheck && pnpm test
pnpm build # 构建dist/ — `browxai`二进制文件在dist/cli.js
pnpm test:keystone # 无头端到端关键测试（真实的Chromium）
pnpm docs:dev # 文档站点，本地
```
项目文档：
- [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献者工作流程 + DCO。
- [AGENTS.md](AGENTS.md) — AI测试框架贡献者的操作规则。
- [SECURITY.md](SECURITY.md) — 漏洞报告 + 披露政策。
- [MAINTAINERS.md](MAINTAINERS.md) — 维护者名单 + 责任。
- [RELEASING.md](RELEASING.md) — 发布仪式 + OIDC发布流程。
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — Contributor Covenant 采用。
## 许可证
代码为MIT — 参见 [LICENSE](LICENSE)。
**browxai 名称和徽标是 Kalebtec 的商标**，不受MIT许可证约束。 [`brand/`](brand/) 下的品牌资产是所有权利保留（参见 [`brand/LICENSE`](brand/LICENSE)`）。参见 [TRADEMARKS.md](TRADEMARKS.md) 以获取完整的品牌政策和允许的命名使用。
