爬虫开发

docs/crawler-rule-guide.md

@@ -0,0 +1,219 @@
+# 采集规则使用文档（含 AI 工具 Demo）
+
+本文面向当前项目内置采集器，目标是让你从 0 到 1 跑通一条规则，并把数据入库到站点模块（如 `AI 工具`、`AI 模型`）。
+
+## 1. 功能概览
+
+当前支持：
+
+- 后台配置采集规则（入口 URL、定时、抓取参数、Extractor JSON、AI 配置）。
+- 定时执行（Laravel Scheduler）与手动触发。
+- 运行日志、失败明细、告警中心。
+- 目标模块入库：`AI 工具`、`AI 模型`。
+- 三种抽取模式：
+  - `xpath`：只用 XPath 规则。
+  - `ai`：只用 AI 抽取结构化数据。
+  - `hybrid`：XPath + AI 合并（XPath 优先）。
+- 页面预览 + 点选元素生成 XPath。
+- AI 一键生成 Extractor 规则（从页面内容推断）。
+
+## 2. 前置准备
+
+### 2.1 迁移数据库
+
+```bash
+php artisan migrate --force
+```
+
+确保存在以下表：
+
+- `crawl_rules`
+- `crawl_runs`
+- `crawl_run_items`
+- `crawl_alerts`
+
+### 2.2 启动队列与调度
+
+采集任务通过队列执行，建议至少一个 worker：
+
+```bash
+php artisan queue:work
+```
+
+系统 cron 每分钟执行一次调度器：
+
+```cron
+* * * * * cd /path/to/ai-web && php artisan schedule:run >> /dev/null 2>&1
+```
+
+### 2.3 AI 配置（用于 AI 抽取/AI 规则生成）
+
+在 `.env` 中配置：
+
+```env
+CRAWLER_AI_ENDPOINT=
+CRAWLER_AI_KEY=
+CRAWLER_AI_MODEL=gpt-4o-mini
+```
+
+## 3. 后台入口
+
+- 采集规则：`/admin/crawlers`
+- 运行记录：`/admin/crawl-runs`
+- 告警中心：`/admin/crawl-alerts`
+
+## 4. AI 工具 Demo（推荐先跑）
+
+### 4.1 新建规则
+
+在 `采集规则` 页面点击“新建采集规则”：
+
+- 规则名称：`AI工具-Demo`
+- 目标模块：`AI 工具`
+- 发布策略：`草稿待审核`
+- Cron：`0 */6 * * *`
+- 时区：`Asia/Shanghai`
+- 最大页面数：`30`
+- 启用规则：勾选
+- 入口 URL：
+
+```text
+https://your-demo-site.com/ai-tools
+```
+
+### 4.2 选择抽取模式
+
+可按场景选：
+
+- 页面结构稳定：`xpath`
+- 页面结构变化大：`ai`
+- 追求稳定 + 覆盖：`hybrid`
+
+### 4.3 配置 Extractor JSON（XPath 模式/Hybrid 建议）
+
+可直接用：
+
+```json
+{
+  "list_link_xpath": "//a[contains(@class,'tool-link')]/@href",
+  "fields": {
+    "name": "//h1/text()",
+    "summary": "//meta[@name='description']/@content",
+    "official_url": "//a[contains(@class,'visit-official')]/@href",
+    "logo_url": "//meta[@property='og:image']/@content",
+    "pricing_type": "//span[@data-field='pricing']/text()",
+    "platform": "//span[@data-field='platform']/text()",
+    "language": "//span[@data-field='language']/text()",
+    "description": "//article[contains(@class,'tool-content')]//text()"
+  }
+}
+```
+
+或使用示例文件：`docs/examples/ai-tools-extractor.json`
+
+### 4.4 用“页面预览 + 选元素”快速生成 XPath
+
+1. 在表单里输入 `预览 URL`。
+2. 点击“加载预览”。
+3. 在预览 iframe 点击目标元素，页面会显示当前 XPath。
+4. 填写“写入字段”（如 `name` / `summary` / `list_link_xpath`）。
+5. 点击“写入 Extractor JSON”。
+
+### 4.5 用 AI 一键生成规则
+
+1. 填写（可选）AI 提示词、模型、温度等。
+2. 点击“AI 生成抽取规则并合并到 Extractor JSON”。
+3. 检查合并后的 JSON 并微调。
+
+### 4.6 Mapping / Dedupe（可选）
+
+`Mapping JSON` 示例：`docs/examples/ai-tools-mapping.json`
+
+```json
+{
+  "name": "title",
+  "summary": "desc",
+  "official_url": "website"
+}
+```
+
+`Dedupe JSON` 当前可先留空对象：`docs/examples/ai-tools-dedupe.json`
+
+```json
+{}
+```
+
+## 5. 如何执行
+
+### 5.1 后台手动执行
+
+在规则列表点击“立即执行”。
+
+### 5.2 命令行执行
+
+执行指定规则：
+
+```bash
+php artisan crawler:run 规则ID --sync
+```
+
+按 cron 执行到期规则：
+
+```bash
+php artisan crawler:run
+```
+
+忽略 cron 执行全部启用规则：
+
+```bash
+php artisan crawler:run --all
+```
+
+重试某次运行：
+
+```bash
+php artisan crawler:retry-failed 运行ID
+```
+
+## 6. 验证结果
+
+1. 打开 `/admin/crawl-runs` 查看该次运行状态。
+2. 进入运行详情看 `list/detail/extract/upsert` 各阶段结果。
+3. 到目标模块（如 AI 工具）确认有新数据，状态应为 `draft`。
+
+## 7. 常见问题
+
+### 7.1 `Table '...crawl_rules' doesn't exist`
+
+未执行迁移：
+
+```bash
+php artisan migrate --force
+```
+
+### 7.2 保存时报 `validation.json` 或 JSON 格式错误
+
+检查以下字段是否是合法 JSON：
+
+- `Extractor JSON`
+- `Mapping JSON`
+- `Headers JSON`
+- `Cookies JSON`
+
+### 7.3 运行成功但没入库
+
+通常是缺少必填字段：
+
+- AI 工具至少需 `name`、`summary`
+- AI 模型至少需 `name`、`summary`、`modality`、`deployment_mode`
+
+去运行详情看 `extract` 阶段的 `Missing required fields`。
+
+### 7.4 预览或 AI 规则生成失败
+
+常见原因：
+
+- URL 不可访问
+- URL 命中安全限制（内网/保留地址）
+- AI 配置缺失（`CRAWLER_AI_ENDPOINT` / `CRAWLER_AI_KEY`）
+

docs/examples/ai-tools-dedupe.json

@@ -0,0 +1 @@
+{}

docs/examples/ai-tools-extractor.json

@@ -0,0 +1,13 @@
+{
+  "list_link_xpath": "//a[contains(@class,'tool-link')]/@href",
+  "fields": {
+    "name": "//h1/text()",
+    "summary": "//meta[@name='description']/@content",
+    "official_url": "//a[contains(@class,'visit-official')]/@href",
+    "logo_url": "//meta[@property='og:image']/@content",
+    "pricing_type": "//span[@data-field='pricing']/text()",
+    "platform": "//span[@data-field='platform']/text()",
+    "language": "//span[@data-field='language']/text()",
+    "description": "//article[contains(@class,'tool-content')]//text()"
+  }
+}

docs/examples/ai-tools-mapping.json

@@ -0,0 +1,5 @@
+{
+  "name": "title",
+  "summary": "desc",
+  "official_url": "website"
+}