# @agentproto/adapter-browser-chrome 中文文档

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

版本：0\.8\.1
npm 元数据更新时间：2026-11-01T13:57:34.140Z
中文译文更新时间：2026-11-06T05:01:24.467Z
软件包许可：Apache-2\.0

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

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

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

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

## 中文简介

用于代理Proto的系统Chrome供应商 : `chrome` a. 在新的专用配置文件目录上发射已安装的Chrome,在CDP上加载,并注入已授予的饼干(绝不是默认配置文件); `chrome-live` (或再利用,热)

## 安装

```sh
npm install @agentproto/adapter-browser-chrome
```

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

## README

# @ agentproto/ 适应器- 浏览器- 色调

两个浏览器提供者 `@agentproto/driver-browser`,两个驱动过生 发展政策委员会:

-   `chrome`机器上安装了克罗姆, **启动** 在新鲜的 专用配置目录( 绝不是您的配置) .
-   `chrome-live`(单位:千美元) **专用头色相** 以自身为特征 默认目录( 不点击同意) —— 附加在您自己运行的 Chrome 通过其远程调试切换只在明确询问时发生;见 [铬活度](https://npmcn.com/package/%40agentproto/adapter-browser-chrome/#readme-chrome-live-your-running-chrome)。 。 。 .

```ts
import { chrome } from "@agentproto/adapter-browser-chrome"

const instance = await chrome.launch({ profile: "work" }, { log: console.log })
const driver = await instance.attach({ initialUrl: "https://example.com" })
await driver.close()
await instance.stop()
```

使用 `createChromeProvider({ cookieSource })` 可以在附加时间注入饼干.

## 查找克罗姆

`launch({ executablePath })` 而提供者的配置获胜。 否则 `resolveChrome` 读取 `CHROME_EXECUTABLE_PATH`,这必须是一条绝对的道路 到已有文件(一个错误的值抛出而不是倒回),然后 a. OS的标准安装路径(在macOS和Windows上的Chrome、Edge和Brave); 众所周知的道路和 `PATH` 名称在 Linux 上)。 当什么都没有发现时, `launch()` 失败时出现名称错误 `CHROME_EXECUTABLE_PATH`。 。 。 .

## F11: 永远不要默认的 Chrome 配置

Chrome 136+ 拒绝 `--remote-debugging-port` 默认用户数据目录,所以 这个供物从不依附它,也不以它为攻击对象 或关闭您使用的克罗姆。 每次发射都会产生一个新的克洛姆过程 一个新的专用目录 `~/.agentproto/browser/chrome/profiles/<name>` (覆盖根以 `AGENTPROTO_HOME` 或者说 `dataDir`),与 `--remote-debugging-port=0`。该端口从 `DevToolsActivePort`。 。 。 .

键入错误拒绝这些请求 `browser:profile-refused` (单位:千美元)`BrowserProfileRefusedError`从 `@agentproto/driver-browser`:

-   (单位:千美元) `userDataDir`,或一个 `profile` 作为路径,即或坐落在 此OS 上的 Chrome、 Chromium、 Brave 或 Edge 默认目录( 已解析 ) ;
-   (单位:千美元) `profile` 命名一个真实的 Chrome 配置文件 (`Default`, (中文(简体) ), `Profile 1`(......) ; (......);
-   `fullProfile: true`,或一个 `--full-profile` 参数,直到赠款模式 土地;
-   额外 `args` 该套 `--user-data-dir` 或者说 `--remote-debugging-*`。 。 。 .

在产卵前再次检查了核子 测试使用二进制根 并申明发射的方格 携带新鲜的目录, 从来没有默认的目录.

## 饼干

捐赠的饼干通过CDP注射 `Network.setCookies` 当一个驱动器 随附. 他们来自 `attach({ sessionPayload })` 并且从提供者 `cookieSource` 参数(`BrowserCookieSource`赠款模式提供 真实源在后行道。 只有饼干计数被记录,从不值.

## 铬活:运行中的克罗姆

`chrome-live` 给予代理人 **专用头色相**,单独 默认情况下,即立即启动(或重新使用,热度), 零同意点击 并且从来没有拨打自己的克罗姆。 随附 给您已经使用的 Chrome (您登录的配置文件, 这样代理可以工作 仅发生在 **明确询问**: 有钉子 `wsUrl`编号 :`port` (发射选择、提供者配置或 `CHROME_LIVE_*` ,或 `attachIntent: true`它永远不会触动你的标签, 它永远不会关闭你的 克罗姆.

```ts
import { chromeLive } from "@agentproto/adapter-browser-chrome"

// Default: a dedicated Chrome, launched or reused hot — no consent wait.
const instance = await chromeLive.launch({}, { log: console.log })
const driver = await instance.attach({ initialUrl: "https://mail.example.com" })
await driver.evaluate({ expression: "document.title", awaitPromise: false, returnByValue: true, maxResultBytes: 10_000 })
await instance.stop() // closes the agent's tabs and its socket, nothing else

// Explicit ask: attach to the user's own, real Chrome instead.
const mine = await chromeLive.launch({ attachIntent: true }, { log: console.log }) // Chrome shows "Allow"
```

在守护者中 `chrome-live` 浏览器适配器 : `start_browser { adapter: "chrome-live" }` (以默认方式指定;通过) `attachIntent: true` 在启动选项中,以要求用户自己的Chrome代替.

### 附加在您自己的 Chrome( 仅明确询问)

1.  使用 Chrome 144 或以后打开 `chrome://inspect/#remote-debugging`。 。 。 .
2.  打开远程调试切换器 。 克罗姆听好了 `127.0.0.1:9222`。 。 。 .
3.  发射方式 `attachIntent: true` (或被钉住) `wsUrl`编号 :`port`) (中文(简体) ). 颜色显示 询问是否允许调试连接的对话框:单击 **允许**。 。 。 . 供养者等待 `consentTimeoutMs` (默认60s).

将切换器再次关闭以切断所有连接. 无 `attachIntent` (或 针头,切口根本没人拨——献出Chrome先来 和附加步骤不运行.

### 从附着路径倒回专用克罗姆

何时 `attachIntent`/一个被钉住的终点要求附着,这是不可能的, 提供者 **自动发射一个专注、有头的Chrome** 并连接到它 相反——不允许点击:

-   **切换时没有颜色** (单位:千美元)`browser:remote-debugging-off`什么都没有听 9222年:推出一款专用克罗姆.
-   **从未同意** (单位:千美元)`browser:consent-timeout`: 不允许在内部单击 `consentTimeoutMs`,或者Chrome拒绝连接 : 提供者停止 等待和发射 专用克罗姆 而不是离开代理卡住.

推出的Chrome在自由端口上聆听并使用 **持续** 剖面图目录, `$CHROME_LIVE_LAUNCH_DATA_DIR` (默认) `~/.agentproto/browser/chrome/live`, (中文(简体) ), 不停地跑来跑去 所以它保持温暖。 它在发现模式( uuid) 中连接 `webSocketDebuggerUrl` 从 `GET /json/version`),其短片记录在 举个例子. `stop()` 杀人 **仅限** 那孩子(剪刀、签名、优雅) SIGKILLL)——只有附具的会话没有子嗣及其子嗣 `stop()` 永远 信号你的克洛姆.

被钉住 `wsUrl`编号 :`port` (发射选择,配置,或嵌入) 禁用此倒计时—— 它被从字面上取出,所以一个故障会浮出水面而不是取而代之 献给克罗姆的. `autoLaunch: false` 禁用全球专用发射 (attach成为唯一的路径,包括作为默认).

### 配置

| 设置 | 默认 |  |
| --- | --- | --- |
| `createChromeLiveProvider({ port })` 编号 : `CHROME_LIVE_PORT` | `9222` | 127.0.0.1上开口 |
| `createChromeLiveProvider({ wsUrl })` 编号 : `CHROME_LIVE_WS_URL` | `ws://127.0.0.1:<port>/devtools/browser` | 完整浏览器 Websocket URL; 击败端口 |
| `consentTimeoutMs` | `60000` | 等待允许点击多久 |
| `discover` | `true` | 读取 `GET /json/version` 并与广告连接 `webSocketDebuggerUrl` (Chrome 155+每个发射浏览器UUID). `false` 是一个遗留的逃生舱门 对于一个155前切换 `/json/version` 无法到达, 但固定的端点仍然回答 |
| `autoLaunch` | `true` | 愿提供商能够发射一个专用的克罗姆(默认,或作为附加路径倒置) |
| `preferDedicated` | `true` | `false` 恢复此提供者实例每次调用时的旧附件首默认值 |
| `launch({ attachIntent })` | `false` | 逐个呼叫明确要求附加到用户自己的Chrome上,而不是专用默认 |
| `createChromeLiveProvider({ cookieSource })` | 无 | 注入给定的 cookie 到 **专用** 每一次的颜色 `attach()` (永远不要进入你自己的);同样 `BrowserCookieSource` 形状为 `chrome`。通过发射过滤 `domains`; cookie 值从未被记录, 仅是一个计数 |
| `CHROME_LIVE_LAUNCH_DATA_DIR` | `~/.agentproto/browser/chrome/live` | 自动发射 Chrome 的 profile dir |

`launch({ wsUrl, port })` 胜过提供者配置, 它胜过 环境。 默认( E)`discover: true`提供者读取 `GET /json/version` 财务报告和审定财务报表 连接到广告 `webSocketDebuggerUrl` - Chrome 155+暴露出一个 每个发射浏览器的UUID(`ws://127.0.0.1:<port>/devtools/browser/<uuid>`(三); id- 无固定 URL 回答 404. 关闭的端口大声失败 `browser:remote-debugging-off` 而不是拨打已死终点; 空出或 非杰森语 `/json/version` (a pre-155 toggle)回落到固定的id-less URL. `discover: false` 跳过探测器并连接到 `ws://127.0.0.1:<port>/devtools/browser`。 。 。 . `DevToolsActivePort` 在克罗梅 profile 不读取( MacOS 不让其他应用程序读取); 端口到来 从配置.

### 一个联系,一个同意

每一个新的网络口袋都让克罗姆再次请求同意,所以提供商保留 **一个** 每个 Websocket URL 连接 . `launch()` 被纪念在 URL, 包括飞行中的连接:同时发射共用一个插座 电话 `launch()` 再次( Bureau 在每个控制工具附件上都这样做) 返回 现场案例 `wasAlreadyRunning: true`。 。 。 . `health()` 运行 `Browser.getVersion` 超越现有的套接字,绝不打开新的套接字; `check()` 是一个裸露的端口TCP探测器,也从未打开过网口. 新的连接仅在前一个关闭或停止后打开, 然后日志上说克罗姆会再次请求同意.

### 代理商自己的窗口

第一个 `attach()` 打开专用窗口 `Target.createTarget { url, newWindow: true }`中打开标签 同一个窗口,从没有第二个窗口。 协议上没有窗口参数 `Target.createTarget` (对照 `devtools-protocol` 定义 重播: 仅 `newWindow`, (中文(简体) ), `background`, (中文(简体) ), `left`编号 :`top`编号 :`width`编号 :`height` 编辑 ),并在最后一个活动窗口中打开新的标签。 因此,提供者先运行 `Target.activateTarget` 在自己的标签上,创建标签,并检查它 与 `Browser.getWindowForTarget`中。如果另一个窗口聚焦于 标签落到别处, 标签立刻关闭, 并重新检查附件, 然后以明显的错误失败。 它永远不会留在你的标签。 一旦你关闭 代理窗口,下一个附件打开一个新的附件 。 CDP 没有标签组 API,所以 代理标签不分组 .

### 文件输入和额外的代理标签

`uploadFileOwnedTarget(selector, paths)` 将本地文件附加到一个 `<input type=file>` 在自有标签上: 它首先探测选择器 (单位:千美元)`no <input type=file> matches selector …` 当它不匹配的时候 以 `DOM.querySelector` 并把它通过 `DOM.setFileInputFiles` 与 ABSOLUTE 路径 — 相同的机制演示工具 使用,一个饲料而不是写作。 第二个自有标签就是 `newTabOwnedTarget(url)` (总是在代理窗口中有一个 FRESH 标签——相同) 激活- 锁定 - 创建目标 - `getWindowForTarget` 流动为第一个 选项卡——永不重复使用),以及 `listOwnedTabs()` 返回每个标签代理 拥有它居住的窗户。 MCP预测是 `browser_upload_file` (路径限制在守护进程上传) 允许列表在此之上, `browser_new_tab` 财务报告和审定财务报表 `browser_list_tabs`。 。 。 .

### 播放代理标签

`chrome-live` 是唯一可以播放的提供者 (单位:千美元)`driver.capabilities.canScreencast`) (中文(简体) ). 播报员骑着CDP `Page.startScreencast` 在驱动程序自己的平面中, 在标签上 开业的供应商——因此,它与一家企业一样处于相同的所有权规则之内 截图( e)`Page.*` 只有,从不设外国分页,从不设桌面).

```ts
const { targetId, index } = await instance.screencastStart({ everyNthFrame: 1, quality: 80 })
const latest = await instance.screencastFrame() // null until the first frame lands
const { frameCount, frames } = await instance.screencastStop()
```

选项镜像 `Page.startScreencast`数字 : `format` (默认) `jpeg`, (中文(简体) ), `quality` (1-100), (中文(简体) ), `everyNthFrame`, (中文(简体) ), `maxWidth`, (中文(简体) ), `maxHeight`框架为 已规范为 `{ data /* base64 */, format, timestampMs, index, width?, height? }` 并缓冲在有界环上(2000帧),所以后站 可以把每个缓冲框交给一个录制编码器. `screencastStart` 重用已有的代理标签并打开新标签 否则,并且是每个司机的专有能力。 屏幕显示器继续使用 连接条目,所以秒 `launch()` 手柄,用于重用 已运行的连接( n)`wasAlreadyRunning`达到相同 边框.

守护进程预测与 MCP 工具相同的实例方法 `browser_screencast_start` 编号 : `browser_screencast_frame` 编号 : `browser_screencast_stop` 和 HTTP 路线 `GET /sessions/<id>/screencast` (HTML浏览器), `.mjpg` (MJPEG流传) 财务报告和审定财务报表 `.jpg` (最晚帧.

### 安全保障

-   **永远别碰你的克洛姆.** 当它附着时, `stop()` 发送 `Target.closeTarget` 对于此提供者创建的目标,然后关闭其 拥有 websocket; 它从未发送 `Browser.close`复用后返回的手柄 `launch()` 只关闭它打开的标签并离开连接到 第一次发射 当它代替 **自动发射** 专一的克罗姆, `stop()` 只用活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活 从来没有表示过.
-   **不要碰你的标签.** 供应商只知道目标身份 创建。 它从不打电话 `Target.getTargets` 绝不是附在目标上 没有创建。 穿过 `driver.send` (代理人的 `cdp_send`),整个 `Target.*` 财务报告和审定财务报表 `Browser.*` 域被拒绝,饼干和存储也被拒绝 写作.
-   **饼干只读到你的档案.** 当与克罗姆你 已运行, 该配置文件中没有写入任何信息 : no `Network.setCookies`, (中文(简体) ), 被授予- cookie 的有效载荷被忽略, 司机报告 `canCookies: false`. 阅读(`Network.getCookies`) 工作情况。 打开 自动发射 **专用** 选择一个主机配置 `cookieSource` (或 a 个) session-pailload cookie 列表)可能通过 `Network.setCookies` 附加时间 —— 代理仍然无法写入 cookie 结束 `cdp_send`你自己的克洛姆也一样.
-   **宣布的能力:** `cdp`, (中文(简体) ), `isUserVisible`, (中文(简体) ), `canMultiTarget` 页:1 代理窗口, `headed`, (中文(简体) ), `canScreencast` (见 [屏幕广播](https://npmcn.com/package/%40agentproto/adapter-browser-chrome/#readme-screencast-of-the-agents-own-tab)) (中文(简体) ). 没有 `headless`没有 `persistentProfile`。 。 。 .

**这不是F11的绕道.** 上面的F11警卫保持原样: 提供商曾经在 **默认** 简介。 当切换是 关了, `chrome-live` 自动发射其上的专用Chrome **拥有** 持续 profile dir( 绝不是默认的 profile ) , 并且没有写到您的 profile; 它 否则只使用你打开的连接 在克罗姆自己的UI, 你可以随时剪接.

### 错误

每个错误都是 `ToolError` 拥有稳定 `code`,导出为常数 :

| 代码 | 常数 | 何时 |
| --- | --- | --- |
| `browser:remote-debugging-off` | `BROWSER_REMOTE_DEBUGGING_OFF_CODE` | 端口上听不到(ECONNREFUSED). 消息:"chrome://inspect/#remote-debugging上允许远程调试" |
| `browser:consent-timeout` | `BROWSER_CONSENT_TIMEOUT_CODE` | 不允许在内部单击 `consentTimeoutMs`,或者Chrome拒绝连接 |
| `browser:disconnected` | `BROWSER_DISCONNECTED_CODE` | 关闭 Chrome 或网络套接字掉入任务中 |

一滴后,下一个 `launch()` 重新连接( 使用新的同意对话框) 和 仍然知道它以前打开的标签,所以 `stop()` 可以关闭它们.

## 已推迟

尚未在此包中: 扩展处理, 多显示的 UI , 标题 收购抛光,和全能访问。 这个 `cookieSource` 缝合在这里 (两个提供方);赠款模式 _用品_ 一个来源生活在 `@agentproto/browser-profiles`。 。 。 .

## 测试

套房驱动一个分接字Chrome(一个能说最小的 CDP 的节点脚本),所以不 需要真正的浏览器. `chrome-live` 运行与进程内假冒的 toggle-mode Chrome 已设置用户标签并标记任何命令地址 一个提供者没有创建的目标。 一个可选的真二元烟跑 `runConformance` 何时 `CHROME_SMOKE_BIN` 名称为 Chrome 或 Chromium 可执行文件.

## 常见问题

### @agentproto/adapter-browser-chrome 是什么？

用于代理Proto的系统Chrome供应商 : chrome a\. 在新的专用配置文件目录上发射已安装的Chrome,在CDP上加载,并注入已授予的饼干\(绝不是默认配置文件\); chrome-live \(或再利用,热\)

### 如何安装 @agentproto/adapter-browser-chrome？

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

### @agentproto/adapter-browser-chrome 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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