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

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

版本：1\.1\.5
npm 元数据更新时间：2026-11-11T08:01:37.078Z
中文译文更新时间：2026-11-15T12:21:14.305Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：128 kB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：4 个
- peer 依赖：@framers/agentos \>=0\.10\.40
- 首次发布：2026-03-15T19:10:55.570Z
- 最新版本发布：2026-11-11T08:01:36.611Z
- 近 30 天下载量：20292（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

隐形浏览器扩展名 — 傀儡- 外加被保护站点的反检测

## 安装

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

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

## README

# 隐形浏览器

这个包提供了代理浏览器的导航,刮取,点击,打字,截图和DOM快照工具. 用这个 `puppeteer-extra`, (中文(简体) ), `puppeteer-extra-plugin-stealth`, (中文(简体) ), `puppeteer-core` 财务报告和审定财务报表 `cheerio` 带有本地 Chrome 可执行文件.

## 安装

```bash
npm install @framers/agentos-ext-stealth-browser
```

同伴依赖 : `@framers/agentos` 有范围 `>=0.10.40`。 。 。 .

## 使用量

```ts
import { AgentOS } from '@framers/agentos';

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-stealth-browser',
        options: {
          headless: true,
          timeout: 30000,
          viewport: { width: 1920, height: 1080 },
        },
      },
    ],
  },
});
```

## 配置

| 选项 | 秘密编号 | 环境变量 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| `headless` | 无 | 无 | 没有 | 在工厂中未安装;发射开始 |
| `timeout` | 无 | 无 | 没有 | 无法通过工厂; 传递给 Puppeteer |
| `userAgent` | 无 | 无 | 没有 | 从内置池随机选择 |
| `viewport` (对象 `width` 财务报告和审定财务报表 `height`(中文(简体) ) | 无 | 无 | 没有 | 在厂房中取消设置; 没有浏览器覆盖 |
| `executablePath` | 无 | 无 | 没有 | OS 特定色调路径 |
| `enableEvasions` | 无 | 无 | 没有 | 启用, 除非 `false` |
| `priority` | 无 | 无 | 没有 | `50`; falsy 值也使用此默认值 |
| A. 背景情况 `logger` | 无 | 无 | 没有 | 未设置 |
| A. 背景情况 `onActivate` | 无 | 无 | 没有 | 未设置 |
| A. 背景情况 `onDeactivate` | 无 | 无 | 没有 | 未设置 |

设定 `headless`, (中文(简体) ), `timeout` 财务报告和审定财务报表 `viewport` 明确使用示例中的值。 工厂通过未定义的属性来覆盖服务构建者的默认. 使用这些平面选项名称, 而不是显示的点化配置名称 .

`logger.info` 接收生命周期信息。 上下文回调在激活和停用时运行;在引用回调前关闭浏览器.

## 工具

| 工具 | 它会做什么 |
| --- | --- |
| `stealth_navigate` | 具有反检测功能的导航并返回页面文本、链接和可选的 HTML. |
| `stealth_scrape` | 使用 CSS 选择器从当前页面中提取内容. |
| `stealth_click` | 等待元素显出并点击. |
| `stealth_type` | 键盘键入输入字段,并有默认键盘延迟. |
| `stealth_screenshot` | 抓取当前页面或所选元素. |
| `stealth_snapshot` | 返回交互式元素、链接和窗体的DOM快照. |

### `stealth_navigate`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `url` | 字符串 | 对 | 要导航的 URL |
| `waitFor` | 字符串, enum : `load`, (中文(简体) ), `domcontentloaded`, (中文(简体) ), `networkidle0`, (中文(简体) ), `networkidle2`; 默认 : `networkidle2` | 没有 | 何时考虑完成导航 |
| `returnHtml` | 布尔, 默认值 `false` | 没有 | 在回复中包含完整的 HTML |
| `returnText` | 布尔, 默认值 `true` | 没有 | 在回复中包含已提取的文本 |
| `returnLinks` | 布尔, 默认值 `true` | 没有 | 包含页面上找到的所有链接( 文本 + ref) |
| `maxTextLength` | 数字,默认 `50000` | 没有 | 要返回的页面文本的最大字符( 默认) `50000`(中文(简体) ) |

### `stealth_scrape`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `selector` | 字符串 | 对 | 匹配元素的 CSS 选择器 |
| `limit` | 数字, 最少一个 | 没有 | 要返回的最大元素数量 |
| `attributes` | 字符串数组 | 没有 | 要提取的特定属性 |

### `stealth_click`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `selector` | 字符串 | 对 | 要单击元素的 CSS 选择器 |
| `waitForNavigation` | 布尔, 默认值 `false` | 没有 | 点击后等待页面导航 |

### `stealth_type`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `selector` | 字符串 | 对 | 输入元素的 CSS 选择器 |
| `text` | 字符串 | 对 | 文本改为类型 |
| `delay` | 数字,默认 `50` | 没有 | 按键之间延迟( ms) 。 默认为 `50` 用于类似人类的打字. |
| `clear` | 布尔, 默认值 `false` | 没有 | 输入前清除已存在的文本 |

### `stealth_screenshot`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `fullPage` | 布尔, 默认值 `false` | 没有 | 抓取完整可滚动页面 |
| `selector` | 字符串 | 没有 | 要捕获的特定元素的 CSS 选择器 |
| `format` | 字符串, enum : `png`, (中文(简体) ), `jpeg`, (中文(简体) ), `webp`; 默认 : `png` | 没有 | 图像格式 |
| `quality` | 数字,最小零,最大 `100`默认值 `80` | 没有 | Jpeg/webp的质量`0` 改为 `100`(中文(简体) ) |

### `stealth_snapshot`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `includeLinks` | 布尔, 默认值 `true` | 没有 | 在快照中包含链接 |
| `includeForms` | 布尔, 默认值 `true` | 没有 | 在快照中包含窗体 |

## 页:1

当一个工具首次使用时,浏览器会懒散地发射,并且仍然在包的工具之间共享,直到失效. 默认可执行路径为 `C:\Program Files\Google\Chrome\Application\chrome.exe` 在窗口上, `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` 关于macOS和 `/usr/bin/google-chrome` 在 Linux 上。 设定 `executablePath` 换个地方.

点击和打入会改变页面并触发其动作. 启动旗下会禁用浏览器沙盒和网络安全,并允许不安全的内容. `enableEvasions: false` 跳过为该服务应用隐形插件,但该服务仍然应用发射旗,HTTP头和页面级别覆盖.

导航失败返回零状态和错误控制台消息的部分内容;导航工具仍然返回 `success: true` 为了这个结果。 Scrape 失败返回空元素列表 。 点击并键入失败返回 `success: false`。 。 。 .

导航文本被切换为 `maxTextLength`,带有截取元数据。 最多保留服务 `100` 控制台消息 。 屏幕截图返回基数64的图像数据;所报道的维度来自取景口. 零截图 `quality` 倒计时 `80`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

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

隐形浏览器扩展名 — 傀儡- 外加被保护站点的反检测

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

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

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

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

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

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

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

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

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

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

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

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

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

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