# 刮板生成器使用 PageObject 模式与 Playwright 和 TypeScript 生成完整、可运行的网络抓取项目。该技能可生成特定于站点的抓取工具，具有类型化数据提取、Docker 部署和可选的代理浏览器集成，以实现自动化站点分析。 ## 何时使用此技能在以下情况下使用此技能： * 构建特定于站点的网络抓取工具以进行数据提取 * 为目标网站生成PageObject类 * 使用 Docker 支持搭建一个完整的 scraper 项目 * 使用代理浏览器分析站点并自动生成选择器 * 创建可重用的抓取组件（分页、数据表）在以下情况下请勿使用此技能： * 构建API客户端（直接使用HTTP客户端库） * 编写 QA/E2E 测试套件（使用 Playwright 测试运行程序和以测试为中心的模式） * 大规模爬行或蜘蛛抓取整个域（使用 Crawlee 或 Scrapy） * 抓取需要绕过身份验证或验证码解决的网站 ## 核心原则 ### 1\.页面对象封装目标站点上的每一页都映射到一个 PageObject 类。定位器在构造函数中定义，而抓取逻辑则存在于方法中。页面对象从不包含断言或业务逻辑——它们提取并返回数据。 ### 2\.选择器弹性优选按以下顺序选择选择器：`data-testid` > `id` > 语义 HTML（`role`、`aria-label`）> 结构化 CSS 类 > 文本内容。避免位置选择器（`nth-child`）和依赖于布局的路径。有关完整的层次结构，请参阅“references/playwright-selectors.md”。 ### 3\.组合优于继承可重用的 UI 模式（分页、数据表、搜索栏）被建模为页面对象通过属性组成的组件类。只有“BasePage”使用继承——其他一切都可以组合。 ### 4\.类型化数据提取所有抓取的数据都流经 Zod 模式进行验证。这会在提取时而不是下游捕获选择器漂移（当站点更改其标记时）。请参阅“assets/templates/data-schema.ts.md”。 ### 5\. Docker优先部署生成的项目包括使用 Microsoft 官方 Playwright 图像的 Dockerfile 和带有用于输出数据和调试屏幕截图的卷挂载的 docker-compose.yml。这可以确保跨机器的浏览器环境一致。 ## 生成模式 ### 模式 1：代理-浏览器分析使用“代理浏览器”导航目标站点、捕获可访问性树快照并自动发现选择器。当代理有权访问代理浏览器 CLI 时，这是首选模式。 **先决条件：** 如果尚未安装 `agent-browser`，请先将其添加为技能： npx 技能添加 vercel-labs/agent-browser **工作流程：** # 1.打开目标页面代理浏览器打开 https://example.com/products # 2. 捕获带有元素引用的交互式快照代理浏览器快照 -i --json > snapshot.json # 3. 捕获范围部分以进行重点分析代理浏览器快照 -i --json -s "main" > main-content.json 代理浏览器快照 -i --json -s "nav" > navigation.json # 4. 测试动态行为（分页、加载更多）代理浏览器单击@e3 代理浏览器等待--加载网络空闲代理浏览器快照 -i --json > after-click.json # 5. 完成后关闭代理浏览器关闭 **代理对快照执行的操作：** 1. 解析元素引用（`@e1`、`@e2`等）及其角色 2. 按语义目的对元素进行分组（导航、数据显示、表单、操作） 3. 将数据元素映射到字段（标题、价格、图像等） 4. 使用发现的选择器生成 PageObject 类 5. 识别分页和动态加载模式有关完整的工作流程参考，请参阅“references/agent-browser-workflow.md”。 ### 模式2：手动说明用户描述目标站点的页面结构，代理将其映射到页面对象。代理会提出结构化问题： 1. **要抓取哪些页面？** — URL 或页面类型列表 2. **要提取哪些数据？** — 每页的字段名称和预期类型 3. **数据如何分页？** — 编号页、加载更多、无限滚动或单页 4. **哪些选择器是已知的？** — 用户已知的任何 CSS 选择器、data-testid 值或 XPath 然后代理： * 将描述与“data/site-archetypes.json”中的站点原型相匹配 * 提出带有类名和职责的页面对象映射 * 用户确认方案后生成代码 ### 模式 3：完整的项目脚手架使用脚手架脚本在一次操作中生成一个完整的可运行项目： deno run --allow-read --allow-write 脚本/scaffold-scraper-project.ts \ --name“我的刮刀”\ --url“https://example.com”\ --pages“产品列表，产品详细信息”\ --字段“标题、价格、图片网址、描述” 这会生成一个包含所有源文件、配置、Docker 设置和准备运行的入口点的项目。有关完整选项，请参阅脚本参考部分。 ## 快速参考类别 |方法|详情 ---|---|--- 框架|剧作家 | `playwright` 包，而不是 `@playwright/test` 语言 |打字稿 |严格模式，ES2022 目标图案|页面对象 |每页一个类，组成组件选择器|坚韧|数据测试id > id > 角色 > CSS 类 > 文本等待策略|自动等待 |内置 Playwright，加上用于导航的“networkidle” 验证 |佐德 |每页对象的输出类型的架构输出| JSON + CSV |可通过存储实用程序进行配置码头工人 |官方图片| `mcr.microsoft.com/playwright:v1.48.0-jammy` 重试 |指数退避|默认 3 次尝试，可配置截图|出现错误 |保存到 `screenshots/` 用于调试 ## 生成过程生成抓取工具时请遵循以下顺序： ### 第 1 步：收集需求询问用户： * 目标站点 URL * 要提取的数据字段 * 预计页数/项目数 * 输出格式首选项（JSON、CSV、两者） * 是否需要Docker部署 ### 第 2 步：分析网站使用模式1（代理-浏览器）或模式2（手动描述）来理解： * 页面结构和导航流程 * 数据元素位置和选择器策略 * 分页或无限滚动模式 * 动态内容加载行为 ### 步骤 3：设计页面对象映射创建计划列表： * 每个PageObject类及其URL模式 * 需要的组件类（Pagination、DataTable等） * 每页的数据模式字段和类型 * 抓取工具在页面之间的导航流程 ### 第 4 步：提出计划在生成代码之前向用户显示页面对象映射。包括类名、字段名和执行流程。等待确认。 ### 步骤 5：生成代码使用“assets/templates/”中的模板作为基础： * `base-page.ts.md` — BasePage 抽象类 * `page-object.ts.md` — 站点特定的页面对象 * `component.ts.md` — 可重用组件 * `scraper-runner.ts.md` — Orchestrator * `data-schema.ts.md` — Zod 验证模式 ### 第 6 步：交付提供完整的项目： * 所有源文件 *来自`assets/configs/`的配置文件 * 解释如何运行它的自述文件 * Docker 设置（除非明确排除） ## 代码模式 ### 基本页提供 `navigate()`、`waitForPageLoad()`、`screenshot()` 和 `getText()` 帮助器的抽象类。所有页面对象都扩展了它。导出抽象类 BasePage { 构造函数（受保护的只读页面：页面）{} 异步导航(url: string): Promise { /* ... */ } 异步屏幕截图（名称：字符串）： Promise { /* ... */ } } 请参阅：`assets/templates/base-page.ts.md` ### 页面对象特定于站点的类，其中定位器作为只读属性、返回类型化数据的抓取方法以及多页面流的导航方法。导出类 ProductListingPage 扩展 BasePage { 只读产品卡：定位器；只读 nextButton：定位器；异步 scrapeProducts(): Promise { /* ... */ } 异步 goToNextPage(): Promise { /* ... */ } } 请参阅：`assets/templates/page-object.ts.md` ### 组件可重用的 UI 模式（分页、DataTable），接收父定位器范围并提供提取方法。导出类分页{ 构造函数（私有页面：页面，私有范围：定位器）{} async hasNextPage(): Promise { /* ... */ } 异步 goToNext(): Promise { /* ... */ } } 请参阅：`assets/templates/component.ts.md` ### 刮板跑者 Orchestrator 用于启动浏览器、创建页面对象、迭代页面、收集数据、使用架构进行验证以及写入输出。导出类 SiteScraper { 异步运行(): Promise { const 浏览器 = 等待 chromium.launch(); const page = 等待 browser.newPage(); // 导航、抓取、验证、写入 } } 请参阅：`assets/templates/scraper-runner.ts.md` ### 数据架构 Zod 模式可验证抓取的记录，在提取时捕获选择器漂移和格式错误的数据。导出 const ProductSchema = z.object({ 标题: z.string().min(1), 价格：z.number().positive(), }); 请参阅：`assets/templates/data-schema.ts.md` ## 反模式反模式|问题 |解决方案 ---|---|--- 整体式刮刀|所有抓取逻辑都在一个文件中 |每页拆分为 PageObject 类睡眠服务员|使用“setTimeout”/固定延迟 |使用 Playwright 自动等待和“networkidle” 未经验证的管道 |输出没有模式验证 |为每种数据类型添加 Zod 架构选择者彩票 |脆弱的位置选择器|使用弹性选择器层次结构无声的失败|吞下错误而不记录 |记录失败并保存调试屏幕截图无节制的爬行者 |请求之间没有延迟 |添加可配置的请求延迟硬编码配置|代码中的 URL 和选择器 |使用环境变量和配置文件无重试逻辑 |每个请求单次尝试 |实施指数退避请参阅“references/anti-patterns.md”以获取包含示例和修复的扩展目录。 ## 脚本参考 ### 脚手架-scraper-project.ts 生成一个完整的爬虫项目： deno run --allow-read --allow-write 脚本/scaffold-scraper-project.ts [选项] 选项： --name <名称> 项目名称（必填） --path 目标目录（默认：./） --url 目标站点基本 URL --pages 以逗号分隔的页面名称（例如，ProductListing、ProductDetail） --fields 逗号分隔的数据字段（例如，标题、价格、评级） --no-docker 跳过 Docker 设置 --no-validation 跳过 Zod 验证设置 --json 输出为 JSON -h, --help 显示帮助示例： # 搭建一个产品刮刀 deno run --allow-read --allow-write 脚本/scaffold-scraper-project.ts \ --name“shop-scraper”--url“https://shop.example.com”\ --pages“产品列表，产品详细信息”--字段“标题，价格，image_url” # 没有 Docker 的最小爬虫 deno run --allow-read --allow-write 脚本/scaffold-scraper-project.ts \ --name“博客刮刀”--no-docker ### 生成页面对象.ts 为现有项目生成单个 PageObject 类： deno run --allow-read --allow-write 脚本/generate-page-object.ts [选项] 选项： --name 类名（必填） --url 页面 URL（用于文档注释） --fields 逗号分隔的数据字段 --selectors 字段到选择器的 JSON 映射 --with-pagination 包含分页方法 --output 输出文件路径（默认：stdout） --json 输出为 JSON -h, --help 显示帮助示例： # 使用已知选择器生成页面对象 deno run --allow-read --allow-write 脚本/generate-page-object.ts \ --name“ProductListing”--url“https://shop.example.com/products”\ --fields "标题、价格、评级" \ --selectors '{"标题":".产品标题","价格":".产品价格","评级":".星级评级"}' \ --with-pagination --output src/pages/ProductListingPage.ts # 快速生成到标准输出 deno run --allow-read script/generate-page-object.ts \ --name“搜索结果”--字段“标题、网址、片段” ## 模板和参考 ### 模板（资产/模板/）模板|目的 ---|--- `base-page.ts.md` |带有导航、屏幕截图、文本助手的抽象 BasePage `page-object.ts.md` |具有定位器和抓取方法的特定于站点的页面对象 `组件.ts.md` |可重用组件：分页、数据表 `scraper-runner.ts.md` | Orchestrator：浏览器启动、迭代、收集、输出 `data-schema.ts.md` |用于抓取数据验证的 Zod 模式 ### 配置（资产/配置/）配置 |目的 ---|--- `dockerfile.md` |使用官方 Playwright 镜像的多阶段 Dockerfile `docker-compose.yml.md` |带有数据/屏幕截图卷安装的服务 `tsconfig.json.md` |具有 ES2022 目标的严格 TypeScript `package.json.md` |剧作家、zod、tsx 依赖项 `playwright.config.ts.md` |以爬虫为中心的剧作家配置 ### 参考文献（参考文献/）参考|目的 ---|--- `pageobject-pattern.md` |适合抓取的 PageObject 模式 `playwright-selectors.md` |选择策略和弹性层次结构 `docker-setup.md` | Docker配置和部署 `代理浏览器工作流程.md` |代理浏览器分析工作流程 `反模式.md` |扩展反模式目录 ### 示例（资产/示例/）示例|目的 ---|--- `电子商务-scraper.md` |完整的多页产品抓取演练 `多页分页.md` |分页处理策略 ### 数据文件（数据/）文件 |目的 ---|--- `选择器模式.json` |按 UI 元素类型组织的通用选择器 `site-archetypes.json` |具有典型页面和字段的网站结构原型 ## 交互示例 **用户：**“我需要一个在线书店的抓取工具。我想从目录页面获取书名、作者、价格和评级。” **代理工作流程：** 1. 检查 `site-archetypes.json` — 匹配 `ecommerce` 原型 2.提出页面对象映射： * `BookListingPage` — 带分页的目录 * `BookDetailPage` — 单独的书页（如果需要详细信息抓取） * `Pagination` 组件 — 共享分页处理程序 3. 通过实地测绘展示计划： * `title` → `[itemprop="name"]` 或 `.book-title` * `author` → `[itemprop="author"]` 或 `.book-author` * `price` → `[itemprop="price"]` 或 `.price` * `评级`→`.星级评级`或`[数据评级]` 4.确认后，使用脚手架脚本生成或者手动代码生成 5. 交付带有 Docker 设置和“Book”类型的 Zod 模式的项目 ## 整合该技能连接到： * **typescript-best-practices** — 生成代码中使用的 TypeScript 编码模式 * **devcontainer** — 生成项目的开发容器设置 * **代理浏览器** — 站点分析和选择器发现（外部工具） ## 你不应该做什么该技能不会： * 绕过身份验证或登录墙 * 解决验证码或机器人检测问题 * 生成纯 JavaScript 输出（始终为 TypeScript） * 生成抓取整个域的爬虫 * 创建违反robots.txt的抓取工具 * 处理速率受限的 API（使用 HTTP 客户端进行 API 工作） * 生成测试套件（使用 Playwright 测试模式进行 QA）

刮板生成器

包含技能