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 迁移数据库

php artisan migrate --force

确保存在以下表：

• crawl_rules
• crawl_runs
• crawl_run_items
• crawl_alerts

2.2 启动队列与调度

采集任务通过队列执行，建议至少一个 worker：

php artisan queue:work

系统 cron 每分钟执行一次调度器：

* * * * * cd /path/to/ai-web && php artisan schedule:run >> /dev/null 2>&1

2.3 AI 配置（用于 AI 抽取/AI 规则生成）

在 .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：

https://your-demo-site.com/ai-tools

4.2 选择抽取模式

可按场景选：

• 页面结构稳定：xpath
• 页面结构变化大：ai
• 追求稳定 + 覆盖：hybrid

4.3 配置 Extractor JSON（XPath 模式/Hybrid 建议）

可直接用：

{
  "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

{
  "name": "title",
  "summary": "desc",
  "official_url": "website"
}

Dedupe JSON 当前可先留空对象：docs/examples/ai-tools-dedupe.json

{}

5. 如何执行

5.1 后台手动执行

在规则列表点击“立即执行”。

5.2 命令行执行

执行指定规则：

php artisan crawler:run 规则ID --sync

按 cron 执行到期规则：

php artisan crawler:run

忽略 cron 执行全部启用规则：

php artisan crawler:run --all

重试某次运行：

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

未执行迁移：

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）