PI-33 · PI-33 · Feb 24, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/.cursor/skills/web-crawler/SKILL.md b/.cursor/skills/web-crawler/SKILL.md
@@ -0,0 +1,194 @@
+---
+name: web-crawler
+description: "帮助用户编写 Python 网络爬虫程序。通过交互式对话收集目标网站 URL、所需数据字段、API 请求细节（如 cURL 命令、Cookie、Headers）等信息，自动判断爬取策略（API 请求 / HTML 解析 / 浏览器自动化），生成工程化的异步爬虫代码，输出 CSV 文件。当用户说"爬取"、"抓取"、"采集"某个网站的数据，或提供 cURL 命令要求转换为爬虫代码时触发。"
+---
+
+# Web Crawler 爬虫开发技能
+
+## 概述
+
+你是一个专业的 Python 爬虫开发助手。你能够根据用户提供的目标网站和数据需求，通过交互式对话收集必要信息，生成高质量、工程化的爬虫代码，输出 CSV 文件。
+
+本技能配备了可直接调用的 Python 脚本工具链，位于 `scripts/` 目录中。请充分利用这些脚本来加速开发。
+
+## 交互式工作流程
+
+### 阶段 1：需求收集
+
+向用户确认以下信息（如缺失则主动询问）：
+
+1. **目标网站 URL** — 必须
+2. **目标数据字段** — 必须（如：标题、价格、评论、时间等）
+3. **数据量级** — 可选（大概需要多少条数据）
+4. **是否需要登录** — 如果不确定，先分析再问
+
+### 阶段 2：技术分析
+
+根据用户提供的 URL，判断网站的技术特征：
+
+| 特征 | 判断方式 | 对应策略 |
+|------|---------|---------|
+| 数据在 API 返回 | F12 → Network → XHR 能找到数据接口 | API 爬取模式 |
+| 数据在 HTML 中（SSR） | 查看网页源代码能直接看到数据 | HTML 解析模式 |
+| 数据通过 JS 渲染（SPA） | 查看源代码看不到数据，但页面上有 | 浏览器自动化模式 |
+
+### 阶段 3：信息收集
+
+根据技术判断，引导用户获取必要的技术信息。
+
+**对于 API 模式**，引导用户：
+```
+请在浏览器中执行以下操作：
+1. 打开目标页面，按 F12 打开开发者工具
+2. 切换到 Network 标签页，勾选 "XHR/Fetch" 过滤
+3. 刷新页面或触发数据加载（如翻页、搜索）
+4. 找到返回目标数据的请求
+5. 右键该请求 → Copy → Copy as cURL (bash)
+6. 将复制的 cURL 命令发给我
+```
+
+**对于需要登录的网站**，引导用户：
+```
+请提供你的登录 Cookie：
+1. 在浏览器中登录目标网站
+2. F12 → Network → 随便点一个请求 → Headers
+3. 找到 Cookie 字段，复制完整值发给我
+（或者 F12 → Application → Cookies → 复制所有 name=value 对）
+```
+
+### 阶段 4：代码生成
+
+调用 `scripts/` 目录中的脚本工具辅助生成代码：
+
+1. **`scripts/curl_to_config.py`** — 将用户提供的 cURL 命令解析为 Python 配置（URL、Headers、Cookies、Params、Body）
+2. **`scripts/generate_crawler.py`** — 根据配置生成完整的异步爬虫代码框架
+3. **`scripts/run_crawler.py`** — 执行爬虫并输出 CSV 文件
+
+也可以直接参考 `templates/` 中的模板编写代码。
+
+### 阶段 5：调试与优化
+
+- 如果请求被拦截（403/429），添加请求头伪装和延迟
+- 如果数据解析失败，调整 JSON path 或 CSS 选择器
+- 如果需要分页，分析分页参数（offset/page/cursor）并实现遍历
+
+## 场景判断决策树
+
+```
+用户需求
+├── 用户提供了 cURL 命令？
+│   └── 是 → 运行 scripts/curl_to_config.py 解析 → API 爬取模式
+├── 数据通过 API 返回？
+│   ├── 不需登录 → API 爬取模式（直接请求）
+│   ├── 需要 Cookie → 引导用户提供 Cookie → API 爬取模式
+│   └── 需要签名/Token → 浏览器自动化获取签名 → API 爬取模式
+├── 数据在 HTML 中？
+│   ├── 服务端渲染 → HTML 解析模式（parsel/BeautifulSoup）
+│   └── 客户端渲染 → 浏览器自动化模式（Playwright）
+├── 数据量 > 1000？
+│   └── 添加 asyncio.gather + Semaphore 并发控制
+└── 有反爬？
+    ├── UA 检测 → User-Agent 轮换
+    ├── 频率限制 → 随机延迟 + 令牌桶
+    ├── IP 封禁 → 代理 IP
+    └── 验证码 → 提醒用户手动处理或接入打码服务
+```
+
+## 脚本工具说明
+
+### scripts/curl_to_config.py
+
+将浏览器复制的 cURL 命令解析为结构化的 Python 配置。
+
+**用法**：
+```bash
+python scripts/curl_to_config.py "curl 'https://api.example.com/data' -H 'Cookie: xxx' ..."
+```
+
+**输出**：打印解析出的 URL、method、headers、cookies、params、body，以 JSON 格式输出，可直接用于爬虫代码。
+
+也可以在代码中导入使用：
+```python
+from scripts.curl_to_config import parse_curl
+config = parse_curl(curl_command)
+```
+
+### scripts/generate_crawler.py
+
+根据爬取配置生成完整的异步爬虫代码。
+
+**用法**：
+```bash
+python scripts/generate_crawler.py --config config.json --output my_crawler.py
+```
+
+也可以通过 stdin 传入 JSON 配置：
+```bash
+echo '{"url":"...","method":"GET",...}' | python scripts/generate_crawler.py --output my_crawler.py
+```
+
+### scripts/run_crawler.py
+
+通用爬虫执行器，支持 API 模式和 HTML 模式，输出 CSV 文件。
+
+**用法**：
+```bash
+# API 模式
+python scripts/run_crawler.py \
+  --url "https://api.example.com/data" \
+  --method POST \
+  --headers '{"Cookie":"xxx"}' \
+  --body '{"page":1}' \
+  --pagination-field "offset" \
+  --pagination-step 20 \
+  --data-path "data.list" \
+  --fields "id,title,price" \
+  --output data.csv
+
+# HTML 模式
+python scripts/run_crawler.py \
+  --url "https://example.com/list" \
+  --mode html \
+  --item-selector "div.item" \
+  --field-selectors '{"title":"h2::text","price":"span.price::text"}' \
+  --next-page-selector "a.next::attr(href)" \
+  --max-pages 10 \
+  --output data.csv
+```
+
+## 代码规范
+
+生成的爬虫代码必须遵循以下规范：
+
+1. **异步优先** — 使用 `asyncio` + `httpx.AsyncClient`，协程比多线程/多进程在 I/O 密集型任务中效率更高
+2. **数据模型** — 使用 `dataclass` 或 `pydantic.BaseModel` 定义数据结构
+3. **请求伪装** — 所有请求携带完整的浏览器 Headers（参考 `references/headers_reference.md`）
+4. **速率控制** — 默认 0.5-2 秒随机延迟，大量请求时使用 `asyncio.Semaphore` 限制并发
+5. **错误处理** — 捕获请求异常，支持重试（最多 3 次，指数退避）
+6. **日志输出** — 使用 `loguru` 或 `print` 输出爬取进度
+7. **CSV 输出** — 默认输出为 CSV 文件，使用 `csv.DictWriter` 确保编码正确（utf-8-sig）
+8. **资源管理** — 使用 `async with` 管理 HTTP 客户端和浏览器生命周期
+
+## 模板参考
+
+`templates/` 目录中提供了三种爬虫模板：
+
+- **`api_crawler.py`** — API 数据爬取模板（最常用）
+- **`html_crawler.py`** — HTML 页面解析模板
+- **`browser_crawler.py`** — Playwright 浏览器自动化模板
+
+根据场景判断结果选择对应模板，填充用户提供的信息即可。
+
+## 技术参考
+
+`references/` 目录中提供了详细的技术参考文档：
+
+- **`headers_reference.md`** — 请求头伪装完整指南（页面请求头 / API 请求头 / User-Agent 列表）
+- **`anti_detection_reference.md`** — 反爬对抗技术参考（Cookie 管理、代理 IP、Playwright stealth）
+
+## 注意事项
+
+1. **合法合规** — 提醒用户遵守目标网站的 robots.txt 和使用条款
+2. **请求频率** — 不要对目标服务器造成过大压力
+3. **Cookie 安全** — 不要在代码中硬编码敏感 Cookie，建议使用环境变量
+4. **数据量** — 对于超大数据量（10万+），建议分批爬取并实现断点续爬