# @framers/agentos-ext-web-scraper 中文文档

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

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

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

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

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

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

## 中文简介

智能网络刮去后退、代理旋转和LLM提取

## 安装

```sh
npm install @framers/agentos-ext-web-scraper
```

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

## README

# 网络刮取器

这个包提供了代理页刮取,结构化取出并被命名为YAML食谱工具. 用这个 `fetch`选项 `playwright-core` 浏览器倒置, 一个 regex 选择引擎和 `yaml` 食谱加载.

## 安装

```bash
npm install @framers/agentos-ext-web-scraper
```

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

## 使用量

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

const agentos = await AgentOS.create({
  extensionManifest: {
    packs: [
      {
        package: '@framers/agentos-ext-web-scraper',
        options: {
          proxyUrl: process.env.WEB_SCRAPER_PROXY_URL,
          proxyList: process.env.WEB_SCRAPER_PROXY_LIST,
        },
      },
    ],
  },
});
```

## 配置

| 选项 | 秘密编号 | 环境变量 | 需求 | 默认 |
| --- | --- | --- | --- | --- |
| `proxyUrl` | `scraper.proxyUrl` | `WEB_SCRAPER_PROXY_URL` | 没有 | 未设置 |
| `proxyList` | `scraper.proxyList` | `WEB_SCRAPER_PROXY_LIST` | 没有 | 未设置 |
| `minDelayMs` | 无 | 无 | 没有 | `500` 分钟 |
| `maxDelayMs` | 无 | 无 | 没有 | `2000` 分钟 |
| `priority` | 无 | 无 | 没有 | `50`; falsy 值也使用此默认值 |
| A. 背景情况 `logger` | 无 | 无 | 没有 | 未设置 |

代理设置从真伪选项解析, 然后 `context.getSecret`然后是环境. `proxyList` 接受逗号分隔字符串或字符串数组,并优先于 `proxyUrl`。服务通过列表旋转;按请求旋转 `options.proxy` 超过它. `logger.info` 接收激活和停用消息.

## 工具

| 工具 | 它会做什么 |
| --- | --- |
| `web_scrape` | 打印一个页面并返回基于选择器的数据或原始的 HTML 和通过渐进倒置清除文本. |
| `web_scrape_recipe` | 使用参数和前结果插值运行一个命名的刮取步骤序列. |

### `web_scrape`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `url` | 字符串 | 对 | 完全合格的 URL 要刮去( 必须从 http:// 或 https:// 开始) . |
| `extract` | 对象 | 没有 | 可选提取配置. 使用 `fields` 用于单一记录提取,或 `list` + 键 `listFields` 用于重复项提取. |
| `extract.fields` | 有字符串值的对象 | 没有 | 输出字段名映射到类似 CSS 的选择器 。 附录 `@attr` 以提取属性值而不是文本内容. |
| `extract.list` | 字符串 | 没有 | 列表视图中重复容器元素的选择器. |
| `extract.listFields` | 有字符串值的对象 | 没有 | 相对于每个项目的字段选择器 `list` 集装箱匹配. |
| `options` | 对象 | 没有 | 可选的按要求刮切设置 . |
| `options.tier` | 最小整数 `1`最大值 `4` | 没有 | 开始刮出分级( E)`1`: 获取, `2`剧作家, `3`隐形, `4`: LLM倒计时. |
| `options.maxTier` | 最小整数 `1`最大值 `4` | 没有 | 服务升级至( 默认) 最高一级 `4`) (中文(简体) ). |
| `options.proxy` | 字符串 | 没有 | 此请求的 HTTP/ SOCKS5 代理 URL . |
| `options.headers` | 有字符串值的对象 | 没有 | 包含额外的 HTTP 信头 . |
| `options.waitFor` | 字符串 | 没有 | CSS选择器在取出前等待(二级及以上仅限). |
| `options.timeout` | 最小整数 `1000` | 没有 | 按毫秒计的请求超时( 默认) `30000`) (中文(简体) ). |
| `options.javascript` | 布尔 | 没有 | 如果页面需要 JS 渲染, 设置为真( 滑至二级) . |

### `web_scrape_recipe`

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `recipe` | 字符串 | 对 | 执行的食谱名称(例如, `generic-article`, (中文(简体) ), `letterboxd-movie`) (中文(简体) ). |
| `params` | 有字符串值的对象 | 对 | 食谱的运行时参数值 。 密钥必须匹配在食谱定义中声明的参数名. |

## 页:1

两个工具都声明 `capability:web_scrape`。服务尝试 plain 获取, 无头的 Playwright, 隐形 Playwright, 然后是文本缩放 . `javascript: true` 除非 `maxTier` 盖取下. 缓存成功级可提升起步级. 获取请求和浏览器导航或选择器等待默认 `30000` 每次操作的毫秒,而不是总的最后期限.

浏览器后退动态导入 `playwright-core` 发射铬 如果导入或发射失败,服务会继续到下一个允许的级别. `playwright-core` 未在软件包的依赖性中列出。 代理被传递到 Playwright 启动选项; 获取路径不应用 。 每个浏览器在之后尝试关闭其浏览器.

文本倒置拒绝内容短于 `200` 字符和已识别的 Cloudflare 挑战页。 与 `extract`,它返回文本和 `_llmExtractionRequired: true`; 调用运行时间进行 LLM 提取 。 浏览器路径也拒绝公认的挑战页面. Plain fatch 接受成功的 HTTP 响应而不进行此挑战检查 。 所有允许的级别返回失败 `success: false` 和一个错误消息.

提取支持 `tag`, (中文(简体) ), `.class`, (中文(简体) ), `#id`, (中文(简体) ), `tag.class` (单位:千美元) `@attr` 后缀。 它使用 regex 匹配而不是一个完整的 CSS 解析器. 未支持或未匹配的字段选择器返回空字符串 。 空取结果不会引发回升.

速率限制使用随机延迟 `minDelayMs` 财务报告和审定财务报表 `maxDelayMs` 重复请求一个域。 每个域成功分级缓存 `30` 分钟,最多 `500` 条目.

从软件包中装入 YAML 配方 `recipes/` 目录,然后 `~/.wunderland/scraper-recipes/`; 用户配方覆盖匹配名称。 捆绑的食谱名称是 `generic-article` 财务报告和审定财务报表 `letterboxd-movie`。引擎查找已装入的名称,而不装入所提供路径 `recipe`。缺少的食谱返回一个错误。 无效的食谱文件生成控制台警告并跳过 .

管道步骤依次运行并插入 `{{paramName}}`, (中文(简体) ), `{{steps.stepName.data.field}}` 财务报告和审定财务报表 `{{steps.stepName.items[N].field}}` 在 URL 和选择器中。 参数前缀 `=` 在配方中存在默认值; 缺失的值会变成空字符串。 内插不 URL 编码值 。 步骤失败 停止执行并返回部分数据 。 一个步骤 `options.maxItems` 上限列表结果 。 被捆绑的Letterboxd配方使用由regex提取引擎不执行的后裔选择器.

## 许可证

阿帕奇 - 2.0

## 常见问题

### @framers/agentos-ext-web-scraper 是什么？

智能网络刮去后退、代理旋转和LLM提取

### 如何安装 @framers/agentos-ext-web-scraper？

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

### @framers/agentos-ext-web-scraper 支持 TypeScript 吗？

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

### @framers/agentos-ext-web-scraper 支持 ESM 还是 CommonJS？

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

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

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

### @framers/agentos-ext-web-scraper 可以商用吗？

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

### @framers/agentos-ext-web-scraper 的下载量有多少？

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

### @framers/agentos-ext-web-scraper 还在维护吗？

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