# @framers/agentos-ext-browser-automation 中文文档

规范地址：https://npmcn.com/package/%40framers/agentos-ext-browser-automation/

版本：0\.3\.3
npm 元数据更新时间：2026-11-11T08:03:40.107Z
中文译文更新时间：2026-11-15T12:18:27.615Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40framers/agentos-ext-browser-automation
原文对照：https://npmcn.com/package/%40framers/agentos-ext-browser-automation/?lang=original
项目主页：https://github.com/framerslab/agentos-extensions/tree/master/registry/curated/system/browser-automation#readme
源码仓库：https://github.com/framerslab/agentos-extensions

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

- 包体积（解压后）：385 kB，152 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@framers/agentos \>=0\.10\.40
- 首次发布：2026-05-02T11:35:16.141Z
- 最新版本发布：2026-11-11T08:03:39.724Z
- 近 30 天下载量：20419（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

AgentOS的完整浏览器自动化扩展——通过Playwright为代理机提供自主的网络导航,DOM交互,截图,captcha解析等功能.

## 安装

```sh
npm install @framers/agentos-ext-browser-automation
```

也可以使用：`pnpm add @framers/agentos-ext-browser-automation`、`yarn add @framers/agentos-ext-browser-automation`、`bun add @framers/agentos-ext-browser-automation`

## README

# @ framers/ agentos-ext-browser-automation (英语)

AgentOS 代理器的浏览器自动化,分两个独立道:

-   **发射道** - 10个Playwright支持的工具(`browserNavigate`, (中文(简体) ), `browserClick`, (中文(简体) ), `browserFill`, (中文(简体) ), `browserScreenshot`, (中文(简体) ), `browserExtract`, (中文(简体) ), `browserWait`, (中文(简体) ), `browserScroll`, (中文(简体) ), `browserSnapshot`, (中文(简体) ), `browserEvaluate`, (中文(简体) ), `browserSession`)驱动一个浏览器,包的启动和拥有。 可选 CAPTCHA 解析和代理旋转 .
-   **附加道** - 7个 `browser_attach_*` 工具加驱动用户的持久守护进程 **已运行、已登录** 浏览器. 仅选入( O)`attach.expectedIdentity` a. 组织事项 永远不要发射浏览器 .

## 附加守护进程

一个长寿的守护进程为运行中的克罗姆举行一个生-CDP会话. 每个消费者——CLI脚本、申报运行、代理任务——都通过文件序列IPC驱动会议 `~/.wunderland/attach/ipc/`。守护进程是唯一触及网络的进程,因此macOS每次守护进程寿命一次提高本地网络权限,而不是每次代理进程一次.

```
callers (CLI / scripts / agent tools)  ── files only ──►  AttachDaemon (one process)
                                                            └─ raw CDP ws://localhost:<port>  ──►  your Chrome
```

需要节点22或更新( 传输为内置) `WebSocket`; 守护进程退出时带有关于旧运行时间的可操作消息. Chrome 必须运行与 `--remote-debugging-port=9222`。 。 。 .

### 硬合同

-   在任何失败下从不发射,退出,重启,或信号克罗姆.
-   创建一个代理标签, 并且只能关闭该标签; 每个其它标签都未受影响( 由真实浏览器 e2e 提供) .
-   CDP 主机为 `localhost` (Chrome的DNS绑定后卫拒绝) `127.0.0.1`) (中文(简体) ).
-   1个守护进程(原子文件锁),1个索赔人(租赁+索赔),系列行动.
-   代理工具表面没有 eval . `eval` 仅存在于JS客户端的用户编译的脚本上.
-   页面文本以 `untrusted: true` ——把它当作数据,从不当作指示.
-   导航是政策检查后守护进程侧: https 或 `about:blank`,没有包含证书的 URL,重定向重验证.
-   没有饼干,存储,或证书导出;诊断被校正.
-   客户端从不重发已死守护进程(再发回回环是一次许可-即时风暴). 自动启动, 当明确启用时, 精确尝试一次 .

### 行动

`ping`, (中文(简体) ), `status`, (中文(简体) ), `claim`, (中文(简体) ), `goto {url, settle?}`, (中文(简体) ), `read {selector?, maxChars?}`, (中文(简体) ), `extract {fields?}`, (中文(简体) ), `screenshot {path, fullPage?}`, (中文(简体) ), `eval {expression, timeoutMs?}` (用户道), `release`, (中文(简体) ), `control {action}`, (中文(简体) ), `quit`。命令是每个文件一个(`cmd-<id>.json` → `resp-<id>.json`,原子写入-当时的重命名,字符串标识; `status.json` 心跳每个循环滴答.

### 用这个

程序化( E)`/attach/daemon` 子路径 :

```ts
import { AttachDaemonClient, runAttachScript } from '@framers/agentos-ext-browser-automation/attach/daemon';

const client = new AttachDaemonClient({ client: 'my-script' });
await client.claim();
await client.goto('https://example.com/', { settle: 2000 });
const { text } = await client.read({ maxChars: 4000 });
await client.release();
```

声明计划( 无控制流, 无 eval ):

```yaml
name: crawl
claim: { ttlMs: 600000 }
steps:
  - { op: goto, url: "https://example.com/list", settle: 2500 }
  - { op: read, out: listing }
  - { op: extract, fields: { items: "ul li" }, out: items }
```

从wunderland CLI: `wunderland attach start | status | stop | run <file.mjs|file.yaml|file.json>`代理代表团通过使附加工具与 `transport: 'cdp'` (单位:千美元)`WUNDERLAND_ATTACH_TRANSPORT=cdp`) (中文(简体) ).

### 截图

`browser_attach_screenshot` (和 `AttachController.screenshot`将代理标签的PNG写入证据目录中的新文件, `~/.wunderland/attach-evidence` 除非 `WUNDERLAND_ATTACH_EVIDENCE_DIR` (或包头) `attach.evidenceDir` 选项,对于进程内控制器)命名另一个。 它需要 CDP 运输: JXA 运输没有像素访问, 拒绝使用 `UNSUPPORTED_OP`。 。 。 .

-   `path` 相对于证据目录,或其中的绝对路径。 一个离开目录,通过链接的路径,或者一个存在文件的名字在被捕获之前被拒绝,而会话保持准备状态. 文件以旗帜创建 `wx`,所以没有文件被替换,结果给出了写入的路径.
-   证据目录对会话所运行的用户是保密的. 它和其中的目录是用0700模式制作的;另一个用户或组可以写入的目录被拒绝,另一个用户可以更改的目录下的一个也是如此(粘着的目录,例如: `/tmp` - 没事 在抓取页面之前检查目录,并在创建文件时再次检查目录,图像只有在被检查的目录中找到新文件后才被写入.
-   截图保存会话直至其文件被写入: 进程内控制器拒绝一个 `goto` 或者说 `read` 同时调用,守护进程会一次执行一个命令.
-   `fullPage` 抓取可滚动页面,每侧切入16,384 CSS像素.
-   工具有副作用(它写一个文件),所以一个否定-侧效应会把它作为政策门.

### 环境

| 变量 | 含义 |
| --- | --- |
| `WUNDERLAND_ATTACH_IDENTITY` | 要求。 配置文件身份守护进程在要求前必须先进行校验(例如您的账户电子邮件; 与身份 - probe tab 的标题/ url 元数据相匹配) . |
| `WUNDERLAND_ATTACH_TRANSPORT` | `jxa` (正在处理中, macOS AppleScript) 或 `cdp` (demon -routed). |
| `WUNDERLAND_ATTACH_PROFILE_ROOT` | Chrome profile 根控住 `DevToolsActivePort`。 。 。 . |
| `WUNDERLAND_ATTACH_PROBE_URL` | 身份检测 URL 子串( 默认) `mail.google.com`) (中文(简体) ). |
| `WUNDERLAND_ATTACH_HOSTS` | 以逗号分隔的 https 主机允许访问列表 . |
| `WUNDERLAND_ATTACH_LEASE` | 租赁文件路径覆盖 . |
| `WUNDERLAND_ATTACH_IPC_DIR` | IPC 目录覆盖( 默认) `~/.wunderland/attach/ipc`) (中文(简体) ). |
| `WUNDERLAND_ATTACH_PID_FILE` | 守护进程 pidfile 覆盖( 默认) `~/.wunderland/attach/daemon.pid`) (中文(简体) ). |
| `WUNDERLAND_ATTACH_AUTOSTART` | `1`编号 :`true`: 在守护进程倒下时允许一次自动启动尝试 . |
| `WUNDERLAND_ATTACH_DRYRUN` | `1`编号 :`true`:在不接触浏览器的情况下模拟导航/读取. |
| `WUNDERLAND_ATTACH_DEADLINE_MS` | 操作截止时间(默认为4500). |
| `WUNDERLAND_ATTACH_EVIDENCE_DIR` | 守护进程写截图的地方( 默认) `~/.wunderland/attach-evidence`) (中文(简体) ). 只有守护进程用户才能写出目录 . |

## 释放

新版本发表于 [架设层/剂-外延](https://github.com/framerslab/agentos-extensions) 由 GitHub Actions 通过 npm 信任的出版, 并附有出处声明 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @framers/agentos-ext-browser-automation 是什么？

AgentOS的完整浏览器自动化扩展——通过Playwright为代理机提供自主的网络导航,DOM交互,截图,captcha解析等功能\.

### 如何安装 @framers/agentos-ext-browser-automation？

在项目目录运行 npm install @framers/agentos-ext-browser-automation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@framers/agentos（\>=0\.10\.40）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @framers/agentos-ext-browser-automation 支持 TypeScript 吗？

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

### @framers/agentos-ext-browser-automation 支持 ESM 还是 CommonJS？

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

### @framers/agentos-ext-browser-automation 需要什么版本的 Node\.js？

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

### @framers/agentos-ext-browser-automation 可以商用吗？

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

### @framers/agentos-ext-browser-automation 的下载量有多少？

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

### @framers/agentos-ext-browser-automation 还在维护吗？

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