crawler

爬虫技能

Playwriter 探索 -> CDP 证据采集 -> 文档编写 -> 代码生成

<output_language>

默认将所有面向用户的交付内容、保存的产物、报告、计划、生成的文档、摘要、交接说明、提交/消息草稿和验证说明设为韩语，即使此规范技能文件以英语编写。

保留源代码标识符、CLI 命令、文件路径、架构键、JSON/YAML 字段名、API 名称、软件包名称、专有名词，以及必须使用指定语言或原始语言的引用源文摘录。

仅在用户明确要求、现有目标产物为保持一致性而必须使用其他语言，或机器可读契约要求使用精确的英语词元时，才使用其他语言。如果存在本地化模板或参考资料（例如 *.ko.md 或 *.ko.json），面向用户的产物优先使用它们。

</output_language>

• 在生成爬虫代码前调查网站。
• 采集 API、身份验证、选择器、网络、反机器人和方法选择方面的证据。
• 将可恢复的爬取状态保存在 .hypercore/crawler/<ACTION>.json 中，并将网站产物保存在 .hypercore/crawler/[site]/ 下。
• 仅在发现证据足以证明方法合理后，才生成爬虫代码。

<routing_rule>

对于可复用的爬取流程、网站提取方案、用于爬取的 API 逆向工程，或基于分析的爬虫代码，使用 crawler。

不要将其用于通用浏览器自动化、一次性页面点击，或不涉及爬取交付内容的文档改写。对于快速的一次性提取，除非请求扩展为可复用的爬取设计，否则应保持轻量。

</routing_rule>

<instruction_contract>

字段	契约
意图	在发现网站/API 后，构建有证据支持的爬虫方案和代码。
触发条件	可复用爬取、网页抓取、全站提取、爬取策略、API 逆向工程、身份验证/网络证据，或爬虫代码生成。
范围	负责发现、方法选择、证据产物、持久化操作状态，以及有充分依据时生成爬虫代码。
权限	用户/项目指令优先于此技能；浏览器/网络/CDP 观察结果和本地文件是证据。
证据	使用 Playwriter、Chrome DevTools/CDP、网络摘要、选择器检查、反机器人发现结果和产物文件。
工具	仅在需要时使用浏览器/CDP 工具和本地文件写入；对凭据、绕过反机器人机制、生产环境和不安全抓取设置门禁。
输出	提供韩语调查结果，以及 .hypercore/crawler/ 产物；仅在证据支持时生成爬虫代码。
验证	根据采集的证据验证方法选择、产物、选择器/API 调用和生成的代码。
停止条件	在爬取方法得到充分论证、产物写入、代码仅在安全时生成，或阻碍因素已记录后停止。

</instruction_contract>

<activation_examples>

正面示例：

• “抓取这家网店的商品卡片，先检查 API，再生成爬虫。”
• “弄清楚这个已登录的仪表板如何加载数据，并记录 Cookie 和请求头。”
• “分析这个受 Cloudflare 保护的网站，并推荐最安全的爬取方式。”

负面示例：

• “打开这个网站，点击完成注册流程。”
• “改写这份爬取操作手册，让它更易读。”

边界示例：

• “现在从这个公开页面抓取三个价格。”除非用户要求构建可复用爬虫或制定全站策略，否则优先采用轻量提取方式。

</activation_examples>

---

<trigger_conditions>

触发条件	操作
可复用的爬取、抓取或全站提取	立即运行
为爬取而进行的网站调查或 API 逆向工程	开始发现和 API 拦截
从单个页面进行一次性提取	视为边界情况；除非用户要求可复用的爬取工作，否则保持工作流轻量
绕过反机器人机制或目标网站大量使用 Cloudflare	从风险检查和 Anti-Detect 指南开始

</trigger_conditions>

---

<support_file_read_order>

按以下顺序阅读支持文件：

1. 在作出爬取或代码决策前，先阅读 pre-crawl-checklist.md。
2. 需要控制会话、与页面交互、进行视觉检查或验证选择器时，使用 playwriter-commands.md（Playwright MCP = 驱动）。
3. 需要对实时网络请求、控制台错误、性能跟踪、Lighthouse 审计或内存快照进行一手 Chrome DevTools 精确检查时，使用 chrome-devtools-mcp.md（Chrome DevTools MCP = 调试）。
4. 需要以低于完整 Playwriter 快照的 token 成本，获取结构化网络、Cookie、令牌、存储或速率限制证据时，使用 cdp-capture.md。
5. 将 Playwriter / chrome-devtools-mcp / CDP 证据整理为 API.md、NETWORK.md 和原始证据文件时，使用 network-crawling.md。
6. DOM 提取仍是可行方案时，使用 selector-strategies.md。
7. 分页、身份验证、延迟加载或重试会影响方案时，使用 crawling-patterns.md。
8. 目标网站出现拦截、CAPTCHA、Cloudflare 或明确的反检测要求时，使用 anti-bot-checklist.md。
9. 运行需要在 .hypercore/crawler/<ACTION>.json 下保存持久状态文件时，使用 action-manifest.md。
10. 编写 .hypercore/crawler/[site]/ 产物时，使用 document-templates.md。
11. 仅在选定方法并记录发现证据后，才使用 code-templates.md。

</support_file_read_order>

---

<mandatory_reasoning>

必须进行结构化推理

• 在制定爬取方案、提取策略或代码生成决策前，始终先进行内部结构化推理。
• 在每个主要阶段（发现、方法选择和实现规划）都进行结构化推理。
• 不要求使用外部推理 MCP。如果任务过于不明确，无法在本地完成推理，则停止并报告阻碍，不要在缺乏结构化计划的情况下继续。

</mandatory_reasoning>

---

<execution_defaults>

• 在生成代码、确定选择器或假设身份验证方式之前，先进行发现。
• 使用 Playwriter 重现用户可见的流程，然后优先使用 CDP 捕获结构化网络/身份验证证据。
• 如果 CDP 或备用浏览器网络证据表明存在稳定端点且身份验证易于处理，则优先采用 API 驱动的爬虫。
• 尽量少使用大型 DOM 或无障碍快照；将其用于结构检查和选择器验证，而非作为默认捕获方式。
• 如果 CDP 连接失败，请在 ANALYSIS.md 中记录限制；仅当备用证据仍然充分时，才使用 Playwriter 拦截。
• 如果法律限制、反复出现的 403/429/503、CAPTCHA 或强烈的反机器人信号导致自动化不安全，则停止并报告阻碍。
• 在记录方法、身份验证材料和速率限制状况之前，不要承诺提供 CRAWLER.ts。

</execution_defaults>

---

| 阶段 | 任务 | 命令/方法 | |-------|------|--------| | **1. 会话** | 创建会话并打开页面 | `playwriter session new` | | **2. 探索** | 使用 Playwriter 重现页面流程 | `accessibilitySnapshot`, `screenshotWithAccessibilityLabels` | | **3. 捕获** | 通过 `chrome-devtools-mcp`（首选）或 CDP 备用方案收集网络/身份验证/性能证据 | `list_network_requests`, `list_console_messages`, `performance_start_trace`；CDP `Network.*`、`Storage.*`、`Runtime.evaluate` — 参见 [chrome-devtools-mcp.md](rules/chrome-devtools-mcp.md) 和 [cdp-capture.md](rules/cdp-capture.md) | | **4. 分析** | 判断采用 API 优先还是 DOM 优先 | [network-crawling.md](rules/network-crawling.md)、[selector-strategies.md](rules/selector-strategies.md) | | **5. 记录** | 将发现结果保存到 `.hypercore/crawler/[site]/` 下 | 写入 | | **6. 编码** | 生成爬虫实现 | [code-templates.md](rules/code-templates.md) |

---

<method_selection>

条件	方法	备注
通过 CDP 或备用浏览器网络证据发现 API，且身份验证简单	fetch / httpx	速度最快
API 需要 Cookie/令牌	fetch + Cookie	需要处理过期问题
API + Cloudflare / DataDome / JA3 指纹识别	curl_cffi (impersonate Chrome)	还原 TLS/JA3；搭配住宅代理使用
探索 / 实时网络 + 性能证据	chrome-devtools-mcp	第一方 CDP 保真度（网络、控制台、性能跟踪、Lighthouse）— 参见 chrome-devtools-mcp.md
驱动页面 / 登录 / 触发延迟加载	playwriter	“让页面执行所需操作”
强反机器人保护（Cloudflare、DataDome）	Patchright 或 rebrowser-patches	修补 Chromium / 修补 Runtime.Enable 信息泄露 — 参见 anti-bot-checklist.md
Chromium 专属指纹识别	Camoufox	基于 Firefox 的隐身分支
没有 API（SSR）且没有反机器人保护	Playwright DOM	直接解析

</method_selection>

---

<output_structure>

ACTION.json 保留意图、当前状态、捕获模式、阻碍因素、输出指针和下一步操作。.hypercore/crawler/[site-name]/ 保留该站点的详细证据、分析和生成的代码。

最低产物要求：

• 对于可复用、受阻或可恢复的爬取工作，必须提供 .hypercore/crawler/<ACTION>.json。
• 对于可复用的爬取工作，必须始终提供 ANALYSIS.md。
• 使用 DOM 提取或将其保留为备用路径时，必须提供 SELECTORS.md。
• 尝试发现 API 时，必须提供 API.md；记录已发现的端点，或说明没有可用的 API。
• Cookie、令牌、标头、速率限制或机器人检测信号会影响方法时，必须提供 NETWORK.md。
• 如果可进行 CDP 捕获，建议提供 raw/network-summary.json、raw/auth-signals.json 和 raw/endpoint-candidates.json，并以此支撑易读文档，而不是取代它们。
• 只有在写入探索证据并说明所选方法的合理性后，才需要提供 CRAWLER.ts。

入门交互命令见 playwriter-commands.md。CDP 证据捕获见 cdp-capture.md。持久化操作状态规则见 action-manifest.md。核心内容应聚焦于方法选择、输出门槛和停止条件。

模板：document-templates.md

</output_structure>

---

<blocked_outcomes>

对于受阻或不安全的运行：

• 编写 ANALYSIS.md，记录阻碍因素、触发停止的证据以及最安全的下一步
• 如果认证信号、拦截响应或反机器人发现影响了决策，则编写 NETWORK.md
• 即使运行被阻止，也要写入所有可用的原始证据文件，以便审计停止原因
• 更新 ACTION.json，使 status、capture_mode、阻碍因素和输出指针与被阻止的状态相符
• 在阻碍因素解决或该方法变得适合安全自动化之前，不要创建 CRAWLER.ts

</blocked_outcomes>

---

✅ Playwriter session created
✅ `ACTION.json` created when the run is reusable, blocked, or resumable
✅ Structure analyzed with limited Playwriter snapshots
✅ CDP capture attempted for network/auth evidence
✅ raw evidence files recorded when CDP capture is available, or the fallback limitation documented when it is not
✅ Selector extraction validated
✅ Findings documented under .hypercore/crawler/
✅ Crawler code generated
✅ Structured reasoning notes recorded for major phases
✅ legal, rate-limit, and bot-detection blockers documented before scaling
✅ blocked runs reported explicitly when crawler code is unsafe or premature
✅ `ACTION.json` status and `site_dir` match the actual run outputs
✅ completed runs leave `ACTION.json.next_step` empty or terminal and point outputs at final files

---

类别	禁止事项
分析	未分析结构就猜测选择器
方法	未检查 API 就仅使用 DOM 流程
文档	跳过分析结果的记录
网络	忽略速率限制

---

# User: /crawler crawl products from https://shop.example.com

# 1. Create durable action context
# .hypercore/crawler/extract-products.json

# 2. Session
playwriter session new  # => 1
playwriter -s 1 -e "state.page = await context.newPage(); await state.page.goto('https://shop.example.com/products')"

# 3. Structure analysis
playwriter -s 1 -e "console.log(await accessibilitySnapshot({ page: state.page }))"
# => list "Products" [ref=e5]: listitem [ref=e6]: link "Product A" [ref=e7]

# 4. CDP capture
playwriter -s 1 -e $'
const client = await state.page.context().newCDPSession(state.page);
await client.send("Network.enable");
state.cdpHits = [];
client.on("Network.responseReceived", (event) => {
  if (event.response.url.includes("/api/")) state.cdpHits.push(event.response.url);
});
'
playwriter -s 1 -e "await state.page.evaluate(() => window.scrollTo(0, 9999))"
playwriter -s 1 -e "console.log(state.cdpHits)"
# => ["/api/products?page=2"]

# 5. Update extract-products.json -> status=running, capture_mode=cdp
# 6. Documentation -> .hypercore/crawler/shop-example-com/ + raw/network-summary.json
# 7. Generate API-based crawler