# @agentproto/driver-browser 中文文档

规范地址：https://npmcn.com/package/%40agentproto/driver-browser/

版本：0\.4\.1
npm 元数据更新时间：2026-11-01T13:57:47.803Z
中文译文更新时间：2026-11-06T04:02:32.754Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentproto/driver-browser
原文对照：https://npmcn.com/package/%40agentproto/driver-browser/?lang=original
项目主页：https://agentproto.sh/
源码仓库：https://github.com/agentproto/ts

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：281 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-09-29T17:18:54.844Z
- 最新版本发布：2026-11-01T13:57:47.464Z
- 近 30 天下载量：5204（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

浏览器提供者工具包:定义浏览器(manifest + launch),浏览器Instance和浏览器Driver端口,一个提供者注册,一个提供者- kit列表,以及一个打出的能力门(浏览器:不支持).

## 安装

```sh
npm install @agentproto/driver-browser
```

也可以使用：`pnpm add @agentproto/driver-browser`、`yarn add @agentproto/driver-browser`、`bun add @agentproto/driver-browser`

## README

# @ agentproto/ 司机浏览器

浏览器提供者工具包. 它给每个浏览器后端( 一个隐形的 Firefox) 在 REST 后方, Playwright 管理的 Chromium, 系统 Chrome, 主机浏览器 一个形状,所以一个主机可以 列表,发射,附加和门 同样的方式.

Spec: BROWSER AIP(职称) `BROWSER.md`, (中文(简体) ), `agentbrowser/v1`页:1 [活性剂/活性剂#53](https://github.com/agentproto/agentproto/pull/53)。 。 。 . AIP号码是临时的,直到编辑指定为止.

## 盒子里装的是什么

| 块 | 这是什么 |
| --- | --- |
| `defineBrowser` | 验证一个清单( zod)并返回被冻结的 `BrowserProvider`。在 `createDoctype`一样 `defineDriver`纯粹的建筑,没有I/O. |
| `BrowserProvider` | 显示字段外加 `launch(opts, ctx)`中,一个同位素保证返回 a `BrowserInstance`。 。 。 . |
| `BrowserInstance` | `id`, (中文(简体) ), `endpoints {rest?, cdp?}`, (中文(简体) ), `pid?`, (中文(简体) ), `wasAlreadyRunning`, (中文(简体) ), `health()`, (中文(简体) ), `attach(opts)`, (中文(简体) ), `stop()`。 。 。 . |
| `BrowserDriver` | 页面和标签控制端口(navigate, valice, 点击, 填充, 截图, 网络, 生 CDP), 其选项和结果形状有zod schemas. |
| `BrowserCapabilities` | 页面级别旗帜( N)`canFullPageScreenshot`,.)和进程级旗帜(`stealth`, (中文(简体) ), `headless`, (中文(简体) ), `cdp`, (中文(简体) ), `downloads`, (中文(简体) ), `recording`(中文(简体) ). 所有默认关闭. |
| `createBrowserRegistry` | 注册、查询和列出提供者。 重复的ID抛出. |
| `makeBrowserProviderLister` | 一个标准 `@agentproto/provider-kit` 列表在注册处. |
| `assertCapability`, (中文(简体) ), `BrowserUnsupportedError` | 能力门. |

## 定义提供者

```ts
import { defineBrowser } from "@agentproto/driver-browser"

export const camofox = defineBrowser({
  id: "camofox",
  name: "Camoufox (stealth Firefox)",
  description: "Stealth Firefox behind a local REST service.",
  version: "1.0.0",
  transport: "http", // sdk | http | cli
  location: "local", // local | remote (remote = a third party sees session data)
  capabilities: { stealth: true, downloads: true, headless: true, persistentProfile: true },
  async launch(opts, ctx) {
    // Return the running instance if one is healthy: wasAlreadyRunning: true.
    // Otherwise start one.
  },
})
```

## 能力门

需要提供商缺乏的能力的呼叫会因打出错误而失败, 非不透明运输故障 :

```ts
import { assertToolSupported, isBrowserUnsupportedError } from "@agentproto/driver-browser"

try {
  assertToolSupported(provider.capabilities, "browser.list_requests", provider.id)
} catch (err) {
  if (isBrowserUnsupportedError(err)) {
    err.code // "browser:unsupported" (stable)
    err.capability // "cdp"
    err.message // '"browser.list_requests" needs the "cdp" capability, which is not supported on provider "camofox"'
  }
}
```

`BrowserUnsupportedError` 扩展 AIP-14 `ToolError`这样 `toToolResult` 设置 `code` 财务报告和审定财务报表 `cause: { capability }` 输入标准信封.

## 卫生

`BrowserInstance.health()` 返回时 `{ ok, reason?, lifecycle? }`。 。 。 . `lifecycle` 包含监管主机从服务读取的字段 `/health`,所有数据 可选( 服务器报告) `null` 以它尚未确定的地方发誓 `bootId`, (中文(简体) ), `startedAt`, (中文(简体) ), `browserState` (单位:千美元)`launching | running | idle | crash-looping`, (中文(简体) ), `launchedAt`, (中文(简体) ), `lastLaunchMs`, (中文(简体) ), `lastRestartReason`。 。 。 .

## 主管

`createBrowserSupervisor` 在健康环下经营一个供应商。 时间和 进程访问被注入( e)`clock`, (中文(简体) ), `orphanSweep.listProcesses/kill`),这样 测试不需要真正的睡眠或过程.

```ts
import { createBrowserSupervisor, browserInstanceMarker } from "@agentproto/driver-browser"

const supervisor = createBrowserSupervisor({
  provider,
  launchOptions: { label: "work" },
  healthIntervalMs: 10_000,
  launchBudgetMs: 120_000, // a slow launch inside the budget is not a failure
  crashLoop: { maxFailures: 3, windowMs: 300_000 },
  orphanSweep: { marker: browserInstanceMarker("work") },
  onBackendRestart: ({ previousBootId, bootId }) => {},
})
await supervisor.start()
```

-   **发射-发射探测器.** `maxFailures` 失败 `windowMs` (发射完毕) `launchBudgetMs` 将状态翻转为 `crash-looping`不再试图发射,由 `start()` 或由 健康循环,直到明确 `restart()`,它清除了计数器.
-   **健康环.** 读取 `BrowserInstance.health()`更改 `bootId` 表示 后端重新启动并起火 `onBackendRestart`。 。 。 . `browserState: "crash-looping"` (即使是在503与 `ok: false`)是国家,主管 报告,不是"下":重启是没有帮助的. `launching` 不是一个 失败。 一个平地 `ok: false` 页:1 `unhealthyThreshold` 连续探测器 引发重启.
-   **孤儿扫地.** `sweepOrphans` 仅指向命令的进程 携带精确的标记符 (`--agentproto-browser=<key>`),从a 已注入进程列表 。 它从不按进程名匹配,也从不信号 目前的进程。 发射时将标记传递到浏览器的 argv.
-   **`KeepAlivePolicy`。 。 。 .** 烂摊子的收割者政策 页:1 `keepAlive` 和闲置的浏览器下拉闸 (单位:千美元)`shouldShutdownIdleBrowser`在任何保留Alive会话时拒绝 已存在.

## 合规包

```ts
import { createFakeBrowserProvider, runConformance } from "@agentproto/driver-browser"

const { provider } = createFakeBrowserProvider()
const report = await runConformance(provider, { levels: ["core", "interaction", "network"] })
report.ok // false if any check failed
report.failed // ["core/launch-idempotent", ...]
```

级别 : `core` (明显,例状,一能发射,健康, 导航,同位素站,远程提供者报告没有本地的pid), `interaction` (评价、DOM、截图、点击/填写固定图), `network` (需求数) `cdp`, (中文(简体) ), `download` (需求数) `downloads`和 `profile` (需求数) `persistentProfile`) (中文(简体) ). 提供者不声明其能力的级别 报告为 `skipped` 输入 `browser:unsupported`,从来没有作为一个 失败 `network` 级别仍然检查缺失的能力失败 与 `browser:unsupported` 而不是一个不透明的错误。 这个 `download` 职等 只检查申报的能力是否与工具门一致 现在, 因为驱动端口没有下载动词; 添加提供者检查 `extraChecks`。 。 。 .

对于 `location: "remote"` 供应商通过 `launch: { baseUrl }`装具船 `startFakeRemoteBrowserServer()` (当地http,随机端口)和 `createFakeRemoteBrowserProvider()` 因此,可以进行远程合规 没有第三方. `createFakeBrowserProvider({ faults })` 正在建设 故意被破坏的变体.

## 范围

这套包装有模型、主管和符合要求的套装. 混凝土提供者和运行时工具接线在其它包中直播.

许可证: Apache -2.0.

## 常见问题

### @agentproto/driver-browser 是什么？

浏览器提供者工具包:定义浏览器\(manifest \+ launch\),浏览器Instance和浏览器Driver端口,一个提供者注册,一个提供者- kit列表,以及一个打出的能力门\(浏览器:不支持\)\.

### 如何安装 @agentproto/driver-browser？

在项目目录运行 npm install @agentproto/driver-browser，或使用 pnpm add / yarn add / bun add。

### @agentproto/driver-browser 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentproto/driver-browser 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agentproto/driver-browser 可以商用吗？

@agentproto/driver-browser 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agentproto/driver-browser 的下载量有多少？

根据 npm 官方下载统计，@agentproto/driver-browser 在 2026/10/05 – 2026/11/03 这 30 天内被下载 5,204 次，日均约 173 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentproto/driver-browser 还在维护吗？

最新版本 0\.4\.1 发布于 2026/11/01（4 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/09/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。