# @ai-agent-forge/plugin-browser-playwright 中文文档

规范地址：https://npmcn.com/package/%40ai-agent-forge/plugin-browser-playwright/

版本：0\.88\.28
npm 元数据更新时间：2026-11-02T00:58:23.706Z
中文译文更新时间：2026-11-06T07:03:55.580Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-agent-forge/plugin-browser-playwright
原文对照：https://npmcn.com/package/%40ai-agent-forge/plugin-browser-playwright/?lang=original
项目主页：https://github.com/agent-forge/agent-forge#readme
源码仓库：https://github.com/agent-forge/agent-forge

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

- 包体积（解压后）：928 kB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- 首次发布：2026-10-07T05:25:01.154Z
- 最新版本发布：2026-11-02T00:58:23.542Z
- 近 30 天下载量：4222（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

为 Agent Forge (17 Base Playwright 工具、 浏览器 login 配置文件、 代理- forge. browser. fetch@ 1; Playwright 从未捆绑) 所建浏览器能力插件

## 安装

```sh
npm install @ai-agent-forge/plugin-browser-playwright
```

也可以使用：`pnpm add @ai-agent-forge/plugin-browser-playwright`、`yarn add @ai-agent-forge/plugin-browser-playwright`、`bun add @ai-agent-forge/plugin-browser-playwright`

## README

# @ agent-forge/plugin-浏览器-播放器

内建的 Playwright 浏览器能力插件 [福吉探员](https://github.com/agent-forge/agent-forge) ——产品单一浏览器频道. 这个 注册涵盖常见的 Playwright 操作的十七个基本工具, 预写后, 模型可以直接调用它们; 全控主机带有一个 互动面临额外注册 `browser_login` 持续注册. `browser_evaluate` 被宣布的逃生舱门 对于一切 内建工具不覆盖. `agent-forge.browser.fetch@1` 是消费者插件用来通过共享加载页面的插件到插件面 在不披露 Playwright 或存储状态的情况下命名配置 .

剧作家是 **从未捆绑**:该套件没有Playwright依赖性. 司机决定 `playwright` 连接时间从 `<agentDir>/browser-deps` 通过 `createRequire`,以及 `browser_setup` 在首次使用时安装( i)`npm install playwright --prefix <dir>`,则 `npx playwright install chromium`浏览器 `<dir>/browsers` 结束 `PLAYWRIGHT_BROWSERS_PATH`) (中文(简体) ). 找到其他浏览器工具时 Playwright 丢失, 返回一个结构化的失败, 其消息带有两个精确的安装命令加一个指针到 `browser_setup`。 。 。 .

## 工具表面

### 会话和设置

| 工具 | 参数 | 页:1 |
| --- | --- | --- |
| `browser_navigate` | `{url, waitUntil?}` | 首先打开会话. |
| `browser_login` | `{url, profile?, timeoutMs?}` | 仅限全控+交互. 打开一个带有命名配置文件的可见的铬窗口( Name`default`),允许用户签名,仅在交互确认后保存存储状态. 确认超时默认为300s(60s.600s);取消/超时/关闭不省事. |
| `browser_setup` | `{}` | 安装 Playwright + 铬到 `<agentDir>/browser-deps`;短路为 `alreadyInstalled`。 。 。 . |

### 观察(也只以只读模式登记)

| 工具 | 参数 | 页:1 |
| --- | --- | --- |
| `browser_snapshot` | `{includeDom?, includeA11y?, includeStyles?, includeScreenshot?}` | a11y的证据是 Playwright aria快照(绑定于16KiB),DOM是 `page.content()` (范围为64KiB). 屏幕截图作为图像内容块(PNG, 16MiB抓取绑定);主机的图像常态器拥有每个工具的内置预算. 证据只包含一个字节计数标记. 样式抓取被宣告 `not_supported_in_this_build`;该参数用于合同相容性。 摘要和证据还报告了最新下载的文件(如果有的话). |
| `browser_assert_postcondition` | `{condition}` - 一个条件或1.32(全部)的阵列 | Over url / 元素 / 文本 / 控制台 / 网络状态; 控制台和网络来自200入行的页面环缓冲. |
| `browser_collect_evidence` | `{kind: console|network|snapshot}` | 原始证据堆放. |
| `browser_console` | `{level?, contains?, limit?}` | 读取控制台环缓冲器. `level` 是逗号组合 `error/warning/info/debug` (单位:千美元)`info` 还匹配 Playwright 的 `log` 类型); `limit` 默认为50,上限为200。 回返 `{total, returned:[{type,text,location?,timestamp}]}`; 自动接受的对话框显示为 `type: "dialog"` 条目. |
| `browser_network` | `{containsUrl?, status?, method?, limit?}` | 读取网络环缓冲. 回返 `{total, returned:[{method,url,status,timestamp,durationMs?,sizeBytes?}]}`; 期限/大小仅在请求的时间和 `content-length` 标题可用 . |
| `browser_performance` | `{}` | 导航计时(TTFB / DOMContentLoaded / 载荷),涂料(FP/FCP),资源汇总(计数,总转移字节数,按持续时间计算最慢为5个),DOM节点计数. 唯相读取. |
| `browser_wait` | `{until: selector|navigation|networkidle|time, locator?, ms?}` | `selector` 需求 `locator` (等待可见); `time` 需求 `ms`。 。 。 . `ms` 被夹到0.30 000(非时间类型默认为30 000)。 请求返回/有效/实际等待持续时间;超时失败地图到 `browser_wait_timeout`。 。 。 . |

### 相互作用( 从未以只读模式注册)

| 工具 | 参数 | 页:1 |
| --- | --- | --- |
| `browser_locator_action` | `{locator: {kind: css|id|role|text|test-id, value, name?}, action, value?, key?, delay?}` | 行动: `click`, (中文(简体) ), `dblclick`, (中文(简体) ), `rightclick`, (中文(简体) ), `fill`, (中文(简体) ), `type`, (中文(简体) ), `press`, (中文(简体) ), `hover`, (中文(简体) ), `select`, (中文(简体) ), `check`, (中文(简体) ), `uncheck`, (中文(简体) ), `clear`, (中文(简体) ), `upload` (单位:千美元)`value` = 一个绝对路径或 JSON 系列路径,通过 `setInputFiles`, (中文(简体) ), `scroll` (单位:千美元)`value` =: `<direction>:<pixels>`,比如说. `down:500`;将元素滚动到视图中,再由像素来轮子. 返回动作后 aria- snapshot 碎片 . |
| `browser_evaluate` | `{expression, arg?}` | **逃出舱门——只有在没有内置工具覆盖操作时才使用.** 运行 `page.evaluate`; JSON 序列化结果以 64KiB 为界(`undefined` 序列化为 `undefined`; 30s 壁点超时离开页面侧脚本自行完成. 评估期间发射的对讲机是自动接收的. |
| `browser_drag` | `{from, to, steps?}` | Hover source – 鼠标下来 – 踩出 `mouse.move` 以几何方式向目标中心移动(Locator.hover没有 `steps` 选项,所以精细的移动是无轮鼠标移动; `steps` 默认为 8, 夹住 1. 100 ) — 鼠标上方 。 目标在按钮下行时故意不被徘徊. 当目标没有边框时跳过精制动作. |
| `browser_mouse` | `{action: move|click|dblclick|rightclick|wheel, x, y, deltaX?, deltaY?, button?}` | 不需要元素的原始视图-坐标动作; `wheel` 是基本的页面滚动原始. |
| `browser_press_key` | `{key, delay?}` | 页面级别 `page.keyboard.press` 带有 Playwright 密钥名称( X)`Control+a`, (中文(简体) ), `Enter`, (中文(简体) ), `Meta+c`) (中文(简体) ). |
| `browser_tabs` | `{action: list|new|switch|close, index?, url?}` | 司机跟踪的标签集; `switch` 为所有后续工具重新指定当前页面. |
| `browser_storage` | `{action: get-cookies|set-cookie|clear-cookies|get-local|set-local|clear-local, name?, value?, domain?, path?, expires?, key?}` | 饼干通过上下文(`set-cookie` 需要名称/值/域;通过页面的本地Storage. |
| `browser_viewport` | `{action: set|get, width?, height?}` | `set` 将尺寸夹入320.7680,并在进行夹时报告所要求的值. |

所有结果都是 `PluginResultV1`结构化的有效载荷(主机/网络条目、性能指标、评价结果、储存和制表状态) 以证据摘要中的JSON文本(64KiB)为界。 仅读主机模式精确登记7个观察工具(`snapshot`, (中文(简体) ), `assert_postcondition`, (中文(简体) ), `collect_evidence`, (中文(简体) ), `console`, (中文(简体) ), `network`, (中文(简体) ), `performance`, (中文(简体) ), `wait`); 更改浏览器或磁盘状态的每件事从不 在那里注册.

## 共享浏览器配置和 `browser.fetch@1`

`browser_login` 写入 `<agentDir>/browser/profiles/<name>/storage-state.json` (0600) 并保留上一个 抓取为 `storage-state.backup.json`。配置锁(`.lock`)通过关闭浏览器从快照加载中保持;a 第二写者返回 `browser_profile_busy` 10s等待之后。 10s等待。 快照被封顶在10 MiB,并通过一个 同名目录临时文件 + fsync + rename.

`agent-forge.browser.fetch@1` (按 `provides`)是只读取的检索面:它加载命名快照 打开无头铬并返回 `{version, finalUrl, title?, text, truncated}` 最多为 16K个人物. 它永远不会返回 cookie, localStorage, 或认证文件 。 能力也以只读模式提供; `browser_login` 没有。 共享配置是便利边界,而不是证书-同位素边界——通用 `browser_storage` 和页面脚本仍然可以读取已装入上下文暴露的内容.

## 内置对话框和下载策略

没有专用工具;驱动程序将两种政策应用到每一个打开的页面:

-   **对话框** 自动接受(`dialog.accept()`)并记录在控制台环缓冲器中作为 `[dialog] <type>: <message>` 输入,所以 `browser_console` 控制台的后置条件可以观察它们.
-   **下载** 保存为 `<agentDir>/browser-deps/downloads/` (目录创建为懒惰),最近的文件名附于 `browser_snapshot` 结果。 当不知道代理代理Dir时,文件名仍然被报告,但文件没有被保存.

## 注射表面

`createBrowserCapabilityFactoryV1(runtime)` 接受任意 `BrowserRuntimeV1 = {connect(): Promise<BrowserDriverV1>; setup?(); login?(); fetch?()}` - 测试和中介 主机注射假药. 运出运行时间, `PlaywrightBrowserRuntimeV1`辅助 `agentDir`编号 :`browserDepsDir`编号 :`headless`,加上确定性 `spawnSync`编号 :`resolvePlaywright`编号 :`loadPlaywright`编号 :`ensureDir` 用于安装器的接合,懒惰模块负载,以及下载目录. 默认 导出 `dist/entry.js` 由主持人作曲 `api.host.agentDir`。 。 。 .

## 真实浏览器测试

决定性的套房从不下载或产出任何东西. 真实的端到端会话( 安装 - > 导航实例. com - > swatch - > 点击 - > 控制台) - > 性能 - > 评估 - > 按键 - > viewport - > close) 运行时仅使用 `AGENT_FORGE_BROWSER_REAL_TEST=1` 和网络访问;它使用丢弃 代理目录,然后删除它.

## 发展

```sh
npm install --ignore-scripts        # repo root, creates the workspace symlink
npm run build                       # plugins/browser-playwright (tsgo)
npm test                            # vitest; the entry fidelity test requires `npm run build` first
```

## 常见问题

### @ai-agent-forge/plugin-browser-playwright 是什么？

为 Agent Forge \(17 Base Playwright 工具、 浏览器 login 配置文件、 代理- forge\. browser\. fetch@ 1; Playwright 从未捆绑\) 所建浏览器能力插件

### 如何安装 @ai-agent-forge/plugin-browser-playwright？

在项目目录运行 npm install @ai-agent-forge/plugin-browser-playwright，或使用 pnpm add / yarn add / bun add。

### @ai-agent-forge/plugin-browser-playwright 支持 TypeScript 吗？

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

### @ai-agent-forge/plugin-browser-playwright 支持 ESM 还是 CommonJS？

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

### @ai-agent-forge/plugin-browser-playwright 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-agent-forge/plugin-browser-playwright 可以商用吗？

@ai-agent-forge/plugin-browser-playwright 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ai-agent-forge/plugin-browser-playwright 的下载量有多少？

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

### @ai-agent-forge/plugin-browser-playwright 还在维护吗？

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