ai-web/docs/crawler-rule-guide.md

# 采集规则使用文档（含 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`）