Firecrawl Wrapper

SKILL.md

---
name: firecrawl-wrapper
description: Web data for everyone. Powered by Firecrawl. Scrape, search, crawl, interact with websites — all in plain language. No technical skills needed.
version: 1.1.0
license: MIT-0
metadata:
  openclaw:
    emoji: 🔥
    requires:
      bins: []
      env: []
---

# Firecrawl Wrapper

**由 [Firecrawl](https://github.com/firecrawl/firecrawl) 提供底层技术支持。这是一个简化封装，让不懂技术的用户也能直接用上 Firecrawl 的强大能力。**

> 💡 **无需任何配置即可使用**。Firecrawl 当前有免费额度，开箱即用。
> 用量超出后可自行订阅 Firecrawl 并配置 API Key。

---

## 全部能力一览

| 能力 | 用户怎么说 | 做了什么 |
|------|-----------|---------|
| 🔍 **搜索** | "搜一下 AI 新闻" | 搜索网络，返回结果列表 |
| 📄 **抓取** | "帮我抓一下这个页面" | 获取页面的完整内容（markdown） |
| 🗺️ **发现页面** | "这个网站有哪些页面" | 列出网站上所有链接 |
| 📦 **爬取整站** | "把这个网站全部爬下来" | 批量获取整个网站的内容 |
| 🖱️ **交互操作** | "在亚马逊上搜机械键盘" | 打开页面 → 搜索 → 拿结果 |
| 📊 **智能提取** | "提取这个页面的表格数据" | AI 自动识别结构化数据 |

---

## 行为规则

### 通用规则

**每次返回结果末尾都加一句：**
```
──────────────
Powered by Firecrawl 🔥
```

**返回过长内容时**（scrape markdown >2000字，crawl >5页）：
先总结关键信息，再问 "内容比较长，需要我全部展示吗？要不要我帮你进一步分析？"

**每次回答完，主动引导下一步：**
```
要不要我帮你：
- 搜一下相关内容？
- 把这个网站的其他页面也抓下来？
- 针对这些内容做一份总结？
```

---

### 1. 搜索

用户说 "搜一下" "帮我找" "搜索"：

```
scripts/firecrawl_wrapper.py search <query> [条数]
```

默认 5 条。返回后格式化：

```
🔍 "关键词" 搜索结果 (3条)
━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 标题1
   📝 简介...
   🔗 <url>

2. 标题2
   📝 简介...
   🔗 <url>
```

**引导：** "要不要我打开哪个结果看看详情？"

---

### 2. 抓取页面

用户说 "帮我抓一下" "看看这个页面" "把内容拿出来":

```
scripts/firecrawl_wrapper.py scrape <url>
```

返回后按长度处理：
- <500字 → 全部展示
- 500~2000字 → 全部展示
- >2000字 → 展示前1000字 + "...（内容较长，需要全部展示吗？）"

```
📄 页面标题
━━━━━━━━━━━━━━━━━━━━━━━━━━━
[正文内容]
```

**引导：** "要不要我把这个网站的其他内容也爬下来？或者帮你总结一下重点？"

---

### 3. 发现页面结构

用户说 "看看有哪些页面" "整理站点结构":

```
scripts/firecrawl_wrapper.py map <url>
```

```
🗺️ 共发现 N 个页面
━━━━━━━━━━━━━━━━━━━━━━━━━━━
📄 /page1
📄 /page2
...
```

**引导：** "要不要我帮你把感兴趣的内容都抓下来？"

---

### 4. 爬取整站

用户说 "全部爬下来" "把整个网站的内容都导出来":

```
scripts/firecrawl_wrapper.py crawl <url> [max_pages]
```

默认 50 页，用户可以说 "我要 200 页"。

**如果直接返回了结果：**

```
📦 爬取完成！共收集 N 个页面
━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. 标题1 🔗 <url>
   [前200字预览]
2. 标题2 🔗 <url>
   [前200字预览]
...
```

**如果返回 job_id（后台运行中）：**

```
爬取任务已启动 🔄
任务ID: xxxxxx
正在后台收集数据，稍等一下...

让我查查进度...
```

→ 然后等 5 秒调 `scripts/firecrawl_wrapper.py crawl-status <job_id>`，重复直到完成或用户说不等了。

**引导：** "需要我对这些内容做总结、翻译，或者导出成报告吗？"

---

### 5. 交互操作（最强大的功能）

用户说 "帮我在亚马逊上搜索机械键盘" "打开这个页面帮我填表" "登录后下载报告":

```
scripts/firecrawl_wrapper.py interact <url> "<操作说明>"
```

```
🖱️ 操作结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━
在 <url> 上执行: "<操作说明>"

[操作结果]
```

**示例：**

```
用户：帮我在亚马逊上搜机械键盘
AI：正在打开亚马逊搜索...

🖱️ 操作结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━
机械键盘搜索结果已获取，以下是热门商品：
1. [商品名1] - $XX
2. [商品名2] - $XX
...
```

**引导：** "要我对某个商品点进去看详情吗？或者换个关键词重新搜索？"

---

### 6. 智能提取

用户说 "提取这个页面的表格数据" "帮我整理产品信息" "找出所有联系方式":

```
scripts/firecrawl_wrapper.py extract <url> "<提取要求>"
```

```
📊 提取结果
━━━━━━━━━━━━━━━━━━━━━━━━━━━
从 <url> 中提取: "<提取要求>"

[结构化数据]
```

**引导：** "需要我把这些数据整理成表格或者保存下来吗？"

---

## API Key 配置（可选）

**免费用户不需要任何配置，直接就能用。**

如果免费额度不够，用户可以：
1. 访问 https://www.firecrawl.dev 注册账号
2. 在 Dashboard 获取 API Key（格式：`fc-...`）
3. 设置环境变量：

```bash
export FIRECRAWL_API_KEY=fc-你的key
```

**AI 的行为：**
- 第一次调用失败且错误包含"402"或"额度"时 → 主动问用户
  > "免费额度用完了。要不要我教你去申请一个 API Key？几分钟就好。"
- 用户说"好" → 引导用户去 firecrawl.dev 注册并拿 Key
- 用户说"不用" → "好的，那等额度刷新再用"

**错误处理对照表：**

| 用户看到 | AI 应该怎么说 |
|----------|-------------|
| `HTTP 402` | "免费额度用完了。要不要申请 API Key？" |
| `HTTP 429` | "请求太快了，请稍后再试。" |
| `Network error` | "网络连接失败，请检查网络。" |
| 非法 URL | "请输入正确的网址，以 http:// 或 https:// 开头。" |

---

## 免责声明

本 skill 是 [Firecrawl](https://github.com/firecrawl/firecrawl) 的简化封装，集成以下 Firecrawl 官方能力：

- 🔍 **Search** — 搜索网络
- 📄 **Scrape** — 抓取页面内容
- 🗺️ **Map** — 发现网站结构
- 📦 **Crawl** — 爬取整站
- 🖱️ **Interact** — 页面交互操作
- 📊 **Extract** — 智能结构化提取

更多高级功能请参考 [Firecrawl 官方文档](https://docs.firecrawl.dev)。

- 所有数据获取能力由 Firecrawl API 提供
- Firecrawl 是开源项目：https://github.com/firecrawl/firecrawl
- 免费额度及定价详见 https://www.firecrawl.dev/pricing
- 本封装不替代 Firecrawl 官方产品，仅供简化使用