爬取技能（Crawl Skill）

爬取网站以从多个页面中提取内容。适用于文档站点、知识库及全站范围的内容采集。

前置条件

需配置 Tavily API Key —— 请前往 https://tavily.com 获取您的密钥

将其添加至 ~/.claude/settings.json 文件中：

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

快速开始

使用脚本

./scripts/crawl.sh '' [output_dir]

示例：

# 基础爬取
./scripts/crawl.sh '{"url": "https://docs.example.com"}'

# 深度爬取并设置限制
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2, "limit": 50}'

# 保存为文件
./scripts/crawl.sh '{"url": "https://docs.example.com", "max_depth": 2}' ./docs

# 聚焦式爬取（含路径过滤）
./scripts/crawl.sh '{"url": "https://example.com", "max_depth": 2, "select_paths": ["/docs/.*", "/api/.*"], "exclude_paths": ["/blog/.*"]}'

# 带语义指令的爬取（适用于 agentic 场景）
./scripts/crawl.sh '{"url": "https://docs.example.com", "instructions": "Find API documentation", "chunks_per_source": 3}'

当提供 output_dir 参数时，每个被爬取的页面将单独保存为一个 Markdown 文件。

基础爬取

curl --request POST 
  --url https://api.tavily.com/crawl 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 1,
    "limit": 20
  }'

带指令的聚焦式爬取

curl --request POST 
  --url https://api.tavily.com/crawl 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and code examples",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

API 参考

端点

POST https://api.tavily.com/crawl

请求头

请求体

响应格式

{
  "base_url": "https://docs.example.com",
  "results": [
    {
      "url": "https://docs.example.com/page",
      "raw_content": "# Page TitlennContent..."
    }
  ],
  "response_time": 12.5
}

爬取深度与性能关系

建议从 max_depth=1 开始，仅在必要时逐步提升深度。

面向上下文的爬取 vs 面向数据采集的爬取

面向 agentic 场景（将结果注入 LLM 上下文）：务必同时使用 instructions 和 chunks_per_source。该模式仅返回相关文本块而非整页内容，可避免上下文窗口溢出。

面向数据采集（保存至本地文件）：省略 chunks_per_source，以获取完整页面内容。

示例

面向上下文：Agentic 研究（推荐）

适用于将爬取结果作为上下文输入给 LLM 的场景：

curl --request POST 
  --url https://api.tavily.com/crawl 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find API documentation and authentication guides",
    "chunks_per_source": 3
  }'

每页仅返回最相关的文本块（每块最多 500 字符），适配上下文长度限制，避免信息过载。

面向上下文：定向技术文档爬取

curl --request POST 
  --url https://api.tavily.com/crawl 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://example.com",
    "max_depth": 2,
    "instructions": "Find all documentation about authentication and security",
    "chunks_per_source": 3,
    "select_paths": ["/docs/.*", "/api/.*"]
  }'

面向数据采集：完整页面归档

适用于将内容保存为文件供后续处理的场景：

curl --request POST 
  --url https://api.tavily.com/crawl 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://example.com/blog",
    "max_depth": 2,
    "max_breadth": 50,
    "select_paths": ["/blog/.*"],
    "exclude_paths": ["/blog/tag/.*", "/blog/category/.*"]
  }'

返回完整页面内容 —— 可配合脚本的 output_dir 参数保存为 Markdown 文件。

Map API（URL 发现）

若仅需获取 URL 列表而无需页面内容，请使用 map 而非 crawl：

curl --request POST 
  --url https://api.tavily.com/map 
  --header "Authorization: Bearer $TAVILY_API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{
    "url": "https://docs.example.com",
    "max_depth": 2,
    "instructions": "Find all API docs and guides"
  }'

仅返回 URL 列表（比 crawl 更快）：

{
  "base_url": "https://docs.example.com",
  "results": [
    "https://docs.example.com/api/auth",
    "https://docs.example.com/guides/quickstart"
  ]
}

使用提示

• agentic 工作流中务必使用 chunks_per_source —— 可防止将结果喂给 LLM 时引发上下文爆炸
• 仅在数据采集场景下省略 chunks_per_source —— 即明确需要保存完整页面内容至文件时
• 初始设置宜保守（例如 max_depth=1、limit=20），再根据需要逐步扩大规模
• 善用路径正则模式 聚焦于目标内容区域
• 优先使用 Map API 探查站点结构，再决定是否执行完整爬取
• 始终设置 limit，防止失控爬取